advance live-docs on a release, and track it from a packaging workspace

[MattDHill]

Problem

A packaging workspace cloned master. master carries the SDK that hasn't shipped: its projects/start-sdk is 2.0.10 while every published package pins @start9labs/start-sdk 2.0.9. So the guide a packager reads, the template init-package scaffolds from, and the SDK source they grep all describe an SDK npm install cannot resolve — and the local guide disagrees with docs.start9.com.

live-docs is the branch that should answer this. It doesn't yet, because nothing has ever advanced its code: it was branched off master's tip in #3652 on 2026-08-10 and only projects/<project>/docs has moved since. Its projects/start-sdk/lib is still that day's in-progress 2.0.10 (5 files / 170 lines of post-v2.0.9 work), and shared-libs/, .github/ and the repo root have not moved a single file in three weeks.

Change

docs-sync-on-tag.yml now advances live-docs to the release, not just its book. It takes the tagged tree whole, then restores every other projects/* to the release it is on. A tag therefore speaks for its own project, the shared libraries beneath it, and the repo root — and for nothing another product owns.

• projects/start-docs (shared site tree, versions.conf included) rides along only with a product that ships a book. A bookless release — start-cli, start-registry — now refreshes its own project and the shared tree instead of being skipped whole, and docs-deploy.yml's paths filter is what keeps it from firing a needless deploy.
• Nothing moves backwards, judged per tree. A product's own tree is compared against that product's earlier syncs; the shared trees (shared-libs/, the root, projects/start-docs/) against every product's. So a deb release, which tags the commit alpha built and is routinely behind a tag cut before it, still advances its own project while the shared trees stay where the newer release put them. A tag behind its own product's last release publishes its book alone, or nothing if it has none. Every earlier sync is consulted, not the newest, because syncs land out of ancestry order.
• [skip-backport] is unchanged and load-bearing — none of the newly-synced paths can bounce onto master.

s9pk init-workspace clones live-docs. git pull --ff-only stays the session-start sync, so there's no new command; a workspace now picks up corrections to published pages the moment they go live, and a release brings that product's whole tree with it.

live-docs-guard.yml fails a PR into live-docs that changes anything but a published book. The branch now carries code, and only the tag sync may write it — a PR that carried code would put a tree there that no release produced, and docs-backport.yml would push it onto master unattended, unreviewed as a code change. Nothing gated PRs into that branch before. It takes edited alongside its live-docs branch filter, so a PR retargeted onto live-docs is checked at once rather than at its next push, and it is registered with check-pr-retarget-workflows.py as a direct listener, like conflict-markers.

The predicate is a rule (projects/<product>/docs/, projects/start-docs/) rather than a mirror of docs-deploy.yml's paths, so a new product's book is covered the moment it exists. It rejects one path under docs/: the package template, which init-package reads out of the workspace's checkout at scaffold time rather than from the binary — so a merge there would change what every new package is built from at once, without facing manage-release.sh pre-check start-sdk's gate on its SDK pin.

An s9pk command says when start-cli itself is behind. start-cli installs outside the workspace, and the two halves drift differently: on Debian the installer adds an apt repo and apt upgrade carries it forward, while on macOS and every other Linux it drops a binary in ~/.local/bin with no update path the guide ever mentioned. Since projects/start-cli on live-docs only moves on a start-cli tag, its manifest names exactly the version a packager should be on — so the check is a file read against the version baked in at build time. Printed once per process, silent on anything unreadable, and hung off the workspace lookups s9pk work already does (signing, init-package) so it fires where a stale binary would bite.

Verification

Sync logic, against a synthetic repo: two products, a with a book and b without, live-docs branched at C0, master C0 → C1 → C2 → C2b → C3, tags applied in the order below.

tag	own tree	shared-libs/ + root	projects/start-docs	other products
a/v1 at C2	→ C2	→ C2	→ C2	held at C0
b/v1 at C1 (behind a/v1, no earlier b)	→ C1	held at C2	held at C2	held
b/v0 at C0 (behind b/v1)	nothing published	held	held	held
a/v0 at C0 (behind a/v1)	book → C0, code held at C2	held	held	held
b/v2 at C3 (ahead of everything)	→ C3	→ C3	held, bookless	held
a/v2 at C2b (ahead of a/v1, behind b/v2)	→ C2b	held at C3	held	held
a/v9 off master	refused
a/v2 again	no commit

The same harness against the previous revision of this branch: b/v1 and b/v0 failed the job on the book-only path, and a/v2 rolled shared-libs/ and the root back to C2b.

Guard predicate, eight cases: book pages, versions.conf, book.toml and a stray docs/*.md pass; shared-libs/, projects/start-sdk/lib/, root AGENTS.md, and package-template/ fail, including when mixed into an otherwise-clean docs PR.

Not covered

The tree live-docs inherited on 2026-08-10 is not repaired here — each project converges at its own next tag. A one-off reset of live-docs to per-project release state is a separate change against a protected branch.

Docs

environment-setup.md, agent-context.md, workflow.md, cli-reference.md, the root and start-docs/start-sdk AGENTS.md release and branch descriptions, and the unreleased start-cli 2.0.0 changelog.

🤖 Generated with Claude Code