docs: audit and tighten error reference pages

Simplify every DF error page (trim verbose Cause/Fix/Example, positive framing, normalize inline throw markers), add missing pages for DF0035 and DF0072, and rebuild the error index to list all codes with severity and titles across the Devframe and Hub ranges.

Author: antfubot

docs/content/6.errors/DF0014.md

@@ -9,9 +9,7 @@ description: 'RPC function "{name}" has an invalid agent field — description m
 
 ## Cause
 
-An RPC function was defined with an `agent` field (opting it in for exposure to agents via the MCP adapter), but the required `description` property is missing or empty.
-
-Agents rely on the description to decide when to invoke a tool. Empty or placeholder descriptions would produce unusable agent surface.
+An RPC function opts into agent exposure with an `agent` field, but its required `description` is missing or empty. Agents rely on the description to decide when to invoke a tool.
 
 ## Example
 
@@ -28,7 +26,7 @@ defineRpcFunction({
 
 ## Fix
 
-Provide a non-empty `description` (~1–3 sentences) explaining what the tool does and when agents should invoke it:
+Provide a non-empty `description` (~1–3 sentences) explaining what the tool does and when agents should invoke it, or remove the `agent` field to keep it RPC-only.
 
 ```ts
 defineRpcFunction({
@@ -41,8 +39,6 @@ defineRpcFunction({
 })
 ```
 
-If you didn't intend for this function to be agent-exposed, remove the `agent` field entirely (default-deny).
-
 ## Source
 
 - [`packages/devframe/src/node/host-agent.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-agent.ts) — agent registration throws `DF0014` when a tool's `agent.description` is missing or empty.

docs/content/6.errors/DF0017.md

@@ -11,14 +11,13 @@ description: 'Failed to start MCP server ({transport}): {reason}'
 
 The MCP server failed while initializing. Common reasons:
 
-- `@modelcontextprotocol/server` is not installed. This is a peer dependency — add it to your devtool's dependencies.
-- The stdio transport threw during `connect()` (e.g. stdin/stdout is not available).
-- The route-based MCP server (`cli.mcp`) could not load its transport module — usually the missing SDK peer dependency.
+- The `@modelcontextprotocol/server` peer dependency is missing (the stdio and route-based transports both need it).
+- The stdio transport threw during `connect()` (e.g. stdin/stdout unavailable).
 
 ## Fix
 
-- **Missing SDK**: `pnpm add @modelcontextprotocol/server` (or npm/yarn equivalent) in the package that imports `devframe/adapters/mcp` or enables `cli.mcp`.
-- **Transport init failure**: check the underlying error (attached as `cause`) for specifics.
+- **Missing SDK**: `pnpm add @modelcontextprotocol/server` in the package that imports `devframe/adapters/mcp` or enables `cli.mcp`.
+- **Transport failure**: inspect the underlying error attached as `cause`.
 
 ## Source
 

docs/content/6.errors/DF0019.md

@@ -9,24 +9,21 @@ description: 'RPC function "{name}" has agent set but jsonSerializable is not tr
 
 ## Cause
 
-The `agent` field exposes an RPC function as an MCP tool. MCP only consumes JSON-shaped data. Functions whose payloads can include `Map`, `Set`, `Date`, `BigInt`, circular references, or class instances cannot be safely advertised to agents.
-
-A registered function is rejected when `agent` is present and `jsonSerializable` is not explicitly `true`.
+The `agent` field exposes an RPC function as an MCP tool, and MCP only consumes JSON-shaped data. A function with `agent` set is rejected unless it also declares `jsonSerializable: true`.
 
 ## Example
 
 ```ts
 defineRpcFunction({
   name: 'my-plugin:summary',
   agent: { description: 'Returns a summary' },
-  // missing `jsonSerializable: true` → registration throws DF0019
-  handler: () => ({ items: [1, 2, 3] }),
+  handler: () => ({ items: [1, 2, 3] }), // ✗ throws DF0019 — missing jsonSerializable: true
 })
 ```
 
 ## Fix
 
-Either declare the payload as JSON-safe:
+Set `jsonSerializable: true` if the payload is JSON-safe, or remove `agent` to keep it RPC-only.
 
 ```ts
 defineRpcFunction({
@@ -37,15 +34,6 @@ defineRpcFunction({
 })
 ```
 
-Or remove `agent` to keep the function as an internal RPC (no agent exposure):
-
-```ts
-defineRpcFunction({
-  name: 'my-plugin:summary',
-  handler: () => new Map([['a', 1]]),
-})
-```
-
 ## Source
 
 - [`packages/devframe/src/rpc/collector.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/collector.ts) — `RpcFunctionsCollectorBase.register()` throws `DF0019` when a definition has `agent` set but is not declared `jsonSerializable: true`.

docs/content/6.errors/DF0020.md

@@ -9,18 +9,14 @@ description: 'RPC function "{name}" declares jsonSerializable: true but the valu
 
 ## Cause
 
-The function is declared `jsonSerializable: true`, which means its args and return value are encoded with strict `JSON.stringify` (both on the wire and in build dumps). The strict serializer rejects any value that JSON cannot round-trip losslessly:
+A `jsonSerializable: true` function encodes its args and return value with strict `JSON.stringify` (on the wire and in build dumps). The serializer throws at the offending value rather than emit a corrupt payload when it hits anything JSON cannot round-trip losslessly:
 
 - `Map`, `Set`, `WeakMap`, `WeakSet`
-- `Date` (silently coerced to ISO string by JSON)
-- `BigInt`
+- `Date` (JSON coerces it to an ISO string)
+- `BigInt`, `Symbol`, `Function`
 - circular references
 - non-plain class instances
 - `undefined` leaves
-- `Symbol`
-- `Function`
-
-When the strict serializer encounters one of these, it throws synchronously at the offending call rather than producing a corrupt payload.
 
 ## Example
 
@@ -29,26 +25,14 @@ defineRpcFunction({
   name: 'my-plugin:graph',
   jsonSerializable: true,
   handler: () => ({
-    nodes: new Map([['a', 1]]), // ← throws DF0020 with type=Map, path="nodes"
+    nodes: new Map([['a', 1]]), // ✗ throws DF0020 — type=Map, path="nodes"
   }),
 })
 ```
 
 ## Fix
 
-Either drop `jsonSerializable: true` so the function uses `structured-clone-es` (round-trips `Map`, `Set`, etc.):
-
-```ts
-defineRpcFunction({
-  name: 'my-plugin:graph',
-  // jsonSerializable: false (default) — Map/Set survive the wire and the dump
-  handler: () => ({
-    nodes: new Map([['a', 1]]),
-  }),
-})
-```
-
-Or convert the payload to a JSON-safe shape (e.g. an array of entries, an ISO string, a plain object) before returning. Note: removing `jsonSerializable: true` also disables `agent` exposure; if you need MCP, you must use a JSON-safe shape.
+Drop `jsonSerializable: true` to fall back to `structured-clone-es` (round-trips `Map`, `Set`, etc.), or convert the payload to a JSON-safe shape before returning. Keeping `agent` exposure requires the JSON-safe shape.
 
 ## Source
 

docs/content/6.errors/DF0029.md

@@ -9,15 +9,13 @@ description: 'Stream "{channel}#{id}" dropped {dropped} chunk(s) after exceeding
 
 ## Cause
 
-A streaming subscriber's queue grew past its `highWaterMark` because the consumer is slower than the producer. The oldest chunks were dropped to keep memory bounded.
-
-This is a soft warning — the stream keeps running and remaining chunks still flow.
+The consumer is slower than the producer, so the subscriber's queue grew past its `highWaterMark` and the oldest chunks were dropped to keep memory bounded. The stream keeps running and remaining chunks still flow.
 
 ## Fix
 
 - Raise `highWaterMark` on `rpc.streaming.subscribe(channel, id, { highWaterMark })` if the consumer can occasionally catch up.
-- Slow the producer so it doesn't outpace the wire (e.g. throttle, debounce, or batch chunks server-side).
-- Switch to `sharedState` if you only need the latest value rather than every intermediate chunk.
+- Slow the producer — throttle, debounce, or batch chunks server-side.
+- Use `sharedState` if you only need the latest value rather than every chunk.
 
 ## Source
 

docs/content/6.errors/DF0030.md

@@ -9,13 +9,13 @@ description: 'Stream "{channel}#{id}" is unknown — no producer has called chan
 
 ## Cause
 
-A client subscribed to a stream id that the server-side channel doesn't know about. Either the producer never started a stream with that id, the producer already ended it and `replayWindow` is `0`, or the client passed the wrong id.
+A client subscribed to a stream id no server-side producer has started. Either the producer never called `channel.start({ id })`, it already ended the stream and `replayWindow` is `0`, or the client passed the wrong id.
 
 ## Fix
 
-- Make sure the action that returns the stream id runs **before** the client subscribes — typically by awaiting `rpc.call('your-action')` and using the returned id.
-- Bump `replayWindow` on `ctx.rpc.streaming.create(name, { replayWindow })` if you need clients to resume after the producer has finished but kept the buffer warm.
-- Check the id is propagated correctly across boundaries (action return value → component prop → subscribe call).
+- Run the producer before clients subscribe — typically await `rpc.call('your-action')` and use the returned id.
+- Bump `replayWindow` on `ctx.rpc.streaming.create(name, { replayWindow })` to let clients resume after the producer finishes.
+- Verify the id propagates correctly (action return → component prop → subscribe call).
 
 ## Source
 

docs/content/6.errors/DF0033.md

@@ -9,19 +9,12 @@ description: 'Failed to start dev RPC bridge for "{id}": {reason}'
 
 ## Cause
 
-`devframeViteBridge()` (from `@devframes/vite`) could not bring up the bridge dev server that pairs a host-served SPA (Vite, Nuxt, Astro, etc.) with devframe's RPC backend. Common reasons:
-
-- The preferred port is in use and no fallback range was configured.
-- Calling `def.setup(ctx)` threw — the devframe's own setup logic surfaced an error.
-- A required peer (e.g. `get-port-please` or `h3`) is missing or mismatched.
-
-This is a soft warning — the surrounding Vite dev server keeps running, but the host-served SPA will fail its `__connection.json` lookup until the bridge starts.
+`devframeViteBridge()` (from `@devframes/vite`) could not bring up the bridge dev server that pairs a host-served SPA with devframe's RPC backend — usually because the preferred port is taken with no fallback range, or `def.setup(ctx)` threw. The surrounding Vite dev server keeps running, but the SPA's `__connection.json` lookup fails until the bridge starts.
 
 ## Fix
 
-- Pin a port via `cli.port` / `cli.portRange` on the devframe definition, or via `port` on `devframeViteBridge`.
-- Inspect the `reason` (or the attached `cause`) for the underlying error — fix the setup function or free the port.
-- For Nuxt: pass `devMiddleware: { port: <free-port> }` to the `@devframes/nuxt` module.
+- Pin a port via `cli.port` / `cli.portRange` on the definition, or `port` on `devframeViteBridge`.
+- Inspect `reason` (or the attached `cause`) to fix the setup function or free the port.
 
 ## Source
 

docs/content/6.errors/DF0035.md

@@ -0,0 +1,20 @@
+---
+title: 'DF0035: Storage File Persist Failed'
+description: 'Failed to persist storage file: {filepath}'
+---
+
+## Message
+
+> Failed to persist storage file: `{filepath}`
+
+## Cause
+
+A shared-state store's debounced write to disk failed — the directory could not be created, or the temp-file write / atomic rename threw. Usually the storage directory is not writable or the disk is full.
+
+## Fix
+
+Check that the storage directory is writable and has free space.
+
+## Source
+
+- [`packages/devframe/src/node/storage.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/storage.ts) — the debounced `updated` handler reports this when writing the temp file or renaming it into place fails.

docs/content/6.errors/DF0036.md

@@ -9,30 +9,23 @@ description: 'RPC call to "{name}" was rejected: the caller is not authorized.'
 
 ## Cause
 
-The RPC server was configured with an `authorize` gate (either directly, or via a [`DevframeAuthHandler`](/guide/security) passed as `auth`) and the calling session hasn't satisfied it — the call is neither to an `anonymous:`-prefixed method (see `isAnonymousRpcMethod`) nor made by a trusted session.
+An `authorize` gate (set directly or via an [`auth` handler](/guide/security)) rejected the call: the session is untrusted and the method is not `anonymous:`-prefixed (see `isAnonymousRpcMethod`).
 
 ## Example
 
 ```ts
-import { createDevServer } from 'devframe/adapters/dev'
-
-// `auth` defaults to devframe's interactive gate; `initDevframe` / `initHub`
-// gate hosted instances the same way through their own `auth` option.
-await createDevServer(def)
-
-// A browser that hasn't completed the handshake yet can still reach the
-// handshake methods themselves…
+// Handshake methods stay reachable before auth completes…
 await client.call('anonymous:devframe:auth', { authToken: '', ua, origin })
 
-// …but any other method throws DF0036 until the handshake succeeds.
+// …but trusted methods throw until the handshake succeeds.
 await client.call('some-plugin:do-something') // ✗ throws DF0036
 ```
 
 ## Fix
 
-- Complete the auth handshake — call `anonymous:devframe:auth` with a previously-issued token, or `anonymous:devframe:auth:exchange` with a one-time code — before calling a trusted method.
-- Connect with a static/pre-shared token (`createInteractiveAuth`'s `clientAuthTokens` option) for CI or shared-machine setups that should skip the interactive prompt.
-- If you supplied a custom `authorize` function, verify it allows the method you expect — it receives the raw method name and the session's `meta` (`isTrusted`, `clientAuthToken`, …).
+- Complete the auth handshake before calling a trusted method.
+- Connect with a static/pre-shared token (`createInteractiveAuth`'s `clientAuthTokens`) for CI or shared machines.
+- With a custom `authorize`, confirm it allows the method — it receives the method name and the session's `meta`.
 
 ## Source
 

docs/content/6.errors/DF0038.md

@@ -9,27 +9,21 @@ description: 'JSON-render view "{id}" received invalid props on element "{key}":
 
 ## Cause
 
-`@devframes/json-render` validates every element's props against the base catalog's per-component Zod schema at spec ingress (`createJsonRenderView` / `view.update`). Upstream `@json-render/core` only checks component *names*, so this per-component prop check is the one validation Devframes adds. An element whose props don't match its component's schema is rejected here rather than failing silently at render.
+`@devframes/json-render` validates every element's props against the base catalog's per-component schema at spec ingress (`createJsonRenderView` / `view.update`). An element whose props don't match its component's schema is rejected here.
 
 ## Example
 
 ```ts
-// ✗ Bad — `variant` is not one of the Button variants
 createJsonRenderView(ctx, {
   id: 'toolbar',
+  // ✗ throws DF0038 — `variant` is not a Button variant
   spec: { root: 'a', elements: { a: { type: 'Button', props: { variant: 'nope' }, children: [] } } },
 })
-
-// ✓ Good
-createJsonRenderView(ctx, {
-  id: 'toolbar',
-  spec: { root: 'a', elements: { a: { type: 'Button', props: { variant: 'primary', label: 'Save' }, children: [] } } },
-})
 ```
 
 ## Fix
 
-Match the element props to the base catalog's prop schema for that component. Dynamic `$state` / `$bindState` expressions are accepted wherever a scalar prop is expected, so a valid binding never triggers this.
+Match the element props to the base catalog's prop schema for that component. Dynamic `$state` / `$bindState` expressions are accepted wherever a scalar prop is expected.
 
 ## Source