pmx-canvas 0.7.2 → 0.8.0

package/dist/types/server/context-reads.d.ts

@@ -22,14 +22,29 @@ export interface ContextRead {
     agentId: string | null;
     pinnedNodeIds: string[];
     deliveredNodeIds: string[];
+    /** Every node on the read board whose content was delivered, with its content revision at read time. */
+    readNodes: Record<string, number>;
     bytes: number;
     /** The board open when the read happened (null on Home). */
     boardId: string | null;
 }
-export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId'> & {
+export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId' | 'readNodes'> & {
     /** Explicit read target, captured before asynchronous formatting/proxy work. */
     boardId?: string | null;
+    /** Ids of every serialized node in what the reader received; the server keeps those on the board. */
+    readNodeIds?: string[];
 };
+/** One node's read state on a board: the latest agent read that delivered its content. */
+export interface NodeReadStatus {
+    nodeId: string;
+    lastReadAt: string;
+    /** Who read it: consumer, else agent id, else transport label. */
+    lastReadBy: string;
+    /** The node's content revision in that read; newer current revision means "changed since read". */
+    readRevision: number;
+    /** How many retained agent reads delivered its content. */
+    readCount: number;
+}
 export interface ContextReadConsumerSummary {
     consumer: string;
     reads: number;
@@ -39,14 +54,22 @@ export interface ContextReadConsumerSummary {
     resources: Record<string, number>;
 }
 /**
- * Pinned nodes whose serialized node (an object carrying `"id": "<id>"`) is in
- * what the reader received. A bare id list, a title, or a clipped-off node does
- * not count — the agent got the pin's name, not its content.
+ * Ids of every serialized node (an object carrying `"id": "<id>"`, or a
+ * `nodeId` with its text) in what the reader received. A bare id list, a
+ * title, or a clipped-off node does not count — the agent got the node's
+ * name, not its content. Non-node ids (edges, intents) are dropped by the
+ * caller against the board's nodes.
  */
+export declare function deliveredIds(payloadText: string): Set<string>;
+/** Pinned nodes whose content is in what the reader received (see `deliveredIds`). */
 export declare function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[];
-export declare function contextReadFromPayload(base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes'>, payload: unknown): ContextReadInput;
-export declare const CONTEXT_READS_SCHEMA_SQL = "\n  CREATE TABLE IF NOT EXISTS context_reads (\n    seq INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    at TEXT NOT NULL,\n    channel TEXT NOT NULL,\n    resource TEXT NOT NULL,\n    source TEXT NOT NULL,\n    consumer TEXT,\n    agent_id TEXT,\n    pinned_node_ids TEXT NOT NULL DEFAULT '[]',\n    delivered_node_ids TEXT NOT NULL DEFAULT '[]',\n    bytes INTEGER NOT NULL DEFAULT 0,\n    board_id TEXT\n  );\n";
-export declare function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null): ContextRead;
+export declare function contextReadFromPayload(base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes' | 'readNodeIds'>, payload: unknown): ContextReadInput;
+export declare const CONTEXT_READS_SCHEMA_SQL = "\n  CREATE TABLE IF NOT EXISTS context_reads (\n    seq INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    at TEXT NOT NULL,\n    channel TEXT NOT NULL,\n    resource TEXT NOT NULL,\n    source TEXT NOT NULL,\n    consumer TEXT,\n    agent_id TEXT,\n    pinned_node_ids TEXT NOT NULL DEFAULT '[]',\n    delivered_node_ids TEXT NOT NULL DEFAULT '[]',\n    bytes INTEGER NOT NULL DEFAULT 0,\n    board_id TEXT,\n    read_nodes TEXT NOT NULL DEFAULT '{}'\n  );\n";
+export declare function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null, readNodes?: Record<string, number>): ContextRead;
+/** Per node on a board, the latest agent read that delivered its content (newest row wins). */
+export declare function loadNodeReadStatusFromDB(db: Database, boardId: string): NodeReadStatus[];
+/** Every node on a board whose content an agent read at or after `since` (ISO). */
+export declare function loadReadNodeIdsSince(db: Database, boardId: string, since: string): string[];
 /** Newest first. The summary covers every retained row, not just the returned page. */
 export declare function loadContextReadsFromDB(db: Database, limit?: number): {
     reads: ContextRead[];

package/dist/types/server/index.d.ts

@@ -42,6 +42,8 @@ export declare class PmxCanvas extends EventEmitter {
     start(options?: {
         open?: boolean;
         automationWebView?: boolean | CanvasAutomationWebViewOptions;
+        /** Embedded startup must not launch external MCP backends from saved nodes. */
+        allowExternalMcp?: boolean;
         /**
          * Bind a nearby free port when the preferred one is taken instead of
          * failing. Default false (an explicit SDK port is honored exactly); the
@@ -293,6 +295,8 @@ export declare class PmxCanvas extends EventEmitter {
     restoreBackup(file: string): Promise<void>;
     /** The context read log: which canvas context each agent read and which pinned nodes reached it. */
     getContextReads(limit?: number): ReturnType<typeof canvasState.getContextReads>;
+    /** Per node on a board: when an agent last read its content, who, and the content revision it read. */
+    getNodeReadStatus(board?: string): ReturnType<typeof canvasState.getNodeReadStatus>;
     listWorkItems(): PmxAxWorkItem[];
     addWorkItem(input: {
         title: string;
@@ -519,7 +523,8 @@ export declare class PmxCanvas extends EventEmitter {
         applied: number;
         skipped: number;
     };
-    setContextPins(nodeIds: string[], mode?: 'set' | 'add' | 'remove'): {
+    /** `reason` is kept with newly pinned nodes and shown to the human on hover. */
+    setContextPins(nodeIds: string[], mode?: 'set' | 'add' | 'remove', reason?: string): {
         count: number;
         nodeIds: string[];
     };

package/dist/types/server/mcp-app-runtime.d.ts

@@ -1,5 +1,6 @@
 import type { CallToolResult, ListPromptsResult, ListResourcesResult, ListResourceTemplatesResult, ListToolsResult, ReadResourceResult, Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { McpUiResourceMeta } from '@modelcontextprotocol/ext-apps';
+export declare function withoutExternalMcp<T>(run: () => T): T;
 export interface ExternalMcpHttpTransportConfig {
     type: 'http';
     url: string;

package/dist/types/server/operations/http.d.ts

@@ -1,3 +1,4 @@
+export declare function matchOperationPath(template: string, pathname: string): Record<string, string> | null;
 /**
  * Shared body reader: preserves the parsed JSON value as-is (object, array,
  * or primitive) — per-op `readInput` decides what to do with non-object
@@ -5,4 +6,5 @@
  * parse is a 400 (OperationError), never a silent empty input.
  */
 export declare function readJsonValue(req: Request): Promise<unknown>;
+export declare function readOperationInput(req: Request, params: Record<string, string>, url: URL): Promise<Record<string, unknown>>;
 export declare function dispatchOperationRoute(req: Request, url: URL): Promise<Response | null>;

package/dist/types/server/operations/invoker.d.ts

@@ -9,18 +9,20 @@ export interface OperationInvoker {
 export declare function agentSourceLabel(fallback: string): string;
 /** Runs operations in-process against the shared canvasState singleton. */
 export declare class LocalOperationInvoker implements OperationInvoker {
+    private readonly allowExternalMcp;
     private readonly source;
     private readonly proxiedRead;
     /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
-    constructor(source?: string);
+    constructor(source?: string, allowExternalMcp?: boolean);
     invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
 }
 /** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
 export declare class HttpOperationInvoker implements OperationInvoker {
+    private readonly allowExternalMcp;
     private readonly baseUrl;
     private readonly source;
     private readonly proxiedRead;
     /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
-    constructor(baseUrl: string, source?: string);
+    constructor(baseUrl: string, source?: string, allowExternalMcp?: boolean);
     invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown>;
 }

package/dist/types/server/operations/ops/nodes.d.ts

@@ -11,12 +11,6 @@ export declare function isRecord(value: unknown): value is Record<string, unknow
 export declare function pickFiniteNumber(record: Record<string, unknown>, key: string): number | undefined;
 export declare function getRecord(value: unknown): Record<string, unknown> | undefined;
 export declare function pickPositiveNumber(record: Record<string, unknown>, key: string): number | undefined;
-export declare function resolveCreateGeometry(body: Record<string, unknown>): {
-    x?: number;
-    y?: number;
-    width?: number;
-    height?: number;
-};
 export declare function setGroupChildrenFromApi(groupId: string, childIds: string[]): boolean;
 export declare function nodeAppSessionId(node: CanvasNodeState | undefined): string | null;
 export declare function closeNodeAppSession(node: CanvasNodeState | undefined): void;

package/dist/types/server/server.d.ts

@@ -108,6 +108,7 @@ export interface CanvasServerOptions {
     workspaceRoot?: string;
     autoOpenBrowser?: boolean;
     allowPortFallback?: boolean;
+    allowExternalMcp?: boolean;
 }
 export declare function startCanvasServer(options?: CanvasServerOptions): string | null;
 export declare function stopCanvasServer(): void;

package/dist/types/server/spatial-analysis.d.ts

@@ -68,6 +68,8 @@ export interface SpatialContext {
     }[];
     annotations: SpatialAnnotationContext[];
 }
+/** Euclidean distance between two node centers */
+export declare function centerDistance(a: CanvasNodeState, b: CanvasNodeState): number;
 /**
  * Detect proximity clusters using single-linkage clustering.
  * Two nodes are "close" if their edge-to-edge gap is within the threshold.

package/dist/types/shared/agent-context.d.ts

@@ -0,0 +1,22 @@
+import type { CanvasNodeState } from '../server/canvas-state.js';
+export interface AgentContextNode {
+    id: string;
+    type: CanvasNodeState['type'];
+    kind: string;
+    title: string | null;
+    content: string | null;
+    metadata?: Record<string, unknown>;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+interface AgentContextOptions {
+    defaultTextLength?: number;
+    webpageTextLength?: number;
+    includePosition?: boolean;
+}
+export declare function summarizeNodeForAgentContext(node: CanvasNodeState, options?: AgentContextOptions): string;
+export declare function serializeNodeForAgentContext(node: CanvasNodeState, options?: AgentContextOptions): AgentContextNode;
+export declare function buildAgentContextPreamble(nodes: CanvasNodeState[], options?: AgentContextOptions): string;
+export {};

package/dist/types/shared/agent-presence.d.ts

@@ -1,7 +1,7 @@
 /**
- * Agent presence — the contract behind every agent surface in the rail chrome
- * (rail-chrome-v2 phase 2). Shared by server and client so the two cannot
- * drift. See design/rail-chrome-v2/PLAN.md, "Phase 2 contract".
+ * Agent presence — the contract behind every agent surface in the rail chrome.
+ * Shared by server and client so the two cannot drift. See
+ * docs/ax-state-contract.md, "Agent presence (contract)".
  *
  * Presence is DERIVED from feeds that already exist (AX activity ingest,
  * agent-originated mutations) plus an explicit set for adapters with richer
@@ -121,10 +121,3 @@ export declare function externalWriters(presences: readonly AgentPresence[]): Ag
 export declare function estimateTokens(text: string): number;
 /** Chip label per phase — shared by the top-bar chip and the on-canvas cursor chip. */
 export declare function agentPhaseLabel(presence: Pick<AgentPresence, 'phase' | 'detail'>): string;
-/**
- * Stable per-agent identity hue (0-359) from the writer key. Phase colors
- * kept telling the human WHAT an agent is doing while erasing WHO — two
- * thinking agents rendered identically. Identity rides the glyph/border;
- * phase stays on dots and labels.
- */
-export declare function agentIdentityHue(key: string): number;

package/dist/types/shared/ax-surface-protocol.d.ts

@@ -14,6 +14,8 @@ export declare const AX_SURFACE_EMIT_SOURCE = "pmx-canvas-ax";
 export declare const AX_SURFACE_ACK_SOURCE = "pmx-canvas-ax-ack";
 /** Parent→surface pushes (theme updates, live AX state) into html/viewer iframes. */
 export declare const HTML_SURFACE_PUSH_SOURCE = "pmx-canvas-html-node";
+/** Tab-local JSON viewer state handoff, independent of AX capabilities. */
+export declare const JSON_VIEWER_STATE_SOURCE = "pmx-canvas-json-state";
 /** Ext-app boot beacon: the iframe's scripts executed (WebKit watchdog liveness). */
 export declare const EXT_APP_BOOT_BEACON_SOURCE = "pmx-canvas-ext-app-alive";
 /**

package/dist/types/shared/canvas-app.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const CANVAS_APP_URI = "ui://pmx/canvas";
+export declare const CANVAS_APP_WRITE_CONTRACT = "pmx-embedded-workbench-v4";
+export declare const canvasAppSnapshotSchema: z.ZodObject<{
+    boardId: z.ZodNullable<z.ZodString>;
+    boardName: z.ZodString;
+    boards: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    revision: z.ZodString;
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodString;
+        text: z.ZodString;
+        contentRevision: z.ZodNumber;
+        editableContent: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        size: z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    pinnedNodeIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type CanvasAppSnapshot = z.infer<typeof canvasAppSnapshotSchema>;
+/** Share only curated text, never image bytes or the whole board's contents. */
+export declare function canvasAppContext(snapshot: Pick<CanvasAppSnapshot, 'boardId' | 'boardName' | 'pinnedNodeIds'> & {
+    nodes: Pick<CanvasAppSnapshot['nodes'][number], 'id' | 'type' | 'title' | 'text' | 'contentRevision'>[];
+}, selectedIds: string[], focusedIds?: string[]): {
+    boardId: string | null;
+    boardName: string;
+    selectedNodeIds: string[];
+    focusedNodeIds: string[];
+    pinnedNodeIds: string[];
+    nodes: {
+        id: string;
+        type: string;
+        title: string;
+        contentRevision: number;
+        text: string;
+    }[];
+};

package/dist/types/shared/themes.d.ts

@@ -9,7 +9,7 @@
  * theme picker, server validation, and surface documents pick it up from this
  * list.
  */
-export declare const CANVAS_THEMES: readonly ["dark", "light", "high-contrast", "midnight", "sepia", "arctic", "ember", "forest", "volt"];
+export declare const CANVAS_THEMES: readonly ["harbor", "daylight", "high-contrast", "midnight", "sepia", "arctic", "ember", "forest", "volt"];
 export type CanvasThemeName = (typeof CANVAS_THEMES)[number];
 export declare function isCanvasTheme(value: unknown): value is CanvasThemeName;
 export declare function normalizeCanvasThemeName(value: unknown, fallback?: CanvasThemeName): CanvasThemeName;

package/docs/RELEASE.md

@@ -11,6 +11,9 @@ single source of truth for the release dance — see also
 
 1. Land all the changes you want in the release on `main` with green CI.
 2. Bump `package.json` `version`.
+   Run `bun run build:plugin` to update the Agent Plugins manifest, canonical adapter runtime
+   pin, and generated plugin copies. Publish that exact npm runtime version before advertising
+   a GitHub plugin release pinned to it.
 3. Add a `## [X.Y.Z]` block to `CHANGELOG.md`.
 4. Commit, push, wait for `test.yml` green.
 5. `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z` →
@@ -40,9 +43,10 @@ bun run pack:dry-run        # confirms the tarball shape
 do not call `bun x playwright test` directly; it fails before test
 discovery with a `.esm.preflight` loader error (ERR-20260508-001).
 
-The Playwright run includes the `pane-600` project
-(`tests/e2e/reference-pane.pw.ts`): the reference surface, Chromium at
-600 px. Every node type must paint there or the release does not ship.
+The reference cases (`tests/e2e/reference-pane.pw.ts`) run in three
+Playwright projects, `narrow-600`, `middle-1024` and `wide-1920`: the
+workbench lives anywhere from a narrow side pane to a full window. Every
+node type must paint at all three or the release does not ship.
 Embedded WebKit panes (the Copilot app) stay best-effort.
 
 `bun run test:e2e-cli` starts a local server in a fresh temp workspace

package/docs/agent-plugin.md

@@ -0,0 +1,123 @@
+# PMX Canvas agent plugin
+
+`plugins/pmx-canvas/` is a self-contained [Agent Plugins 1.0](https://agent-plugins.org/)
+package. It contains only PMX Canvas: the portable MCP server configuration and a native
+canvas extension for the GitHub Copilot app. It does not include frame integrations,
+general-purpose skills, or custom agents.
+
+## Client support
+
+| Client | Experience |
+| --- | --- |
+| GitHub Copilot app | PMX MCP tools and the native PMX Canvas side panel |
+| Other Agent Plugins-compatible clients | PMX MCP tools; open the workbench in a browser or the client's browser surface |
+| Clients without Agent Plugins support | Configure the MCP launcher manually using the client's MCP settings |
+
+The native Copilot canvas is **not** a portable capability. Other clients ignore the
+`com.github.copilot/` namespace. Supporting the package format also does not guarantee a
+client has an embedded browser, canvas panel, or host-specific steering adapter.
+
+## Install
+
+The local package can be loaded without changing the user's installed plugins:
+
+```bash
+copilot --plugin-dir /absolute/path/to/pmx-canvas/plugins/pmx-canvas
+```
+
+Once the plugin directory is published in the GitHub repository, install it with:
+
+```bash
+copilot plugin install pskoett/pmx-canvas:plugins/pmx-canvas
+```
+
+In the Copilot app, enable the plugin and start a new project session. Open the **PMX Canvas**
+canvas. Ask the agent to connect PMX to the active project; it calls `canvas_connect_workspace`
+with the project's absolute directory before using board tools. Do not separately install its
+project adapter or configure a second PMX MCP server.
+An existing project adapter can coexist with the plugin canvas. If both declare `pmx-canvas`,
+select the provider explicitly when opening: `plugin:pmx-canvas:pmx-canvas` for this plugin,
+or `project:pmx-canvas` for the project extension. An unqualified open can be ambiguous.
+
+Other clients should install the same plugin directory using their Agent Plugins support.
+For a manual MCP setup, invoke `bun /absolute/path/to/plugin/start-mcp.mjs` from the intended
+project directory. The launcher returns MCP JSON-RPC on stdout; diagnostics go to stderr.
+
+## Connect the workspace
+
+Agent Plugins launches MCP processes from the **plugin installation directory**, not the active
+project. Installing or initializing this plugin therefore does not create a board or start a
+daemon. Before any board operation, the agent calls:
+
+```json
+{
+  "name": "canvas_connect_workspace",
+  "arguments": { "workspaceRoot": "/absolute/path/to/project" }
+}
+```
+
+The result contains `serverUrl` and `workbenchUrl`. Other harnesses can open `workbenchUrl`
+in a browser. Copilot's native panel resolves the same workspace server.
+
+Board tools are advertised from a generated catalog so clients with a fixed initial tool list
+can discover them, but refuse execution until connected. Relative roots and the plugin
+installation directory are rejected. A connected MCP session cannot silently switch projects;
+start a new session for a different workspace.
+
+Clients advertising exactly one standard MCP file root can connect automatically. An explicit
+absolute `PMX_CANVAS_WORKSPACE_ROOT` in the MCP process environment also permits auto-connection.
+Neither `process.cwd()` nor an inherited `PWD` is used to guess the project.
+
+## Runtime and workspace ownership
+
+[Bun](https://bun.sh/) must be installed and available on the host's `PATH`. No globally
+installed `pmx-canvas` executable is required. The first workspace connection downloads the exact package
+version in `runtime.json` using `bun x --bun pmx-canvas@<version>`; it therefore needs npm
+access unless that version is already cached.
+
+Both the native canvas and the MCP launcher use the same resolver. It discovers the
+workspace's daemon port from `.pmx-canvas/daemon-<port>.pid` filenames, checks `/health`
+ownership, and serializes concurrent startup with `.pmx-canvas/plugin-start.lock`.
+The MCP subprocess receives the selected `PMX_CANVAS_URL` and an absolute workspace root.
+A foreign server on the preferred port is never treated as this project's server. Each forwarded
+MCP request rechecks ownership; a server replaced by another workspace is refused.
+
+The adapter uses the session's **working directory**, not Copilot's session-state
+`workspacePath` or the plugin installation directory. Boards remain in the project's
+`.pmx-canvas/canvas.db`.
+
+The daemon belongs to the workspace and stays running when one client closes, so closing
+the native panel cannot break another MCP client. Stop it explicitly from the project:
+
+```bash
+bun x --bun pmx-canvas@<version> serve stop --port=<port>
+```
+
+Use the exact version from `runtime.json` and the port from the panel's `status` action.
+`PMX_CANVAS_PORT` selects a preferred port; `PMX_CANVAS_URL` targets an existing server.
+An explicit URL that fails ownership checks is reported rather than silently replaced.
+
+## Package maintenance
+
+The plugin's adapter copies are generated from `.github/extensions/pmx-canvas/`:
+
+```bash
+bun run build:plugin
+bun test tests/unit/agent-plugin.test.js tests/unit/agent-plugin-mcp.test.ts tests/unit/copilot-runtime.test.js
+```
+
+The build bundles the MCP bootstrap with the existing SDK, generates its initial tool catalog
+through the real MCP `tools/list` API, and copies the canonical adapter and shared resolver into
+the plugin boundary. It pins their runtime to `package.json`'s version. No plugin code
+imports files outside the installed package. `bun run build` also regenerates the plugin,
+and drift tests byte-compare the distributed files against their canonical sources.
+
+The portable root contains `plugin.json`, `mcp.json`, `start-mcp.mjs`, `tools.json`, `runtime.mjs`,
+`runtime.json`, and license notices for the bundled dependencies. Copilot auto-discovers the native adapter at
+`com.github.copilot/extensions/pmx-canvas/extension.mjs`.
+
+The marketplace preview is copied from `docs/screenshot.png` to `assets/preview.png` on each
+plugin build. The manifest's `extensions.com.github.copilot.logo` points to that packaged PNG.
+
+Publishing a repository package does not register it in a curated marketplace or make it
+Featured in the Copilot app. Those are separate submission and review steps.

package/docs/ax-host-adapter-contract.md

@@ -6,12 +6,23 @@ capabilities, and the tool/prompt policy — over HTTP and MCP. What makes AX
 *interactive* on a given coding harness (GitHub Copilot, Codex, Claude Code, …) is
 a thin **adapter** that wires PMX's neutral surfaces to that harness's lifecycle.
 
-"Agnostic" means a documented interface plus PMX-side behavior plus one small
-reference adapter per harness — not zero-adapter magic. The genuinely harness-owned
+"Agnostic" means a documented interface plus PMX-side behavior that a host-specific
+adapter can use — not a shipped adapter for every harness or zero-adapter magic. The genuinely harness-owned
 acts (waking a turn, per-turn context injection, forwarding native tool hooks,
 native modals) still need a per-harness adapter; PMX owns everything on its side of
 the line (queues, endpoints, schemas, the canvas-surface fallback).
 
+### Amp uses native MCP, not a bundled lifecycle adapter
+
+Amp's portal and agent connection are separate. Configure `amp.mcpServers` in the
+executing workspace's `.amp/settings.json`, align its root/port with the portal service,
+and have the human approve a new workspace command before reloading MCP. See the
+[Amp setup guide](../skills/pmx-canvas/references/installing-pmx-canvas.md#amp-connect-the-agent-separately-from-the-portal).
+An active Amp agent can read pinned context, claim addressed steering, edit, verify the
+visible result and acknowledge. PMX ships no Amp lifecycle adapter that automatically
+injects context, forwards tool hooks, or wakes idle threads. The injection/push behavior
+below requires an adapter implementing it; merely configuring MCP does not provide it.
+
 ## The interface
 
 Every adapter implements as much of this as its host allows; PMX provides the

package/docs/ax-state-contract.md

@@ -71,3 +71,43 @@ record; redo replays `removeNode` inside suppressed recording
 **not** append a second note. Consumers should read `reanchoredIds` /
 `removedReviewIds` against the *current* canvas-bound state, not assume the
 referenced items are still re-anchored.
+
+## Agent presence (contract)
+
+Presence is the shape behind every agent surface in the rail chrome: the agent
+cursor and phase chip, the session panel, the command bar and the external
+steering indicator. It is **derived, in-memory and never persisted** — not a
+fourth partition, and not a second source of truth for work items, gates or
+steering, which stay in the AX state above. The shared shape lives in
+`src/shared/agent-presence.ts` (server and client import the same types and
+constants, so they cannot drift); the registry is `src/server/agent-presence.ts`.
+
+- **Sources.** Agent-originated mutations through `executeOperation` (no
+  workbench marker), `ax.activity.ingest` kinds (`session-start` /
+  `session-end` attach and detach; `tool-start` / `tool-result` / `failure` /
+  `error` drive the phase), and an explicit `ax.presence.set` for adapters with
+  richer hooks (`thinking`, cursor, focus).
+- **Modes.** `sessionActive` = any presence with `attached: true`. No presences →
+  quiet board; live but unattached writers → external steering (passive
+  indicator only); an attached session → the session panel and command bar.
+  Presence cursors render for every live writer regardless.
+- **Phase.** An agent mutation or `tool-start` → `tooling` (detail = op or tool
+  name), settling to `idle` after `PRESENCE_TOOLING_SETTLE_MS`; `thinking` only
+  via the explicit set, settling after `PRESENCE_THINKING_SETTLE_MS`. A cursor
+  update that moves the cursor restarts the settle window of a live explicit
+  `tooling`; a stationary cursor or focus heartbeat does not, and neither
+  extends `thinking`. An idle writer that reported a cursor keeps painting it.
+  An attached session with a pending approval gate reads as `waiting-approval`.
+- **Lifetime.** Unattached writers fade `PRESENCE_ACTIVITY_TTL_MS` after their
+  last write; attached sessions expire after `PRESENCE_ATTACHED_IDLE_TTL_MS`
+  without activity; `session-end` or an explicit `attached: false` removes the
+  presence immediately; at most `MAX_PRESENCES`, oldest evicted. Expiry emits,
+  so clients never run their own ticker.
+- **Transport.** One SSE frame, `agent-presence`, carries the full snapshot on
+  every change, including the last `MAX_ACTIVITY_ENTRIES` agent writes with a
+  one-line summary. `GET /api/canvas/ax/presence` for the connect-time read;
+  `POST /api/canvas/ax/presence` (`canvas_ax_state { action: "set-presence" }`)
+  for explicit updates.
+- **Budget.** `used` = estimated tokens of the `pinned-context.get` payload;
+  `total` = `PMX_CANVAS_CONTEXT_BUDGET_TOKENS` (default
+  `CONTEXT_BUDGET_DEFAULT_TOKENS`).

package/docs/cli.md

@@ -159,12 +159,17 @@ pmx-canvas                            # Start canvas, open browser
 pmx-canvas --demo                     # Start with the showcase demo board
 pmx-canvas --port=8080                # Custom port
 pmx-canvas --no-open                  # Headless (for agents/CI)
-pmx-canvas --theme=light              # dark | light | high-contrast | midnight | sepia | arctic | ember | forest | volt
+pmx-canvas --theme=daylight           # harbor | daylight | high-contrast | midnight | sepia | arctic | ember | forest | volt
 pmx-canvas --mcp                      # Run as MCP server (stdio)
+pmx-canvas --mcp-app                  # Private MCP App preview (stdio; shared active board)
 pmx-canvas --webview-automation       # Start headless Bun.WebView session
 pmx-canvas open                       # Open the current workbench in a browser
 ```
 
+The experimental `--mcp-app` profile has ten assistant tools plus an app-only
+transport for the real PMX workbench, separate from the standard MCP tool set. See
+[private MCP App setup and limitations](mcp.md#private-mcp-app-preview).
+
 ### Daemon mode
 
 Run detached with pid/log tracking instead of holding a terminal:
@@ -223,7 +228,7 @@ content.
 
 ```bash
 pmx-canvas node schema --type json-render --component Table --summary
-pmx-canvas validate                                                      # Layout validation
+pmx-canvas validate                                                      # Layout validation (collisions, groupFrameOverlaps, sizeWarnings)
 pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
 pmx-canvas validate spec --type html-primitive --kind choice-grid --data-json '{"items":[{"title":"A"}]}' --summary
 ```