@zvada/cr8 0.2.0 → 0.3.1

package/docs/user/app-store-screenshots.md

@@ -12,5 +12,3 @@ With MCP, call:
 With the CLI, use `cr8 playbooks`, `cr8 playbook app-store`, `cr8 styles --playbook app-store`, and `cr8 style <chosen-style>`.
 
 Playbooks define the task methodology and acceptance gate. Style Directions define the composition system: signature visual mass, layout, hierarchy, typography, color, imagery, anti-patterns, and visual checks. CR8 validates both against shared typed contracts and caches responses in process memory only. The installed skill and local design project never persist their bodies, so service updates are available without reinstalling the plugin.
-
-`canvas_guide({ topic: "app-store" })` and `cr8 guide --topic app-store` remain backward-compatible aliases for the playbook during migration.

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,9 +72,10 @@ 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. |
 | `projects [--workspace DIR]` | List bounded, workspace-relative CR8 projects and identify the active one. With `--workspace` (or `CR8_WORKSPACE`) the catalog is read from disk, so no server needs to run yet. Each ready project held by a live process carries a `session` with its `pid` and `port`. |
 | `open PROJECT_PATH` | Atomically switch to another listed project. |
 | `status` | Answer `url`, the runtime that answered, and summarize artboards, nodes, assets, diagnostics, and the dynamic design-knowledge discovery flow; its data carries `workspaceRoot` and `project` (`path`, `directory`), which project this runtime serves from where, and `mediaConnection`, whether the person's account is connected on this device, which generation needs. |
@@ -84,7 +87,6 @@ Omitting `--sequence` reads the latest session immediately before a mutation. Th
 | `style STYLE_ID` | Load one current visual direction with concrete composition and hierarchy rules. |
 | `materials [--kind icon\|recipe] [--query TEXT]` | Search the bundled named vector icons and small product recipes. Read-only; no open project, runtime connection or network needed. |
 | `material MATERIAL_ID [--key-prefix PREFIX]` | Return ordinary compose drafts in `result.data.composition`, with source attribution. Adapt them and pass them to `compose`; recipes are independent editable copies. The prefix namespaces node, token and text-style keys. |
-| `guide [--topic canvas-foundations\|web-app\|faithful-reproduction\|app-store]` | Backward-compatible alias for loading a legacy-named playbook. |
 | `skills [list]` | List the skills that ship with this CLI: name, description, when to read each, files, and where they live on disk. |
 | `skills get NAME [--path FILE]` | Print a skill's `SKILL.md` as markdown, not JSON, or one file it references such as `agents/openai.yaml`. |
 | `skills path [NAME]` | Print the on-disk skills directory, or one skill's; the compiled binary carries them embedded and refuses with `skills_embedded`. |
@@ -113,13 +115,13 @@ Omitting `--sequence` reads the latest session immediately before a mutation. Th
 | `media-job JOB_ID` | Read a media job by the id `media-create` returned. |
 | `media-download JOB_ID --out FILE [--output N]` | Write a completed media job's output to a file as it came, a clip included, so an agent can look at it or hand it over; `--output` is the 1-based output, the first when left out. |
 | `place (--job JOB_ID [--output N] \| --asset ASSET_ID) [--artboard FRAME_ID] [--fit cover\|contain] [--behind\|--on-top] [--name NAME]` | Put a picture on the design: a completed media job's output (copied into the project with its provider, model and generation ids as provenance) or an asset the project holds (an import), as an image layer in the named root artboard, centred at no more than 80 % of it (`--fit cover` fills it and goes behind what it holds), or in a new artboard to the right of everything. Answers `{ assetId, nodeId, artboardId, created, sequence, file }`. A clip stays on its cloud path. |
-| `media-materialize --src PATH` | Copy a completed job's output into the project as an ordinary asset, ready for `edit` with `insert_node`. |
+| `media-materialize --src PATH` | Copy an output into durable project files and return its source and dimensions; does not register an asset or layer. Use `place --job JOB_ID` to put it on the canvas. |
 | `workflow-create (--json JSON\|--file FILE) [--workspace-id ID] [--revision N]` | Create one workflow. The workflow needs an `id` you mint (see `schema --workflow`). `--workspace-id` defaults to the open project's and `--revision` to the catalog's current revision, read just before the request; an explicit stale revision still conflicts. |
 | `workflow-replace WORKFLOW_ID (--json JSON\|--file FILE) [--workspace-id ID] [--revision N]` | Atomically replace one workflow; the path identity must match `workflow.id`. Same defaults. |
 | `workflow-delete WORKFLOW_ID [--workspace-id ID] [--revision N]` | Delete one workflow using optimistic concurrency and a retry-safe request ID. Same defaults. |
 | `workflow-templates` / `workflow-template TEMPLATE_ID` | List the templates a new flow starts from (id, name, what each makes, step count), or read one as a complete placed workflow: fill the brief's `text` (and an asset step's `assetId`), then pass it to `workflow-create`. Neither needs a revision. |
 | `workflow-preflight WORKFLOW_ID [--workspace-id ID] [--revision N]` | Check required inputs, assets, outputs, and deterministic node order without mutating the workflow (the same defaults as the mutations). Answers `ready` (the graph, with `issues`), `executable` with `blockers` (the account: `connection_required` or `connection_expired`, each with a `recovery` naming `cr8 connect --open`), and `steps[]` with each model step's `resolvedPrompt`, the exact text a run sends. |
-| `workflow-run WORKFLOW_ID [--workspace-id ID] [--revision N] [--request-id ID] [--from NODE_ID] [--detach] [--full]` | Execute that exact ready revision (by default the current one) through the media service. The answer is compact: `status`, `runId`, `workflowId`, `workflowRevision`, `failedNodeId` when it failed, `steps[]` (`nodeId`, `status`, and a `message` for a failed or a kept step) and `outputs[]` (`outputNodeId`, `file`, the workspace-relative path the output is kept at such as `designs/launch/assets/sha256-….webp`, and `src`, its runtime path). `--full` prints the whole answer with every step's artifact and provenance. `--from NODE_ID` starts at one step: it and every step after it run, and a model step before it keeps what the flow last made for it. Reuse the request ID only to recover the same run. |
+| `workflow-run WORKFLOW_ID [--workspace-id ID] [--revision N] [--request-id ID] [--from NODE_ID \| --node NODE_ID] [--detach] [--full]` | Execute that exact ready revision (by default the current one) through the media service. The answer is compact: `status`, `runId`, `workflowId`, `workflowRevision`, `failedNodeId` when it failed, `steps[]` (`nodeId`, `status`, and a `message` for a failed or a kept step) and `outputs[]` (`outputNodeId` and `src`, the managed cloud path for a generated output; `file` is included only for an output already stored in the project). Generated Flow outputs stay on their cloud paths until `workflow-place` copies an image or SVG into the design. `--full` prints the whole answer with every step's artifact and provenance. `--node NODE_ID` runs only that generation node using available upstream results, refuses missing upstream generations without spending, and returns the node’s own output. `--from NODE_ID` starts at one step: it and every step after it run, and a model step before it keeps what the flow last made for it. Reuse the request ID only to recover the same run. |
 | `workflow-run-status WORKFLOW_ID --request-id ID [--workspace-id ID] [--full]` | Where a run started with `--detach` is: the steps visited so far while it runs, or its answer once it ended, compact like `workflow-run`'s unless `--full`. |
 | `workflow-place WORKFLOW_ID [--output NODE_ID] [--artboard FRAME_ID] [--name NAME] [--fit cover\|contain] [--behind\|--on-top] [--all]` | Put what the flow last made on the design: the named output of its last completed run (the first when none is named) becomes a project asset with its generation provenance and an image layer in the named root artboard, or filling a new artboard to the right of everything, named after the output (or `--name`). In a named artboard the layer is centred at up to 80 % of the artboard's width and height, never enlarged; `--fit cover` fills the artboard (the image cropped to it) and `--fit contain` scales it to the largest size that fits inside, centred. Answers `assetId`, `nodeId`, `artboardId`, `created`, the design's `sequence` and `file`, the workspace-relative path the asset is kept at. `--all` places every output of the run on one new review artboard named `<flow name> · review` (or `--name`), side by side at one height with a small gap, to the right of everything, and answers `artboardId`, `created`, the board's `x`, `y`, `width` and `height` (so an agent lays its own artboards clear of it), `sequence` and `placed[]` (`outputNodeId`, `assetId`, `nodeId`, `file`), with `skipped[]` for clips. Idempotent: an output already placed there, or a review board of that name already holding every output, answers `created: false` and adds nothing; an asset the project holds is shown again, never copied twice. A clip is refused on its own, since it stays in Flows. A `--fit cover` placement goes behind what the artboard already holds (it is the background); `--behind` does so for any placement and `--on-top` keeps a cover placement above. |
 | `exec --command JSON` | Send a command object from the published schema. |
@@ -231,7 +233,7 @@ Exit codes are `1` for invalid/unavailable/rejected work, `2` for diagnostics, `
 
 ## Media
 
-There are two ways to make media. `generate` runs a product preset (`auto`, `fast`, `quality`, `vector`) and places the output on the canvas in one call; CR8 chooses the model behind it. `generate --model ID` with an image or vector model id from `media-models` runs that model and places its output the same way; a model that takes no prompt, such as an upscaler, needs `--node` and no `--prompt`. `media-create --model ID` runs any model of the registry, including direct provider bindings and the video and enhancement models; it prints the job envelope (`status`, `result.outputs` on their cloud paths, or `error`), and the output reaches the canvas through `media-materialize --src` followed by `edit` with `insert_node`. Prefer `generate` for a quick artboard from a prompt or a reference, and `media-create` when the model, its parameters or its category matter. `media-models` lists the registry as summaries: each model's id, its task (`generate`, `edit`, `enhance`, `utility`), whether an image is `required` or `optional`, the `choices` it narrows (the ratios, durations, resolutions and scales it makes where fewer than the vocabulary's, and whether a seed may be set) and one line; `--full` prints each model's `inputSchema` and metadata instead. `media-model ID` prints one model in full, and `media-job ID` reads a job back. The registry spans image generation, editing, enhancement and utilities, vector generation and video generation; a video job's output is an MP4 on its cloud path. Model inputs use the model's own vocabulary (`prompt`, `count`, `aspect_ratio`, `image`, `seed`) as published in the schema; a project asset is named in the `image` field as `{ "assetId", "src" }` and ingested before the job starts.
+There are two ways to make media. `generate` runs a product preset (`auto`, `fast`, `quality`, `vector`) and places the output on the canvas in one call; CR8 chooses the model behind it. `generate --model ID` with an image or vector model id from `media-models` runs that model and places its output the same way; a model that takes no prompt, such as an upscaler, needs `--node` and no `--prompt`. `media-create --model ID` runs any model of the registry, including direct provider bindings and the video and enhancement models; it prints the job envelope (`status`, `result.outputs` on their cloud paths, or `error`), and an image or SVG reaches the canvas through `place --job JOB_ID`, which copies its bytes, registers the asset and places its layer in one retryable transaction. Prefer `generate` for a quick artboard from a prompt or a reference, and `media-create` when the model, its parameters or its category matter. `media-models` lists the registry as summaries: each model's id, its task (`generate`, `edit`, `enhance`, `utility`), whether an image is `required` or `optional`, the `choices` it narrows (the ratios, durations, resolutions and scales it makes where fewer than the vocabulary's, and whether a seed may be set) and one line; `--full` prints each model's `inputSchema` and metadata instead. `media-model ID` prints one model in full, and `media-job ID` reads a job back. The registry spans image generation, editing, enhancement and utilities, vector generation and video generation; a video job's output is an MP4 on its cloud path. Model inputs use the model's own vocabulary (`prompt`, `count`, `aspect_ratio`, `image`, `seed`) as published in the schema; a project asset is named in the `image` field as `{ "assetId", "src" }` and ingested before the job starts.
 
 The CLI calls the server-side provider-neutral media boundary through the running project process. Connect the account once, from the canvas, with `cr8 connect --open`, or through an agent's `canvas_connect`; CLI and MCP requests then share the short-lived, device-bound grant kept in your configuration directory (see [install](install.md#accounts-and-ai-media)), whatever project is open. A generation the account blocks answers `connection_required` or `connection_expired`, with the recovery in `details.blockers`. `CR8_MEDIA_API_URL` and `CR8_MEDIA_API_TOKEN` remain operator-only overrides for private deployments, not user installation settings.
 

package/docs/user/desktop.md

@@ -1,15 +1,15 @@
-# CR8 desktop wrapper
+# CR8 desktop
 
 The desktop build is an optional window around the same loopback CR8 runtime used by the browser, CLI, and MCP integration. It does not own another document database, copy project files into an Electron profile, or replace the agent-facing installation. The browser, CLI, and MCP installation remain fully usable without Electron.
 
 ## Runtime model
 
 1. The main process resolves one explicit workspace and design project.
-2. It spawns `cr8 serve` from the bundled runtime on an ephemeral loopback port, or attaches to a runtime that already holds the project's lease (the lease records the listener port).
+2. It spawns `cr8 serve --mcp --managed` from the bundled runtime on an ephemeral loopback port, or attaches to a runtime that already holds the project's lease (the lease records the listener port).
 3. Electron loads that exact `http://127.0.0.1:<port>` URL. Opening the printed URL in a normal browser shows the same running session. On macOS the window hides its title bar and the page's own top bar is the drag region, with room for the traffic lights; other platforms keep their native frame.
-4. The project remains the normal portable `cr8.json`, optional `flows.json`, and content-addressed `assets/`. Closing the window drains the loopback server and releases the project lease.
+4. The project remains the normal portable `cr8.json`, optional `flows.json`, and content-addressed `assets/`. Closing a window releases its presence. A managed runtime stays alive while a desktop, launcher-backed agent or browser is connected, and closes after a short grace period once the last client leaves. An externally owned runtime remains controlled by its original host.
 
-The wrapper has no preload bridge. Renderer Node integration and webviews are disabled, context isolation and Chromium sandboxing are enabled, and permissions are denied. Project switching updates the one trusted loopback origin to the runtime's exact active URL; stale or unrelated loopback ports remain blocked. Navigation and popup creation stay inside that origin, except that an AI-media connection URL on the configured HTTPS account origin is opened in the system browser while the CR8 window remains local.
+The canvas has no preload bridge. A bundled setup view inside that same native window has a narrow, validated IPC bridge for choosing folders and configuring agent connections; it is never exposed to the editor, MCP App or account hub. Renderer Node integration and webviews are disabled, context isolation and Chromium sandboxing are enabled, and permissions are denied. Project switching updates the one trusted loopback origin to the runtime's exact active URL; stale or unrelated loopback ports remain blocked. Navigation and popup creation stay inside that origin, except that an AI-media connection URL on the configured HTTPS account origin is opened in the system browser while the CR8 window remains local.
 
 ## Selecting a project
 
@@ -21,9 +21,39 @@ The desktop executable accepts:
 --project <path>         Workspace-relative directory containing cr8.json
 ```
 
-The equivalent environment variables are `CR8_CWD`, `CR8_WORKSPACE`, and `CR8_PROJECT`. Command-line values win. Any other switch (for example `--remote-debugging-port=9333` or `--disable-gpu`) is left to Electron and Chromium. If `--project` is omitted, CR8 opens the only valid project it discovers. It fails safely when none or several exist instead of guessing or using a global recent-file database.
+The equivalent environment variables are `CR8_CWD`, `CR8_WORKSPACE`, and `CR8_PROJECT`. Command-line values win. Any other switch (for example `--remote-debugging-port=9333` or `--disable-gpu`) is left to Electron and Chromium. If `--project` is omitted and the workspace itself is not a project, CR8 offers Create/Open instead of guessing among designs or using a global recent-file database.
 
-The desktop process owns the project's single-writer lease while it is open. CLI agent commands can target the loopback URL printed by the process. Design and Flows use the same workspace identity and runtime, while scene sequence and workflow revision remain separate. Starting another local runtime for the same project correctly fails with `project_locked`, naming the desktop process and its port; close the desktop window before opening that project in another MCP process. **File → Open Project Folder…** relaunches the window on another folder. When the window attaches to a running runtime, it trusts the account origin that runtime reports on `/health`; a loopback `http://127.0.0.1` account hub is accepted while developing the hub.
+The local runtime owns the project's single-writer lease. CLI agent commands can target its loopback URL. Design and Flows share that runtime while scene sequence and workflow revision remain independent.
+
+## First launch and agent setup
+
+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 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`.
+
+The launcher lives in desktop-owned application data under `agent/` and is refreshed when the app opens, so normal app replacement preserves host configuration. It launches the bundled engine with the desktop window closed, joining a compatible live project runtime or starting one lazily. A moved app is repaired by opening it at its new location. Restart active agent sessions to adopt an updated runtime; version mismatch fails with an actionable message rather than replacing a running writer. The npm/plugin install remains independent. Existing externally owned or older stdio sessions keep their original agent connection and lifetime.
+
+**File → New Canvas…** opens the creation surface; **File → Open Project Folder…** opens an existing project. Setup preferences record completion, owned connections, and the explicitly chosen workspace folder. They never store project contents or an auto-open last design. Opening another project reuses the native window without relaunching the app. An attached runtime supplies the trusted account origin through `/health`.
+
+**Settings → Account** shows the device’s actual media identity, connection status, sign-in/reconnect, account management, and device sign-out. It works before any design is open through the bundled runtime’s canonical media connection endpoints. Account sign-in opens the trusted account hub in the browser. Credentials stay in the runtime; Settings receives only the public status. Local editing remains available while signed out. No usage or billing values are invented.
+
+## Canvas, Flows and Settings
+
+The desktop has one workspace dashboard with exactly **Canvas**, **Flows**, and **Settings** in its sidebar. There is no Home section. **Canvas** lists recent canvas files with real artwork thumbnails, search, and explicit workspace selection. **Flows** lists recent saved flows across those same project files, with separate Recent flows and Templates tabs. Both sections work before an editor is open and read the canonical bounded, symlink-safe project catalog without starting a runtime or maintaining another file database.
+
+Click a file to open its canvas, or a saved flow to open its owning project and graph. A template asks whether to use an existing project or create a named project file, then opens an editable draft. Save commits it to the project’s `flows.json`. The editor occupies the full window without the dashboard sidebar. **Files**, **Flows**, and **Settings** controls return to the respective dashboard section; **Back to editor** resumes the mounted editor without losing work.
+
+Settings is a page in this dashboard, never a modal over the canvas. A normal launch after onboarding returns to the Canvas section in the chosen workspace without auto-opening a last document. Explicit `--project` launches still open that canvas directly. Browser and MCP App product names are **Canvas** and **Flows**; protocol identifiers remain compatible.
+
+## Manual MCP and command-line setup
+
+**Settings → Agents · MCP → Manual MCP setup** shows selectable, syntax-highlighted JSON using the same stable launcher as Connect. Merge that entry into the client's user settings; different client formats use the same command and arguments. The per-agent **Copy setup prompt** handles those host-specific instructions. Copying does not modify a host. **Refresh connections** checks changes made outside CR8. If a client cannot provide its project folder, add an explicit `--workspace /absolute/path` in its configuration.
+
+**Settings → Command line** provides a copyable invocation of the full bundled CLI under the desktop’s application data `bin/cr8` (`bin/cr8.cmd` on Windows, shown for PowerShell). The command initially runs `--help`; replace that argument with a CR8 command and target a workspace explicitly when needed. It works without system Node or npm and follows app replacement, just like the MCP launcher. CR8 does not edit shell profiles or add itself to PATH. The independent `npx @zvada/cr8` route remains available and never installs Electron.
 
 ## Development and packaging
 
@@ -40,4 +70,18 @@ Run the built wrapper with Electron and explicit project arguments:
 npx electron dist/desktop/main.mjs --workspace "$PWD" --project designs/example
 ```
 
-`packages/desktop/electron-builder.yml` packages the bundled main process and unpacks `dist/cr8.mjs` beside the asar so Node can run it. `npm run build:desktop` builds the runtime and main process before invoking Electron Builder. The release workflow signs and notarizes the macOS build when the Apple secrets are configured, ships Windows unsigned until a certificate is chosen, and attaches every installer to the GitHub release. The app does not update itself: a new version is a new download, and the runtime inside it tells you when a newer CR8 exists.
+`packages/desktop/electron-builder.yml` packages the bundled main process and unpacks `dist/cr8.mjs` beside the asar so Node can run it. `npm run build:desktop` builds the runtime and main process before invoking Electron Builder. The release workflow signs and notarizes the macOS build when the Apple secrets are configured, ships Windows unsigned until a certificate is chosen, and attaches every installer to the GitHub release. Local packaging always passes `--publish never`. The app does not check for or install desktop updates: replace it with a newer download and restart. npm updates affect only the npm installation, not this app. GitHub downloads currently require access to the private repository.
+
+## Verification
+
+`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 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/feedback.md

@@ -1,6 +1,10 @@
 # Feedback for CR8
 
-CR8 uses [Hivenet](https://hivenet.app) as its agent feedback channel. This is for actionable product reports from agents or people working on CR8 and from agents using the installed CLI, MCP server, MCP App, or docs.
+Use the feedback button in the bottom-right corner of any CR8 screen to suggest a feature, report a problem, or share other feedback. The same form is available in the local browser, desktop, account hub, onboarding and embedded MCP App, without requiring sign-in or an open project. Closing the form preserves its draft in the current view; reloading the page clears it.
+
+Only clicking **Send feedback** sends a report to HiveNet. Human reports are marked `author: "human"` and contain the message, feedback type, CR8 version and an opaque submission ID. They include no account identity, project content, screenshots, paths, cookies or referrer. Sending requires internet access; failures preserve the draft and an unchanged retry reuses its submission ID to prevent duplicate reports. There is no background outbox or automatic retry.
+
+The CLI and MCP also send actionable product reports to [HiveNet](https://hivenet.app), for agents or people working on CR8 or using its installed tools and docs.
 
 Feedback is always an explicit external write. An agent must state what it is sending before it submits; CR8 never reports usage, failures, prompts, canvas content, or ambient context automatically.
 

package/docs/user/install.md

@@ -3,47 +3,52 @@
 CR8 is one local process. It serves the Design and Flows workspace to your browser, speaks MCP to an agent, and answers a JSON CLI. It creates no daemon and no document until you ask for one. Projects live in your repositories; the hosted account hub only signs you in for AI media.
 
 > [!IMPORTANT]
-> CR8 is proprietary software under the terms in the repository's `LICENSE`: install and use it, do not copy, modify or redistribute it. Before the first release the npm package only holds the name and the binaries are not published, so collaborators install from source (below); the npm and binary sections describe what the release workflow produces.
+> CR8 is proprietary software under the terms in the repository's `LICENSE`: install and use it, do not copy, modify or redistribute it.
 
-## From source (today)
+## From npm
 
-You need Git and Node.js 20.19 or newer.
-
-```bash
-git clone https://github.com/zvadaadam/baby-canva.git "$HOME/.cr8"
-cd "$HOME/.cr8"
-npm ci && npm run build:package
-```
-
-That builds `dist/cr8.mjs`: the MCP server, the CLI, the browser workspace and the MCP App in one file. Put it on your path however you like; the rest of this page writes `cr8` and means `node "$HOME/.cr8/dist/cr8.mjs"`.
-
-## From npm (after the first release)
+Requires Node.js 20.19 or newer; use a currently supported Node LTS release. This route is public and does not require access to the source repository.
 
 ```bash
 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`.
+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
 
-## A release binary (after the first release)
+The source repository is private: its GitHub release pages and assets require repository access. Publishing a release there does **not** make the downloads public. Until a public download channel is available, use npm on other computers.
 
-Each GitHub release carries one executable per platform, a `SHA256SUMS.txt` and a build-provenance attestation:
+For people with repository access, each release carries one executable per platform and a `SHA256SUMS.txt`:
 
 | File | For |
 | --- | --- |
-| `cr8-darwin-arm64.zip` | Apple silicon Macs (signed and notarized) |
-| `cr8-darwin-x64.zip` | Intel Macs (signed and notarized) |
+| `cr8-darwin-arm64-unsigned.zip` | Apple silicon Macs |
+| `cr8-darwin-x64-unsigned.zip` | Intel Macs |
 | `cr8-linux-x64.tar.gz`, `cr8-linux-arm64.tar.gz` | Linux |
 | `cr8-windows-x64.zip` | Windows |
 
 Check the download before you run it, then start:
 
 ```bash
-shasum -a 256 -c SHA256SUMS.txt --ignore-missing
-unzip cr8-darwin-arm64.zip && ./cr8-darwin-arm64 start designs/first
+shasum -a 256 cr8-darwin-arm64-unsigned.zip
+# Compare the printed hash with this archive’s entry in SHA256SUMS.txt.
+unzip cr8-darwin-arm64-unsigned.zip && ./cr8-darwin-arm64 start designs/first
+```
+
+The binary needs no Node.js. The macOS archives end in `-unsigned` today, because no signing certificate is configured yet; Gatekeeper refuses them until you allow them in System Settings, and a signed release is the fix, not a habit. They lose the suffix once a certificate is set. GitHub attests a build only for a public repository, so while this one is private a release ships its checksums alone.
+
+## From source
+
+You need repository access, Git and Node.js 20.19 or newer.
+
+```bash
+git clone https://github.com/zvadaadam/baby-canva.git "$HOME/.cr8"
+cd "$HOME/.cr8"
+npm ci && npm run build:package
 ```
 
-The binary needs no Node.js. A macOS archive whose name ends in `-unsigned` was built without the signing certificate; Gatekeeper will refuse it until you allow it in System Settings, and a signed release is the fix, not a habit.
+That builds `dist/cr8.mjs`: the MCP server, the CLI, the browser workspace and the MCP App in one file. Put it on your path however you like; installed this way, `cr8` on this page means `node "$HOME/.cr8/dist/cr8.mjs"`.
 
 ## Start a project
 
@@ -57,31 +62,75 @@ cr8 start --no-open       # serves without opening a browser; the answer carries
 
 ## Add it to an agent
 
-The agent host owns the process: it starts CR8 when a tool is called 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 -- cr8 mcp
+codex mcp add cr8 -- npx -y @zvada/cr8@0.3.1 mcp-connect
 ```
 
-Codex passes the workspace through MCP roots. 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 -- cr8 mcp
+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`.
+
+**Manual setup.** Add this to the host's user-level MCP settings, adapting the syntax for hosts such as Codex that use TOML:
+
+```json
+{
+  "mcpServers": {
+    "cr8": {
+      "command": "npx",
+      "args": ["--yes", "@zvada/cr8@0.3.1", "mcp-connect"]
+    }
+  }
+}
 ```
 
-Claude Code exposes its project directory to the server. Once the package is public the plugin marketplace is the shorter road: `/plugin marketplace add zvadaadam/baby-canva`, then `/plugin install cr8`.
+Keep the launch directory dynamic. CR8 follows `CLAUDE_PROJECT_DIR` or the host's launch directory, joins that workspace's unique compatible runtime, and waits for an explicit file choice when none is running. Clients that cannot supply their project folder can add `--workspace /absolute/path/to/workspace`; multiple live runtimes in that folder require an explicit `--project designs/name`. Installation creates no design files. The npm version is pinned to match the running editor and bundled guidance; update the saved version when upgrading CR8.
 
-**Any host, per project.** The repository's `.mcp.json` starts the server with `--workspace .`; copy it into a project to pin CR8 to that repository. The Codex plugin carries its own server file, `.codex-plugin/mcp.json`, which runs the bundled runtime from wherever the plugin was installed.
+The repository's `.mcp.json` is for a built source checkout; copying it alone into another project will not install its `dist/cr8.mjs`. The installable Claude and Codex plugins use the same `mcp-connect` behavior. The Codex plugin resolves its bundled runtime from the plugin's installation directory.
 
 Use `/mcp` to diagnose a host, and `codex mcp remove cr8` or `claude mcp remove cr8` to take it out.
 
+## 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 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.
+
+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
 
-Three skills ship with CR8, in the package's `skills/` directory: `cr8-design` for design work on a canvas, `cr8-flows` for building and running flows, and `cr8-feedback` for reporting. Each is a `SKILL.md` with an `agents/openai.yaml` beside it. The same text is embedded in the runtime: the MCP server hands it out through `canvas_skills` and `canvas_skill`, and the CLI through `cr8 skills get NAME`, so what an agent reads always matches the version it runs. Each is a short `SKILL.md` contract plus a `references/` folder the contract lists at its end (the flows skill's `references/models.md` is the guide to which model does which job); the hosts read the folder whole, and `cr8 skills get NAME --path references/<file>` prints one reference.
+Three skills ship with CR8, in the package's `skills/` directory: `cr8-design` for design work on a canvas, `cr8-flows` for building and running flows, and `cr8-feedback` for reporting. Each is a `SKILL.md` with an `agents/openai.yaml` beside it. The same text is embedded in the runtime: the MCP server hands it out through `list_skills` and `read_skill`, or the Skills extension (`skills/list`, `skills/get` and `resources/read`), and the CLI through `cr8 skills get NAME`, so what an agent reads always matches the version it runs. Each is a short `SKILL.md` contract plus a `references/` folder the contract lists at its end (the flows skill's `references/models.md` is the guide to which model does which job); the hosts read the folder whole, and `cr8 skills get NAME --path references/<file>` prints one reference.
 
 To put them where the hosts look:
 
@@ -115,7 +164,7 @@ your-repository/
         ├── flows.json            # created after the first saved flow
         ├── flow-runs.json        # what each flow last made, created after the first run
         ├── assets/
-        │   └── sha256-….webp     # imports, Design generations and flow outputs alike
+        │   └── sha256-….webp     # imports, Design generations and placed Flow outputs
         ├── .gitignore
         └── .cr8/
             ├── session.json
@@ -125,11 +174,11 @@ your-repository/
 
 - `cr8.json` is the strict, versioned, human-readable project envelope.
 - `flows.json` holds the project's flows, with its own revision because flow edits are not scene history.
-- `flow-runs.json` holds the last run of each flow: how it ended and what it made, by the paths of the copies in `assets/`. The Flows home and the graph read it, on this computer or in a clone.
-- `assets/` holds immutable content-addressed imports, Design generations and flow outputs. Documents store relative `assets/…` paths, so the directory survives moves and clones.
+- `flow-runs.json` holds the last run of each flow: how it ended and what it made, including managed cloud paths for generated outputs. The Flows library and graph read this metadata; viewing cloud outputs requires network access and a connected CR8 account.
+- `assets/` holds immutable content-addressed imports, Design generations and Flow outputs explicitly placed into the design. Scene documents store relative `assets/…` paths, so saved designs survive moves and clones and render offline.
 - `.cr8/` holds disposable coordination state. The generated `.gitignore` excludes it.
 
-Commit `cr8.json`, `flows.json` and `flow-runs.json` when present, `assets/` and `.gitignore` when you want Git history: a clone opens with every design, every flow and what each flow last made. Nothing global decides which repository an agent edits.
+Commit `cr8.json`, `flows.json` and `flow-runs.json` when present, `assets/` and `.gitignore` when you want Git history: a clone contains the saved designs, flows and their last-run metadata. Unplaced generated Flow outputs remain in the cloud. Nothing global decides which repository an agent edits.
 
 Older projects that still carry `.relay/session.json` migrate on open; the new file is written beside the old one, which is preserved.
 
@@ -145,7 +194,7 @@ Three roads ask for the account, and all end on the same page:
 - The CLI: `cr8 connect --open` prints the sign-in URL, opens it and waits until you have signed in; `cr8 status` reports the connection as `mediaConnection`, and `cr8 disconnect` forgets the grant.
 - An agent: when a generation answers that the account is not connected, it calls `canvas_connect` and gives you the URL to open. It never asks for your credentials.
 
-Every generation is recorded in the media Worker's catalog with its provider, model, prompt, parameters and source. A Design generation is downloaded, validated and written into the project's asset directory before the scene may reference it, and a completed flow run's images and SVGs are copied there the same way, so what a flow made travels with the project; a clip stays on its cloud path. Losing the network stops new generations; it does not stop a design from opening.
+Every generation is recorded in the media Worker's catalog with its provider, model, prompt, parameters and source. A Design generation is downloaded, validated and written into the project's asset directory before the scene may reference it, while Flow outputs stay on managed cloud paths until Add to Design copies an image or SVG into the project. Clips stay in Flows. Losing the network stops new generations; it does not stop a design from opening.
 
 ## Updating
 
@@ -155,6 +204,6 @@ From npm: run `npx @zvada/cr8@latest` or `npm install -g @zvada/cr8@latest`. Fro
 cd "$HOME/.cr8" && git pull --ff-only && npm ci && npm run build:package
 ```
 
-Restart the agent host afterwards. Projects live in their own repositories, so an update cannot touch them. The desktop app does not update itself; see the [desktop wrapper](desktop.md).
+The MCP examples above pin a version: installing a newer global CLI does not update those pins. Remove and re-add that host entry with the chosen version, then restart the agent session. Update a plugin through its host and refresh any separately copied skills with that version’s `cr8 skills install --force`. Projects stay outside the installation directory; opening one in a newer runtime can still migrate its format, so keep a project backup before major upgrades. The desktop app does not update itself; see the [desktop wrapper](desktop.md).
 
 See the [local-first decision](../decisions/2026-08-15-local-first-install.md), the [MCP App](mcp.md), the [CLI guide](cli.md) and the [desktop wrapper](desktop.md). Releases themselves are described in [the release runbook](../operations/release.md).