Merge remote-tracking branch 'origin/main' into feat/assets-plugin

# Conflicts:
#	pnpm-lock.yaml
#	pnpm-workspace.yaml

Author: antfubot

docs/guide/agent-native.md

@@ -16,7 +16,7 @@ Three building blocks:
 
 1. **An `agent` field on `defineRpcFunction`.** Add `agent: { description, ... }` to opt a function in. Functions without the field stay private.
 2. **`ctx.agent`** — a host exposed on `DevframeNodeContext`. Plugins register tools that aren't backed by an RPC, and expose readable resources (e.g. a Markdown build summary).
-3. **The MCP adapter** (`devframe/adapters/mcp`) — translates the agent host into a [Model Context Protocol](https://modelcontextprotocol.io) server, currently over `stdio`.
+3. **The MCP adapter** (`devframe/adapters/mcp`) — translates the agent host into a [Model Context Protocol](https://modelcontextprotocol.io) server, over `stdio` (`devframe mcp`) or as a Streamable-HTTP route on the dev server (`--mcp`, advertised in `__connection.json`).
 
 ## Exposing an RPC function
 
@@ -118,6 +118,52 @@ Add an entry to `claude_desktop_config.json`:
 
 Restart Claude Desktop. The tools you flagged with `agent: { ... }` (plus any `registerTool` calls) show up in the MCP tool drawer. Resources are reachable as `devframe://resource/<id>` and `devframe://state/<key>` URIs.
 
+## Writing descriptions agents act on
+
+A tool description is a prompt, not documentation. The agent decides *when* to call your tool from the description alone, so tell it — state when to reach for the tool, not just what it returns:
+
+<!-- eslint-skip -->
+
+```ts
+// ✗ Bad: describes the mechanism
+agent: { description: 'Returns the session summary object.' }
+// ✓ Good: tells the agent when and why
+agent: { description: 'Summarize the current build session — durations, chunk counts, warnings. Call this before proposing any build-config change.' }
+```
+
+Two conventions:
+
+- **Lead with the action and the trigger.** "Call this before/after/when …" steers proactive use; a bare noun phrase gets ignored.
+- **State freshness and cost.** "Safe to call freely" / "expensive, call once per session" lets the agent budget calls.
+
+## Gateway tools
+
+A gateway tool returns *instructions and locations* instead of doing the work — the pattern for anything the agent can do better directly (reading bundled docs, running a CLI it has shell access to):
+
+```ts
+ctx.agent.registerTool({
+  id: 'my-plugin:docs',
+  description: 'Locate the version-accurate docs for this tool. Call before answering questions about its config format.',
+  safety: 'read',
+  handler: () => ({
+    docsPath: resolveInstalledDocsDir(),
+    hint: 'Read the file matching your topic; do not rely on training-data knowledge of this config format.',
+  }),
+})
+```
+
+The agent gets a path and a next step; the actual reading happens with its own tools, which are faster and keep large content out of the MCP payload.
+
+## Structured errors
+
+A coded devframe diagnostic thrown from a tool handler crosses the MCP boundary as structured JSON rather than a flattened message:
+
+```json
+{ "error": { "code": "DF0017", "message": "…", "fix": "…", "docs": "https://devfra.me/errors/df0017" } }
+```
+
+Agents can act on `fix` directly and follow `docs` for detail — prefer throwing coded diagnostics from anything agent-reachable.
+
 ## Safety model
 
 - **Opt-in exposure.** Functions opt in via the `agent` field; everything else stays private.

examples/a11y-messages-playground/package.json

@@ -1,7 +1,7 @@
 {
   "name": "a11y-messages-playground",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
   "description": "A focused hub playground that pairs @devframes/plugin-a11y with @devframes/plugin-messages over an intentionally-broken, multi-route app under test — for exercising a11y scanning, route tracking, and message→dock navigation.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/a11y-messages-playground",

examples/files-inspector/package.json

@@ -1,7 +1,7 @@
 {
   "name": "files-inspector-example",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
   "description": "End-to-end devframe demo — lists files in cwd via RPC, exercises CLI dev/build/spa surfaces.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/files-inspector",

examples/json-render/package.json

@@ -1,7 +1,7 @@
 {
   "name": "json-render",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
   "description": "Standalone devframe that serves a JSON-render view — a server-authored spec rendered by @devframes/json-render-ui, with live state and an action bridge.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/json-render",

examples/next-devframe-hub/package.json

@@ -1,7 +1,7 @@
 {
   "name": "next-devframe-hub",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
   "description": "Protocol-witness example — a tiny Next.js Devframe Hub built on @devframes/hub that exercises every hub subsystem end-to-end.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/next-devframe-hub",

examples/next-runtime-snapshot/package.json

@@ -1,7 +1,7 @@
 {
   "name": "next-runtime-snapshot-example",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
   "description": "End-to-end devframe demo — Next.js App Router SPA over RPC, exposing the host Node runtime snapshot (system info, memory, env).",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/next-runtime-snapshot",

examples/streaming-chat/package.json

@@ -1,7 +1,7 @@
 {
   "name": "streaming-chat-example",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
   "description": "End-to-end devframe demo — streams synthetic chat tokens from server to client via `ctx.rpc.streaming`. Mirrors the AI-deltas use case from issue #306.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/streaming-chat",

examples/vite-devframe-hub/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vite-devframe-hub",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
   "description": "Protocol-witness example — a tiny Vite Devframe Hub built on @devframes/hub that exercises every hub subsystem end-to-end.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/vite-devframe-hub",

package.json

@@ -1,9 +1,9 @@
 {
   "name": "devframe-monorepo",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "private": true,
-  "packageManager": "pnpm@11.16.0",
+  "packageManager": "pnpm@11.17.0",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "funding": "https://github.com/sponsors/antfu",

packages/devframe/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "description": "Framework for building generic devframes",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -111,32 +111,5 @@
     "ua-parser-modern": "catalog:inlined",
     "whenexpr": "catalog:deps",
     "ws": "catalog:deps"
-  },
-  "inlinedDependencies": {
-    "bundle-name": "4.1.0",
-    "default-browser": "5.5.0",
-    "default-browser-id": "5.0.1",
-    "define-lazy-prop": "3.0.0",
-    "get-port-please": "3.2.0",
-    "immer": "11.1.8",
-    "is-docker": "3.0.0",
-    "is-in-ssh": "1.0.0",
-    "is-inside-container": "1.0.0",
-    "is-wsl": "3.1.1",
-    "launch-editor": "2.13.2",
-    "obug": "2.1.1",
-    "ohash": "2.0.11",
-    "open": "11.0.0",
-    "p-limit": "7.3.0",
-    "perfect-debounce": "2.1.0",
-    "picocolors": "1.1.1",
-    "powershell-utils": "0.1.0",
-    "run-applescript": "7.1.0",
-    "shell-quote": "1.8.3",
-    "structured-clone-es": "2.0.0",
-    "ua-parser-modern": "0.1.1",
-    "whenexpr": "0.1.2",
-    "wsl-utils": "0.3.1",
-    "yocto-queue": "1.2.2"
   }
 }