feat(doc): add test section

docs/build/auth.mdx

@@ -147,7 +147,7 @@ server
   .registerTool(/* create-checkout … */);
 ```
 
-### Declare Public Tools
+### Declare Tool Visibility
 
 Three declarations cover the combinations:
 
@@ -194,6 +194,10 @@ server.registerTool(
 );
 ```
 
+<Card title="All done!" type="tip" href="/test" horizontal icon="check">
+    You now know how to authenticate users. Learn how to test your MCP App in the next chapter.
+</Card>
+
 ## Go Further
 <Columns cols={3}>
     <Card title="Register Tools" img="/images/tools.png" href="/build/tools">

docs/build/index.mdx

@@ -0,0 +1,29 @@
+---
+title: "Build Your App"
+description: "The four decisions that make an MCP App"
+icon: "drafting-compass"
+---
+
+Building an MCP App means answering four questions: what the model can do, what the user sees, what the model knows, and who is asking. Each page below covers one, in build order, on the same running example: a personal shopper with a product carousel and an authenticated checkout.
+
+| Define | Page | Core APIs |
+|------------|------|-----------|
+| What the model can do | [Register Tools](/build/tools) | `registerTool` |
+| What the user sees | [Create Views](/build/view) | `useToolInfo`, `useCallTool` |
+| What the model knows | [Manage State](/build/state) | `useViewState`, `data-llm` |
+| Who is asking | [Authenticate Users](/build/auth) | `requireBearerAuth`, `securitySchemes` |
+
+<Columns cols={2}>
+    <Card title="Register Tools" img="/images/tools.png" href="/build/tools">
+        Define what humans and agents can do
+    </Card>
+    <Card title="Create Views" img="/images/view.png" href="/build/view">
+        Craft interactive UIs rendered in conversation
+    </Card>
+    <Card title="Manage State" img="/images/state.png" href="/build/state">
+        Decide what the model sees
+    </Card>
+    <Card title="Authenticate Users" img="/images/auth.png" href="/build/auth">
+        Know who's behind every tool call
+    </Card>
+</Columns>

docs/build/state.mdx

@@ -128,9 +128,11 @@ export default function Carousel() {
 }
 ```
 
-This is what lets the user speak in references: "what do you think of this one?". The model resolves *this one* from the `data-llm` narration.
+This is what lets the user speak in references: "what do you think of this one?". The model resolves *this one* from the `data-llm` narration. Nest `data-llm` on inner elements and the model receives an indented outline of the screen.
 
-Nest `data-llm` on inner elements and the model receives an indented outline of the screen.
+<Card title="All done!" type="tip" href="/build/auth" horizontal icon="check">
+    You now know how to manage state. Learn who's behind every tool call in the next chapter.
+</Card>
 
 ## Go Further
 <Columns cols={3}>

docs/build/tools.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Register Tools"
 description: "Define what humans and agents can do"
-icon: "tools"
+icon: "wrench"
 ---
 <img src="/images/tools.png" alt="Tools Illustration" style={{ width: "100%", maxHeight: "40vh", marginTop:"-0.75rem", objectFit: "cover", borderRadius: "15px" }} />
 
@@ -271,6 +271,10 @@ export default function Carousel() {
 
 Each model call to the tool mounts a fresh view instance. Tools without `view` are headless: data, no UI.
 
+<Card title="All done!" type="tip" href="/build/view" horizontal icon="check">
+    You now know how to register tools. Learn what happens inside the view in the next chapter.
+</Card>
+
 ## Go Further
 <Columns cols={3}>
     <Card title="Create Views" img="/images/view.png" href="/build/view">

docs/build/view.mdx

@@ -197,9 +197,9 @@ server.registerTool(
 
 {/* @todo: full csp reference */}
 
-## Manage State
-
-Reading output and calling tools cover a view's request side. Everything in between (a cart filling up, a selection, a draft) is state. And it moves both ways: the user changes it by interacting, and the model can change it too, by triggering a tool the view registered. Held by the view, shared with the model, restored across remounts: that's [the next chapter](/build/state).
+<Card title="All done!" type="tip" href="/build/state" horizontal icon="check">
+    You now know how to create views. Learn what the view holds between tool calls, and who sees it, in the next chapter.
+</Card>
 
 ## Go Further
 <Columns cols={3}>

docs/docs.json

@@ -35,12 +35,26 @@
           {
             "group": "Build",
             "icon": "drafting-compass",
+            "root": "build/index",
             "pages": [
               "build/tools",
               "build/view",
               "build/state",
               "build/auth"
-            ]
+            ],
+            "expanded": true
+          },
+          {
+            "group": "Test",
+            "icon": "test-tube-diagonal",
+            "root": "test/index",
+            "pages": [
+              "test/devtools",
+              "test/tunnel",
+              "test/playground",
+              "test/audit"
+            ],
+            "expanded": true
           },
           {
             "group": "Get Started (legacy)",
@@ -293,5 +307,8 @@
   },
   "interaction": {
     "drilldown": false
+  },
+  "icons": {
+    "library": "lucide"
   }
 }

docs/get-started/introduction.mdx

@@ -51,13 +51,13 @@ MCP Apps introduce a fundamental shift: unlike bidirectional web apps, they are
 
 {/* @todo: turn those into tiles with images */}
 <Columns cols={3}>
-    <Card title="Architecture" icon="route" href="/get-started/architecture">
+    <Card title="Architecture" img="/images/architecture.png" href="/get-started/architecture">
         Design experiences leveraging model intelligence.
     </Card>
-    <Card title="Tools" icon="tools">
+    <Card title="Tools" img="/images/tools.png" href="/build/tools">
         Define what humans and agents can see and do.
     </Card>
-    <Card title="Views" icon="palette">
+    <Card title="Views" img="/images/view.png" href="/build/view">
         Craft interactive UIs rendered in conversation.
     </Card>
 </Columns>

docs/get-started/quickstart.mdx

@@ -1,14 +1,13 @@
 ---
 title: "Quickstart"
 description: "Build, test, and deploy your first MCP App"
-icon: "bolt"
-iconType: "regular"
+icon: "zap"
 ---
 <img src="/images/quickstart.png" alt="Quickstart Illustration" style={{ width: "100%", maxHeight: "40vh", marginTop:"-0.75rem", objectFit: "cover", borderRadius: "15px" }} />
 
 To get a running codebase right away, you can scaffold a project from our templates. They come pre-configured with:
 - a working MCP server
-- a complete development environment with a local emulator, file watching, and hot module reload.
+- a complete development environment with a local emulator, file watching, and hot module reload
 
 <Info>
 Prerequisite: Skybridge runs on [Node 24+](https://nodejs.org/en/download)

docs/test/audit.mdx

@@ -0,0 +1,64 @@
+---
+title: "Audit"
+description: "Catch spec and platform issues before submission"
+icon: "clipboard-check"
+---
+<img src="/images/audit.png" alt="Audit Illustration" style={{ width: "100%", maxHeight: "40vh", marginTop:"-0.75rem", objectFit: "cover", borderRadius: "15px" }} />
+
+Before a platform accepts your app, the server must conform to the MCP specs, and each platform layers its own requirements on top, which differ between OpenAI and Anthropic. The Audit checks your app's conformance and performs end-to-end tests in real ChatGPT and Claude conversations, triggering tools and rendering views.
+
+## Run the Audit
+
+The Audit needs your server publicly reachable: start the [tunnel](/test/tunnel), then click **Audit** in the [DevTools](/test/devtools) header.
+
+<CodeGroup>
+```bash npm
+npm run dev -- --tunnel
+```
+```bash pnpm
+pnpm dev --tunnel
+```
+```bash yarn
+yarn dev --tunnel
+```
+```bash bun
+bun dev --tunnel
+```
+```bash deno
+deno task dev --tunnel
+```
+</CodeGroup>
+
+<Info>
+The Audit is powered by [Alpic Beacon](https://docs.alpic.ai/testing/beacon). It can also be launched from [beacon.alpic.ai](https://beacon.alpic.ai) with your server's public URL, or via the [Alpic CLI](https://docs.alpic.ai/cli/tunnel).
+</Info>
+
+## What It Checks
+
+- **MCP protocol**: tool and resource conformance with the official specification.
+- **MCP Apps**: view resource requirements (metadata, Content Security Policy, annotations) for both ChatGPT and Claude.
+- **Platform requirements**: each platform's own submission guidelines.
+- **App behavior**: the app actually works, verified by triggering tools and rendering views in real ChatGPT and Claude conversations.
+
+<Frame caption="The Audit interface">
+<img src="/images/audit-screenshot.png" alt="Audit Illustration" />
+</Frame>
+
+The report returns an overall score, a readiness status per platform, and the issues found, each with its severity (error, warning, info), the affected component, and the solution. **Improve your score** turns the report into a prompt for your coding agent to fix them all.
+
+## Limitation
+
+OAuth-protected servers aren't supported yet.
+
+## Go Further
+<Columns cols={3}>
+    <Card title="DevTools" img="/images/devtools.png" href="/test/devtools">
+        Call tools and render views locally, without a host
+    </Card>
+    <Card title="Tunnel" img="/images/tunnel.png" href="/test/tunnel">
+        Expose your local server to real hosts
+    </Card>
+    <Card title="Playground" img="/images/playground.png" href="/test/playground">
+        Chat with a real model running your app
+    </Card>
+</Columns>

docs/test/devtools.mdx

@@ -0,0 +1,85 @@
+---
+title: "DevTools"
+description: "Call tools and render views locally, without a host"
+icon: "square-dashed-mouse-pointer"
+---
+{/* @todo: devtools illustration asset */}
+<img src="/images/devtools.png" alt="DevTools Illustration" style={{ width: "100%", maxHeight: "40vh", marginTop:"-0.75rem", objectFit: "cover", borderRadius: "15px" }} />
+
+Testing through a real host means exposing a public URL, registering a connector, starting a conversation, and prompting the model until it calls the right tool. DevTools cuts that loop down to a file save: it runs locally, emulates the host runtime, and lets you call tools directly, no model or host involved.
+
+## Start the Emulator
+
+DevTools ships with the dev server. In a scaffolded project (`npx skybridge create`), start it from the project root:
+
+<CodeGroup>
+```bash npm
+npm run dev
+```
+```bash pnpm
+pnpm dev
+```
+```bash yarn
+yarn dev
+```
+```bash bun
+bun dev
+```
+```bash deno
+deno task dev
+```
+</CodeGroup>
+
+Two routes come up:
+- `http://localhost:3000/mcp`: your MCP server
+- `http://localhost:3000/`: the DevTools
+
+Every tool registered on the server appears in the sidebar automatically, and edits to the server or the views reload the preview on save.
+
+## Explore the Features
+
+Select a tool in the sidebar and DevTools gives you the full exchange:
+
+<Frame caption="The DevTools interface">
+<img src="/images/devtools-screenshot.png" alt="DevTools Illustration" />
+</Frame>
+
+- **Tool controls**: generated from the tool's input schema. Inputs can be saved and re-run from the tool header.
+- **Tool output**: the raw server response (`content`, `structuredContent`, `_meta`), with status, latency, and payload size.
+- **State inspector**: the view state as a JSON tree, updated as the view mutates it.
+- **View preview**: the rendered view, with live controls to switch display mode, theme, locale, and device type; the preview updates immediately.
+- **Call logs**: every runtime API call the view makes (`setViewState`, `callTool`, `requestDisplayMode`) with its arguments and responses.
+
+## Limitations
+
+DevTools emulates, and three gaps separate the emulation from production:
+
+- **No model**: you pick the tool and type the arguments yourself. Tool selection, the prompt surface (names, descriptions, schemas), and follow-up messages are never exercised.
+- **One runtime**: as of today the preview mocks the Apps SDK runtime. MCP Apps-specific features are not yet supported.
+- **Loose CSP**: external resources blocked by hosts in production may load locally.
+
+## Custom Integration
+
+Projects created with `npx skybridge create` serve DevTools automatically. If you added Skybridge to an existing Express app instead, register the two DevTools middlewares yourself:
+
+```ts server.ts
+import { devtoolsStaticServer, viewsDevServer } from "skybridge/server";
+
+if (process.env.NODE_ENV !== "production") {
+  app.use(await devtoolsStaticServer());
+  app.use(await viewsDevServer());
+}
+```
+
+## Go Further
+<Columns cols={3}>
+    <Card title="Tunnel" img="/images/tunnel.png" href="/test/tunnel">
+        Expose your local server to real hosts
+    </Card>
+    <Card title="Playground" img="/images/playground.png" href="/test/playground">
+        Chat with a real model running your app
+    </Card>
+    <Card title="Audit" img="/images/audit.png" href="/test/audit">
+        Catch spec and platform issues before submission
+    </Card>
+</Columns>

docs/test/index.mdx

@@ -0,0 +1,29 @@
+---
+title: "Test Your App"
+description: "Pick the right tool for what you're testing"
+icon: "test-tube-diagonal"
+---
+
+Testing an MCP App means assessing how well it integrates with the host, interacts with the model, and responds to the user. The tools below put these actors in the loop, each trading setup for fidelity.
+
+| To | Use | Real model | Real host | Interactive |
+|-------------|-----|------------|-----------|-------------|
+| Iterate on tools and views | [DevTools](/test/devtools) | <Icon icon="x" color="#EF4444" /> | <Icon icon="x" color="#EF4444" /> | <Icon icon="check" color="#22C55E" /> |
+| Verify behavior in ChatGPT and Claude | [Tunnel](/test/tunnel) | <Icon icon="check" color="#22C55E" /> | <Icon icon="check" color="#22C55E" /> | <Icon icon="check" color="#22C55E" /> |
+| Check what the model does with your app | [Playground](/test/playground) | <Icon icon="check" color="#22C55E" /> | <Icon icon="x" color="#EF4444" /> | <Icon icon="check" color="#22C55E" /> |
+| Validate before submission | [Audit](/test/audit) | <Icon icon="check" color="#22C55E" /> | <Icon icon="check" color="#22C55E" /> | <Icon icon="x" color="#EF4444" /> |
+
+<Columns cols={2}>
+    <Card title="DevTools" img="/images/devtools.png" href="/test/devtools">
+        Call tools and render views locally, without a host
+    </Card>
+    <Card title="Tunnel" img="/images/tunnel.png" href="/test/tunnel">
+        Expose your local server to real hosts
+    </Card>
+    <Card title="Playground" img="/images/playground.png" href="/test/playground">
+        Chat with a real model running your app
+    </Card>
+    <Card title="Audit" img="/images/audit.png" href="/test/audit">
+        Catch spec and platform issues before submission
+    </Card>
+</Columns>