Merge remote-tracking branch 'origin/main' into docs/project-structure

Author: antfubot

docs/content/1.guide/4.rpc.md

@@ -56,13 +56,7 @@ Scope with your devframe id, then a kebab-case action: `my-devframe:get-modules`
 
 ### Handler arguments
 
-Handlers accept any serializable arguments. Declared `args` schemas validate each at the boundary; extra object fields still reach the handler.
-
-> [!TIP]
-> If your app already pulls in **zod**, use it for your RPC schemas to reuse a dependency you already ship.
-
-> [!WARNING]
-> Declared `args`/`returns` schemas are enforced at runtime; failing arguments or return values are rejected with `DF0043` / `DF0044`.
+Handlers accept any serializable arguments. Declared `args` and `returns` schemas are enforced at runtime; extra object fields still reach the handler.
 
 ### Setup vs handler
 
@@ -198,15 +192,7 @@ The WS transport picks one of two encoders per function:
 | `false` (default) | `structured-clone-es` | `s:` | `Map`, `Set`, `Date`, `BigInt`, cycles, class instances |
 | `true` (opt-in) | strict `JSON.stringify` | _(unprefixed)_ | JSON-only |
 
-When every function is JSON-flagged, the wire stays plain JSON.
-
-### Discovering shape errors during dev
-
-When a `jsonSerializable: true` handler returns a value JSON cannot round-trip (`Map`, `Date`, …), the strict serializer throws [`DF0020`](/errors/DF0020).
-
-### MCP requires JSON
-
-`agent: {...}` requires `jsonSerializable: true`; one without the other throws [`DF0019`](/errors/DF0019).
+When every function is JSON-flagged, the wire stays plain JSON. A `jsonSerializable: true` handler must return JSON-only values — `Map`, `Date`, and friends won't round-trip.
 
 ## Agent exposure
 
@@ -230,6 +216,8 @@ defineRpcFunction({
 })
 ```
 
+Exposing a function over MCP requires `jsonSerializable: true`.
+
 ## What's next
 
 - [Shared State](/guide/shared-state) — state synced across clients

docs/content/4.helpers/3.interactive-auth.md

@@ -29,6 +29,7 @@ As `auth` it wires `rpcFunctions`, `authorize`, and `onConnect` — see [Securit
 |--------|---------|---------|
 | `clientAuthTokens` | `undefined` | Pre-shared bearer tokens, always trusted. |
 | `banner` | a small boxed console message | Called with `{ code, url }`; prints via `printBanner()`. |
+| `onTrusted` | `undefined` | Called with `{ session, authToken }` once a code exchange succeeds, so a host rendering its own banner can retract it. |
 | `serverUrl` | `context.host.resolveOrigin()` | Magic-link base URL. |
 
 Returns a `DevframeAuthHandler`:
@@ -57,4 +58,6 @@ if (!auth.authorize(methodName, session))
 auth.onConnect(peer, session)
 ```
 
+An exchange rotates the code and prints the new one, and `onTrusted` fires after that, so a host retracting a sticky notice drops that follow-up too and calls `auth.printBanner()` when it next wants a code on screen.
+
 Auth storage is internal, not `devframe/node/hub-internals`.

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.