m0saic 0.2.2 → 0.3.1

package/node_modules/@m0saic/knowledge/docs/runtime/cli-usage.md

@@ -0,0 +1,475 @@
+# m0saic CLI usage
+
+> Regenerated 2026-07-29 from the CLI source (not published) — re-verify with
+> `m0saic --help` / `grep -c '.command(' the CLI source (not published) (14 as of
+> 2026-07-29, **2 of them dev-gated** — `browse-templates` and `momo`; a 15th
+> command, `telemetry`, registers via a helper — see below). So: 12 public
+> commands + 2 dev-gated + `telemetry`.
+>
+> **2026-09-16:** `doctor` (added after this snapshot, dev-gated at 0.1.0) is now
+> **public** — see its row; `browse-templates` and `momo` remain the only two
+> `if (DEV_MODE)` commands. Public set is locked by `PUBLIC_COMMANDS` in
+> the CLI source (not published) (15 incl. `doctor`, `hello-world`).
+
+Source of truth: [the CLI source (not published)](the CLI source (not published))
+(~5,866 lines). Inline-DSL arg parsing: [the CLI source (not published)](the CLI source (not published)).
+Root `COMMANDS.md` (monorepo document, not published) documents the inline-DSL shorthand + test tiers.
+
+## Entry routing — inline-DSL mode is first-class
+
+Before commander ever runs, `index.ts:~7279-7285` inspects `process.argv[2]`:
+`isInlineM0()` (`inlineDsl.ts:36-41`) treats ANY first arg that is not a flag and
+not in `KNOWN_SUBCOMMANDS` as an inline m0 string and dispatches to
+`handleInlineDsl` instead of `program.parseAsync`.
+
+```bash
+m0saic "2(1,1)"            # static wireframe → output.png (default mode "wire")
+m0saic "2(1,1)" --anim     # animated wireframe → output.mp4
+m0saic "2(1,1)" --wire     # explicit static (same as default)
+m0saic layout.m0           # .m0 / .m0c paths also accepted (index.ts:~7184-7270)
+```
+
+- Args after the string parse via `parseInlineArgs` (`inlineDsl.ts:123`): `-w/-h`
+  (default 1920×1080), `-o`, `--fps`, `--durationMs`, `--props`, `--save-mosaic`,
+  `--save-m0`, `--prefer-pretty-m0`/`--prefer-canonical-m0`, `--disable-ui`,
+  `--format`, `--alpha`, `--validate-only`, `--report`, `--toolchain`, plus the
+  dev-gated dump flags (below).
+- The string is validated with `validateM0String` before render (index.ts:~7222);
+  whitespace is stripped. Always shell-quote the DSL (parens/brackets).
+- Output extension is coerced to match mode (`resolveInlineOutput`,
+  `inlineDsl.ts:86` — `--anim -o out.png` → `out.mp4`).
+- Mode maps onto the wireframe handlers: `wire` → `handleWireframe`, `anim` →
+  `handleAnimatedWireframe` (index.ts:~7264-7266).
+
+## Command table
+
+18 `.command(` registrations in `index.ts` + `telemetry` registered by
+`registerTelemetryCommand(program)` (index.ts:~7138 → `utils/telemetry.ts:~372`).
+Two of the 18 sit inside `if (DEV_MODE) { … }` and are absent from the public
+help — see the DEV-GATED rows below.
+
+> **Line numbers are loose signposts, written `~NNNN`** (founder ruling
+> 2026-09-25). `index.ts` is ~7,200 lines and every number in this doc had drifted
+> within weeks. **The greppable symbol is the anchor; the number only says
+> roughly where to look.** A number that has moved is not a defect and does not
+> earn a fix pass — correct one when you are editing that row anyway, and
+> otherwise leave it.
+
+| Command (index.ts line) | What it does |
+|---|---|
+| `make <input>` (~5095) | Primary render: template id / `.mosaic` / `.mosaicx` → video or image. Full flag surface below. |
+| `hello-world` | The first render — a thin alias for `make @m0saic/hello-world/v1` (the brand card; output defaults to `hello-world.mp4`). With `--template-repo <path...>` / `--community-repo <path>` it renders the loaded repo's **front door** instead: the first repo (load order) whose `repo.helloWorld` names a template that registered, announced as `Front door: <id> — <repo>'s hello-world`; no repos, or none that name one → the core card with a one-line why. Takes `-o -w -h --fps --durationMs --props --quiet --verbose` (no engine surface). Picker: the CLI source (not published). |
+| `make-wireframe` (~5462) | Static wireframe PNG from `--m0 <string>` or `--mfile <path>`. |
+| `make-wireframe-animated` (~5568) | Animated wireframe MP4 from `--m0`/`--mfile`; extra `--disable-ui`. |
+| `flatten <input>` (~5680) | Inline all `type:mosaic` children of a `.mosaic`/template into one flat JSON doc — no render. |
+| `resolve <input>` (~5800) | `.mosaicx` recipe → resolved `.mosaic` provenance doc, no ffmpeg; `--flatten` also inlines children. |
+| `list-templates` (~5946) | Print registered template ids (`--json`); annotates primitive/internal/deprecated. |
+| `doctor <repoDir>` | **Public since 0.2.0** (dev-gated at 0.1.0; founder ruling 2026-09-16, BURN-DOWN D5 → publish). Run the template conventions over a template repo folder — the same checks its build gate (`tools/check-registry.mjs`) runs, from outside (agents, reviewers, forks, CI on a fork): definition-time + render-time conventions (the 13 throw-posture ones incl. `latticeSmooth`) and, when the repo commits `layout-fingerprints/` or `.layout.m0` sidecars, the fingerprint diff. `--json` (one object: `ok, repo, mode, loadDiagnostics, rendered, skipped, errors, warnings, notes, fingerprints, conventions`), `--sweep` (also render on the standard 1080p canvases → `canvasEnvelope`), `--entry <path>`, `--src <dir>`. Loads through `loadTemplateRepoFromPath` under the external origin scope, so conventions RECORD rather than throw and one bad template never hides the rest. **Runs the repo's template module bodies in-process** — prints a trust warning to stderr (not under `--json`). Exit 1 on any error-severity finding or a fatal load diagnostic. It is the pack-publishing contract for community/starter authors ("the publish requirement for packs"). Impl: the CLI source (not published); locked public by `__tests__/cli.surface.test.js`. |
+| `browse-templates` (~6033) | **DEV-GATED** (whole command inside `if (DEV_MODE)`, 4792): interactive TTY picker (template → variant → confirm → delegates to `make`). It drives the E2E variant matrix and writes to `test-output/` — a development harness, not a user surface. |
+| `momo <message…>` (~6282) | **DEV-GATED** (whole command inside `if (DEV_MODE)`, 5040): relay English geometry instruction to Momo in a running Mosaic Desktop over the loopback bridge; exit 0 applied / 2 not-applied / 1 couldn't-run. |
+| `init <name>` (~6464) | Scaffold a template workspace — the compact starter twin, renamed to the user's handle. `--dir`, `--handle`, `--display-name`. Shares ONE scaffold with Desktop's Start pane (`scaffoldTemplateWorkspace` in `@m0saic/product`), so the two cannot drift. Deliberately does NOT write the trust store: loading an external repo is the user's consent, recorded by the app in `~/m0saic/template-trust.json`. Prints the install / build / fingerprint line and the Add-source hint. |
+| `mcp` (~6538) | Run the CLI as an **MCP server** over stdio — the agent-facing surface. See below. |
+| `open [file]` (~6608) | Open a file in Mosaic Desktop, or `--template` / `--make` to open the Make page via the bridge. See below. |
+| `setup` (~6830) | Download + install the pinned ffmpeg toolchain (`--gpl` default / `--lgpl` / `--yes` / `--platform-key`). Idempotent: detects installed golden slot or a PATH ffmpeg with libx264. **The only path that downloads** — renders never do. TTY asks `Download the pinned GPL ffmpeg build now?`; non-TTY / `CI` need explicit approval — `--yes` (or the `--gpl` / `--lgpl` repair flags), otherwise `No terminal to ask for approval on.` + exit 1, nothing downloaded. Ends `✓ ffmpeg is ready. Now run your m0saic command again.` |
+| `activate <key>` (~7000) | Validate + store a license key at `~/m0saic/license.json` (`M0SAIC_PRODUCT_KEY` env wins over the file). **A VERIFIED key — valid, in grace, expired or revoked — also sends ONE notice to m0saic.io from a detached worker (`utils/licenseActivation.ts` → `licenseActivationWorker.js`): the key's `keyId`, the outcome, `surface: "cli"`, the CLI's major.minor. Never the token, the email or the install id. Sent in EVERY telemetry mode — the one signal outside them (founder ruling 2026-09-26); honours `M0SAIC_TELEMETRY_ENDPOINT=off`, `CI` (unless the endpoint came from env) and dormancy (a dev checkout never sends); ignores the mode and `DO_NOT_TRACK`. The command prints "Told m0saic.io this key was used …" after the verdict, and `--help` says so. An unverified key sends nothing.** `TELEMETRY.md` §1.16. |
+| `license` (~6991) | Show tier/holder/expiry; `--remove` returns to free tier. |
+| `update` (~7050) | Check npm for a newer release; offers `npm i -g m0saic@latest`. |
+| `versions` (~7116) | Print **every bundled `@m0saic/*` package**, grouped by tier (language / substrate / product — the CLI bundles no community package) + ffmpeg baseline/runtime + resolved toolchain. `--json`: `packages` holds ALL bundled packages (a superset of the old `templates`/`types` pair, so scripts keep working). Classification comes from `@m0saic/platform` `describeMosaicPackage`, shared with Desktop's Tools → About this build (2026-09-26). |
+| `telemetry` (via helper) | Subcommands `status` (default) · `set-mode <standard\|local-only\|ghost>` · `list` · `preview` · `flush` · `clear`. Since 0.2.0 PUBLISHED builds transmit (Standard mode): day summary + today-so-far rollups after renders via a detached worker, to `https://m0saic.io/api/telemetry`. Workspace builds are dormant. Gates for harnesses: `M0SAIC_TELEMETRY=ghost` (nothing recorded), `M0SAIC_TELEMETRY_ENDPOINT=off` (nothing sent), `CI` (no send unless the endpoint is set by env). **Modes govern usage telemetry only: `activate` is in `CLI_USAGE_SKIPPED_COMMANDS`** — its notice is identity-less, and the rollup deliberately carries no `cli.command.activate` counter beside it (the pairing would link an install id to a key id). `status` / `preview` cannot list the notice: it is never queued. Full reference: `TELEMETRY.md` at the repo root (§1.16 for the notice). |
+
+> **`decode-watermark` is GONE** (removed 2026-07-28). Recovering a forensic
+> watermark is now an ordinary template — `@m0saic/forensic/watermark/verify/v1`,
+> run through `make` — because a CLI can't grow a bespoke command per template
+> family. The old `--ffmpeg <path>` override it carried is now the template's
+> `ffmpegPath` prop.
+
+## `make` input routing (index.ts:~5340-5372)
+
+1. Extension `.mosaic` → `handleMosaicFile` — parse JSON renderable, resolve
+   relative media against the file's dir, plan + render.
+2. Extension `.mosaicx` → `handleMosaicxFile` (~4214) — the **resolve-then-render
+   branch**: absolutize asset paths → apply the doc's `runner` block as option
+   defaults (explicit flags win) → sibling `.m0v` auto-discovery → route
+   `--inputs`/`--input-dir` into the single `template_invocation`'s
+   `props.sourceIds` (ambiguous multi-invocation → error; zero inputs on an
+   input-requiring template → renders a usage-card and exits non-zero) →
+   `resolveMosaicx` → write resolved doc to a tmp `.mosaic` → delegate to
+   `handleMosaicFile` (~4460, defined ~4475) so the post-resolve render path is shared.
+   **Two roots accepted** (2026-08-14): `mosaicx_document` and
+   `mosaicx_pipeline` (a root-level template chain — see
+   `templates/data-pipeline.md`). The header echoes which one it read
+   (`kind: mosaicx_pipeline`). A chain root has no top-level `sources`, so the
+   `--inputs` routing and the usage-card gap detection above are inert for it;
+   `runner` applies to both. Same for `resolve <input>`.
+   **Duration is an ASK on this path** (2026-09-05): `--durationMs ??
+   wrapper.durationMs` reaches the template as `userIntent.durationMs` via
+   `mosaicxUserIntent` (`mosaicxRunner.ts:405`) on both `make` and `resolve`, so a
+   self-timing template FITS its walk to the length (as Make does) instead of
+   being trimmed to it. Mint ledger wrappers mirroring the template's natural
+   length unless the variant is deliberately pinned.
+3. No extension + starts with `@` → `handleTemplateMake` — template id, merge
+   `--props` over `defaultProps`, render.
+4. Anything else → error, exit 1.
+
+## Exit codes (2026-09-15)
+
+| Code | Meaning | File at `-o`? |
+|---|---|---|
+| `0` | Success — the output is the render asked for. | Yes |
+| `1` | Failure — plan build threw, ffmpeg exited non-zero, validation failed, zero commands. | No / unusable |
+| `2` | `momo` ran but did not apply a change. | n/a |
+| `3` | **RENDER DEGRADED** — the renderable carried `engine.renderStatus: "error"`, so the output is an **error mosaic**. | **Yes**, valid media |
+
+**Why 3 exists.** A template that hits bad input does not crash: it returns
+`makeErrorMosaic(...)`, a readable card stamped `engine.renderStatus: "error"`.
+That card renders, so the CLI used to write it and exit 0 — a caller whose only
+success test was "did a file appear at the expected path?" reported success on a
+picture of an error. 3 is deliberately not 1: exit 1 means "there is no output,
+retry or clean up", which is false here. The engine still never aborts on the
+marker — it renders, writes the file, and *then* the CLI reports.
+
+**Detection** (`src/utils/collectRenderErrors.ts`) walks the WHOLE renderable
+tree for the marker: document level, source level, nested `children`
+(recursively), and pipeline `steps` (dispatching per step, so a nested pipeline
+is walked too). **One error mosaic anywhere in the tree degrades the whole run** —
+a batch where 4 of 5 steps are fine still exits 3, because one deliverable is an
+error card. `errors[].path` in the sidecar (`children.hero.sources[0]`,
+`steps[1].sources[0]`) says which.
+
+> ⚠️ Historical: the walker read `doc.config?.sources`, but
+> `MosaicDocument.sources` was hoisted out of `config` long ago — so every
+> source-level marker (exactly where `makeErrorMosaic` puts it) was invisible and
+> every error-mosaic render exited 0. `mosaicxRunner` hand-promoted its error to
+> doc level to work around it; both the bug and the workaround are gone.
+
+**Classification** (`src/utils/renderOutcome.ts` — the single decision point; all
+12 report call sites in `index.ts` route through it):
+
+- **Hard errors beat engine errors.** A run with both is 1, not 3.
+- A **zero-command plan** counts its engine errors as hard — there is no output
+  to call degraded — so that path stays 1.
+- Free vs paid tier is **orthogonal**. The marker is read off the document, not
+  the file; the free-tier QR wrap runs before classification, so on free tier the
+  error card ships stamped and still exits 3. A stamp failure is swallowed as a
+  warning and never changes the exit code.
+
+With `--report` the same verdict is machine-readable, so a caller that parses the
+sidecar never needs the exit code and a caller that reads exit codes never needs
+the JSON:
+
+```json
+{ "ok": false, "exitCode": 3, "renderStatus": "degraded",
+  "renderErrorCodes": ["ENGINE_ERROR"],
+  "errors": [{ "code": "ENGINE_ERROR", "message": "Quote Card: quote must not be empty", "path": "sources[0]" }] }
+```
+
+## `make` flags
+
+**Core** — `-w/--width` and `-h/--height` are `requiredOption`s. Then:
+`-o/--output` (defaults `out.mp4` / `out.png`, index.ts:~172-173), `--fps` (1–120),
+`--durationMs` (>0), `--format`/`--output-kind` (`video|image`),
+`--alpha`/`--no-alpha`, `--props <jsonOrPath>` (inline JSON **or** `@path/to/json`
+— `utils/readJsonArg.ts:18` strips the `@` and reads the file),
+`--validate-only` (exit 0/1/3, no render — 3 = the renderable IS an error
+mosaic; prints `Validation DEGRADED`), `--report` (`.output.json` /
+`.validate.json` sidecars, both carrying `renderStatus` + `renderErrorCodes`),
+`--save-mosaic [path]`, `--save-m0 [path]`,
+`--keep-temp`, `--quiet`, `--verbose`, `--prefer-pretty-m0` /
+`--prefer-canonical-m0` (printed-m0 form only; note: NOT `--prefer-*-m0saic`),
+`--background-color <color>`, `--template-repo <path...>` +
+`--template-repo-entry <file>` (external template repos), `--community-repo <path>`
+(ONE checkout of the official community repo — see the community gate below).
+
+**Encode surface** (index.ts:~4231-4338, mirrors the Make page's Advanced panel;
+precedence: flags > `.m0v` preset > doc-on-disk > engine default):
+`--target <preset>` (`web-mp4|web-webm|alpha-mov|image-png|image-jpeg|animated-gif|audio-mp3|audio-wav`),
+`--container`, `--video-codec`, `--audio-codec`, `--pixel-format`, `--bitrate`
+(CRF wins on conflict), `--crf`, `--encoder-preset`, `--encoder-profile`,
+`--encoder-level`, `--encoder-options <k=v,…>`, `--gop-size`, `--audio-bitrate`,
+`--audio-sample-rate`, `--audio-channel-layout`, `--no-audio` (`-an`),
+`--color-space`/`--color-range`/`--color-primaries`/`--color-transfer`
+(metadata-only), `--metadata-title`/`-description`/`-author`/`-copyright`/`-comment`.
+
+**Batching / multi-output**: `--inputs <files...>` (populates `sourceIds`; wins
+over `--input-dir`), `--input-dir <path>` (+ `--recursive` for depth-first walk),
+`--output-pattern <pattern>` (tokens `{{base}} {{ext}} {{stepName}} {{index}}
+{{i}} {{date}} {{batch}} {{label}}`; collisions get `-1,-2,…`), `--batch <name>`.
+
+**`.m0v`**: `--m0v <path>` loads a Mosaic Vocabulary file two ways — named
+outputs onto `ctx.userIntent.outputs` (template-consultative) AND a post-render
+merge onto the renderable **by index** when entry counts match
+(index.ts:~4218-4221; `BaseRenderOptions` docstring ~541-557).
+
+**Toolchain**: `--toolchain <name>` is a **global program option**
+(index.ts:~526), not make-specific — a named entry from `m0saic.local.json`, with
+implicit `gpl`/`lgpl` golden slots merged in. Resolution precedence: `--toolchain`
+flag > `M0SAIC_TOOLCHAIN` env > config `defaultToolchain` > PATH/golden fallback
+(`utils/toolchainConfig.ts:129`). There is **no** `--ffmpeg` anywhere on the CLI
+any more (it left with `decode-watermark`) — the equivalent is the verify
+template's `ffmpegPath` prop; `--platform-key` only on `setup`.
+
+**No-ffmpeg gate** (`utils/ensureFfmpeg.ts` via `ensureRenderToolchain()`, index.ts
+~404, first thing in every render handler): resolved ffmpeg fails to probe → the
+4-line `ffmpeg isn't detected.` message (points at `setup`) and **exit 1** — TTY,
+piped and CI alike; no prompt, no inline download, no auto-install (founder
+ruling 2026-09-16; supersedes cli-v1-publish.md Phase 2). `setup` is the only
+downloader, and it too never fetches without approval (TTY prompt, or `--yes`).
+Spell every `setup` hint with `cliSetupCommand()` (`utils/invocation.ts`):
+`npx m0saic setup` under npx, `m0saic setup` installed.
+
+**Perf**: `--perf [path]` writes a `.perf.json` sidecar — per-ffmpeg-command
+timing rolled up by mosaic node (names the bottleneck panel/template).
+
+**DEV-GATED** (each wrapped in `.hideHelp(!DEV_MODE)`; `DEV_MODE =
+process.env.M0SAIC_DEV === "1"` at index.ts:~71, compile-stripped to `false` in
+the published artifact): `--dev` (commands + timings), `--print-commands`,
+`--save-plan [path]`, `--save-commands [path]`. Same gating inside inline-DSL
+mode (`inlineDsl.ts:148-154`). Also dev-gated: the whole `momo` command, the
+whole `browse-templates` command, and `open`'s
+`--agent-note`/`--agent-question`. `--save-mosaic` and `--save-m0` are NOT gated,
+and neither is `doctor` (public since 0.2.0).
+
+> Note: a dev-gated command's NAME still appears in `KNOWN_SUBCOMMANDS`
+> (`inlineDsl.ts:11-29`), outside the gate — the inline-DSL router has to know
+> `momo` is a subcommand and not an m0 string. So grepping a shipped tarball for
+> `momo` / `browse-templates` finds hits; that is the router table, not the
+> gated implementation.
+
+## External template repos and the community gate (2026-09-16)
+
+**Three reserved identities, exact-match, nothing else is checked:** template
+namespaces `@m0saic/` and `@m0saic-dev/`, repo id `@m0saic-community`
+(`index.ts:~907-909`; registry compare is case-insensitive, `templateRegistry.ts:~112`).
+Every other namespace / repo id is open. `--template-repo` never grants anything.
+
+**The grant.** `--community-repo <path>` says "this IS the official repo"; the
+`@m0saic-dev/` grant comes only from `verifyCommunityRelease()` (`@m0saic/product`
+`communityRelease.ts`) passing on the checkout's `release.json` against
+`LICENSE_PUBLIC_KEYS` (`publicKeys.ts` — the licence k1 family; rotation = append
+`k2`, ship, sign with `M0SAIC_SIGNING_KID=k2`; older CLIs report `unknown-kid`).
+The gate runs BEFORE the entry module is imported. All gate/notice lines go to
+stderr (survive `--quiet`, keep `--json` stdout clean):
+
+- ok → `✓ community repo verified: <tag> (signed, <kid>)`
+- else → `⚠  <path> is not a verified release of the official community repo
+  (<reason>). Loaded as an ordinary template repo — its @m0saic-dev/ ids are
+  refused. Get the official checkout: the link on m0saic.io/community` → the
+  reserved ids are refused in ONE collapsed line, `⚠  [template-repo]
+  TEMPLATE_ID_RESERVED_NAMESPACE: refused <N> ids in reserved namespace
+  (@m0saic-dev/…): <id1>, <id2>, <id3>, …` (other rejection codes stay one line
+  each) → the existing `❌ Refusing to use template repo` block → **exit 1**.
+
+**`release.json` v1:** `{ schemaVersion: 1, tag, publishedAt, treeSha256,
+signature: { kid, alg: "ed25519", sig: <base64url> } }` (`--unsigned` omits
+`signature`; the legacy `{ tag, publishedAt }` reads as `missing-signature`).
+Tree = every file under `dist/**` + `template-manifest.json` + `package.json`,
+sorted POSIX paths, one `"<path>\0<sha256>\n"` line each; `*.json` hashed on
+`JSON.stringify(JSON.parse(text))` (BOM stripped; CRLF / re-indent survive, a
+key reorder does not), other files raw bytes; no symlink is ever followed.
+Payload `"m0saic-community-release/v1\n<tag>\n<publishedAt>\n<treeSha256>\n"`
+(`publishedAt` must be ISO 8601, else `malformed`). Ladder:
+`missing-release → malformed → missing-signature → unknown-kid → bad-signature
+→ symlink-in-tree / foreign-modules → tree-mismatch → ok` — signature before
+tree, so `tree-mismatch` = authentic release with edited dist/manifests,
+`bad-signature` = forged `release.json`; the two structural refusals
+(`symlink-in-tree`: ANY symlink under `dist/**`, `dist` itself or a signed
+root file; `foreign-modules`: a `node_modules` dir at the root or under
+`dist/`) sit between them and carry the offending path in the notice —
+`(symlink-in-tree: dist/node_modules)`, `(foreign-modules: node_modules)`.
+`publishedAt` is signed but there is still no anti-rollback (an older
+authentic release verifies).
+
+**A checkout never supplies `@m0saic/*` to itself.** The loader
+(`@m0saic/platform` `template-repos/hostFirstResolution.ts`, installed by
+`loadTemplateRepoFromPath` before the entry import) resolves every
+`@m0saic/<pkg>[/<subpath>]` require whose parent file lies under a loaded
+repo root from the HOST's own `node_modules` walk — the CLI's vendored copies,
+the desktop's bundle, the workspace under dev — never from the checkout. So a
+clone with nothing installed loads anywhere (0.2.0 is the first CLI that
+can), and a `node_modules/@m0saic/template-utils` planted beside a tree is
+never evaluated, via `--community-repo` or `--template-repo` alike. Every
+other specifier (`sharp`, `@twemoji/svg`, relative paths) resolves as before,
+from the checkout. CommonJS only — an `.mjs` entry's static `import`s use the
+ESM resolver, which has no hook.
+
+**Minting:** `scripts/sync-community-templates.mjs --tag <tag> --out <dir>` signs
+with `M0SAIC_SIGNING_KEY_FILE` (REQUIRED — no default path; production laptop
+only) under `M0SAIC_SIGNING_KID` (default `k1`), self-verifies against the
+embedded keys, writes `.gitattributes` (`* -text`). Unset or missing key =
+refused, never a silent unsigned release; `--unsigned` = loud banner, a snapshot
+no shipped CLI trusts.
+
+**DEV seam (workspace builds only, inside `if (DEV_MODE)`):** reasons
+`missing-release` / `missing-signature` are still granted — `✓ community repo:
+<path> (dev build: unsigned community checkout trusted)` (the in-repo
+https://github.com/m0saic-project/m0saic-community-templates/blob/main has no `release.json`) — and
+`M0SAIC_COMMUNITY_TRUST_KEY_PEM` (+ `M0SAIC_COMMUNITY_TRUST_KEY_KID`, default `k1`)
+adds a public key for tests. Tampered tree, forged release or unknown kid are
+refused even in dev. The tarball folds `process.env.M0SAIC_DEV` to `"0"` and the
+audit bans the token, so none of this ships.
+
+**Lookalikes are a display concern** — one stderr line for UNSIGNED repos, never a
+refusal: `⚠  [template-repo] <subject> is not an official m0saic namespace — only
+@m0saic/ and @m0saic-dev/ are, and they are signed.` Subject: loaded publisher
+namespaces starting with `@m0saic` that are not exactly the two reserved ones →
+else a repoId matching `/m0saic|mosaic/i` → else `"<displayName>" (<repoId>)`.
+Never for repoId exactly `@m0saic-community`: via `--template-repo` that gets
+`⚠  [template-repo] repo id "@m0saic-community" is reserved for the official
+community repo and this checkout is unverified — loading it under ordinary
+rules.` A `--community-repo` checkout that fails the gate gets ONLY the
+not-verified notice.
+
+**Desktop:** `installVersion()` runs `validateCommunityTree` → `verifyCommunityTree`
+(inline-requires `@m0saic/product`) → refuses `tag-mismatch`; failure =
+`{ ok:false, error: "downloaded tree rejected: release signature not verified
+(<reason>): <detail>", reason }` on the existing IPC path; `installed.json` gains
+`signedBy` + `treeSha256`; seam `installVersion({ releasePublicKeys })`. The
+seed/installed load path (`loadCommunityRepo`) does not re-verify; consent gate
+unchanged.
+
+Help wording for `make` / `hello-world` / `list-templates` is ONE string,
+test-locked (`__tests__/cli.flags.test.js`): "…Grants the @m0saic-dev/ namespace
+when its release signature verifies (unsigned or modified checkouts load as
+ordinary repos); the community checkout loads only this way".
+
+### Hardening (rounds 2 + 3, 2026-09-16)
+
+**Host-first `@m0saic/*` resolution.** https://github.com/m0saic-project/m0saic-packages/blob/main/packages/platform/src/template-repos/hostFirstResolution.ts (wired in `loadTemplateRepoFromPath.ts` via `registerHostFirstRepoRoot(repoRoot)` before the native `import(file://…)` of the entry): ONE wrapper around Node's real `Module._resolveFilename` (found by walking the prototype chain — under Jest `node:module` exports a subclass copy), installed once per process, persistent so render-time lazy requires are covered. A request matching `/^@m0saic\/[^/\\]+(?:\/.*)?$/` whose requesting module lies under a registered root (realpath'd) is resolved from the HOST's own `node_modules` walk — never the checkout's. Everything else (relative paths, non-`@m0saic` deps, host code) is untouched. CJS only. Consequences: a community clone loads from ANY directory with no `node_modules` (before this, `--community-repo` only worked inside the monorepo); a planted `node_modules/@m0saic/*` beside a verified tree is never evaluated, via either flag; a starter's `file:` link to `@m0saic/template-utils` resolves to the same physical package — no drift.
+
+**Fail-closed tree verification** (`inspectReleaseTree` in `communityRelease.ts`; desktop mirror `inspectCommunityTree` in the Mosaic Desktop / Web app source (not published), run by `installVersion`). A release tree is plain files and directories, nothing else. Refused, in this order after the signature check and before the hash compare: `symlink-in-tree` (ANY symlink — file or dir — under `dist/**`, `dist` itself, a signed root file, or ANY entry at the checkout root); `special-file-in-tree` (FIFO / socket / device anywhere in the same places — a FIFO named `dist/publishers.js` shadows the signed `dist/publishers/` dir and blocks or executes whoever opens it); `foreign-modules` (a `node_modules` dir at the root or under `dist/`, matched case-insensitively). `verifyCommunityRelease` lstats `release.json` before opening it (a FIFO planted there used to hang the verifier). The hasher THROWS `ReleaseTreeError` on a special entry rather than skipping it; `signCommunityRelease` refuses to sign such a tree. The signed payload is `"m0saic-community-release/v1\n<tag>\n<publishedAt>\n<treeSha256>\n"`. The CLI notice carries the detail for these reasons — `(foreign-modules: node_modules)`; for `special-file-in-tree` the CLI does NOT load the folder at all (an ordinary load provably hangs): notice + `❌ Refusing to use template repo` + exit 1.
+
+**Community deps.** The `@m0saic-dev/community-m` pack (the only `sharp` / `@twemoji/svg` user) was deleted as defunct on 2026-09-16; both left the community `package.json` and BOTH allowlists (`dep-allowlist.json` ↔ `TEMPLATE_REPO_DEP_ALLOWLIST`, lockstep-tested). Community templates may import only what the hosts ship: `@m0saic/{types,template-utils,dsl-stdlib,platform,dsl}` + `node:path`. A native or third-party runtime dep is a founder decision. `sharp` survives only as a root devDependency for core/templates tests.
+
+**Accepted residual.** A third-party `--template-repo` checkout with its own `node_modules` runs its own copies of non-`@m0saic` deps — third-party code, with the notice printed; it cannot obtain a reserved identity that way (adversary-verified). DEV builds (`M0SAIC_DEV=1`, compile-stripped from the tarball) still trust an unsigned checkout for `missing-release` / `missing-signature` only; a tampered or forged tree is refused even in dev.
+
+## Wireframe commands
+
+`make-wireframe` / `make-wireframe-animated` take the layout as `--m0 <string>`
+(inline DSL — the flag is `--m0`, not `--m0saic`) or `--mfile <path>`, plus the
+same core/save/report/`--m0v`/`--output-pattern` surface as `make` (no encode
+surface, no `--inputs`). Animated adds `--disable-ui` (index.ts:~4504).
+
+## `m0saic open` — pointer only
+
+The canonical protocol (candidate file naming, agent block, iteration ritual,
+`--template` hot-reload loop) lives in
+[https://github.com/m0saic-project/m0saic-sandbox/blob/main/packages/sandbox/agent.md](https://github.com/m0saic-project/m0saic-sandbox/blob/main/packages/sandbox/agent.md) — read that,
+not this. Shape only: `open <file>` accepts `.m0 .m0c .m0p .m0v .mosaic
+.mosaicx` and routes to Mosaic Desktop (auto-detects a running dev electron on
+macOS; `--app <path>` override); `open --template <id> [--props/--props-file]`
+opens the Make page via the loopback bridge, hot-reloading fresh
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/dist first (`--no-reload` to skip); `open --make
+<file.mosaicx>` opens an authored `.mosaicx` in Make and adopts it for the
+agent loop.
+
+## `m0saic mcp` — the agent surface (2026-09-25)
+
+MCP has three primitives; this server implements **tools** only (model-invoked).
+Transport is newline-delimited JSON-RPC 2.0 over stdio, hand-rolled in
+`src/mcp/server.ts` (~230 lines, **zero runtime deps**: the official SDK carries
+17, including express, hono, cors, jose and ajv, and the CLI vendors its whole
+closure into the published tarball). `initialize` echoes the client's
+`protocolVersion`; a tool that throws returns `isError: true` rather than a
+JSON-RPC error, so the model sees the failure instead of the transport eating it.
+
+The 21 tools (`src/mcp/tools.ts`; the list is locked in `tools.test.ts`), in four groups:
+
+- **Knowledge** — `knowledge_list`, `knowledge_read`, `knowledge_search`. The
+  `@m0saic/knowledge` docs, so an agent reads the handbook instead of guessing.
+- **Local, no app needed** — `list_templates`, `template_props`, `validate_m0`,
+  `workspace_scaffold`, `render_still`, `doctor`.
+- **Through the loopback bridge into a running Desktop — the authoring loop** —
+  `desktop_status` (also says which flow you are in: `in-the-room`, a shell
+  Desktop's Agent panel opened, or `ecosystem`), `desktop_open_in_make` (open a
+  template for review — this resets the person's session on it),
+  `desktop_reload_sources`, `desktop_read_verdict` (takes a template id, or the
+  path of a forked `.mosaic`; surfaces `srcMosaic` + `geometryEdits`).
+- **The live canvas (0.3.1)** — see it: `desktop_layout` (the template, every
+  tile's bound prop and shown value, the current bag with `changedKeys`, the
+  modes; `detail`, `tileId`, `prop`), `desktop_snapshot` (a PNG on disk); act
+  through Make's own handlers: `desktop_set_props` (THE way to change a prop —
+  one undoable write, "Agent changed …"), `desktop_select_tile`,
+  `desktop_make_control` (reveal, camera, undo/redo, view, preview mode, canvas,
+  tile card, studio, cover, hover, tile override); branch when the template has
+  no knob: `desktop_fork_to_document` (a plain `.mosaic` + its m0),
+  `desktop_open_file`, `desktop_edit_geometry` (a pending ghost the person
+  applies). Behaviour and etiquette: [`agent-at-the-canvas.md`](agent-at-the-canvas.md);
+  the wire: `docs/compat-bridges.md` (0.3.1 routes).
+
+Three rules the implementation enforces:
+
+- **`render_still` pins `M0SAIC_CLI=/usr/bin/false`.** `@m0saic/benchmark/run/v1`
+  re-invokes `argv[1]`; without the pin a render from inside the CLI fork-bombs.
+- **Failures return a HINT, never raw stderr** (`findFailureHint`). Engine text is
+  moat: the argv and the filtergraph never cross to a model.
+- **The act routes never focus or restore the window**, and every live-canvas verb
+  runs the handler a click would — Desktop's main process sanitises the verb and
+  its args inbound and rebuilds every result from an allow-list outbound
+  (`electron/makeAgent.js`), so nothing an agent polls can carry a plan, an argv
+  or a filtergraph.
+
+`src/mcp/bridgeClient.ts` is the transport for the desktop tools. A 404 means
+`route-missing` — "this Desktop is too old for that route" — not "the app is
+down"; the compat warning prints once per process. The full route table is
+`docs/compat-bridges.md`.
+
+**`--agent-note` / `--agent-question` are PUBLIC** as of this line (the DEV_MODE
+strip is gone and `__tests__/cli.surface.test.js` asserts they appear in the
+published help — the lock was inverted, not removed). With `--template` they seed
+a note / question into Make's File tab for the reviewer to answer.
+
+## `m0saic doctor` answers a VERSIONED question (2026-09-25)
+
+Conventions change, so "does this repo pass?" is the wrong question — the right one is **which line
+does it pass at.** `report.conventions` carries it:
+
+```
+conventions: meets 0.2.0 (shipped at 0.2.0).
+  behind 0.3.0: bindingsDeclared, canvasFill
+  9 of 96 template(s) behind — a vN+1 on each clears it.
+```
+
+- **`meets`** — the newest m0saic line every template in the repo satisfies (error severity only; a
+  `record` warning is advice, not a failure to meet a line).
+- **`behind`** — the lines it does not meet, with the rules that fail, oldest first.
+- **`shippedAt`** — the repo's own `frozen.manifest.json` `release`.
+- **`target`** — the repo's `repo.conventions` (e.g. `"0.3.1"`, 0.3.1): the line whose rules it has
+  adopted. Each template is held to the LOWER of its shipped line and the target; rules introduced after
+  that are lag ("behind"), never errors. A repo moves its target when its templates have adopted the
+  newer rules — like a crate's edition. Absent: held to every rule this CLI knows. A malformed target is
+  a load warning (`CONVENTIONS_TARGET`); one newer than the CLI knows is a note. The summary line reads
+  `conventions: meets 0.3.0 (targets 0.3.0).` and a lagging template says *"the repo targets 0.3.0:
+  behind on catalogSidecar — not a defect, adopt them, then move repo.conventions."*
+- **`lagOnly`** — true when EVERY failure comes from a line newer than `shippedAt`. The footer then
+  says so explicitly: *"Not a defect: these templates met the conventions of their day. Fix at the
+  next vN."*
+
+**A template is allowed to lag.** It met the conventions of its day; the rules moved; the fix is its
+next `vN`. **A repo is allowed to target an older line too** (`repo.conventions`): a new m0saic release
+never turns its build red — the freeze protects what shipped, the target protects a repo with no freeze
+(every third-party repo). What the rules guarantee is that **NEW** templates meet the CURRENT line — which is why the
+postures throw (founder: "we need to be greedy about adding conventions because agents, especially
+non-frontier ones, won't"). The exit code is still 1 on any error, because the status is informational
+and the message carries the meaning.
+
+`TEMPLATE_CONVENTION_SINCE` in `@m0saic/template-utils` is the map of rule → line. Everything
+pre-0.3.0 reads `0.2.0`: at that freeze the whole shipped fleet passed every rule then in force, so it
+is a true lower bound rather than a guessed date.
+
+## Failure modes
+
+- `spawnSync m0saic EACCES` — the CLI isn't built/linked on this machine:
+  `cd the CLI source (not published) && npm run build && npm link`.
+- No ffmpeg at all → `ffmpeg isn't detected.` (4 lines), exit 1, nothing
+  downloaded (`ensureRenderToolchain()`, index.ts ~404); run `m0saic setup`
+  (`npx m0saic setup` under npx), then re-run. A broken golden slot prints
+  `❌ Toolchain "gpl" (golden) is broken … Re-install it:  m0saic setup --gpl`.
+- Free tier re-encodes every deliverable (QR stamp wrap) — codecs/durations
+  change, breaking probe-based assertions. Check `npm run tier:status` first;
+  full rule in the maintainers' agent contract §7.7 (not published).
+- Non-zero ffmpeg exits print a core-computed failure classification after the
+  exit-code line (`printFfmpegFailure`, index.ts:~113) — read it before rerunning
+  with `--verbose`.
+- Invalid m0 strings fail fast at validation (`validateM0String`), not inside
+  ffmpeg; `SPLIT_EXCEEDS_AXIS` means the split count exceeds the pixel axis —
+  see `docs/handbook/feasibility-precision-quantization.md`.

package/node_modules/@m0saic/knowledge/docs/runtime/ffmpeg-expression-limits.md

@@ -0,0 +1,117 @@
+# FFmpeg Expression Limits — the parse-depth cliff (a phantom "OOM")
+
+**Source of truth:** `rebalanceAdditiveChains` in
+[https://github.com/m0saic-project/m0saic-packages/blob/main/packages/platform/src/ffexpr/balance.ts](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/platform/src/ffexpr/balance.ts)
+(`DEFAULT_MAX_FLAT_ADDITIVE_TERMS = 32`); the funnels that apply it —
+`quoteEnableArg` in [https://github.com/m0saic-project/m0saic-packages/blob/main/packages/platform/src/ffexpr/ffmpeg.ts](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/platform/src/ffexpr/ffmpeg.ts),
+`buildOverlayAlphaFilter` + `buildCameraFilters` in `@m0saic/core`.
+Verified against BtbN ffmpeg `N-124278-gcc3ca17127-20260430` (the pinned GPL build).
+
+> Companion mental model: [`../skills/more-atoms-not-bigger-atoms.md`](../skills/more-atoms-not-bigger-atoms.md).
+> This doc is the measured case study; that one is the general principle.
+
+---
+
+## The symptom (and why it lies)
+
+FFmpeg's expression parser (`av_expr_parse`, `libavutil/eval.c`) has a **fixed
+recursion budget (~100)**. When an emitted expression exceeds it, filtergraph
+init fails with:
+
+- **`Error initializing filters / Error : Cannot allocate memory` (−12)** — a
+  **phantom OOM**: deterministic, ~60 ms, completely independent of free RAM.
+  This is the additive-chain shape.
+- or **`Missing ')' or too many args` → `Invalid argument` (−22) /
+  `Error reinitializing filters`** — the deeply-nested shape (e.g. a `crop`
+  focus expr).
+
+The word "memory" is a lie. It is NOT commit pressure, graph size, filter
+count, or a platform difference — all of which this failure repeatedly (and
+expensively) misled debugging toward. It is one expression too deep.
+
+## The cliff (measured, term-count-driven — NOT chars)
+
+- A **flat `a+b+c+…` chain fails at exactly 99 terms** (98 parses, 99 fails).
+  Character length is irrelevant: a 3.8 K-char / 98-term expr parses; a
+  2.3 K-char / 99-term expr fails.
+- **Genuine nesting** (nested `if(cond,…,else)` chains) fails at ~100 levels.
+- Because ffmpeg spends one recursion level **per additive term at the same
+  nesting level**, both shapes share the same ~100 budget.
+
+## The two shapes → the two fixes
+
+1. **Flat additive chains** (`enable` window sums, the `overlay.enable`→`geq`
+   alpha fold, camera zoom/focus). Fixable by REGROUPING the same terms into a
+   **balanced binary tree** — `((a+b)+(c+d))…` — which keeps parse depth
+   O(log N) and is safe past 1024 terms. This is `rebalanceAdditiveChains`.
+2. **Deep nesting** (one nested `if()` level per keyframe). Rebalancing CANNOT
+   help — the builder must **emit a flat shape instead**. dsl-tutorial's camera
+   `focusExpr` was rewritten from nested `if(lt(t,…),…, else)` (depth 109 at
+   10×10) to a **flat sum of disjoint window-gated smoothstep segments**
+   (`lt` head + `gte·lt` segments + `gte` tail).
+
+## Authoring rule
+
+**No flat additive chain longer than ~32 terms, and no piecewise-over-time
+expression built as a nested if-else chain, should ever reach a filtergraph.**
+Build piecewise-in-time values as **flat gated sums**; long chains are
+auto-rebalanced at the engine funnels below.
+
+## Engine enforcement (shipped 2026-07-02 — route new work through these)
+
+`rebalanceAdditiveChains` (`@m0saic/platform` `ffexpr/balance.ts`, threshold
+`DEFAULT_MAX_FLAT_ADDITIVE_TERMS = 32`) is applied automatically at every
+expression funnel:
+
+- `quoteEnableArg` — ALL `:enable='…'` sites (overlay, drawtext,
+  `compileEnableArg`).
+- `buildOverlayAlphaFilter` — the `overlay.enable` → `geq` alpha fold.
+- `buildCameraFilters` — zoom/focus chains.
+
+Chains **≤ 32 terms pass through byte-identical** (goldens unaffected); only
+longer chains are regrouped. Rebalancing fixes PARSE; it does not change eval
+cost (see below).
+
+**Known bypasses to watch:** hand-rolled lavfi strings that build `enable=`
+outside the funnels — dsl-string caret-track `drawbox`, dsl-canvas `drawbox`
+(both currently ≤3-term chains, safe) — and any template that still builds a
+nested-`if` expression (e.g. a line-chart animation) which will hit the cliff
+if its dataset grows. Keep per-filter chains small, or call
+`rebalanceAdditiveChains` before joining.
+
+## The "graph-SIZE OOM" was this cliff wearing a trench coat (debunked)
+
+A separate ≈130 K-chars / 9 000-filters "graph-size OOM" mode was once believed
+to exist, and a `splitByGraphBudget` chunker was calibrated against it. **It does
+not reproduce.** Direct verification:
+
+- The exact 142 K canvas part it was calibrated on renders standalone at full
+  duration; so do a **12 000-chained-drawbox / 1.19 MB single graph** and a
+  9 000-filter graph.
+- Every recorded failure sidecar in `smokebatch/` (smoke9–29) is a command
+  whose EXPRESSIONS cross the parse cliff (flat ≥99 or nesting ≥109), failing in
+  <80 ms with −12/−22. **No sidecar ever names a size-heavy command.**
+
+Graph chars merely *correlated* with expression bulk in that era's graphs. The
+graph-size chunker was reverted. **Do not re-add a filtergraph-size split
+chasing a "size OOM" — it is the parse cliff.** (The input-count split,
+`maxInputsPerCommand`, is a separate and real argv/process-arg constraint and
+stays.)
+
+## Note: the macOS "grind" is a different wall
+
+The same dense graphs that fail fast on Windows (parse cliff) instead ran for
+20+ min on macOS. That was NOT the parse cliff (Mac's ffmpeg parses flat chains
+fine) — it was **per-pixel `geq` eval cost** (O(terms) per pixel per plane per
+frame). Rebalancing does not reduce it; density caps like `PULSE_TERM_CAP` and
+representational fixes (SVG masks, pre-rendered intermediates) do. That's a
+perf ceiling, not a crash — see the "more atoms" skill, atom 2.
+
+There is also a *third*, mechanically distinct macOS wall on
+conversion-/input-dense graphs (many `scale`/`format` nodes + many still
+inputs, e.g. dsl-tutorial grids): **swscale thread-cap exhaustion**, where
+per-conversion thread pools blow past `kern.num_taskthreads` and frames freeze
+at t=0 or grind at ~1 fps. That one is neither parse depth nor `geq` eval cost —
+that wall is engine-internal: `.ai/moat/runtime/macos-swscale-thread-cap.md`
+(absent in the shipped copy; symptom summary: dense still-image canvases freeze
+at t=0 / grind ~1 fps on macOS — the engine's threadGuard mitigates it).