Merge remote-tracking branch 'origin/dev'

Author: localpibox

.env.example

@@ -79,6 +79,9 @@ LPB_AGENT_BROWSER_IDLE_TIMEOUT_MS=300000
 #   0.20   → 262K context → 52.4K max tokens
 # LPB_MAX_TOKENS_CONTEXT_RATIO=0.06
 
+# SSH port for `lpb --ssh` (default: 2222)
+# LPB_SSH_PORT=2222
+
 # ─── Persistence ─────────────────────────────────────────────────────────────
 
 # Persist gh CLI auth to ~/.config/gh inside container, stored in

.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
@@ -179,18 +197,28 @@ push. `bump` (without `--push`) warns about this.
 
 ```bash
 lpb-config status | update | reset [--force] | merge   # config repo
+lpb-config render [--force]                             # regen runtime config from templates
 lpb-config align                                        # pins → latest GitHub tags
 lpb-config memory show | setup                          # lpb-memory config
 ```
 
+`render` recreates the gitignored runtime files (`settings.json`,
+`lpb-memory-config.json`) from the repo's templates. lpb-config auto-renders
+after `reset` (force) / `update` / `merge` (non-forcing): without it the
+rendered config was unrecoverable after `reset` (start.sh only renders on
+first boot, gated by `~/.pi/.initialized`). Non-forcing render never
+overwrites — it creates missing files and warns on stale pins; `--force`
+merges (user keys/packages preserved, template pins win in settings.json,
+local keys win in the memory config).
+
 **`lpb-devstack`** — DevOps workspace tool (container + host):
 
 ```bash
 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:
@@ -207,11 +235,14 @@ Both tools are thin CLIs over the shared `scripts/localpibox/stack/` library
 
 1. Config repo ships `settings.json.template` with `__LPB_VERSION__` placeholders
 2. First boot: `start.sh` generates `settings.json` (replaces placeholders)
-3. No model/provider preconfigured — user runs `/login lemonade`
-4. Pin sync: `lpb-devstack workspace sync --extensions`
+3. `lpb-config render` regenerates it on demand (auto after reset/update/
+   merge) — this is the recovery path when the rendered file is lost or
+   its pins are stale after a stack version move
+4. No model/provider preconfigured — user runs `/login lemonade`
+5. Pin sync: `lpb-devstack workspace sync --extensions`
    (main pipeline reads the stable version from devstack `origin/main`)
-5. `lpb-devstack validate` checks pins match the current stack version
-6. Persistent on the host volume — survives container rebuilds
+6. `lpb-devstack validate` checks pins match the current stack version
+7. Persistent on the host volume — survives container rebuilds
 
 Pins look like: `git:github.com/lpb-stack/pi-subagents@0.0.57-lpb-dev`
 
@@ -269,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`

Dockerfile

@@ -174,9 +174,13 @@ COPY support/validate-subagent-output.ts /opt/pi-support/validate-subagent-outpu
 COPY support/config/ /opt/pi-support/config/
 COPY support/docs/ /opt/pi-support/docs/
 COPY support/schemas/ /opt/pi-support/schemas/
-# Shared Python helpers used by the ported support tools (import via the
-# script directory, which Python adds to sys.path automatically).
+# ── Shared Python helpers + user-facing CLIs ─────────────────────────────
+# The localpibox package and the lpb-config/lpb-devstack CLIs are the source of
+# truth in scripts/ (single copy — no support/ duplicates). They must live
+# under /opt/pi-support/ for their sys.path resolution.
 COPY scripts/localpibox/ /opt/pi-support/localpibox/
+COPY --chmod=755 scripts/lpb-config /opt/pi-support/lpb-config
+COPY --chmod=755 scripts/lpb-devstack /opt/pi-support/lpb-devstack
 
 # ── Devstack deployment scripts ──
 COPY --chmod=755 support/install-browser.py /opt/devstack/install-browser.py
@@ -204,8 +208,6 @@ RUN mkdir -p /home/lpb/.local/bin \
 # lpb-config / lpb-devstack need to live under /opt/pi-support/ for their
 # sys.path resolution (the localpibox package is copied there above).
 # Symlinks at ~/.local/bin give users the clean CLI names.
-COPY --chmod=755 support/lpb-config /opt/pi-support/lpb-config
-COPY --chmod=755 support/lpb-devstack /opt/pi-support/lpb-devstack
 
 # ── Root operations: ownership + gitconfig + shell PATH ─────────────────────
 USER root

README.md

@@ -26,13 +26,16 @@ lpb                              # resumes your last project (or ~)
 ```
 
 On the **first run** the container pulls the image, clones the config preset,
-generates `settings.json`, and installs the extensions — then Pi starts.
-You'll be asked to connect a model:
+generates `settings.json`, and installs the extensions. Before Pi starts, the
+**first-run setup wizard** walks you through connecting your Lemonade server:
 
-```
-/login lemonade     # connect to the local Lemonade server (must be running on the host)
-/model              # pick a model (e.g. the Qwen3.6-35B reasoning model)
-```
+1. server URL (pre-filled from `LEMONADE_BASE_URL`, health-checked)
+2. API key (a placeholder like `lemonade` is fine for a local server)
+3. default model (picked from the server's model list)
+4. lpb-memory configuration
+
+After that Pi starts fully configured. Re-run it any time inside the
+container with `lpb-config setup --reconfigure`.
 
 ### Common commands
 
@@ -119,7 +122,8 @@ CI tags images per pipeline: `:0.0.x-lpb[-dev]-cli/web` (versioned),
 | `lpb /path` | Pi CLI session (foreground); no path → last project or `~` |
 | `lpb --web /path` | VSCodium (background); `--port 8080` to change the port |
 | `lpb --shell /path` | Interactive bash inside the container |
-| `lpb --ssh [pubkey] /path` | sshd server in the container for remote login |
+| `lpb --ssh [pubkey\|path] /path` | sshd server in the container for remote login (key auto-detected from `~/.ssh` when omitted) |
+| `lpb --ssh --ssh-password [pw]` | SSH password login (random if omitted, shown once; can combine with a key) |
 | `lpb --stop` / `--remove` / `--logs` | Stop / stop+remove+state cleanup / stream logs |
 | `lpb --update` | Self-update launcher + pull latest image for the selected pipeline |
 | `lpb /path -- <pi-args>` | Pass args to Pi, e.g. `lpb /path -- -p "summarize this repo"` |
@@ -194,14 +198,14 @@ flowchart LR
 ## Forked Repos & Upstream Policy
 
 Fork URLs and branches are tracked in `lpb.stack.env` at the repo root.
-Each fork carries its LocalPibox work as a **single squashed commit** on top
-of upstream, so the delta vs upstream is always one clean patch.
+Each fork keeps its LocalPibox work as clean commits on top of upstream
+merges, so the delta vs upstream can always be extracted as one patch.
 
 | Repo | Upstream | LocalPibox work | Update policy |
 |---|---|---|---|
 | **pi** | `earendil-works/pi` (v0.84.2) | Qwen `reasoning_effort` + context-overflow patches | rebase onto new upstream releases |
 | **lemonade-pi-plugin** | `lemonade-sdk/lemonade-pi-plugin` (no stable release) | Qwen thinking + vision support | follow upstream `main`, check periodically |
-| **pi-subagents** | `tintinweb/pi-subagents` (v0.14.3) | centralized local-first subagent model registry | follow `master`; submit upstream if clean |
+| **pi-subagents** | `tintinweb/pi-subagents` (v0.16.1) | centralized local-first subagent model registry | follow upstream; merge + repair as needed |
 | **lpb-memory** | *(independent project)* | Pi memory extension (subprocess reviews) | no upstream to track |
 | **config** / **devstack** | — | own | own |
 
@@ -230,8 +234,10 @@ Versioning is **manual**: `lpb-devstack bump` commits a new `VERSION`, and CI
 builds + tags only when VERSION changed in the pushed commit. Pipeline jobs:
 **VERSION check** → **test** (always) → **build & publish images** →
 **tag repos** (CI tags the other 5 stack repos on their pipeline branches) →
-**status**. Devstack itself is tracked by its `VERSION` file and is never
-tagged.
+**docs publish** (main pipeline only — publishes the stable docs version,
+gated on the docs being flagged ready via `lpb-devstack release docs-ready`
+before promotion) → **status**. Devstack itself is tracked by its `VERSION`
+file and is never tagged.
 
 ## Troubleshooting
 
@@ -281,24 +287,25 @@ devstack/
 ├── lpb.stack.env         # fork URLs, image names, container identity
 ├── lpb.conf.env          # runtime defaults (baked into the image)
 ├── .env.example          # template for per-project .env (LPB_ vars)
-├── scripts/
+├── scripts/              # CLIs + shared package (single source, baked to
+│   │                     # /opt/pi-support/ by the Dockerfile)
 │   ├── lpb               # bash wrapper
 │   ├── lpb.py            # launcher engine (stdlib-only Python)
+│   ├── lpb-config        # config repo manager (in-container)
+│   ├── lpb-devstack      # DevOps tool (bump/tag/workspace/validate/release)
 │   ├── install.sh        # host installer (lpb + stack tools)
 │   └── localpibox/       # shared Python helpers (env/log/run/cli/stack)
-├── support/
+├── support/              # runtime image tools (start.sh, browser, schemas…)
 │   ├── start.sh          # container bootstrap (config, .env, extensions)
 │   ├── entrypoint-*.sh   # cli / web entrypoints
-│   ├── lpb-config        # config repo manager (in-container)
-│   ├── lpb-devstack      # DevOps tool (bump/tag/workspace/validate/release)
 │   └── docs/             # operational docs (e.g. subagent spawning)
 └── doc/                  # reference docs (mirrored to the docs site)
 ```
 
 ## Documentation & Related Repos
 
-- [Documentation site](https://lpb-stack.github.io/devstack/) — versioned
-  per stack tag
+- [Documentation site](https://lpb-stack.github.io/devstack/) — one version
+  per stable release (served from the `docs` branch)
 - [lpb-stack/pi](https://github.com/lpb-stack/pi) — Pi monorepo fork
 - [lpb-stack/config](https://github.com/lpb-stack/config) — agent config preset
 - [lpb-stack/lemonade-pi-plugin](https://github.com/lpb-stack/lemonade-pi-plugin) — Lemonade provider plugin

VERSION

@@ -1 +1 @@
-0.0.60-lpb
+0.0.62-lpb-dev

doc/config-repo.md

@@ -71,7 +71,7 @@ Extensions are pinned in the `packages` array of `settings.json` as
 
 The `__LPB_VERSION__` placeholder in the template is replaced with the
 stack version at boot. Pins are synced to a new stack version by
-`lpb-devstack workspace sync --extensions`.
+`lpb-devstack workspace sync-pins`.
 
 ## Extension Clones
 
@@ -142,7 +142,7 @@ lpb-config update
 lpb-devstack validate
 
 # Sync extension pins to stack version
-lpb-devstack workspace sync --extensions
+lpb-devstack workspace sync-pins
 
 # Reset config repo
 lpb-config reset