chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing

- beads-release formula: drop the snapshot-docs step (ran the deleted scripts/snapshot-release-docs.sh on the critical needs-chain); stamp- changelog now needs update-vendorhash - update-versions.sh: remove the mangled --skip-docs/docs-snapshot logic and garbled usage text left by mid-line deletions - pre-push hook: drop the snapshot-script remediation hint - release.yml: collapse the prerelease branch; BEADS_REQUIRE_RELEASE_DOCS has no consumer since check-docs-version.sh was deleted - RELEASING.md / scripts/docs.md: describe the current pipeline (no --versioned, no website/ outputs, no check-docs-version.sh) - docs-mintlify.yml: paths filter now includes engdocs/** and the curated root markdown files the docsync guard validates - docs-render-check.sh: pin mint@4.2.687, fail closed when mint dies without producing a broken-links report, parse report lines only, drop dead extract_page_links(), fix the stale jq requirement; mint.sh pins the same version - nightly.yml: remove the deleted website measurement suite option - CODEOWNERS: init-safety ADR gate follows the file to engdocs/adr/ - beads-docs skill: align with settled decision 6 — no pointer stubs, moved pages get docs.json redirects; bd's printed paths are fixed at the source - CHANGELOG (edited line), FEDERATION-SETUP, README, examples, oracle-a, .buildflags, gh-issue-to-pr formula: retarget moved-file references; anchor the build/ gitignore pattern
2026-09-14 20:17:24 +08:00 · 2026-07-12 11:07:26 -07:00
parent 39d07f8442
commit 789044b83e
24 changed files with 106 additions and 148 deletions
@@ -504,7 +504,7 @@ grep 'vendorHash = ' default.nix
 [[steps]]
 id = "stamp-changelog"
 title = "Stamp changelog with release date"
-needs = ["snapshot-docs"]
+needs = ["update-vendorhash"]
 description = """
 Add the release date to the [Unreleased] section header.

@@ -528,28 +528,6 @@ grep -A2 '\\[Unreleased\\]' CHANGELOG.md
 ```
 """

-[[steps]]
-id = "snapshot-docs"
-title = "Snapshot versioned documentation"
-needs = ["update-vendorhash"]
-description = """
-Create or verify the Docusaurus snapshot for {{version}} so the published docs
-version dropdown, default docs route, and llms-full artifact match the release.
-
-This is a single, idempotent script so version.go and the docs snapshot cannot
-drift apart. It installs website deps if needed, creates the versioned snapshot
-(if missing), points `docusaurus.config.ts` lastVersion at it, regenerates the
-CLI reference and llms-full.txt, and verifies consistency.
-
-```bash
-./scripts/snapshot-release-docs.sh {{version}}
-```
-
-If `scripts/update-versions.sh {{version}}` was used for the version bump, the
-docs snapshot has already run as part of that step (unless --skip-docs was
-passed) and this step just re-verifies.
-"""
-
 [[steps]]
 id = "verify-versions"
 title = "Verify version consistency"
@@ -4,7 +4,7 @@
 #
 # Rationale: go-mysql-server links ICU by default under cgo. beads never
 # uses SQL REGEXP, so we always build with -tags=gms_pure_go. See
-# docs/ICU-POLICY.md for the full policy.
+# engdocs/ICU-POLICY.md for the full policy.

 # Embedded Dolt requires CGO; server mode and nocgo builds do not. Default
 # to 1 for the embedded-capable build paths that sourced this, but respect
@@ -201,8 +201,8 @@ preview with `make docs-dev` (or `./mint.sh dev`) at `localhost:3000`.
 When you **move or remove a page**: add a redirect to the `redirects` array
 in `docs/docs.json`, rewrite inbound links repo-wide (README, engdocs/,
 examples/, npm-package/, plugin resources — grep, don't guess), and check
-whether released `bd` binaries print the old path (if so, leave a pointer
-stub; see the allowlist in `test/docsync/docsync_test.go`).
+whether `bd` prints the old path (if so, fix the Go source and regenerate —
+never a pointer stub; decision 6 covers old routes with redirects).

 ## 10. Review and commit discipline

@@ -46,6 +46,8 @@ the binary still prints, the docs now lie.
  mechanically.
 - `.beads/issues.jsonl` — always described as a passive export. Never call it
  the database, the sync protocol, or a backup.
- Paths released binaries print (`docs/RECOVERY.md`, `docs/PLUGIN.md`,
-  `docs/SETUP.md`, …) — the pointer stubs at those paths stay; see the
-  allowlist in `test/docsync/docsync_test.go`.
+- Paths `bd` prints (`docs/RECOVERY.md`, `docs/SETUP.md`, …) — never
+  recreate pointer stubs at old paths; moved pages are covered by the
+  `redirects` array in `docs/docs.json` (decision 6 of
+  `engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md`). If bd prints an
+  old path, fix the Go source so it prints the new one and regenerate.
@@ -7,7 +7,7 @@ Run these before considering docs work complete. Ordered cheapest-first.
 ```bash
 # 1. Docs sync: docs.json nav <-> file consistency, link conventions
 #    (root-relative extensionless in docs/, exact paths in engdocs/ and
-#    curated root files), orphan detection with the stub allowlist.
+#    curated root files), orphan detection (only CLI_REFERENCE.md is exempt).
 go test ./test/docsync

 # 2. Generated CLI docs freshness: regenerates from the live command tree
@@ -57,9 +57,11 @@ all of:
 2. **Rewrite inbound links** — grep the whole repo, not just `docs/`:
   README.md, AGENTS.md, AGENT_INSTRUCTIONS.md, engdocs/, examples/,
   npm-package/, plugins/, integrations/, scripts, and Go comments.
-3. **Check released-binary output** — if `bd` prints the old path (grep
-   `cmd/` and `internal/templates/` for it), leave a pointer stub at the old
-   path and add it to the allowlist in `test/docsync/docsync_test.go`.
+3. **Check bd's printed output** — if `bd` prints the old path (grep `cmd/`
+   and `internal/templates/` for it), fix the Go source to print the new
+   path and regenerate the CLI docs. Do **not** create a pointer stub at the
+   old path — decision 6 (no pointer stubs; Mintlify redirects) accepts that
+   old GitHub links printed by already-released binaries 404.
 4. **Fix anchor text** — if a link's label named the old page, update the
   label too, and dedupe links that now collapse to the same target.

@@ -27,12 +27,11 @@ if [ ! -x "$repo_root/scripts/check-versions.sh" ]; then
    exit 0
 fi

-echo "Release tag push detected — verifying version + docs consistency..."
+echo "Release tag push detected — verifying version consistency..."
 if ! (cd "$repo_root" && ./scripts/check-versions.sh); then
    echo ""
-    echo "❌ Refusing to push release tag: version/docs are inconsistent." >&2
+    echo "❌ Refusing to push release tag: versions are inconsistent." >&2
    echo "   Fix with: scripts/update-versions.sh <version>" >&2
-    echo "   (or scripts/snapshot-release-docs.sh <version> for the docs side)." >&2
    echo "   Override with --no-verify only if you know what you are doing." >&2
    exit 1
 fi
@@ -1,7 +1,7 @@
 # CODEOWNERS — review ownership
 #
 # Changes under cmd/bd/init*.go interact with init-safety invariants
-# documented in docs/adr/0002-init-safety-invariants.md. Reviewers MUST
+# documented in engdocs/adr/0002-init-safety-invariants.md. Reviewers MUST
 # confirm new flags / data sources extend CheckRemoteSafety's guard
 # matrix (cmd/bd/init_safety_test.go) before approving. Silent guard
 # accretion is how we ended up with 8+ paper-over commits before ADR 0002
@@ -11,7 +11,7 @@
 cmd/bd/init.go              @gastownhall/beads-maintainers
 cmd/bd/init_*.go            @gastownhall/beads-maintainers
 cmd/bd/init_safety*.go      @gastownhall/beads-maintainers
-docs/adr/0002-init-safety-invariants.md  @gastownhall/beads-maintainers
+engdocs/adr/0002-init-safety-invariants.md  @gastownhall/beads-maintainers

 # Schema-migration critical path (bd-6dnrw.15). The 2026 Apr-Jun window
 # shipped a corrupting migration (PR 4039, DEFAULT (UUID()) PK, zero reviews,
@@ -16,16 +16,20 @@
 #
 # Exit codes:
 #   0 — no net-new page-link regressions
-#   1 — net-new page-link regressions found; details on stdout
+#   1 — net-new page-link regressions found (details on stdout), or the
+#       mint tool itself failed to produce a broken-links report
 #
-# Requires: git, npx (Node.js), jq
+# Requires: git, npx (Node.js)
 #
 set -euo pipefail

 DOCS_DIR="docs"
 DOCS_CONFIG="$DOCS_DIR/docs.json"
 BASE_REF="${1:-origin/main}"
-MINT_CMD="${MINT_CMD:-npx --yes mint@latest}"
+# Pinned so a floating release can't silently change the output format this
+# script parses (keep in sync with mint.sh).
+MINT_VERSION="${MINT_VERSION:-4.2.687}"
+MINT_CMD="${MINT_CMD:-npx --yes mint@$MINT_VERSION}"

 WORK_TMP="$(mktemp -d)"
 trap 'rm -rf "$WORK_TMP"' EXIT
@@ -36,28 +40,29 @@ if [[ ! -f "$DOCS_CONFIG" ]]; then
    exit 0
 fi

-# --- extract_page_links <mint-output-file> -----------------------------------
-# Parse `mint broken-links` output lines. Each broken link looks like:
+# Static-asset refs are excluded: mint over-reports in-tree images the
+# published build serves fine.
+ASSET_EXTS='\.png$|\.svg$|\.jpg$|\.jpeg$|\.gif$|\.ico$|\.webp$|\.woff2?$|\.ttf$|\.eot$'
+
+# has_report <mint-output-file> — did mint produce a broken-links report at
+# all (as opposed to dying on a registry outage / crash)?
+has_report() {
+    grep -qE '✗|broken' "$1" 2>/dev/null
+}
+
+# Parse `mint broken-links` report lines. Each broken link looks like:
 #   [broken-links]  tutorials/01-beads.md  ->  /tutorials/01-beads.md
 # or
 #   ✗  /tutorials/01-beads.md
-# We capture only page links (no static-asset extensions).
-ASSET_EXTS='\.png$|\.svg$|\.jpg$|\.jpeg$|\.gif$|\.ico$|\.webp$|\.woff2?$|\.ttf$|\.eot$'
-
-extract_page_links() {
-    local file="$1"
-    grep -oE '[^ ]+\.[a-z]+$|/[^ ]+' "$file" 2>/dev/null \
-        | grep -vE "$ASSET_EXTS" \
-        | sort -u || true
-}
-
-# Alternative simpler extraction: just lines with the broken-links marker.
+# Capture path-shaped tokens on report lines only — root-relative (/foo) or
+# relative with a slash — excluding URLs and static assets. The same parser
+# runs on both HEAD and BASE output, so residual noise cancels out in the
+# net-new comparison.
 parse_mint_broken_links() {
    local file="$1"
-    # mint outputs lines like: "  ✗  /path/to/page" or "  ✗  page-slug"
-    # or with indentation. Grab any token that looks like a link (starts with /).
-    grep -E '✗|broken|BROKEN|error|ERROR' "$file" 2>/dev/null \
-        | grep -oE '[/][^ )]+' \
+    grep -E '✗|broken' "$file" 2>/dev/null \
+        | grep -oE '[/][^ )]+|[A-Za-z0-9_.-]+/[^ )]+' \
+        | grep -vE '^https?:|^[A-Za-z0-9_.-]+\.[A-Za-z]{2,}/' \
        | grep -vE "$ASSET_EXTS" \
        | sort -u || true
 }
@@ -92,9 +97,19 @@ HEAD_LINKS="$WORK_TMP/head-links.txt"
 parse_mint_broken_links "$HEAD_OUT" | sort -u >"$HEAD_LINKS"

 if [[ ! -s "$HEAD_LINKS" ]]; then
-    # mint exited non-zero but no links we care about. Pass.
-    echo "docs-render-check: mint non-zero but no page-link regressions detected — PASS" >&2
-    exit 0
+    if has_report "$HEAD_OUT"; then
+        # mint produced a report, but every flagged link is a static asset
+        # we deliberately ignore. Pass.
+        echo "docs-render-check: mint flagged only static-asset links — PASS" >&2
+        exit 0
+    fi
+    # mint exited non-zero without producing a broken-links report at all
+    # (registry outage, crash, output-format change). Fail closed rather
+    # than let the gate silently stop enforcing.
+    echo "::error::docs-render-check: mint failed without producing a broken-links report — tool failure, not a clean run"
+    echo "mint output follows:" >&2
+    cat "$HEAD_OUT" >&2
+    exit 1
 fi

 # --- BASE check (baseline-aware) --------------------------------------------
@@ -4,9 +4,21 @@ on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    paths:
+      # The docsync guard also validates engdocs/** and the curated root
+      # markdown files (rootDocFiles in test/docsync/docsync_test.go) — keep
+      # this filter in sync with that list, or a docs-breaking PR merges
+      # green and turns main red at the full test run.
      - 'docs/**'
+      - 'engdocs/**'
      - 'test/docsync/**'
      - 'mint.sh'
+      - 'README.md'
+      - 'AGENTS.md'
+      - 'AGENT_INSTRUCTIONS.md'
+      - 'CONTRIBUTING.md'
+      - 'CLAUDE.md'
+      - 'RELEASING.md'
+      - 'PR_MAINTAINER_GUIDELINES.md'
      - '.github/scripts/docs-render-check.sh'
      - '.github/workflows/docs-mintlify.yml'

@@ -26,7 +26,6 @@ on:
          - nix
          - mcp-package
          - npm-package
-          - website
      smoke_version:
        description: "Optional previous release for cross-version-smoke"
        required: false
@@ -45,15 +45,8 @@ jobs:
          fi
          echo "OK: tag and version.go agree on $code_version"

-      - name: Check version + docs consistency
-        run: |
-          tag_version="${GITHUB_REF_NAME#v}"
-          if [[ "$tag_version" == *-* ]]; then
-            echo "Prerelease tag detected; stable docs snapshot may remain on latest stable release."
-            ./scripts/check-versions.sh
-          else
-            BEADS_REQUIRE_RELEASE_DOCS=1 ./scripts/check-versions.sh
-          fi
+      - name: Check version consistency
+        run: ./scripts/check-versions.sh

  release-package-mcp:
    name: Release Package Gate (MCP)
@@ -138,5 +138,5 @@ bd_test

 # Beads / Dolt files (added by bd init)
 .beads/proxieddb/
-build/
+/build/
 node_modules/
@@ -436,7 +436,7 @@ gate that rc.1 introduced, and ships the validated upgrade documentation.

 ### Added

- **`bd init --reinit-local` / `--discard-remote`** — named-intent flags for local re-initialization and explicit remote-history override. Replaces the overloaded `--force`. See [`bd help init-safety`](engdocs/adr/0002-init-safety-invariants.md) and [`docs/RECOVERY.md`](docs/RECOVERY.md).
+- **`bd init --reinit-local` / `--discard-remote`** — named-intent flags for local re-initialization and explicit remote-history override. Replaces the overloaded `--force`. See [`bd help init-safety`](engdocs/adr/0002-init-safety-invariants.md) and [`docs/recovery/init-safety.md`](docs/recovery/init-safety.md).
 - **`bd init-safety`** — documents the init flag surface + destroy-token format. Referenced by every init refusal message.
 - **Stable exit codes for init refusals** — `10` remote divergence, `11` local exists, `12` destroy-token missing. Grep-safe for CI.
 - **[ADR 0002 — `bd init` safety invariants](engdocs/adr/0002-init-safety-invariants.md)** — encodes the single-source identity rule, scope-bound `--force`/`--reinit-local`, the `CheckRemoteSafety` chokepoint, the error-text-no-echo rule, and the race-safety invariant.
@@ -2,5 +2,5 @@

 The canonical federation guide is [docs/multi-agent/federation.md](docs/multi-agent/federation.md).

-This root-level file remains only as a stable pointer for existing links
-(website quickstart pages, `llms-full.txt`).
+This root-level file remains only as a stable pointer for existing external
+links and bookmarks.
@@ -111,7 +111,7 @@ version: sync remote-backed databases with your current `bd`, back up with
 migration on a remote-backed database, exactly one designated clone runs
 `bd migrate --force` and `bd dolt push`; other clones install the new binary
 and run `bd bootstrap`. See the full
-[upgrade guide](https://gastownhall.github.io/beads/docs/getting-started/upgrading)
+[upgrade guide](https://gastownhall.github.io/beads/getting-started/upgrading)
 or [docs/getting-started/installation.md](docs/getting-started/installation.md#updating-bd).

 ### Security And Verification
@@ -519,11 +519,9 @@ identifier (e.g. `1.1.0-rc.1`); Python tooling normalizes this to PEP 440 form
 - **PyPI** and **npm** publish jobs are **skipped**. The `publish-pypi` and
  `publish-npm` jobs are gated with `!contains(github.ref_name, '-')`, so a tag
  containing a `-` never reaches the stable package channels.
- **The stable docs snapshot is not required.** `verify-version-consistency`
-  runs `scripts/check-versions.sh` without `BEADS_REQUIRE_RELEASE_DOCS=1` for
-  prerelease tags, and `scripts/check-docs-version.sh` treats a prerelease
-  canonical version as non-strict. The versioned docs stay on the latest stable
-  release until the base `X.Y.Z` ships.
+- **Docs are unaffected.** The docs site publishes from `main` via the
+  Mintlify GitHub integration; there is no release-time docs snapshot for
+  either prereleases or stable releases.

 ### Cut an RC

@@ -566,9 +564,9 @@ above. Tag creation is restricted to release maintainers; see
 - Install the RC from the GitHub prerelease assets and exercise the changes it
  is gating before promoting.
 - To promote to stable, bump to the base version with no suffix
-  (`./scripts/update-versions.sh 1.1.0`). The stable bump **does** require the
-  docs snapshot and **does** publish to Homebrew/PyPI/npm, so follow the
-  standard [Prepare Release](#1-prepare-release) steps from there.
+  (`./scripts/update-versions.sh 1.1.0`). The stable release **does** publish
+  to Homebrew/PyPI/npm, so follow the standard
+  [Prepare Release](#1-prepare-release) steps from there.

 ## Hotfix Releases

@@ -37,4 +37,4 @@ commands to match your project before first use.

 ## Creating Your Own

-See the [Formulas documentation](https://gastownhall.github.io/beads/docs/workflows/formulas) for the full reference.
+See the [Formulas documentation](https://gastownhall.github.io/beads/workflows/formulas) for the full reference.
@@ -472,7 +472,7 @@ ALL THREE quality gates are MANDATORY — do not skip any without explicit justi
   ```
   golangci-lint run ./...
   ```
-   (Ignore baseline warnings documented in docs/LINTING.md — focus on NEW issues)
+   (Ignore baseline warnings documented in engdocs/LINTING.md — focus on NEW issues)
 3. Build the project:
   ```
   make build
@@ -5,6 +5,9 @@ set -euo pipefail

 repo_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
 docs_dir="$repo_dir/docs"
+# Pinned so local preview and CI parse the same tool (keep in sync with
+# .github/scripts/docs-render-check.sh).
+MINT_VERSION="${MINT_VERSION:-4.2.687}"
 args=("$@")
 if [[ ${#args[@]} -eq 0 ]]; then
  args=(dev)
@@ -37,13 +40,13 @@ find_node22_bin() {
 major=$(node_major)
 if [[ "$major" =~ ^[0-9]+$ ]] && (( major < 25 )); then
  cd "$docs_dir"
-  exec npx --yes mint@latest "${args[@]}"
+  exec npx --yes "mint@$MINT_VERSION" "${args[@]}"
 fi

 if node22_bin=$(find_node22_bin); then
  export PATH="$node22_bin:$PATH"
  cd "$docs_dir"
-  exec npx --yes mint@latest "${args[@]}"
+  exec npx --yes "mint@$MINT_VERSION" "${args[@]}"
 fi

 cat >&2 <<EOF
@@ -46,11 +46,10 @@ PATCH_FILE="$(readlink -f "$PATCH_FILE")"
 COMMENT_MARKER="<!-- cli-docs-autofix -->"
 AUTOFIX_SUBJECT="docs: auto-regenerate CLI reference"

-# Files the doc generators may write - a superset of GEN_PATHSPECS in
-# scripts/check-cli-docs-drift.sh (generate-cli-docs.sh also refreshes the
-# versioned CLI snapshot). Anchored, single path segment where a wildcard
-# appears, conservative filename charset: no traversal, no nesting, no
-# metacharacters can slip through.
+# Files the doc generators may write - keep in sync with GEN_PATHSPECS in
+# scripts/check-cli-docs-drift.sh. Anchored, single path segment where a
+# wildcard appears, conservative filename charset: no traversal, no nesting,
+# no metacharacters can slip through.
 path_allowed() {
    case "$1" in *..*) return 1 ;; esac
    [[ "$1" == "docs/CLI_REFERENCE.md" ]] && return 0
@@ -10,7 +10,11 @@ Key scripts include version bumping, installation helpers that inject git inform

 ## generate-cli-docs.sh

-Generates maintained CLI reference docs from the live Cobra command tree exposed by `bd help`.
+Generates maintained CLI reference docs from the live Cobra command tree in
+two stages: `bd help --docs-root` emits vendor-neutral output (the single-file
+reference plus a generic per-command tree in uncommitted staging), then
+`tools/docsmint` post-processes the staging tree into the committed Mintlify
+pages and splices the CLI Reference pages array in `docs/docs.json`.

 ### Usage

@@ -18,9 +22,6 @@ Generates maintained CLI reference docs from the live Cobra command tree exposed
 # Regenerate checked-in CLI docs using a temporary no-cgo build
 ./scripts/generate-cli-docs.sh

-# Regenerate the live docs and one release snapshot
-./scripts/generate-cli-docs.sh --versioned 1.0.5
-
 # Regenerate/check against an existing binary
 ./scripts/generate-cli-docs.sh ./bd
 ./scripts/generate-cli-docs.sh --check ./bd
@@ -29,26 +30,11 @@ Generates maintained CLI reference docs from the live Cobra command tree exposed
 ### Outputs

 - `docs/CLI_REFERENCE.md` from the live Cobra command tree
- `website/docs/cli-reference/*.md` from the live Cobra command tree
- `website/versioned_docs/version-X.Y.Z/cli-reference/*.md` only when `--versioned X.Y.Z` is supplied by the release snapshot workflow
- `website/static/llms-full.txt` freshness is checked from the same generated website docs tree
+- `docs/cli-reference/*.md` (Mintlify pages) via `tools/docsmint`
+- the CLI Reference pages array in `docs/docs.json`

-`scripts/check-doc-flags.sh` runs the `--check` mode in CI and fails when live top-level commands are missing from live generated docs or `llms-full.txt` is stale. Historical Docusaurus CLI snapshots are release artifacts; ordinary PR checks do not rewrite them to match unreleased commands.
-
-## check-docs-version.sh
-
-Validates the released Docusaurus docs metadata:
-
- `website/versions.json` latest entry and `website/docusaurus.config.ts` `lastVersion` agree
- the matching `website/versioned_docs/version-X.Y.Z` and sidebar snapshot exist
- the versioned CLI reference label matches the latest released docs snapshot
- `website/static/llms-full.txt` is sourced from the latest released snapshot
-
-Default CI mode does not require the latest released docs snapshot to equal
-`cmd/bd/version.go`, because a version bump may land before the release is cut.
-Use `BEADS_REQUIRE_RELEASE_DOCS=1 ./scripts/check-docs-version.sh`, or run from a
-`v*` tag, for release preflight mode where the docs snapshot must match the
-current binary version.
+`scripts/check-cli-docs-drift.sh` runs the `--check` mode in CI and fails when
+the committed copies are stale relative to the live command tree.

 ## check-doc-freshness.sh

@@ -20,13 +20,9 @@ YELLOW='\033[1;33m'
 NC='\033[0m'

 usage() {
-    echo "Usage: $0 <version> [--skip-docs]"
+    echo "Usage: $0 <version>"
    echo ""
-    echo "Updates version numbers across all components (no git operations),"
-    echo "snapshot cannot drift apart for stable releases."
-    echo ""
-    echo "                <version> elsewhere before tagging a stable release, or CI"
-    echo "                will fail. Prereleases skip docs snapshots by default."
+    echo "Updates version numbers across all components (no git operations)."
    echo ""
    echo "Examples:"
    echo "  $0 0.47.1"
@@ -36,10 +32,8 @@ usage() {
 }

 NEW_VERSION=""
-SKIP_DOCS=0
 for arg in "$@"; do
    case "$arg" in
-        --skip-docs) SKIP_DOCS=1 ;;
        -h|--help) usage; exit 0 ;;
        -*) echo "Unknown option: $arg" >&2; usage; exit 1 ;;
        *)
@@ -65,10 +59,6 @@ if ! [[ $NEW_VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$ ]]
 fi

 BASE_VERSION="${NEW_VERSION%%-*}"
-IS_PRERELEASE=0
-if [ "$BASE_VERSION" != "$NEW_VERSION" ]; then
-    IS_PRERELEASE=1
-fi

 # Check we're in repo root
 if [ ! -f "cmd/bd/version.go" ]; then
@@ -144,24 +134,6 @@ update_file "cmd/bd/winres/manifest.xml" "version=\"$CURRENT_BASE.0\"" "version=
 echo ""
 echo -e "${GREEN}✓ Version constants updated to $NEW_VERSION${NC}"
 echo ""
-
-# and the published docs cannot diverge. This is the failure mode that left
-# main red after the 1.0.5 release (version bumped, docs snapshot missing).
-if [ "$SKIP_DOCS" -eq 1 ]; then
-    echo -e "${YELLOW}Skipping docs snapshot (--skip-docs).${NC}"
-    if [ "$IS_PRERELEASE" -eq 1 ]; then
-        echo "  Prerelease CI does not require a stable docs snapshot for $NEW_VERSION."
-    else
-        echo "  or CI (check-version-consistency) will fail."
-    fi
-elif [ "$IS_PRERELEASE" -eq 1 ]; then
-    echo -e "${YELLOW}Skipping docs snapshot for prerelease $NEW_VERSION.${NC}"
-    echo "  Stable docs stay on the latest stable release until $BASE_VERSION ships."
-else
-    echo "Snapshotting release docs..."
-    fi
-
-echo ""
 echo "Changed files:"
 git diff --stat 2>/dev/null || true
 echo ""
@@ -56,7 +56,7 @@ Overrides:
 - **Rust / `cargo`** — builds the conformance harness (`harness/`).
 - **A CGO toolchain (`gcc`/`cc`)** and **`go`** — `bd` embeds Dolt, which is cgo;
  both binaries build with `CGO_ENABLED=1 -tags gms_pure_go` (the `gms_pure_go`
-  tag is mandatory per `docs/ICU-POLICY.md`).
+  tag is mandatory per `engdocs/ICU-POLICY.md`).
 - **`git`** with `origin/main` fetched (the script resolves `REF_REF` locally;
  run `git fetch` first if it is stale).
 - **`jq`** — used for the golden floor assertion (the reference's `create` steps
@@ -52,7 +52,7 @@ else
  unset ORACLE_CATALOG 2>/dev/null || true
 fi

-# gms_pure_go is mandatory per docs/ICU-POLICY.md; CGO is required for embedded Dolt.
+# gms_pure_go is mandatory per engdocs/ICU-POLICY.md; CGO is required for embedded Dolt.
 BUILD_TAGS="gms_pure_go"

 # unique scratch dir per run — cp over an exec-mapped binary fails silently and