cozyclay 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -1,9 +1,79 @@
 # Changelog
 
+## 1.9.0
+
+The Agent panel moves onto the open-source pi harness with six model
+providers, the Studio gains a gated Fal H3 motion workflow with a
+mocap-readable mannequin, and the codebase sheds its dead exports and
+committed research artifacts. **Node 22.19 is the new floor**, and Agent
+sessions saved by earlier versions are skipped, not migrated.
+
+Agent
+
+- The Agent panel runs on the open-source pi agent harness
+  (`@earendil-works/pi-ai` and `@earendil-works/pi-agent-core`, MIT), which
+  the sidecar loads only when a turn starts.
+- Six model providers instead of one: ChatGPT (the same Codex sign-in),
+  Anthropic, OpenAI, Google Gemini, OpenRouter and a self-hosted CLIProxyAPI.
+  Model ids read `provider/model`, and a bare id still resolves to the ChatGPT
+  provider. API keys come from `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+  `GEMINI_API_KEY` or `GOOGLE_API_KEY`, `OPENROUTER_API_KEY` and
+  `CLIPROXY_API_KEY`, or from `~/.config/cozyclay/providers.json` (mode 0600),
+  managed through `GET/PUT/DELETE /agent/providers`, which never return key
+  material. Saved keys are validated before they are advertised as usable.
+- A running Workflow turn can be steered: `POST /agent/turn/<turnId>/steer`
+  hands the text to the model at the next step of the same turn instead of
+  stopping it. Studio turns keep their frozen envelopes and refuse with
+  `STEER_UNSUPPORTED`.
+- Conversations are stored in a new v2 transcript format that keeps each
+  provider's own message fields. Sessions saved before this version are
+  ignored, not migrated: the files stay on disk and are skipped by History.
+- Images can be pasted or dropped into the Agent composer and travel with the
+  turn; pasted attachments come back as thumbnails in a resumed session.
+- Studio Agent sessions persist across reloads, and the shared panel is split
+  into a surface-neutral core plus a Studio adapter whose receipts land as
+  Inspector rows.
+- Studio commands: `patch_elements` is one thin family derived from the
+  element declaration table (environment description, style and sheet flag
+  included); element ranges are the single source of truth, partial receipts
+  are reported, revisions are read-safe, and a session re-admits within a turn.
+- Stop handling: a Studio stop that names a motion job this session never
+  admitted is refused; retired jobs no longer accept stale stops; the model
+  registry is built single-flight and refreshed on sign-in.
+
+Studio
+
+- Gated Fal H3 motion generation: the capture card and a wide authoring modal
+  with duration, motion description and an editable prompt. References are
+  accepted only from a fixed camera with the palette mannequin, clipped or
+  unshaded references are rejected, and Fal video routes through H3 Max Turbo.
+- The mannequin is readable for mocap input: separated palette hues per limb
+  and two eye marks on the face; a warning fires before cropped mocap framing.
+- Motion extraction: hybrid 2D keypoints use palette-derived joints where the
+  render lost a part (face from ViTPose); GVHMR takes get a sigma-3 smoother and
+  a foot-anchored root. Clearing a motion take also drops its persisted
+  `motionRef`.
+- Look through has one entry in the Shot monitor; the on-screen Shot camera
+  indicator and Esc return to the free camera without a duplicate toolbar
+  toggle.
+- Camera fly, pan and orbit lock the pointer for the hold: the cursor hides,
+  the view can turn past the window edge, and release puts the cursor back
+  where the press started.
+- One undo entry per key light, environment and character transform gesture;
+  agent camera history stays reachable after an object undo; persistence
+  elements are declared and verified.
+
+Housekeeping
+
+- Dead exports, duplicate 500 handlers and the committed `.omo/` research
+  artifacts are gone (#411). The README is restructured around the user path.
+- `cclay live` and the agent sidecar share one workspace-selection rule.
+- Agent tests keep their sessions out of the author's config directory.
+
 ## 1.8.1
 
 The Studio camera tutorial now starts where the landing page does and shows
-where to click.
+where to click. Look-through flies the shot camera instead of opening the player.
 
 - Opening the tutorial (Settings ▾ → Camera tutorial or `/app/?tutorial=camera`)
   loads the City Block starter scene with the walk take on its character, at
@@ -16,6 +86,9 @@ where to click.
   turning green as they are pressed. The hint card names the region ("↓
   Timeline, Shots lane", "→ Viewport"). Overlays never take the pointer and go
   static under `prefers-reduced-motion`.
+- **Look through** on the Camera bar (and the Shot monitor's expand icon) hands
+  the viewport to the shot camera with the same fly bindings as the free camera.
+  Esc returns. The chrome-free player remains the Workflow embed.
 
 ## 1.8.0
 

package/README.md

@@ -13,24 +13,24 @@
 <p align="center">
   <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue"></a>
   <a href="https://www.npmjs.com/package/cozyclay"><img alt="npm" src="https://img.shields.io/npm/v/cozyclay"></a>
-  <img alt="Node 22.13+" src="https://img.shields.io/badge/node-22.13%2B-brightgreen">
+  <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>
 </p>
 
 <p align="center">
   <a href="https://cozyclay.org/#try">Try it in the browser</a> ·
-  <a href="https://cozyclay.org/greybox-to-video/">Greybox to AI video</a> ·
-  <a href="https://cozyclay.org/previs-software/">Previs software compared</a> ·
   <a href="#quick-start">Quick start</a> ·
   <a href="#what-you-can-do">Features</a> ·
-  <a href="#ai-control-mcp">AI control</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>
 </p>
 
 ---
 
-CozyClay is a browser-based 3D staging studio built with Three.js and React Three Fiber. Block a scene, pose characters, sequence motion prompts on a timeline, and preview generated motion — all in one local workspace.
+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
@@ -52,21 +52,19 @@ https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 
 |  | |
 | --- | --- |
-| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with a W/E/R gizmo. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye plan view drives 2D root waypoints for character paths. The topbar's Auto Color toggle gives every object its own stable display 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. |
-| **Undo anything** | Every scene mutation goes through one history store: a drag, a scrub, an inspector edit is exactly one undo entry. `Esc` cancels an in-flight drag and restores the pre-drag transform. |
-| **Generate motion** | Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to Kimodo, then play the result back with sparse IK correction where the generated motion needs fixing. |
-| **Direct it with an AI** | Connect Claude — or any MCP client — and ask for a shot in plain language. It places the cast, frames “a low wide profile”, generates multi-phase motion, and the viewport moves in front of you. See [AI control](#ai-control-mcp). |
-
-## Requirements
-
-- Node.js 22.13 or newer
-- npm, or bun
-- A Chromium-based browser
-- An SSH-accessible NVIDIA machine running Kimodo, for motion generation — run `npm run kimodo:setup` once; the first setup downloads the Kimodo checkpoint and text-encoder stack.
+| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with the transform strip's gizmo. 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. |
+| **Generate motion** | Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to Kimodo, then play the result back with sparse IK correction where the generated motion needs fixing. Draw over a joint's trail to reshape a take, keep most of it and regenerate a window, and step back through its history. |
+| **Capture motion from video or a photo** | Drop a clip or a still: the GPU box runs [GVHMR](https://github.com/zju3dv/GVHMR) and the result is retargeted onto the character with stabilisation, contact correction and a quality gate. |
+| **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", generate multi-phase motion, and the viewport moves in front of you. See [AI control](#ai-control). |
 
 ## Quick start
 
+You need Node.js 22.19 or newer, npm or bun, and a Chromium-based browser.
+
 ```bash
 npx cozyclay
 # or
@@ -77,24 +75,55 @@ That downloads the built studio and opens it at `http://127.0.0.1:5180/app/`. No
 
 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.
 
-Motion generation uses Kimodo by default once you point it at an SSH-accessible NVIDIA machine:
+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
 
 ```bash
-CCLAY_KIMODO_HOST=user@your-gpu-box npx cozyclay
+git clone https://github.com/NomaDamas/CozyClay.git
+cd CozyClay
+npm install
+npm run dev
 ```
 
-Install the remote worker once:
+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 Kimodo bridge once `CCLAY_KIMODO_HOST` points at a GPU box; without that variable it starts the studio alone and says so. `npm run dev:ui` starts the browser UI alone in every case.
+
+### Motion generation
+
+Generating new motion needs Kimodo on a machine you can reach. Point the Studio at it and install the worker once:
 
 ```bash
 CCLAY_KIMODO_HOST=user@your-gpu-box npm run kimodo:setup
+CCLAY_KIMODO_HOST=user@your-gpu-box npx cozyclay
 ```
 
-## AI control (MCP)
+The installer detects OS, architecture, RAM and CUDA and picks the best-supported backend for that host — kimodo-mlx on a big Apple Silicon machine, kimodo.cpp with Metal or CPU otherwise, the upstream PyTorch stack on NVIDIA. An SSH-accessible NVIDIA box is the classic target and the only route with the full feature set; the same box runs GVHMR for video and photo mocap. Routes, overrides and local-only limits are in [`docs/kimodo-setup.md`](docs/kimodo-setup.md).
+
+## 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.
 
-The studio ships an [MCP](https://modelcontextprotocol.io) server, so an AI assistant can drive it — the same scene, the same viewport, live:
+### Agent panel in the Studio
 
-> “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.”
+**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
 {
@@ -107,78 +136,20 @@ The studio ships an [MCP](https://modelcontextprotocol.io) server, so an AI assi
 }
 ```
 
-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.
+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, generated motion, prompt blocks 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`, `set_prompt_blocks`, `generate_motion`, and
-  `apply_batch` require the live editor.
+- **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`, `set_prompt_blocks`, `generate_motion`, 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 clone
-
-```bash
-git clone https://github.com/NomaDamas/CozyClay.git
-cd CozyClay
-npm install
-npm run dev
-```
-
-Open `http://127.0.0.1:5180/` for the Studio. The Workflow canvas remains available at `http://127.0.0.1:5180/workflow/` when you need its node editor. `npm run dev` starts the studio together with its local Kimodo bridge once `CCLAY_KIMODO_HOST` points at a GPU box; without that variable it starts the studio alone and says so, and Block Generation stays unavailable until you set it. `npm run dev:ui` starts the browser UI alone in every case. The bridge listens on loopback only; Kimodo host variables are documented in [`tools/kimodo/setup-on-box.sh`](tools/kimodo/setup-on-box.sh).
-
-### Workflow canvas
-
-The Vibe-Workflow canvas is available at `http://127.0.0.1:5180/workflow/`. It keeps the original node-style flow and adds a **CozyClay Scene** node with an interactive 3D viewport, frame/camera controls, and an Open Studio handoff. Start it with the normal dev server, or run `npm run dev:ui` by itself for local-only editing. Workflow graphs are saved in the browser and execute locally; no remote workflow service or API key is required.
-
-## Hosted demo
-
-Installing a GPU motion backend is the hard part, so `cozyclay.org` also runs a queued demo: a visitor writes one prompt, gets a ticket link, and a GPU box owned by the maintainer generates the motion and uploads it. The visitor never installs anything and never leaves the site — the result opens in the studio itself.
-
-The pieces live in this repository, under `AGPL-3.0-or-later` like everything else:
-
-| Path | Role |
-| --- | --- |
-| `demo/`, `d/` | Static composer and ticket/result pages, built into `dist/` by the same `npm run build` |
-| `workers/api/` | Cloudflare Worker queue API (D1 for state, R2 for results), with its own pinned toolchain |
-| `tools/demo-worker/` | The GPU-box poller. Outbound fetch only — it never opens a listening socket |
-
-**Queue policy.** Jobs run in a single FIFO queue. All of these values live in `workers/api/src/policy.js`; nothing else carries a copy.
-
-| Rule | Value |
-| --- | --- |
-| Active jobs per account | 1 |
-| Daily cap | 2 per account |
-| Global waiting cap | 200, then submissions are refused |
-| Lease / heartbeat / hard timeout | 15 min lease, renewed every 60 s, 20 min hard stop |
-| Attempts | 2 (one automatic retry); a failed job refunds the daily cap |
-| Result retention | 30 days, then the R2 object is deleted |
-| Prompt limit | shared with the studio via `tools/ardy/prompt-limits.mjs` |
-
-**Secrets.** Never committed. Configure each with `wrangler secret put` against `workers/api/wrangler.toml`:
-`GOOGLE_CLIENT_SECRET`, `CC_WORKER_SECRET`, `SESSION_SIGNING_KEY`, `TURNSTILE_SECRET_KEY`. The non-secret `GOOGLE_CLIENT_ID` and `TURNSTILE_SITE_KEY` vars in `wrangler.toml` must also be replaced before a real deployment.
-
-**Running the API locally.**
+### From a terminal
 
-```bash
-npm run demo:api:install   # npm --prefix workers/api ci
-npm --prefix workers/api exec -- wrangler d1 migrations apply cozyclay-demo --local
-npm run demo:api           # wrangler dev on 127.0.0.1:8787
-```
+`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).
 
-**Running the GPU-box worker.** The hosted queue worker has its own isolated runtime and reaches the API outbound only. It is independent from the local Studio's Kimodo backend.
+## Workflow canvas
 
-```bash
-CC_DEMO_API_BASE=https://api.cozyclay.org \
-CC_WORKER_ID=box1 \
-CC_WORKER_SECRET=... \
-  npm run demo:worker
-```
-
-See [`workers/api/README.md`](workers/api/README.md) for the deployment, migration and rollback runbook, and [`tools/demo-worker/README.md`](tools/demo-worker/README.md) for service units, environment-file permissions and the listening-socket check.
+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
 
@@ -192,7 +163,7 @@ See [`workers/api/README.md`](workers/api/README.md) for the deployment, migrati
 | Alt + drag | Orbit the selection |
 | Scroll | Dolly; while flying, sets the fly speed instead |
 | Click | Select; empty space clears |
-| W / E / R | Move / rotate / scale tool |
+| 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 |
@@ -200,6 +171,26 @@ See [`workers/api/README.md`](workers/api/README.md) for the deployment, migrati
 | 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
+
+| Read | For |
+| --- | --- |
+| [`docs/kimodo-setup.md`](docs/kimodo-setup.md) | Installing Kimodo: the route table, CUDA over SSH, local MLX/Metal/CPU generation and what each route supports |
+| [`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 |
+| [`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 hosted demo on cozyclay.org: queue policy, the Cloudflare Worker and the GPU-box poller |
+| [`docs/releasing.md`](docs/releasing.md) | Publishing a signed npm release |
+| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
+
+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/).
 
 ## Validate
 
@@ -212,6 +203,9 @@ See [`workers/api/README.md`](workers/api/README.md) for the deployment, migrati
 | `npm run test:theme` / `test:appearance` / `test:layout` | UI theme, appearance, layout |
 | `npm run test:lifecycle` | Dev-server process lifecycle |
 | `npm run test:ardy` | Motion conversion, playback, and IK pipeline |
+| `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 |
@@ -228,69 +222,22 @@ Found something broken, or want a feature? [Open an issue](https://github.com/No
 
 **Repository hygiene.** Generated motion archives, QA output, build output, logs and local runtime artifacts are not source files and must not be committed. Keep `tools/ardy/out/`, `artifacts/`, `dist/`, `.gjc/` and `.npz` files local.
 
-All runtime libraries intentionally live in `devDependencies` because the published npm package ships the prebuilt `dist/`, so `npx cozyclay` must not install the studio's dependency tree.
+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
 
-The hosted site at [cozyclay.org](https://cozyclay.org/) collects anonymous usage analytics via [PostHog](https://posthog.com/) (US Cloud). There are no cookies and no session recording, and Do-Not-Track is respected. A random pseudonymous identifier is kept in your browser's localStorage so that returning visits and retention can be counted; it is never linked to an account or project content and is removed by clearing site data or using the opt-out toggle.
-
-Events collected:
-
-| Event | Purpose |
-| --- | --- |
-| `install:first_launch` | First run of the official npm package |
-| `app:session_started` | Start of an official npm package session |
-| `app:session_ended` | Session duration, action count, and scenes touched (bucketed) |
-| `feature:used` | One signal per feature per session |
-| `$pageview` | Funnel and drop-off analysis |
-| `scene:created` | Funnel and drop-off analysis |
-| `scene:loaded` | Funnel and drop-off analysis |
-| `project:saved` | User-owned project persistence |
-| `project:opened` | Return to a saved project (age bucket) |
-| `craft:first_action` | Funnel and drop-off analysis |
-| `motion:backend_state` | Motion capability at session start (`none`, `local_kimodo`, or `hosted`) |
-| `motion:generate_blocked` | Generate intent when no motion backend is available |
-| `motion:job_started` | Motion reliability |
-| `motion:job_succeeded` | Motion reliability |
-| `motion:job_failed` | Motion reliability |
-| `export:blocking_frame_succeeded` | Funnel and drop-off analysis |
-| `activation:completed` | Funnel and drop-off analysis |
-| `hosted:composer_viewed`, `hosted:login_started`, `hosted:ticket_created` | Hosted demo funnel |
-| `hosted:result_opened`, `hosted:opened_in_studio` | Hosted result funnel |
-
-Geo data comes from ingest-time GeoIP country lookup only — no precise location is collected. Prompt text, asset names, file names, project content, local paths, and any user-entered text are never collected.
-
-The official npm package also measures anonymous first launches, sessions, and
-the same in-app funnel on its `127.0.0.1` studio. It stores one random
-installation identifier in `~/.config/cozyclay/state.json` so returning use can
-be counted across ports and browser storage resets. Source checkouts, forks,
-development servers, CI, and tests do not send analytics. Official npm
-artifacts carry a signature checked by the launcher, so copying or repackaging
-the source does not enable telemetry.
-
-Each event is registered with `origin_kind` (`local` or `hosted`), a coarse
-operating-system label, and (for npm sessions) `install_kind` (`npx` or
-`global`). Source checkouts are classified as `clone` and remain telemetry-off.
-The first npm launch may optionally answer a one-line channel question
-(`x`, `hn`, `reddit`, `github`, `friend`, `other`, or `skip`); `skip` sends no
-acquisition value. Session duration and action counts are buckets, and project
-events never include names, paths, prompts, or timestamps.
-
-The npm package prints this disclosure once on first launch. Control it at any
-time:
+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
-cclay telemetry on
 ```
 
-`COZYCLAY_TELEMETRY=0` and `DO_NOT_TRACK=1` disable collection for a launch.
-The in-app topbar toggle changes the same npm-package setting and removes its
-anonymous installation identifier. Hosted-site visitors can opt out with that
-toggle, browser Do-Not-Track, or a content blocker.
+`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).
+
+## Hosted demo
 
-PostHog's free plan retains events for 1 year.
+Installing a GPU motion backend is the hard part, so `cozyclay.org` also runs a queued demo: a visitor writes one prompt, gets a ticket link, and a GPU box owned by the maintainer generates the motion and uploads it — the result opens in the studio itself. The composer pages, the Cloudflare Worker queue API and the GPU-box poller all live in this repository; the queue policy and runbooks are in [`workers/api/README.md`](workers/api/README.md).
 
 ## License & credits
 

package/THIRD_PARTY_NOTICES.md

@@ -34,6 +34,27 @@ 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`).
@@ -117,6 +138,33 @@ event table and opt-out controls.
 - License: Apache-2.0 AND MIT
 - Source: https://github.com/PostHog/posthog-js
 
+## pi agent packages
+
+The optional agent sidecar loads `@earendil-works/pi-ai` and
+`@earendil-works/pi-agent-core` at runtime (they are declared dependencies,
+loaded lazily by the sidecar; the launcher itself does not import them).
+
+- Copyright (c) Earendil Works
+- License: MIT
+- Source: https://github.com/earendil-works/pi (packages/ai → @earendil-works/pi-ai, packages/agent → @earendil-works/pi-agent-core)
+
+Their transitive runtime dependencies, which the agent sidecar also loads, are:
+
+- `@anthropic-ai/sdk` — License: MIT — https://github.com/anthropics/anthropic-sdk-typescript
+- `openai` — License: Apache-2.0 — https://github.com/openai/openai-node
+- `@google/genai` — License: Apache-2.0 — https://github.com/googleapis/js-genai
+- `@aws-sdk/client-bedrock-runtime` — License: Apache-2.0 — https://github.com/aws/aws-sdk-js-v3
+- `@smithy/node-http-handler` — License: Apache-2.0 — https://github.com/smithy-lang/smithy-typescript
+- `http-proxy-agent` — License: MIT — https://github.com/TooTallNate/proxy-agents
+- `https-proxy-agent` — License: MIT — https://github.com/TooTallNate/proxy-agents
+- `partial-json` — License: MIT — https://github.com/promplate/partial-json-parser-js
+- `typebox` — License: MIT — https://github.com/sinclairzx81/typebox
+- `@earendil-works/chord` — License: MIT — https://github.com/earendil-works/pi
+- `@earendil-works/pi-telemetry` — License: MIT — https://github.com/earendil-works/pi
+- `diff` — License: BSD-3-Clause — https://github.com/kpdecker/jsdiff
+- `ignore` — License: MIT — https://github.com/kaelzhang/node-ignore
+- `yaml` — License: ISC — https://github.com/eemeli/yaml
+
 ## CozyClay license scope
 
 The CozyClay combined work in this repository is distributed under AGPL-3.0-or-later, subject to the transition details in `LICENSING.md`. That license does not replace or relicense Three.js, ARDY, ARDY model checkpoints, the bundled fonts, the character rigs, or any other third-party component.