feat(release): docs-ready flag gates stable promotions

- release docs-ready: merge origin/dev -> docs (worktree at
  ~/.lpb-stack/docs-preview), build site for local review (mike serve),
  commit DOCS_READY=<stable-version> on the docs branch + push
- release status: docs verdict line (READY/MISSING/WRONG-VERSION/STALE)
- release promote: refuses unless docs are READY for the release version
  (--force overrides); no-op releases are not gated
- CI (main pipeline): new docs-publish job after tag-repos — re-verifies
  the flag, then mike deploy <version> latest -> gh-pages
- fix(release): VERSION-only main<->dev conflict (stable strips -dev by
  design) is a clean merge now — merge-tree conflicts are inspected, the
  merge takes dev's VERSION (the strip step rewrites it right after)
- tests: test_localpibox_release.py (11 tests), CLI surface tests
- docs: lpb-devstack.md, repo-workflow skill, workflow phase comments

Author: localpibox

.github/workflows/build-and-publish.yml

@@ -18,6 +18,7 @@
 #       Phase 2: build-cli     — only if VERSION changed
 #       Phase 3: build-web     — only if VERSION changed
 #       Phase 4: tag-repos     — only if VERSION changed (after build)
+#       Phase 4.5: docs-publish — main only, stable docs version (mike)
 #       Phase 5: status        — always runs
 #   - Cron / manual dispatch always build (keep image fresh / on-demand)
 #   - Dev pipeline (push to dev):   0.0.x-lpb-dev, images :dev-*, :{v}-*, :{sha}-*
@@ -371,6 +372,78 @@ jobs:
             exit 1
           fi
 
+  # ──────────────────────────────────────────────────────
+  # Phase 3.5: Publish stable docs (main pipeline only)
+  # Docs are gated into the release BEFORE promotion:
+  #   lpb-devstack release docs-ready  (merge dev→docs, review, flag)
+  #   lpb-devstack release promote     (refuses unless docs are ready)
+  # This job re-verifies the flag (catches --force promotions), then cuts
+  # the immutable docs version and points the `latest` alias at it.
+  # Output: gh-pages branch (mike) → https://lpb-stack.github.io/devstack/<version>/
+  # ──────────────────────────────────────────────────────
+  docs-publish:
+    name: Publish docs (mike)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: [tag-repos, VERSION_CHECK]
+    if: ${{ github.ref_name == 'main' && github.event_name == 'push' && needs.VERSION_CHECK.outputs.changed == 'true' && needs.tag-repos.result == 'success' }}
+    steps:
+      - name: Checkout docs branch
+        uses: actions/checkout@v6
+        with:
+          ref: docs
+          fetch-depth: 0
+
+      - name: Verify docs flag
+        run: |
+          set -e
+          VERSION=$(git show origin/main:VERSION | tr -d '[:space:]')
+          FLAG=$(git show HEAD:DOCS_READY 2>/dev/null | tr -d '[:space:]' || true)
+          if [ "$FLAG" != "$VERSION" ]; then
+            echo "::error::docs not flagged ready for $VERSION (DOCS_READY='${FLAG:-<missing>}') — run 'lpb-devstack release docs-ready' before promoting, then re-run this job"
+            exit 1
+          fi
+          echo "docs flag OK: $FLAG"
+
+      - name: Fetch stack repos at the release tag
+        run: |
+          set -e
+          VERSION=$(git show origin/main:VERSION | tr -d '[:space:]')
+          mkdir -p ws/git
+          git clone --quiet https://github.com/lpb-stack/config.git ws/config
+          for r in lpb-memory pi-subagents lemonade-pi-plugin; do
+            git clone --quiet "https://github.com/lpb-stack/$r.git" "ws/git/$r"
+          done
+          git clone --quiet https://github.com/lpb-stack/pi.git ws/pi
+          for d in ws/config ws/git/lpb-memory ws/git/pi-subagents \
+                   ws/git/lemonade-pi-plugin ws/pi; do
+            git -C "$d" fetch --quiet --depth 1 origin tag "$VERSION"
+            git -C "$d" checkout -q "$VERSION"
+          done
+
+      - name: Install docs tooling
+        run: python3 -m pip install --quiet "mkdocs-material==9.7.7" mike
+
+      - name: Prepare docs tree + version stamp
+        env:
+          AGENT_DIR: ${{ github.workspace }}/ws/config
+          LPB_AGENT_GIT: ${{ github.workspace }}/ws/git
+          LPB_WORKSPACE_ROOT: ${{ github.workspace }}/ws
+        run: python3 scripts/generate.py --tag "$(git show origin/main:VERSION | tr -d '[:space:]')"
+
+      - name: Configure git identity for mike
+        run: |
+          git config user.name "lpb-docs"
+          git config user.email "ci@lpb-stack.dev"
+
+      - name: Publish tagged docs version
+        run: |
+          set -e
+          VERSION=$(git show origin/main:VERSION | tr -d '[:space:]')
+          mike deploy "$VERSION" latest --push --update-aliases
+          mike set-default latest --push
+          echo "Docs version: https://lpb-stack.github.io/devstack/$VERSION/"
+
   status:
     name: Build status
     needs: [build-cli, build-web]

.pi/skills/localpibox-repo-workflow/SKILL.md

@@ -110,16 +110,26 @@ commits to the repo (manual tagging).
 
 ## Stable Release Procedure (dev → main)
 
+**Docs are gated into the release** — `promote` refuses until the docs
+branch is flagged ready for the version being released (`--force`
+overrides). Doc content changes on `dev` in place as usual; the one-shot
+docs sync + review happens at release time via `docs-ready`.
+
 **`lpb-devstack release` is the tool** (there is no other local version path).
 
 ```bash
-# 1. Readiness check (all 6 repos, non-destructive, fetches first)
+# 0. Flag docs as reviewed for the release (merge dev→docs, build site,
+#    review with `cd ~/.lpb-stack/docs-preview && mike serve`, confirm →
+#    commits DOCS_READY=<stable-version> on the docs branch + pushes)
+lpb-devstack release docs-ready
+
+# 1. Readiness check (all 6 repos + docs verdict, non-destructive, fetches first)
 lpb-devstack release status
 
 # 2. Inspect the exact plan without changing anything
 lpb-devstack release promote --dry-run
 
-# 3. Promote (interactive confirmation)
+# 3. Promote (interactive confirmation; blocked unless docs are READY)
 lpb-devstack release promote
 ```
 
@@ -150,9 +160,17 @@ lpb-devstack --tag main validate
 ```
 
 Flags: `--yes` (skip confirmation), `--dry-run` (plan only), `--rebase`
-(first-release mode for unrelated histories). Re-runs are safe: promoted
+(first-release mode for unrelated histories), `--force` (promote even if
+docs are not flagged ready). Re-runs are safe: promoted
 repos fast-forward or no-op.
 
+Docs readiness verdicts (`release status`, checked by `promote`):
+- `READY` — `DOCS_READY` on the `docs` branch matches the release version
+  and doc content matches `dev`
+- `MISSING` — no flag yet → run `lpb-devstack release docs-ready`
+- `STALE` — flag for another version, or doc content changed on `dev`
+  after flagging → re-run `docs-ready`
+
 ## Shipping a Dev Image (the common case)
 
 ```bash
@@ -200,7 +218,7 @@ lpb-devstack bump [--minor|--major] [--set V] [--no-commit] [--push]
 lpb-devstack tag-repos [--branch dev|main] [--version V] [--dry-run]
 lpb-devstack workspace status | sync [--extensions] | ensure [--fix]
 lpb-devstack validate
-lpb-devstack release status | promote [--yes] [--dry-run] [--rebase]
+lpb-devstack release status | docs-ready | promote [--yes] [--dry-run] [--rebase] [--force]
 lpb-devstack validate-hooks     # full pre-commit checks (tests included)
 
 # Pipeline override (dev vs main) on any command:
@@ -282,7 +300,12 @@ Jobs:
    and **fails the run if any repo's tag fails** (a partially-tagged stack
    is a release bug — re-running the job is idempotent, 422 = already
    tagged). A missing branch aborts immediately.
-5. **status** — always runs; passes when builds were skipped (no VERSION
+5. **docs-publish** — main pipeline only, after tag-repos, only if VERSION
+   changed: re-verifies the `DOCS_READY` flag on the `docs` branch matches
+   the released VERSION (catches `--force` promotions), then
+   `mike deploy <version> latest` + `set-default latest` → `gh-pages`
+   branch. Served at `lpb-stack.github.io/devstack/<version>/`.
+6. **status** — always runs; passes when builds were skipped (no VERSION
    change), fails otherwise only on build failure
 
 Images: `ghcr.io/lpb-stack/devstack` in two flavours per tag — `…-cli`

doc/lpb-devstack.md

@@ -64,9 +64,27 @@ partially-tagged stack is a release bug.
 
 | Command | Description |
 |---|---|
-| `lpb-devstack release status` | Pre-flight check: all 6 repos, non-destructive |
+| `lpb-devstack release status` | Pre-flight check: all 6 repos + docs flag, non-destructive |
+| `lpb-devstack release docs-ready [--yes]` | Flag the docs branch as reviewed for the next stable release |
 | `lpb-devstack release promote --dry-run` | Inspect plan without making changes |
-| `lpb-devstack release promote` | Promote dev → main (interactive confirmation) |
+| `lpb-devstack release promote` | Promote dev → main (interactive confirmation, blocked until docs are ready) |
+
+**Docs are gated into the release.** The docs site (MkDocs + mike) lives on
+the `docs` branch; stable releases ship the docs version too. Before
+promoting:
+
+1. `lpb-devstack release docs-ready` — merges `origin/dev` → `docs`, builds
+   the site, and (after your local review via
+   `cd ~/.lpb-stack/docs-preview && mike serve`) commits
+   `DOCS_READY=<stable-version>` on the `docs` branch and pushes it
+2. `release status` shows the docs verdict: `READY` / `MISSING` /
+   `STALE` (stale = flag for another version, or doc content changed on dev
+   after flagging)
+3. `release promote` **refuses** unless docs are `READY` for the version
+   being released — `--force` overrides with a warning
+4. The main pipeline re-verifies the flag, then publishes the immutable
+   docs version (`mike deploy <version> latest`) to the `gh-pages` branch:
+   `https://lpb-stack.github.io/devstack/<version>/`
 
 `promote` does per repo (dev branch → stable branch: `dev` → `main` for
 devstack/config/lpb-memory, `lpb-dev` → `lpb` for pi/pi-subagents/
@@ -85,7 +103,8 @@ lemonade-pi-plugin):
   `0.0.58-lpb-dev` → `0.0.58-lpb`) and commits it
 
 Flags: `--yes` (skip confirmation), `--dry-run` (plan only), `--rebase`
-(first-release mode).
+(first-release mode), `--force` (promote even if docs are not flagged
+ready). `docs-ready` accepts `--yes` (skip the review confirmation).
 
 ### Pipeline Override
 
@@ -111,12 +130,15 @@ lpb-devstack validate
 ## Manual Tagging Flow (stable release)
 
 ```bash
-lpb-devstack release status                    # readiness check
+lpb-devstack release docs-ready                # merge dev→docs, review site, flag DOCS_READY
+lpb-devstack release status                    # readiness check (repos + docs)
 lpb-devstack release promote --dry-run         # inspect plan
-lpb-devstack release promote                   # dev → stable + push
+lpb-devstack release promote                   # dev → stable + push (blocked until docs ready)
 lpb-devstack tag-repos --branch main           # tag the 5 repos on stable branches
 lpb-devstack --tag main workspace sync-pins   # pins → stable tag
 pi update --extensions
+# CI (main pipeline) then builds images, tags repos, and publishes the
+# stable docs version (https://lpb-stack.github.io/devstack/<version>/)
 ```
 
 ## Quick Reference

scripts/docs/site/.marker

@@ -0,0 +1 @@
+built