cozyclay 3.0.3 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 ## Unreleased
 
+## 3.1.0 - 2026-10-23
+
+Hands that hold, throw and catch with weight, Studio tasks in the chat, faster playback, and a leaner first run.
+
+Motion
+
+- Hands hold what they carry. Fingers close until they touch the held
+  surface, a ball rests in the palm and fingers, and spheres and cylinders
+  are round to the compiler. QA flags a finger through the object
+  (`FINGER_PEN`), a finger short of it (`FINGER_GAP`) and a hand that does
+  not hold it (`SUPPORT`).
+- A held thing has weight: `objects.<id>.mass` sags the arm, and a load past
+  one hand asks for two (`LOAD`, `observations.load`).
+- New skills `throwObject` and `catchObject`. A thrown thing leaves with the
+  hand's speed and lands on the first surface its path comes down onto; a
+  hand meets a flying ball where it can reach and gives with it.
+- Grasp issues say why and carry the fix that repair applies.
+
+Studio and agent
+
+- Tasks: a **Tasks** switch in the agent composer. With it on, the main
+  agent answers at once while Studio tasks edit the scene in their own
+  scopes, on a pool of two compile workers. Running tasks show as one line
+  in the chat. Off by default.
+- A video can be attached to the agent; it travels as a contact sheet.
+- A fresh install opens the project chooser with one "+ New project" card.
+- The Shot Camera card draws the live shot in every mode, and a focal-length
+  scrub replaces the read-only lens label.
+- The project menu, scene dropdown and Outliner menu no longer open behind
+  the panels and close each other.
+- + Add shot on a full take grows the take; dock tabs are clickable; Pose
+  enters from the editor view and releases IK focus on exit.
+
+Performance
+
+- Timeline playback no longer re-renders the whole app every frame.
+- The motion body fits (~0.5 MB) load after first paint instead of in the
+  first bundle.
+
+Fixes
+
+- `npm test` and `npm run lint` run on a Windows checkout, and the MCP server
+  removes its live endpoint file when it exits on Windows.
+- `npm run dev` exits within about 1.5 s on Ctrl+C instead of hanging.
+- mcp: `proxy-addr` 2.0.8 (CVE-2026-90711).
+
+Removed
+
+- The built-in set pieces: Chair, Car and Plane (aircraft), with their Set
+  pieces group, Content › Sets folder and renderers. An old project that has
+  one opens it as a plain cube with the same transform and size.
+- The City Block starter scene and its thumbnails. The chooser's "+ New
+  project" card is now the one blank entry; the Blank Stage card, the Samples
+  page and the category tabs are gone. `--scene <id>` and `?scene=` stay; an
+  unknown id is ignored with a console warning.
+- The camera tutorial: the Studio overlay, Help › Tutorial, the Settings and
+  Learn entries, `?tutorial=camera`, the first-shot handoff, the `tutorial:*`
+  analytics events, and the seven-step tutorial and project download on the
+  home-page playground (which now opens a blank stage).
+
+Docs
+
+- The README is short again: install, what it does, the three AI surfaces, docs.
+- `INSTALL_FOR_AGENTS.md` is the install, run and connect guide for an AI agent given the
+  repository link. It ships in the npm package.
+- The README links the CozyClay Discord server and GitHub Sponsors.
+
 ## 3.0.3 - 2026-10-20
 
 Grasp round 2, from a user's own cup, ball and steering-wheel sessions on 3.0.2.

package/INSTALL_FOR_AGENTS.md

@@ -0,0 +1,146 @@
+# CozyClay: install and run guide for AI agents
+
+You are an AI agent. A user gave you this repository and asked you to install CozyClay, run it, or
+connect to it. Follow this file. The [README](README.md) is the short version for people.
+
+CozyClay is a previs studio that runs in a browser tab. The user blocks a scene, poses
+characters and cuts cameras. The studio then exports the shot for an AI video model. You install it
+with npm. You do not need a GPU, Python, a model download or a build step.
+
+## 1. Check the requirements
+
+| Need | Check | If it fails |
+| --- | --- | --- |
+| Node.js 22.19 or newer | `node --version` | Install Node 22 LTS or newer. Do not continue on an older Node. |
+| npm (or bun) | `npm --version` | It comes with Node. |
+| A Chromium-based browser (Chrome, Edge, Brave, Arc) | Ask the user | Safari and Firefox are not supported. |
+
+## 2. Install and start (normal case)
+
+Do not clone the repository unless the user wants to change the source code. The npm package
+contains the built studio.
+
+```sh
+npx -y cozyclay --no-star
+```
+
+- This is a long-running server. Start it in the background and keep it running.
+- It is ready when it prints `CozyClay is running at http://127.0.0.1:5180/app/`.
+- It opens the default browser. Add `--no-open` when there is no screen, and give the user the URL.
+- `--port 5200` serves on another port. Use it when the output is `port 5180 is taken`.
+- `--no-star` stops the "star the repo" question when the process exits. An agent cannot answer it.
+
+For a permanent install, run `npm install -g cozyclay`. Then `cclay` and `cozyclay` are the same
+command. `cclay update` installs the latest release.
+
+Tell the user:
+
+- The URL to open, in a Chromium browser.
+- **Assets › Characters** adds a character, and the timeline at the bottom holds the shots.
+- `Cmd/Ctrl+B` opens the Agent panel. In that panel the user signs in with a ChatGPT account, or
+  chooses a model from another provider (section 5).
+
+## 3. Control the studio yourself
+
+Pick one surface. Do not use two that start a live hub on the same port (see "One hub per port").
+
+### a. Terminal agent (coding agent with a shell): `cclay live`
+
+Use this when you have a shell and the studio from step 2 is running. You need a browser tab open
+on the studio URL, because the tab is the editor.
+
+```sh
+npx -y cozyclay live status --wait          # wait for an editor tab; required first step
+npx -y cozyclay live inspect --scope scene  # read before you edit
+npx -y cozyclay live capture --out shot.png # check the result as an image
+```
+
+The loop: wait for the editor. Read the scene. Apply one change (`arrange-objects`,
+`arrange-characters`, `frame-shot`, `patch`, or `run <command>`). Verify it (`verify`, `capture`).
+Each edit returns a receipt, and `undo --receipt <id>` takes it back. The output is one JSON
+object per command. Exit codes: 0 ok, 1 editor or receipt error, 2 usage, 3 no hub, 4 workspace,
+5 timeout or uncertain apply, 6 stale scene or busy target.
+
+- Look at the result with `capture` PNGs. Do not screenshot the browser window.
+- `UNCERTAIN_APPLY`: inspect the scene before you try again. Do not repeat the edit blindly.
+- `npx -y cozyclay live --help` lists every verb.
+- Full guide with worked sessions: [`docs/agent-cli.md`](docs/agent-cli.md).
+
+### b. MCP client (Claude Desktop, Claude Code, Cursor, any MCP client)
+
+Add this server to the client's MCP config, then restart the client:
+
+```json
+{
+  "mcpServers": {
+    "cozyclay": { "command": "npx", "args": ["-y", "cozyclay", "mcp"] }
+  }
+}
+```
+
+For Claude Code: `claude mcp add cozyclay -- npx -y cozyclay mcp`.
+
+- The first start installs the MCP SDK (about 95 packages). This takes some time once.
+- Without an editor tab, the scene, camera, prompt and project-file tools work in memory.
+- With an editor tab connected, the tools move the visible viewport. `live_status` tells you if
+  a tab is connected. `capture_frame`, `apply_batch` and `import_mesh` need a connected tab.
+- Tool list and protocol: [`mcp/README.md`](mcp/README.md).
+
+### One hub per port
+
+The studio (`cozyclay`) and the MCP server (`cozyclay mcp`) each try to host the live hub on
+port 5184. The second one to start loses the port and does not report an error:
+
+- MCP server second: it works in memory only and does not move the editor.
+- Studio second: its Agent panel has no hub.
+
+To run both, give them different ports, with `COZYCLAY_LIVE_PORT` set in each one's environment.
+To drive a running studio from a shell, use `cclay live` (it connects to the hub and does not host
+one).
+
+## 4. Make motion
+
+Motion is compiled in the browser, not generated. You write a motion spec (key poses, hand
+anchors, props, walks), compile it with `motion.compile`, and read the QA report (collisions, foot
+slide, reach, contacts). Spec format and loop: [`docs/motion3-agent-guide.md`](docs/motion3-agent-guide.md).
+Motion works on rigged characters in Animation projects. Capsule figures and Storyboard projects
+refuse it with `TARGET_NOT_READY` or `NOT_IN_MODE`.
+
+## 5. Agent panel models (optional)
+
+The Agent panel inside the studio can use ChatGPT (sign in in the panel), Anthropic, OpenAI,
+Google Gemini, OpenRouter or CLIProxyAPI. Set the key in the environment of the process that starts
+the studio (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`,
+`CLIPROXY_API_KEY`), or let the user paste it in the panel. Keys go to
+`~/.config/cozyclay/providers.json` (mode 0600). Never print a key or put it in a command line
+that is logged. Details: [`docs/agent-cli.md`](docs/agent-cli.md#models-and-providers).
+
+## 6. From source (only to change the code)
+
+```sh
+git clone https://github.com/NomaDamas/CozyClay.git
+cd CozyClay
+npm install
+npm run dev        # studio, agent sidecar and live hub on http://127.0.0.1:5180/app/
+npm test           # build, then every verification file
+```
+
+Contribution rules (branches, PR checks, the lint ratchet) are in [`AGENTS.md`](AGENTS.md).
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `port 5180 is taken` | Another studio runs. Open its URL, or start with `--port 5200`. |
+| `live status` shows `"editors":[]` | No tab is open on the studio URL, or the tab uses a different live port. Open or reload the tab. |
+| `NO_EDITOR` on an edit | Same as above. Run `live status --wait` first. |
+| Blank page or WebGL error | The browser is not Chromium, or hardware acceleration is off. |
+| The studio tab stops responding | Reload the tab (`Cmd+R` on macOS, `Ctrl+R` elsewhere). Your project autosaves in the browser. |
+| MCP tools do not move the editor | See "One hub per port". |
+
+## Privacy
+
+The official npm package sends anonymous usage counts and prints the disclosure on first
+launch. It never sends project content. Turn it off with `cclay telemetry off`, or with
+`COZYCLAY_TELEMETRY=0` or `DO_NOT_TRACK=1`. Source checkouts send nothing. Details:
+[`docs/privacy.md`](docs/privacy.md).

package/README.md

@@ -3,11 +3,8 @@
 </p>
 
 <p align="center">
-  <em>Block a scene, pose the cast, cut the camera — in a browser tab.</em>
-</p>
-
-<p align="center">
-  Created and maintained by <a href="https://github.com/HaD0Yun">Doyun</a> at <a href="https://github.com/NomaDamas">NomaDamas</a>.
+  <b>Make the scene first. Then make it a video.</b><br>
+  <em>Open source previs in a browser tab: block the set, move the cast, cut the camera, hand the shot to an AI video model.</em>
 </p>
 
 <p align="center">
@@ -15,229 +12,114 @@
   <a href="https://www.npmjs.com/package/cozyclay"><img alt="npm" src="https://img.shields.io/npm/v/cozyclay"></a>
   <img alt="Node 22.19+" src="https://img.shields.io/badge/node-22.19%2B-brightgreen">
   <a href="https://github.com/NomaDamas/CozyClay/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/NomaDamas/CozyClay?style=flat"></a>
+  <a href="https://discord.gg/Hp9V5wwgjF"><img alt="Discord" src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white"></a>
 </p>
 
 <p align="center">
   <a href="https://cozyclay.org/#try">Try it in the browser</a> ·
   <a href="#quick-start">Quick start</a> ·
-  <a href="#what-you-can-do">Features</a> ·
-  <a href="#ai-control">AI control</a> ·
-  <a href="#workflow-canvas">Workflow</a> ·
-  <a href="#controls">Controls</a> ·
-  <a href="#documentation">Docs</a> ·
-  <a href="https://github.com/NomaDamas/CozyClay/issues">Issues</a>
+  <a href="INSTALL_FOR_AGENTS.md">Guide for AI agents</a> ·
+  <a href="#docs">Docs</a> ·
+  <a href="CHANGELOG.md">Changelog</a> ·
+  <a href="https://discord.gg/Hp9V5wwgjF">Discord</a>
 </p>
 
----
-
-CozyClay is a browser-based previs studio built with Three.js and React Three Fiber. Block a scene, pose the cast, cut the camera on a timeline, then hand the same shot to an AI video model (Seedance, Kling, Veo, or your own) as a first frame, a reference clip, or a prompt — all from one local workspace. The keyframe pack's greybox clip is the input Seedance 2.5 documents as white-model control: "Use the white-model reference video as the sole guide for camera movement, pacing, framing, subject motion, and blocking" (seed.bytedance.com/en/seedance2_5). MiniMax H3, Wan 3.0, LTX Desktop and fal render-to-real take the same plain RGB clip.
-
-```bash
-npx cozyclay
+<table>
+  <tr>
+    <td width="50%"><video src="https://github.com/user-attachments/assets/00f28c2f-e8e2-43eb-b253-b6c2436e1818" controls muted width="100%"></video></td>
+    <td width="50%"><video src="https://github.com/user-attachments/assets/4c9b1e29-4803-435c-8305-f2c899fb1c2c" controls muted width="100%"></video></td>
+  </tr>
+  <tr>
+    <td align="center"><sub>Top: the greybox blocked in CozyClay. Bottom: the AI video made from it.</sub></td>
+    <td align="center"><sub>Same idea, a parkour jump: the blocking holds the timing and the camera.</sub></td>
+  </tr>
+</table>
+
+## Why
+
+AI video costs money per take, and one miss means paying again. A text prompt cannot hold a
+whole scene: where everyone stands, how they move, where the camera is, when it cuts.
+
+CozyClay lets you make those decisions first, in 3D, where they are cheap to change. Then the video
+model gets the shot as a first frame, a greybox reference clip and a prompt that describes the
+real framing. It follows the blocking instead of guessing.
+
+```mermaid
+flowchart LR
+  S["Stage<br/>set + cast"] --> M["Motion<br/>compiled + QA"] --> C["Camera<br/>shots + cuts"] --> E["Export<br/>frame · clip · prompt"] --> V["AI video model"]
 ```
 
-That is the whole install. Not sure yet? **[Try it in the browser first](https://cozyclay.org/#try)** — a seven-step camera tutorial on a live scene — then keep going on your machine with the same set:
+## Quick start
 
 ```bash
-npx cozyclay --scene city-block
+npx cozyclay
 ```
 
-The camera tutorial seeds a compiled walk, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away. New motion is compiled in the browser from a motion spec — no GPU box or sidecar needed.
-
-## Demo
+That is the whole install. You need Node.js 22.19 or newer and a Chromium browser. You do not need
+a GPU, Python or a model download. The studio opens at `http://127.0.0.1:5180/app/`.
 
-https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
+> **Asking an AI agent to set it up?** Give it this repository link. Its instructions are in
+> [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md).
 
 ## What you can do
 
-|  | |
+| | |
 | --- | --- |
-| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with the transform strip's gizmo. Cast people from **Assets › Characters**: a rigged character you can pose and animate, or a **Capsule figure** — a rigless stand-in with one posture (stand, sit or lie) chosen in Details, for blocking where nobody needs to move their limbs. Capsule figures follow root paths and per-panel placements like any character but refuse pose, IK and motion tools, with the reason in the tooltip. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye Top-View drives 2D root waypoints for character paths. **View ▾** on the viewport bar holds the reference grid and Auto Color — Blender's random viewport color, so twenty grey blockout boxes stay tellable apart without touching the colors you authored (captures include the display colors while it is on). |
-| **Fly the camera** | Right-drag flies (WASD walks, Q/E cranes), middle-drag pans, Alt+drag orbits the selection, click selects, `F` frames — the muscle memory you already have from a 3D editor. Fly, pan and orbit lock the pointer for the hold, so the view can turn past the window edge. Selecting the camera switches to Camera mode. **Look through** in the Shot monitor puts you behind the shot camera with the same bindings; click the on-screen **Shot camera** indicator or press `Esc` to return to the free camera. |
-| **Cut and move the camera** | Add shots on the timeline, draw a dolly rail on the Top-View, set speed, height and crane, and preview the move through the shot camera. Each shot carries a **Target model** (Seedance 2.5, Kling 2, Veo 3, self-hosted MiniMax-H3) and is flagged when the cut runs past that model's limits. |
-| **Export for AI video** | One **Export ▾** menu: a keyframe pack (first/last frame, clip, camera JSON, prompt, README) as a zip, an mp4 of the shot, depth + normal conditioning passes, a storyboard contact sheet, and an OTIO cut list. Seedance 2.5 reads the pack's greybox clip as its white-model reference video, and MiniMax H3, Wan 3.0, LTX Desktop and fal render-to-real accept the same clip. The **Shot Prompt** turns the framing into a structured prompt for the model you picked. |
-| **Undo anything** | Every scene mutation goes through one history store: a drag, a scrub, an inspector edit, an agent's camera key is exactly one undo entry. `Esc` cancels an in-flight drag and restores the pre-drag transform. |
-| **Compile motion** | The agent writes a motion spec — key poses, hand anchors, props, walks, hinged doors — and a deterministic compiler bakes every frame on the X Bot or Y Bot rig, then QA measures collisions, foot slide, reach and the contacts the spec declares ([`docs/motion3-agent-guide.md`](docs/motion3-agent-guide.md)). A compiled take is saved as its spec and replays identically; sparse IK keys and range pins correct any frame on top. |
-| **Direct it with an AI** | Open the **Agent panel** (`Cmd/Ctrl+B`), sign in with your ChatGPT account, and ask for a shot in plain language; the conversation survives reloads and you can paste a reference screenshot into it. Or connect Claude — or any MCP client — or drive the Studio from a terminal with `cclay live`. All three place the cast, frame "a low wide profile", compile motion, and the viewport moves in front of you. See [AI control](#ai-control). |
+| **Stage** | Build the set from primitives. Add rigged characters, or capsule stand-ins when nobody needs to move a limb. Fly the view like a 3D editor. |
+| **Move** | Describe the action. The agent writes a motion spec, and a deterministic compiler in the browser bakes every frame. QA checks collisions, foot slide, reach and hand contact before you see it. |
+| **Shoot** | Put shots on a timeline, draw dolly rails, look through the lens. Each shot knows the limits of the video model you target. |
+| **Export** | Keyframe pack (first and last frame, greybox clip, camera, prompt), mp4, depth and normal passes, contact sheet, OTIO cut list. |
+| **Storyboard** | Prefer stills? A Storyboard project is a row of panels with captions, an animatic and a contact sheet. |
+| **Undo anything** | Every edit, including each change the agent makes, is one undo step. |
 
-## Modes
+## Direct it with AI
 
-A project is either a **Storyboard** or an **Animation**. Pick it on the start screen (the badge in the top bar shows which one you are in); a project keeps its mode when saved and reopened.
+The same scene can be driven from three places, live, while you watch the viewport.
 
-| | Storyboard | Animation |
+| Surface | Start | For |
 | --- | --- | --- |
-| **Choose it when** | You want a row of still panels: framing, who stands where, a caption and a hold per panel | You want moving shots: motion on a timeline, camera moves, takes |
-| **Timeline** | The **Board** dock tab: one card per panel with a greybox thumbnail, caption, hold, duplicate, delete and drag-to-reorder | Shots on the timeline, with the compiled take |
-| **Cast** | Rigged characters or capsule figures; each panel can keep its own placement ("Use stage placement" clears it) | Rigged characters with Pose and Motion mode; capsule figures for blocking |
-| **Motion tools** | Hidden: no Motion mode (`4`) | Available |
-| **Agent** | **Agent · Storyboard** builds one panel per request and never generates motion | The full Studio tool set |
-| **Exports** | **Stylize** a panel through the image route, **Send to Workflow** (the stylized image or the greybox) from its card, plus the Export ▾ menu: **Contact sheet (PNG)**, **Panel pack (zip)**, **All panels (zip)**, **Animatic (mp4)**, **Cut list (OTIO)** and **Depth + normal (PNG)**; File ▸ **Export as Animation project…** turns the panels into an Animation. There is no keyframe pack or shot video in a storyboard | Export ▾: keyframe pack, mp4, depth + normal passes, contact sheet, OTIO cut list |
+| **Agent panel** | `Cmd/Ctrl+B` in the studio | Chat in the studio. Sign in with ChatGPT or use your own key (Anthropic, OpenAI, Gemini, OpenRouter, CLIProxyAPI). |
+| **MCP server** | `npx -y cozyclay mcp` | Claude Desktop, Claude Code, Cursor or any MCP client. |
+| **Terminal** | `cclay live status --wait` | Coding agents that drive a running studio, JSON in and out. |
 
-Start in Storyboard when you are deciding what the shots are, then open the idea as an Animation when it needs motion.
-
-## Quick start
-
-You need Node.js 22.19 or newer, npm or bun, and a Chromium-based browser.
-
-```bash
-npx cozyclay
-# or
-bunx cozyclay
+```json
+{ "mcpServers": { "cozyclay": { "command": "npx", "args": ["-y", "cozyclay", "mcp"] } } }
 ```
 
-That downloads the built studio and opens it at `http://127.0.0.1:5180/app/`. Nothing to compile, no dependency tree to install. Useful flags: `--port 5200`, `--no-open`, `--no-motion`, `--scene city-block` (start on the bundled starter scene instead of an empty room; the first-run dialog offers the same under **Start from a scene**, and a `.cclayproject` downloaded from the browser tutorial opens with **Open a project**).
-
-A global install gives you `cclay`, the same command with less typing. Once a day the launcher checks npm for a newer release and prints a one-line notice after the studio is up; it stays quiet when you're current or offline. `cclay update` installs the latest release, and `--no-update-check` skips the check entirely.
-
-New to the camera? The seven-step tutorial runs inside the Studio on the City Block set: **Settings ▾ → Camera tutorial**, or open `http://127.0.0.1:5180/app/?tutorial=camera`. Each step points at the control it needs and completes only when you actually make the move.
-
-### From source
+## From source
 
 ```bash
-git clone https://github.com/NomaDamas/CozyClay.git
-cd CozyClay
+git clone https://github.com/NomaDamas/CozyClay.git && cd CozyClay
 npm install
-npm run dev
-```
-
-Open `http://127.0.0.1:5180/app/` for the Studio (the root redirects there) and `http://127.0.0.1:5180/workflow/` for the Workflow canvas. `npm run dev` starts the studio together with its local OAuth and agent sidecar; `npm run dev:ui` starts the browser UI alone.
-
-## AI control
-
-Three surfaces drive the same scene, live, through one hub: a chat panel in the Studio, an MCP server for external assistants, and a terminal CLI.
-
-### Agent panel in the Studio
-
-**View ▾ → Panels → Agent panel** (or `Cmd/Ctrl+B`) opens a chat column that signs in with your ChatGPT account (Codex OAuth; the token lives in `~/.config/cozyclay/`) and works the scene in front of you:
-
-> "Put a detective and a courier in an alley, give me a low wide profile shot,
-> then make her stand up from the chair, sprint, and trip."
-
-- Every change comes back as a receipt that highlights the Inspector and hierarchy rows it touched, and `Cmd/Ctrl+Z` takes it back like any other edit.
-- The conversation is stored under `~/.config/cozyclay/agent-sessions/` and resumes across reloads and restarts; **History** lists earlier sessions.
-- Paste or drop up to four images into the composer — a reference frame, a storyboard panel — and they go with the turn.
-- The agent has nine Studio tool families, from `inspect_studio` and `arrange_characters` to `patch_elements`, which sets any declared authored field (a character's tint, a shot's target model, the key light) by path. How it turns a pasted video prompt into blocking — what it asks, infers, or leaves empty — is the rule in [`docs/agent-prompt-to-scene.md`](docs/agent-prompt-to-scene.md).
-
-The panel is not tied to ChatGPT. Models come from six providers: ChatGPT (your Codex sign-in), Anthropic, OpenAI, Google Gemini, OpenRouter and CLIProxyAPI. A model id reads `provider/model`, so you pick one in the dropdown and that is where the turn goes. The five API-key providers take a key from an environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` or `GOOGLE_API_KEY`, `OPENROUTER_API_KEY`, `CLIPROXY_API_KEY`) or from `~/.config/cozyclay/providers.json`, written at mode 0600 and never echoed back by any route; ChatGPT still signs in the way it always did. On the Workflow canvas you can steer a turn while it runs instead of stopping it. Conversations are saved in a new transcript format, so sessions recorded before this version are ignored rather than converted: the old files stay on disk, unread. The provider table, the key routes, the steer route and the session format are in [`docs/agent-cli.md`](docs/agent-cli.md).
-
-The agent runs on [pi](https://github.com/earendil-works/pi), an open-source agent harness: `@earendil-works/pi-ai` and `@earendil-works/pi-agent-core` (MIT) are the only runtime dependencies the package declares, and the sidecar loads them lazily, when a turn starts.
-
-The same panel sits on the right of the Workflow canvas, where it builds and runs canvas nodes.
-
-### MCP server
-
-The studio ships an [MCP](https://modelcontextprotocol.io) server, so any MCP client can drive it — the same scene, the same viewport:
-
-```json
-{
-  "mcpServers": {
-    "cozyclay": {
-      "command": "npx",
-      "args": ["-y", "cozyclay", "mcp"]
-    }
-  }
-}
+npm run dev     # http://127.0.0.1:5180/app/
+npm test
 ```
 
-Drop that into `claude_desktop_config.json` (or any MCP client config) and restart the client. The first run automatically installs the MCP SDK's 95-package tree; opening the studio never waits on it, so those dependencies are fetched only when you actually want the server.
-
-- **Editor open?** Tool calls move the visible viewport — camera, cast, set, compiled motion on the timeline.
-- **No editor?** Scene and project tools run headless: block scenes, derive film vocabulary ("wide shot · right profile · knee level · 24mm"), render AI video prompts, and write `.cclayproject` files. `capture_frame` and `apply_batch` require the live editor.
-
-Tools, transports and the live-control protocol are documented in [`mcp/README.md`](mcp/README.md).
-
-### From a terminal
-
-`cclay live` is a small CLI that reads the scene, places and moves things, frames and keys shots, patches declared fields (`cclay live patch --target stage --set '{"keyLight.intensity":2.4}'`), verifies the result with a capture PNG, and undoes by receipt — one JSON object per command, stable error codes, no browser of your own required (only the studio tab itself). It is the intended surface for a coding agent that has to manage a running Studio. The full guide, with three worked sessions against a real editor, is in [`docs/agent-cli.md`](docs/agent-cli.md).
-
-## Workflow canvas
-
-The Workflow canvas at `http://127.0.0.1:5180/workflow/` is a node editor around the Studio: a **CozyClay Scene** node with a live viewport that previews the shot camera, a **Shot Prompt** node that builds a structured prompt from the capture, **Image** nodes (versions, A/B, pinned references) and a **Video** node that runs through your own ComfyUI (`COZYCLAY_COMFY_URL`) or fal (`FAL_KEY`) — bring your own key, nothing is proxied. Graphs are saved in the browser and execute locally.
-
-## Controls
-
-| Input | Action |
-| --- | --- |
-| Right-drag | Look around (fly) |
-| RMB + WASD | Walk while flying |
-| RMB + Q/E | Crane down / up |
-| RMB + Shift | Boost fly speed 2.6× |
-| Middle-drag | Pan |
-| Alt + drag | Orbit the selection |
-| Scroll | Dolly; while flying, sets the fly speed instead |
-| Click | Select; empty space clears |
-| Transform strip | Move / rotate / scale tool, snap |
-| Ctrl/Cmd (during drag) | Invert grid snapping |
-| Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z | Undo / redo |
-| Esc | Cancel the in-flight drag |
-| End | Drop the selection to the surface |
-| Ctrl/Cmd+D | Duplicate the selection |
-| Delete / Backspace | Delete the selection |
-| F | Frame the selection |
-| Look through / Esc | Fly / leave the shot camera |
-| Cmd/Ctrl+B | Show / hide the Agent panel |
-
-Every control's home is recorded in [`docs/studio-ui-ia.md`](docs/studio-ui-ia.md), with the rule behind each placement.
-
-## Documentation
+## Docs
 
 | Read | For |
 | --- | --- |
-| [`docs/motion3-agent-guide.md`](docs/motion3-agent-guide.md) | How the agent writes a motion spec, compiles it and reads QA |
-| [`docs/agent-cli.md`](docs/agent-cli.md) | Driving the Studio from a terminal with `cclay live` |
-| [`docs/agent-prompt-to-scene.md`](docs/agent-prompt-to-scene.md) | The ask / infer / omit rule the Agent follows when turning a video prompt into blocking, and the one-panel-per-request rule in storyboards |
-| [`mcp/README.md`](mcp/README.md) | MCP tools, transports, and the live-control protocol |
-| [`docs/studio-ui-ia.md`](docs/studio-ui-ia.md) | Where every Studio control lives and why |
-| [`docs/privacy.md`](docs/privacy.md) | The full analytics disclosure: events, identifiers, opt-out, internal QA marking |
-| [`workers/api/README.md`](workers/api/README.md) | The cozyclay.org API Worker: sign-in and the hosted video-model route |
-| [`docs/releasing.md`](docs/releasing.md) | Publishing a signed npm release |
-| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
+| [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md) | Install, run and connect, written for AI agents |
+| [`docs/motion3-agent-guide.md`](docs/motion3-agent-guide.md) | Motion specs, compile and QA |
+| [`docs/agent-cli.md`](docs/agent-cli.md) | `cclay live`, model providers, sessions |
+| [`mcp/README.md`](mcp/README.md) | MCP tools and the live protocol |
+| [`docs/studio-ui-ia.md`](docs/studio-ui-ia.md) | Every control and where it lives |
+| [`docs/privacy.md`](docs/privacy.md) | Anonymous telemetry and how to turn it off (`cclay telemetry off`) |
+| [`AGENTS.md`](AGENTS.md) | Contribution rules |
 
-Longer reads on the site: [Greybox to AI video](https://cozyclay.org/greybox-to-video/), [Seedance 2.5 camera control](https://cozyclay.org/seedance-camera-control/), [Camera control for AI video](https://cozyclay.org/ai-camera-control/), [Previs software compared](https://cozyclay.org/previs-software/).
+## Guides
 
-## Validate
-
-| Command | Covers |
+| Read | For |
 | --- | --- |
-| `npm run test:history` | Undo/redo store and transaction coordinator |
-| `npm run test:scene-objects` | Scene-object model |
-| `npm run test:hierarchy` | Hierarchy panel model |
-| `npm run test:objects` | Gizmo interaction in a real browser — needs `npm run dev:ui` in another shell |
-| `npm run test:theme` / `test:appearance` / `test:layout` | UI theme, appearance, layout |
-| `npm run test:lifecycle` | Dev-server process lifecycle |
-| `npm run test:ardy` | IK pipeline, range pins and timeline helpers |
-| `node tools/run-tests.mjs` | Every Node verification file (what CI runs) |
-| `npm run qa:browser -- node test/qa-camera-tutorial-browser.mjs` | The seven-step tutorial driven with real input, beacons pinned to their controls |
-| `QA_URL=… CDP_PORT=… OUT=/tmp/count npm run qa:browser -- node tools/qa/studio-control-count.mjs` | Simultaneously visible controls per mode (budget: Scene ≤35 / Camera ≤38 / Motion ≤52) |
-| `cd mcp && npm install && npm run verify` | MCP server over real stdio — all 420 framing combinations |
-| `cd mcp && npm run verify:live` | Live-control protocol against a fake editor (same `npm install` first) |
-| `npm run build` | Production build |
-
-Ad-hoc browser QA, while a dev server is available (the browser opens the studio at `/app/`):
-
-```bash
-npm run qa:browser -- node <qa-script>
-```
-
-## Contributing
-
-Found something broken, or want a feature? [Open an issue](https://github.com/NomaDamas/CozyClay/issues) — bug reports with a repro are the most useful thing you can send. Contributions are accepted under `AGPL-3.0-or-later`.
-
-**Repository hygiene.** Generated motion archives, QA output, build output, logs and local runtime artifacts are not source files and must not be committed. Keep `artifacts/`, `dist/`, `.gjc/` and `.npz` files local.
-
-Every runtime library except the two agent packages (`@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`) intentionally lives in `devDependencies`, because the published npm package ships the prebuilt `dist/`, so `npx cozyclay` must not install the studio's dependency tree.
-
-## Analytics & privacy
-
-Anonymous usage counts, no cookies, no recordings, never your project content — on the hosted site via PostHog and in the official npm package, which prints the disclosure once on first launch. Source checkouts, forks, dev servers, CI and tests send nothing.
-
-```bash
-cclay telemetry status
-cclay telemetry off
-```
+| [Greybox to AI video](https://cozyclay.org/greybox-to-video/) | Why a grey blockout is the most reliable input for a video model, and the block-then-generate loop |
+| [Previs software compared](https://cozyclay.org/previs-software/) | Free, open source and browser-based previs tools side by side |
+| [Seedance 2.5 camera control](https://cozyclay.org/seedance-camera-control/) | Getting the same camera on every take with a reference clip |
+| [Camera control for AI video](https://cozyclay.org/ai-camera-control/) | Why camera prompts drift and what the models actually accept |
 
-`COZYCLAY_TELEMETRY=0` or `DO_NOT_TRACK=1` disables collection for a launch; **Settings ▾ → Privacy** is the same switch inside the Studio. The event list, what each identifier is, how internal QA traffic is marked and the first-edit definition are in [`docs/privacy.md`](docs/privacy.md).
+Found a bug or want a feature? [Open an issue](https://github.com/NomaDamas/CozyClay/issues).
 
-## License & credits
+## License
 
-GNU Affero General Public License v3.0 or later — see [`LICENSE`](LICENSE) and the transition details in [`LICENSING.md`](LICENSING.md). Modified network services must offer their users the corresponding source. Third-party projects retain their own licenses and copyright; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+AGPL-3.0-or-later. See [`LICENSE`](LICENSE), [`LICENSING.md`](LICENSING.md) and
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md). Made by [Doyun](https://github.com/HaD0Yun) at
+[NomaDamas](https://github.com/NomaDamas).

package/THIRD_PARTY_NOTICES.md

@@ -34,27 +34,6 @@ ARDY is not bundled with CozyClay. Users must obtain, install, and operate ARDY
 
 ARDY model checkpoints and other model assets may be governed by separate terms, including the NVIDIA Open Model License identified by the ARDY project. Users are responsible for reviewing and complying with those terms before downloading or using the models.
 
-## NVIDIA Kimodo
-
-CozyClay provides an optional bridge and data-conversion workflow for externally installed [Kimodo](https://github.com/nv-tlabs/kimodo), a human-motion generation project from NVIDIA Research, and [kimodo.cpp](https://github.com/localai-org/kimodo.cpp).
-
-Kimodo runtimes and model weights are not bundled with CozyClay. Users must obtain, install, and operate them separately under NVIDIA's terms and the applicable runtime licenses.
-
-- Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES (Kimodo skeleton data)
-- Kimodo source license: Apache License 2.0
-- Source: https://github.com/nv-tlabs/kimodo
-- Source license: https://github.com/nv-tlabs/kimodo/blob/main/LICENSE
-- kimodo.cpp source license: Apache License 2.0
-- Source: https://github.com/localai-org/kimodo.cpp
-- Source license: https://github.com/localai-org/kimodo.cpp/blob/main/LICENSE
-
-`tools/kimodo/local-output.mjs` embeds skeleton constants extracted from the `nv-tlabs/kimodo` SOMA77 definitions and `kimodo/assets/skeletons/somaskel77/` assets at commit `1aece8c124d73d255ceff5086d983b844c9f4e94`: the joint hierarchy, neutral-pose offsets, and relaxed-hand rotation matrices. The source assets are pinned by SHA256:
-
-- `joints.p`: `dc5fd8e39e0ff312f5d0f536a87ac22ac58445e13443fcb8ab54e6817cb97ce7`
-- `relaxed_hands_rest_pose.npy`: `64a3828e0d1ef1f1de8228c74eba8040c0810d898169f1892d8997a213b2b64c`
-
-Kimodo model checkpoints and other model assets may be governed by separate terms, including the NVIDIA Open Model License identified by the Kimodo project. Users are responsible for reviewing and complying with those terms before downloading or using the models.
-
 ## Meta Llama 3
 
 ARDY's text encoder is based on Meta Llama 3 (`Meta-Llama-3-8B-Instruct`).