@mostra/cli 0.0.0-stage → 0.2.0

package/dist/reference/errors/MOSTRA_A11Y_MINOR.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_A11Y_MINOR
+severity: hint
+phase: a11y
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_A11Y_MINOR
+
+Minor accessibility problem. Severity: hint. Phase: a11y.
+
+## What it means
+
+axe-core found a problem it rates moderate or minor. The message names axe's rule and the elements.
+
+## How to fix it
+
+Optionally follow the rule's advice.
+
+## Hint
+
+Read axe's description of the rule in the message.

package/dist/reference/errors/MOSTRA_A11Y_SERIOUS.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_A11Y_SERIOUS
+severity: warning
+phase: a11y
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_A11Y_SERIOUS
+
+Serious accessibility problem. Severity: warning. Phase: a11y.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Follow the rule's advice for each element named, for example add an `aria-label` to an icon button.
+
+## Hint
+
+Read axe's description of the rule in the message; it names the elements it found.

package/dist/reference/errors/MOSTRA_ACTION_CANCELLED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_CANCELLED
+severity: warning
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_CANCELLED
+
+Action run cancelled. Severity: warning. Phase: runtime.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Nothing to fix. Pass `abortSignal` from `@mostra/server` to `fetch` and other cancellable calls so cancelling stops the work.
+
+## Hint
+
+Start the action again if it should still run.

package/dist/reference/errors/MOSTRA_ACTION_EVENT_INVALID.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_EVENT_INVALID
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_EVENT_INVALID
+
+Host event type or payload invalid. Severity: error. Phase: runtime.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Name the event `host.<name>` with 1 to 64 letters, digits, `.`, `_` and `-`, and keep its payload JSON of at most 64 KiB.

package/dist/reference/errors/MOSTRA_ACTION_EXPORT_INVALID.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_EXPORT_INVALID
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_EXPORT_INVALID
+
+Server module exports something other than an async function. Severity: error. Phase: compile.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Make the function `async`, or move the value to a separate module without the directive and import it from both sides.
+
+## Hint
+
+Export only async functions from a "use server" module; move other exports to an ordinary module.

package/dist/reference/errors/MOSTRA_ACTION_INTERRUPTED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_INTERRUPTED
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_INTERRUPTED
+
+Action run interrupted. Severity: error. Phase: runtime.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Check the run's effects at their provider, then start it again with a new key if it should run again.

package/dist/reference/errors/MOSTRA_ACTION_RUN_NOT_FOUND.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_RUN_NOT_FOUND
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_RUN_NOT_FOUND
+
+No such action run. Severity: error. Phase: runtime.
+
+## What it means
+
+A page asked for or cancelled an action run that this artifact doesn't have, or one started from another artifact.
+
+## How to fix it
+
+Use the run IDs `useAction` reports. A page that keeps run IDs itself should drop IDs from other artifacts.
+
+## Hint
+
+Start the action again; the run ID names no run of this artifact.

package/dist/reference/errors/MOSTRA_ACTION_THREW.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_THREW
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_THREW
+
+Server function threw. Severity: error. Phase: runtime.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Read the run's log for the stack, then fix the server function or catch the error and return a result instead.

package/dist/reference/errors/MOSTRA_ACTION_TOO_LARGE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_TOO_LARGE
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_TOO_LARGE
+
+Server function arguments or result too large. Severity: error. Phase: runtime.
+
+## What it means
+
+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`.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Return or pass less data: page through it, or write it to artifact state or a live source instead.

package/dist/reference/errors/MOSTRA_ACTION_UNKNOWN_FUNCTION.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_UNKNOWN_FUNCTION
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_UNKNOWN_FUNCTION
+
+No such server function in this version. Severity: error. Phase: runtime.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Republish the artifact and reload the page. Call server functions by importing them from their `"use server"` module, never by ID.
+
+## Hint
+
+Publish the artifact again so the page and its server code come from the same version.

package/dist/reference/errors/MOSTRA_ACTION_UNSERIALIZABLE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ACTION_UNSERIALIZABLE
+severity: error
+phase: runtime
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ACTION_UNSERIALIZABLE
+
+Server function argument or result outside React's serializable types. Severity: error. Phase: runtime.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Pass and return only plain objects, arrays, primitives, Map, Set, Date, typed arrays, FormData and promises; convert class instances to plain objects first.

package/dist/reference/errors/MOSTRA_ARTIFACT_DIR_NOT_EMPTY.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_DIR_NOT_EMPTY
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_DIR_NOT_EMPTY
+
+Directory isn't empty. Severity: error. Phase: host.
+
+## What it means
+
+Creating an artifact writes its entry into a directory, and the directory given already has files. Mostra never overwrites them.
+
+## How to fix it
+
+Pass a path that doesn't exist yet or an empty directory. To make existing files an artifact, add the entry yourself and publish.
+
+## Hint
+
+Choose a new or empty directory for the artifact.

package/dist/reference/errors/MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS
+severity: error
+phase: manifest
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS
+
+More than one entry file. Severity: error. Phase: manifest.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Keep the entry you mean and rename the others, for example into `components/`.
+
+## Hint
+
+Keep one entry file in the directory and rename or remove the others.

package/dist/reference/errors/MOSTRA_ARTIFACT_NOT_FOUND.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_NOT_FOUND
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_NOT_FOUND
+
+Artifact not found. Severity: error. Phase: host.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Check the artifact ID or source path, or list the home's artifacts with `mostra list`.

package/dist/reference/errors/MOSTRA_ARTIFACT_NO_ENTRY.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_NO_ENTRY
+severity: error
+phase: manifest
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_NO_ENTRY
+
+No entry file. Severity: error. Phase: manifest.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Add `index.tsx` or `index.mdx` to the directory, or publish a single `.tsx` or `.mdx` file.

package/dist/reference/errors/MOSTRA_ARTIFACT_NO_PAGE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_NO_PAGE
+severity: error
+phase: manifest
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_NO_PAGE
+
+Entry has no page. Severity: error. Phase: manifest.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Add `export default function Page() { ... }` to the entry, or move pages into `pages/index.tsx`, `pages/settings.tsx` and so on.
+
+## Hint
+
+Export the page component as the entry's default export, or add a `pages/` folder.

package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_MISSING.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_SOURCE_MISSING
+severity: error
+phase: publish
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_SOURCE_MISSING
+
+Artifact source missing. Severity: error. Phase: publish.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Pass the path where the source lives now. Its manifest `id`, if it has one, keeps the artifact identity at the new path.
+
+## Hint
+
+Publish from the artifact's source path, or restore the directory the message names.

package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_UNREADABLE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_SOURCE_UNREADABLE
+severity: error
+phase: publish
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_SOURCE_UNREADABLE
+
+Artifact source can't be read. Severity: error. Phase: publish.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Make the named file readable, rename one of two clashing names, or exclude the file with `.mostraignore` in the artifact's root.
+
+## Hint
+
+Fix the file or directory the message names so your user can read it, then publish again.

package/dist/reference/errors/MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN
+
+Unknown template. Severity: error. Phase: host.
+
+## What it means
+
+The template named isn't one this runtime provides. Without a template, Mostra writes a minimal entry with a generated artifact ID.
+
+## How to fix it
+
+Leave out the template, or use one of the templates of this release.
+
+## Hint
+
+Create the artifact without a template, or use a template this Mostra release provides.

package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_COLLECTED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_VERSION_COLLECTED
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_VERSION_COLLECTED
+
+Version collected. Severity: error. Phase: host.
+
+## What it means
+
+`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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Open the artifact's latest version, or publish this version's source again to restore its files.

package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_NOT_FOUND.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_ARTIFACT_VERSION_NOT_FOUND
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_ARTIFACT_VERSION_NOT_FOUND
+
+No such version. Severity: error. Phase: host.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Name a version the artifact has (`artifact/get` lists them), or leave the version out for the latest.

package/dist/reference/errors/MOSTRA_BUILD_CRASHED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_BUILD_CRASHED
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_BUILD_CRASHED
+
+Builder crashed. Severity: error. Phase: compile.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Publish again; if it crashes again, report the builder's last output from the message.

package/dist/reference/errors/MOSTRA_BUILD_FAILED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_BUILD_FAILED
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_BUILD_FAILED
+
+Build failed. Severity: error. Phase: compile.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Fix the error at the reported location, then publish again.

package/dist/reference/errors/MOSTRA_BUILD_TIMEOUT.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_BUILD_TIMEOUT
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_BUILD_TIMEOUT
+
+Build timed out. Severity: error. Phase: compile.
+
+## What it means
+
+The build took longer than its limit (180 seconds) and was stopped. Nothing was published.
+
+## How to fix it
+
+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.
+
+## Hint
+
+Make the build smaller, for example by moving large data into `public/`, then publish again.

package/dist/reference/errors/MOSTRA_BUILD_UNRESOLVED.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_BUILD_UNRESOLVED
+severity: error
+phase: compile
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_BUILD_UNRESOLVED
+
+Import can't be resolved. Severity: error. Phase: compile.
+
+## What it means
+
+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.
+
+## How to fix it
+
+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>`.
+
+## Hint
+
+Correct the import path, or import the package from the warm set or add it with `mostra add`.

package/dist/reference/errors/MOSTRA_CLI_CONFIG_UNWRITABLE.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_CLI_CONFIG_UNWRITABLE
+severity: error
+phase: platform
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_CLI_CONFIG_UNWRITABLE
+
+The CLI's config directory can't be written. Severity: error. Phase: platform.
+
+## What it means
+
+`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.
+
+## How to fix it
+
+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.
+
+## 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.

package/dist/reference/errors/MOSTRA_CLI_UNKNOWN_COMMAND.md

@@ -0,0 +1,23 @@
+---
+code: MOSTRA_CLI_UNKNOWN_COMMAND
+severity: error
+phase: host
+---
+
+<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
+
+# MOSTRA_CLI_UNKNOWN_COMMAND
+
+Unknown command. Severity: error. Phase: host.
+
+## What it means
+
+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.
+
+## How to fix it
+
+Run one of the listed commands. `mostra --help` lists every command with a one-line summary.
+
+## Hint
+
+Pick one of the commands this message lists; `mostra --help` describes each.