Merge branch 'main' into antfu/rpc-json-serializable

Resolves a numbering conflict: main's #302 introduced DF0018 for the
`ctx.logs` deprecation warning, so my jsonSerializable diagnostics
shift up by one. New numbering on this branch:

- DF0018 (main) — `ctx.logs` deprecated.
- DF0019 — Agent Requires JSON-Serializable RPC.
- DF0020 — Non-JSON Value in JSON-Serializable RPC.
- DF0021..DF0028 — migrated from DTK0001..DTK0008.

Updates code, callsites, docs pages, sidebar count (28), error
index table, and skill / guide references to the new numbers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antfu

devframe/docs/.vitepress/sidebar.ts

@@ -13,7 +13,8 @@ export default function devframeSidebar(prefix = ''): DefaultTheme.SidebarItem[]
         { text: 'Dock System', link: `${prefix}/guide/dock-system` },
         { text: 'Commands', link: `${prefix}/guide/commands` },
         { text: 'When Clauses', link: `${prefix}/guide/when-clauses` },
-        { text: 'Logs & Notifications', link: `${prefix}/guide/logs` },
+        { text: 'Messages & Notifications', link: `${prefix}/guide/messages` },
+        { text: 'Structured Diagnostics', link: `${prefix}/guide/diagnostics` },
         { text: 'Terminals', link: `${prefix}/guide/terminals` },
         { text: 'Client', link: `${prefix}/guide/client` },
         { text: 'Standalone CLI', link: `${prefix}/guide/standalone-cli` },
@@ -25,7 +26,7 @@ export default function devframeSidebar(prefix = ''): DefaultTheme.SidebarItem[]
       text: 'Error Reference',
       link: `${prefix}/errors/`,
       collapsed: true,
-      items: Array.from({ length: 27 }, (_, i) => {
+      items: Array.from({ length: 28 }, (_, i) => {
         const code = `DF${String(i + 1).padStart(4, '0')}`
         return { text: code, link: `${prefix}/errors/${code}` }
       }),

devframe/docs/errors/DF0018.md

@@ -2,53 +2,51 @@
 outline: deep
 ---
 
-# DF0018: Agent Requires JSON-Serializable RPC
+# DF0018: `ctx.logs` Deprecated
 
 > Package: `devframe`
 
 ## Message
 
-> RPC function "`{name}`" has `agent` set but `jsonSerializable` is not `true` — MCP requires JSON-serializable data.
+> `` `ctx.logs` is deprecated and will be removed in a future release. Use `ctx.messages` instead. ``
 
 ## Cause
 
-The `agent` field exposes an RPC function as an MCP tool. MCP and the underlying schema-conversion path (`@valibot/to-json-schema`) only consume JSON-shaped data. Functions whose payloads can include `Map`, `Set`, `Date`, `BigInt`, circular references, or class instances cannot be safely advertised to agents.
+The user-facing message subsystem has been renamed from `logs` to `messages` to disambiguate it from the structured diagnostics surface (`ctx.diagnostics`, powered by [`logs-sdk`](https://github.com/vercel-labs/logs-sdk)).
 
-A registered function is rejected when `agent` is present and `jsonSerializable` is not explicitly `true`.
+`ctx.logs` continues to work as an alias of `ctx.messages` for one release cycle, but emits this warning the first time it is accessed in a given process.
 
 ## Example
 
+Code that triggers it:
+
 ```ts
-defineRpcFunction({
-  name: 'my-plugin:summary',
-  agent: { description: 'Returns a summary' },
-  // missing `jsonSerializable: true` → registration throws DF0018
-  handler: () => ({ items: [1, 2, 3] }),
-})
+ctx.logs.add({ message: 'something happened', level: 'info' })
 ```
 
 ## Fix
 
-Either declare the payload as JSON-safe:
+Replace `ctx.logs` with `ctx.messages`:
 
 ```ts
-defineRpcFunction({
-  name: 'my-plugin:summary',
-  jsonSerializable: true,
-  agent: { description: 'Returns a summary' },
-  handler: () => ({ items: [1, 2, 3] }),
-})
+ctx.messages.add({ message: 'something happened', level: 'info' })
 ```
 
-Or remove `agent` to keep the function as an internal RPC (no agent exposure):
+The runtime behavior is identical — the same host instance backs both fields.
 
-```ts
-defineRpcFunction({
-  name: 'my-plugin:summary',
-  handler: () => new Map([['a', 1]]),
-})
-```
+The associated type names have been renamed too (with deprecated aliases kept for one release):
+
+| Old | New |
+|-----|-----|
+| `DevToolsLogsHost` | `DevToolsMessagesHost` |
+| `DevToolsLogsClient` | `DevToolsMessagesClient` |
+| `DevToolsLogEntry` | `DevToolsMessageEntry` |
+| `DevToolsLogEntryInput` | `DevToolsMessageEntryInput` |
+| `DevToolsLogHandle` | `DevToolsMessageHandle` |
+| `DevToolsLogLevel` | `DevToolsMessageLevel` |
+
+The event names emitted by the host have changed from `log:added` / `log:updated` / `log:removed` / `log:cleared` to `message:added` / `message:updated` / `message:removed` / `message:cleared`.
 
 ## Source
 
-`packages/devframe/src/rpc/collector.ts`
+`packages/devframe/src/node/context.ts`

devframe/docs/errors/DF0019.md

@@ -2,57 +2,53 @@
 outline: deep
 ---
 
-# DF0019: Non-JSON Value in JSON-Serializable RPC
+# DF0019: Agent Requires JSON-Serializable RPC
 
 > Package: `devframe`
 
 ## Message
 
-> RPC function "`{name}`" declares `jsonSerializable: true` but the value at "`{path}`" is a `{type}`.
+> RPC function "`{name}`" has `agent` set but `jsonSerializable` is not `true` — MCP requires JSON-serializable data.
 
 ## 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:
+The `agent` field exposes an RPC function as an MCP tool. MCP and the underlying schema-conversion path (`@valibot/to-json-schema`) only consume JSON-shaped data. Functions whose payloads can include `Map`, `Set`, `Date`, `BigInt`, circular references, or class instances cannot be safely advertised to agents.
 
-- `Map`, `Set`, `WeakMap`, `WeakSet`
-- `Date` (silently coerced to ISO string by JSON)
-- `BigInt`
-- 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.
+A registered function is rejected when `agent` is present and `jsonSerializable` is not explicitly `true`.
 
 ## Example
 
 ```ts
 defineRpcFunction({
-  name: 'my-plugin:graph',
-  jsonSerializable: true,
-  handler: () => ({
-    nodes: new Map([['a', 1]]), // ← throws DF0019 with type=Map, path="nodes"
-  }),
+  name: 'my-plugin:summary',
+  agent: { description: 'Returns a summary' },
+  // missing `jsonSerializable: true` → registration throws DF0019
+  handler: () => ({ items: [1, 2, 3] }),
 })
 ```
 
 ## Fix
 
-Either drop `jsonSerializable: true` so the function uses `structured-clone-es` (round-trips `Map`, `Set`, etc.):
+Either declare the payload as JSON-safe:
 
 ```ts
 defineRpcFunction({
-  name: 'my-plugin:graph',
-  // jsonSerializable: false (default) — Map/Set survive the wire and the dump
-  handler: () => ({
-    nodes: new Map([['a', 1]]),
-  }),
+  name: 'my-plugin:summary',
+  jsonSerializable: true,
+  agent: { description: 'Returns a summary' },
+  handler: () => ({ items: [1, 2, 3] }),
 })
 ```
 
-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.
+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/serialization.ts`
+`packages/devframe/src/rpc/collector.ts`

devframe/docs/errors/DF0020.md

@@ -2,28 +2,57 @@
 outline: deep
 ---
 
-# DF0020: RPC Function Already Registered
+# DF0020: Non-JSON Value in JSON-Serializable RPC
 
 > Package: `devframe`
 
-> Migrated from `DTK0001`.
-
 ## Message
 
-> RPC function "`{name}`" is already registered
+> RPC function "`{name}`" declares `jsonSerializable: true` but the value at "`{path}`" is a `{type}`.
 
 ## Cause
 
-`ctx.rpc.register()` was called twice with the same `name`. RPC names must be unique within a devtool.
+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:
+
+- `Map`, `Set`, `WeakMap`, `WeakSet`
+- `Date` (silently coerced to ISO string by JSON)
+- `BigInt`
+- 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
+
+```ts
+defineRpcFunction({
+  name: 'my-plugin:graph',
+  jsonSerializable: true,
+  handler: () => ({
+    nodes: new Map([['a', 1]]), // ← throws DF0020 with type=Map, path="nodes"
+  }),
+})
+```
 
 ## Fix
 
-Either give the second registration a distinct name, or pass `force: true` to overwrite the previous one (e.g. during HMR-driven re-registration).
+Either drop `jsonSerializable: true` so the function uses `structured-clone-es` (round-trips `Map`, `Set`, etc.):
 
 ```ts
-ctx.rpc.register(defineRpcFunction({ name: 'my-plugin:fn', handler: () => 1 }), true /* force */)
+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.
+
 ## Source
 
-`packages/devframe/src/rpc/collector.ts`
+`packages/devframe/src/rpc/serialization.ts`

devframe/docs/errors/DF0021.md

@@ -2,23 +2,27 @@
 outline: deep
 ---
 
-# DF0021: RPC Function Not Registered (Update)
+# DF0021: RPC Function Already Registered
 
 > Package: `devframe`
 
-> Migrated from `DTK0002`.
+> Migrated from `DTK0001`.
 
 ## Message
 
-> RPC function "`{name}`" is not registered. Use register() to add new functions.
+> RPC function "`{name}`" is already registered
 
 ## Cause
 
-`ctx.rpc.update()` was called for a function that was never registered. `update()` is for replacing an existing definition.
+`ctx.rpc.register()` was called twice with the same `name`. RPC names must be unique within a devtool.
 
 ## Fix
 
-Call `ctx.rpc.register()` first, or pass `force: true` to `update()` to register-or-replace in one call.
+Either give the second registration a distinct name, or pass `force: true` to overwrite the previous one (e.g. during HMR-driven re-registration).
+
+```ts
+ctx.rpc.register(defineRpcFunction({ name: 'my-plugin:fn', handler: () => 1 }), true /* force */)
+```
 
 ## Source
 

devframe/docs/errors/DF0022.md

@@ -2,23 +2,23 @@
 outline: deep
 ---
 
-# DF0022: RPC Function Not Registered (Get)
+# DF0022: RPC Function Not Registered (Update)
 
 > Package: `devframe`
 
-> Migrated from `DTK0003`.
+> Migrated from `DTK0002`.
 
 ## Message
 
-> RPC function "`{name}`" is not registered
+> RPC function "`{name}`" is not registered. Use register() to add new functions.
 
 ## Cause
 
-A consumer asked for the schema or handler of a function that has never been registered with `ctx.rpc.register()`.
+`ctx.rpc.update()` was called for a function that was never registered. `update()` is for replacing an existing definition.
 
 ## Fix
 
-Confirm the function name matches a registration. RPC names are namespaced — typos in the prefix are a common cause.
+Call `ctx.rpc.register()` first, or pass `force: true` to `update()` to register-or-replace in one call.
 
 ## Source
 

devframe/docs/errors/DF0023.md

@@ -2,24 +2,24 @@
 outline: deep
 ---
 
-# DF0023: Missing RPC Handler
+# DF0023: RPC Function Not Registered (Get)
 
 > Package: `devframe`
 
-> Migrated from `DTK0004`.
+> Migrated from `DTK0003`.
 
 ## Message
 
-> Either handler or setup function must be provided for RPC function "`{name}`"
+> RPC function "`{name}`" is not registered
 
 ## Cause
 
-The RPC definition has neither a `handler` nor a `setup` returning `{ handler }`. devframe has nothing to invoke when the function is called.
+A consumer asked for the schema or handler of a function that has never been registered with `ctx.rpc.register()`.
 
 ## Fix
 
-Add either `handler: ...` directly on the definition, or `setup: ctx => ({ handler: ... })` if the handler depends on context.
+Confirm the function name matches a registration. RPC names are namespaced — typos in the prefix are a common cause.
 
 ## Source
 
-`packages/devframe/src/rpc/handler.ts`
+`packages/devframe/src/rpc/collector.ts`

devframe/docs/errors/DF0024.md

@@ -2,24 +2,24 @@
 outline: deep
 ---
 
-# DF0024: Function Not in Dump Store
+# DF0024: Missing RPC Handler
 
 > Package: `devframe`
 
-> Migrated from `DTK0005`.
+> Migrated from `DTK0004`.
 
 ## Message
 
-> Function "`{name}`" not found in dump store
+> Either handler or setup function must be provided for RPC function "`{name}`"
 
 ## Cause
 
-A static-mode client called an RPC function that was not baked into the build dump. This usually means the function was added after the dump was generated, or its name changed between build and runtime.
+The RPC definition has neither a `handler` nor a `setup` returning `{ handler }`. devframe has nothing to invoke when the function is called.
 
 ## Fix
 
-Re-run `createBuild` to regenerate the dump, or check that the call site uses the same name registered on the server.
+Add either `handler: ...` directly on the definition, or `setup: ctx => ({ handler: ... })` if the handler depends on context.
 
 ## Source
 
-`packages/devframe/src/rpc/dumps.ts`
+`packages/devframe/src/rpc/handler.ts`