@mostra/cli 0.0.0-stage → 0.2.0

package/dist/reference/diagnostics.json

@@ -0,0 +1,1264 @@
+{
+  "codes": [
+    {
+      "code": "MOSTRA_A11Y_MINOR",
+      "severity": "hint",
+      "phase": "a11y",
+      "title": "Minor accessibility problem",
+      "hint": "Read axe's description of the rule in the message.",
+      "explanation": "axe-core found a problem it rates moderate or minor. The message names axe's rule and the elements.",
+      "fix": "Optionally follow the rule's advice."
+    },
+    {
+      "code": "MOSTRA_A11Y_SERIOUS",
+      "severity": "warning",
+      "phase": "a11y",
+      "title": "Serious accessibility problem",
+      "hint": "Read axe's description of the rule in the message; it names the elements it found.",
+      "explanation": "axe-core found a problem it rates critical or serious, such as a button with no accessible name or text with too little contrast. The message names axe's rule and the elements; `count` says how many.",
+      "fix": "Follow the rule's advice for each element named, for example add an `aria-label` to an icon button."
+    },
+    {
+      "code": "MOSTRA_ACTION_CANCELLED",
+      "severity": "warning",
+      "phase": "runtime",
+      "title": "Action run cancelled",
+      "hint": "Start the action again if it should still run.",
+      "explanation": "The action run was cancelled from a page, and its `abortSignal` fired. The run ends `cancelled` when the action stops; an action that ignores the signal ends with whatever it returns.",
+      "fix": "Nothing to fix. Pass `abortSignal` from `@mostra/server` to `fetch` and other cancellable calls so cancelling stops the work."
+    },
+    {
+      "code": "MOSTRA_ACTION_EVENT_INVALID",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Host event type or payload invalid",
+      "hint": "Name the event `host.<name>` with 1 to 64 letters, digits, `.`, `_` and `-`, and keep its payload JSON of at most 64 KiB.",
+      "explanation": "Server code called `emit(type, payload)` from `@mostra/server` with a type that isn't `host.` followed by a name, or a payload that isn't JSON or is larger than 64 KiB. The event is not appended; `emit` throws.",
+      "fix": "Use a type such as `host.reply-sent` and a small JSON payload. Put larger data in artifact state or a live source and send its key in the event."
+    },
+    {
+      "code": "MOSTRA_ACTION_EXPORT_INVALID",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Server module exports something other than an async function",
+      "hint": "Export only async functions from a \"use server\" module; move other exports to an ordinary module.",
+      "explanation": "A module that starts with `\"use server\"` makes every export a server function the page can call. React's contract allows only async functions there. Mostra reports this code for any other export (a constant, a class, a non-async function, `export *`), naming the export.",
+      "fix": "Make the function `async`, or move the value to a separate module without the directive and import it from both sides."
+    },
+    {
+      "code": "MOSTRA_ACTION_INTERRUPTED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Action run interrupted",
+      "hint": "Check the run's effects at their provider, then start it again with a new key if it should run again.",
+      "explanation": "The action run's worker crashed, ran out of memory, was stopped by the event-loop watchdog, or the instance stopped while the run was running. The run ends `failed` with the reason `interrupted`, and Mostra never retries it by itself (D24): an action that had already started a side effect, such as sending an email, may or may not have finished it.",
+      "fix": "Look at the effect where it happens (the mail provider's sent folder, say) before running the action again. Pass the provider's own idempotency key from the action (for example, the run's key) so a repeated request can't act twice."
+    },
+    {
+      "code": "MOSTRA_ACTION_RUN_NOT_FOUND",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "No such action run",
+      "hint": "Start the action again; the run ID names no run of this artifact.",
+      "explanation": "A page asked for or cancelled an action run that this artifact doesn't have, or one started from another artifact.",
+      "fix": "Use the run IDs `useAction` reports. A page that keeps run IDs itself should drop IDs from other artifacts."
+    },
+    {
+      "code": "MOSTRA_ACTION_THREW",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Server function threw",
+      "hint": "Read the run's log for the stack, then fix the server function or catch the error and return a result instead.",
+      "explanation": "A server function threw while it ran. The page gets `{ code: \"MOSTRA_ACTION_THREW\", message }` with the thrown error's message (`useAction`'s `error`, or the rejected promise of a plain call); the stack goes to the action run's log, never to the page. When the error carried a diagnostic code of its own (a `MOSTRA_SECRET_MISSING`, say), that code is reported instead.",
+      "fix": "Fix the cause in the function, or catch the error inside it and return a value the page can show. Mostra never retries a run by itself (D24); retry in your own code, or call the action again with a new key."
+    },
+    {
+      "code": "MOSTRA_ACTION_TOO_LARGE",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Server function arguments or result too large",
+      "hint": "Return or pass less data: page through it, or write it to artifact state or a live source instead.",
+      "explanation": "A server function's serialized arguments, or an action run's serialized result, is over 16 MiB. A plain call or run with arguments that large is refused before it starts; a run whose result grows past the limit is stopped and ends `failed`.",
+      "fix": "Send identifiers rather than whole documents, return a page of results at a time, or publish large data through a live source or artifact state, which the page reads on its own."
+    },
+    {
+      "code": "MOSTRA_ACTION_UNKNOWN_FUNCTION",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "No such server function in this version",
+      "hint": "Publish the artifact again so the page and its server code come from the same version.",
+      "explanation": "The page called a server function ID (`<module path>#<export>`) that the version's server bundle doesn't export. Pages call only functions their own build references, so this means a page and a worker of different versions, or a request written by hand.",
+      "fix": "Republish the artifact and reload the page. Call server functions by importing them from their `\"use server\"` module, never by ID."
+    },
+    {
+      "code": "MOSTRA_ACTION_UNSERIALIZABLE",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Server function argument or result outside React's serializable types",
+      "hint": "Pass and return only plain objects, arrays, primitives, Map, Set, Date, typed arrays, FormData and promises; convert class instances to plain objects first.",
+      "explanation": "Server function arguments and results cross a process boundary, so Mostra accepts exactly the types React documents for Server Functions (D54): strings, numbers, bigints, booleans, `undefined`, `null`, symbols registered with `Symbol.for`, arrays, `Map`, `Set`, typed arrays, `ArrayBuffer`, `Date`, `FormData`, plain objects, other server functions and promises. A result may also be an async iterable, whose items stream to the page. Mostra reports this code for anything else (a class instance, an `Error`, a `RegExp`, an object with a null prototype, a function that isn't a server function, an unregistered symbol, JSX) and names where in the value it is, such as `Argument 2 at .items[1]`. A promise in an argument that rejects fails the call the same way.",
+      "fix": "Convert the value to the supported types before the call or the return: `{ ...instance }` or a mapping for class instances, `error.message` for errors and `regexp.source` for regular expressions."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_DIR_NOT_EMPTY",
+      "severity": "error",
+      "phase": "host",
+      "title": "Directory isn't empty",
+      "hint": "Choose a new or empty directory for the artifact.",
+      "explanation": "Creating an artifact writes its entry into a directory, and the directory given already has files. Mostra never overwrites them.",
+      "fix": "Pass a path that doesn't exist yet or an empty directory. To make existing files an artifact, add the entry yourself and publish."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS",
+      "severity": "error",
+      "phase": "manifest",
+      "title": "More than one entry file",
+      "hint": "Keep one entry file in the directory and rename or remove the others.",
+      "explanation": "A directory artifact has exactly one entry, and this directory has more than one of `index.tsx`, `index.jsx` and `index.mdx`, so Mostra can't tell which one is the page.",
+      "fix": "Keep the entry you mean and rename the others, for example into `components/`."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_NO_ENTRY",
+      "severity": "error",
+      "phase": "manifest",
+      "title": "No entry file",
+      "hint": "Add `index.tsx` or `index.mdx` to the directory, or publish a single `.tsx` or `.mdx` file.",
+      "explanation": "An artifact is a single `.tsx`, `.jsx` or `.mdx` file, or a directory whose entry is `index.tsx`, `index.jsx` or `index.mdx`. The source given is neither.",
+      "fix": "Create the entry: its default export is the page, and its manifest is `export const artifact = defineArtifact({ title: \"...\" })` (or frontmatter in MDX). For a single page, publish the file itself."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_NO_PAGE",
+      "severity": "error",
+      "phase": "manifest",
+      "title": "Entry has no page",
+      "hint": "Export the page component as the entry's default export, or add a `pages/` folder.",
+      "explanation": "The entry has no default export and the artifact has no `pages/` folder, so there is nothing to render. With `pages/`, each file there is a route and the entry's default export, when present, is the layout around them.",
+      "fix": "Add `export default function Page() { ... }` to the entry, or move pages into `pages/index.tsx`, `pages/settings.tsx` and so on."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_NOT_FOUND",
+      "severity": "error",
+      "phase": "host",
+      "title": "Artifact not found",
+      "hint": "Check the artifact ID or source path, or list the home's artifacts with `mostra list`.",
+      "explanation": "The artifact named by an ID or a source path doesn't exist in this home: the ID was never published here, or the path was never published.",
+      "fix": "Use an ID or path from `mostra list`. A source that was never published becomes an artifact at its first `mostra publish`. A host that uses its own home sees only the artifacts published there."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_SOURCE_MISSING",
+      "severity": "error",
+      "phase": "publish",
+      "title": "Artifact source missing",
+      "hint": "Publish from the artifact's source path, or restore the directory the message names.",
+      "explanation": "Publishing needs the artifact's source files. The path given, or the path the artifact was last published from, doesn't exist. Versions already published stay readable, because Mostra keeps a snapshot of their source in the home.",
+      "fix": "Pass the path where the source lives now. Its manifest `id`, if it has one, keeps the artifact identity at the new path."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_SOURCE_UNREADABLE",
+      "severity": "error",
+      "phase": "publish",
+      "title": "Artifact source can't be read",
+      "hint": "Fix the file or directory the message names so your user can read it, then publish again.",
+      "explanation": "Mostra couldn't read a file of the artifact's source: permissions, a file that disappeared while it was copied, or two names that are the same after Unicode normalization. Nothing was published.",
+      "fix": "Make the named file readable, rename one of two clashing names, or exclude the file with `.mostraignore` in the artifact's root."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN",
+      "severity": "error",
+      "phase": "host",
+      "title": "Unknown template",
+      "hint": "Create the artifact without a template, or use a template this Mostra release provides.",
+      "explanation": "The template named isn't one this runtime provides. Without a template, Mostra writes a minimal entry with a generated artifact ID.",
+      "fix": "Leave out the template, or use one of the templates of this release."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_VERSION_COLLECTED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Version collected",
+      "hint": "Open the artifact's latest version, or publish this version's source again to restore its files.",
+      "explanation": "`mostra gc` removed this version's files because nothing referenced it (D140). Its ID and number stay in the ledger forever, so history and events still name it, but it can't be opened or linked.",
+      "fix": "Open a version that still exists (`artifact/get` marks collected ones), or publish the exact source of this version again: publish restores its files under the same ID and number."
+    },
+    {
+      "code": "MOSTRA_ARTIFACT_VERSION_NOT_FOUND",
+      "severity": "error",
+      "phase": "host",
+      "title": "No such version",
+      "hint": "Name a version the artifact has (`artifact/get` lists them), or leave the version out for the latest.",
+      "explanation": "The request named a version number or version ID that this artifact never published in this home. Viewers only ever open published versions (D09), so there is nothing to show.",
+      "fix": "List the artifact's versions with `artifact/get` and pick one, or omit the version to open the latest. A link to `/a/<artifactId>/v/<number>` needs a number from that list."
+    },
+    {
+      "code": "MOSTRA_BUILD_CRASHED",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Builder crashed",
+      "hint": "Publish again; if it crashes again, report the builder's last output from the message.",
+      "explanation": "The builder child process exited before it finished, for example after running out of memory or on a signal. The supervisor and everything else in the instance keep working, and nothing was published. The message carries the builder's last lines of error output.",
+      "fix": "Run the publish again, which starts a fresh builder. A crash that repeats points at the artifact's size or at a defect in Mostra: very large inline data is better kept in `public/` or loaded through a live source."
+    },
+    {
+      "code": "MOSTRA_BUILD_FAILED",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Build failed",
+      "hint": "Fix the error at the reported location, then publish again.",
+      "explanation": "The builder couldn't bundle the artifact: a syntax error, an invalid JSX or MDX construct, a CSS error or another bundler error. The message carries the bundler's own explanation, and the location points at the file, line and column when the bundler reports one. Nothing was published.",
+      "fix": "Open the reported file at the reported line and fix the code there. For MDX, check that JSX in the document is closed and that `{` and `<` in prose are escaped. Run `mostra verify` to see the same error with the type checker's findings."
+    },
+    {
+      "code": "MOSTRA_BUILD_TIMEOUT",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Build timed out",
+      "hint": "Make the build smaller, for example by moving large data into `public/`, then publish again.",
+      "explanation": "The build took longer than its limit (180 seconds) and was stopped. Nothing was published.",
+      "fix": "Move large data files that are imported into code into `public/` and fetch them at run time, split very large modules, and remove unused imports of heavy libraries. Then publish again."
+    },
+    {
+      "code": "MOSTRA_BUILD_UNRESOLVED",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Import can't be resolved",
+      "hint": "Correct the import path, or import the package from the warm set or add it with `mostra add`.",
+      "explanation": "An import in the artifact names a file or package the builder can't find. Relative imports resolve inside the artifact's own files, `@/...` resolves from the artifact's root, and package imports resolve from Mostra's warm set and the artifact's installed packages. The message names the import and the file that contains it.",
+      "fix": "For a file, check the path and its extension against the artifact's files. For a package, check its name; packages outside the warm set install with `mostra add <package>`."
+    },
+    {
+      "code": "MOSTRA_CLI_CONFIG_UNWRITABLE",
+      "severity": "error",
+      "phase": "platform",
+      "title": "The CLI's config directory can't be written",
+      "hint": "Make the directory the message names yours and writable (or point MOSTRA_CONFIG_DIR at one that is), then run the command again; DO_NOT_TRACK=1 turns telemetry off without writing anything.",
+      "explanation": "`mostra telemetry on` and `off` record the choice in the CLI's config directory (`MOSTRA_CONFIG_DIR`, else `${XDG_CONFIG_HOME:-~/.config}/mostra`). The directory or its `telemetry.json` can't be written (another user owns it, the disk is full, it's read-only), so the choice wasn't recorded and nothing changed. Telemetry never stops another command for this: a store that can't be written means nothing is sent.",
+      "fix": "Fix the directory's owner or mode, or set `MOSTRA_CONFIG_DIR` to a directory you own, and run the command again. `DO_NOT_TRACK=1` or `MOSTRA_TELEMETRY=0` in your environment turn telemetry off without a file."
+    },
+    {
+      "code": "MOSTRA_CLI_UNKNOWN_COMMAND",
+      "severity": "error",
+      "phase": "host",
+      "title": "Unknown command",
+      "hint": "Pick one of the commands this message lists; `mostra --help` describes each.",
+      "explanation": "The first word after `mostra` isn't a command this CLI has. The message lists the commands that exist. Commands that later releases add (sharing, export, plugins, terminals) appear only once they exist, never as placeholders.",
+      "fix": "Run one of the listed commands. `mostra --help` lists every command with a one-line summary."
+    },
+    {
+      "code": "MOSTRA_CLI_USAGE",
+      "severity": "error",
+      "phase": "host",
+      "title": "Command used wrongly",
+      "hint": "Run `mostra <command> --help` for the command's arguments and flags, then run it again.",
+      "explanation": "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.",
+      "fix": "Read `mostra <command> --help` (or `--help --json` for the machine-readable definition) and correct the arguments."
+    },
+    {
+      "code": "MOSTRA_CONSOLE_ERROR",
+      "severity": "error",
+      "phase": "console",
+      "title": "Error logged to the console",
+      "hint": "Fix what the logged error describes; React logs errors its boundaries catch here too.",
+      "explanation": "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.",
+      "fix": "Read the message and fix its cause in the artifact's code. Errors logged by a library usually name what it was given."
+    },
+    {
+      "code": "MOSTRA_CONSOLE_WARNING",
+      "severity": "hint",
+      "phase": "console",
+      "title": "Warning logged to the console",
+      "hint": "Read the warning; nothing is broken by it.",
+      "explanation": "The page logged a warning with `console.warn`. Warnings are often a library's advice, so they are hints.",
+      "fix": "Nothing is required."
+    },
+    {
+      "code": "MOSTRA_DEP_INSTALL_FAILED",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Package install failed",
+      "hint": "Read the installer's output in the message, then fix the package spec or choose another version.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_DEP_MISSING",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Package not added",
+      "hint": "Run the `mostra add` command in this diagnostic's fix, then publish again.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_DEP_NOT_FOUND",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Package not found",
+      "hint": "Check the package name and version against the npm registry, then fix the import or the spec.",
+      "explanation": "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.",
+      "fix": "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>`."
+    },
+    {
+      "code": "MOSTRA_DEP_OFFLINE",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Package unavailable offline",
+      "hint": "Connect to the network and publish again, or import a package the home already holds.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_DEP_SPEC_INVALID",
+      "severity": "error",
+      "phase": "host",
+      "title": "Invalid package spec",
+      "hint": "Write the spec as `name`, `name@version`, `name@range` or `name@tag`.",
+      "explanation": "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.",
+      "fix": "Correct the spec, for example `mostra add three@0.186.1` or `mostra add @xyflow/react`."
+    },
+    {
+      "code": "MOSTRA_DEP_TIMEOUT",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Package install timed out",
+      "hint": "Check the network and the registry, then publish again.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_DEP_WARM_CONFLICT",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Warm package version requested",
+      "hint": "Add the package without a version, or with one the warm set's version satisfies.",
+      "explanation": "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.",
+      "fix": "Drop the version from the spec (`mostra add react`), or request a range the warm version satisfies. The message names the warm version."
+    },
+    {
+      "code": "MOSTRA_ENV_BIND_FAILED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Gateway can't bind",
+      "hint": "Start Mostra with an address this machine has, or without `--bind` to use the loopback address.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_ENV_BROWSER_MISSING",
+      "severity": "error",
+      "phase": "host",
+      "title": "Browser for verify missing",
+      "hint": "Run the runtime bundle's `bin/mostra-setup` (with network access) to fetch the browser verify uses, then verify again.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED",
+      "severity": "error",
+      "phase": "platform",
+      "title": "Runtime bundle download failed",
+      "hint": "Check the network or proxy (`HTTPS_PROXY`), then run the command again: a retry starts the download over.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_ENV_BUNDLE_INVALID",
+      "severity": "error",
+      "phase": "platform",
+      "title": "Runtime bundle failed verification",
+      "hint": "Nothing was installed; install Mostra again, and if it fails the same way, report it with the message.",
+      "explanation": "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.",
+      "fix": "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`."
+    },
+    {
+      "code": "MOSTRA_ENV_BUNDLE_UNAVAILABLE",
+      "severity": "error",
+      "phase": "platform",
+      "title": "No runtime bundle available",
+      "hint": "Run this once with network access, or point `MOSTRA_BUNDLE` at an extracted bundle.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_ENV_NODE_UNSUPPORTED",
+      "severity": "error",
+      "phase": "platform",
+      "title": "Node.js too old to start 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.",
+      "explanation": "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.",
+      "fix": "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`."
+    },
+    {
+      "code": "MOSTRA_ENV_PORT_TAKEN",
+      "severity": "warning",
+      "phase": "host",
+      "title": "Leased port taken",
+      "hint": "Open the artifact through a new link: `view/url` or `mostra open` mints one on the new port.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_ENV_RUNTIME_MISSING",
+      "severity": "error",
+      "phase": "host",
+      "title": "Runtime not found",
+      "hint": "Reinstall Mostra, or set `MOSTRA_RUNTIME_BIN` to the runtime's `mostra-runtime` entry.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_ENV_SERVICE_FAILED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Login service could not be installed",
+      "hint": "Read the message, fix what it names, and run the install again.",
+      "explanation": "`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.",
+      "fix": "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`."
+    },
+    {
+      "code": "MOSTRA_ENV_SHELL_MISSING",
+      "severity": "error",
+      "phase": "host",
+      "title": "Shell app missing",
+      "hint": "Reinstall the Mostra runtime, or set `MOSTRA_SHELL_DIR` to its built shell.",
+      "explanation": "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.",
+      "fix": "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`."
+    },
+    {
+      "code": "MOSTRA_ENV_WARM_MISSING",
+      "severity": "error",
+      "phase": "host",
+      "title": "Warm package set missing",
+      "hint": "Reinstall the Mostra runtime, or set `MOSTRA_WARM_DIR` to its warm package set.",
+      "explanation": "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.",
+      "fix": "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`."
+    },
+    {
+      "code": "MOSTRA_FIELD_CONFLICT",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Field changed by another writer",
+      "hint": "Read the value again, then write it; for a value several writers change often, give each writer a field of its own.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_FIELD_DUPLICATE_ID",
+      "severity": "error",
+      "phase": "lint",
+      "title": "Field ID used for two different fields",
+      "hint": "Give each of these fields its own ID.",
+      "explanation": "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.",
+      "fix": "Rename one of them, for example `notes` and `notes.summary`, so each persisted value has its own ID."
+    },
+    {
+      "code": "MOSTRA_FIELD_ID_INVALID",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Invalid field ID",
+      "hint": "Use a stable field ID of 1 to 256 characters: dot-separated parts, none empty.",
+      "explanation": "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.",
+      "fix": "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."
+    },
+    {
+      "code": "MOSTRA_FIELD_ID_UNSTABLE",
+      "severity": "error",
+      "phase": "lint",
+      "title": "Field ID changes between renders",
+      "hint": "Build the field's ID from stable data, such as a record's ID, never from random numbers or the time.",
+      "explanation": "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.",
+      "fix": "Derive the ID from something stable, for example a template with the record's ID instead of one with `Math.random()`."
+    },
+    {
+      "code": "MOSTRA_FIELD_MUTATION_ID_REUSED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Mutation ID reused",
+      "hint": "Generate a new mutation ID for every new change.",
+      "explanation": "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.",
+      "fix": "Create a fresh `mut_` ID for each change and reuse an ID only to retry exactly the same change."
+    },
+    {
+      "code": "MOSTRA_FIELD_SHARED",
+      "severity": "hint",
+      "phase": "lint",
+      "title": "Field ID shared by several controls",
+      "hint": "Nothing to fix if these controls are meant to edit one value; give each its own ID if not.",
+      "explanation": "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.",
+      "fix": "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.`."
+    },
+    {
+      "code": "MOSTRA_FIELD_TOO_LARGE",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Field value too large",
+      "hint": "Split large data across fields, keeping each value under 1 MiB and the whole document under 16 MiB.",
+      "explanation": "A field value is at most 1 MiB of JSON and a draft or artifact state at most 16 MiB in all (DATA_MODEL §5). This write would pass one of those limits, so Mostra refused it whole: nothing was truncated, and the page keeps the value locally.",
+      "fix": "Split the value across several fields under one dotted prefix (`report.part1`, `report.part2`); they nest again in results."
+    },
+    {
+      "code": "MOSTRA_FIELD_UNBOUND",
+      "severity": "hint",
+      "phase": "smoke",
+      "title": "Input not bound to a field",
+      "hint": "Bind the input with `useField` (or a kit input with an `id`) if its value should be saved and submitted.",
+      "explanation": "Verify's smoke test typed into an input and the page saved nothing: the input isn't bound to a field, so what a viewer types there is lost on reload and isn't part of a submission. A search box or a filter may be meant that way.",
+      "fix": "Use `const [value, setValue] = useField(\"<id>\", \"\")` for the input's value, or leave it if it isn't meant to persist."
+    },
+    {
+      "code": "MOSTRA_HOME_DISK_FULL",
+      "severity": "error",
+      "phase": "host",
+      "title": "Disk full",
+      "hint": "Free space on the disk that holds the Mostra home, then retry.",
+      "explanation": "A ledger write failed because the disk holding the home is full. The transaction was rolled back, so nothing partial was saved and nothing that was acknowledged earlier is lost. Viewers keep unsaved edits in their browser until a retry succeeds.",
+      "fix": "Free space on that disk (`mostra gc` removes unreferenced versions; build caches can be deleted), then retry the operation. Retries with the same request or mutation ID are safe."
+    },
+    {
+      "code": "MOSTRA_HOME_GC_INCOMPLETE",
+      "severity": "warning",
+      "phase": "host",
+      "title": "gc didn't finish a step",
+      "hint": "Run `mostra gc` again: what this run removed is in its result, and the next run picks up what it left.",
+      "explanation": "`mostra gc` removes what nothing references in steps: version files, source snapshots, lock layouts, the package store, verify's caches and, when asked, events. One step failed (the message names it and why), so it left that step's files in place. Everything an earlier step removed is listed in the result, and the versions it collected stay collected. The home is consistent: what gc left is still recorded as there.",
+      "fix": "Run `mostra gc` again; a failure that repeats names its cause in the message (for example, a file the user can't remove)."
+    },
+    {
+      "code": "MOSTRA_HOME_GONE",
+      "severity": "error",
+      "phase": "host",
+      "title": "Home directory removed",
+      "hint": "Restore or recreate the home directory, then start Mostra again.",
+      "explanation": "The instance's home directory disappeared or was replaced while the instance was running. Writing anywhere else could split the home's data, so the instance stops accepting requests, stops its child processes and exits.",
+      "fix": "Put the home back (or choose a new one with `--home` or `MOSTRA_HOME`) and start Mostra again. Clients reconnect and retry their requests by ID."
+    },
+    {
+      "code": "MOSTRA_HOME_INTEGRITY",
+      "severity": "error",
+      "phase": "host",
+      "title": "Stored version or file damaged",
+      "hint": "Publish the version's source again to rebuild a damaged version in place, and run `mostra doctor` for other damaged objects.",
+      "explanation": "Mostra checks stored versions, source snapshots and blobs against their recorded content digests before using them. This code means a stored object is missing or its content changed after it was written, for example after a disk error or a manual edit inside the home. The message names the object.",
+      "fix": "Leave files inside the home unchanged. To repair a version, publish the same source again: Mostra rebuilds the version's directory and puts it back under the same version ID, and the artifact keeps its version number. If the source has changed since, the publish makes a new version and the damaged one stays as it is; its source snapshot in the home holds the original files. `mostra doctor` lists other damaged objects."
+    },
+    {
+      "code": "MOSTRA_HOME_LEDGER_UNREADABLE",
+      "severity": "error",
+      "phase": "host",
+      "title": "Ledger can't be read",
+      "hint": "Restore the ledger from the latest `ledger.sqlite.bak-*` backup in the home's `store/` directory, or move the damaged file aside.",
+      "explanation": "The ledger (`store/ledger.sqlite` in the home) holds drafts, submissions, events and the rest of the home's interaction data. Mostra reports this code when the file can't be opened, isn't a SQLite database, isn't a Mostra ledger, or fails SQLite's integrity check. Mostra never replaces an existing ledger with an empty one.",
+      "fix": "Stop every Mostra process for this home. Copy `store/ledger.sqlite` somewhere safe, then restore the newest `store/ledger.sqlite.bak-<from>-<to>` in its place, or move the damaged file aside to start an empty ledger. Versions, sources and blobs in the home are untouched either way."
+    },
+    {
+      "code": "MOSTRA_HOME_LOCKED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Home in use by another instance",
+      "hint": "Use the instance that already owns this home, or stop it (`mostra daemon stop`, or end the process named in the message) and start again.",
+      "explanation": "One Mostra instance owns a home at a time. It holds an exclusive lock on the home's ledger, and the operating system releases that lock when the process exits. Mostra reports this code in two cases: `mostra host` was started for a home another instance already owns, or a starter found the owner but couldn't reach its control socket. The message names the owner's process ID.",
+      "fix": "To share the running instance, attach to it: start the client with the same home (`MOSTRA_HOME` or `--home`) instead of starting a second instance. To replace it, stop it with `mostra daemon stop`, or end the process named in the message, and start again. A host that needs its own instance gives it its own home."
+    },
+    {
+      "code": "MOSTRA_HOME_MISMATCH",
+      "severity": "error",
+      "phase": "host",
+      "title": "Instance serves a different home",
+      "hint": "Connect to the instance for the home you expect, or start it with `--home` set to that home.",
+      "explanation": "A client sent `home.path` in `mostra/initialize`, and it names a different home from the one the instance locked at start-up. The home is chosen when the instance starts (`--home`, then `MOSTRA_HOME`, then the platform default), so `home.path` is a check: it stops a client from writing to a home it didn't mean.",
+      "fix": "Start the instance with `--home` set to the home the client expects, or connect to the socket of the instance that serves it. Leave `home.path` out to accept whichever home the instance serves."
+    },
+    {
+      "code": "MOSTRA_HOME_NOT_ALWAYS_ON",
+      "severity": "warning",
+      "phase": "host",
+      "title": "Long-lived artifacts without an always-on daemon",
+      "hint": "Run `mostra daemon install` so the home's daemon runs as a login service and these artifacts answer at any hour.",
+      "explanation": "The home has artifacts with submission policy `none`, which are meant to stay open (dashboards, task managers, D63), but no login service runs its daemon. Without one, the daemon exits after 30 idle minutes and their links stop answering until a command starts it again.",
+      "fix": "Run `mostra daemon install`. It registers a launchd or systemd user service that keeps the home's daemon running; `mostra daemon uninstall` removes it."
+    },
+    {
+      "code": "MOSTRA_HOME_NOT_OWNED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Directory not owned by you",
+      "hint": "Choose a home you own with `--home` or `MOSTRA_HOME`, or give the directory named in the message back to your user with `chown`.",
+      "explanation": "Mostra keeps secrets, answers and its ledger in the home, and its control socket in a runtime directory, so it uses only directories that belong to the user running it. It reports this code when the home or the runtime directory is owned by another user, or when the path exists but isn't a directory. Mostra changes nothing in that case.",
+      "fix": "Point Mostra at a directory you own: `--home <dir>` or `MOSTRA_HOME` for the home, `MOSTRA_RUNTIME_DIR` for the runtime directory. If the directory should be yours, change its owner with `chown`. Mostra tightens a directory you own to mode 0700 by itself."
+    },
+    {
+      "code": "MOSTRA_HOME_SOCKET_TOO_LONG",
+      "severity": "error",
+      "phase": "host",
+      "title": "Control socket path too long",
+      "hint": "Set `MOSTRA_RUNTIME_DIR` to a short directory you own, for example `/tmp/mostra-$USER`, and start again.",
+      "explanation": "Clients reach an instance through a Unix socket in a per-user runtime directory. The operating system limits a socket path to 103 bytes on macOS and 107 on Linux, and the path Mostra computed is longer, usually because the home directory's path is long. Mostra stops instead of using a different place that clients couldn't find.",
+      "fix": "Set `MOSTRA_RUNTIME_DIR` to a short directory you own, such as `/tmp/mostra-$USER`, in the environment of every Mostra client and host that uses this home. Mostra creates it with mode 0700 and re-creates its socket if a temporary-file cleanup removes it."
+    },
+    {
+      "code": "MOSTRA_HOME_TOO_NEW",
+      "severity": "error",
+      "phase": "host",
+      "title": "Home written by a newer Mostra",
+      "hint": "Run a Mostra release at least as new as the one named in the message, or use another home with `--home`.",
+      "explanation": "A newer Mostra migrated this home's ledger to a schema version this runtime doesn't know. Reading it could misinterpret or lose data, so this runtime refuses to open it. The message names the schema version and the release that wrote it.",
+      "fix": "Upgrade the runtime (or the host or CLI that bundles it) to at least the release named in the message. Mostra never migrates a ledger backwards; to keep an older release, give it a separate home with `--home` or `MOSTRA_HOME`."
+    },
+    {
+      "code": "MOSTRA_HOST_CONNECTION_CLOSED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Connection closed",
+      "hint": "Reconnect, then retry the request with the same request ID.",
+      "explanation": "The connection to the other side closed before a response arrived, for example because the instance exited or restarted. The request may or may not have taken effect.",
+      "fix": "Reconnect and send `mostra/initialize` again, then retry the request with the same request ID. Mutating methods are idempotent by request ID, so a retry never applies twice."
+    },
+    {
+      "code": "MOSTRA_HOST_CURSOR_COMPACTED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Events compacted",
+      "hint": "Read from the cursor in the message to receive the compaction summary, then continue from there.",
+      "explanation": "Events before a cursor were compacted on request (`mostra gc --compact-events`, DATA_MODEL §4): an artifact's old events were replaced by one `artifact.compacted` event that summarizes them. A reader asking for events after an earlier cursor would miss some, and Mostra never leaves a silent gap.",
+      "fix": "Read again with `after` set to the cursor the message names: the next event is the `artifact.compacted` summary. Rebuild what you track from it and continue as usual."
+    },
+    {
+      "code": "MOSTRA_HOST_IDENTITY_UNAVAILABLE",
+      "severity": "error",
+      "phase": "host",
+      "title": "The host that identifies viewers didn't answer",
+      "hint": "Start the host that serves this home's identity port, then open the link again.",
+      "explanation": "A host registered the `identity` port, so it decides who opens this home's links. When a link minted without a viewer was opened, that host failed, didn't answer within 5 seconds, gave an answer its schema refuses, or is expected (it lists `identity` in `HomeConfig.ports`) but not connected. Mostra refuses the link rather than let the session act as someone else.",
+      "fix": "Start or reconnect the host, then open the link again. A link minted with `view/url`'s `viewer` names its person itself and never needs the port. To return the home to Mostra's own identity, have the host register without the port and clear its expected ports (`HomeConfig.ports: []`)."
+    },
+    {
+      "code": "MOSTRA_HOST_INITIALIZE_ORDER",
+      "severity": "error",
+      "phase": "host",
+      "title": "Initialize first, and only once",
+      "hint": "Send `mostra/initialize` as the first request on the connection, and only once.",
+      "explanation": "Every connection starts with `mostra/initialize`, which agrees the protocol revision and registers the client's ports. The instance received another request before it, or a second `mostra/initialize` on the same connection.",
+      "fix": "Send `mostra/initialize` first and wait for its result before any other request. To renegotiate, open a new connection."
+    },
+    {
+      "code": "MOSTRA_HOST_INTERNAL_ERROR",
+      "severity": "error",
+      "phase": "host",
+      "title": "Unexpected failure in the instance",
+      "hint": "Retry the request with the same request ID; if it fails again, report it with the instance's log.",
+      "explanation": "The instance failed while handling the request, for a reason that isn't one of its known conditions. Durable state is unaffected: a request is acknowledged only after its ledger transaction commits. The details are in the instance's log (`logs/supervisor.log` in the home), not in the response.",
+      "fix": "Retry the request with the same request ID; retries are idempotent. If the failure repeats, report it with the relevant lines of `logs/supervisor.log`."
+    },
+    {
+      "code": "MOSTRA_HOST_INVALID_PARAMS",
+      "severity": "error",
+      "phase": "host",
+      "title": "Invalid method params",
+      "hint": "Fix the params named in the message so they match the method's schema.",
+      "explanation": "The request's `params` don't match the method's published schema: a required field is missing, a value has the wrong type, or a value is outside its allowed range. The message names the first problem found.",
+      "fix": "Compare the request with the method's schema in `@mostra/protocol` (or the published JSON Schema) and correct the field named in the message."
+    },
+    {
+      "code": "MOSTRA_HOST_MALFORMED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Malformed protocol message",
+      "hint": "Send each message as one line of JSON holding a single JSON-RPC 2.0 request or notification.",
+      "explanation": "Every message on a Mostra connection is one line of JSON with one JSON-RPC 2.0 object. This code means a line wasn't valid JSON, wasn't a JSON-RPC 2.0 request or response, or was a batch (a JSON array), which revision `2026-10-10` doesn't accept. A client also reports it when a response doesn't match the method's result schema.",
+      "fix": "Encode one request per line with `\"jsonrpc\": \"2.0\"`, a `method`, an `id` for requests, and `params` as an object. Send several requests as separate lines instead of a batch."
+    },
+    {
+      "code": "MOSTRA_HOST_MESSAGE_TOO_LARGE",
+      "severity": "error",
+      "phase": "host",
+      "title": "Message too large for the protocol",
+      "hint": "Ask for less at once: a specific submission, fewer events, or smaller values.",
+      "explanation": "One host-protocol message is one line of JSON, and a line holds at most 64 Mi characters (`MAX_LINE_LENGTH`), so neither side buffers without bound. Mostra checks every message before it writes it: an answer that would be longer is replaced by this error, and a delivery whose envelope would be longer is recorded as undeliverable instead of being sent and retried forever.",
+      "fix": "Read less per request (`events/read` with a smaller `limit`, `results/get` for one submission), and keep artifacts' values within the field and document limits."
+    },
+    {
+      "code": "MOSTRA_HOST_METHOD_UNKNOWN",
+      "severity": "error",
+      "phase": "host",
+      "title": "Unknown protocol method",
+      "hint": "Call only the methods listed in `capabilities.methods` of the `mostra/initialize` result.",
+      "explanation": "The instance doesn't serve the method that was called. Either the name is misspelled, or the client is newer than the instance and calls a method the instance's release doesn't have.",
+      "fix": "Check the method name against INTERFACES §6, and against `capabilities.methods` in the `mostra/initialize` result, which lists every method this instance serves. Upgrade the instance if the client needs a newer method."
+    },
+    {
+      "code": "MOSTRA_HOST_NOTIFICATION_UNSUPPORTED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Notification not accepted",
+      "hint": "List the notification in `capabilities.notifications` when you initialize.",
+      "explanation": "Mostra sends a client only the notifications it listed in `mostra/initialize` (D84). This method would send one the client didn't list, such as `events/notify` for `events/subscribe`.",
+      "fix": "Reconnect and initialize with `capabilities: { notifications: [\"events/notify\"] }`, or poll with `events/read` instead."
+    },
+    {
+      "code": "MOSTRA_HOST_PORT_UNSUPPORTED",
+      "severity": "warning",
+      "phase": "host",
+      "title": "Port not supported by this instance",
+      "hint": "Leave the port out of `mostra/initialize`, or run a Mostra release that lists it in `capabilities.ports`.",
+      "explanation": "The client registered a port this instance doesn't call, so registering it has no effect. The port may be reserved for a later release (such as `ai`), or the client may be newer than the instance. The session continues without the port, and Mostra uses its standalone behavior instead.",
+      "fix": "Register only the ports listed in `capabilities.ports` of the `mostra/initialize` result. If the host needs the port, upgrade the instance to a release that supports it."
+    },
+    {
+      "code": "MOSTRA_HOST_REQUEST_ID_REUSED",
+      "severity": "error",
+      "phase": "host",
+      "title": "A requestId was reused with other parameters",
+      "hint": "Send a new `requestId` for a new request; repeat the exact parameters only to retry one.",
+      "explanation": "A mutating method recorded its result under this `requestId` for different parameters. Replaying that result would answer a request nobody made (a link for another artifact or with other scopes, another source's publish), so the instance refuses (H-03). Retries with the same parameters still return the recorded result.",
+      "fix": "Generate a fresh `requestId` for every new request, and reuse one only to retry the same request after a timeout or a lost connection."
+    },
+    {
+      "code": "MOSTRA_HOST_REVISION_UNSUPPORTED",
+      "severity": "error",
+      "phase": "host",
+      "title": "No common host protocol revision",
+      "hint": "Run the client and the instance from the same Mostra release, for example with `mostra daemon restart`.",
+      "explanation": "A client and a Mostra instance agree on a host protocol revision when they connect (`mostra/initialize`). The client offers the revisions it speaks, and the instance picks the newest one it also supports. This code means the two lists have nothing in common, usually because the client and the running daemon come from Mostra releases far apart.",
+      "fix": "Restart the daemon so it runs the same release as the client: `mostra daemon restart`. Durable state survives the restart, and open views reconnect. A host that embeds Mostra updates its pinned Mostra runtime or its host library until both support a common revision."
+    },
+    {
+      "code": "MOSTRA_HOST_SHUTDOWN_REFUSED",
+      "severity": "error",
+      "phase": "host",
+      "title": "Only the spawning host can stop this instance",
+      "hint": "Ask the host that started this instance to stop it, or end the connection you opened instead.",
+      "explanation": "An instance started by a host over stdio (`mostra host`) lives as long as that host's connection, so only the host may stop it with `mostra/shutdown`. A client that attached through the home's socket asked it to stop. A daemon (`mostra daemon`) accepts `mostra/shutdown` from every attached client (D87).",
+      "fix": "Close your own connection when you are done. To stop the instance, stop the host that spawned it, or have the host send `mostra/shutdown` or close its stdio."
+    },
+    {
+      "code": "MOSTRA_HOST_SUBSCRIPTION_UNKNOWN",
+      "severity": "error",
+      "phase": "host",
+      "title": "Unknown subscription",
+      "hint": "Subscribe again with `events/subscribe`, then use the ID it returns.",
+      "explanation": "The subscription ID belongs to no subscription on this connection: it was never created here, was ended with `events/unsubscribe`, or belonged to a connection that closed. Subscriptions live as long as their connection; a named subscriber's acknowledged cursor outlives it.",
+      "fix": "Call `events/subscribe` again on this connection. With the same `name`, delivery resumes after the last acknowledged cursor."
+    },
+    {
+      "code": "MOSTRA_HOST_TIMEOUT",
+      "severity": "error",
+      "phase": "host",
+      "title": "Request timed out",
+      "hint": "Retry the request with the same request ID, or allow it more time.",
+      "explanation": "No response arrived within the time the caller allowed. The other side may still be working on the request, and it may still take effect.",
+      "fix": "Retry with the same request ID, which returns the recorded result if the first attempt completed. Allow a longer timeout for slow operations."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_CONTENT_TYPE",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "JSON content type required",
+      "hint": "Send the body as JSON with `Content-Type: application/json`.",
+      "explanation": "Requests that change state must have a JSON body. A form or plain-text body is something any website can send without asking the browser first, so the gateway refuses it with 415.",
+      "fix": "Send `Content-Type: application/json` and a JSON body."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_CSRF_MISSING",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "CSRF token missing or wrong",
+      "hint": "Send the session's CSRF token from `GET /_mostra/session` in the `X-Mostra-CSRF` header.",
+      "explanation": "Every request that changes state through a session carries the session's CSRF token in the `X-Mostra-CSRF` header. The token comes only from the session endpoint of the same origin, which no other page can read. A missing or different token is answered with 403.",
+      "fix": "Read `csrf` from `GET /_mostra/session` (on the shell, `GET /a/<artifactId>/_mostra/session`) and send it with every POST. Mostra's client runtime and shell do this for you."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_HEADERS_TOO_LARGE",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "The request's headers are too large",
+      "hint": "Open the link again: this page cleared the cookies that made the request too large.",
+      "explanation": "The request's headers passed the gateway's limit of 1 MiB, more than any browser sends for one host's cookies. Every port of the loopback host shares one cookie jar, so a page on any of them can fill it. The gateway answers 431 with `Clear-Site-Data: \"cookies\"`, which empties the host's cookies, so the next request works. Mostra's sessions go with them and come back when a link is opened again.",
+      "fix": "Open the artifact's link again. If it keeps happening, find the page that sets the cookies: it runs on this host."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_HOST_REFUSED",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Host not served",
+      "hint": "Open the artifact through the exact link Mostra gave you.",
+      "explanation": "The request's `Host` header named a host this gateway doesn't serve. Each gateway listener accepts exactly the host and port its capability URLs use, so a page that rebinds its own DNS name to the loopback address can't reach an artifact (DNS rebinding). The gateway answers 421.",
+      "fix": "Use the URL from `view/url` or the publish receipt as it is, without replacing `127.0.0.1` by `localhost` or another name. A gateway started with `--bind` and `--url-host` accepts the URL host it was given."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_NOT_SERVED",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Nothing served here",
+      "hint": "Request a published version's files or a documented `/_mostra/` path.",
+      "explanation": "The gateway serves only published versions' client files and the browser-protocol paths under `/_mostra/`. Everything else in the home, such as sources, server bundles, staging and unpublished builds, has no URL. A path or method nothing answers gets 404 or 405.",
+      "fix": "Check the path. Server code runs through the browser protocol, never as a file, and an artifact becomes viewable only once it is published."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_ORIGIN_REFUSED",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Origin refused",
+      "hint": "Send the request from the page's own origin.",
+      "explanation": "A request that changes state, opens a stream or upgrades to a WebSocket must carry an `Origin` header equal to the origin it is sent to. The gateway compares the strings exactly and answers 403 otherwise, so another website, or another artifact on a different port, can't drive this one.",
+      "fix": "Call the gateway from the page it serves: the shell from the shell, the artifact from its own frame. Tools outside a browser send the listener's own origin."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_RATE_LIMITED",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Too many failed attempts",
+      "hint": "Wait for the time in `Retry-After`, then open the link again.",
+      "explanation": "More than 30 capability tokens failed for this artifact within a minute, so the gateway refuses every token for it, valid ones included, until the minute has passed. A guess can't succeed while the limit holds, and only this artifact's links wait. The gateway answers 429 with `Retry-After`.",
+      "fix": "Wait, then open the link again. Repeated failures usually come from a mistyped link or a script retrying an old one."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_REQUEST_MALFORMED",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Malformed request",
+      "hint": "Send one well-formed HTTP request with a path that starts with `/`.",
+      "explanation": "The gateway refused a request it can't interpret safely: a repeated `Host` or `Origin` header, a request target that isn't a path, an encoded `/` or `..` that would leave the served tree, a body that isn't valid JSON, or a header with control characters. It answers 400 rather than guess.",
+      "fix": "Send a single request with one `Host` header and a plain path. Browsers always do; this usually means a hand-written client or a probe."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_SCOPE_DENIED",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Not allowed by this link",
+      "hint": "Open a link minted with this scope (`view/url` with `scopes`).",
+      "explanation": "The session's link doesn't carry the scope this request needs: `draft` to save answers, `submit` to submit, `review` to comment, and `action:*`, `action:<export>` or `action:<module path>#<export>` to run a server function. A view-and-comment link, for example, can't submit or run an action. The gateway answers 403.",
+      "fix": "Mint a link with the scopes the viewer needs, such as `view/url` with `scopes: [\"view\", \"draft\", \"submit\"]`. Without `scopes`, a link carries every scope."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_SESSION_CONFLICT",
+      "severity": "warning",
+      "phase": "hygiene",
+      "title": "Another link is already open for this artifact",
+      "hint": "Choose which link to keep; send `replace: true` to use the new one.",
+      "explanation": "This browser already has a live session for the artifact from a different link. Opening a link never silently replaces it, because a page elsewhere could send the viewer to its own, narrower link and take over their tabs (D98). The shell shows both links' access and lets the viewer choose; the answer is 409 with `current` and `offered`.",
+      "fix": "In the shell, choose the link to keep. A client exchanging tokens itself sends `replace: true` to replace the session."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_SESSION_MISSING",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "No session",
+      "hint": "Open the artifact's capability link again to start a session.",
+      "explanation": "The request carried no valid session for this origin. Sessions start when a capability link is opened: the shell exchanges the link's token for a session cookie, and gives the artifact frame a single-use ticket for its own. A session issued for another origin never counts, because every port of the host shares the browser's cookies. The gateway answers 401.",
+      "fix": "Open the full capability link, including the part after `#`. A bookmark of the page without it works while the browser keeps the session cookie (400 days)."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_TOKEN_INVALID",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Unknown capability token",
+      "hint": "Use the complete capability link Mostra gave you, or mint a new one with `view/url`.",
+      "explanation": "The capability token or frame ticket matched nothing in this home: it was mistyped, cut short, belongs to another home or artifact, or the ticket was already used or expired (tickets last 60 seconds and work once). Over the host protocol, the token ID named in `view/revoke` or `view/rotate` doesn't exist. The gateway answers 401, and failed attempts count towards the rate limit.",
+      "fix": "Copy the whole link again. An agent or host mints a fresh one with `view/url`; the shell gets a new frame ticket by reloading."
+    },
+    {
+      "code": "MOSTRA_HYGIENE_TOKEN_REVOKED",
+      "severity": "error",
+      "phase": "hygiene",
+      "title": "Link revoked or expired",
+      "hint": "Ask for a new link: `view/url` mints one, or `view/rotate` replaces this one.",
+      "explanation": "The capability link was revoked (`view/revoke`), replaced (`view/rotate`), or reached the end of its `ttl`. Every session started from it ends too. The gateway answers 410. Local links have no expiry unless one was asked for.",
+      "fix": "Get a new link from whoever shared this one. An agent mints it with `view/url`, or rotates the old one with `view/rotate`, and shares the new URL."
+    },
+    {
+      "code": "MOSTRA_LIVE_SOURCE_FAILED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Live source failed",
+      "hint": "Read the message, fix the live source's loader or stream, and publish again; the last good value stays meanwhile.",
+      "explanation": "A live source's `load` or `stream` threw, or its value was outside the serializable types. Pages keep showing the last good value with `useLive`'s `error` set, and the producer tries again on its schedule (FAILURE_MODEL §6).",
+      "fix": "Fix the producer in `live.ts`, or catch transient failures there and return the previous value."
+    },
+    {
+      "code": "MOSTRA_LIVE_TOO_LARGE",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Live value too large",
+      "hint": "Push or produce a smaller value: at most 4 MiB serialized.",
+      "explanation": "A live value, pushed or produced, is over 4 MiB once serialized (DATA_MODEL §5). It is refused and the last good value stays.",
+      "fix": "Send a smaller window of the data, or split it across several live sources. For high-rate series, push single points in append mode and let the page keep the window."
+    },
+    {
+      "code": "MOSTRA_MANIFEST_INVALID",
+      "severity": "error",
+      "phase": "manifest",
+      "title": "Manifest value is invalid",
+      "hint": "Fix the manifest field named in the message so it matches the manifest's documented shape.",
+      "explanation": "The manifest was read, but a field has a value the manifest doesn't allow: a missing `title`, a wrong type, an `id` that isn't an artifact ID (`art_` followed by a ULID), a `mode` this runtime doesn't build (`spa` is the only one), or frontmatter that isn't valid YAML. The message names the field and what was expected.",
+      "fix": "Correct the field the message names. Leave `id` out to let Mostra bind the artifact to its source path at first publish, or keep the `id` that `mostra new` wrote. Every field except `title` is optional."
+    },
+    {
+      "code": "MOSTRA_MANIFEST_NOT_LITERAL",
+      "severity": "error",
+      "phase": "manifest",
+      "title": "Manifest isn't a literal",
+      "hint": "Write the manifest as plain values: strings, numbers, booleans, null, arrays and objects, with no variables, calls, spreads or computed keys.",
+      "explanation": "Mostra reads an artifact's manifest without running its code: the `export const artifact = defineArtifact({...})` in a TSX entry, or the frontmatter of an MDX entry. It reports this code when the exported `artifact` isn't a `defineArtifact(...)` call with one object literal, or when a value inside it needs evaluation (an identifier, a function call, a spread, a computed key, a template literal with a placeholder). The location points at the first such value.",
+      "fix": "Replace the value with the literal it stands for, for example `title: \"Q3 review\"` instead of `title: TITLE`. Keep computed values in the page code, where they can use anything. `as const` and `satisfies` on the object are fine."
+    },
+    {
+      "code": "MOSTRA_MANIFEST_UNKNOWN_KEY",
+      "severity": "warning",
+      "phase": "manifest",
+      "title": "Unknown manifest key",
+      "hint": "Remove the key or correct its spelling; a newer Mostra may support it.",
+      "explanation": "The manifest has a key this runtime doesn't know. Mostra ignores it, so manifests written for a newer release still publish, but a misspelled key (`familly`, `decription`) silently has no effect.",
+      "fix": "Check the key against the manifest fields (`id`, `title`, `description`, `family`, `links`, `mode`, `submission`, `kit`, `terminals`, `demos`, `limits`, `verify`) and fix the spelling, or remove it."
+    },
+    {
+      "code": "MOSTRA_NETWORK_EXTERNAL_FAILED",
+      "severity": "warning",
+      "phase": "network",
+      "title": "Request to another origin failed",
+      "hint": "A request to another origin failed while verify ran; check the URL and whether that service was reachable.",
+      "explanation": "A request the page made to another origin failed or answered 4xx or 5xx. It may be the environment (no network, a service that is down, a request the service refuses from this origin) rather than the code, so it is a warning.",
+      "fix": "Check the URL and the service. If the page depends on it, show a fallback when it fails."
+    },
+    {
+      "code": "MOSTRA_NETWORK_REQUEST_FAILED",
+      "severity": "error",
+      "phase": "network",
+      "title": "Request for the page's own resource failed",
+      "hint": "Check the path: a file the page loads from the artifact itself failed to load.",
+      "explanation": "A resource the page loaded from the artifact's own origin (the document, a script, a style, an image, a font, or a fetch by artifact code) failed or answered 4xx or 5xx. Requests the browser makes on its own, such as `/favicon.ico`, and Mostra's own protocol aren't counted.",
+      "fix": "Put the file in `public/` (served at the root) or import it from the code so the build includes it, and check the path's spelling."
+    },
+    {
+      "code": "MOSTRA_PLATFORM_UNSUPPORTED",
+      "severity": "error",
+      "phase": "platform",
+      "title": "Unsupported platform",
+      "hint": "Run Mostra on macOS or Linux, on an x64 or arm64 machine.",
+      "explanation": "Mostra 1.0 runs on macOS and Linux, on x64 and arm64. On any other operating system or architecture, Windows included, every entry point stops with this code before it creates or changes anything, because the process model, sockets and storage are built and tested only on those platforms. The message names the platform that was detected.",
+      "fix": "Run Mostra on a macOS or Linux machine with an x64 or arm64 processor. Windows support is planned for a release after 1.0."
+    },
+    {
+      "code": "MOSTRA_PUBLISH_ID_CONFLICT",
+      "severity": "error",
+      "phase": "publish",
+      "title": "Artifact ID claimed by two sources",
+      "hint": "Give one of the two sources a different `id`, or delete the `id` line from the copy so it becomes a new artifact.",
+      "explanation": "An artifact's `id` names exactly one source. Mostra reports this code when a manifest claims an `id` that is already bound to another source path whose entry still claims it, which usually means a directory was copied. A source that moved, so that the old path no longer claims the `id`, is rebound instead. The message names both paths.",
+      "fix": "Decide which source is the artifact. In the other one, remove the `id` from the manifest (it is then bound to its own path at its first publish) or replace it with a new ID from `mostra new`."
+    },
+    {
+      "code": "MOSTRA_PUBLISH_SOURCE_CHANGED",
+      "severity": "error",
+      "phase": "publish",
+      "title": "Source changed during the publish",
+      "hint": "Publish again once the artifact's files have stopped changing.",
+      "explanation": "Publishing reads the entry's manifest twice: once to find the artifact, and again from the snapshot it builds. Mostra reports this code when the two disagree about which artifact the source is, because the manifest `id` or the source's binding changed while the publish ran, for example when an editor saved the entry mid-publish or another publish rebound the path. Nothing was published.",
+      "fix": "Wait until the files are saved and nothing else is publishing the same source, then publish again. If the manifest `id` was changed on purpose, the next publish uses the new one."
+    },
+    {
+      "code": "MOSTRA_PUBLISH_VERIFY_FAILED",
+      "severity": "error",
+      "phase": "publish",
+      "title": "Verify found errors",
+      "hint": "Run `mostra verify` to see the errors and fix them, or publish with `--force` to record them in the version.",
+      "explanation": "Publish runs verify (or reuses the verdict it cached for the same source and environment) and refuses when the verdict has errors (D41). The message lists their codes. Nothing was published. With `--force`, publish goes ahead and records the codes in the version, where hosts read them; a source that doesn't build can't be published either way.",
+      "fix": "Fix the errors `mostra verify` reports and publish again, or publish with `--force` if the version must ship as it is."
+    },
+    {
+      "code": "MOSTRA_REGRESSION_ACTION_REMOVED",
+      "severity": "warning",
+      "phase": "contract",
+      "title": "Server function gone since the last passing version",
+      "hint": "Observed only: the last passing version had this server function and this source doesn't; one removed on purpose needs nothing more.",
+      "explanation": "A `\"use server\"` export the last passing version had is gone. Pages of the older version still call it while they are open, and keyed runs started by it can't be started again.",
+      "fix": "If it was renamed by mistake, keep its name. If it was removed on purpose, nothing needs to change."
+    },
+    {
+      "code": "MOSTRA_REGRESSION_ARIA",
+      "severity": "warning",
+      "phase": "regression",
+      "title": "Controls or landmarks gone since the last passing version",
+      "hint": "Observed only: the last passing version had these controls or landmarks and this source doesn't; a change that removed them on purpose needs nothing more.",
+      "explanation": "Verify compared this source's accessibility snapshot with the newest version whose verdict passed, rendered in the same run with the same data. The controls or landmarks the message lists (by role and name) were there and aren't now. A redesign may remove them on purpose.",
+      "fix": "If they should be gone, nothing needs to change. If not, look at what removed them."
+    },
+    {
+      "code": "MOSTRA_REGRESSION_FIELD_REMOVED",
+      "severity": "warning",
+      "phase": "contract",
+      "title": "Field gone since the last passing version",
+      "hint": "Observed only: answers saved under this field ID won't carry over to this version; a field removed on purpose needs nothing more.",
+      "explanation": "A field ID the last passing version used is gone from this source. Viewers' answers under it become orphans when they switch (D42): kept, shown read-only and delivered, but not editable. The message gives how many saved answers it affects.",
+      "fix": "If the field was renamed by mistake, keep its old ID. If it was removed on purpose, nothing needs to change."
+    },
+    {
+      "code": "MOSTRA_REGRESSION_LIVE_REMOVED",
+      "severity": "warning",
+      "phase": "contract",
+      "title": "Live source gone since the last passing version",
+      "hint": "Observed only: the last passing version had this live source and this source doesn't; one removed on purpose needs nothing more.",
+      "explanation": "A live source (`live.ts` export) the last passing version had is gone, so its producer stops and hosts that push to it push to a key no page reads.",
+      "fix": "If it was renamed by mistake, keep its name. If it was removed on purpose, nothing needs to change."
+    },
+    {
+      "code": "MOSTRA_REGRESSION_PAGE_REMOVED",
+      "severity": "warning",
+      "phase": "contract",
+      "title": "Page route gone since the last passing version",
+      "hint": "Observed only: the last passing version had this page route and this source doesn't; one removed on purpose needs nothing more.",
+      "explanation": "A route of `pages/` the last passing version had is gone, so links and bookmarks to it now open the artifact's fallback page.",
+      "fix": "If it was renamed by mistake, keep its path. If it was removed on purpose, nothing needs to change."
+    },
+    {
+      "code": "MOSTRA_REGRESSION_PIXELS",
+      "severity": "warning",
+      "phase": "regression",
+      "title": "Page looks different from the last passing version",
+      "hint": "Observed only: this share of the viewport's pixels differs from the last passing version; an intended visual change shows here too and needs nothing more.",
+      "explanation": "Verify rendered the newest version whose verdict passed and this source at the same viewport, clock and data, and the share of pixels the message gives differs between them. Any intended visual change shows here too.",
+      "fix": "If the change is one you made on purpose, nothing needs to change. To see where it is, read the ARIA snapshots, or look at the diff image the message names if you can view images."
+    },
+    {
+      "code": "MOSTRA_RUNTIME_BLANK",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Page rendered nothing",
+      "hint": "Make the page render something visible; check its first render and its imports.",
+      "explanation": "After the page reported ready, no element had a visible box (text, image, SVG, canvas or video) and the screenshot was one uniform color. Usually the page threw during its first render, rendered nothing until data arrived, or hid everything with CSS.",
+      "fix": "Look at the other diagnostics for an error during the first render, and make the page show content (or a loading state) right away."
+    },
+    {
+      "code": "MOSTRA_RUNTIME_NOT_READY",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Page never became ready",
+      "hint": "Make sure the entry's default export renders; check the other diagnostics for an error at load.",
+      "explanation": "The page never reported `mostra/ready`: the client runtime didn't mount it within the time verify allows, usually because the entry threw while loading or a module failed to load.",
+      "fix": "Fix the load error the other diagnostics report. A page that waits for data should render a loading state first."
+    },
+    {
+      "code": "MOSTRA_RUNTIME_PAGE_ERROR",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Uncaught error in the page",
+      "hint": "Fix the error the message names; it was thrown in the page and nothing caught it.",
+      "explanation": "The artifact's page threw an error that nothing caught, or a promise rejected with nothing handling it, while verify rendered it or while the smoke test used a control (the message says which). A viewer's page would meet the same error.",
+      "fix": "Find the stack's first frame in the artifact's code and fix the error there, or catch it where the page can recover."
+    },
+    {
+      "code": "MOSTRA_RUNTIME_WORKER_CRASHED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Artifact server code crashed",
+      "hint": "Read the cause and the worker's last output, fix the server code, and publish again.",
+      "explanation": "The artifact version's worker process exited while serving a call: it threw outside any call, ran out of its heap (1 GiB by default), or kept its event loop blocked past the watchdog (10 s by default). Other artifacts and the gateway keep working (RT-04). Mostra appends `worker.crashed` with the cause and starts the worker again on the next request, waiting longer after each crash (1 s up to 60 s). `verify` reports it too when the source's server code crashes, fails to load or hangs while the page renders, even when the page handled the failed call.",
+      "fix": "Fix the crash in the server code. A long synchronous computation can raise `limits.watchdogMs` in the manifest, and a large data set `limits.heapMb`; both are stability limits, not security ones."
+    },
+    {
+      "code": "MOSTRA_RUNTIME_WORKER_PARKED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Artifact server code keeps crashing",
+      "hint": "Fix the server code and publish again, which clears the park; the message names the last crash's cause.",
+      "explanation": "The artifact version's worker crashed more than 5 times in 10 minutes, so Mostra stopped starting it (FAILURE_MODEL §2). Calls, runs and live sources of that version answer this code until the park clears, and the shell tells the viewer that the artifact's server code keeps crashing.",
+      "fix": "Find the cause in the message and the worker's output, fix it, and publish again: a new publish, `verify` or a restart of the instance clears the park."
+    },
+    {
+      "code": "MOSTRA_SECRET_MISSING",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Secret not set",
+      "hint": "Set the secret with `mostra secret set NAME`, reading the value from stdin.",
+      "explanation": "Server code called `secret(name)` for a secret that neither the host's `secrets` port, the artifact's own secrets nor the home's shared secrets hold (D44). The call throws, and an action run fails with this code.",
+      "fix": "Set the secret for the artifact (`mostra secret set NAME --artifact <path|id>`) or for every artifact of the home (`mostra secret set NAME`), passing the value on stdin, then run the action again. Secret values never go into the artifact's source."
+    },
+    {
+      "code": "MOSTRA_SMOKE_BUDGET",
+      "severity": "hint",
+      "phase": "smoke",
+      "title": "Smoke test stopped at its budget",
+      "hint": "Nothing to fix: the smoke test stops after 200 interactions or 60 s.",
+      "explanation": "The page has more controls than the smoke test uses in one run, so it stopped at its budget. The controls it used are counted in `smoke.interactions`.",
+      "fix": "Nothing is required."
+    },
+    {
+      "code": "MOSTRA_SMOKE_NO_EFFECT",
+      "severity": "warning",
+      "phase": "smoke",
+      "title": "Control showed no effect",
+      "hint": "Observed only: using this control twice changed nothing verify could see; a control that acts on something verify can't observe needs no change.",
+      "explanation": "Verify's smoke test clicked or hovered the control the message names, once among the other controls and again after them, and saw no change either time: no change to the page, no request, no saved field, no navigation and no error. Controls that are disabled or already active (the selected tab) are skipped, and those that open on hover are hovered. A control can still be fine: it may act on something verify can't observe, such as the clipboard or a sound.",
+      "fix": "Read the control's handler. If it does what it should, nothing needs to change; if it is meant to change the page, look at why it doesn't."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_ALREADY",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Already submitted",
+      "hint": "This artifact takes one submission, and it was made; read it with `mostra results`.",
+      "explanation": "The artifact's submission policy is `once`, and a submission already closed this draft: for scope `per-artifact` any viewer's submission closes every draft, for `per-viewer` the viewer's own. A submission is immutable and final, so Mostra refuses a second one and further edits to the closed draft. The refusal carries the existing submission. A repeated submit of the same view at the same draft revision is not refused: it returns the original submission.",
+      "fix": "Read the existing submission with `mostra results <artifact>`. When another round of answers is wanted, publish a new artifact linked to this one (`links: [{ rel: \"round-of\", artifact }]`), or have the host publish with the `epochs` policy."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_BLOCKED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Answers missing before submit",
+      "hint": "Fill in the fields this diagnostic lists, fix their errors or resolve their conflicts, then submit again.",
+      "explanation": "Before a submit, the shell and the client runtime check every mounted field (D106): a `required` field without a value, a value its `validate` rejects, or a conflict the viewer hasn't resolved blocks the submit. The diagnostic lists the blockers with their field IDs and labels; `useSubmit().blockers` lists them before anyone submits. Nothing was submitted.",
+      "fix": "Show `useSubmit().blockers` next to your submit button, or let the shell list them by label. Answer the required fields, fix the invalid values, and keep or take the conflicting values, then submit again."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_CHANNEL_DENIED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Submit channel not allowed",
+      "hint": "Let the viewer submit with the shell's trusted Submit; this host doesn't take submissions from artifact code.",
+      "explanation": "A submission comes through one of two channels (D40): the shell's trusted Submit (`shell`), which only a person can press, or the artifact's own code (`artifact`, `useSubmit().submit()` and `useChoice().choose()`). The host decides which it accepts (D108): through `HomeConfig.submitChannels` for the home, or its `trustedControls` port for each artifact. This view allows only the other channel, so Mostra refused the submit or the choice. `useSubmit().allowed` is `false` in such a view.",
+      "fix": "Ask the viewer to press the shell's Submit (relabel it with `useSubmitControl`), and use `useChoice(id, { candidates })` to have the shell render a trusted Choose. Check `allowed` before showing an in-page submit button."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_NOT_FOUND",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "No such submission",
+      "hint": "Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.",
+      "explanation": "The artifact has no submission yet, or none with the ID asked for. Submissions are durable once made, so this means none was made (or the ID belongs to another artifact or home).",
+      "fix": "Run `mostra wait <artifact> --until submitted` to block until the viewer submits, then read the results. List the artifact's submissions through `submission.created` events."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_POLICY_NONE",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Artifact takes no submissions",
+      "hint": "Exchange data through artifact state, actions and signals; this artifact has no submissions.",
+      "explanation": "The artifact's submission policy is `none` (D63): long-lived artifacts such as dashboards and task managers talk to agents through artifact state, actions, signals and events, and the shell shows no Submit control. Mostra refuses a submit, and a `wait --until submitted`, on such an artifact.",
+      "fix": "Wait for a signal (`--until signal:<name>`), a state change (`--until state:<field>`) or an event instead, and read state with `mostra state get`. To collect submissions, publish with policy `once` or `epochs`."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_REVISION_MOVED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Draft changed before submit",
+      "hint": "Reload the draft, check what changed, and submit again with its current revision.",
+      "explanation": "A submit names the draft revision the viewer saw (`expectedRevision`), and the draft has changed since: another tab, device or writer saved an edit. Mostra never makes a submission from content the viewer didn't see (FAILURE_MODEL §4), so it refuses. The message names the draft's current revision.",
+      "fix": "Let the page reload the draft so the viewer sees exactly what will be sent, then submit with the new revision. The shell and the client runtime flush pending saves before they submit, which makes this rare."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_SIGNAL_INVALID",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Invalid signal",
+      "hint": "Name signals with letters, digits, `.`, `_` and `-`, and keep their payload under 64 KiB of JSON.",
+      "explanation": "A signal names something the artifact wants a host's attention for, such as `ping-agent`. Its name is 1 to 64 characters of letters, digits, `.`, `_` and `-`, starting with a letter or digit, and its payload is JSON of at most 64 KiB. This one broke one of those rules. The name `submit` is reserved for submissions.",
+      "fix": "Rename the signal or shrink its payload; put large data into a field or artifact state and send its ID in the payload."
+    },
+    {
+      "code": "MOSTRA_SUBMIT_VIEW_INVALID",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Unknown view",
+      "hint": "Send the view ID this page was opened with.",
+      "explanation": "Mutations and submits name the view they come from, the one the shell created when it opened this frame. The view named doesn't exist, belongs to another artifact, or belongs to another viewer. Mostra binds every submission to the exact version its view showed, so it refuses a view it can't place.",
+      "fix": "Use the `viewId` the shell handed this frame. A page opened outside Mostra's shell has no view and can't submit."
+    },
+    {
+      "code": "MOSTRA_TARGET_UNAVAILABLE",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Not available in this delivery target",
+      "hint": "Open the published version through Mostra to use this feature.",
+      "explanation": "The page called something that needs Mostra's server, such as a server function, and this delivery target doesn't provide it: a static export, a file opened from disk, or a runtime without server support. The page keeps working without it.",
+      "fix": "Open the artifact through its Mostra link, where server functions, submissions and live data are available. In a static export, handle the error so the page explains what isn't available."
+    },
+    {
+      "code": "MOSTRA_TYPE_ERROR",
+      "severity": "error",
+      "phase": "compile",
+      "title": "Type error",
+      "hint": "Fix the type error at the reported location; the message carries TypeScript's code and text.",
+      "explanation": "TypeScript's checker (`tsc --noEmit`, TypeScript 7) found an error in the artifact's code. Verify checks with the artifact's own `tsconfig.json` when it has one, else in strict mode without the unused-variable rules, and resolves imports exactly as the build does. MDX isn't checked.",
+      "fix": "Open the file at the reported line and fix the code, for example a missing property, a wrong argument type or a misspelled import."
+    },
+    {
+      "code": "MOSTRA_TYPE_UNTYPED_PACKAGE",
+      "severity": "warning",
+      "phase": "compile",
+      "title": "Package without type declarations",
+      "hint": "Nothing breaks: the package works without types; declare a module for it if you want them checked.",
+      "explanation": "The artifact imports a package that ships no type declarations (TypeScript's TS7016). The package still builds and runs, so this is a warning: its values are typed `any`.",
+      "fix": "Optionally add a declaration file such as `declare module \"<package>\";`, or a typed wrapper, to the artifact."
+    },
+    {
+      "code": "MOSTRA_VERIFY_ACTION_SKIPPED",
+      "severity": "hint",
+      "phase": "smoke",
+      "title": "Action skipped in verify",
+      "hint": "To have verify run this action, check `dryRun()` from `@mostra/server` in it and return early without its side effects when it is true.",
+      "explanation": "Verify's smoke test never runs a server function that doesn't check `dryRun()` (D55). When the page called one, verify refused the call instead: the page's `run()` or server reference rejected with a `MostraError` carrying this code, as it would for any failed action. The verdict lists every such function in `smoke.skippedActions`. Nothing was sent, written or charged.",
+      "fix": "Nothing is wrong. To have verify exercise the action, add `if (dryRun()) return <a representative result>;` before its side effects; verify then runs it with `dryRun()` true."
+    },
+    {
+      "code": "MOSTRA_VERIFY_BASELINE_MISSING",
+      "severity": "hint",
+      "phase": "regression",
+      "title": "Baseline version's build is missing",
+      "hint": "Nothing to fix here; publish again to give later versions a baseline.",
+      "explanation": "The newest version that passed verify is recorded in the ledger, but its stored build isn't in the home any more, so verify couldn't render it and ran no regression stage.",
+      "fix": "Nothing is required. A version published from this source becomes the next baseline."
+    },
+    {
+      "code": "MOSTRA_VERIFY_CRASHED",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Verify runner crashed",
+      "hint": "Verify again; if it keeps crashing, report the message with `mostra doctor`'s output.",
+      "explanation": "The verify runner, the child process that drives the browser, stopped before it finished (FAILURE_MODEL §2). The message carries its last lines of output. Nothing was published, and the next verify starts a fresh runner.",
+      "fix": "Verify again. A crash that repeats for the same artifact can come from a page that exhausts the browser's memory; one that repeats for every artifact means the runtime's browser is damaged."
+    },
+    {
+      "code": "MOSTRA_VERIFY_LIVE_FAILED",
+      "severity": "warning",
+      "phase": "runtime",
+      "title": "Live source failed during verify",
+      "hint": "Check the live source's message: it failed while verify rendered the page, which may be the environment rather than the code.",
+      "explanation": "A live source's producer (`live.ts`) threw or couldn't reach its data while verify rendered the page. Verify runs producers for real, since they only read, so a failure can come from the environment (no network, a service that is down) as well as from the code. The page shows `useLive`'s `error` meanwhile.",
+      "fix": "Read the message. If the producer itself is wrong, fix it; if the data source was unreachable, verify again when it is back."
+    },
+    {
+      "code": "MOSTRA_VERIFY_NO_BASELINE",
+      "severity": "hint",
+      "phase": "regression",
+      "title": "No earlier passing version",
+      "hint": "Nothing to fix: the next version will be compared with this one once it is published.",
+      "explanation": "Verify compares a source with the newest published version of its artifact whose verdict passed. This artifact has none yet (it is new, or every earlier version was published with `--force`), so no regression stage ran.",
+      "fix": "Nothing is required."
+    },
+    {
+      "code": "MOSTRA_VERIFY_SECRET_MISSING",
+      "severity": "warning",
+      "phase": "runtime",
+      "title": "Secret missing during verify",
+      "hint": "Set the secret with `mostra secret set <NAME>` if the artifact needs it; verify reports it as the environment, not the code.",
+      "explanation": "Server code asked for a secret (`secret()`) that neither the host, the artifact's secrets nor the home's hold, while verify ran it. Secrets are part of the environment, so verify reports this as a warning rather than an error.",
+      "fix": "Run `mostra secret set <NAME>` (for the artifact or the home) with the value the code needs, then verify again."
+    },
+    {
+      "code": "MOSTRA_VERIFY_SKIP_CONSEQUENCE",
+      "severity": "hint",
+      "phase": "smoke",
+      "title": "Page reaction to a skipped action",
+      "hint": "Nothing to fix: this followed from verify skipping an action, which a viewer's page never meets.",
+      "explanation": "After verify refused a server function that doesn't check `dryRun()`, the page reported an error: an unhandled rejection, an error a boundary caught, or a console error while it settled. It follows from verify's synthetic refusal, not from a defect a viewer would meet, so it is reported as a hint naming the skipped action.",
+      "fix": "Nothing is required. To let verify see the action's real result, opt it into the smoke test with `dryRun()`."
+    },
+    {
+      "code": "MOSTRA_VERIFY_TIMEOUT",
+      "severity": "error",
+      "phase": "runtime",
+      "title": "Verify ran out of time",
+      "hint": "Make the page render without waiting on slow work at load, then verify again.",
+      "explanation": "Verify allows 120 s for everything after the build: booting the sandbox, rendering each viewport, the smoke test and the regression stage. This run went past it, so its verdict is partial: the message names the stage it reached. A partial run can't vouch for the page, so this is an error, and the verdict isn't cached.",
+      "fix": "Look for work the page does at load that takes long (large data, long animations, requests that never answer) and defer it, then verify again. On a heavily loaded machine, verifying again may be enough."
+    }
+  ]
+}