docs(plans): brief for the mosaic-on-PATH docs after Q81

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-11 16:18:57 -05:00
parent d3ca2c22d6
commit 19e38d7f2d
1 changed files with 58 additions and 0 deletions
@@ -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.