# 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.