pmx-canvas 0.4.2 → 0.4.4

package/dist/canvas/surface-theme.css

@@ -218,32 +218,32 @@
 }
 
 :root[data-theme="ember"] {
-  /* ── Core palette (ember · charcoal + vivid warm orange) ─── */
-  --c-bg: #0E0E11;
-  --c-panel: #17181D;
-  --c-panel-soft: #121317;
-  --c-line: #2A2C34;
-  --c-text: #ECEDF0;
-  --c-text-soft: #C9CCD4;
-  --c-muted: #8E939F;
-  --c-dim: #5F646E;
-  --c-accent: #FF5C2E;
+  /* ── Core palette (ember · neutral charcoal + vivid orange-red) ─── */
+  --c-bg: #0B0B0C;
+  --c-panel: #161618;
+  --c-panel-soft: #101012;
+  --c-line: #29292C;
+  --c-text: #EDEBE6;
+  --c-text-soft: #CBC9C2;
+  --c-muted: #96948D;
+  --c-dim: #66655F;
+  --c-accent: #F34E1C;
   --c-ok: #4CC38A;
   --c-warn: #F5B944;
   --c-warn-alt: #FFB300;
   --c-danger: #F0566A;
   --c-purple: #A78BFA;
 
-  --color-bg: #0E0E11;
-  --color-panel: #17181D;
-  --color-surface: #121317;
-  --color-border: #2A2C34;
-  --color-text: #ECEDF0;
-  --color-text-primary: #ECEDF0;
-  --color-text-secondary: #C9CCD4;
-  --color-text-muted: #8E939F;
-  --color-text-dim: #5F646E;
-  --color-accent: #FF5C2E;
+  --color-bg: #0B0B0C;
+  --color-panel: #161618;
+  --color-surface: #101012;
+  --color-border: #29292C;
+  --color-text: #EDEBE6;
+  --color-text-primary: #EDEBE6;
+  --color-text-secondary: #CBC9C2;
+  --color-text-muted: #96948D;
+  --color-text-dim: #66655F;
+  --color-accent: #F34E1C;
   --color-success: #4CC38A;
   --color-warning: #F5B944;
   --color-danger: #F0566A;
@@ -281,6 +281,38 @@
   --color-danger: #E57373;
 }
 
+:root[data-theme="volt"] {
+  /* ── Core palette (volt · green-tinted charcoal + coral) ── */
+  --c-bg: #0B0D0B;
+  --c-panel: #171A17;
+  --c-panel-soft: #111311;
+  --c-line: #272A27;
+  --c-text: #F6FFF5;
+  --c-text-soft: #CBD3CA;
+  --c-muted: #9CA49C;
+  --c-dim: #626962;
+  --c-accent: #F34E3F;
+  --c-ok: #52C880;
+  --c-warn: #E4C465;
+  --c-warn-alt: #FFB300;
+  --c-danger: #D67670;
+  --c-purple: #BC8FB4;
+
+  --color-bg: #0B0D0B;
+  --color-panel: #171A17;
+  --color-surface: #111311;
+  --color-border: #272A27;
+  --color-text: #F6FFF5;
+  --color-text-primary: #F6FFF5;
+  --color-text-secondary: #CBD3CA;
+  --color-text-muted: #9CA49C;
+  --color-text-dim: #626962;
+  --color-accent: #F34E3F;
+  --color-success: #52C880;
+  --color-warning: #E4C465;
+  --color-danger: #D67670;
+}
+
 html,
 body {
   margin: 0;

package/dist/types/cli/agent.d.ts

@@ -22,5 +22,6 @@ import './commands/ax.js';
 import './commands/webview.js';
 import './commands/apps.js';
 import './commands/copilot.js';
+import './commands/skills.js';
 export { extractGlobalTargetFlags };
 export declare function runAgentCli(rawArgs: string[]): Promise<void>;

package/dist/types/cli/commands/skills.d.ts

@@ -0,0 +1,41 @@
+export declare const BUNDLED_SKILLS: readonly ["pmx-canvas", "pmx-canvas-testing"];
+export interface SkillTreeComparison {
+    inSync: boolean;
+    /** Files present in the package tree but missing or different in the mirror. */
+    missingOrDifferent: string[];
+    /** Files present in the mirror but not in the package tree. */
+    extra: string[];
+}
+export declare function compareSkillTrees(sourceRoot: string, targetRoot: string): SkillTreeComparison;
+export interface InstalledSkillMirror {
+    /** The directory that owns the skills/ folder (e.g. ".codex", ".github", or any agent dir). */
+    host: string;
+    skill: string;
+    dir: string;
+}
+/**
+ * Find the bundled skills' installed copies in this workspace: any immediate
+ * child directory holding `skills/<skill>/SKILL.md`, regardless of which agent
+ * that directory belongs to. The package's own skills source is excluded so
+ * running inside the pmx-canvas checkout never compares a tree to itself.
+ */
+export declare function discoverInstalledSkillMirrors(workspaceRoot: string, packageSkillsRoot: string): InstalledSkillMirror[];
+export interface SkillMirrorResult {
+    host: string;
+    skill: string;
+    dir: string;
+    status: 'in-sync' | 'synced' | 'drifted' | 'skipped-not-a-package-copy';
+    missingOrDifferent?: string[];
+    extra?: string[];
+}
+/**
+ * A mirror is only replaceable when its SKILL.md frontmatter `name:` matches
+ * the bundled skill it sits under. A user's own skill living in a same-named
+ * directory (different frontmatter identity) must never be deleted — these
+ * trees are typically gitignored, so a wrong replace is unrecoverable.
+ */
+export declare function mirrorIdentityMatches(mirrorDir: string, skill: string): boolean;
+/** Sync (or, with check=true, only compare) every INSTALLED mirror against the package trees. */
+export declare function syncInstalledSkillMirrors(packageSkillsRoot: string, workspaceRoot: string, opts: {
+    check: boolean;
+}): SkillMirrorResult[];

package/dist/types/client/state/sse-bridge.d.ts

@@ -1,3 +1,4 @@
+export declare function forcedTransport(): 'poll' | 'sse' | null;
 /** @internal — exported for testing */
 export declare function hashPath(path: string): string;
 /** @internal — exported for testing */

package/dist/types/client/state/theme-override.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-session theme override — host-default theming.
+ *
+ * Hosts that embed the workbench (the GitHub Copilot panel, the Claude Code
+ * desktop browser pane, ChatGPT-style app browsers, …) can open it with
+ * `?theme=<name>` or `?theme=auto` to give THEIR panel a fitting default
+ * without touching the server-global theme every other client sees. The
+ * override is client-local: server theme frames are ignored while it is
+ * active, and it ends the moment the user explicitly picks a theme from the
+ * picker (which then applies + saves globally as usual).
+ *
+ * `theme=auto` follows the host's prefers-color-scheme live, mapping to the
+ * built-in light/dark themes — so a light-mode host panel gets a light canvas
+ * by default and flips with the host appearance.
+ */
+import { type CanvasThemeName } from '../../shared/themes.js';
+export declare function themeOverrideActive(): boolean;
+/** Test-only: reset the module state, including the page-lifetime latch. */
+export declare function resetThemeOverrideForTests(): void;
+/** The user picked a theme explicitly — the session override ends for good. */
+export declare function clearThemeOverride(): void;
+export declare function sessionThemeParam(): CanvasThemeName | 'auto' | null;
+/**
+ * Activate the override from the URL (no-op without a valid `?theme=`).
+ * `apply` is the canvas theme applier (client-side only — never saved).
+ */
+export declare function initSessionThemeOverride(apply: (theme: CanvasThemeName) => void): void;

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"];
+export declare const CANVAS_THEMES: readonly ["dark", "light", "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

@@ -134,12 +134,20 @@ publishing, update the installed package in the consumer workspace and re-sync
 its four mirrors from `<global npm root>/pmx-canvas/skills/` so the first test
 pass runs against the released skills, not the previous version's guidance.
 
-Sync the **complete tree of every bundled skill** — `pmx-canvas` AND
-`pmx-canvas-testing`, including `references/`, `evals/`, and fixtures — and
-verify by diffing whole directories, not by comparing the `SKILL.md` hash
-alone. The 0.3.4 and 0.4.0 cycles both hit drift where `SKILL.md` matched but
-references/evals were stale, or a newly bundled skill was missing from the
-mirrors entirely.
+This is now one command in the consumer workspace (added post-0.4.3):
+
+```bash
+pmx-canvas skills sync --yes     # refreshes every INSTALLED skill copy from the package
+pmx-canvas skills sync --check   # drift detection only (exit 1 when stale)
+```
+
+It discovers the skill copies already installed in the workspace (whatever
+agent layout owns them — no host list is assumed) and compares/replaces
+**whole trees** — `references/`, `evals/`, fixtures — not `SKILL.md` hashes
+alone (the 0.3.x–0.4.x cycles repeatedly hit drift where the hash matched but
+supporting files were stale). Also re-run
+`pmx-canvas copilot install-extension --yes` in repos that use the Copilot
+adapter so the panel picks up new open-URL behavior.
 
 ## GitHub release
 

package/docs/bun-webview-integration.md

@@ -12,7 +12,7 @@ This document tracks:
 
 **Implemented** for Phase 1.
 
-The repo now targets Bun `>=1.3.12`, and PMX Canvas ships an opt-in, server-owned WebView automation session that can:
+The repo now targets Bun `>=1.3.14`, and PMX Canvas ships an opt-in, server-owned WebView automation session that can:
 
 - start a headless browser session for `/workbench`
 - report WebView runtime status
@@ -192,7 +192,7 @@ If `chromePath` or `chromeArgv` is provided, PMX Canvas forces a Chrome-backed s
 
 The repo now requires:
 
-- Bun `>=1.3.12`
+- Bun `>=1.3.14`
 
 That change is reflected in:
 

package/docs/cli.md

@@ -20,7 +20,7 @@ pmx-canvas                            # Start canvas, open browser
 pmx-canvas --demo                     # Start with the saved dashboard 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
+pmx-canvas --theme=light              # dark | light | high-contrast | midnight | sepia | arctic | ember | forest | volt
 pmx-canvas --mcp                      # Run as MCP server (stdio)
 pmx-canvas --webview-automation       # Start headless Bun.WebView session
 pmx-canvas open                       # Open the current workbench in a browser
@@ -211,6 +211,29 @@ pmx-canvas copilot install-extension --dry-run   # Preview target, writes nothin
 pmx-canvas copilot install-extension --yes        # Install/overwrite into .github/extensions/pmx-canvas/
 ```
 
+## Skill sync
+
+Refresh the pmx-canvas skill copies **already installed** in this workspace.
+The command discovers them (any `<agent-dir>/skills/pmx-canvas[-testing]`,
+whichever agent layout the workspace uses) and compares/replaces whole trees —
+references, evals, and fixtures included — so a copy can no longer drift while
+its `SKILL.md` hash matches. It never creates a copy where none is installed
+and makes no assumptions about which agents you use.
+
+```bash
+pmx-canvas skills sync --yes     # Refresh every installed copy from the package
+pmx-canvas skills sync --check   # Report drift only (exit 1 when stale), change nothing
+```
+
+Replacing a tree is destructive, so the sync requires `--yes`; without it the
+command only reports drift (like `--check`) and hints at the flag. A directory
+whose `SKILL.md` identity doesn't match the bundled skill is skipped, never
+replaced.
+
+Run `skills sync --yes` (and `copilot install-extension --yes` if the repo uses the
+Copilot adapter) after every `pmx-canvas` upgrade so agents operate on the
+released guidance.
+
 ## WebView automation
 
 Drive a headless Bun.WebView (Chromium or WebKit) pointed at the workbench:

package/docs/environment.md

@@ -25,8 +25,8 @@ optional; defaults are listed.
 
 | Variable | Read by | Effect |
 |---|---|---|
-| `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`. |
-| `AMP_ORB` | server | Set by Amp orb services. When present, the served canvas page tells the browser it is running in an orb, which skips the iframe embed probe and forces `srcdoc` surface rendering when embedded (the orb portal blocks `src`-URL child iframes and the probe is unreliable there). |
+| `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, `volt`. |
+| `AMP_ORB` | server | Set by Amp orb services. When present, the served canvas page tells the browser it is running in an orb, which skips the iframe embed probe, forces `srcdoc` surface rendering when embedded (the orb portal blocks `src`-URL child iframes and the probe is unreliable there), and defaults the event transport to polling instead of SSE (the portal proxy buffers streams; `?transport=sse` overrides for diagnosis). |
 | `PMX_CANVAS_DISABLE_BROWSER_OPEN` | server | `1` suppresses auto-opening the browser (used by tests/CI). |
 | `PMX_CANVAS_DIST` | server | Explicit client bundle directory to serve instead of the packaged `dist/canvas`. |
 | `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` | server | Startup timeout for the Bun.WebView automation session. |

package/docs/http-api.md

@@ -341,9 +341,20 @@ Responses are `{ ok, transport: "poll", snapshot, seq, events }` — poll again
 with `since=<seq>` every couple of seconds. A `since` from a previous server
 run or one that fell off the bounded event ring recovers with a fresh
 snapshot. The browser client uses this automatically: if the SSE stream
-produces no event within 3 seconds of connecting, it switches to polling.
-Force a transport with `/workbench?transport=poll` (or `transport=sse` to
-disable the fallback).
+produces no event within 3 seconds of connecting, it switches to polling (and
+tells the boot screen to wait for the fallback instead of alarming). Pages
+served by an Amp orb (`AMP_ORB` set — the same stamp that drives srcdoc mode)
+skip SSE entirely and default straight to polling. Force a transport with
+`/workbench?transport=poll` (or `transport=sse` to disable the fallback /
+override the orb default).
+
+## Session theme override (host-default theming)
+
+`/workbench?theme=<name>` gives that browser session its own theme without
+touching the server-global theme other clients see — embedding hosts use it to
+match their chrome (the bundled Copilot extension opens `?theme=light`).
+`?theme=auto` follows the host's `prefers-color-scheme` live. Picking a theme
+from the toolbar ends the override and saves globally as usual.
 
 ## Iframe embed probe (nested-iframe hosts)
 

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -66,7 +66,7 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 |---|---|
 | Windows web-artifacts | The artifact build pipeline is bash-script-backed (POSIX-only); `tests/unit/web-artifacts.test.ts` self-skips on win32 and docs now state the boundary. Decide: port the build scripts to a cross-platform runner, or keep the documented "build on POSIX, render anywhere" stance. |
 | Composite parity no longer machine-checked | Since v0.3.0 removed the legacy standalones, the byte-identical composite-vs-legacy guarantee has no head-to-head test — regressions in `buildInput`/`formatResult` reuse surface only via output-shape assertions. Accepted at review; revisit if a composite drifts. |
-| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap", inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. 0.4.1 shipped the cheaper mimic (post-settle WebKit repaint nudge, `repaint-nudge` trail event) and the 0.4.1 Copilot report confirms the nudge RUNS but residual black tiles still appear (Diamond on first-load settle, Ellipse after restart settle) — the contingency's trigger condition is now met. This portal-layer mount is the designated next Finding N step; scope it as its own project (drag/zoom sync, z-order, clipping, minimap interplay), not a patch-release bolt-on. |
+| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap", inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. 0.4.1 shipped the cheaper mimic (post-settle WebKit repaint nudge, `repaint-nudge` trail event) and the 0.4.1 Copilot report confirms the nudge RUNS but residual black tiles still appear (Diamond on first-load settle, Ellipse after restart settle) — the contingency's trigger condition is now met. 0.4.3 Codex hardens the evidence: three ready tiles blank in WebKit with **byte-identical** early/late screenshots while the recovery trail reported initialized/settled — DOM-level recovery completion does not prove compositor paint, so no DOM-side nudge can close this. This portal-layer mount is the designated next Finding N step; scope it as its own project (drag/zoom sync, z-order, clipping, minimap interplay), not a patch-release bolt-on. |
 
 ## Added post-0.4.0 (2026-08-04 report cycle)
 
@@ -74,5 +74,8 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 |---|---|
 | Finding S — frame documents vs server restart | **Done + field-confirmed (0.4.1 reports, both hosts):** the browser revalidates minted frame-document URLs on every reconnect epoch (`workbenchConnectionEpoch`, HEAD probe) and re-mints against the new process when the store is gone; `/api/canvas/frame-documents/:id` answers HEAD. Copilot: IDs fully rotated, all post-restart 200, no frame-not-found tiles. Codex: re-mint without workbench reload. Server-side persistence deliberately NOT done — frames are client-derived and re-mintable. |
 | Amp portal nested-iframe embedding | **Done (2026-08-04):** boot-time embed probe (`/api/canvas/iframe-probe`) + fetch()+srcdoc fallback for all same-origin surfaces (`useSurfaceFrame`, `useIframeDocument` srcdoc short-circuit), `?iframe-mode` override, e2e-forced-mode coverage. External (cross-origin) app URLs cannot be inlined — documented limitation. |
-| Copilot adapter `canvas_snapshot list` descriptor lag | Host-side cached tool schema still requires `name`; fresh `--mcp` is correct. Adapter/packaging issue, not a daemon defect — nothing to change in core; re-verify next cycle. |
+| Copilot adapter `canvas_snapshot list` descriptor lag | Host-side cached tool schema still requires `name`; fresh `--mcp` is correct. Adapter/packaging issue, not a daemon defect — nothing to change in core; 0.4.2 cycle saw the legacy tools gone from the host list after refresh. |
+| Finding T — theme/More menu mis-anchored | **Done + field-confirmed (0.4.3 reports, both hosts):** menus moved inside `.toolbar-menu-anchor` wrappers around their triggers. Copilot measured button/menu right edges equal; Codex measured delta 0. Anchor-geometry e2e regression tests in place. |
+| Finding U — sticky `-32001` session-error banner over rendering content | **Presentation fix field-confirmed (0.4.3 reports, both hosts); root cause open:** forced error state renders the soft saved-content notice. The underlying stressed-reconnect MCP timeout is still not clean-reproducible — investigate session re-establishment retry/backoff if a future cycle reproduces it. |
+| Skill-mirror drift automation | **Done (2026-08-05):** `pmx-canvas skills sync` (+ `--check`, exit 1 on drift) discovers the skill copies already installed in the workspace — no assumed host layout, per maintainer direction — and whole-tree-replaces them from the package. Closes the recurring every-cycle hand-sync complaint in the audit addenda. Remaining audit ask: a true model-vs-baseline benchmark of the 17 eval prompts (a test-harness task, not a repo artifact). |
 | Registry-migration dead-code sweep | **Done (2026-08-03):** removed the orphaned `describeOp`/`describeGateOp` (composites.ts, dead since the v0.3.0 registration filter) and the `compactNodePayload`/`compactLayoutPayload`/`wantsFullPayload` duplicates in `mcp/server.ts` (live copies are in `ops/nodes.ts`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Spatial canvas workbench for coding agents \u2014 infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",
@@ -43,9 +43,9 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "test": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
+    "test": "if [ -d tests/unit ]; then PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
     "test:unit": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
-    "test:client": "bun test --preload ./tests/client/setup.ts tests/client",
+    "test:client": "if [ -d tests/client ]; then bun test --preload ./tests/client/setup.ts tests/client; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
     "test:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bash scripts/run-playwright.sh",
     "test:e2e": "bun run test:web-canvas",

package/skills/pmx-canvas/SKILL.md

@@ -18,6 +18,14 @@ Humans curate agent context by pinning nodes; agents read that curation through
 
 ## Required Operating Sequence
 
+0. **After a `pmx-canvas` upgrade, refresh this skill first.** Run
+   `pmx-canvas skills sync --yes` (`--check` to detect drift; exit 1 when stale) — it finds the skill
+   copies already installed in the workspace (whatever layout your agent uses) and replaces the
+   complete trees from the package, references/evals/fixtures included. Sync ONLY from the
+   installed package, never from a source checkout: this skill documents the runtime it ships
+   with, and a newer repo skill paired with an older installed runtime advertises commands and
+   themes the binary does not have (0.4.3 report skew finding). Also restart the HTTP daemon and
+   any `--mcp` processes; Bun does not hot-reload a running process.
 1. **Open or focus the workbench before mutating.** Reuse one visible canvas surface for the
    session.
 2. **Verify workspace identity.** Read `GET /health` or `pmx-canvas serve status`; the returned
@@ -175,12 +183,16 @@ Use the visible workbench when the human is actively curating layout:
 - Drop files or URLs to create matching nodes.
 - Double-click markdown to edit inline.
 - Use toolbar snapshots before experiments and restore only after confirmation.
-- The toolbar carries view controls (fit, reset, zoom), arrange, minimap, a theme picker (eight
-  themes: dark, light, high-contrast, midnight, sepia, arctic, ember, forest), snapshots, trace,
+- The toolbar carries view controls (fit, reset, zoom), arrange, minimap, a theme picker (nine
+  themes: dark, light, high-contrast, midnight, sepia, arctic, ember, forest, volt), snapshots, trace,
   the annotation tools, search (Cmd+K), and shortcuts. On narrow viewports (≤900px — most
   embedded host panes and mobile) the secondary controls collapse into a single "⋯" More menu at
   the end of the bar; every action is still there as a labeled row, including the theme list. If
   an automation script can't find a toolbar button at panel width, open the More menu first.
+- Embedding hosts can open `/workbench?theme=<name>` (or `?theme=auto` to follow the host's
+  light/dark appearance) for a session-local default theme that never changes the server-global
+  theme other clients see; an explicit pick from the theme menu ends the override. The bundled
+  Copilot extension opens its panel with `?theme=light`.
 
 After changing files under `src/client/`, rebuild with `bun run build` before manual browser
 verification.
@@ -261,8 +273,10 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   with a gray placeholder. The canvas probes this at boot and auto-falls back to fetching
   same-origin surfaces and rendering them inline via `srcdoc` (HTML, graph, json-render, frame
   documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and stamps
-  the page so the embedded client skips the (there-unreliable) probe and goes straight to
-  `srcdoc`; HTML surfaces also inline their theme stylesheet so they render styled. External app
+  the page so the embedded client skips the (there-unreliable) probe, goes straight to `srcdoc`,
+  AND defaults to the polling transport (the portal proxy buffers SSE — waiting out the watchdog
+  could trip the boot modal); HTML surfaces also inline their theme stylesheet so they render
+  styled. External app
   URLs cannot be inlined (cross-origin) and may stay blocked in such hosts. Force a mode with
   `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and

package/skills/pmx-canvas/references/full-reference.md

@@ -132,7 +132,7 @@ pmx-canvas --theme=light       # Light theme
 pmx-canvas --version           # Print installed version and exit
 ```
 
-`--theme` accepts `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, or `forest` (0.4.x; the browser toolbar has a matching theme picker). Same value can be set via
+`--theme` accepts `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, or `volt` (0.4.x; the browser toolbar has a matching theme picker). Same value can be set via
 the `PMX_CANVAS_THEME` environment variable, or toggled live in the browser toolbar.
 
 Start the canvas once per session, then reuse it. Use `--no-open` when running as an agent — the

package/skills/pmx-canvas-testing/SKILL.md

@@ -74,6 +74,10 @@ Prefer extending the existing suites before inventing a one-off script.
 - MCP harnesses using the official SDK must wind down BOTH halves: call `client.close()` AND
   `transport.close()` on the `StdioClientTransport`. Closing only the client leaves the spawned
   stdio server process alive after the test exits (0.4.0 cycle finding)
+- Before a version-test cycle, run `pmx-canvas skills sync --check` in the consumer workspace —
+  exit 1 means the installed skill copies are stale against the package; run
+  `pmx-canvas skills sync --yes` to refresh them (whole trees, whatever agent layout owns them) before
+  trusting skill-guided results
 
 ## Layout And Embedded Content Checks
 

package/src/cli/agent.ts

@@ -31,6 +31,7 @@ import './commands/ax.js';
 import './commands/webview.js';
 import './commands/apps.js';
 import './commands/copilot.js';
+import './commands/skills.js';
 
 // Re-exported for existing importers (tests import it from this module).
 export { extractGlobalTargetFlags };

package/src/cli/commands/skills.ts

@@ -0,0 +1,183 @@
+// Skill mirror commands: skills sync (+ --check drift detection).
+//
+// Every release cycle found installed skill copies stale against the package,
+// and testers hand-synced complete trees before results were trustworthy.
+// This command automates that WITHOUT assuming any agent layout: it discovers
+// the pmx-canvas skill copies already installed in the workspace (any
+// `<dir>/skills/<skill-name>/SKILL.md`, whatever agent owns `<dir>`) and
+// compares/replaces whole trees — references, evals, fixtures included. It
+// never creates a mirror where none is installed.
+
+import { cpSync, existsSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cmd, output, parseFlags, showCommandHelp } from '../shared.js';
+
+export const BUNDLED_SKILLS = ['pmx-canvas', 'pmx-canvas-testing'] as const;
+
+function listFilesRecursive(root: string, prefix = ''): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...listFilesRecursive(join(root, entry.name), rel));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out.sort();
+}
+
+export interface SkillTreeComparison {
+  inSync: boolean;
+  /** Files present in the package tree but missing or different in the mirror. */
+  missingOrDifferent: string[];
+  /** Files present in the mirror but not in the package tree. */
+  extra: string[];
+}
+
+export function compareSkillTrees(sourceRoot: string, targetRoot: string): SkillTreeComparison {
+  const sourceFiles = listFilesRecursive(sourceRoot);
+  const targetFiles = listFilesRecursive(targetRoot);
+  const targetSet = new Set(targetFiles);
+  const missingOrDifferent: string[] = [];
+  for (const rel of sourceFiles) {
+    if (!targetSet.has(rel)) {
+      missingOrDifferent.push(rel);
+      continue;
+    }
+    if (!readFileSync(join(sourceRoot, rel)).equals(readFileSync(join(targetRoot, rel)))) {
+      missingOrDifferent.push(rel);
+    }
+  }
+  const sourceSet = new Set(sourceFiles);
+  const extra = targetFiles.filter((rel) => !sourceSet.has(rel));
+  return { inSync: missingOrDifferent.length === 0 && extra.length === 0, missingOrDifferent, extra };
+}
+
+export interface InstalledSkillMirror {
+  /** The directory that owns the skills/ folder (e.g. ".codex", ".github", or any agent dir). */
+  host: string;
+  skill: string;
+  dir: string;
+}
+
+/**
+ * Find the bundled skills' installed copies in this workspace: any immediate
+ * child directory holding `skills/<skill>/SKILL.md`, regardless of which agent
+ * that directory belongs to. The package's own skills source is excluded so
+ * running inside the pmx-canvas checkout never compares a tree to itself.
+ */
+export function discoverInstalledSkillMirrors(
+  workspaceRoot: string,
+  packageSkillsRoot: string,
+): InstalledSkillMirror[] {
+  const found: InstalledSkillMirror[] = [];
+  for (const entry of readdirSync(workspaceRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === 'node_modules') continue;
+    const skillsDir = join(workspaceRoot, entry.name, 'skills');
+    if (!existsSync(skillsDir)) continue;
+    for (const skill of BUNDLED_SKILLS) {
+      const dir = join(skillsDir, skill);
+      if (!existsSync(join(dir, 'SKILL.md'))) continue;
+      if (resolve(dir) === resolve(join(packageSkillsRoot, skill))) continue;
+      found.push({ host: entry.name, skill, dir });
+    }
+  }
+  return found;
+}
+
+export interface SkillMirrorResult {
+  host: string;
+  skill: string;
+  dir: string;
+  status: 'in-sync' | 'synced' | 'drifted' | 'skipped-not-a-package-copy';
+  missingOrDifferent?: string[];
+  extra?: string[];
+}
+
+/**
+ * A mirror is only replaceable when its SKILL.md frontmatter `name:` matches
+ * the bundled skill it sits under. A user's own skill living in a same-named
+ * directory (different frontmatter identity) must never be deleted — these
+ * trees are typically gitignored, so a wrong replace is unrecoverable.
+ */
+export function mirrorIdentityMatches(mirrorDir: string, skill: string): boolean {
+  try {
+    const head = readFileSync(join(mirrorDir, 'SKILL.md'), 'utf-8').slice(0, 2000);
+    const match = /^name:\s*(\S+)\s*$/m.exec(head);
+    return match?.[1] === skill;
+  } catch {
+    return false;
+  }
+}
+
+/** Sync (or, with check=true, only compare) every INSTALLED mirror against the package trees. */
+export function syncInstalledSkillMirrors(
+  packageSkillsRoot: string,
+  workspaceRoot: string,
+  opts: { check: boolean },
+): SkillMirrorResult[] {
+  const results: SkillMirrorResult[] = [];
+  for (const mirror of discoverInstalledSkillMirrors(workspaceRoot, packageSkillsRoot)) {
+    const source = join(packageSkillsRoot, mirror.skill);
+    if (!mirrorIdentityMatches(mirror.dir, mirror.skill)) {
+      results.push({ ...mirror, status: 'skipped-not-a-package-copy' });
+      continue;
+    }
+    const cmp = compareSkillTrees(source, mirror.dir);
+    if (cmp.inSync) {
+      results.push({ ...mirror, status: 'in-sync' });
+      continue;
+    }
+    if (opts.check) {
+      results.push({ ...mirror, status: 'drifted', ...cmp });
+      continue;
+    }
+    // Full-tree replace: a copy-over would leave deleted package files behind
+    // in the mirror, which is exactly the drift class release audits kept
+    // hitting even when SKILL.md hashes matched. Stage the complete new tree
+    // BESIDE the mirror first, so a crash between the rm and the rename leaves
+    // the staged copy on disk as recovery instead of losing the install.
+    const staging = `${mirror.dir}.pmx-sync-staging`;
+    rmSync(staging, { recursive: true, force: true });
+    cpSync(source, staging, { recursive: true });
+    rmSync(mirror.dir, { recursive: true, force: true });
+    renameSync(staging, mirror.dir);
+    results.push({ ...mirror, status: 'synced' });
+  }
+  return results;
+}
+
+// ── skills sync ──────────────────────────────────────────────
+cmd(
+  'skills sync',
+  'Refresh the pmx-canvas skill copies already installed in this workspace (any agent layout)',
+  ['pmx-canvas skills sync --yes', 'pmx-canvas skills sync --check'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('skills sync');
+
+    const packageSkillsRoot = fileURLToPath(new URL('../../../skills', import.meta.url));
+    // Replacing a mirror deletes a whole installed tree — destructive, so it
+    // follows the CLI's `--yes` contract. Without --yes (or with --check) the
+    // command only reports drift; exit 1 signals stale either way.
+    const check = flags.check === true || flags.yes !== true;
+    const results = syncInstalledSkillMirrors(packageSkillsRoot, process.cwd(), { check });
+
+    const drifted = results.filter((r) => r.status === 'drifted');
+    const ok = drifted.length === 0;
+    output({
+      ok,
+      check,
+      packageSkillsRoot,
+      mirrorsFound: results.length,
+      ...(results.length === 0 ? { note: 'No installed pmx-canvas skill copies found in this workspace.' } : {}),
+      ...(drifted.length > 0 && flags.yes !== true
+        ? { note: 'Drift detected. Re-run with --yes to replace the drifted trees from the installed package.' }
+        : {}),
+      results,
+    });
+    if (!ok) process.exitCode = 1;
+  },
+);