@mostra/runtime 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. package/dist/bin.js +4058 -310
  2. package/dist/bin.js.map +1 -1
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/{instance-FExcyENK.js → instance-DCiUHvgZ.js} +682 -47
  6. package/dist/instance-DCiUHvgZ.js.map +1 -0
  7. package/dist/reference/cli.md +1322 -0
  8. package/dist/reference/diagnostics.json +1552 -0
  9. package/dist/reference/errors/MOSTRA_A11Y_MINOR.md +23 -0
  10. package/dist/reference/errors/MOSTRA_A11Y_SERIOUS.md +23 -0
  11. package/dist/reference/errors/MOSTRA_ACTION_CANCELLED.md +23 -0
  12. package/dist/reference/errors/MOSTRA_ACTION_EVENT_INVALID.md +23 -0
  13. package/dist/reference/errors/MOSTRA_ACTION_EXPORT_INVALID.md +23 -0
  14. package/dist/reference/errors/MOSTRA_ACTION_INTERRUPTED.md +23 -0
  15. package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
  16. package/dist/reference/errors/MOSTRA_ACTION_RUN_NOT_FOUND.md +23 -0
  17. package/dist/reference/errors/MOSTRA_ACTION_THREW.md +23 -0
  18. package/dist/reference/errors/MOSTRA_ACTION_TOO_LARGE.md +23 -0
  19. package/dist/reference/errors/MOSTRA_ACTION_UNKNOWN_FUNCTION.md +23 -0
  20. package/dist/reference/errors/MOSTRA_ACTION_UNSERIALIZABLE.md +23 -0
  21. package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
  22. package/dist/reference/errors/MOSTRA_ARTIFACT_DIR_NOT_EMPTY.md +23 -0
  23. package/dist/reference/errors/MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS.md +23 -0
  24. package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
  25. package/dist/reference/errors/MOSTRA_ARTIFACT_NOT_FOUND.md +23 -0
  26. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_ENTRY.md +23 -0
  27. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_PAGE.md +23 -0
  28. package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
  29. package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
  30. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_MISSING.md +23 -0
  31. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_UNREADABLE.md +23 -0
  32. package/dist/reference/errors/MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN.md +23 -0
  33. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_COLLECTED.md +23 -0
  34. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_NOT_FOUND.md +23 -0
  35. package/dist/reference/errors/MOSTRA_BUILD_CRASHED.md +23 -0
  36. package/dist/reference/errors/MOSTRA_BUILD_FAILED.md +23 -0
  37. package/dist/reference/errors/MOSTRA_BUILD_TIMEOUT.md +23 -0
  38. package/dist/reference/errors/MOSTRA_BUILD_UNRESOLVED.md +23 -0
  39. package/dist/reference/errors/MOSTRA_CLI_CONFIG_UNWRITABLE.md +23 -0
  40. package/dist/reference/errors/MOSTRA_CLI_UNKNOWN_COMMAND.md +23 -0
  41. package/dist/reference/errors/MOSTRA_CLI_USAGE.md +23 -0
  42. package/dist/reference/errors/MOSTRA_CONSOLE_ERROR.md +23 -0
  43. package/dist/reference/errors/MOSTRA_CONSOLE_WARNING.md +23 -0
  44. package/dist/reference/errors/MOSTRA_DEP_INSTALL_FAILED.md +23 -0
  45. package/dist/reference/errors/MOSTRA_DEP_MISSING.md +23 -0
  46. package/dist/reference/errors/MOSTRA_DEP_NOT_FOUND.md +23 -0
  47. package/dist/reference/errors/MOSTRA_DEP_OFFLINE.md +23 -0
  48. package/dist/reference/errors/MOSTRA_DEP_SPEC_INVALID.md +23 -0
  49. package/dist/reference/errors/MOSTRA_DEP_TIMEOUT.md +23 -0
  50. package/dist/reference/errors/MOSTRA_DEP_WARM_CONFLICT.md +23 -0
  51. package/dist/reference/errors/MOSTRA_ENV_BIND_FAILED.md +23 -0
  52. package/dist/reference/errors/MOSTRA_ENV_BROWSER_MISSING.md +23 -0
  53. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED.md +23 -0
  54. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_INVALID.md +23 -0
  55. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_UNAVAILABLE.md +23 -0
  56. package/dist/reference/errors/MOSTRA_ENV_HELPER_MISSING.md +23 -0
  57. package/dist/reference/errors/MOSTRA_ENV_NODE_UNSUPPORTED.md +23 -0
  58. package/dist/reference/errors/MOSTRA_ENV_PORT_TAKEN.md +23 -0
  59. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
  60. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_MISSING.md +23 -0
  61. package/dist/reference/errors/MOSTRA_ENV_SERVICE_FAILED.md +23 -0
  62. package/dist/reference/errors/MOSTRA_ENV_SHELL_MISSING.md +23 -0
  63. package/dist/reference/errors/MOSTRA_ENV_WARM_MISSING.md +23 -0
  64. package/dist/reference/errors/MOSTRA_FIELD_CONFLICT.md +23 -0
  65. package/dist/reference/errors/MOSTRA_FIELD_DUPLICATE_ID.md +23 -0
  66. package/dist/reference/errors/MOSTRA_FIELD_ID_INVALID.md +23 -0
  67. package/dist/reference/errors/MOSTRA_FIELD_ID_UNSTABLE.md +23 -0
  68. package/dist/reference/errors/MOSTRA_FIELD_MUTATION_ID_REUSED.md +23 -0
  69. package/dist/reference/errors/MOSTRA_FIELD_SHARED.md +23 -0
  70. package/dist/reference/errors/MOSTRA_FIELD_TOO_LARGE.md +23 -0
  71. package/dist/reference/errors/MOSTRA_FIELD_UNBOUND.md +23 -0
  72. package/dist/reference/errors/MOSTRA_HOME_DISK_FULL.md +23 -0
  73. package/dist/reference/errors/MOSTRA_HOME_GC_INCOMPLETE.md +23 -0
  74. package/dist/reference/errors/MOSTRA_HOME_GONE.md +23 -0
  75. package/dist/reference/errors/MOSTRA_HOME_INTEGRITY.md +23 -0
  76. package/dist/reference/errors/MOSTRA_HOME_LEDGER_UNREADABLE.md +23 -0
  77. package/dist/reference/errors/MOSTRA_HOME_LOCKED.md +23 -0
  78. package/dist/reference/errors/MOSTRA_HOME_MISMATCH.md +23 -0
  79. package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
  80. package/dist/reference/errors/MOSTRA_HOME_NOT_ALWAYS_ON.md +23 -0
  81. package/dist/reference/errors/MOSTRA_HOME_NOT_OWNED.md +23 -0
  82. package/dist/reference/errors/MOSTRA_HOME_SOCKET_TOO_LONG.md +23 -0
  83. package/dist/reference/errors/MOSTRA_HOME_TOO_NEW.md +23 -0
  84. package/dist/reference/errors/MOSTRA_HOST_CONNECTION_CLOSED.md +23 -0
  85. package/dist/reference/errors/MOSTRA_HOST_CURSOR_COMPACTED.md +23 -0
  86. package/dist/reference/errors/MOSTRA_HOST_IDENTITY_UNAVAILABLE.md +23 -0
  87. package/dist/reference/errors/MOSTRA_HOST_INITIALIZE_ORDER.md +23 -0
  88. package/dist/reference/errors/MOSTRA_HOST_INTERNAL_ERROR.md +23 -0
  89. package/dist/reference/errors/MOSTRA_HOST_INVALID_PARAMS.md +23 -0
  90. package/dist/reference/errors/MOSTRA_HOST_MALFORMED.md +23 -0
  91. package/dist/reference/errors/MOSTRA_HOST_MESSAGE_TOO_LARGE.md +23 -0
  92. package/dist/reference/errors/MOSTRA_HOST_METHOD_UNKNOWN.md +23 -0
  93. package/dist/reference/errors/MOSTRA_HOST_NOTIFICATION_UNSUPPORTED.md +23 -0
  94. package/dist/reference/errors/MOSTRA_HOST_PORT_UNSUPPORTED.md +23 -0
  95. package/dist/reference/errors/MOSTRA_HOST_REQUEST_ID_REUSED.md +23 -0
  96. package/dist/reference/errors/MOSTRA_HOST_REVISION_UNSUPPORTED.md +23 -0
  97. package/dist/reference/errors/MOSTRA_HOST_SHUTDOWN_REFUSED.md +23 -0
  98. package/dist/reference/errors/MOSTRA_HOST_SUBSCRIPTION_UNKNOWN.md +23 -0
  99. package/dist/reference/errors/MOSTRA_HOST_TIMEOUT.md +23 -0
  100. package/dist/reference/errors/MOSTRA_HYGIENE_CONTENT_TYPE.md +23 -0
  101. package/dist/reference/errors/MOSTRA_HYGIENE_CSRF_MISSING.md +23 -0
  102. package/dist/reference/errors/MOSTRA_HYGIENE_FRAME_SESSION.md +23 -0
  103. package/dist/reference/errors/MOSTRA_HYGIENE_HEADERS_TOO_LARGE.md +23 -0
  104. package/dist/reference/errors/MOSTRA_HYGIENE_HOST_REFUSED.md +23 -0
  105. package/dist/reference/errors/MOSTRA_HYGIENE_NOT_SERVED.md +23 -0
  106. package/dist/reference/errors/MOSTRA_HYGIENE_ORIGIN_REFUSED.md +23 -0
  107. package/dist/reference/errors/MOSTRA_HYGIENE_RATE_LIMITED.md +23 -0
  108. package/dist/reference/errors/MOSTRA_HYGIENE_REQUEST_MALFORMED.md +23 -0
  109. package/dist/reference/errors/MOSTRA_HYGIENE_SCOPE_DENIED.md +23 -0
  110. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_CONFLICT.md +23 -0
  111. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_MISSING.md +23 -0
  112. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_INVALID.md +23 -0
  113. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_REVOKED.md +23 -0
  114. package/dist/reference/errors/MOSTRA_LIVE_SOURCE_FAILED.md +23 -0
  115. package/dist/reference/errors/MOSTRA_LIVE_TOO_LARGE.md +23 -0
  116. package/dist/reference/errors/MOSTRA_MANIFEST_INVALID.md +23 -0
  117. package/dist/reference/errors/MOSTRA_MANIFEST_NOT_LITERAL.md +23 -0
  118. package/dist/reference/errors/MOSTRA_MANIFEST_UNKNOWN_KEY.md +23 -0
  119. package/dist/reference/errors/MOSTRA_NETWORK_EXTERNAL_FAILED.md +23 -0
  120. package/dist/reference/errors/MOSTRA_NETWORK_REQUEST_FAILED.md +23 -0
  121. package/dist/reference/errors/MOSTRA_PLATFORM_UNSUPPORTED.md +23 -0
  122. package/dist/reference/errors/MOSTRA_PUBLISH_ID_CONFLICT.md +23 -0
  123. package/dist/reference/errors/MOSTRA_PUBLISH_SOURCE_CHANGED.md +23 -0
  124. package/dist/reference/errors/MOSTRA_PUBLISH_VERIFY_FAILED.md +23 -0
  125. package/dist/reference/errors/MOSTRA_REGRESSION_ACTION_REMOVED.md +23 -0
  126. package/dist/reference/errors/MOSTRA_REGRESSION_ARIA.md +23 -0
  127. package/dist/reference/errors/MOSTRA_REGRESSION_FIELD_REMOVED.md +23 -0
  128. package/dist/reference/errors/MOSTRA_REGRESSION_LIVE_REMOVED.md +23 -0
  129. package/dist/reference/errors/MOSTRA_REGRESSION_PAGE_REMOVED.md +23 -0
  130. package/dist/reference/errors/MOSTRA_REGRESSION_PIXELS.md +23 -0
  131. package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
  132. package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
  133. package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
  134. package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.md +23 -0
  135. package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
  136. package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
  137. package/dist/reference/errors/MOSTRA_REMOTE_NO_INSTANCE.md +23 -0
  138. package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
  139. package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
  140. package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
  141. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
  142. package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
  143. package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
  144. package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
  145. package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
  146. package/dist/reference/errors/MOSTRA_RUNTIME_BLANK.md +23 -0
  147. package/dist/reference/errors/MOSTRA_RUNTIME_NOT_READY.md +23 -0
  148. package/dist/reference/errors/MOSTRA_RUNTIME_PAGE_ERROR.md +23 -0
  149. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_CRASHED.md +23 -0
  150. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_PARKED.md +23 -0
  151. package/dist/reference/errors/MOSTRA_SECRET_MISSING.md +23 -0
  152. package/dist/reference/errors/MOSTRA_SHARE_NOT_ENABLED.md +23 -0
  153. package/dist/reference/errors/MOSTRA_SHARE_NOT_FOUND.md +23 -0
  154. package/dist/reference/errors/MOSTRA_SHARE_PORTS_EXHAUSTED.md +23 -0
  155. package/dist/reference/errors/MOSTRA_SHARE_TOOL_MISSING.md +23 -0
  156. package/dist/reference/errors/MOSTRA_SHARE_TOOL_NOT_READY.md +23 -0
  157. package/dist/reference/errors/MOSTRA_SHARE_TTL_INVALID.md +23 -0
  158. package/dist/reference/errors/MOSTRA_SHARE_TUNNEL_FAILED.md +23 -0
  159. package/dist/reference/errors/MOSTRA_SMOKE_BUDGET.md +23 -0
  160. package/dist/reference/errors/MOSTRA_SMOKE_NO_EFFECT.md +23 -0
  161. package/dist/reference/errors/MOSTRA_SUBMIT_ALREADY.md +23 -0
  162. package/dist/reference/errors/MOSTRA_SUBMIT_BLOCKED.md +23 -0
  163. package/dist/reference/errors/MOSTRA_SUBMIT_CHANNEL_DENIED.md +23 -0
  164. package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +23 -0
  165. package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
  166. package/dist/reference/errors/MOSTRA_SUBMIT_POLICY_NONE.md +23 -0
  167. package/dist/reference/errors/MOSTRA_SUBMIT_REVISION_MOVED.md +23 -0
  168. package/dist/reference/errors/MOSTRA_SUBMIT_SIGNAL_INVALID.md +23 -0
  169. package/dist/reference/errors/MOSTRA_SUBMIT_VIEW_INVALID.md +23 -0
  170. package/dist/reference/errors/MOSTRA_TARGET_UNAVAILABLE.md +23 -0
  171. package/dist/reference/errors/MOSTRA_TYPE_ERROR.md +23 -0
  172. package/dist/reference/errors/MOSTRA_TYPE_UNTYPED_PACKAGE.md +23 -0
  173. package/dist/reference/errors/MOSTRA_VERIFY_ACTION_SKIPPED.md +23 -0
  174. package/dist/reference/errors/MOSTRA_VERIFY_BASELINE_MISSING.md +23 -0
  175. package/dist/reference/errors/MOSTRA_VERIFY_CRASHED.md +23 -0
  176. package/dist/reference/errors/MOSTRA_VERIFY_LIVE_FAILED.md +23 -0
  177. package/dist/reference/errors/MOSTRA_VERIFY_NO_BASELINE.md +23 -0
  178. package/dist/reference/errors/MOSTRA_VERIFY_SECRET_MISSING.md +23 -0
  179. package/dist/reference/errors/MOSTRA_VERIFY_SKIP_CONSEQUENCE.md +23 -0
  180. package/dist/reference/errors/MOSTRA_VERIFY_TIMEOUT.md +23 -0
  181. package/dist/reference/self-hosting.md +130 -0
  182. package/dist/reference/telemetry.md +84 -0
  183. package/dist/skill/SKILL.md +122 -0
  184. package/dist/skill/assets/examples/dashboard/index.tsx +161 -0
  185. package/dist/skill/assets/examples/dashboard/live.ts +25 -0
  186. package/dist/skill/assets/examples/dashboard/styles.css +125 -0
  187. package/dist/skill/assets/examples/decision/index.tsx +95 -0
  188. package/dist/skill/assets/examples/decision/styles.css +125 -0
  189. package/dist/skill/assets/examples/inbox/actions.ts +23 -0
  190. package/dist/skill/assets/examples/inbox/index.tsx +109 -0
  191. package/dist/skill/assets/examples/inbox/styles.css +125 -0
  192. package/dist/skill/assets/studio.css +125 -0
  193. package/dist/skill/references/answers.md +217 -0
  194. package/dist/skill/references/design.md +154 -0
  195. package/dist/skill/references/libraries.md +167 -0
  196. package/dist/skill/references/long-lived.md +148 -0
  197. package/dist/skill/references/mcp.md +68 -0
  198. package/dist/skill/references/page.md +131 -0
  199. package/dist/skill/references/server.md +146 -0
  200. package/dist/skill/references/sharing.md +123 -0
  201. package/dist/skill/references/verify.md +71 -0
  202. package/package.json +10 -5
  203. package/src/gateway/actions.ts +20 -0
  204. package/src/gateway/browser.ts +44 -0
  205. package/src/gateway/capabilities.ts +8 -0
  206. package/src/gateway/http.ts +12 -1
  207. package/src/gateway/index.ts +170 -5
  208. package/src/gateway/listener.ts +31 -6
  209. package/src/gateway/routes.ts +8 -0
  210. package/src/gc/index.ts +5 -0
  211. package/src/instance/index.ts +20 -1
  212. package/src/interaction/index.ts +60 -0
  213. package/src/interaction/pause.ts +106 -0
  214. package/src/interaction/submissions.ts +42 -1
  215. package/src/interaction/viewers.ts +34 -1
  216. package/src/ledger/index.ts +20 -1
  217. package/src/ledger/migrations.ts +51 -0
  218. package/src/link/author.ts +215 -0
  219. package/src/link/hosted.ts +37 -1
  220. package/src/link/http.ts +6 -1
  221. package/src/link/index.ts +3 -1
  222. package/src/link/manager.ts +138 -34
  223. package/src/protocol-server/client.ts +53 -0
  224. package/src/protocol-server/index.ts +1 -1
  225. package/src/server/api.ts +514 -72
  226. package/src/server/auth.ts +600 -74
  227. package/src/server/authorize.ts +816 -0
  228. package/src/server/clients.ts +235 -0
  229. package/src/server/config.ts +7 -0
  230. package/src/server/data.ts +59 -1
  231. package/src/server/directory.ts +69 -0
  232. package/src/server/feed.ts +191 -0
  233. package/src/server/handle.ts +172 -0
  234. package/src/server/hosted-pages.ts +532 -0
  235. package/src/server/hosted.ts +519 -18
  236. package/src/server/index.ts +343 -61
  237. package/src/server/mcp.ts +330 -0
  238. package/src/server/metering.ts +156 -0
  239. package/src/server/oauth-clients.ts +510 -0
  240. package/src/server/operator.ts +498 -0
  241. package/src/server/providers.ts +284 -0
  242. package/src/server/remove.ts +148 -0
  243. package/src/server/routing.ts +275 -0
  244. package/src/verify/runner.ts +23 -2
  245. package/dist/instance-FExcyENK.js.map +0 -1
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_TYPE_ERROR
3
+ severity: error
4
+ phase: compile
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_TYPE_ERROR
10
+
11
+ Type error. Severity: error. Phase: compile.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ Open the file at the reported line and fix the code, for example a missing property, a wrong argument type or a misspelled import.
20
+
21
+ ## Hint
22
+
23
+ Fix the type error at the reported location; the message carries TypeScript's code and text.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_TYPE_UNTYPED_PACKAGE
3
+ severity: warning
4
+ phase: compile
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_TYPE_UNTYPED_PACKAGE
10
+
11
+ Package without type declarations. Severity: warning. Phase: compile.
12
+
13
+ ## What it means
14
+
15
+ 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`.
16
+
17
+ ## How to fix it
18
+
19
+ Optionally add a declaration file such as `declare module "<package>";`, or a typed wrapper, to the artifact.
20
+
21
+ ## Hint
22
+
23
+ Nothing breaks: the package works without types; declare a module for it if you want them checked.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_ACTION_SKIPPED
3
+ severity: hint
4
+ phase: smoke
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_ACTION_SKIPPED
10
+
11
+ Action skipped in verify. Severity: hint. Phase: smoke.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ 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.
20
+
21
+ ## Hint
22
+
23
+ To have verify run this action, check `dryRun()` from `@mostra/server` in it and return early without its side effects when it is true.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_BASELINE_MISSING
3
+ severity: hint
4
+ phase: regression
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_BASELINE_MISSING
10
+
11
+ Baseline version's build is missing. Severity: hint. Phase: regression.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ Nothing is required. A version published from this source becomes the next baseline.
20
+
21
+ ## Hint
22
+
23
+ Nothing to fix here; publish again to give later versions a baseline.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_CRASHED
3
+ severity: error
4
+ phase: runtime
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_CRASHED
10
+
11
+ Verify runner crashed. Severity: error. Phase: runtime.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ 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.
20
+
21
+ ## Hint
22
+
23
+ Verify again; if it keeps crashing, report the message with `mostra doctor`'s output.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_LIVE_FAILED
3
+ severity: warning
4
+ phase: runtime
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_LIVE_FAILED
10
+
11
+ Live source failed during verify. Severity: warning. Phase: runtime.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ Read the message. If the producer itself is wrong, fix it; if the data source was unreachable, verify again when it is back.
20
+
21
+ ## Hint
22
+
23
+ Check the live source's message: it failed while verify rendered the page, which may be the environment rather than the code.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_NO_BASELINE
3
+ severity: hint
4
+ phase: regression
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_NO_BASELINE
10
+
11
+ No earlier passing version. Severity: hint. Phase: regression.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ Nothing is required.
20
+
21
+ ## Hint
22
+
23
+ Nothing to fix: the next version will be compared with this one once it is published.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_SECRET_MISSING
3
+ severity: warning
4
+ phase: runtime
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_SECRET_MISSING
10
+
11
+ Secret missing during verify. Severity: warning. Phase: runtime.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ Run `mostra secret set <NAME>` (for the artifact or the home) with the value the code needs, then verify again.
20
+
21
+ ## Hint
22
+
23
+ Set the secret with `mostra secret set <NAME>` if the artifact needs it; verify reports it as the environment, not the code.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_SKIP_CONSEQUENCE
3
+ severity: hint
4
+ phase: smoke
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_SKIP_CONSEQUENCE
10
+
11
+ Page reaction to a skipped action. Severity: hint. Phase: smoke.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ Nothing is required. To let verify see the action's real result, opt it into the smoke test with `dryRun()`.
20
+
21
+ ## Hint
22
+
23
+ Nothing to fix: this followed from verify skipping an action, which a viewer's page never meets.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_VERIFY_TIMEOUT
3
+ severity: error
4
+ phase: runtime
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_VERIFY_TIMEOUT
10
+
11
+ Verify ran out of time. Severity: error. Phase: runtime.
12
+
13
+ ## What it means
14
+
15
+ 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.
16
+
17
+ ## How to fix it
18
+
19
+ 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.
20
+
21
+ ## Hint
22
+
23
+ Make the page render without waiting on slow work at load, then verify again.
@@ -0,0 +1,130 @@
1
+ # Self-hosting the remote server
2
+
3
+ The remote server hosts shared pages so their links keep working while the machine that shared them sleeps. It also hosts the remote MCP endpoint for chat apps. You run it as one container behind a TLS front. This page shows the shape with Caddy. Any TLS terminator that keeps the request's `Host` and adds `X-Forwarded-For` works the same way.
4
+
5
+ ## What you need
6
+
7
+ - **A host name for the API origin**, such as `api.example.com`. Owners sign in and connect there, chat apps reach `/mcp` there, and version files upload there.
8
+ - **A user-content domain of its own**, such as `example-usercontent.com`. Its apex serves the hosted shell, and each shared page gets a random label under it (`<label>.example-usercontent.com`). Use a registrable domain that serves nothing else, and keep the API origin off it. A page on it can set cookies for the whole domain, so nothing else should live there.
9
+ - **DNS** for the API host, the user-content apex and the wildcard `*.example-usercontent.com`, all pointing at your front. Labels are one level deep, so one wildcard certificate covers every page.
10
+ - **One machine** with Docker and a local disk. The data directory can't be on a network filesystem: the server refuses NFS, SMB and network FUSE mounts at start.
11
+
12
+ ## Configuration
13
+
14
+ The server reads a JSON file (`--config`) and `MOSTRA_SERVER_<KEY>` variables. A variable overrides the file's key. It holds JSON, or a plain string for `apiOrigin`, `operator` and `scheme`. If the server can't use a key, it stops before serving anything and names the key (`MOSTRA_REMOTE_CONFIG_INVALID`).
15
+
16
+ ```json
17
+ {
18
+ "apiOrigin": "https://api.example.com",
19
+ "domains": { "active": "example-usercontent.com" },
20
+ "trustedProxies": ["172.31.230.0/24"],
21
+ "identityProviders": [
22
+ {
23
+ "id": "github",
24
+ "kind": "github",
25
+ "label": "GitHub",
26
+ "clientId": "<the OAuth app's client ID>",
27
+ "clientSecretFile": "/run/secrets/github"
28
+ }
29
+ ],
30
+ "rateLimits": {
31
+ "perIp": { "submissions": { "count": 120, "per": "1m" } },
32
+ "perLink": { "submissions": { "count": 600, "per": "1m" } }
33
+ }
34
+ }
35
+ ```
36
+
37
+ | Key | What it does |
38
+ |---|---|
39
+ | `apiOrigin` | The API origin, `https:` |
40
+ | `domains.active`, `domains.spares` | The user-content domain new links use, and older ones that issued links keep working on. To move off a domain, make a spare active and restart the server |
41
+ | `trustedProxies` | Addresses or CIDR ranges whose `X-Forwarded-For` the server believes. It reads the header from the right and takes the first address that isn't a trusted proxy. Rate limits count IPv6 clients per /64 (`rateLimits.ipv6Prefix`) |
42
+ | `identityProviders` | How people sign in: `github` (an OAuth app), `oidc` (any OpenID Connect provider: `issuer`, `clientId`, `clientSecretFile`) or `development` (trusts any typed name; for tests only, never on a public server) |
43
+ | `rateLimits` | Rates as `{ "count", "per" }`: `perIp.submissions` and `perLink.submissions` for answers, `perLink.relayedRuns` for actions, and `perIp.requests` for every request an address sends (a health check aside). Past a rate the answer is 429 with `Retry-After`; a page says to try again shortly and keeps the draft. A key left out is no limit |
44
+ | `relay`, `homes`, `ledger` | The relay's waiting-run cap and drain rate, how long an idle hosted home stays open, and the ledger's WAL checkpoint (`0` for a backup replicator) |
45
+ | `operator` | The path of an operator module, which adds limits, metering, accounts and abuse handling through the operator ports (`@mostra/protocol/operator`). Without one, every port keeps its no-op default |
46
+
47
+ For GitHub sign-in, create an OAuth app with the callback `https://api.example.com/signin/github/callback`. For OpenID Connect, register the redirect URI `https://api.example.com/signin/<id>/callback`. Keep each client secret in a file that only the container's user (UID 10001) can read.
48
+
49
+ ## Running it with Caddy
50
+
51
+ The image is `ghcr.io/mostra-dev/mostra-server`, tagged with each release's version, for `linux/amd64` and `linux/arm64`. It runs `mostra-runtime server` as a non-root user. It listens on port 8080 and keeps everything in `/data`: hosted homes, version files and the server's keys. Append `--config <file>` to its command, or set the `MOSTRA_SERVER_*` variables.
52
+
53
+ `compose.yaml`:
54
+
55
+ ```yaml
56
+ networks:
57
+ front:
58
+ ipam:
59
+ config:
60
+ - subnet: 172.31.230.0/24
61
+ volumes:
62
+ data: {}
63
+ caddy-data: {}
64
+ services:
65
+ mostra-server:
66
+ image: ghcr.io/mostra-dev/mostra-server:<version>
67
+ command: ["--config", "/config/server.json"]
68
+ restart: unless-stopped
69
+ networks: [front]
70
+ read_only: true
71
+ tmpfs: [/tmp]
72
+ volumes:
73
+ - data:/data
74
+ - ./server.json:/config/server.json:ro
75
+ - ./github-secret:/run/secrets/github:ro
76
+ caddy:
77
+ image: <caddy built with the caddy-dns module for your DNS provider>
78
+ restart: unless-stopped
79
+ networks: [front]
80
+ ports: ["80:80", "443:443", "443:443/udp"]
81
+ volumes:
82
+ - ./Caddyfile:/etc/caddy/Caddyfile:ro
83
+ - ./dns-token:/run/secrets/dns-token:ro
84
+ - caddy-data:/data
85
+ ```
86
+
87
+ `Caddyfile`:
88
+
89
+ ```caddyfile
90
+ {
91
+ servers {
92
+ # A sibling page can fill the domain's cookie jar: pass up to 1 MiB of headers.
93
+ max_header_size 1MiB
94
+ }
95
+ }
96
+
97
+ api.example.com {
98
+ reverse_proxy mostra-server:8080
99
+ }
100
+
101
+ example-usercontent.com, *.example-usercontent.com {
102
+ tls {
103
+ dns cloudflare {file./run/secrets/dns-token}
104
+ }
105
+ reverse_proxy mostra-server:8080
106
+ }
107
+ ```
108
+
109
+ The wildcard certificate needs the DNS-01 challenge, so Caddy needs a build with your DNS provider's module (`xcaddy build --with github.com/caddy-dns/<provider>`) and a token that may edit the zone's records, kept in the file `dns-token` beside the `Caddyfile` (readable by the user Caddy runs as, and by nobody else) and read by `{file.…}`, so it is in no environment a process listing or a log can show. Caddy keeps the request's `Host` and adds `X-Forwarded-For`, and the server believes that header only from the network `trustedProxies` names.
110
+
111
+ Check the server once it runs:
112
+
113
+ ```sh
114
+ curl https://api.example.com/health # {"status":"ok",…}
115
+ curl https://api.example.com/.well-known/oauth-authorization-server # the sign-in metadata
116
+ ```
117
+
118
+ An owner then links a machine with `mostra login https://api.example.com` and shares a page with `mostra share <dir> --cloud`. A chat app connects to `https://api.example.com/mcp`.
119
+
120
+ ## Fronts and request headers
121
+
122
+ Hosted pages use no cookies, and the server drops every `Cookie` header unread. A tenant's page can still fill the user-content domain's cookie jar, and browsers then send up to about 720 KiB of cookies with each request. The server accepts headers up to 1 MiB, so such a jar never costs another page its session. Your front has to pass them too. Caddy's default is 16 KiB, so the Caddyfile above raises it with `max_header_size 1MiB`. A CDN or proxy whose limit is smaller fails every page on the domain for a browser whose jar a sibling page filled.
123
+
124
+ ## Backups and restores
125
+
126
+ Each hosted home's ledger is SQLite in WAL mode with normal locking, so a WAL replicator such as Litestream can read it live from its own process. Back up the whole data directory. After restoring a home, or the whole directory, by hand, start the server with `--restored <homeId>` or `--restored all`. The restored homes then rotate their incarnations before they serve anything, so owners never mistake reused cursors for ones they already copied. Each owner's machine also notices a home that holds less than it copied, and records the gap as `remote.regressed`.
127
+
128
+ ## What the open server doesn't do
129
+
130
+ It imposes no quota, link expiry or automatic pause, deletes nothing on its own, and sends no email or webhook. Plans, quotas, billing, abuse scoring, placing homes across machines, backup automation and outside domains come from an operator module through the operator ports. An operator pauses, quarantines, suspends and removes through the server handle the module receives.
@@ -0,0 +1,84 @@
1
+ # Telemetry
2
+
3
+ The standalone `mostra` CLI can send anonymous usage events, so we can see which commands work,
4
+ which fail, and which agents people use Mostra with. This page lists every event and every field.
5
+ If it isn't on this page, Mostra doesn't send it.
6
+
7
+ ## What Mostra never sends
8
+
9
+ - Artifact content, source code, answers or submissions
10
+ - File paths, project or artifact names, URLs, capability links or tokens
11
+ - Names, emails, usernames, hostnames or account identifiers
12
+ - Your time zone, locale or anything typed on the command line
13
+
14
+ The collector doesn't store IP addresses.
15
+
16
+ ## When it is on
17
+
18
+ - **In the EU, the EEA, the UK, Switzerland and nearby countries, and when the time zone is UTC or
19
+ unknown,** Mostra asks first. Nothing is sent until you answer yes or run `mostra telemetry on`.
20
+ Pressing Enter or not answering means no. Where no one can answer (CI, an agent's shell, `--json`),
21
+ Mostra doesn't ask and sends nothing. Mostra checks the time zone on your machine and never
22
+ sends it.
23
+ - **Elsewhere,** telemetry is on by default. Mostra prints a notice once before it sends anything.
24
+
25
+ ## When it is off
26
+
27
+ - `mostra telemetry off`, `MOSTRA_TELEMETRY=0` or `DO_NOT_TRACK=1`. Any of these wins over every
28
+ setting that turns it on.
29
+ - Embedded use never sends anything: the TypeScript SDK, the Rust crate, an instance a host starts
30
+ (`mostra host`), any home a host has configured, and an MCP server started with
31
+ `mostra mcp --embedded`, as a harness plugin starts it.
32
+ - A build without a telemetry endpoint sends nothing.
33
+
34
+ `mostra telemetry status` shows whether telemetry is on, why, your install ID and how many
35
+ events are waiting to be sent. `MOSTRA_TELEMETRY_DEBUG=1` prints every event to stderr exactly as
36
+ it would be sent, and sends nothing.
37
+
38
+ ## The install ID
39
+
40
+ On the first run that sends, Mostra creates a random ID and stores it in its config directory
41
+ (`${XDG_CONFIG_HOME:-~/.config}/mostra`, or `MOSTRA_CONFIG_DIR`). It is never derived from your
42
+ machine or from you, and it is the only value Mostra keeps between events. It lets us count
43
+ installs. Turning telemetry off deletes it and any unsent events; turning it on again creates a new
44
+ one.
45
+
46
+ ## Fields on every event
47
+
48
+ | Field | Example | Why |
49
+ |---|---|---|
50
+ | `schema` | `1` | The version of this list |
51
+ | `event` | `cli.command` | Which event |
52
+ | `at` | `2026-11-10T14:05:00Z` | When, to the minute |
53
+ | `installId` | a random UUID | Count installs without knowing who you are |
54
+ | `version` | `1.0.0` | Know which versions fail |
55
+ | `os`, `arch` | `darwin`, `linux` or `win32`; `x64` or `arm64` | Platform support |
56
+ | `node` | `22` | Which Node versions to support |
57
+ | `harness` | `claude-code`, `codex`, `gemini-cli`, `opencode`, `cursor`, `other`, `none` | Which agents to work with next |
58
+ | `ci` | `false` | Separate CI from people |
59
+ | `consent` | `explicit` or `default` | Whether you said yes or it was on by default |
60
+
61
+ ## Events
62
+
63
+ | Event | Sent when | Its own fields |
64
+ |---|---|---|
65
+ | `cli.first_run` | The install ID is created | none |
66
+ | `cli.command` | A command finishes | `command` (its name, never its arguments), `exit` (exit code), `duration` (`<1s`, `1-5s`, `5-30s`, `30s-2m`, `2-10m`, `>10m`), `json` (whether `--json` was used), `error` (the diagnostic code, when it failed) |
67
+ | `verify.result` | `mostra verify` finishes | `status` (`pass` or `fail`), `codes` (up to 50 diagnostic codes, never their messages), `codesTruncated` |
68
+ | `publish.done` | A version is published | `reused`, `forced` |
69
+ | `share.done` | A share starts | `kind`: `tailnet`, `funnel`, `cloudflare` or `remote` |
70
+ | `mcp.session` | An MCP client first uses `mostra mcp`, once per client in each run | `client` (a known agent's ID, or `other`), `clientVersion` (known agents only) |
71
+
72
+ ## How it is sent
73
+
74
+ Events wait in a small queue in the config directory and are sent in the background after a
75
+ command finishes (`mostra mcp`, which runs until its client stops it, sends `mcp.session` as it
76
+ happens), at most 100 per request. No command waits for the network, and the network
77
+ never changes a command's result. Events that can't be sent within 7 days are dropped.
78
+
79
+ ## Retention and your rights
80
+
81
+ We keep raw events for 12 months, then only aggregated counts. To have your events deleted, send
82
+ your install ID (from `mostra telemetry status`) to the privacy contact in our privacy policy.
83
+
84
+ Changes to this list are announced in the changelog before they ship.
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: mostra
3
+ description: Communicate visually with the user through Mostra. Use whenever showing or asking works better as a page than as chat text, such as questions to answer, options to choose between, a plan to approve, work to review, a report, a dashboard, a demo, or a page kept up to date. You write an ordinary React page, Mostra verifies it, publishes it behind a private link, and returns the person's answers to you.
4
+ license: Apache-2.0
5
+ compatibility: Needs a shell that runs `mostra` (or `npx` with Node.js 22.19 or later) on macOS, Linux or Windows, x64 or arm64.
6
+ metadata:
7
+ version: "0.11.0"
8
+ ---
9
+
10
+ # Mostra
11
+
12
+ Mostra turns a React page you write into an **artifact**: a web page a person opens from a private link, reads, answers, and acts on. Their answers are saved as they type, submitted once they're done, and come back to you as **results**. You check every page with `verify` before anyone sees it, so you never send a page you haven't looked at.
13
+
14
+ ## Running Mostra
15
+
16
+ Run `mostra <command>`. When `mostra` isn't on the `PATH`, run `npx -y @mostra/cli@0.11.0 <command>` everywhere this Skill says `mostra`; the first run downloads Mostra's own runtime (no global Node.js needed beyond `npx`). Every command takes `--json` (one JSON envelope on stdout, logs on stderr) and `--help`. `mostra docs <topic>` prints the reference, including every diagnostic code's page (`mostra docs MOSTRA_FIELD_DUPLICATE_ID`). `mostra list` lists the artifacts you've published, and `mostra status` shows the running instance.
17
+
18
+ When Mostra's tools are in your tool list (`artifact_create`, `artifact_verify` and the rest), use them instead: each step below has its tool, and everything else here holds unchanged. See [references/mcp.md](references/mcp.md).
19
+
20
+ A link that starts with `http://127.0.0.1` opens only on the computer Mostra runs on. When you run in a cloud sandbox (a chat app's code execution, a remote container), the person can't open it: use Mostra's tools from a connector when you have them, and otherwise say so and offer to share the page ([references/sharing.md](references/sharing.md)).
21
+
22
+ ## Words
23
+
24
+ | Word | Meaning |
25
+ |---|---|
26
+ | artifact | One page (or a few, under `pages/`) in its own directory, with a stable `art_…` ID |
27
+ | version | One published, immutable build of an artifact. People only ever see versions |
28
+ | field | One saved answer with a stable string ID: `useField("budget", 0)` |
29
+ | submission | The immutable snapshot of a person's answers, made when they submit |
30
+ | capability URL | The private link. Whoever holds it can use the artifact; treat it like a password |
31
+ | trusted control | The Submit (and Choose) button Mostra draws outside your page, so the person knows it's real |
32
+ | results | The submission as Markdown or JSON: answers by label, choices, comments, actions |
33
+
34
+ ## The loop
35
+
36
+ Each step ends when its check holds. Don't hand a link out before step 4 passes.
37
+
38
+ 1. **Decide what the person does.** Write one sentence: who it's for, what they do, what comes back to you. Pick the submission policy: `once` (the default: one submission, then it's closed), `epochs` (they can submit again, each round kept), or `none` (a long-lived page that never submits, such as a dashboard or task list: see [references/long-lived.md](references/long-lived.md)). *Done when* the sentence names the answers you need.
39
+ 2. **Create it.** `mostra new <dir> --title "<title>"` writes `index.tsx` (with the artifact's `id`; keep it) and an `AGENTS.md` for whoever edits it next. *Done when* the directory exists.
40
+ 3. **Write the page.** Ordinary React 19 and TypeScript with Tailwind CSS 4, no `package.json`, no build config. Every answer is a field with a stable ID:
41
+
42
+ ```tsx
43
+ import { defineArtifact, useField, useSubmitControl } from "@mostra/react";
44
+
45
+ export const artifact = defineArtifact({
46
+ title: "Sidebar redesign: your call",
47
+ description: "Pick a direction and say why.",
48
+ submission: { policy: "once" },
49
+ });
50
+
51
+ export default function Page() {
52
+ const [direction, setDirection] = useField("direction", "", { label: "Direction", required: true });
53
+ const [why, setWhy] = useField("why", "", { label: "Why" });
54
+ useSubmitControl({ label: "Send my choice" });
55
+ // …render radios bound to direction, a textarea bound to why
56
+ }
57
+ ```
58
+
59
+ Mostra draws the Submit button in its own frame around your page; `useSubmitControl` names it, and `required` fields block it until they're answered. Make it look considered: [references/design.md](references/design.md) has a baseline stylesheet and the rules for pages people answer. *Done when* every answer you need is a field with a label.
60
+ 4. **Verify until it passes.** `mostra verify <dir> --screenshots always`. It type-checks, builds, renders the page headlessly, clicks through it, runs an accessibility check and screenshots it at 1280×800 and 390×844. Fix every error, then **open both screenshots and look at them** (about 1,300 and 450 image tokens). Warnings that start with "Observed only" describe what verify saw; judge them, and leave working code alone. *Done when* the status is `pass` and the screenshots show what you meant at both sizes. More in [references/verify.md](references/verify.md).
61
+ 5. **Publish.** `mostra publish <dir>` prints the version and the capability URL. Publishing again after an edit makes a new version; open pages offer the person the new one, and answers carry over by field ID. *Done when* you have the link.
62
+ 6. **Hand the link over.** Say who is asking and why, what the page is for, and roughly how long it takes. For the person at this machine, `mostra open <dir> --browser` opens it in their browser, and its output says when none could be opened. For a phone or another person, see [references/sharing.md](references/sharing.md): one link is one person's draft, so give each person their own link. *Done when* the person has the link and knows what to do.
63
+ 7. **Wait for the answer.** `mostra wait <dir> --until submitted --timeout 10m`. Exit code 0 means submitted; 5 means still waiting, with nothing lost: wait again, or continue other work and check later. *Done when* it exits 0.
64
+ 8. **Read the results.** `mostra results <dir>` prints the submission as Markdown (`--format json` for JSON). Act on it. *Done when* you've used every answer.
65
+
66
+ ## What a page can do
67
+
68
+ | Need | Use | Reference |
69
+ |---|---|---|
70
+ | Save an answer, a choice, a note | `useField(id, initial, { label, required, validate })` | [answers.md](references/answers.md) |
71
+ | A form with validation | `useForm` from `@mostra/react/form` (react-hook-form) | [answers.md](references/answers.md) |
72
+ | Name or confirm the trusted Submit | `useSubmitControl({ label, confirm })` | [answers.md](references/answers.md) |
73
+ | Let the person ping you without submitting | `useSignal(name).send(payload)`, then `mostra wait <dir> --until signal:<name>` | [answers.md](references/answers.md) |
74
+ | Choose one of several candidates | `useChoice(reviewSetId, { candidates })` | [answers.md](references/answers.md) |
75
+ | A button that does something real (send, file, deploy) | a `"use server"` function, run with `useAction(fn, { key })` | [server.md](references/server.md) |
76
+ | Secrets for that code | `mostra secret set NAME`, then `secret("NAME")` in server code | [server.md](references/server.md) |
77
+ | Data that updates by itself | `defineLive` in `live.ts`, `useLive(key)` in the page, `mostra push` from you | [long-lived.md](references/long-lived.md) |
78
+ | State everyone shares and you can edit | `useField(id, initial, { scope: "artifact" })`, `mostra state set` | [long-lived.md](references/long-lived.md) |
79
+ | Several pages, packages, MDX, images | `pages/`, any npm import, `index.mdx`, `public/` | [page.md](references/page.md) |
80
+ | Charts, tables, animation, UI primitives | the preinstalled libraries | [libraries.md](references/libraries.md) |
81
+
82
+ ## Rules verify enforces
83
+
84
+ - **Field IDs are stable.** A literal string (`useField("budget", …)`), or a template keyed by your data's own ID for a list (`` useField(`reply.${email.id}`, …) ``); never an array index or a random value. Changing an ID between versions leaves the old answer behind ("Not carried over"). An ID used twice with different types is an error.
85
+ - **The manifest is a literal.** `defineArtifact({...})` holds only literal values; Mostra reads it without running your code.
86
+ - **Imports stay inside the artifact directory.** Packages install on demand; `@/…` imports from the artifact's root.
87
+ - **Server code is opt-in for verify.** Verify never runs a `"use server"` function unless it checks `dryRun()` and skips its side effects. The others are reported as skipped, which is fine.
88
+ - **No browser errors.** Uncaught errors, console errors and failed requests to your own origin are errors; a blank page is an error.
89
+
90
+ ## Codes you'll meet most
91
+
92
+ | Code | What to do |
93
+ |---|---|
94
+ | `MOSTRA_TYPE_ERROR` | Fix the TypeScript error at the location given |
95
+ | `MOSTRA_BUILD_UNRESOLVED` | Import from inside the artifact, or a package by its name |
96
+ | `MOSTRA_MANIFEST_NOT_LITERAL` | Write the manifest's values as literals |
97
+ | `MOSTRA_FIELD_DUPLICATE_ID`, `MOSTRA_FIELD_ID_UNSTABLE` | Give each field one stable ID |
98
+ | `MOSTRA_RUNTIME_PAGE_ERROR`, `MOSTRA_CONSOLE_ERROR`, `MOSTRA_RUNTIME_BLANK` | Fix the page's runtime error; look at the screenshot |
99
+ | `MOSTRA_VERIFY_ACTION_SKIPPED` | A hint: that action didn't run in verify. Add a `dryRun()` branch if you want it exercised |
100
+ | `MOSTRA_SMOKE_NO_EFFECT`, `MOSTRA_REGRESSION_*` | Observed only: check the screenshot, change nothing that works |
101
+ | `MOSTRA_PUBLISH_VERIFY_FAILED` | Publish refused because verify failed: run verify and fix its errors |
102
+ | `MOSTRA_SUBMIT_NOT_FOUND` | Nothing submitted yet: wait for it |
103
+
104
+ Every code's page: `mostra docs <CODE>`.
105
+
106
+ ## References
107
+
108
+ Read the one you need when you need it.
109
+
110
+ | File | Read it when |
111
+ |---|---|
112
+ | [references/page.md](references/page.md) | Structuring the artifact: files, manifest, pages, packages, MDX, links out, `window.storage` |
113
+ | [references/answers.md](references/answers.md) | Collecting answers: fields, forms, submission policies, signals, choices, `wait` and `results` |
114
+ | [references/design.md](references/design.md) | Before writing the page's markup: the baseline stylesheet and the design rules |
115
+ | [references/verify.md](references/verify.md) | Verify fails, or you want to understand a verdict, screenshots or `mostra dev` |
116
+ | [references/server.md](references/server.md) | The page must do something real: actions, secrets, idempotency |
117
+ | [references/long-lived.md](references/long-lived.md) | A page that lives for days: shared state, live data, `none` policy, always-on |
118
+ | [references/sharing.md](references/sharing.md) | Someone other than the person at this machine opens it, or on another device |
119
+ | [references/libraries.md](references/libraries.md) | Using charts, tables, motion or UI primitives, or an import fails |
120
+ | [references/mcp.md](references/mcp.md) | You work through Mostra's tools (`artifact_create` and the rest) instead of the `mostra` command |
121
+
122
+ Three complete artifacts that pass verify, to copy from: [assets/examples/decision/](assets/examples/decision/) (a choice with a reason), [assets/examples/inbox/](assets/examples/inbox/) (drafted replies with real Send actions) and [assets/examples/dashboard/](assets/examples/dashboard/) (live data and a shared list). The same guide is `mostra docs guide`, and each reference `mostra docs guide/<name>`.