diff --git a/docs/plans/2026-10-11_mosaic-on-path-docs.md b/docs/plans/2026-10-11_mosaic-on-path-docs.md new file mode 100644 index 000000000..bf783d5e5 --- /dev/null +++ b/docs/plans/2026-10-11_mosaic-on-path-docs.md @@ -0,0 +1,58 @@ +# Docs after Q81: `mosaic` on PATH can be the mosaic-stack CLI (2026-10-11) + +Status: written by Sage, lead, after Q81 (sage-0042). It follows +`docs/plans/BRIEF-TEMPLATE.md`. One row, docs only. + +## Docs say mosaic on PATH is the estate CLI; after Q81 it can be this one + +### Problem + +Q81 put a wrapper at `~/.npm-global/bin/mosaic` on Jason's host (commits +918a4a19 and d3ca2c22, `agents/sage/work/q81/mosaic-cli.sh`). It runs +`scripts/mosaic` from a detached worktree pinned to a pushed commit and +forwards only `__lease-capability` to the renamed estate CLI, +`~/.npm-global/bin/mosaic-old`. Three places still say the opposite: + +- `scripts/mosaic` lines 10-11: "Not the npm-global `mosaic` CLI from the + estate tooling; this one is repository-local and only reachable as + scripts/mosaic." +- `docs/TOOLS.md` line 146: "Not the npm-global `mosaic` CLI; run by path." +- `packages/seat/README.md` line 14: "It is not on PATH and is not the + npm-global `mosaic` CLI from the estate tooling ... run it by path." + +None of them says what a reader most needs. A pinned `mosaic` is not the +working checkout, and `mosaic queue` refuses there ("this queue code ... +is not under the canonical root"), so queue work stays on +`scripts/mosaic` in the canonical checkout. + +### Owner and reviewer + +Owner: Sage. Reviewer: Filbert. + +### Files owned + +- `scripts/mosaic`, the header comment only +- `docs/TOOLS.md`, the seat-launch paragraph's last sentences only +- `packages/seat/README.md`, the "Commands" paragraph only + +### What ships + +- Each place says `scripts/mosaic` is the repository wrapper. A host may + also put it on PATH as `mosaic`, pinned to a pushed commit. On Jason's + host that's the Q81 wrapper, and the estate CLI is `mosaic-old`. +- Each says `mosaic queue` refuses from a pinned copy, so queue commands + run as `scripts/mosaic queue` in the canonical checkout. +- No code change. The cli, queue and seat node suites and every + `scripts/test-*.sh` still pass. The queue dispatch test reads + `scripts/mosaic`, and a header edit must not move its seat usage text. + +### Out of scope + +The Q81 script itself, which is host operations under +`agents/sage/work/q81/`. Packaging `mosaic` for other hosts. Any change to +the queue's canonical-checkout refusal. + +### Gate + +Filbert approves on the row's issue naming the candidate manifest. The +suites above are green on Sage's gate run.