@mostra/cli 0.0.0-stage → 0.2.0

package/dist/reference/errors/MOSTRA_CLI_USAGE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_CLI_USAGE
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_CLI_USAGE
+
+Command used wrongly. Severity: error. Phase: host.
+
+## What it means
+
+The command line didn't fit the command's definition: a missing or extra argument, an unknown flag, a flag without its value, or a value of the wrong form (a duration, a number, JSON). Nothing ran. In `--json` mode the error is the envelope's `error`, and the exit code is 2.
+
+## How to fix it
+
+Read `mostra <command> --help` (or `--help --json` for the machine-readable definition) and correct the arguments.
+
+## Hint
+
+Run `mostra <command> --help` for the command's arguments and flags, then run it again.

package/dist/reference/errors/MOSTRA_CONSOLE_ERROR.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_CONSOLE_ERROR
+severity: error
+phase: console
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_CONSOLE_ERROR
+
+Error logged to the console. Severity: error. Phase: console.
+
+## What it means
+
+The page logged an error with `console.error` while verify rendered it or used its controls. Errors caught by React error boundaries, the root's included, are logged this way. A viewer's page would log the same.
+
+## How to fix it
+
+Read the message and fix its cause in the artifact's code. Errors logged by a library usually name what it was given.
+
+## Hint
+
+Fix what the logged error describes; React logs errors its boundaries catch here too.

package/dist/reference/errors/MOSTRA_CONSOLE_WARNING.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_CONSOLE_WARNING
+severity: hint
+phase: console
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_CONSOLE_WARNING
+
+Warning logged to the console. Severity: hint. Phase: console.
+
+## What it means
+
+The page logged a warning with `console.warn`. Warnings are often a library's advice, so they are hints.
+
+## How to fix it
+
+Nothing is required.
+
+## Hint
+
+Read the warning; nothing is broken by it.

package/dist/reference/errors/MOSTRA_DEP_INSTALL_FAILED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_DEP_INSTALL_FAILED
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_DEP_INSTALL_FAILED
+
+Package install failed. Severity: error. Phase: compile.
+
+## What it means
+
+The package installer failed for a reason other than a missing package or the network: most often a package's lifecycle script (`preinstall`, `install`, `postinstall`) exited with an error, or a downloaded package didn't match its integrity hash. Lifecycle scripts run in an install child in the artifact's directory with the artifact's environment. The message carries the end of the installer's output.
+
+## How to fix it
+
+Fix what the output names. For a failing install script, check what it needs (a compiler, a system library) or use another version of the package.
+
+## Hint
+
+Read the installer's output in the message, then fix the package spec or choose another version.

package/dist/reference/errors/MOSTRA_DEP_MISSING.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_DEP_MISSING
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_DEP_MISSING
+
+Package not added. Severity: error. Phase: compile.
+
+## What it means
+
+The artifact imports a package that is neither in Mostra's warm set nor in the artifact's lockfile, and the host has set the dependency policy to `explicit`. Under that policy a package enters an artifact's lockfile only when it is added on purpose, so Mostra installs nothing on its own. The location points at the first import of the package, and the fix carries the exact command that adds every missing package.
+
+## How to fix it
+
+Run the command from the fix (`mostra add <package…> --artifact <path>`, or the host protocol method `deps/add`), then publish again. To use a package from the warm set instead, change the import.
+
+## Hint
+
+Run the `mostra add` command in this diagnostic's fix, then publish again.

package/dist/reference/errors/MOSTRA_DEP_NOT_FOUND.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_DEP_NOT_FOUND
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_DEP_NOT_FOUND
+
+Package not found. Severity: error. Phase: compile.
+
+## What it means
+
+The registry has no package by that name, or no version that matches the requested one. A spec without an exact version only matches releases at least a day old, so a package whose every release is newer than that isn't found either. The message names the package and what the registry answered.
+
+## How to fix it
+
+Correct the package name in the import or in the `mostra add` spec. To use a release less than a day old, add it at its exact version: `mostra add <package>@<version>`.
+
+## Hint
+
+Check the package name and version against the npm registry, then fix the import or the spec.

package/dist/reference/errors/MOSTRA_DEP_OFFLINE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_DEP_OFFLINE
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_DEP_OFFLINE
+
+Package unavailable offline. Severity: error. Phase: compile.
+
+## What it means
+
+Mostra is offline (`MOSTRA_OFFLINE` is set, no network interface is up, or the registry can't be reached), and the artifact needs a package that the home's package store doesn't hold yet. Everything the store holds keeps working offline, including rebuilds of published versions. The message names the missing package.
+
+## How to fix it
+
+Publish again once the registry is reachable; the package then stays in the store for later offline use. Otherwise remove the import, or use a package from the warm set.
+
+## Hint
+
+Connect to the network and publish again, or import a package the home already holds.

package/dist/reference/errors/MOSTRA_DEP_SPEC_INVALID.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_DEP_SPEC_INVALID
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_DEP_SPEC_INVALID
+
+Invalid package spec. Severity: error. Phase: host.
+
+## What it means
+
+A package spec given to `mostra add` (`deps/add`) isn't an npm registry spec. Mostra adds packages from the registry by name, optionally with a version, a semver range or a dist-tag; scoped names such as `@scope/name@1.2.3` work too. Git URLs, local paths and tarball URLs aren't registry specs.
+
+## How to fix it
+
+Correct the spec, for example `mostra add three@0.186.1` or `mostra add @xyflow/react`.
+
+## Hint
+
+Write the spec as `name`, `name@version`, `name@range` or `name@tag`.

package/dist/reference/errors/MOSTRA_DEP_TIMEOUT.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_DEP_TIMEOUT
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_DEP_TIMEOUT
+
+Package install timed out. Severity: error. Phase: compile.
+
+## What it means
+
+Installing the artifact's packages took longer than 300 seconds and was stopped. A slow registry, a stalled download or a lifecycle script that never ends are the usual causes. Nothing was published, and packages already in the store stay there.
+
+## How to fix it
+
+Publish again; packages that finished downloading aren't fetched twice. When a package's install script hangs, use another version of the package or another package.
+
+## Hint
+
+Check the network and the registry, then publish again.

package/dist/reference/errors/MOSTRA_DEP_WARM_CONFLICT.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_DEP_WARM_CONFLICT
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_DEP_WARM_CONFLICT
+
+Warm package version requested. Severity: error. Phase: compile.
+
+## What it means
+
+The package is part of Mostra's warm set, which every artifact resolves at one fixed version so that React and the other shared packages exist exactly once. The requested version doesn't match the warm one, and an artifact can't replace a warm package.
+
+## How to fix it
+
+Drop the version from the spec (`mostra add react`), or request a range the warm version satisfies. The message names the warm version.
+
+## Hint
+
+Add the package without a version, or with one the warm set's version satisfies.

package/dist/reference/errors/MOSTRA_ENV_BIND_FAILED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_BIND_FAILED
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_BIND_FAILED
+
+Gateway can't bind. Severity: error. Phase: host.
+
+## What it means
+
+The gateway couldn't listen on the address it was given: `--bind` named an address no interface has, a wildcard bind came without `--url-host`, or the operating system refused the address. Mostra doesn't start rather than serve on an address nobody asked for.
+
+## How to fix it
+
+Omit `--bind` to serve on `127.0.0.1` only (the default). For a wider bind, pass an address of one of this machine's interfaces, and with `0.0.0.0` or `::` also `--url-host <name>`, the name viewers use to reach it.
+
+## Hint
+
+Start Mostra with an address this machine has, or without `--bind` to use the loopback address.

package/dist/reference/errors/MOSTRA_ENV_BROWSER_MISSING.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_BROWSER_MISSING
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_BROWSER_MISSING
+
+Browser for verify missing. Severity: error. Phase: host.
+
+## What it means
+
+Verify renders pages in the Chromium headless shell its Playwright release pins. The runtime bundle fetches that browser when it is set up and checks every file of it (D142). It wasn't there, so verify ran only the stages that need no browser (type check, build and the field-ID scan) and reported this error. Publishing needs `--force` until it is installed.
+
+## How to fix it
+
+Run `bin/mostra-setup` in the runtime bundle's directory (the message names it) with network access; it fetches and checks the pinned browser. Outside a bundle, in a development checkout, run `npx playwright-core install chromium-headless-shell`. Then verify again.
+
+## Hint
+
+Run the runtime bundle's `bin/mostra-setup` (with network access) to fetch the browser verify uses, then verify again.

package/dist/reference/errors/MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED
+severity: error
+phase: platform
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED
+
+Runtime bundle download failed. Severity: error. Phase: platform.
+
+## What it means
+
+The runtime bundle for this release and platform isn't in the local cache yet, and fetching it failed: the network or a proxy refused it, the server answered with an error, the connection stalled for 60 seconds, or the disk ran out of space while it was written. Nothing partial is kept.
+
+## How to fix it
+
+Check the connection, and set `HTTPS_PROXY` (and `NO_PROXY`) when the network needs a proxy. Behind a firewall that blocks GitHub, host the release's files on a reachable server and set `MOSTRA_BUNDLE_MIRROR` to its base URL (a `file:` URL works for a local directory). Free space in the cache directory (`MOSTRA_CACHE_DIR`) if the message says the disk is full.
+
+## Hint
+
+Check the network or proxy (`HTTPS_PROXY`), then run the command again: a retry starts the download over.

package/dist/reference/errors/MOSTRA_ENV_BUNDLE_INVALID.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_BUNDLE_INVALID
+severity: error
+phase: platform
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_BUNDLE_INVALID
+
+Runtime bundle failed verification. Severity: error. Phase: platform.
+
+## What it means
+
+Mostra checks every runtime bundle before it runs anything from it: the archive against the SHA-256 the installing package pins, then each extracted file against the bundle's own file list, and the verify browser against the bundle's browser pin. One of them differed, so the download was corrupted, changed on the way or replaced, and Mostra refused it. A bundle already installed that fails a later check (`mostra doctor --deep`) is refused the same way.
+
+## How to fix it
+
+Run the install again (`npm create mostra`, or the command that started it), which downloads a fresh copy. When a mirror is configured (`MOSTRA_BUNDLE_MIRROR`), check that it serves the release's files unchanged. Check a file you downloaded yourself against the release's `SHA256SUMS`, or with `gh attestation verify <file> --repo mostra-dev/mostra`.
+
+## Hint
+
+Nothing was installed; install Mostra again, and if it fails the same way, report it with the message.

package/dist/reference/errors/MOSTRA_ENV_BUNDLE_UNAVAILABLE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_BUNDLE_UNAVAILABLE
+severity: error
+phase: platform
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_BUNDLE_UNAVAILABLE
+
+No runtime bundle available. Severity: error. Phase: platform.
+
+## What it means
+
+Mostra runs on its own runtime bundle, found in the local cache, beside the installed package or at `MOSTRA_BUNDLE`. None was there, and no download could start: Mostra is offline (`MOSTRA_OFFLINE`), this build of the package pins no bundle for this platform, or the platform has none.
+
+## How to fix it
+
+Run the command once with network access and without `MOSTRA_OFFLINE`, so the pinned bundle is fetched and cached; later runs work offline. On a machine without network access, extract the release's archive for the platform and set `MOSTRA_BUNDLE` to its directory. A development checkout uses its own built runtime instead.
+
+## Hint
+
+Run this once with network access, or point `MOSTRA_BUNDLE` at an extracted bundle.

package/dist/reference/errors/MOSTRA_ENV_NODE_UNSUPPORTED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_NODE_UNSUPPORTED
+severity: error
+phase: platform
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_NODE_UNSUPPORTED
+
+Node.js too old to start Mostra. Severity: error. Phase: platform.
+
+## What it means
+
+A `mostra` (or `npm create mostra`) installed from npm starts on the machine's Node.js only long enough to find its runtime bundle, then every Mostra process runs on the bundle's own Node.js (RT-01, D142). That start needs Node.js 22.19 or later, and this one is older, so Mostra stopped before loading anything.
+
+## How to fix it
+
+Upgrade the machine's Node.js to 22.19 or later, or run Mostra without npm: download the runtime bundle for your platform from the GitHub release, check it against `SHA256SUMS`, extract it, run its `bin/mostra-setup` once, then use its `bin/mostra`.
+
+## Hint
+
+Run `mostra` with Node.js 22.19 or later, or run the runtime bundle's own `bin/mostra`, which needs no Node.js.

package/dist/reference/errors/MOSTRA_ENV_PORT_TAKEN.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_PORT_TAKEN
+severity: warning
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_PORT_TAKEN
+
+Leased port taken. Severity: warning. Phase: host.
+
+## What it means
+
+The shell's port or an artifact's port is leased per home and reused across restarts, so links keep working (D62, D99). At start-up another program held the leased port, so Mostra leased a new one. Links that named the old port stop working; the shell's port changing affects every link of the home.
+
+## How to fix it
+
+Mint new links with `view/url` (the publish receipt of the next publish carries the new default link too). Stop the program that took the port if you want the old links back; `mostra doctor` names it where it can.
+
+## Hint
+
+Open the artifact through a new link: `view/url` or `mostra open` mints one on the new port.

package/dist/reference/errors/MOSTRA_ENV_RUNTIME_MISSING.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_RUNTIME_MISSING
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_RUNTIME_MISSING
+
+Runtime not found. Severity: error. Phase: host.
+
+## What it means
+
+The CLI starts and attaches to the home's instance through the runtime binary (`mostra-runtime`, D85). It looked, in order, for `MOSTRA_BUNDLE`, `MOSTRA_RUNTIME_BIN`, the runtime bundle it runs from, its release's pinned bundle and a development checkout's built runtime (D142), and found nothing it could run: here, `MOSTRA_RUNTIME_BIN` names a file that doesn't exist, or the runtime couldn't be started.
+
+## How to fix it
+
+Unset `MOSTRA_RUNTIME_BIN` or point it at a `mostra-runtime` entry (its `dist/bin.js`), or reinstall Mostra so the CLI and its runtime are complete.
+
+## Hint
+
+Reinstall Mostra, or set `MOSTRA_RUNTIME_BIN` to the runtime's `mostra-runtime` entry.

package/dist/reference/errors/MOSTRA_ENV_SERVICE_FAILED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_SERVICE_FAILED
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_SERVICE_FAILED
+
+Login service could not be installed. Severity: error. Phase: host.
+
+## What it means
+
+`mostra daemon install` couldn't register the home's daemon as a login service: writing the launchd agent or systemd user unit failed, or `launchctl` or `systemctl --user` refused to load it.
+
+## How to fix it
+
+Check the named file's directory permissions, and on Linux that a systemd user session is running (`systemctl --user status`). On a machine without one, start the daemon from your own login scripts with `mostra daemon start`.
+
+## Hint
+
+Read the message, fix what it names, and run the install again.

package/dist/reference/errors/MOSTRA_ENV_SHELL_MISSING.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_SHELL_MISSING
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_SHELL_MISSING
+
+Shell app missing. Severity: error. Phase: host.
+
+## What it means
+
+Viewers open artifacts inside the shell, Mostra's trusted page, which ships with the runtime as built files. The runtime couldn't find them, which means the runtime installation is incomplete. Artifact frames are still served.
+
+## How to fix it
+
+Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the shell's built directory with `MOSTRA_SHELL_DIR`.
+
+## Hint
+
+Reinstall the Mostra runtime, or set `MOSTRA_SHELL_DIR` to its built shell.

package/dist/reference/errors/MOSTRA_ENV_WARM_MISSING.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ENV_WARM_MISSING
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ENV_WARM_MISSING
+
+Warm package set missing. Severity: error. Phase: host.
+
+## What it means
+
+Builds resolve React, Tailwind and Mostra's own client packages from the warm package set that ships with the runtime. The runtime couldn't find it, which means the runtime installation is incomplete.
+
+## How to fix it
+
+Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the warm set's directory with `MOSTRA_WARM_DIR`.
+
+## Hint
+
+Reinstall the Mostra runtime, or set `MOSTRA_WARM_DIR` to its warm package set.

package/dist/reference/errors/MOSTRA_FIELD_CONFLICT.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_FIELD_CONFLICT
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_FIELD_CONFLICT
+
+Field changed by another writer. Severity: error. Phase: runtime.
+
+## What it means
+
+Every write names the revision it was based on, and a field changed after it is a conflict, never overwritten silently (D22). `window.storage` writes end with the last write: on a conflict it writes again over the newer value, a few times. When another writer kept changing the field each time, the write is refused with this code, and the field keeps the other writer's value.
+
+## How to fix it
+
+Read the key again and write the new value. For a counter or a list that many viewers change at once, store each viewer's part under its own key (`votes.<viewer>`) and combine them when reading.
+
+## Hint
+
+Read the value again, then write it; for a value several writers change often, give each writer a field of its own.

package/dist/reference/errors/MOSTRA_FIELD_DUPLICATE_ID.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_FIELD_DUPLICATE_ID
+severity: error
+phase: lint
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_FIELD_DUPLICATE_ID
+
+Field ID used for two different fields. Severity: error. Phase: lint.
+
+## What it means
+
+One field ID is used for two different fields: with two hook kinds (`useField` and `useChoice`, say), two scopes (`viewer` and `artifact`), or initial values of two types. The two would overwrite each other's saved value. The same ID used the same way twice is a deliberately shared value and isn't reported here.
+
+## How to fix it
+
+Rename one of them, for example `notes` and `notes.summary`, so each persisted value has its own ID.
+
+## Hint
+
+Give each of these fields its own ID.

package/dist/reference/errors/MOSTRA_FIELD_ID_INVALID.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_FIELD_ID_INVALID
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_FIELD_ID_INVALID
+
+Invalid field ID. Severity: error. Phase: runtime.
+
+## What it means
+
+Every persisted value has an explicit, stable field ID (D52). An ID is 1 to 256 characters with no control characters; dots separate the parts that nest in results (`reply.m1`), so it can't start or end with a dot or hold two in a row.
+
+## How to fix it
+
+Give the field a fixed ID such as `layout` or `reply.m1` (one per message, from its ID), and keep it the same across renders and versions so drafts carry over.
+
+## Hint
+
+Use a stable field ID of 1 to 256 characters: dot-separated parts, none empty.

package/dist/reference/errors/MOSTRA_FIELD_ID_UNSTABLE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_FIELD_ID_UNSTABLE
+severity: error
+phase: lint
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_FIELD_ID_UNSTABLE
+
+Field ID changes between renders. Severity: error. Phase: lint.
+
+## What it means
+
+Verify loaded the page twice with identical inputs and a fixed clock, and a field ID differed between the two loads. A viewer's saved answer would then be lost on every reload. IDs an interaction creates, such as a new list row's, are new fields and aren't reported.
+
+## How to fix it
+
+Derive the ID from something stable, for example a template with the record's ID instead of one with `Math.random()`.
+
+## Hint
+
+Build the field's ID from stable data, such as a record's ID, never from random numbers or the time.

package/dist/reference/errors/MOSTRA_FIELD_MUTATION_ID_REUSED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_FIELD_MUTATION_ID_REUSED
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_FIELD_MUTATION_ID_REUSED
+
+Mutation ID reused. Severity: error. Phase: runtime.
+
+## What it means
+
+A mutation ID identifies one change, so a retry after a timeout replays its recorded result (IN-01). This ID was already used for a change with other contents or another target. Mostra refuses it rather than answer with the result of a change nobody sent now.
+
+## How to fix it
+
+Create a fresh `mut_` ID for each change and reuse an ID only to retry exactly the same change.
+
+## Hint
+
+Generate a new mutation ID for every new change.

package/dist/reference/errors/MOSTRA_FIELD_SHARED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_FIELD_SHARED
+severity: hint
+phase: lint
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_FIELD_SHARED
+
+Field ID shared by several controls. Severity: hint. Phase: lint.
+
+## What it means
+
+Several mounted components use one field ID in the same way, so they all edit one saved value. That is how a value is shared deliberately; in a list, it can also mean every row edits the same answer.
+
+## How to fix it
+
+If each row should keep its own answer, include the row's identity in the ID, such as a template that adds the task's ID after `done.`.
+
+## Hint
+
+Nothing to fix if these controls are meant to edit one value; give each its own ID if not.