@zvada/cr8 0.3.0 → 0.3.1

package/docs/user/cli.md

@@ -32,6 +32,8 @@ cr8 serve --project designs/launch --open
 
 `start` and `serve` print one JSON readiness record with the loopback `url`, the `port`, the `pid`, the `workspaceRoot` and the `project` (its workspace-relative `path`, its `directory`, name, `workspaceId` and `sequence`), stay attached, and open the browser (`start` unless `--no-open`; `serve` with `--open`). A workspace with no project makes `serve` refuse and name `cr8 start <path>`, which creates the project and serves it; when the workspace contains exactly one project, `--project` may be omitted.
 
+`start` also enables MCP and reports `mcpUrl`: an agent registered with `mcp-connect` in the same workspace joins this process and edits the same project. `serve` enables MCP only with `--mcp`. A browser-only session stays intact when an agent tries to attach; stop it with Ctrl-C in its original terminal, restart the same command with `--mcp`, then reconnect the agent.
+
 Both record the runtime they started in `<workspaceRoot>/.cr8/runtime.json` (so does `mcp`, once an agent's canvas_init or canvas_open has opened a project) (`url`, `pid`, `workspaceRoot`, `projectPath`, `startedAt` and the `command`; the directory ignores itself in Git, and the record goes on a clean shutdown), and the ready line names the file as `record`. A CLI run anywhere inside that workspace then needs no `--url`. Without one, the CLI uses, in order: `CR8_URL` when set; the recorded runtime when its `/health` answers for the workspace around the current directory (or the one `--workspace DIR` or `CR8_WORKSPACE` names); else `http://127.0.0.1:4176` (or `CR8_PORT`). A runtime the CLI chose this way is checked before the command runs: when its `/health` names another workspace than the CLI's, the command is refused with `wrong_runtime` and one sentence, `The runtime at URL serves WORKSPACE (project PATH); this workspace's runtime is URL2 (from start at TIME); pass --url URL2 or start one here`, or, when the recorded runtime no longer answers, `… no longer answers; start one here: cr8 start PATH`. A record whose process is gone is removed by the command that finds it gone; the workspace stays known by its `.cr8` directory, so a stranger on the default port is still refused there (`this workspace has no runtime recorded; start one here`) until a new `start`. Every probe the CLI makes to choose a runtime waits at most 1.5 s. `--url` is taken as given. `status` answers `url`, the runtime that answered, beside the `workspaceRoot` and `project` it serves.
 
 The default port is 4176 (or `CR8_PORT`). When another process holds it and no `--port` was asked for, the runtime takes a free port and says so in a `note` beside the `port` and `url` it serves on. With an explicit `--port` that is held, it refuses with `port_in_use`: when the holder is another CR8 runtime, the message names its pid, the project it serves and its workspace root (read from its `/health`), and says to pass another `--port` or to talk to it with `--url`. `status` carries the same `workspaceRoot` and `project` (`path`, `directory`), so an agent tells a stranger's runtime on a port from its own.
@@ -70,7 +72,7 @@ Omitting `--sequence` reads the latest session immediately before a mutation. Th
 | Command | Purpose |
 | --- | --- |
 | `start [PROJECT_PATH] [--workspace DIR] [--port N] [--no-open]` | Open the project, or create it when the named path holds none yet (a legacy `.relay` project opens and migrates), serve the loopback canvas, open the browser and emit JSON readiness with `created`, the `port`, a `note` when the default port was busy and `record`, the file the workspace remembers the runtime by, so a CLI run inside it finds it without `--url`. |
-| `serve [--workspace DIR] [--project PATH] [--port N] [--host LOOPBACK] [--open]` | Open one project and serve the loopback canvas; emit JSON readiness with the `port` (and a `note` when the default was busy) and `record`, as `start` does. A workspace with no project is refused with a sentence naming `cr8 start <path>`. |
+| `serve [--workspace DIR] [--project PATH] [--port N] [--host LOOPBACK] [--open] [--mcp]` | Open one project and serve the loopback canvas, adding MCP when requested; emit JSON readiness with the `port` (and a `note` when the default was busy) and `record`, as `start` does. A workspace with no project is refused with a sentence naming `cr8 start <path>`. |
 | `init PROJECT_PATH [--workspace DIR]` | Create a blank project directory and release it. |
 | `mcp [--transport stdio\|http] [--port N] [--workspace DIR]` | Serve the MCP tools; `http` mounts `/mcp` on the loopback listener for development hosts. |
 | `mcp-connect [--workspace DIR] [--project PATH]` | Recommended host registration: join the unique compatible runtime in the agent session's workspace, or start project-free stdio discovery. Defaults to `CLAUDE_PROJECT_DIR`, then the launch directory. A fixed workspace is optional; multiple live runtimes require an explicit project. |

package/docs/user/desktop.md

@@ -29,7 +29,9 @@ The local runtime owns the project's single-writer lease. CLI agent commands can
 
 First launch offers a skippable questionnaire and optional agent setup, then opens the workspace without creating a file. Canvas offers **New file** and **Open canvas** afterward. Creation asks for a name and workspace folder, then creates `designs/<name>/cr8.json` through the canonical initializer. Cancel creates nothing. Local editing needs no account, system Node, npm or separate skills.
 
-The agent screen connects **Claude Code** or **Codex**. Connect uses the installed host CLI to add one user-level `cr8-desktop` entry pointing to CR8's stable launcher, with no fixed workspace, project or launch directory. The agent does not need to be running: setup only uses its CLI administration commands. It preserves unrelated configuration and refuses duplicate CR8 integrations. If the CLI isn't found, choose **Locate CLI…** or continue without it. **Copy setup prompt** offers the same server definition for agent-assisted setup. Configuration saved and a live agent handshake are different states; restart an existing agent session to load a new registration. A saved choice doesn't trigger sign-in or an agent turn.
+The agent screen saves configuration for **Claude Code** or **Codex**. CR8 requires MCP `2026-07-28`; a successful registration does not verify protocol compatibility. See the [dated host checks and recovery steps](install.md#host-compatibility). If your host reports an unsupported protocol, continue to **Open workspace** to use Canvas and Flows, or choose **Copy CLI command** on the agent screen. The command line and local browser work without MCP.
+
+Connect uses the installed host CLI to add one user-level `cr8-desktop` entry pointing to CR8's stable launcher, with no fixed workspace, project or launch directory. The agent does not need to be running: setup only uses its CLI administration commands. It preserves unrelated configuration and refuses duplicate CR8 integrations. If the CLI isn't found, choose **Locate CLI…** or continue without it. **Copy setup prompt** offers the same server definition for agent-assisted setup. Configuration remains saved and unverified until a successful MCP call establishes live agent presence. Restarting loads a new registration but cannot add protocol support. A saved choice doesn't trigger sign-in or an agent turn.
 
 Return through **CR8 → Settings…** on macOS or **File → Settings…** on Windows/Linux (⌘, / Ctrl+,), then choose **Agents · MCP**. Setup works before choosing a workspace or design. Each new agent session supplies its own project folder through `CLAUDE_PROJECT_DIR` or its launch directory. CR8 joins that workspace's unique compatible runtime, or starts without a design and waits for an explicit file choice. Settings is an in-place dashboard section with the Canvas/Flows/Settings sidebar. **Back to editor** returns to the mounted editor, preserving selection, undo, and Flow drafts. Disconnect removes only an entry still matching the configuration CR8 created; if it changed externally, use the agent's settings instead. Switching repositories does not require reconnecting; project switching within a running session remains canonical `canvas_open`.
 
@@ -74,10 +76,12 @@ npx electron dist/desktop/main.mjs --workspace "$PWD" --project designs/example
 
 `npm run test:desktop` runs the native macOS onboarding test against built assets: one native window from onboarding through canvas, workspace dashboard search and navigation, Canvas/Flows switching, Settings before a design exists, copied CLI execution without system Node, copied MCP configuration and handshake, cancel/create, actual host CLI registration in isolated configuration directories when those CLIs are installed, launcher MCP handshake, shared edits, desktop restart, one-step human undo after returning from the dashboard/Settings, project opening without relaunch, and removal of owned host entries. It uses Playwright's default Electron loader. `npm run test:install` verifies the separately packed command product. Other platforms still require their native installed-artifact checks before release.
 
+The handshake tests use CR8's pinned SDK client. Actual host registration checks only verify saved configuration; neither is proof that a particular Claude Code or Codex release supports CR8's required protocol. The installation guide records the separate [actual-host results](install.md#host-compatibility).
+
 Canvas file cards use the canonical renderer and local project assets, with a bounded disposable memory cache. Empty canvases and unavailable previews are labeled. Refreshing previews never changes the active project.
 
 The dashboard uses neutral dark surfaces, soft hairlines, and original illustrated product icons generated through `designs/cr8-product-icons/flows.json`. Icon provenance is recorded in `packages/editor/src/workspace/icons/provenance.json`. Krea was used as a visual reference; its artwork is not bundled.
 
 The local browser and desktop load the same workspace screens from `packages/editor/src/workspace`, including Canvas, Flows, Settings and onboarding. Inter typography and interface styles are shared with the editor. Electron contributes native folder dialogs, its bundled CLI and explicit agent registration; browser Settings provides manual MCP configuration and the npx command. The browser stays bound to the workspace of its local runtime. Opening Settings preserves the mounted editor and Flow draft in both hosts. The public account website remains a separate account-only build.
 
-For a browser session started from the CLI, include `--mcp` in the start command to enable agent connections. Browser Settings offers per-agent setup prompts and a version-matched `npx … mcp-connect` configuration without a fixed workspace. When the agent runs in the browser's workspace, it follows the unique live runtime across design switches and reconnects. If multiple runtimes are open there, add `--project designs/name` to select one explicitly.
+For a browser session started with `cr8 start`, MCP is enabled by default. The low-level `cr8 serve` command needs `--mcp`. Browser Settings offers per-agent setup prompts and a version-matched `npx … mcp-connect` configuration without a fixed workspace. When a compatible agent runs in the browser's workspace, it follows the unique live runtime across design switches and reconnects. If multiple runtimes are open there, add `--project designs/name` to select one explicitly.

package/docs/user/install.md

@@ -13,7 +13,7 @@ Requires Node.js 20.19 or newer; use a currently supported Node LTS release. Thi
 npx @zvada/cr8 start designs/first
 ```
 
-That single command creates the project when it does not exist, serves it on a loopback port and opens your browser. The same binary is the MCP server and the CLI; install it once with `npm install -g @zvada/cr8` if you would rather not type `npx`. The rest of this page writes `cr8` and means whichever install you chose.
+That single command creates the project when it does not exist, serves the browser and MCP together on a loopback port and opens your browser. The same binary is the MCP server and the CLI; install it once with `npm install -g @zvada/cr8` if you would rather not type `npx`. The rest of this page writes `cr8` and means whichever install you chose.
 
 ## A release binary
 
@@ -62,20 +62,41 @@ cr8 start --no-open       # serves without opening a browser; the answer carries
 
 ## Add it to an agent
 
-Use an agent host that supports MCP `2026-07-28`; CR8 rejects older protocol handshakes. The agent host owns the process: it starts CR8 when needed and stops it when the session ends. Do not start a separate server for the agent.
+Use an agent host that supports MCP `2026-07-28`; CR8 rejects older protocol handshakes. The agent joins a compatible runtime already started in its workspace. When none is running, the host starts CR8 when needed and stops its process when the session ends. A human-owned `cr8 start` process stays open after the agent disconnects.
+
+### Host compatibility
+
+Saving an MCP entry proves only that the host saved configuration. It does not verify that the host can connect. Isolated checks on **2026-09-14**, without a model turn, found:
+
+| Host | Versions checked | Requested protocol | Result |
+| --- | --- | --- | --- |
+| Claude Code | 2.1.267, 2.1.270 | `2025-11-25` | Rejected with `-32022` |
+| Codex | 0.153.4, 0.154.0 | `2025-06-18` | Rejected with `-32022` |
+
+These are dated observations, not compatibility rules based on version numbers. The registration commands below remain useful for a host that supports `2026-07-28`; neither checked host completed that connection. Restarting a session loads new configuration but cannot add protocol support. After a compatible host update, verify with a read-only `list_skills` call. CR8's SDK tests alone do not verify an installed agent host.
+
+If the host reports an unsupported protocol or `-32022`, keep CR8's protocol requirement unchanged and use the local browser and CLI:
+
+```bash
+npx @zvada/cr8@0.3.1 start designs/first
+```
+
+Agents can use the same [JSON CLI](cli.md) without MCP; `cr8 skills get cr8-design --path references/cli.md` reads its bundled command guidance. Desktop users can continue to **Open workspace**, or copy the bundled CLI command from the agent setup screen. No agent connection is needed for Canvas or Flows.
+
+### Save the configuration
 
 **Codex**
 
 ```bash
-codex mcp add cr8 -- npx -y @zvada/cr8@0.3.0 mcp-connect
+codex mcp add cr8 -- npx -y @zvada/cr8@0.3.1 mcp-connect
 ```
 
-This saves a user-level connection available across projects. CR8 uses the directory where the host launches it. Ask it: *Initialize CR8 at `designs/thumbnail` and create a 1280 × 720 YouTube thumbnail. Keep every layer editable and show me the canvas.*
+This saves user-level configuration available across projects. CR8 uses the directory where the host launches it. After verifying a connection, ask it: *Initialize CR8 at `designs/thumbnail` and create a 1280 × 720 YouTube thumbnail. Keep every layer editable and show me the canvas.*
 
 **Claude Code**
 
 ```bash
-claude mcp add --transport stdio --scope user cr8 -- npx -y @zvada/cr8@0.3.0 mcp-connect
+claude mcp add --transport stdio --scope user cr8 -- npx -y @zvada/cr8@0.3.1 mcp-connect
 ```
 
 Claude Code exposes its project directory to the server. Once the repository is public the plugin marketplace is the shorter road: `/plugin marketplace add zvadaadam/baby-canva`, then `/plugin install cr8`.
@@ -87,7 +108,7 @@ Claude Code exposes its project directory to the server. Once the repository is
   "mcpServers": {
     "cr8": {
       "command": "npx",
-      "args": ["--yes", "@zvada/cr8@0.3.0", "mcp-connect"]
+      "args": ["--yes", "@zvada/cr8@0.3.1", "mcp-connect"]
     }
   }
 }
@@ -101,9 +122,11 @@ Use `/mcp` to diagnose a host, and `codex mcp remove cr8` or `claude mcp remove
 
 ## Desktop and browser sessions
 
-The desktop installer already includes Electron, the CR8 runtime, MCP App and embedded skills. First launch offers an optional questionnaire and agent setup before opening the workspace. **Connect** in onboarding or **Settings → Agents · MCP** uses the installed Claude Code or Codex CLI to add a user-level connection. No agent chat, chosen folder, design, or account is required. It points to a stable bundled launcher, works with the desktop closed, and survives normal app replacement. Setup preserves existing integrations and can remove its own unchanged entries. Saved configuration and a live connection have separate status.
+The desktop installer already includes Electron, the CR8 runtime, MCP App and embedded skills. First launch offers an optional questionnaire and agent setup before opening the workspace. **Connect** in onboarding or **Settings → Agents · MCP** uses the installed Claude Code or Codex CLI to save user-level configuration. No agent chat, chosen folder, design, or account is required. It points to a stable bundled launcher, works with the desktop closed, and survives normal app replacement. Setup preserves existing integrations and can remove its own unchanged entries. Saved configuration stays unverified until a successful MCP call establishes live agent presence; setup shows the protocol requirement and a copyable CLI fallback before registration.
+
+Browser Settings offers **Copy setup prompt** for each agent and syntax-highlighted manual configuration. The prompts use the same server definition and ask the agent to preserve other integrations. The browser cannot register a native host directly. For collaboration with a human browser session, run `cr8 start designs/first`; MCP is enabled by default and the standard `mcp-connect` registration discovers it in the agent's workspace. Its `mcpUrl` is also available for hosts using a direct, session-specific Streamable HTTP connection.
 
-Browser Settings offers **Copy setup prompt** for each agent and syntax-highlighted manual configuration. The prompts use the same server definition and ask the agent to preserve other integrations. The browser cannot register a native host directly. For collaboration with a human browser session, run `cr8 start designs/first --mcp`; the standard `mcp-connect` registration discovers it in the agent's workspace. Its `mcpUrl` is also available for hosts using a direct, session-specific Streamable HTTP connection.
+The low-level `cr8 serve` command enables MCP only with `--mcp`. If an existing browser-only session refuses an agent connection, press Ctrl-C in the terminal that started it, restart that same command with `--mcp`, then reconnect the agent. CR8 leaves the running session and its project lease intact until you stop it.
 
 ## Skills
 

package/docs/user/mcp.md

@@ -82,6 +82,8 @@ Read only the skill and references relevant to the work. Reading a resource does
 
 CR8 uses the stable MCP TypeScript SDK v2 and requires protocol `2026-07-28`. The SDK handles native `server/discover`, per-request metadata, cancellation and subscription streams for stdio and Streamable HTTP. Older `initialize` handshakes are rejected. A host must support this protocol; it can then choose either the Skills extension or the ordinary `list_skills` / `read_skill` tools. Both interfaces are current and share one catalog.
 
+Saved host configuration is not a verified connection. The shared launcher reports live agent presence after a successful MCP call; discovery alone is not enough. If a host reports an unsupported protocol (`-32022`), use CR8's CLI and local browser while waiting for a compatible host. See [checked Claude Code/Codex versions and recovery](install.md#host-compatibility); SDK integration tests do not establish those hosts' readiness.
+
 `list_skills` takes no input and returns each shipped skill's `name`, `description`, `readWhen` (the sentence of the description that says when it applies) and `files`. `read_skill` takes `{ name, path? }` and returns the skill's `SKILL.md` as text, or the file named by `path` (for example `agents/openai.yaml`); the structured result carries the same `content` with its `path`. Both are read-only. An unknown name or file is refused with `skill_not_found` or `skill_file_not_found` and a sentence naming what exists.
 
 Each skill is a short contract in `SKILL.md` plus a `references/` folder the contract's last section lists: the design skill's start, build, verify, CLI and troubleshooting references; the flows skill's models (which model for which job, and what each does that the brief did not ask for), build, run, results, CLI and troubleshooting references. `read_skill` with `path` (`references/models.md`, say) returns one; `list_skills` lists every file a skill carries.
@@ -114,7 +116,7 @@ The agent should show that loopback link after opening a project. It opens the h
 
 Desktop onboarding and **Settings → Agents · MCP** register a stable stdio launcher at user scope. The saved configuration contains no fixed workspace or design: each agent session supplies its project folder. Browser Settings copies the equivalent version-matched `npx … mcp-connect` configuration, with a setup prompt for each agent. Native Connect uses the host's CLI administration commands without starting a chat or creating a design; saved configuration is distinct from a verified live connection.
 
-The adapter discovers or starts the shared local runtime and forwards MCP over native Streamable HTTP; discovery, cancellation and MCP App calls stay on the canonical server. Browser users opt in with `cr8 start designs/first --mcp`; the readiness answer includes `mcpUrl`. Both use the existing project runtime, including atomic edits, selection, skills and `ui://cr8/canvas.html`. Disconnecting a client leaves the human’s session running. The browser’s direct HTTP URL is session-specific; the stable launcher discovers the current port and design across restarts and file switches. Workspace discovery verifies the existing runtime record and project leases; if several live runtimes share a workspace, or the bounded catalog cannot establish a unique one, use `mcp-connect --workspace DIR --project designs/name` to select the session explicitly. With no live runtime, setup starts an empty MCP process and leaves file selection to `canvas_projects`, `canvas_open` and `canvas_init`. Desktop, launcher and connected browser views retain a managed runtime until the last client leaves; a crashed native client is reaped. The stdio plugin route remains the default for a host-managed process; do not launch a second runtime for a project already open in the desktop.
+The adapter discovers or starts the shared local runtime and forwards MCP over native Streamable HTTP; discovery, cancellation and MCP App calls stay on the canonical server. `cr8 start designs/first` enables MCP by default; the readiness answer includes `mcpUrl`. The low-level `cr8 serve` command needs `--mcp`. Both use the existing project runtime, including atomic edits, selection, skills and `ui://cr8/canvas.html`. Disconnecting a client leaves the human’s session running. The browser’s direct HTTP URL is session-specific; the stable launcher discovers the current port and design across restarts and file switches. Workspace discovery verifies the existing runtime record and project leases; if several live runtimes share a workspace, or the bounded catalog cannot establish a unique one, use `mcp-connect --workspace DIR --project designs/name` to select the session explicitly. With no live runtime, setup starts an empty MCP process and leaves file selection to `canvas_projects`, `canvas_open` and `canvas_init`. Desktop, launcher and connected browser views retain a managed runtime until the last client leaves; a crashed native client is reaped. The stdio plugin route remains the default for a host-managed process; do not launch a second runtime for a project already open in the desktop.
 
 ## Development host
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvada/cr8",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A live design canvas shared by people and AI agents through the web, CLI, and MCP Apps.",
   "license": "SEE LICENSE IN LICENSE",
   "author": {
@@ -73,6 +73,9 @@
     "test:mcp-app": "node --import tsx --test tests/install/mcp-app.test.mjs",
     "test:account-ui": "npm run build --workspace @cr8/account-hub && node --import tsx --test tests/install/account-ui.test.mjs"
   },
+  "overrides": {
+    "sharp": "0.35.4"
+  },
   "devDependencies": {
     "@babel/parser": "7.29.7",
     "@cr8/contracts": "file:packages/contracts",

package/skills/cr8-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cr8-design
 description: Design in CR8 as the designer, from a brief or a reference, through its MCP or CLI surfaces. Use for new product screens, landing pages, marketing visuals, App Store screenshots, faithful reproduction of an existing page or picture, and any task where an agent designs on a canvas while a person watches or collaborates.
-allowed-tools: Bash(cr8:*), Bash(npx @zvada/cr8@0.3.0:*)
+allowed-tools: Bash(cr8:*), Bash(npx @zvada/cr8@0.3.1:*)
 ---
 
 # CR8 Design

package/skills/cr8-flows/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cr8-flows
 description: Build, run and reuse CR8 Flows, node graphs over image, vector and video models, through its MCP or CLI surfaces. Use when a task needs several generations in sequence or in parallel, a repeatable recipe a person can rerun and edit, a video or vector step, or a chain such as draft, edit, upscale; and when a person asks for variations, a campaign kit, or a pipeline rather than one picture.
-allowed-tools: Bash(cr8:*), Bash(npx @zvada/cr8@0.3.0:*)
+allowed-tools: Bash(cr8:*), Bash(npx @zvada/cr8@0.3.1:*)
 ---
 
 # CR8 Flows