pmx-canvas 0.1.26 → 0.1.28

package/skills/control-session-orchestrator/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: control-session-orchestrator
+description: >
+  Control-plane workflow for coordinating multi-agent, multi-session project work from a single
+  Codex, GitHub Copilot, or agent-app control session. Use this skill whenever the user asks to
+  orchestrate agents, create or steer worker sessions, run a workflow-like effort, fan out
+  audits/research/migrations, coordinate parallel implementation streams, monitor other project
+  sessions, or compare this control-session pattern to Claude Code dynamic workflows. This skill is
+  especially relevant when the current session can spawn persistent project sessions and those
+  sessions can spawn their own subagents, creating a two-level orchestration hierarchy.
+---
+
+# Control Session Orchestrator
+
+Use the current session as the control plane for project work that is too broad, risky, or
+stateful for one conversation. The control session owns intent, decomposition, routing, status,
+verification, and consolidation. Worker sessions own scoped execution. Worker subagents are local
+implementation/research/audit helpers inside each worker session.
+
+## Mental model
+
+```
+User
+  -> Control session (strategy, dispatch, tracking, integration)
+       -> Worker project session A (persistent branch/workstream)
+            -> Subagents for research, implementation, review, tests
+       -> Worker project session B (persistent branch/workstream)
+            -> Subagents for local fan-out
+       -> Verifier/reviewer session (optional independent gate)
+```
+
+This is similar to dynamic workflows, but the orchestration is human-readable and session-native
+instead of a runtime script. Use it when persistence, branches, PRs, human steering, or cross-session
+continuity matter more than fully automated fan-out.
+
+A code runtime gets reliability for free (validated results, barriers, budgets, dedup, resume). A
+prompt-driven control plane only gets it if you make state machine-checkable. Two contracts do that
+without a runtime: a required **worker result block** and a durable **control-state manifest** (see
+[Machine-checkable contracts](#machine-checkable-contracts)). Everything else in this skill keys off
+those two artifacts — without them, "is this worker done and passing?" is a guess, not a field read.
+
+## Supported control apps
+
+This skill is app-agnostic. First discover which orchestration tools are available in the current
+session, then adapt the same control workflow to that surface.
+
+| Capability | Codex app | GitHub Copilot app | Fallback |
+|---|---|---|---|
+| Find worker sessions | List/search project threads | List/search app sessions | Ask user for target session links/IDs |
+| Create persistent workstreams | Create or reuse Codex threads/worktrees when available | Create or reuse Copilot app sessions/workspaces when available | Use local subagents only |
+| Steer an existing workstream | Send a follow-up prompt to the thread | Send a follow-up prompt to the session | Ask user to paste the prompt into the worker |
+| Local fan-out | Spawn subagents from this session or ask workers to spawn their own | Use Copilot's available agent/session tools | Keep work local |
+| Tracking | Thread titles, pins, branches, PRs, canvas nodes, compact status tables | Session names, branches, PRs, issues, canvas nodes, compact status tables | Markdown status table |
+
+Do not assume the GitHub Copilot or Codex tool names. Use the tools exposed in the current
+environment, and say which control surface is active before dispatching workers.
+
+## When to use
+
+Use this skill for:
+
+- Codebase-wide audits, migrations, or parity checks
+- Parallel investigation across modules, services, features, or PRs
+- Work that benefits from independent implementer and verifier sessions
+- Large features where design, implementation, testing, and review should be split
+- Project-control prompts like "coordinate agents", "spin up sessions", "run a workflow",
+  "make workers handle this", "monitor the other sessions", or "act as control"
+- Situations where worker sessions may themselves use subagents for local research, coding, or review
+
+Do not use it for a simple one-file fix, a quick answer, or a task where a single local subagent is
+enough. Orchestration has overhead; spend it only when coordination reduces risk or increases
+throughput.
+
+## Machine-checkable contracts
+
+These are the session-native analog of a runtime's typed results and durable run state. They stay
+human-readable, but they are **required**, not advisory — the control session parses them instead of
+re-reading prose.
+
+### Worker result block
+
+Every worker MUST end its report with a fenced ` ```json ` block tagged `control-result`. The control
+session reads this block (never the surrounding prose) to update state, dedup, and decide routing.
+
+```json control-result
+{
+  "worker_id": "auth-api",
+  "wave_id": "w1",
+  "unit_key": "service/auth",
+  "scope": "src/auth/** — refresh-token rotation",
+  "status": "complete",
+  "files_changed": ["src/auth/rotate.ts"],
+  "verification": { "command": "pnpm test auth", "result": "pass", "evidence": "42 passed" },
+  "subagents_used": "2 — one research, one test author",
+  "risks": ["rotation interacts with logout; covered by test"],
+  "next_step": "ready for review session",
+  "report_ref": "thread/PR/path to the full report"
+}
+```
+
+The block must be **strict JSON** (no comments/trailing commas) so it parses. `status` is one of
+`complete | blocked | needs-decision | failed`; `verification.result` is one of `pass | fail | not-run`.
+
+### Control-state manifest
+
+One durable artifact that **is** the source of truth for the mission — a pinned control thread, a
+tracking-issue body, a canvas node, or a committed `control/state.json`. Re-read and update it every
+turn; keep the conversation for decisions, not state. One row per **unit** (unit-keyed, so the same
+unit is never dispatched twice — this is the dedup ledger).
+
+```json
+{
+  "mission": "MCP tool parity audit",
+  "non_goals": ["no behavior changes"],
+  "success_criteria": ["every tool present in server, HTTP, SDK, docs or flagged"],
+  "budget": { "max_concurrent_workers": 5, "max_total_workers": 25, "spawned": 0, "in_flight": 0 },
+  "convergence": { "rule": "single-pass", "k_empty": 2, "empty_streak": 0, "target": null, "current": 0 },
+  "workers": [
+    {
+      "unit_key": "surface/http",
+      "worker_id": "http-audit",
+      "session_ref": "thread-or-session id/link",
+      "scope": "HTTP API surface",
+      "branch_or_pr": "—",
+      "status": "pending",
+      "wave_id": "w1",
+      "last_update": "ISO-8601",
+      "evidence_ref": "report_ref from the result block"
+    }
+  ],
+  "decisions": [],
+  "open_followups": []
+}
+```
+
+Rules:
+
+- **Worker status** (what a worker self-reports in its result block): `complete | blocked |
+  needs-decision | failed`.
+- **Manifest unit status** (the superset the control session maintains): `pending | dispatched |
+  needs-decision | blocked | stalled | complete | failed | dropped`. Worker-reported values are a
+  subset of these, so setting a unit's status from a worker block (Step 5) is always valid.
+- **Terminal** states — a unit is closed — are `complete | failed | dropped`. Everything else is
+  non-terminal and must be resolved, or explicitly converted to `dropped` with a reason, before the
+  mission closes (Step 8).
+- `budget.in_flight` is the number of rows currently `dispatched`. Increment `spawned` and `in_flight`
+  on dispatch; decrement `in_flight` when a unit leaves `dispatched`; recompute it from the rows on
+  rehydrate.
+- `convergence.rule` is one of `single-pass | loop-until-dry | loop-until-budget |
+  accumulate-to-target`. `k_empty`/`empty_streak` are used only by `loop-until-dry`; `target`/`current`
+  only by `accumulate-to-target` (`target` = the count or coverage goal, `current` = progress so far).
+- dropped/failed units MUST carry a reason in `open_followups`.
+
+This manifest is what a fresh control session rehydrates from (Step 0).
+
+## Control workflow
+
+### 0. Rehydrate (resume an in-flight mission)
+
+On session start, look for an existing control-state manifest for this mission. If one exists:
+
+- Load it; treat it as the source of truth.
+- Re-attach to workers by `session_ref` and reconcile each worker's *real* status (read the thread/PR)
+  before any new dispatch.
+- Recompute `budget.in_flight` from the rows still marked `dispatched`.
+- Do NOT re-dispatch a unit whose status is `dispatched` or `complete` — route a follow-up instead.
+
+If no manifest exists, this is a new mission — create one during Step 1.
+
+### 1. Frame the mission
+
+Before spawning anything, capture (and write into the manifest):
+
+- Objective and non-goals
+- Repositories, branches, PRs, or issues in scope
+- File or subsystem boundaries for each workstream
+- Success criteria and verification gates
+- Merge/integration expectations
+- Any "do not touch" constraints
+
+Also set explicit limits up front (manifest `budget` and `convergence`):
+
+- `max_concurrent_workers` (default ~4–6) — never more in flight at once
+- `max_total_workers` — a lifetime backstop for the whole mission (e.g. 25)
+- optional token / cost / time ceiling
+- the convergence rule: `single-pass` for bounded missions; `loop-until-dry`, `loop-until-budget`,
+  or `accumulate-to-target` for open-ended audits/migrations/parity sweeps
+
+If any boundary is ambiguous and could cause conflicting edits, ask before dispatch.
+
+### 2. Detect the control surface
+
+Before dispatch, identify the available app tools:
+
+- Codex app: thread/session tools such as list, create/read, send-message, rename, pin/archive, plus
+  optional local subagent tools.
+- GitHub Copilot app: session or workspace tools exposed by the app connector, plus any available
+  GitHub issue/PR/branch controls.
+- Generic agent app: any combination of session, task, subagent, branch, issue, PR, or automation
+  tools.
+
+If no persistent-session tools are available, downgrade to a local multi-agent plan and explain the
+limitation. Do not invent a backend.
+
+### 3. Choose the topology
+
+Pick the smallest useful topology:
+
+- **One worker**: isolated implementation or bug fix that should live in its own project session
+- **Parallel workers**: independent modules, packages, endpoints, tests, or docs
+- **Research then implementation**: exploratory sessions report findings before coding starts
+- **Implementer + verifier**: one session changes code, another reviews or verifies independently
+- **Control-only**: no workers yet; just inspect state, list sessions, or plan the dispatch
+
+Prefer separate sessions when workers may edit overlapping history, need different branches, or need
+long-running context. Prefer local subagents inside one session when the task is exploratory and does
+not need persistent branch state.
+
+### 4. Dispatch workers with complete prompts
+
+Respect the budget: **never dispatch while `in_flight >= max_concurrent_workers`** — queue the unit
+(`status: pending`) and log it. On reaching `max_total_workers` or a token/cost ceiling, STOP
+dispatching and surface a *Decision needed* rather than spawning more. Dispatch is an **atomic
+manifest update**: set the unit's row to `status: dispatched` (with `session_ref`, `worker_id`,
+`wave_id`, `last_update`) and increment `spawned` and `in_flight` together; if the dispatch fails to
+start, leave the row `pending` and advance neither counter. Decrement `in_flight` when a unit leaves
+`dispatched` (it reaches a terminal state, or returns to `needs-decision`/`blocked`/`stalled`) so
+queued units can start. This keeps `in_flight` equal to the count of `dispatched` rows that Step 0
+recomputes.
+
+Each worker prompt should be self-contained. Include:
+
+- The mission and exact scope (and its `unit_key`)
+- Files, subsystems, issue/PR links, and branch expectations
+- What the worker may and may not change
+- Verification commands or acceptance criteria
+- Whether it may create commits, PRs, or only report back
+- The required result block
+
+Worker prompt template:
+
+```text
+You are worker <name> for <project>.
+
+Mission: <specific outcome>
+unit_key / wave_id: <key> / <wave>
+Scope: <files/subsystems/issue/PR>
+Do not touch: <boundaries>
+Approach: <expected plan or constraints>
+Verification: <commands/checks/evidence>
+
+You MAY use your own subagents for local research, implementation, and review, but you remain
+accountable for this scope and the final report. Do NOT create or steer further persistent project
+sessions — if the work needs another full workstream, say so in next_step.
+
+End your report with a fenced ```json control-result block (see the contract). Populate every field;
+record subagents you used in subagents_used. The control session reads only that block.
+```
+
+When using Codex app controls, prefer to rename and pin important worker/control threads so the
+session graph stays legible. When using GitHub Copilot app controls, use the corresponding session or
+workspace labels if exposed.
+
+### 5. Track state centrally
+
+The control-state manifest is the single source of truth — update it every turn, not the
+conversation. From each worker's result block, set the unit's `status`, `branch_or_pr`,
+`last_update`, and `evidence_ref`. Keep the control session's context focused on summaries and
+decisions, not full transcripts; the full report lives at `report_ref`.
+
+Track at least, per unit: `unit_key`, `worker_id`, `session_ref`, scope, status, branch/PR, last
+update, blocker, and verification state. Canvas nodes or a SQL/todo table are good backends for the
+manifest when the app exposes them.
+
+### 6. Route follow-ups (result-gate)
+
+When a worker reports, first run the **result-gate**:
+
+- Parse the `control-result` block. If a required field is missing or malformed, or the status is
+  inconsistent with evidence (e.g. `status: complete` with `verification.result != pass`), do NOT
+  accept it — send exactly one standardized re-prompt asking only for the corrected block. Cap at 2
+  retries, then escalate to the user.
+- Accept completed work only when the block validates AND meets the success criteria.
+
+Then route:
+
+- Send targeted follow-ups for missing verification, scope drift, or blockers.
+- Avoid duplicating a worker's investigation unless its result is incomplete or suspect (check the
+  unit ledger first).
+- If two or more workers conflict, pause integration and resolve ownership before more edits happen.
+
+### 7. Iterate waves to convergence
+
+For multi-wave missions, after routing a wave's follow-ups, apply the declared `convergence.rule`
+before consolidating:
+
+- **single-pass** — one wave; skip to consolidate.
+- **loop-until-dry** — keep opening units until `k_empty` consecutive waves produce zero *new*
+  (deduped) units; maintain `empty_streak` in the manifest.
+- **loop-until-budget** — stop when a budget cap is hit.
+- **accumulate-to-target** — stop when the target count/coverage is reached.
+
+"New" and "dry" are measured against the manifest's set of `unit_key`s, not memory. Never stop
+silently — write why iteration ended (`open_followups` / `decisions`).
+
+### 8. Verify and consolidate
+
+Before declaring the mission done:
+
+- Run or delegate the agreed verification gate.
+- Review diffs or ask an independent reviewer session for high-signal findings.
+- Ensure worker outputs are integrated in the right branch/session.
+
+**Wave-join / completeness gate:** the mission is complete only when **every** manifest worker row is
+in a **terminal** state — `complete`, `failed`, or `dropped`. Non-terminal rows (`pending`,
+`dispatched`, `needs-decision`, `blocked`, `stalled`) must first be resolved; a unit that cannot be —
+e.g. a worker that never reported by its checkpoint, marked `stalled` — must be explicitly converted
+to `dropped` with a reason. Only then may the mission be declared *"complete with N dropped: <ids +
+reasons>"*. Never close with a non-terminal row, and never drop silently. Enumerate every dispatched
+unit in the final summary.
+
+**Pull cadence (no push signal):** a session-native control plane has no "worker done" event to wake
+it. After dispatching a wave, define the next checkpoint trigger — a follow-up turn, a status-table
+poll, or a user ping — and never leave a wave un-joined.
+
+For PR-bound work, keep the control session responsible for final PR readiness and review routing.
+
+## Safety rules
+
+- Do not spawn workers for trivial tasks.
+- Do not let multiple workers edit the same files unless explicitly coordinated.
+- Do not assume a named app connector exists; discover it and fall back honestly.
+- Do not silently create branches, commits, pushes, or PRs; follow the user's consent and repo rules.
+- Do not ask workers to share secrets or sensitive data across sessions.
+- Worker subagents are leaf helpers — they MUST NOT create or steer further persistent sessions. The
+  hierarchy is exactly two levels (control -> worker -> subagents); a worker that needs another full
+  workstream reports that need to control.
+- Enforce the concurrency and total-fan-out caps; never exceed them silently. Dropped, skipped, or
+  failed units MUST be recorded with a reason (no silent truncation).
+- If using an in-place checkout, be extra careful: other user-owned changes may already exist.
+- If the plan changes materially, update the user and the workers before continuing.
+
+## Recommended reporting format
+
+Use a compact control-plane update (rows derived from the manifest):
+
+```markdown
+**Status:** <on track | blocked | needs decision | complete>
+**Budget:** in-flight <X/Y> · spawned <A/B> · wave <N> (empty-streak <E>)
+
+| Workstream | Session | Scope | State | Evidence |
+|---|---|---|---|---|
+| <name> | <id/name> | <scope> | <state> | <test/report/PR> |
+
+**Decision needed:** <only if blocked>
+```
+
+Keep user-facing updates concise. The control session should make coordination legible, not flood the
+user with every worker's transcript.

package/skills/control-session-orchestrator/evals/evals.json

@@ -0,0 +1,75 @@
+{
+  "skill_name": "control-session-orchestrator",
+  "evals": [
+    {
+      "id": 1,
+      "name": "multi-session-audit",
+      "prompt": "Act as the pmx-canvas control session and coordinate a workflow to audit MCP tool parity across server, HTTP API, SDK, and docs. Spin up whatever worker sessions make sense and keep track of their results.",
+      "expected_output": "The agent should use the control-session-orchestrator skill, define a control-plane topology, assign scoped worker sessions for independent surfaces, specify reporting and verification expectations, and track status centrally instead of trying to audit everything inline.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "implementer-and-verifier",
+      "prompt": "We need a safe parallel workflow for a risky canvas refactor: one agent should implement, another should independently review and verify. Please coordinate it from this session.",
+      "expected_output": "The agent should use the skill to frame mission, create or route to separate implementer and verifier sessions, prevent overlapping scope drift, require verification evidence, and consolidate the final decision in the control session.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "codex-control-thread",
+      "prompt": "Use this Codex app thread as the pmx-canvas control session. Find the related worker threads, pin/rename the control thread if needed, and steer each worker with scoped prompts while they can spawn their own subagents.",
+      "expected_output": "The agent should use the control-session-orchestrator skill, identify Codex app thread/session tools as the active control surface, avoid assuming GitHub Copilot-only tool names, define worker ownership and reporting, and keep central status in the control thread.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "name": "avoid-over-orchestration",
+      "prompt": "Fix the typo in the README heading.",
+      "expected_output": "The agent should not use heavyweight control-session orchestration. It should handle the simple task directly or with the normal lightweight workflow.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "name": "rehydrate-after-handover",
+      "prompt": "You're taking over as the control session for an in-progress multi-session migration. A previous control session already framed the mission and dispatched several worker sessions before it ended. Pick up where it left off.",
+      "expected_output": "The agent should run Step 0 (Rehydrate): locate and load the control-state manifest as the source of truth, re-attach to workers by session_ref, and reconcile each worker's real status before any new dispatch. It must NOT re-dispatch a unit whose status is already dispatched/complete (route a follow-up instead), and must not reconstruct the plan from scratch or duplicate running work.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "name": "result-gate-rejects-unverified-report",
+      "prompt": "A worker session you dispatched just reported back: 'Done, the refactor looks good and tests should pass.' Decide whether to accept it and mark the workstream complete.",
+      "expected_output": "The agent should NOT accept the report. Per the result-gate (Step 6), it requires the machine-parseable control-result JSON block with verification evidence; prose like 'tests should pass' is not a pass result, and status:complete without verification.result:pass is inconsistent. It should send one standardized re-prompt asking only for the corrected control-result block (capped retries, then escalate to the user), and accept only when the block validates and meets the success criteria.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "name": "respect-concurrency-and-total-caps",
+      "prompt": "Coordinate a parity audit across 20 independent endpoints; spin up worker sessions to cover them all.",
+      "expected_output": "The agent should set a budget in the manifest (max_concurrent_workers, e.g. 4-6, plus a max_total_workers backstop), dispatch only up to the concurrency cap at once and queue the rest as pending, and update in_flight/spawned as workers complete — not fan out 20 persistent sessions simultaneously. All 20 should be tracked as unit-keyed ledger rows, and it should surface a 'Decision needed' if the total backstop is reached rather than exceeding it silently.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "name": "wave-join-completeness-gate",
+      "prompt": "Most of the audit workers have reported back. Two never responded. Can we call the audit complete and write up the result?",
+      "expected_output": "No. Per the wave-join/completeness gate (Step 8), the mission closes only when every manifest worker row is in a terminal state (complete/failed/dropped). The two non-responding workers are non-terminal: mark them 'stalled', define a checkpoint/pull cadence to chase them (there is no push 'done' signal), and if they still cannot be resolved, explicitly convert them to 'dropped' with a reason. Only then may the agent declare 'complete with N dropped: <ids + reasons>'. It must never close with a non-terminal row or drop work silently.",
+      "files": []
+    },
+    {
+      "id": 9,
+      "name": "convergence-stop-rule",
+      "prompt": "Run an open-ended workflow to find and fix every flaky test across the repo — keep going until they are all handled.",
+      "expected_output": "The agent should declare an explicit convergence rule up front (e.g. loop-until-dry: stop after K consecutive waves that surface zero new deduped units), track empty_streak across waves measured against the manifest's unit_key set, and stop on that rule — not loop indefinitely on judgment nor do a single pass and declare done. It should record why iteration ended and never stop silently.",
+      "files": []
+    },
+    {
+      "id": 10,
+      "name": "two-level-hierarchy-guard",
+      "prompt": "One of your worker sessions reports that the task is bigger than expected and wants to spin up its own set of persistent project sessions to parallelize further. How should that be handled?",
+      "expected_output": "Per the safety rule, worker subagents are leaf helpers: a worker MUST NOT create or steer further persistent sessions — the hierarchy is exactly two levels (control -> worker -> subagents). The worker should report the need (e.g. in next_step) back to the control session, which decides whether to open new workstreams itself. Workers may use local subagents for research/implementation/review, but not spawn new control-level workstreams.",
+      "files": []
+    }
+  ]
+}

package/skills/data-analysis/SKILL.md

@@ -35,6 +35,12 @@ In `pmx-canvas`, prefer `canvas_add_graph_node` for charts and trend lines and
 `canvas_add_json_render_node` when the analysis should land as a richer dashboard or table inside
 the canvas.
 
+For chart design and color choices, apply the `tufte-viz` skill (`skills/tufte-viz/SKILL.md`): color
+must encode data, not decorate. Single-series bar charts default to one accent with the key bar
+highlighted (`colorBy: series`); opt into `category`/`value` only when color carries a variable.
+Prefer `sparkline`/`dot-plot`/`bullet`/`slopegraph` and direct labels over legends; use small
+multiples for more than ~4 overlapping series.
+
 ## When to Use
 
 - Answering quantitative questions about engineering performance, delivery, or team health

package/skills/pmx-canvas/SKILL.md

@@ -181,6 +181,10 @@ pmx-canvas node list --type external-app --summary
 pmx-canvas pin --list
 pmx-canvas ax context
 pmx-canvas ax focus <node-id>
+pmx-canvas ax work add --title "Wire up auth" --status in-progress <node-id>
+pmx-canvas ax approval request --title "Deploy to prod"
+pmx-canvas ax steer "focus on the failing test first"
+pmx-canvas ax timeline --limit 50
 pmx-canvas snapshot save --name "before-refactor"
 pmx-canvas code-graph
 pmx-canvas spatial
@@ -202,6 +206,15 @@ pmx-canvas spatial
   `focus --no-pan` when you only need to select/raise a node without hijacking the human's camera.
 - `ax status|context|focus` — inspect the host-agnostic AX layer; `ax context`
   combines pinned context and AX focus for adapter prompt injection.
+- `ax event add`, `ax steer`, `ax evidence add`, `ax timeline` — the AX timeline
+  (agent-events, steering messages, evidence). Persisted for diagnostics,
+  retention-bounded, and excluded from snapshots.
+- `ax work add|update|list`, `ax approval request|resolve|list`,
+  `ax review add|list` — canvas-bound AX state (work items, approval gates,
+  review annotations) that rides snapshots and restore and is cleared by `clear`.
+- `ax host report|status` — report/read the host/session capability (own partition).
+- `copilot install-extension [--dry-run] [--yes]` — install the bundled GitHub
+  Copilot adapter into a repo; the core stays host-agnostic.
 - `fit [id ...]` — set the server viewport to fit the whole canvas or selected nodes before screenshots or whole-board review
 - `screenshot --output <path>` — top-level shortcut for `webview screenshot`; supports `--format png|jpeg|webp` and `--quality`
 - `json-render --schema|--examples` — inspect the json-render component catalog with `--component`/`--field` filters; same data as `node schema --type json-render` in a more direct shape
@@ -252,7 +265,7 @@ The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_UR
 | `trace` | Trace/timeline viewer | Execution traces, timelines |
 | `mcp-app` | Hosted app/embed frame | Tool-backed MCP apps or external app content; not generic CLI-created notes |
 | `json-render` | Native structured UI panel | Dashboards, forms, tables, interactive layouts from json-render specs |
-| `graph` | Native chart panel | Line, bar, pie, area, scatter, radar, stacked-bar, and composed charts rendered inside the canvas |
+| `graph` | Native chart panel | Line, bar, pie, area, scatter, radar, stacked-bar, composed, plus Tufte primitives (sparkline, dot-plot, bullet, slopegraph) rendered inside the canvas |
 | `html` | Sandboxed HTML+JS document | Self-contained HTML with optional inline `<script>` and CDN imports rendered in a sandbox-restricted iframe; canvas theme tokens are auto-injected |
 | `group` | Spatial container/frame | Visually group related nodes together |
 | `prompt` | Prompt thread root | Canvas-native prompt entry points for agent conversations. **Internal type — surfaces in `canvas://layout` for thread rendering but is not created via the public `canvas_add_node` API. Don't try to add one directly.** |
@@ -364,19 +377,47 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
   `outline`. Legacy `props.label` and status variants (`success`, `info`, `warning`, `error`,
   `danger`) are normalized for saved-spec compatibility.
 
+**`canvas_stream_json_render_node`** — Build a json-render node progressively (live)
+- Omit `nodeId` on the first call to create a new streaming node — it returns the node `id`
+- Pass that same `nodeId` on later calls to append more `patches`; set `done: true` on the final call
+- `patches` are SpecStream JSON-Patch ops applied server-side (the canvas accumulates the spec):
+  `{ "op": "add", "path": "/elements/card", "value": { "type": "Card", "props": { "title": "Live" }, "children": [] } }`,
+  `{ "op": "replace", "path": "/root", "value": "card" }`,
+  `{ "op": "add", "path": "/elements/card/children/-", "value": "row1" }`
+- Build incrementally: set `/root`, add container elements, then append child element ids and elements
+- Each call re-renders the live node; partial specs render what they can. Use for dashboards/reports
+  that should fill in as you generate them rather than appearing all at once.
+
 **`canvas_add_graph_node`** — Add a native graph/chart node
 - Required: `graphType`, `data`
-- Supports `line`, `bar`, `pie`, `area`, `scatter`, `radar`, `stacked-bar`, and `composed`
-  graph types (aliases accepted)
+- Supports `line`, `bar`, `pie`, `area`, `scatter`, `radar`, `stacked-bar`, `composed`,
+  and the Tufte primitives `sparkline`, `dot-plot`, `bullet`, `slopegraph` (aliases accepted)
 - Use `xKey`/`yKey` for line, bar, area, and scatter graphs
 - Use `zKey` for scatter bubble size
 - Use `nameKey`/`valueKey` for pie graphs
 - Use `axisKey` plus `metrics` for radar graphs
 - Use `series` for stacked-bar graphs
 - Use `barKey`/`lineKey` plus optional `barColor`/`lineColor` for composed graphs
+- Bar charts: `colorBy` (`series` default = one accent + a highlighted bar, `category`, `value`, `none`) and `highlight` (`max`/`min`/index)
+- Use `valueKey` for `sparkline` (plus `fill`/`showEndDot`/`showMinMax`/`showValue`)
+- Use `labelKey`/`valueKey` (plus `sort`) for `dot-plot`
+- Use `labelKey`/`valueKey`/`targetKey`/`rangesKey` for `bullet`
+- Use `labelKey`/`beforeKey`/`afterKey` (plus `beforeLabel`/`afterLabel`/`colorByDirection`) for `slopegraph`
 - Use `nodeHeight` for the canvas frame height and `height` for chart content height
 - Uses the native json-render chart catalog under the hood
 
+**Tufte-aware charting** — color must encode data, not decorate. For chart design and critique, use
+the `tufte-viz` skill (`skills/tufte-viz/SKILL.md`). Key rules:
+- Single-series `bar` charts use `colorBy`: default `series` (one accent + one highlighted bar),
+  `category` (opt-in palette), `value` (sequential shade by magnitude), or `none` (flat). Do not
+  rainbow categorical bars by default.
+- Prefer the Tufte primitives where they fit: `sparkline` (inline trend), `dot-plot` (ranked single
+  metric vs. a bar forest), `bullet` (measure vs. target, replaces a gauge), `slopegraph`
+  (before/after across many categories).
+- Direct-label data (`showLegend: false`) instead of a legend when one or two series are identifiable.
+- For more than ~4 overlapping series, build small multiples (several small graph nodes on a shared
+  scale, arranged in a grid/group) instead of one multi-color chart.
+
 **`canvas_build_web_artifact`** — Build and optionally open a bundled web artifact
 - Required: `title`, `appTsx` (source string contents, not a file path)
 - CLI `--app-file` reads a file before calling the same build path; MCP callers must pass the source contents
@@ -682,7 +723,7 @@ server's `ui://` resource as an iframe node on the canvas
 ### HTML Nodes (Sandboxed iframe)
 
 **`canvas_add_html_node`** — Add a normal self-contained HTML document rendered in a sandboxed iframe
-- Required: `html` (full document or fragment; inline `<script>` and CDN `<script src="...">` are allowed)
+- Required: `html` (full document or fragment; inline `<script>` and CDN `<script src="...">` are allowed). If `html` is a bare path to an existing local `.html`/`.htm` file, the server reads that file's contents; otherwise it is treated as raw HTML.
 - Optional: `title`, `summary`, `agentSummary`, `presentation`, `slideTitles`, `embeddedNodeIds`, `embeddedUrls`, `x`, `y`, `width` (default 720), `height` (default 640), `strictSize`
 - Iframe sandbox is `allow-scripts` only — no same-origin access, no top-navigation, no forms
 - Canvas theme tokens are auto-injected as CSS custom properties (both `--c-*` and common `--color-*` aliases such as `--color-text-primary`, `--color-bg`, `--color-accent`) and updated live when the canvas theme changes
@@ -734,6 +775,10 @@ what the human has set up and what they're focusing on.
 | `canvas://spatial-context` | Proximity clusters, reading order, pinned neighborhoods |
 | `canvas://history` | Human-readable mutation timeline |
 | `canvas://code-graph` | Auto-detected file import dependencies (JS/TS, Python, Go, Rust) |
+| `canvas://ax` | Host-agnostic AX state: focus, work items, approval gates, review annotations, host capability |
+| `canvas://ax-context` | Agent-ready AX context: pinned context + current focus |
+| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations |
+| `canvas://ax-timeline` | Bounded AX timeline: recent agent events, evidence, and steering messages |
 | `canvas://skills` | Index of bundled agent skills shipped with the install. Each skill is also addressable as `canvas://skills/<name>` (e.g. `canvas://skills/web-artifacts-builder`) and returns the full SKILL.md. Read this resource first to discover companion workflows the canvas is built to support. |
 
 ### Reading Spatial Intent
@@ -777,6 +822,7 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 | GET | `/api/canvas/pinned-context` | Get current pins with neighborhood context |
 | GET | `/api/canvas/search?q=...` | Search nodes |
 | POST | `/api/canvas/json-render` | Create a native json-render node |
+| POST | `/api/canvas/json-render/stream` | Create/append a streaming json-render node (SpecStream patches) |
 | POST | `/api/canvas/graph` | Create a native graph node |
 | GET | `/api/canvas/schema` | Get running-server create schemas, examples, and json-render catalog metadata |
 | POST | `/api/canvas/schema/validate` | Validate a json-render spec or graph payload without creating a node |

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -83,6 +83,12 @@ The adapter rejects an unrelated running PMX server unless `serverUrl` is explic
 | `get_ax_context` | Return current pinned + focused AX context. |
 | `focus_nodes` | Set AX focus with `source: "copilot"`. |
 | `send_instruction` | Send an explicit prompt into the active Copilot session. |
+| `add_work_item` | Create a canvas-bound AX work item. |
+| `request_approval` | Open an approval gate (`pending`) before a high-impact action. |
+| `resolve_approval` | Resolve an approval gate as approved/rejected. |
+| `add_review_annotation` | Record a review comment/finding anchored to a node/file/region. |
+| `get_timeline` | Read the bounded AX timeline (events, evidence, steering). |
+| `report_capability` | Report host capabilities for diagnostics. |
 
 Example focus action: