Merge remote-tracking branch 'origin/main' into antfu/decouple-docks-terminals

# Conflicts:
#	AGENTS.md
#	devframe/docs/.vitepress/sidebar.ts
#	devframe/docs/guide/devtool-definition.md
#	devframe/docs/guide/dock-system.md
#	devframe/docs/guide/index.md
#	devframe/skills/devframe/SKILL.md
#	docs/.vitepress/config.ts

Author: antfu

.gitignore

@@ -18,7 +18,7 @@ packages/kit/skills
 devframe/packages/devframe/skills
 .rolldown
 *.tsbuildinfo
-docs/.vitepress/cache
+**/.vitepress/cache
 .turbo
 .context
 

AGENTS.md

@@ -21,9 +21,9 @@ Monorepo (`pnpm` workspaces + `turbo`). ESM TypeScript; bundled with `tsdown`. P
 | `packages/kit` | `@vitejs/devtools-kit` | The hub. `createKitContext` wraps devframe's context with `docks` / `terminals` / `messages` / `commands` host subsystems plus the Vite-augmented context type. `createPluginFromDevframe` bridges a portable devframe app into a `Plugin.devtools.setup` Vite plugin, auto-deriving its iframe dock entry from the definition. |
 | `packages/core` | `@vitejs/devtools` | Vite plugin + CLI + standalone/webcomponents client for Vite DevTools itself. Calls kit's `createKitContext`, scans Vite plugins for `.devtools.setup`, and serves the dock UI. |
 | `packages/ui` | `@vitejs/devtools-ui` | Shared UI components, composables, and UnoCSS preset (`presetDevToolsUI`). Private, not published. |
-| `packages/rolldown` | `@vitejs/devtools-rolldown` | Nuxt UI for Rolldown build data. Hub-mounted via `Plugin.devtools.setup`. Serves at `/.devtools-rolldown/`. |
-| `packages/vite` | `@vitejs/devtools-vite` | Nuxt UI for Vite DevTools (WIP). Hub-mounted via `Plugin.devtools.setup`. Serves at `/.devtools-vite/`. |
-| `packages/self-inspect` | `@vitejs/devtools-self-inspect` | Meta-introspection — DevTools for the DevTools. Hub-mounted via `Plugin.devtools.setup`. Serves at `/.devtools-self-inspect/`. |
+| `packages/rolldown` | `@vitejs/devtools-rolldown` | Nuxt UI for Rolldown build data. Hub-mounted via `Plugin.devtools.setup`. Serves at `/__devtools-rolldown/`. |
+| `packages/vite` | `@vitejs/devtools-vite` | Nuxt UI for Vite DevTools (WIP). Hub-mounted via `Plugin.devtools.setup`. Serves at `/__devtools-vite/`. |
+| `packages/self-inspect` | `@vitejs/devtools-self-inspect` | Meta-introspection — DevTools for the DevTools. Hub-mounted via `Plugin.devtools.setup`. Serves at `/__devtools-self-inspect/`. |
 | `packages/webext` | — | Browser extension scaffolding (ancillary). |
 
 Other top-level directories:
@@ -76,7 +76,7 @@ pnpm -C docs run docs                 # docs dev server
 - Use workspace aliases from `alias.ts`.
 - RPC functions must use `defineRpcFunction` from kit; always namespace IDs (`my-plugin:fn-name`).
 - Shared state via `devframe/utils/shared-state`; keep values serializable.
-- Nuxt UI base paths: `/.devtools-rolldown/`, `/.devtools-vite/`, `/.devtools-self-inspect/`.
+- Nuxt UI base paths: `/__devtools-rolldown/`, `/__devtools-vite/`, `/__devtools-self-inspect/`.
 - Shared UI components/preset in `packages/ui`; use `presetDevToolsUI` from `@vitejs/devtools-ui/unocss`.
 - Currently focused on Rolldown build-mode analysis; dev-mode support is deferred.
 
@@ -87,7 +87,7 @@ These apply to everything inside `devframe/packages/devframe` and reinforce its
 - **Single-integration scope.** Devframe describes one tool. If a feature only makes sense when multiple tools share a UI — docking, a unified command palette, cross-tool toasts, terminal aggregation — it lives in `@vitejs/devtools-kit`, not here.
 - **Headless by default.** No default startup banners, no opinionated logging to stdout, no default styling. Provide hooks (`onReady`, `cli.configure`, etc.); let the application print its own branding. Structured diagnostics via `logs-sdk` are fine — ad-hoc `console.log`s baked into adapters are not.
 - **File watching is the app's job, not devframe's.** Don't add a generic watcher primitive. Authors wire chokidar / fs.watch / watchman themselves and signal change via `ctx.rpc.sharedState.set(...)` or event-type RPCs. devframe stays out of the filesystem-observation business.
-- **Mount path depends on adapter context.** Given `id: 'foo'`, the default mount path is `/.foo/` for *hosted* adapters (`vite`, `embedded`, kit's `createPluginFromDevframe`) and `/` for *standalone* adapters (`cli`, `spa`, `build`). Authors override via `DevtoolDefinition.basePath`. Don't hardcode `DEVTOOLS_MOUNT_PATH` in adapter code paths that may run standalone.
+- **Mount path depends on adapter context.** Given `id: 'foo'`, the default mount path is `/__foo/` for *hosted* adapters (`vite`, `embedded`, kit's `createPluginFromDevframe`) and `/` for *standalone* adapters (`cli`, `spa`, `build`). Authors override via `DevtoolDefinition.basePath`. Don't hardcode `DEVTOOLS_MOUNT_PATH` in adapter code paths that may run standalone.
 - **SPAs own their basePath at runtime.** Build SPAs with relative asset paths (`vite.base: './'`); discover the effective base in the browser from the executing script's location / `document.baseURI`. `createBuild` / `createSpa` copy SPA output verbatim — no HTML rewriting, no build-time `--base` injection. The client (`connectDevtool`) resolves `.connection.json` relative to the runtime base automatically.
 - **CLI flags compose from both sides.** The `cac` instance backing `createCli` is exposed both to the `DevtoolDefinition` (`cli.configure(cli)`) — for capabilities contributed by the tool itself — and to the `createCli` caller — for flags added at the final assembly stage. Parsed flag values are forwarded to `setup(ctx, { flags })`. Never hardcode domain-specific flags into `createCli`.
 

devframe/docs/.vitepress/config.ts

@@ -1,14 +1,66 @@
+import type { DefaultTheme } from 'vitepress'
+import { fileURLToPath } from 'node:url'
+import { globSync } from 'tinyglobby'
 import { defineConfig } from 'vitepress'
 import { withMermaid } from 'vitepress-plugin-mermaid'
-import devframeSidebar from './sidebar'
+
+const errorsDir = fileURLToPath(new URL('../errors/', import.meta.url))
+
+function listErrorCodes(prefix: string): string[] {
+  return globSync(`${prefix}*.md`, { cwd: errorsDir })
+    .map(f => f.replace(/\.md$/, ''))
+    .sort()
+}
+
+function guideItems(prefix: string): DefaultTheme.NavItemWithLink[] {
+  return [
+    { text: 'Introduction', link: `${prefix}/guide/` },
+    { text: 'Devtool Definition', link: `${prefix}/guide/devtool-definition` },
+    { text: 'Adapters', link: `${prefix}/guide/adapters` },
+    { text: 'RPC', link: `${prefix}/guide/rpc` },
+    { text: 'Shared State', link: `${prefix}/guide/shared-state` },
+    { text: 'Streaming', link: `${prefix}/guide/streaming` },
+    { text: 'When Clauses', link: `${prefix}/guide/when-clauses` },
+    { text: 'Structured Diagnostics', link: `${prefix}/guide/diagnostics` },
+    { text: 'Client', link: `${prefix}/guide/client` },
+    { text: 'Standalone CLI', link: `${prefix}/guide/standalone-cli` },
+    { text: 'Nuxt Helper', link: `${prefix}/guide/nuxt` },
+    { text: 'Agent-Native (experimental)', link: `${prefix}/guide/agent-native` },
+  ]
+}
+
+export function devframeSidebar(prefix = ''): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Guide',
+      items: guideItems(prefix),
+    },
+    {
+      text: 'Error Reference',
+      link: `${prefix}/errors/`,
+      collapsed: true,
+      items: listErrorCodes('DF').map(code => ({
+        text: code,
+        link: `${prefix}/errors/${code}`,
+      })),
+    },
+  ]
+}
+
+export function devframeNav(prefix = ''): DefaultTheme.NavItemWithLink[] {
+  return [
+    ...guideItems(prefix),
+    { text: 'Error Reference', link: `${prefix}/errors/` },
+  ]
+}
 
 export default withMermaid(defineConfig({
   title: 'DevFrame',
   description: 'Framework-neutral foundation for building generic DevTools — RPC layer, hosts, and adapters.',
   themeConfig: {
     nav: [
-      { text: 'Guide', link: '/guide/' },
-      { text: 'Errors', link: '/errors/' },
+      { text: 'Guide', items: guideItems('') },
+      { text: 'Error Reference', link: '/errors/' },
     ],
     sidebar: devframeSidebar(),
     search: {

devframe/docs/.vitepress/sidebar.ts

@@ -48,7 +48,7 @@ my-devtool build --out-dir dist-static --base /devtools/
 my-devtool mcp                 # stdio MCP server (experimental)
 ```
 
-> Standalone CLI serves the SPA at `/` by default — no `/.devtools/` prefix. That prefix is reserved for *hosted* adapters where devframe mounts alongside an existing app. See [Mount paths](#mount-paths) below.
+> Standalone CLI serves the SPA at `/` by default — no `/__devtools/` prefix. That prefix is reserved for *hosted* adapters where devframe mounts alongside an existing app. See [Mount paths](#mount-paths) below.
 
 ### Options
 
@@ -180,7 +180,7 @@ The basePath where a devtool's SPA is mounted depends on the adapter it's runnin
 | Adapter kind | Default basePath | Reason |
 |--------------|------------------|--------|
 | `cli`, `spa`, `build` (standalone) | `/` | The devtool is the only thing on the origin. |
-| `vite`, `kit`, `embedded` (hosted) | `/.<id>/` | The devtool shares the origin with a host app and must namespace itself. |
+| `vite`, `kit`, `embedded` (hosted) | `/__<id>/` | The devtool shares the origin with a host app and must namespace itself. |
 
 Override either side explicitly with `DevtoolDefinition.basePath`:
 
@@ -196,7 +196,7 @@ SPA authors should **build with relative asset paths** (`vite.base: './'`) rathe
 
 ## Vite
 
-A thin Vite plugin that mounts a devtool's SPA into an existing Vite dev server as a *hosted* adapter — the mount path defaults to `/.<id>/` to avoid colliding with the app. It **does not** start an RPC WebSocket server — use `kit` or `cli` when you need RPC.
+A thin Vite plugin that mounts a devtool's SPA into an existing Vite dev server as a *hosted* adapter — the mount path defaults to `/__<id>/` to avoid colliding with the app. It **does not** start an RPC WebSocket server — use `kit` or `cli` when you need RPC.
 
 ```ts
 import { createVitePlugin } from 'devframe/adapters/vite'
@@ -210,7 +210,7 @@ export default defineConfig({
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `base` | `def.basePath ?? '/.<id>/'` | Mount path inside the Vite dev server. |
+| `base` | `def.basePath ?? '/__<id>/'` | Mount path inside the Vite dev server. |
 
 Use this adapter when a devtool's UI is purely static (no server calls) and you want to surface it during Vite `serve` without shipping a separate dev server. Set `DevtoolDefinition.basePath` on the definition if you want a custom path that stays consistent across adapters.
 
@@ -221,7 +221,7 @@ Produces a self-contained static deploy of a devtool:
 1. Copies the author's SPA dist (`cli.distDir` or `options.distDir`) into `<outDir>`.
 2. Runs `setup(ctx)` with `mode: 'build'`.
 3. Collects RPC dumps for every `'static'` function and any `'query'` function with `dump.inputs` / `snapshot: true`.
-4. Writes `<outDir>/.connection.json` (`{ backend: 'static' }`) and sharded dump files under `<outDir>/.rpc-dump/` — both at the SPA root so the deployed client discovers them via relative paths from `document.baseURI`.
+4. Writes `<outDir>/__connection.json` (`{ backend: 'static' }`) and sharded dump files under `<outDir>/__rpc-dump/` — both at the SPA root so the deployed client discovers them via relative paths from `document.baseURI`.
 5. When `def.spa` is set, also writes `<outDir>/spa-loader.json` describing how the SPA hydrates its data.
 
 ```ts
@@ -240,7 +240,7 @@ await createBuild(devtool, {
 | `base` | `/` | Absolute URL base the output is served from. |
 | `distDir` | `def.cli?.distDir` | Override the SPA dist directory. |
 
-The resulting directory can be hosted by any static web server (`serve`, nginx, GitHub Pages, …). The client auto-detects `static` mode via `./.connection.json` resolved against `document.baseURI` and runs in read-only form.
+The resulting directory can be hosted by any static web server (`serve`, nginx, GitHub Pages, …). The client auto-detects `static` mode via `./__connection.json` resolved against `document.baseURI` and runs in read-only form.
 
 > [!TIP]
 > `createBuild` copies the SPA verbatim. To deploy under a custom URL base, build your SPA with relative asset paths (`vite.base: './'`) — the client discovers the effective base at runtime. No HTML rewriting is performed at build time.
@@ -278,7 +278,7 @@ The returned object has the shape `{ name, devtools: { setup, capabilities } }`.
 
 ## Embedded
 
-Register a devtool into an already-running context at runtime. Mirrors the internal plugin-scan that Kit runs at startup, but exposes it for callers that need dynamic, post-startup registration. The host decides the mount path; `embedded` is treated as a hosted adapter and inherits the `/.<id>/` default when one is needed.
+Register a devtool into an already-running context at runtime. Mirrors the internal plugin-scan that Kit runs at startup, but exposes it for callers that need dynamic, post-startup registration. The host decides the mount path; `embedded` is treated as a hosted adapter and inherits the `/__<id>/` default when one is needed.
 
 ```ts
 import { createEmbedded } from 'devframe/adapters/embedded'

devframe/docs/guide/adapters.md

@@ -18,11 +18,11 @@ const rpc = await connectDevtool()
 const modules = await rpc.call('my-devtool:get-modules', { limit: 10 })
 ```
 
-`connectDevtool` auto-detects the backend via `.devtools/.connection.json` and falls back through a sequence of base URLs. No arguments are needed when the client is hosted from the default mount path.
+`connectDevtool` auto-detects the backend via `__devtools/__connection.json` and falls back through a sequence of base URLs. No arguments are needed when the client is hosted from the default mount path.
 
 ### Runtime basePath discovery
 
-SPAs built for devframe are designed to be **base-agnostic**: the same artifact can be served at `/`, at `/.<id>/`, or at any custom subpath, without rebuilding. `connectDevtool` resolves `.connection.json` relative to the page at runtime by reading `document.baseURI` and the executing script's URL.
+SPAs built for devframe are designed to be **base-agnostic**: the same artifact can be served at `/`, at `/__<id>/`, or at any custom subpath, without rebuilding. `connectDevtool` resolves `__connection.json` relative to the page at runtime by reading `document.baseURI` and the executing script's URL.
 
 The practical consequence for SPA authors:
 
@@ -46,16 +46,16 @@ await connectDevtool({
 
 | Option | Description |
 |--------|-------------|
-| `baseURL` | Mount path to probe for `.connection.json`. Accepts an array for fallback. Default: `'./'` — resolved relative to `document.baseURI` so the SPA finds its meta wherever it was deployed. Pass an explicit absolute path (e.g. `'/.devtools/'`) when calling from outside the SPA — for instance, an embedded webcomponent injected into a host app. |
+| `baseURL` | Mount path to probe for `__connection.json`. Accepts an array for fallback. Default: `'./'` — resolved relative to `document.baseURI` so the SPA finds its meta wherever it was deployed. Pass an explicit absolute path (e.g. `'/__devtools/'`) when calling from outside the SPA — for instance, an embedded webcomponent injected into a host app. |
 | `authToken` | Override the auth token. Defaults to a locally-persisted human-readable id. |
 | `cacheOptions` | `true` to enable caching with defaults, or an options object. |
 | `wsOptions` | Forwarded to the WebSocket transport (reconnect, heartbeat, etc.). |
 | `rpcOptions` | Forwarded to `birpc`. |
-| `connectionMeta` | Skip the `.connection.json` fetch with a pre-known descriptor. |
+| `connectionMeta` | Skip the `__connection.json` fetch with a pre-known descriptor. |
 
 ## Modes
 
-The client runs in one of two modes depending on what the server advertises in `.devtools/.connection.json`:
+The client runs in one of two modes depending on what the server advertises in `__devtools/__connection.json`:
 
 | Backend | When | Capabilities |
 |---------|------|--------------|
@@ -156,9 +156,9 @@ const rpc = await connectDevtool({ cacheOptions: true })
 
 With caching on, `query` / `static` function responses are memoized per argument hash. Server-side broadcasts like `rpc:cache:invalidate` clear entries automatically — plugins that mutate state should broadcast that message after the change.
 
-## Discovery (`.connection.json`)
+## Discovery (`__connection.json`)
 
-DevFrame writes a small JSON descriptor at `<base>/.connection.json` so the client knows where to connect:
+DevFrame writes a small JSON descriptor at `<base>/__connection.json` so the client knows where to connect:
 
 ```json
 {

devframe/docs/guide/client.md

@@ -68,7 +68,7 @@ At build time the module:
   return { provide: { rpc } }
   ```
 
-At runtime the built SPA fetches `./.connection.json` (resolved against `document.baseURI`) and branches on the `backend` field — `websocket` in dev, `static` from a `createBuild` snapshot.
+At runtime the built SPA fetches `./__connection.json` (resolved against `document.baseURI`) and branches on the `backend` field — `websocket` in dev, `static` from a `createBuild` snapshot.
 
 ## Relationship to `createCli`
 

devframe/docs/guide/nuxt.md

@@ -10,6 +10,7 @@
   "devDependencies": {
     "devframe": "workspace:*",
     "mermaid": "catalog:docs",
+    "tinyglobby": "catalog:deps",
     "vitepress": "catalog:docs",
     "vitepress-plugin-mermaid": "catalog:docs"
   }

devframe/docs/package.json

@@ -8,15 +8,15 @@ A simplified [node-modules-inspector](https://github.com/antfu/node-modules-insp
 
 The Preact client showcases two patterns relevant to devframe authors:
 
-1. **Runtime base discovery.** The client is built with `vite.base: './'` and reads `document.baseURI` at runtime to resolve its mount path. The same `dist/client` works under any base path (`/.devframe-files-inspector/`, `/`, `/custom/`, …) without rebuilding.
+1. **Runtime base discovery.** The client is built with `vite.base: './'` and reads `document.baseURI` at runtime to resolve its mount path. The same `dist/client` works under any base path (`/__devframe-files-inspector/`, `/`, `/custom/`, …) without rebuilding.
 2. **Two RPC types.** `:list-files` is a `query` with `dump.inputs: [[]]` (live in dev, baked in static). `:get-cwd` is a `static` RPC.
 
 ## Run
 
 ```sh
 pnpm install
 pnpm -C examples/devframe-files-inspector run build       # build the Preact client
-pnpm -C examples/devframe-files-inspector run dev         # http://127.0.0.1:9876/.devframe-files-inspector/
+pnpm -C examples/devframe-files-inspector run dev         # http://127.0.0.1:9876/__devframe-files-inspector/
 pnpm -C examples/devframe-files-inspector run cli:build   # static deploy in ./dist/static
 serve examples/devframe-files-inspector/dist/static       # any static host works (relative paths)
 pnpm -C examples/devframe-files-inspector run test        # E2E tests