Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Docs: connect-mcp, agent-workflows and optimize-for-agents learn pages

Nguyen Xuan An7cf61d00cc7a
diff --git a/changes/docs-agent-harnesses.md b/changes/docs-agent-harnesses.md
new file mode 100644
index 00000000..08d5c214
--- /dev/null
+++ b/changes/docs-agent-harnesses.md
@@ -0,0 +1 @@
+- Add three learn pages for AI agents and tighten `models-and-ai-agents`. `connect-mcp` gives the launch command and the config file for nine harnesses (Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI, Antigravity, Cline, Zed), a check and troubleshooting. `agent-workflows` shows the real result of each tool, the render loop, skills and the no-MCP path. `optimize-for-agents` has measured tool, result and image costs and the agent-modeling results.
diff --git a/docs/learn/agent-workflows.md b/docs/learn/agent-workflows.md
new file mode 100644
index 00000000..5aeb63d2
--- /dev/null
+++ b/docs/learn/agent-workflows.md
@@ -0,0 +1,441 @@
+# Working with agents
+
+This page shows what to ask an agent, which tools it calls, and what each tool returns. It assumes that you [connected the MCP server](#connect-mcp). The results below are real. They came from the `67js-mcp` server, version 0.15.0, started with `--backend cpu`.
+
+## Prompts and the tools they trigger
+
+An agent picks tools from your words. You do not name tools. These prompts show the pattern:
+
+| You say | The agent calls |
+| --- | --- |
+| "What can 67js do here? What are the limits?" | `scene_capabilities` |
+| "Build a wooden table with four legs." | `scene_create` |
+| "Show me." | `scene_look` |
+| "What parts does the scene have? How big are they?" | `scene_inspect` |
+| "Make the legs thicker and add a shelf." | `scene_apply` |
+| "Save this state, then try a glass top." | `scene_checkpoint`, then `scene_apply`, and `scene_restore` to go back |
+| "Try the top in red, blue and green and keep the best." | `scene_apply` with a `branch` for each, one `scene_review`, then `scene_restore` with the winning `branch` |
+| "Show the front, the side and the top." | `scene_review` |
+| "The legs look bent. Check the mesh." | `mesh_inspect`, then `mesh_edit` |
+| "Use the robot from my models folder." | `scene_asset_catalog`, then `scene_create_asset` |
+| "Render a 1920 by 1080 PNG." | `scene_render_submit`, `scene_render_status`, `scene_render_result` |
+| "Give me a GLB file." | `scene_export_glb` |
+| "Save the recipe so I can reuse it." | `scene_export_recipe` |
+
+`--assets` must be set for the robot prompt, and `--jobs` for the render prompt. [Connect the MCP server](#connect-mcp) has both options.
+
+## A first session
+
+The session below builds a table. Each block shows what the agent receives.
+
+### 1. Start the connection
+
+The client sends `initialize`. The server answers with its name, version and instructions for the agent. The instructions string is shortened here:
+
+```json
+{
+ "protocolVersion": "2025-06-18",
+ "capabilities": {
+ "tools": {"listChanged":true}
+ },
+ "serverInfo": {"name":"67js-scene","version":"0.15.0"},
+ "instructions": "Start with scene_capabilities. ..."
+}
+```
+
+### 2. Read the limits
+
+`scene_capabilities` returns the recipe format, the geometry types, the limits and what is unsupported. The result is about 24 KB, so the agent calls it once per session. These are some of its fields:
+
+```json
+{
+ "scene": {
+ "format": "67js.scene",
+ "schemaVersion": 1,
+ "geometryTypes": ["box","cylinder","sphere","torus","lathe","extrude","tube","curve","text","grid","terrain","mesh"],
+ "...": "..."
+ },
+ "sceneLimits": {
+ "maxNodes": 4096,
+ "maxDepth": 256,
+ "maxGeometries": 256,
+ "maxMaterials": 256,
+ "maxVertices": 250000,
+ "maxGeometryBytes": 33554432,
+ "maxOperations": 256,
+ "maxCheckpoints": 8,
+ "maxRecipeBytes": 1048576
+ },
+ "preview": {
+ "backend": "cpu",
+ "memoryBudgetMiB": 192,
+ "maximumWidth": 1024,
+ "maximumHeight": 1024,
+ "maximumImageBytes": 1048576,
+ "maximumActiveScenes": 1,
+ "maximumQueuedCalls": 16,
+ "evaluationTimeoutMs": 30000
+ },
+ "review": {
+ "minimumShots": 1,
+ "maximumShots": 4,
+ "minimumDimension": 64,
+ "maximumDimension": 480,
+ "defaultWidth": 384,
+ "defaultHeight": 384,
+ "labelHeight": 24,
+ "maximumLabelLength": 48,
+ "maximumGridWidth": 960,
+ "maximumGridHeight": 1008,
+ "maximumImageBytes": 1048576,
+ "maximumPendingFrames": 1,
+ "backend": "cpu",
+ "memoryBudgetMiB": 192,
+ "evaluationTimeoutMs": 30000,
+ "totalTimeoutMs": 30000,
+ "sourcePreserved": true,
+ "defaultMotionTime": null,
+ "defaultRendererTime": 0,
+ "branches": {"maximumBranches":8,"maximumNameLength":24,"maximumLabels":24}
+ },
+ "jobs": {"configured":true,"kinds":["image","stills","video"],"passes":["albedo","normal","emission","depth","objectId"],"...":"..."},
+ "unsupported": ["remote asset providers","arbitrary code execution","imported morph track authoring"]
+}
+```
+
+### 3. Create the scene
+
+The agent sends a recipe: geometries, materials, nodes and a camera. `scene_create` returns the session ID, the revision and an inspection of the node tree:
+
+```json
+{
+ "sessionId": "1f0ac91e-860f-4332-b6e6-44e7007a81a1",
+ "revision": 0,
+ "topologyRevision": 0,
+ "inspection": {
+ "revision": 0,
+ "topologyRevision": 0,
+ "motion": null,
+ "physics": null,
+ "boundsSpace": "authored-base-world",
+ "counts": {"nodes":3,"parts":2,"geometries":2,"materials":1,"vertices":1578},
+ "geometryBytes": 70272,
+ "estimatedGeometryBytes": 88368,
+ "residentGeometryBytes": 70272,
+ "residentGeometryVertices": 1578,
+ "look": {"world":false,"pointLights":0,"spotLights":0,"areaLights":0,"volumeFogDensity":0,"exposure":1},
+ "nodes": [
+ {"id":"table","label":"table","parent":null,"geometry":null,"material":null,"vertices":0,"triangles":0},
+ {"id":"top","label":"top","parent":"table","geometry":"top","material":"wood","vertices":1176,"triangles":2028},
+ {"id":"leg-a","label":"leg-a","parent":"table","geometry":"leg","material":"wood","vertices":402,"triangles":672}
+ ],
+ "truncated": false
+ },
+ "render": {
+ "graphics": "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)",
+ "estimatedBytes": 34304152,
+ "width": 768,
+ "height": 512,
+ "samples": 0,
+ "hdr": true,
+ "depth": true,
+ "geometryBuffers": 3,
+ "materialTextures": 0,
+ "skinTextures": 0,
+ "morphTextures": 0,
+ "gpuBuffers": 12,
+ "drawBatches": 3
+ }
+}
+```
+
+The `render.graphics` field names the renderer. Here it is SwiftShader, the software renderer of the `cpu` backend. With `--backend gpu` it names your graphics card.
+
+### 4. Look
+
+`scene_look` returns two content blocks. The first is a PNG image. The second is this JSON text, so the agent can read facts without reading the picture:
+
+```json
+{
+ "sessionId": "1f0ac91e-860f-4332-b6e6-44e7007a81a1",
+ "revision": 0,
+ "topologyRevision": 0,
+ "motionTime": null,
+ "graphics": "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)",
+ "estimatedBytes": 24211608,
+ "width": 512,
+ "height": 320,
+ "samples": 0,
+ "hdr": true,
+ "depth": true,
+ "geometryBuffers": 3,
+ "materialTextures": 0,
+ "skinTextures": 0,
+ "morphTextures": 0,
+ "gpuBuffers": 12,
+ "drawBatches": 3,
+ "requestedWidth": 512,
+ "requestedHeight": 320,
+ "backend": "cpu"
+}
+```
+
+The image has the size that the agent asked for, here 512 by 320 pixels. It looks like this for the first revision, which has one leg:
+
+![The first look: a table top on one leg](/docs-media/agent-scene-look.webp)
+
+### 5. Edit in one batch
+
+`scene_apply` takes the revision that the agent last saw and a list of operations. This call adds three legs at once:
+
+```json
+{
+ "sessionId": "1f0ac91e-860f-4332-b6e6-44e7007a81a1",
+ "revision": 1,
+ "topologyRevision": 1,
+ "inspection": {
+ "revision": 1,
+ "topologyRevision": 1,
+ "motion": null,
+ "physics": null,
+ "boundsSpace": "authored-base-world",
+ "counts": {"nodes":6,"parts":5,"geometries":2,"materials":1,"vertices":1578},
+ "geometryBytes": 70272,
+ "estimatedGeometryBytes": 88368,
+ "residentGeometryBytes": 70272,
+ "residentGeometryVertices": 1578,
+ "look": {"world":false,"pointLights":0,"spotLights":0,"areaLights":0,"volumeFogDensity":0,"exposure":1},
+ "nodes": [
+ {"id":"table","label":"table","parent":null,"geometry":null,"material":null,"vertices":0,"triangles":0},
+ {"id":"top","label":"top","parent":"table","geometry":"top","material":"wood","vertices":1176,"triangles":2028},
+ {"id":"leg-a","label":"leg-a","parent":"table","geometry":"leg","material":"wood","vertices":402,"triangles":672},
+ {"id":"leg-b","label":"leg-b","parent":"table","geometry":"leg","material":"wood","vertices":402,"triangles":672},
+ {"id":"leg-c","label":"leg-c","parent":"table","geometry":"leg","material":"wood","vertices":402,"triangles":672},
+ {"id":"leg-d","label":"leg-d","parent":"table","geometry":"leg","material":"wood","vertices":402,"triangles":672}
+ ],
+ "truncated": false
+ },
+ "render": {
+ "graphics": "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)",
+ "estimatedBytes": 24212100,
+ "width": 512,
+ "height": 320,
+ "samples": 0,
+ "hdr": true,
+ "depth": true,
+ "geometryBuffers": 3,
+ "materialTextures": 0,
+ "skinTextures": 0,
+ "morphTextures": 0,
+ "gpuBuffers": 12,
+ "drawBatches": 3
+ },
+ "committed": true,
+ "renderSucceeded": true
+}
+```
+
+`committed: true` means that the edit is in the scene. `renderSucceeded: true` means that the preview drew it. If the preview fails, the edit stays, and the result says `renderSucceeded: false` with a `renderError`.
+
+### 6. Look with labels
+
+`scene_look` with `labels: true` prints each part's name on the picture and returns its pixel position. The agent can match a name to what it sees:
+
+![The table with part names printed on it](/docs-media/agent-scene-look-labels.webp)
+
+```json
+{
+ "sessionId": "1f0ac91e-860f-4332-b6e6-44e7007a81a1",
+ "revision": 1,
+ "topologyRevision": 1,
+ "motionTime": null,
+ "graphics": "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)",
+ "estimatedBytes": 24212100,
+ "width": 512,
+ "height": 320,
+ "samples": 0,
+ "hdr": true,
+ "depth": true,
+ "geometryBuffers": 3,
+ "materialTextures": 0,
+ "skinTextures": 0,
+ "morphTextures": 0,
+ "gpuBuffers": 12,
+ "drawBatches": 3,
+ "labels": [
+ {"id":"top","name":"top","tag":"surface","faceTags":["left","side","right","bottom","top","back"],"problems":[],"x":256,"y":131},
+ {"id":"leg-a","name":"leg-a","tag":"surface","faceTags":["bottom","right","side","front","left","back"],"problems":[],"x":230,"y":154},
+ {"id":"leg-b","name":"leg-b","tag":"surface","faceTags":["bottom","right","side","front","left","back"],"problems":[],"x":335,"y":182},
+ {"id":"leg-c","name":"leg-c","tag":"surface","faceTags":["bottom","right","side","front","left","back"],"problems":[],"x":183,"y":169},
+ {"id":"leg-d","name":"leg-d","tag":"surface","faceTags":["bottom","right","side","front","left","back"],"problems":[],"x":291,"y":204}
+ ],
+ "requestedWidth": 512,
+ "requestedHeight": 320,
+ "backend": "cpu"
+}
+```
+
+### 7. Errors say what to do
+
+A call with an old revision fails without changing the scene. The result has `isError: true` and this text:
+
+```text
+scene_apply failed: expectedRevision must match the current revision.
+```
+
+A call that names a missing part fails the same way:
+
+```text
+scene_apply failed: set-node target was not found: nope. scene_inspect lists the IDs; add it first with an add operation.
+```
+
+The agent reads the message, calls `scene_inspect` to get the current state, and sends the call again.
+
+## The render loop: render, look, fix
+
+An agent works best in a loop. It makes a cheap picture, checks the picture, fixes what is wrong, and renders the final file only at the end.
+
+1. **Preview.** `scene_look` at the default 768 by 512 pixels, or smaller. With the `cpu` backend, the two looks above took 208 ms and 321 ms.
+2. **Look.** The agent reads the picture and the `labels` JSON. It lists what is wrong: a part that floats, a camera that cuts off the subject, a dark shadow.
+3. **Fix.** One `scene_apply` batch with the current `expectedRevision`. Then back to step 1.
+4. **Checkpoint.** Before a risky change, `scene_checkpoint`. If the change fails, `scene_restore` returns to the saved state.
+5. **Final render.** `scene_render_submit` with the final size, then `scene_render_status` until the state is `completed`, then `scene_render_result`.
+
+The final render is a job. The next three blocks show an image job of 640 by 400 pixels. The submit call returns a job record at once:
+
+```json
+{
+ "schemaVersion": 1,
+ "jobId": "5e37aa83-ebbe-42d3-956f-e4ae22d21c99",
+ "sourceRevision": 0,
+ "state": "queued",
+ "settings": {
+ "kind": "image",
+ "width": 640,
+ "height": 400,
+ "fps": 24,
+ "duration": 1,
+ "frameCount": 1,
+ "rendererTime": {"start":0,"rate":1}
+ },
+ "progress": {"frames":0,"maximumPendingFrames":0},
+ "artifacts": []
+}
+```
+
+The status call shows the progress and, when the job is done, the file and the timings:
+
+```json
+{
+ "schemaVersion": 1,
+ "jobId": "5e37aa83-ebbe-42d3-956f-e4ae22d21c99",
+ "sourceRevision": 0,
+ "state": "completed",
+ "settings": {
+ "kind": "image",
+ "width": 640,
+ "height": 400,
+ "fps": 24,
+ "duration": 1,
+ "frameCount": 1,
+ "rendererTime": {"start":0,"rate":1}
+ },
+ "progress": {"frames":1,"maximumPendingFrames":1},
+ "artifacts": [
+ {"filename":"render.png","mimeType":"image/png","bytes":22312,"sha256":"3b0f65321dace0c1eb7ee9c18c739356da4d4d777e3a9431a905c6027396a626"}
+ ],
+ "metrics": {
+ "backend": "cpu",
+ "requestedWidth": 640,
+ "requestedHeight": 400,
+ "renderSeconds": 0.18262570000000006,
+ "captureSeconds": 0.051269700000000286,
+ "peakNodeBytes": 180748288,
+ "peakBrowserHeap": 5409100,
+ "maximumPendingFrames": 1,
+ "graphics": "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)",
+ "width": 640,
+ "height": 400,
+ "estimatedBytes": 28266648,
+ "elapsedSeconds": 1.1123075000000002
+ }
+}
+```
+
+The result call returns the path of the file in the jobs folder. The agent reads the PNG from that path with its own file tool. The path below starts with `<jobs>`, which stands for the folder that you gave to `--jobs`:
+
+```json
+{
+ "jobId": "5e37aa83-ebbe-42d3-956f-e4ae22d21c99",
+ "sourceRevision": 0,
+ "artifacts": [
+ {
+ "filename": "render.png",
+ "mimeType": "image/png",
+ "bytes": 22312,
+ "sha256": "3b0f65321dace0c1eb7ee9c18c739356da4d4d777e3a9431a905c6027396a626",
+ "path": "<jobs>/5e37aa83-ebbe-42d3-956f-e4ae22d21c99/render.png"
+ }
+ ],
+ "metrics": {
+ "backend": "cpu",
+ "requestedWidth": 640,
+ "requestedHeight": 400,
+ "renderSeconds": 0.18262570000000006,
+ "captureSeconds": 0.051269700000000286,
+ "peakNodeBytes": 180748288,
+ "peakBrowserHeap": 5409100,
+ "maximumPendingFrames": 1,
+ "graphics": "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)",
+ "width": 640,
+ "height": 400,
+ "estimatedBytes": 28266648,
+ "elapsedSeconds": 1.1123075000000002
+ }
+}
+```
+
+While a job runs, previews and edits pause. Inspection and recipe export still work. After the job, call `scene_render_release` to delete files that you no longer need. [Render jobs](/agent-render-jobs.md) covers sequences, video, render passes and the path tracer.
+
+## Skills
+
+A skill is a folder with a `SKILL.md` file. It gives an agent a procedure and the names of the files to read. The npm package includes two skills:
+
+- `build-67js-scene` for building and refining scenes.
+- `render-67js-media` for PNG and MP4 export, backends and memory limits.
+
+Copy them from the installed package into the skill folder of your harness. Run this in your project folder, after `npm install 67js@npm:@codepawlhq/67js`:
+
+```sh
+mkdir -p .agents/skills
+cp -r node_modules/67js/skills/build-67js-scene node_modules/67js/skills/render-67js-media .agents/skills/
+```
+
+In PowerShell, run this instead:
+
+```powershell
+New-Item -ItemType Directory -Force .agents/skills | Out-Null
+Copy-Item -Recurse node_modules/67js/skills/build-67js-scene, node_modules/67js/skills/render-67js-media .agents/skills/
+```
+
+Each harness reads its own folder:
+
+| Harness | Project folder | User folder | Source |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` | [Claude Code skills docs](https://code.claude.com/docs/en/skills) |
+| OpenAI Codex | `.agents/skills/` | `~/.agents/skills/` | [Codex skills docs](https://developers.openai.com/codex/skills) |
+| Gemini CLI | `.gemini/skills/` or `.agents/skills/` | `~/.gemini/skills/` or `~/.agents/skills/` | [Gemini CLI skills docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md) |
+| Cursor | `.cursor/skills/` or `.agents/skills/` | `~/.cursor/skills/` or `~/.agents/skills/` | [Cursor skills docs](https://cursor.com/docs/skills) |
+
+For Claude Code, replace `.agents/skills` in the commands above with `.claude/skills`. The other harnesses in [Connect the MCP server](#connect-mcp) have no skill folder that this page confirmed. For those, tell the agent to read the two `SKILL.md` files, or add the line `Read node_modules/67js/skills/build-67js-scene/SKILL.md before you build a scene` to the project's `AGENTS.md`.
+
+The skills were written for work in a 67js source checkout. Some steps name files such as `scripts/render-media.mjs`. With the npm package, the agent finds the scene and render guides in `node_modules/67js/docs/`, for example `agent-scene.md` and `agent-render-jobs.md`.
+
+## Without MCP
+
+Some harnesses have no MCP support. An agent can still use 67js. Give it these two things:
+
+1. The map of the docs at [`/llms.txt`](/llms.txt) and the full text at [`/guide.md`](/guide.md).
+2. A script that renders a picture. [Render a PNG from a script without MCP](#render-a-png-from-a-script-without-mcp) has one that was tested.
+
+The agent writes JavaScript against the installed package, runs the script, and reads the PNG that the script saves. This path needs more steps for each picture than the MCP path. The agent must start a browser itself and manage its own scene state. See [Optimise agent runs](#optimize-for-agents) for the cost of each path.
diff --git a/docs/learn/connect-mcp.md b/docs/learn/connect-mcp.md
new file mode 100644
index 00000000..2b822980
--- /dev/null
+++ b/docs/learn/connect-mcp.md
@@ -0,0 +1,282 @@
+# Connect the MCP server
+
+This page connects the 67js MCP server to an AI agent harness. A harness is the program that runs the agent, such as Claude Code or Cursor. At the end, the agent can build a scene and show you a picture of it.
+
+## What the server is
+
+`67js-mcp` is a local program. The harness starts it and talks to it over stdin and stdout. It has no network listener for MCP.
+
+The server holds one active scene. When the agent calls `scene_create`, the server starts your installed Chrome in the background and renders the scene there. It gives the agent 22 tools to build, look at and export the scene. The tools take JSON, and they never run code that the agent writes.
+
+You need two things:
+
+- **Node.js 20.19 or later.** Run `node --version` to check.
+- **Google Chrome or another Chromium.** The server does not download a browser.
+
+Check that the server starts. This command downloads the package and prints its version:
+
+```sh
+npx -y --package @codepawlhq/67js 67js-mcp --version
+```
+
+The command prints the version, for example `0.15.0`. The package on npm is `@codepawlhq/67js` and its command is `67js-mcp`.
+
+## The launch command
+
+Every harness below runs the same command. These are the parts of it:
+
+```text
+npx -y --package @codepawlhq/67js 67js-mcp --backend gpu --memory 192
+```
+
+`--backend` is `gpu` or `cpu`. Use `cpu` on a machine with no graphics card or on a remote machine. `--memory` is the render budget in MiB, from 32 to 384. The default is 192. These options are optional too:
+
+| Option | Value | What it does |
+| --- | --- | --- |
+| `--browser` | Path to a Chrome or Chromium executable | Use a browser other than the installed Google Chrome. |
+| `--assets` | Absolute path to a folder of GLB files | Lets the agent place those models. |
+| `--jobs` | Absolute path to a private folder | Turns on the render job tools for PNG, image sequences and MP4. |
+| `--ffmpeg` | Absolute path to FFmpeg | Sets the encoder for MP4 jobs. FFmpeg on `PATH` works without it. |
+| `--audio` | Absolute path to a folder of sound files | Lets video jobs add sound. |
+
+`67js-mcp --help` prints the same list. Add `@0.15.0` after the package name to pin a version, as in `@codepawlhq/[email protected]`.
+
+### The node form
+
+The first `npx` run downloads the package, which can take longer than a harness waits for a server to start. A harness on Windows can also fail to start `npx`. In both cases, install the package once and start Node directly:
+
+```sh
+npm install 67js@npm:@codepawlhq/67js
+```
+
+Then replace `command` and `args` in any snippet below with the absolute path of Node and of the installed script. This example is for Windows:
+
+```json
+{
+ "command": "C:/Program Files/nodejs/node.exe",
+ "args": ["C:/projects/my-scene/node_modules/67js/bin/67js-mcp.mjs", "--backend", "gpu", "--memory", "192"]
+}
+```
+
+On macOS and Linux, use the output of `which node` as the command. Use forward slashes in JSON on Windows. A backslash needs a second backslash.
+
+## Claude Code
+
+Claude Code can add the server with one command. Everything after `--` is the launch command:
+
+```sh
+claude mcp add --transport stdio 67js-scene -- npx -y --package @codepawlhq/67js 67js-mcp --backend gpu --memory 192
+```
+
+The command writes to your local scope. Add `--scope project` to write a `.mcp.json` file in the project root that you can commit, or `--scope user` to use the server in every project. You can also write `.mcp.json` yourself:
+
+```json
+{
+ "mcpServers": {
+ "67js-scene": {
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"]
+ }
+ }
+}
+```
+
+Claude Code asks you to approve a server from `.mcp.json` the first time you run `claude` in that folder. Run `claude mcp get 67js-scene` to see its status. Inside a session, `/mcp` shows the same list.
+
+If the server needs more than the default time to start, set `MCP_TIMEOUT` in milliseconds, as in `MCP_TIMEOUT=60000 claude`. Source: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp).
+
+## Claude Desktop
+
+Open Settings, then Developer, then Edit Config. The file is:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+Add the server under `mcpServers`:
+
+```json
+{
+ "mcpServers": {
+ "67js-scene": {
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"]
+ }
+ }
+}
+```
+
+Restart Claude Desktop completely. A desktop app does not read your shell `PATH`, so it can start a different Node than your terminal does. If the server does not appear, use the node form with absolute paths. The logs are in `%APPDATA%\Claude\logs` on Windows. Source: [Model Context Protocol, connect local servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
+
+## Cursor
+
+Cursor reads `.cursor/mcp.json` in a project and `~/.cursor/mcp.json` for every project. Use the same `mcpServers` shape:
+
+```json
+{
+ "mcpServers": {
+ "67js-scene": {
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"]
+ }
+ }
+}
+```
+
+Cursor lists the server under its Customize page. Source: [Cursor MCP docs](https://cursor.com/docs/mcp).
+
+## VS Code
+
+VS Code runs MCP servers for GitHub Copilot chat. It reads `.vscode/mcp.json` in a workspace, or an `mcp.json` in your user profile. This file uses `servers`, not `mcpServers`, and it has a `type`:
+
+```json
+{
+ "servers": {
+ "67js-scene": {
+ "type": "stdio",
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"]
+ }
+ }
+}
+```
+
+To see the server's tools, open Chat, then Customizations, then Tools. In a local harness session, use Configure Tools in the chat input. Source: [VS Code MCP configuration reference](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration).
+
+## OpenAI Codex CLI
+
+Codex stores MCP servers in `~/.codex/config.toml`. A project can have its own `.codex/config.toml`. Add a table for the server:
+
+```toml
+[mcp_servers.67js-scene]
+command = "npx"
+args = ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"]
+startup_timeout_sec = 60
+tool_timeout_sec = 120
+```
+
+The default start timeout is 10 seconds, so the first `npx` download can fail without `startup_timeout_sec`. The default tool timeout is 60 seconds. You can also add the server from the shell:
+
+```sh
+codex mcp add 67js-scene -- npx -y --package @codepawlhq/67js 67js-mcp --backend gpu --memory 192
+```
+
+Source: [Codex MCP docs](https://developers.openai.com/codex/mcp).
+
+## Gemini CLI
+
+Gemini CLI reads `~/.gemini/settings.json` for every project and `.gemini/settings.json` for one project. Add `mcpServers` to the file. Keep the other settings in it:
+
+```json
+{
+ "mcpServers": {
+ "67js-scene": {
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"],
+ "timeout": 120000
+ }
+ }
+}
+```
+
+`timeout` is in milliseconds. Leave `trust` at its default of `false`, so Gemini CLI asks before each tool call. Sources: [Gemini CLI MCP docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) and [its settings reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md).
+
+## Google Antigravity
+
+Antigravity reads `~/.gemini/config/mcp_config.json` for every project and `<workspace>/.agents/mcp_config.json` for one workspace. In the IDE, open Manage MCP Servers, then View raw config, and edit the same file:
+
+```json
+{
+ "mcpServers": {
+ "67js-scene": {
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"]
+ }
+ }
+}
+```
+
+In the Antigravity CLI, type `/mcp` to see the status of each server. Source: [Antigravity MCP docs](https://antigravity.google/docs/mcp).
+
+## Cline
+
+Cline stores its servers in a JSON file. In the IDE extension, open the MCP Servers icon, then the Configure tab, then Configure MCP Servers. The Cline CLI uses `~/.cline/data/settings/cline_mcp_settings.json`.
+
+```json
+{
+ "mcpServers": {
+ "67js-scene": {
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"],
+ "disabled": false,
+ "autoApprove": []
+ }
+ }
+}
+```
+
+An empty `autoApprove` list makes Cline ask before each tool call. The Cline CLI can also add the server: `cline mcp add 67js-scene --yes -- npx -y --package @codepawlhq/67js 67js-mcp --backend gpu --memory 192`. Source: [Cline MCP docs](https://docs.cline.bot/mcp/mcp-overview).
+
+## Zed
+
+Zed calls MCP servers context servers. Open the settings file with the `zed: open settings file` action and add the server under `context_servers`:
+
+```json
+{
+ "context_servers": {
+ "67js-scene": {
+ "command": "npx",
+ "args": ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu", "--memory", "192"],
+ "env": {}
+ }
+ }
+}
+```
+
+You can also use Settings, then AI, then MCP Servers, then Add Server. The Agent Panel then lists the server's tools. Source: [Zed MCP docs](https://zed.dev/docs/ai/mcp).
+
+## Not covered: Windsurf
+
+The Windsurf documentation pages now redirect to Devin Desktop, which names `.devin/mcp_config.json` and `~/.config/devin/mcp_config.json`. The pages do not show the Windsurf editor's own file, so this page has no Windsurf snippet. If you use Devin Desktop, put the same `mcpServers` entry in one of those two files.
+
+## Check that it works
+
+First, ask the harness to list its MCP tools. You must see 22 tools whose names start with `scene_`, `mesh_` or `scene_render_`. Some harnesses add the server name in front, for example `mcp__67js-scene__scene_look` in Claude Code.
+
+Then give the agent this prompt:
+
+```text
+Use 67js to build a small wooden table with a top and four legs. Show me a picture of it.
+```
+
+The agent calls these tools in this order. [Working with agents](#agent-workflows) shows the real result of each call.
+
+1. `scene_capabilities` reads the limits.
+2. `scene_create` makes the scene. This call starts Chrome. It took 1.2 seconds with the `cpu` backend in a local test.
+3. `scene_look` returns a PNG picture and a small JSON record.
+
+If the agent answers with JavaScript instead of tool calls, the server is not connected. Open the harness's MCP status view and read the error there.
+
+## Troubleshooting
+
+- **The server never appears.** Run the launch command in a terminal. If it works there and not in the harness, the harness uses another `PATH` or another Node. Use the node form with absolute paths.
+- **The server times out on first start.** The first `npx` run downloads the package. Install it once with `npm install 67js@npm:@codepawlhq/67js`, or raise the harness start timeout as shown above.
+- **Node is too old.** The package needs Node 20.19 or later. Run `node --version`, and use the Node that the harness starts, not only the one in your terminal.
+- **`scene_create` fails.** The server could not start Chrome or the preview page. Install Google Chrome, or pass `--browser` with the path of a Chromium executable. The server writes the cause to stderr, which the harness shows in its MCP log.
+- **A sandbox blocks the tool.** The server starts a browser and serves its preview page on the loopback interface. A sandbox that blocks either one makes `scene_create` fail. Allow both for this server, or run the harness without that sandbox.
+- **The connection breaks with a parse error.** The server writes only MCP messages to stdout. Its errors go to stderr. A wrapper script that prints to stdout breaks the connection, so do not wrap the launch command in a script that echoes text.
+- **Render job tools are missing.** The job tools need `--jobs` with an absolute path to a private folder.
+- **A tool call asks for approval each time.** This is the harness policy. Approve the read-only tools `scene_look`, `scene_inspect` and `scene_capabilities` once, and review the rest.
+
+## Security limits
+
+The server is built so that an agent cannot do more than build scenes:
+
+- No tool runs JavaScript or any other code from the agent. Every argument is checked against a schema before it runs.
+- No tool takes a remote URL. Remote asset requests are blocked in the preview page.
+- No tool takes a file path for output. Render jobs and GLB exports go to a fixed folder under `--jobs` with names that the server picks.
+- Models load only from the `--assets` folder, and only as self-contained GLB files within fixed size limits.
+- The only text that reaches a shader is a bounded fragment snippet in `postPasses`, which a strict validator checks first.
+- The process runs below normal priority, so it does not slow down your other work.
+
+Give `--jobs` and `--assets` folders that hold nothing private. The [MCP guide](/mcp.md) lists every limit.
diff --git a/docs/learn/models-and-ai-agents.md b/docs/learn/models-and-ai-agents.md
index b1278855..f38ff2ef 100644
--- a/docs/learn/models-and-ai-agents.md
+++ b/docs/learn/models-and-ai-agents.md
@@ -2,36 +2,11 @@
An AI agent can build a 67js scene in two ways. With the MCP server, the agent calls tools that take JSON and return pictures, and it writes no engine code. Without MCP, the agent writes JavaScript like the code in these docs and renders it in a browser.
-## Connect an agent through MCP
+Three pages cover the details:
-The package includes the `67js-mcp` server. It needs Node.js 20.19 or later and an installed Chrome or Chromium. It renders in a local browser and talks to the agent over stdin and stdout.
-
-1. Install the package in your project:
-
-```sh install
-npm install 67js@npm:@codepawlhq/67js
-```
-
-2. Check that the server starts. It prints the installed version:
-
-```sh
-npx 67js-mcp --version
-```
-
-3. Add the server to your MCP client with absolute paths to Node and the installed command:
-
-```json
-{
- "mcpServers": {
- "67js-scene": {
- "command": "/usr/local/bin/node",
- "args": ["/path/to/my-scene/node_modules/67js/bin/67js-mcp.mjs", "--backend", "gpu", "--memory", "192"]
- }
- }
-}
-```
-
-On Windows, the command is like `C:/Program Files/nodejs/node.exe`. `--backend` is `gpu` or `cpu`. `--memory` is the render budget from 32 to 384 MiB, and the default is 192. `--assets` names a folder of GLB files that the agent can place. The [MCP guide](/mcp.md) has every option, the tested clients and the limits.
+- [Connect the MCP server](#connect-mcp): the launch command and the config file for nine harnesses, from Claude Code to Zed.
+- [Working with agents](#agent-workflows): example prompts, the real result of each tool, the render loop, skills and the no-MCP path.
+- [Optimise agent runs](#optimize-for-agents): how to cut tool calls, tokens and waiting, with measured numbers.
## What the agent does
@@ -44,7 +19,7 @@ The server has 22 tools for authoring, previewing and exporting scenes. A normal
5. `scene_checkpoint` and `scene_restore` save and return to a state. `scene_review` shows several views or variants in one picture grid.
6. `scene_export_recipe` and the render job tools save the recipe, PNG images, image sequences and MP4 video.
-The agent can start from an empty recipe and add parts with `add-geometry`, `add-material` and `add-node` commands. The tools check every argument against a schema. The server never runs code that the agent writes.
+The tools check every argument against a schema. The server never runs code that the agent writes.
These guides cover the parts of a recipe:
@@ -55,9 +30,7 @@ These guides cover the parts of a recipe:
- [Visual review](/agent-review.md): several labeled views or poses in one PNG grid.
- [Render jobs](/agent-render-jobs.md): images, sequences, video and render passes.
-## Give the agent these docs
-
-An agent reads plain text best. Give it [the plain-text guide](/guide.md), which holds all of these docs in one Markdown file. The repository also has two skills that hold the scene and media procedures: `skills/build-67js-scene/SKILL.md` and `skills/render-67js-media/SKILL.md`. The npm archive includes them. Copy them into the skill folder of your agent, or point the agent at them.
+## Give the agent a brief
Start with a short brief: the subject, references, the camera, the output size, the interaction, the GPU or CPU backend and the memory budget. Ask for the smallest trial first. A prompt can look like this:
@@ -68,6 +41,8 @@ capture a real wide and mobile preview. List unsupported features. Do not claim
speed superiority without a comparable benchmark.
```
+An agent reads plain text best. Give it [the plain-text guide](/guide.md), which holds all of these docs in one Markdown file, or the shorter map in [`llms.txt`](/llms.txt). [Working with agents](#agent-workflows/skills) shows how to install the two skills that hold the scene and media procedures.
+
## Check the work of an agent
A successful build does not prove a good picture. Ask the agent to do these checks and to report the results:
diff --git a/docs/learn/optimize-for-agents.md b/docs/learn/optimize-for-agents.md
new file mode 100644
index 00000000..bcf5dc13
--- /dev/null
+++ b/docs/learn/optimize-for-agents.md
@@ -0,0 +1,142 @@
+# Optimise agent runs
+
+This page shows how to make an agent finish a 67js task with fewer tool calls, fewer tokens and less waiting. Each number says how it was obtained. Tool sizes were measured on 2026-11-07 with `node scripts/measure-tool-cost.mjs` in a source checkout of 0.15.0. Timings come from one machine under normal load, so read them as ranges.
+
+## Where the tokens go
+
+An agent pays for three things: the tool list, the results of its calls, and the pictures that it reads.
+
+**The tool list.** The harness sends every tool's name, description and input schema to the model. The 22 tools total 189,144 bytes, about 54,000 tokens. Three tools make up most of it:
+
+| Tool | Schema size | Estimated tokens |
+| --- | --- | --- |
+| `scene_create` | 67,995 B | 19,428 |
+| `scene_apply` | 43,581 B | 12,452 |
+| `mesh_edit` | 33,752 B | 9,644 |
+| `scene_create_asset` | 14,087 B | 4,025 |
+| `mesh_stack` | 10,806 B | 3,088 |
+| The other 17 tools | 18,923 B | 5,405 |
+
+Claude Code loads tool schemas on demand through tool search by default, so it pays this cost only for the tools that a task uses. Other harnesses can send the whole list on every turn. If your harness does that, cut the list to the tools that your task needs:
+
+```toml
+[mcp_servers.67js-scene]
+command = "npx"
+args = ["-y", "--package", "@codepawlhq/67js", "67js-mcp", "--backend", "gpu"]
+disabled_tools = ["mesh_edit", "mesh_stack", "mesh_inspect", "scene_create_asset", "scene_asset_catalog"]
+```
+
+This is Codex syntax. Gemini CLI uses `"excludeTools": [...]` in the server entry. Dropping these five tools saves about 17,200 estimated tokens of schema, and the agent can no longer edit meshes or import GLB files. Keep them when the task needs them.
+
+**The results.** Most results are small. These sizes are from the same measurement:
+
+| Result | Size | Estimated tokens |
+| --- | --- | --- |
+| `scene_capabilities` | 24,167 B | 6,905 |
+| `scene_export_recipe` | 2,664 B | 762 |
+| `mesh_edit` | 2,009 B | 574 |
+| `scene_create` | 1,176 B | 336 |
+| `scene_inspect` | 1,123 B | 321 |
+
+`scene_capabilities` is the one large result. The agent needs it once per session. Tell the agent in the first prompt that it must not call it again. A scene with more nodes gives a longer node list in `scene_create` and `scene_apply`. `scene_inspect` takes `ids` and `limit` to read only some nodes.
+
+**The pictures.** A picture is the largest single result. See the next section.
+
+## Choose preview or final quality
+
+Use small pictures to decide and a render job to deliver. Claude counts an image as `ceil(width / 28) × ceil(height / 28)` tokens, according to [Anthropic's vision documentation](https://platform.claude.com/docs/en/build-with-claude/vision), read on 2026-11-07. Other models count differently, and that was not measured. For `scene_look`, the formula gives these estimates:
+
+| Size | Tokens | Use for |
+| --- | --- | --- |
+| 256 by 160 | 60 | Checking that a part exists and where it is. |
+| 512 by 320 | 228 | Most checks. This is the size used in the examples. |
+| 768 by 512 | 532 | The default. Checking proportions and light. |
+| 1024 by 1024 | 1,369 | The largest preview. Checking fine detail. |
+
+Rules that follow from this:
+
+- Ask for a small `width` and `height` in the first prompt, for example "preview at 512 by 320".
+- Ask for a larger picture only when a detail is unclear. Then use `scene_look` with a smaller camera distance, not a bigger image.
+- Use one `scene_review` for several views. It returns one labeled grid of up to four shots, so the agent pays for one picture and one call. Each shot is at most 480 pixels on a side.
+- Do the final render as a job. `scene_render_result` returns a file path and a hash, not the image. The picture enters the context only when the agent opens the file. A 1920 by 1080 final that the agent never opens costs no image tokens.
+- A PNG over 1 MiB returns an error. Ask for a smaller preview.
+
+## Fewer calls for the same work
+
+Every call is a turn. These habits remove turns:
+
+- **Batch edits.** One `scene_apply` takes up to 256 operations. Adding four legs in one call took one call and 49 ms in the local test. A call for each leg takes four.
+- **Skip the inspect after an edit.** `scene_create`, `scene_apply` and `scene_restore` return the revision, an inspection of the nodes and the render status. A `scene_inspect` call right after them repeats that.
+- **Edit, do not rewrite.** A small mesh change as a `mesh_edit` call is 187 bytes. The same change as a new `scene_create` is 1,202 bytes, plus 52 bytes to dispose the old scene. The gap grows with the size of the scene.
+- **Leave out `sessionId`.** One scene exists at a time. Every tool uses the active scene when the field is missing.
+- **Send the right revision.** A stale `expectedRevision` costs a failed call and a retry. Pass the `revision` from the last result.
+- **Compare variants with branches.** `scene_apply` with a `branch` name tries a change without touching the scene. One `scene_review` compares up to four branches. `scene_restore` with the winning `branch` keeps it.
+- **Checkpoint before a risky edit.** `scene_checkpoint` and `scene_restore` return to a good state in two calls. Rebuilding a scene takes many.
+
+## Read results as numbers
+
+A picture costs tokens and an agent can misread it. The text results hold facts that cost far less:
+
+- `scene_inspect` returns the bounds, the node counts and the revision. The agent can check that a part rests on the ground or sits in the middle without a picture.
+- `mesh_inspect` returns lint with a fix for each problem, such as `floating-part` and `thin-wall`.
+- `scene_look` with `labels: true` returns the pixel position of each named part. The agent finds the part to fix.
+- `committed` and `renderSucceeded` in an edit result say whether the edit stuck and drew.
+
+Ask the agent to check these numbers first and to take a picture only when the numbers pass. The [agent modeling suite](https://github.com/codepawl/67.js/tree/main/bench/agent-modeling) grades the same way: it reads bounds, connected parts and holes from the exported recipe and never looks at the picture.
+
+## Keep the state in the server
+
+The scene lives in the server process. The agent does not resend it on each call.
+
+- **Do not resend the recipe.** After `scene_create`, send only operations. A recipe can be up to 1 MiB of JSON.
+- **Save the recipe.** `scene_export_recipe` returns the canonical recipe, 2,664 bytes in the measured case. Ask the agent to save it to a file after each good step. A server restart loses the active scene, and the recipe is how the agent rebuilds it.
+- **Keep the tool list stable.** A harness that caches the start of the prompt can reuse the cache only while the tool list stays the same. Do not switch the server on and off during a session. This is an inference that was not measured.
+- **Dispose before a new scene.** One scene is active at a time. `scene_dispose` frees its memory before `scene_create` starts the next.
+
+## Speed
+
+These timings are from one local run with the `cpu` backend, which uses a software renderer. `--backend gpu` is faster on a machine with a graphics card.
+
+| Step | Time |
+| --- | --- |
+| `scene_create`, the first call, including starting Chrome | 1,241 ms |
+| `scene_look`, 512 by 320 | 208 ms |
+| `scene_look` with labels | 321 ms |
+| `scene_apply`, four legs | 49 ms |
+| Image job, 640 by 400, from submit to completed | 1.1 s |
+
+Chrome starts only on the first scene call, so a harness that connects and never builds a scene pays nothing. The default `--memory 192` fits a 1920 by 1080 frame of an empty scene, which needs about 175 MiB. Raise it to 256 for textured scenes.
+
+## What agents achieve
+
+The repository has a suite that measures how an agent models through these tools. Each task runs in a fresh Claude Code session that has only the 67js tools. The numbers below are from the run of 2026-11-04. It used 5 tasks (crate, bolt, window, table, mug), 2 runs each, and the `cpu` backend.
+
+| Model | Runs passed | Mean tool calls | Mean turns |
+| --- | --- | --- | --- |
+| Haiku | 10 of 10 | 7 | 9 |
+| Sonnet | 9 of 10 | 3.2 | 5.3 |
+
+The stronger model used less than half the calls. The one failure was the crate on Sonnet, 1 of 2. Per task, the mean tool calls were:
+
+| Task | Haiku | Sonnet |
+| --- | --- | --- |
+| crate | 6.5 | 2 |
+| bolt | 11 | 2 |
+| window | 6 | 3.5 |
+| table | 5.5 | 2 |
+| mug | 6 | 6.5 |
+
+The same suite has a no-MCP task. The agent has only [`llms.txt`](/llms.txt) and the installed package, and it must write a script that renders a red sphere to a 512 pixel PNG. On 2026-11-04, both models passed 2 of 2. Haiku used 14 tool calls on average and Sonnet 10.5. This task is different from the five above, so the numbers are not a direct comparison. They show that the no-MCP path works and that it needs about 10 to 14 calls for one picture.
+
+Two features did not show a clear gain in these runs. Branches saved 2 of 17 calls for Haiku and none for Sonnet in a best-of-three task on 2026-11-01. Treat that as noise, because the suite README says a difference of one or two tasks per run is noise. Models other than Claude Haiku and Sonnet were not measured.
+
+## A prompt that applies all of this
+
+```text
+Use 67js through MCP. Call scene_capabilities once and do not call it again.
+Build the scene with one scene_create. Make every later change as one scene_apply batch.
+Preview at 512 by 320 and use scene_review for several views.
+Check bounds and lint with scene_inspect and mesh_inspect before you look at a picture.
+Checkpoint before each risky edit. Save the recipe with scene_export_recipe after each good step.
+For the final file, submit one render job and give me the path.
+```
diff --git a/public/docs-media/agent-scene-look-labels.webp b/public/docs-media/agent-scene-look-labels.webp
new file mode 100644
index 00000000..7d6eebc0
Binary files /dev/null and b/public/docs-media/agent-scene-look-labels.webp differ
diff --git a/public/docs-media/agent-scene-look.webp b/public/docs-media/agent-scene-look.webp
new file mode 100644
index 00000000..7945659c
Binary files /dev/null and b/public/docs-media/agent-scene-look.webp differ