stack/docs/plans/2026-10-11_mosaic-on-path-docs.md

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.