chore: update

Author: antfu

docs/content/1.guide/1.tutorial.md …uide/1.tutorial-server-data-inspector.mddocs/content/1.guide/1.tutorial.md renamed to docs/content/1.guide/1.tutorial-server-data-inspector.md docs/content/1.guide/1.tutorial.md renamed to docs/content/1.guide/1.tutorial-server-data-inspector.md

@@ -1,30 +1,32 @@
 ---
-title: 'Tutorial: Build a Data Inspector'
-description: 'Build a small devtool from an empty folder — a live view into your server''s state — then grow it one capability at a time: a dock in a hub, a static build, a standalone server, and a CLI.'
+title: 'Tutorial: Build a Server Data Inspector'
+description: 'Build a Devframe to display and query data from the server side, with a dock in a hub, a static build, a standalone server, and a CLI.'
 ---
 
-Let's build a real devtool from nothing: a **Data Inspector** that shows the shape of your server's live state and lets you read any value out of it. We'll get it working first, then teach it new tricks one at a time — a dock in a hub, a static build, a standalone server, a CLI.
-
-One new idea per step, nothing assumed. You'll need **Node 24+** (so `node` runs TypeScript directly) and a terminal.
+Let's build a real devtool from sketch: a **Data Inspector** that shows the shape of your server's live state and lets you read any value out of it. We'll get it working first, then teach it new tricks one at a time, a dock in a hub, a static build, a standalone server, a CLI.
 
 ## The shape of a devframe app
 
-Two halves talk over a typed connection: a **server** half in your Node process that exposes functions, and a **browser** half that calls them and shows the answers. Devframe is everything in between — the wire, the UI hosting, auth, builds, a CLI. Write the two halves once; run them anywhere.
+Two halves talk over a typed connection: a **server** in your Node process that exposes server functions, and a **browser** client that gets the data and renders them nicely and provides interactivity. Devframe is everything in between, the wire, the UI hosting, auth, builds, a CLI.
+
+## Step 1, Define the tool
+
+Everything starts with `defineDevframe`: your tool's name, plus a `setup` where you register what it can do. 
 
-## Step 1 — Define the tool
+> You will need [Node 24+](https://nodejs.org/) for this tutorial.
 
-Everything starts with `defineDevframe`: your tool's name, plus a `setup` where you register what it can do. Create the project and the definition:
+Create the project and the definition:
 
 ```sh
 mkdir data-inspector && cd data-inspector
 npm init -y && npm pkg set type=module
 npm install devframe && npm install -D typescript
 ```
 
-```ts [src/devframe.ts]
+```ts [src/data-inspector.ts]
 import { defineDevframe } from 'devframe'
 
-// Whatever you want to peek at while your app runs — config, a cache, a DB handle.
+// An example server-side data, whatever you want to peek at while your app runs, config, a cache, a DB handle.
 const serverState = {
   config: { name: 'Acme', port: 3000, debug: false },
   users: [
@@ -34,7 +36,7 @@ const serverState = {
   featureFlags: { newDashboard: true, betaSearch: false },
 }
 
-// Follow a dot-path like `users.0.name` into the state.
+// A simple query function that follows a dot-path like `users.0.name` into the state.
 function valueAtPath(root: unknown, path: string): unknown {
   if (!path)
     return root
@@ -45,7 +47,7 @@ function valueAtPath(root: unknown, path: string): unknown {
   }, root)
 }
 
-export default defineDevframe({
+const dataInspectorFrame = defineDevframe({
   id: 'data-inspector',
   name: 'Data Inspector',
   version: '0.0.0',
@@ -77,13 +79,15 @@ export default defineDevframe({
     })
   },
 })
+
+export default dataInspectorFrame
 ```
 
 `ctx.rpc.register` publishes a function the browser can call: a namespaced `name`, a `type` (`query` is read-only), and a `handler` that takes the call's arguments and returns JSON. That's the whole server. ([RPC](/guide/rpc) has the other types; [Devframe Definition](/guide/devframe-definition) has every field.)
 
-## Step 2 — Add a UI
+## Step 2, Add a UI
 
-Now the browser half. We'll use React, but any framework works — the only devframe-specific line is `connectDevframe`, which opens the connection home.
+Now the browser part. We'll use React for this example, but any framework works, the only devframe-specific line is `connectDevframe`, which opens the connection home.
 
 ```sh
 npm install react react-dom @devframes/vite
@@ -148,7 +152,7 @@ export function App() {
         {meta.map(m => (
           <li key={m.key}>
             <code>{m.key}</code>
-            {' — '}
+            {' - '}
             {m.type}
             {m.length != null ? ` (${m.length})` : ''}
           </li>
@@ -162,17 +166,17 @@ export function App() {
 }
 ```
 
-`client.call(name, ...args)` reaches your handlers. (We cast `.call` to call by name; wire up a typed registry later and every call is checked end to end — see [RPC](/guide/rpc).)
+`client.call(name, ...args)` reaches your handlers. (We cast `.call` to call by name; wire up a typed registry later and every call is checked end to end, see [RPC](/guide/rpc).)
 
-## Step 3 — Run it
+## Step 3, Run it as Development
 
-The two halves still need to meet. While developing, let Vite serve the UI and hand RPC traffic to devframe:
+To try the tool we just built, we can let Vite serve the UI and hand RPC traffic to devframe:
 
-```ts [vite.config.ts]
+```ts [vite.client.config.ts]
 import { devframeViteBridge } from '@devframes/vite/single'
 import react from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
-import devframe from './src/devframe.ts'
+import dataInspectorFrame from './src/data-inspector.ts'
 
 export default defineConfig({
   root: 'client',
@@ -181,26 +185,26 @@ export default defineConfig({
   plugins: [
     react(),
     // Vite serves the page; the bridge answers RPC on the same origin, so
-    // `connectDevframe()` just finds it. `auth: false` — see the note below.
-    devframeViteBridge(devframe, { base: '/', auth: false }),
+    // `connectDevframe()` just finds it. `auth: false`, see the note below.
+    devframeViteBridge(dataInspectorFrame, { base: '/', auth: false }),
   ],
 })
 ```
 
 ```sh
-npx vite
+npx vite --config vite.client.config.ts
 ```
 
 Open the printed URL. Three keys with their types show up, and typing `config.port` or `users.0.name` and hitting **Query** prints the value. Button → `call` → your `handler` → back to the page: that's the whole app, working.
 
 > [!WARNING]
-> `auth: false` trusts anything that can reach the port — fine for localhost, but leave it out (devframe gates with a one-time code by default) for anything reachable from elsewhere. See [Security](/guide/security).
+> `auth: false` trusts anything that can reach the port. We have it off to make the tutorial easier. But we strongly recommend enabling it if you are publishing it as a tool. See [Security](/guide/security).
 
 Everything below reuses this exact `src/devframe.ts` and `client/`. We only change where they run.
 
-## Step 4 — Dock it in a hub
+## Step 4, Dock it in a hub
 
-A [hub](/guide/hub) puts many devframes behind one interface, each a **dock** you switch between — the tool's own UI in an iframe. Since our client uses a bare `connectDevframe()`, it already works anywhere; the hub just needs the built UI. Point the definition at it:
+A [hub](/guide/hub) puts many devframes behind one interface, each a **dock** you switch between, the tool's own UI in an iframe. Since our client uses a bare `connectDevframe()`, it already works anywhere; the hub just needs the built UI. Point the definition at it:
 
 ```ts [src/devframe.ts]
 import { fileURLToPath } from 'node:url'
@@ -217,88 +221,89 @@ Build the UI and stand up a one-devframe hub:
 
 ```sh
 npm install @devframes/hub @devframes/hub-ui
-npx vite build
+npx vite build --config vite.client.config.ts
 ```
 
-```ts [hub.config.ts]
+```ts [vite.hub.config.ts]
 import { createUi } from '@devframes/hub-ui'
 import { viteDevframeHub } from '@devframes/vite/hub'
 import { defineConfig } from 'vite'
-import devframe from './src/devframe.ts'
+import dataInspectorFrame from './src/data-inspector.ts'
 
 export default defineConfig({
   plugins: [
     viteDevframeHub({
-      devframes: [devframe],
+      devframes: [dataInspectorFrame],
       ui: createUi({ branding: { productName: 'My Devtools' } }),
-      quiet: true,
     }),
   ],
 })
 ```
 
 ```sh
-npx vite --config hub.config.ts
+npx vite --config vite.hub.config.ts
 ```
 
-Your inspector now sits in the hub's rail as a dock. Drop more into `devframes: [...]` — your own or the [built-in plugins](/plugins) — and each gets its own. (The hub prints a code to authorize on first connect.)
+Your inspector now sits in the hub's rail as a dock. Drop more into `devframes: [...]`, your own or the [built-in plugins](/plugins), and each gets its own. (The hub prints a code to authorize on first connect.)
 
-## Step 5 — Build a static version
+## Step 5, Build a static version
 
-Some tools should work with no server at all — a report you can drop on any static host. `createBuild` renders the UI and **bakes in** the results of read-only calls. Opt one in with `snapshot: true`:
+Some tools should work with no server at all, a report you can drop on any static host. `createBuild` renders the UI and **bakes in** the results of read-only calls. Opt one in with `snapshot: true`:
 
 ```ts
 ctx.rpc.register({
   name: 'data-inspector:get-meta',
   type: 'query',
   jsonSerializable: true,
   snapshot: true, // bake this call's result into the build
-  handler: () => /* … unchanged … */,
+  handler: () => {
+    /* … unchanged … */
+  }
 })
 ```
 
 ```js [scripts/build.mjs]
 import { createBuild } from 'devframe/adapters/build'
-import devframe from '../src/devframe.ts'
+import dataInspectorFrame from '../src/data-inspector.ts'
 
-await createBuild(devframe, { outDir: 'dist-static' })
+await createBuild(dataInspectorFrame, { outDir: 'dist-static' })
 ```
 
 ```sh
 npx vite build          # refresh dist/client
 node scripts/build.mjs  # → dist-static/
 ```
 
-Serve `dist-static/` anywhere and the meta list renders from the baked snapshot, no Node in sight. `query` takes an argument, so it needs the live server (next) — or bake specific inputs ([Client Assets](/guide/client-assets)).
+Serve `dist-static/` anywhere and the meta list renders from the baked snapshot, no Node in sight. `query` takes an argument, so it needs the live server (next), or bake specific inputs ([Client Assets](/guide/client-assets)).
 
-## Step 6 — Run it standalone
+## Step 6, Run it standalone
 
 The definition never depended on Vite. `createDevServer` runs the tool on its own, serving the UI from `clientAssets` and answering RPC live:
 
 ```js [scripts/serve.mjs]
 import { createDevServer } from 'devframe/adapters/dev'
-import devframe from '../src/devframe.ts'
+import dataInspectorFrame from '../src/data-inspector.ts'
 
-await createDevServer(devframe, { openBrowser: true })
+await createDevServer(dataInspectorFrame, { openBrowser: true })
 ```
 
 ```sh
 npx vite build
 node scripts/serve.mjs
 ```
 
-Same UI, same live calls — no bundler in the loop. This is what you'd drop into your own Node program.
+Same UI, same live calls, no bundler in the loop. This is what you'd drop into your own Node program.
 
-## Step 7 — Give it a CLI
+## Step 7, Give it a CLI
 
-Finally, wrap that server in a command shell. `createCac` hands you `dev`, `build`, and `mcp` for free:
+Finally, if you want to provide a CLI for standalone use, which wraps that server in a command shell. `devframe/adapters/cac` made it easy to automatically turn a devframe into a CLI with `dev`, `build`, and `mcp` commands. For example:
 
 ```js [bin.mjs]
 #!/usr/bin/env node
 import { createCac } from 'devframe/adapters/cac'
-import devframe from './src/devframe.ts'
+import dataInspectorFrame from './src/data-inspector.ts'
 
-createCac(devframe).parse()
+createCac(dataInspectorFrame).parse()
 ```
 
 ```sh
@@ -309,11 +314,13 @@ node bin.mjs build   # the static build from Step 5
 node bin.mjs mcp     # expose the tool to a coding agent over MCP
 ```
 
-Publish it and the same binary runs with `npx data-inspector`. One definition, five ways to run it — and you never rewrote the tool.
+While you can also build a CLI on your own with the functions provides above.
+
+Let's all for this tutorial. If you want to see a full-featured server data inspector, we have it a as a ready-to-use [plugin](/plugins/data-inspector) that you can play with or reference to.
 
 ## What's next
 
-- [RPC](/guide/rpc) — `action` and `event` calls, end-to-end types, schema validation
-- [Shared State](/guide/shared-state) — push live changes to the UI without polling
-- [Hub](/guide/hub) — docks, commands, terminals across many tools
-- [Agent-Native](/guide/agent-native) — expose your tool to coding agents over MCP
+- [RPC](/guide/rpc), `action` and `event` calls, end-to-end types, schema validation
+- [Shared State](/guide/shared-state), push live changes to the UI without polling
+- [Hub](/guide/hub), docks, commands, terminals across many tools
+- [Agent-Native](/guide/agent-native), expose your tool to coding agents over MCP