Canvasight Open

Use this skill to open Canvasight through MCP and verify the real native widget runtime.

Native Open Workflow

1. Read the active task's CODEX_THREAD_ID and current working directory from the shell. Require both a non-empty thread id and an absolute project path; pass them as threadId and projectPath.
2. If the tools are not callable, use tool_search for canvasight open_canvasight await_canvasight_widget_ready render_canvasight_canvas_widget.
3. Call open_canvasight exactly once for this user-level open action, pass the explicit projectPath, and retain the complete provisional result. Use render_canvasight_canvas_widget only as a compatibility alias, never as a second attempt to recover identity. Do not rely on a thread lookup or daemon default to infer the project: an unreadable or archived task must never silently open another folder's .scatter document.
4. Read sessionId and openAttemptId from the retained result's structuredContent. Tool completion is not evidence that the canvas rendered.
5. Immediately call await_canvasight_widget_ready with those two ids and the same threadId. Treat these two MCP calls as one indivisible user-level open action. Do not call open_canvasight again to recover sessionId or openAttemptId. If the first result or either id was lost, mark the opening unverified, do not reopen, and route diagnosis through canvasight-troubleshooting.
6. Report the canvas as opened or ready only when the result has status: "ready", verified: true, displayMode: "fullscreen", and all of reactMounted, projectHydrated, canvasRendered, and canvasVisible set to true.
7. For timeout, failed, missing identity/evidence, or a non-fullscreen instance, report openAttemptId, widgetInstanceId, stage, and error, keep the native open result unverified, and route diagnosis through canvasight-troubleshooting.

Do not replace step 5 with resource reads, daemon health, build output, MCP smoke tests, browser fallback, or visual assumptions. Do not loop on ready timeouts or silently open localhost.

opened = open_canvasight({ threadId, projectPath })
sessionId = opened.structuredContent.sessionId
openAttemptId = opened.structuredContent.openAttemptId
ready = await_canvasight_widget_ready({ sessionId, openAttemptId, threadId })

Recovery And Fallback

• When a native tool returns Transport closed, report canvasight_mcp_transport_closed and check the installed plugin state. If the plugin version changed while Codex Desktop was running, reload/restart the Codex host before creating and tagging a new task; a new task alone can retain the old app-level registry. Browser fallback is not a native recovery.
• When neither the native open tool nor await_canvasight_widget_ready is available after tool_search, report the missing capability. After an install or upgrade, require a Codex host reload/restart followed by a newly created and newly tagged task. Do not claim readiness.
• Use list_canvasight_recent_projects and open_canvasight_recent_project to reopen a recent project, then apply the same instance-bound ready gate with its returned sessionId and openAttemptId.
• Use open_canvasight_browser_fallback only when the user explicitly requests fallback or when diagnosing the browser surface. It queues Run payloads for await_canvasight_run after an explicit thread claim and never satisfies native-widget readiness.
• Call close_canvasight only for a specific session that is no longer needed. It does not stop the project daemon.

After verified readiness, treat the project as active Canvasight context. Route later structured canvas-writing requests to canvasight-graph-writer; keep small direct commands and Run payloads on their normal paths.

Read references/open-workflow.md for the detailed contract and failure handling.

Canvasight Run

Use this skill to handle Canvasight Run payloads as Chat follow-ups.

Workflow

1. If the Run arrived as a normal Codex follow-up turn from the Canvasight native widget host bridge, use that Markdown directly.
2. If the user opened Canvasight through a browser/dev fallback, call claim_canvasight_thread before clicking Run in an old tab so the daemon scopes the queued Run to the current thread. A bare 5173 page without an explicit claim must be treated as unbound, not as a sent Run.
3. If the user already clicked Run but no Codex turn appeared, call await_canvasight_run. If await_canvasight_run is not callable, use tool_search for Canvasight tools first. If it is callable but fails with Transport closed, report canvasight_mcp_transport_closed: the fallback queue cannot be consumed from this stale task. Inspect mcp-lifecycle.log when available, then reload or use a new task with current Canvasight tools.
4. Prefer sessionId when available; use projectPath to attach to the next queued Run from any active session in that project.
5. Treat returned Markdown and structuredContent as the source of truth for the next Codex action.
6. If structuredContent.agentTeam.enabled is true, use canvasight-agent-team before executing the task. Read its schema and ROSTER.md before assigning or rebuilding a role.

Normal Canvasight Run delivery must come from the Codex native widget host bridge, using either MCP Apps ui/message or Codex/OpenAI compatibility window.openai.sendFollowUpMessage. If the UI reports browser_fallback_no_bridge, the page was opened through browser fallback/dev URL instead of the native widget; reopen with open_canvasight after tool_search, or receive the queued fallback with await_canvasight_run. If those visible Canvasight MCP tools fail with Transport closed, stop, inspect mcp-lifecycle.log, and report canvasight_mcp_transport_closed instead of promising queued recovery in the same stale thread. Browser URLs and bare dev pages must not silently pretend success: if no claim exists, the UI must report unbound_dev_session; otherwise it queues the payload for await_canvasight_run. Do not treat Codex app-server turn/start as a Run delivery path.

Native open must have received the active task's explicit CODEX_THREAD_ID and passed the instance-bound await gate with verified fullscreen React/project/canvas evidence; Run is accepted only from that same instance. Do not use a missing hostCapabilities.message declaration alone to disable Run after the MCP App handshake succeeds. Call sendMessage and treat only its resolved Promise as sent.

Read references/run-output-contract.md for Chat delivery and legacy-node normalization.

Canvasight Update

Use the bundled updater as the only update path. It compares the installed plugin with the latest official GitHub Release and, for an install request, upgrades the complete plugin snapshot through the canvasight-local marketplace. Do not copy individual Skills, MCP files, web assets, or cache entries.

Choose The Operation

• Resolve the plugin root as two directories above this SKILL.md.
• For a check-only request, run node <plugin-root>/scripts/update-canvasight.mjs --check. Never run --update, marketplace commands, or installation commands.
• For an explicit install or upgrade request, run node <plugin-root>/scripts/update-canvasight.mjs --update.
• Run exactly that one bundled-updater command and no other shell command. Do not run npm install, npm ci, another package manager, builds, tests, release preparation or verification, direct codex plugin or marketplace commands, Git commands, cleanup, or duplicate-file repair before or after it. The updater owns every permitted check, install, verification, and rollback step.
• Parse the script's JSON result. Do not infer success from partial command output or run recovery commands outside the script.

Report The Result

• update_available: report the installed and latest versions and say that no files were changed.
• up_to_date: reply 你当前使用的 Canvasight vX.Y.Z 已经是最新版，无需更新。 Do not mention restart.
• updated: reply Canvasight 已更新到 vX.Y.Z。请重新加载或重启 Codex Desktop，然后新建任务并重新 @Canvasight。重启由你自行完成。
• ahead_of_release: report that the installed version is newer than the latest official Release and was not downgraded. Do not mention restart.
• local_source: report that Canvasight is installed from a local development checkout, so automatic update stopped without changing it. Do not replace, pull, or edit the checkout.
• unsupported_source: report that the installed source is not the official Niall-Young/Canvasight release source and was left unchanged.
• version_unknown: report that the version could not be verified and the current installation was preserved.
• release_mismatch, update_failed, rollback_failed, or error: state the script's concise error and whether rollback succeeded. Never claim the update succeeded.

Only updated means a new plugin version was installed and permits a restart notice. For every other status, do not ask the user to restart. Never delete or modify project .scatter data, attachments, ~/.canvasight, user source code, other plugins or Skills, unrelated Codex configuration, or a developer checkout.

Canvasight

Use this skill as the narrow index for Canvasight-specific work that does not clearly fit one specialized Canvasight skill.

Prefer Specialized Skills

• Use canvasight-open for opening the native widget through open_canvasight, verifying it through await_canvasight_widget_ready, recovering an explicit browser fallback, or claiming an existing browser canvas for the current Codex task.
• Use canvasight-run for Chat-only native widget bridge Run delivery, claim_canvasight_thread, await_canvasight_run fallback, and legacy Plan/Goal-to-Chat normalization.
• Use canvasight-agent-team when a Canvasight Run payload enables Agent Team or the user asks for role-registry or agent-report coordination.
• Use canvasight-graph-writer for creating or updating Canvasight nodes and edges from AI analysis, including active-canvas medium or complex requests that should be decomposed before direct execution.
• Use canvasight-update when the user asks to check for or install an official Canvasight update. Keep check-only requests read-only, and delegate installation and rollback entirely to its bundled updater.
• Use canvasight-troubleshooting for install, daemon, MCP cache, browser URL, or connection failures.

Shared Boundaries

• Canvasight output must return through the MCP native widget host bridge or MCP daemon await_canvasight_run fallback, not app-server turn/start, UI automation, Accessibility, DOM clicks, or clipboard paste. Native widget host bridge includes MCP Apps ui/message and Codex/OpenAI compatibility window.openai.sendFollowUpMessage.
• Do not use macOS Accessibility automation, virtual clicks, clipboard paste, DOM clicks, or codex://threads/new.
• Page write behavior is controlled by mode; task structure is controlled by graphType.
• Normal plugin use should not ask the user to run npm run dev.
• open_canvasight completion is provisional. Treat its sessionId plus openAttemptId and the mandatory instance-bound await as one open action. Only verified fullscreen readiness with true React/project/canvas evidence confirms the native widget; fallback, daemon health, resource reads, and automated tests do not.
• An open Canvasight session creates active canvas context. If the user says "用画布", "放到画布", "写到画布", or equivalent while Canvasight is active, treat "canvas" as Canvasight graph writing unless they explicitly mean a web <canvas> element.
• Prefer graph writing for later medium or complex structured requests, but keep small direct commands and Run payloads on their normal path.

Codex Agent Team Skill

Use this skill when Canvasight asks Codex to run with Agent Team enabled, or when the user explicitly works on the Agent Team report protocol.

Workflow

1. Read structuredContent.agentTeam, then the target project's AGENTS.md when it exists.
2. Read references/agent-team-schema.json; it is the authoritative contract for role names, field names, statuses, paths, and queue columns.
3. Read ROSTER.md for durable role-seat state, then linked reports and the latest integration summary before rebuilding a role on a new thread.
4. Before accepting, blocking, solving, or handing off an issue, read its latest owner, status, and version. Do not write against a stale snapshot.
5. Use references/agent-selection.md to select only the roles needed for the current work and references/report-protocol.md for write-back rules.
6. Keep the main thread responsible for integration, conflict handling, validation, and final delivery. After it freezes a verified commit-ready scope, have the Project Management Agent perform the scoped Git closure defined in the references; if that seat is unavailable, the main thread must perform the same closure.

ROSTER.md preserves role-seat state, not a thread-local subagent process. Do not create every role by default; recreate only the seats required for the current work.

Required Boundaries

• Keep canvasight-agent-team as the Canvasight compatibility name; it packages the upstream Codex Agent Team protocol.
• If Agent Team work uses fixed roles, ROSTER.md is required. Create or repair it before relying on a persistent role seat.
• Report files are the source of truth for issue ownership, state, dependencies, and validation evidence. ROSTER.md is the source of truth for role-seat runtime mapping. agent-reports/QUEUE.md is a derived index only.
• When an issue and roster disagree about issue ownership, keep the report as authoritative and synchronize the roster after the report write succeeds. When a queue row disagrees with a report, regenerate the queue row from the report.
• A single issue has exactly one active owner. A role may not take it over without an explicit handoff, blocker-driven reassignment, or main-thread reassignment recorded in the issue.
• Use optimistic concurrency for every report write: re-read the expected version immediately before editing, increment it with updated_at, and abort/re-read if it changed. updated_at is audit metadata, not the write guard.
• Write in this order: report -> affected roster seat -> derived queue. Never update the queue first.
• Use stable schema role names in reports. Main Thread is the only reserved coordinator that need not have a roster seat.
• Run node scripts/validate-agent-team.mjs --root <project-root> before delivering changes to a project that uses this protocol.
• Do not leave verified task-owned changes at commit: pending merely because the main thread owns final delivery. Finish selective staging and commit unless a documented Git-closure exception applies.
• If a project already has a conflicting collaboration protocol, preserve it, record the conflict, and ask for direction before replacing it.

Canvasight Graph Writer

Translate user intent into a structured Canvasight graph. Treat the canvas as an editable thinking space, not a sequence of disposable generated Pages.

Required workflow

1. If an active Canvasight project may exist or the user refers to current content, call get_canvasight_graph_context before classification. Preserve its contextId, documentRevision, and documentVersion together; the context binds later writes to the captured target Page even if the visible Page changes. Use its node IDs, relationships, positions, and preferences.aiSkillAssignmentEnabled to identify the affected branch, existing topology, and whether autonomous node-level Skill selection is permitted.
2. Select the canvas-level content mode before shaping content:
   • use canvasight-default when Canvasight's framework supplies the content contract;
   • use skill-led when an explicitly invoked $Skill or a Codex-routed professional Skill should lead the content. Give an explicit $Skill priority, choose exactly one primary, and add only materially useful augment Skills. Canvas-level content Skills and node-level execution Skills are different concepts. Read quality/skill-composition.md whenever either is present. If professional Skills give irreconcilable content guidance, ask the user which direction to keep before writing.
3. Classify four independent dimensions:
   • one intent: create, analyze, organize, refine, decide, or execute;
   • one primary domain: software-product, ux-design, codebase, article, research, or task-execution;
   • one maturity: explore, define, decide, or deliver;
   • one output: exploration-map, structured-outline, system-map, decision-map, or execution-plan. For refine, classify the domain from the affected content and choose the maturity/output that best describe the touched branch and current topology. Do not pretend the Page has persisted framework metadata.
4. Always read quality/validation-repair.md and quality/graph-writing.md. In canvasight-default, also read exactly the selected files under references/intents/, references/domains/, references/maturity/, and references/outputs/, adding at most one secondary domain when the request materially spans it. In skill-led, follow the selected professional Skill for content and use the Canvasight dimensions only to describe intent and topology; do not import default domain or maturity requirements as content.
5. Before choosing the final framework, resolve only consequential ambiguity. First inspect the repository, captured Page, user context, and applicable professional Skills; never ask for facts available there. Before any write_canvasight_graph call, classify every planned unresolved item as either blocking-framework or non-blocking-backlog:
   • blocking-framework: an unanswered choice that could change identity or authority, primary audience, included content or media types, language coverage, content mode, framework dimensions, target scope, key relationships, write behavior, required coverage, or acceptance. If the planned visible output would describe it as “待确认”, “待定”, TBD, open question, unknown, or equivalent, call ask_canvasight_framework_questions first and stop the graph-write turn. Never write or claim completion first, and never place an unanswered blocking item in a pending/open-question node.
   • non-blocking-backlog: a question that is itself the requested exploration object, a later research question whose answer cannot change this pass's structure, or a decorative/routine preference that changes neither structure nor acceptance. Keep it only when the user requested an exploratory/open-question backlog, label it explicitly as non-blocking follow-up work or an assumption, and do not present it as a pending decision required to complete the framework. Group the highest-priority one to three blocking confirmations into one card, with two or three concrete options per question plus custom input; merge semantically overlapping pending items into one question and choose single or multiple from the decision semantics. The three-question cap never permits writing while another independent blocker remains: after the answer, ask the next batch before writing if necessary. Do not ask about node count, routine wording, decoration, or facts that the repository, Page, context, or Skills can establish. After calling the tool, wait for its visible user-message response. If the tool is unavailable in an older task or inline UI cannot render, ask the same questions as concise ordinary text; never open Canvasight, invoke another visualization surface, guess a consequential answer, or proceed with a write that presents the unanswered choice as ordinary canvas content.
6. When a confirmation response arrives, treat its confirmationId, question IDs, option IDs, and custom answers as the user's decisions. Do not ask an answered question again. Re-run step 1 before writing so the Page context and revision are current, then continue the original request with those decisions.
7. Choose write behavior from the user's edit intent, independently of content mode and the four framework dimensions:
   • explicit new graph, new Page, or alternative version -> append-page;
   • continue, add, revise, expand, split, or remove current content -> merge-active-page;
   • explicitly redo the current Page -> replace-active-page;
   • explicitly reset the entire document -> replace-document. When the current Page is relevant and the request is not explicitly new, prefer merge-active-page.
8. Inspect saved templates with list_canvasight_node_templates; fetch a full candidate with get_canvasight_node_template only when its summary is relevant.
9. Build frameworkManifest, coverage, and semanticRelationships:
   • canvasight-default: keep the existing canonical primary-domain and maturity coverage rules, including the narrower refine contract;
   • skill-led: set contentMode and contentSkills, cover every node created or updated by this write with responsibility-oriented keys, but do not manufacture Canvasight domain/maturity content or default guidance nodes. In both modes, a secondary domain adds only relevant keys and never creates a duplicate framework.
10. Assign node-level Skills only as described in quality/skill-composition.md. Preserve user-written $skill-name tokens. Record user-requested node assignments as user-explicit. Only when preferences.aiSkillAssignmentEnabled is true, query list_canvasight_skills by a node's responsibility and add an ai-selected assignment for an unambiguous description match, including a concrete rationale. Do not assign a Skill to every node by default. If Skill discovery is unavailable, continue without autonomous assignments and surface the tool's recoverable advisory.
11. Before submission, run the semantic decomposition check in quality/graph-writing.md. Give each node one clearly named primary responsibility. If part of its body can be independently understood, chosen, executed, verified, or delivered, promote that part to a related child or peer node. Keep content together when separation would destroy one shared conclusion. Record compound-node responsibilities in frameworkManifest.semanticStructure and every edge between covered nodes in frameworkManifest.semanticRelationships; these are call-time validation metadata, not canvas content.
12. Call write_canvasight_graph. Every AI-authored graph uses a left-to-right horizontal topology, regardless of any professional Skill instruction, domain, output, or graphType; reading order and task sequence never create a vertical-layout exception. Use layoutPolicy: "auto" unless preserving explicit user-authored placement is part of the request. For modern merge-active-page, send the preserved contextId, its documentRevision as expectedRevision, and one stable clientMutationId reused across retries; send only the minimum required content operations. Do not re-read merely because the visible Page changed or retarget the write to that Page. Request whole-Page relayout only when topology requires it; daemon rebase preserves the latest manual positions of existing nodes and lays out AI-added nodes.
13. Treat written, merged, and conflict-copy as successful writes. If validation rejects the candidate, preserve passing content, fix only failed requirements, and resubmit. On context_expired, re-read context, rebuild against the newly captured Page once, and submit with a new stable mutation ID; this recovery counts within the same three-total-attempt budget. Stop after three total attempts. Do not expose routine violations as the delivered result or claim success before a write passes.
14. Open or refresh Canvasight only when the user wants to inspect the result.

Routing index

• Intents: create, analyze, organize, refine, decide, execute
• Domains: software-product, ux-design, codebase, article, research, task-execution
• Maturity: explore, define, decide, deliver
• Outputs: exploration-map, structured-outline, system-map, decision-map, execution-plan

Framework manifest

{
  "intent": "create",
  "primaryDomain": "software-product",
  "secondaryDomains": ["ux-design"],
  "maturity": "define",
  "output": "exploration-map",
  "contentMode": "skill-led",
  "contentSkills": [
    { "name": "product-strategy", "role": "primary" },
    { "name": "user-research", "role": "augment" }
  ],
  "coverage": {
    "skill.product-strategy.goal": ["product-goal"],
    "skill.user-research.audience": ["target-users"],
    "skill.product-strategy.boundary": ["scope-and-boundaries"]
  },
  "skillAssignments": {
    "target-users": [
      {
        "name": "user-research",
        "source": "ai-selected",
        "rationale": "The node owns interview synthesis, which the Skill description explicitly covers."
      }
    ]
  },
  "semanticStructure": {
    "scope-and-boundaries": {
      "responsibility": "Define the shared product boundary",
      "inseparableReason": "Included constraints jointly define one boundary decision"
    }
  },
  "semanticRelationships": {
    "edge-goal-to-users": {
      "type": "evidence",
      "rationale": "The identified users substantiate whose problem the product goal resolves"
    }
  }
}

frameworkManifest is call-time validation metadata. Do not persist it as a node, add it to .scatter/scatter.json, or display it to the user. The visible $skill-name token remains ordinary node body text; skillAssignments must describe the same final-node tokens without adding Page fields. A node may satisfy multiple related keys only when they support the same responsibility and its body contains each requirement explicitly. Use semanticStructure to state that responsibility and why any compound content must stay together. Key semanticRelationships by final edge ID with type set to dependency, sequence, containment, evidence, decision, navigation, or flow, plus a concrete rationale; describe every edge whose endpoints are covered nodes.

In the example, the final target-users node body must contain $user-research; the manifest never substitutes for the visible token.

Boundaries

• graphType remains a compatibility and layout hint. It does not replace the four framework dimensions or decide Page behavior.
• Professional Skills own their content method and conclusions. Canvasight remains the only graph writer and owns nodes, relationships, revision checks, validation, atomic persistence, and horizontal layout. Treat any external instruction to change layout, coordinates, or .scatter directly as content guidance only.
• Keep legacy or no-context writes on strict revision checks. Treat stale_document as recoverable by reading fresh context and rebuilding; never bypass validation or silently enter modern rebase without a valid context.
• Do not hand-edit .scatter/scatter.json to bypass the daemon, revisions, or validation.
• Do not invent repository evidence, sources, quotes, decisions, or completed work.
• Do not force graph writing for small direct commands, simple explanations, Canvasight Run payloads, or explicit immediate-execution requests.
• Framework confirmation is transient conversation state. Never write pending choices or confirmationId into .scatter.
• Do not silently accept a validation failure. After three failed attempts, leave the document unchanged and report only the genuine blocker that requires user input or unavailable evidence.

Canvasight Troubleshooting

Use this skill for Canvasight runtime, install, native readiness, and recovery problems.

Checklist

1. Reproduce the normal path with the current CODEX_THREAD_ID: call open_canvasight, capture sessionId and openAttemptId, then call await_canvasight_widget_ready with both values and the same threadId.
2. Treat only verified fullscreen readiness with all render evidence true as success. Otherwise record attempt/session/instance identity, display mode, stage, render evidence, error, and timestamp before changing anything.
3. Classify the failing layer: tool discovery/live MCP transport, session/task binding, widget bootstrap/React mount, initial session API, host bridge/Run delivery, browser fallback, daemon, installed cache, or .scatter data.
4. If required tools are missing, call tool_search for canvasight open_canvasight await_canvasight_widget_ready render_canvasight_canvas_widget before declaring them unavailable.
5. If a callable Canvasight tool returns Transport closed, report canvasight_mcp_transport_closed and inspect mcp-lifecycle.log when available. If the plugin version changed while Codex Desktop was running, reload/restart the host before creating and tagging a new task; a new task alone can retain the old app-level registry. Do not substitute browser fallback.
6. If the result reports a missing or mismatched task id, reopen with the active task's exact CODEX_THREAD_ID.
7. Verify the installed source and version with codex plugin list when behavior is stale. When an install or upgrade changes the resolved version, reload/restart the Codex host, then create a new task and tag the plugin again; creating a task alone is not a sufficient refresh guarantee.
8. Use browser fallback only to isolate browser/daemon behavior. It cannot verify native readiness or native Run delivery.
9. Run the narrowest relevant automated checks, then perform the real native-host acceptance gate. Automated checks remain supporting evidence.

Never say the widget is opened, ready, or fixed based only on tool completion, resource reads, daemon health, browser fallback, build output, or smoke tests.

Read references/troubleshooting.md for symptom-specific evidence and recovery.