@runcofactor/cli 0.10.0

package/dist/skill-KM34LDMO.js

@@ -0,0 +1,1839 @@
+import { createRequire as __cr } from "module"; const require = __cr(import.meta.url);
+import "./chunk-VKVL7WBN.js";
+
+// src/skill.ts
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+
+// src/skill-templates/issue-log-xref.ts
+var issueLogXrefTemplate = {
+  name: "issue-log-xref",
+  description: "Cross-reference Canary issues with server logs to find root causes",
+  version: "1.0.0",
+  render: () => `---
+name: issue-log-xref
+version: 1.0.0
+description: Cross-reference Canary QA issues with server logs to identify root causes. Use when investigating why a test failed, correlating browser errors with backend logs, or debugging issues found by Canary.
+allowed-tools: Bash(canary issues:*), Bash(canary login:*), Grep, Read
+---
+
+# Issue Log Cross-Reference
+
+Cross-reference Canary-detected issues with server logs to identify root causes, correlate errors, and provide actionable debugging context.
+
+## Prerequisites
+
+- \`canary\` CLI installed and authenticated (\`canary login\`)
+- Access to server logs (see Log Source Configuration below)
+
+## Workflow
+
+### 1. Fetch issues from Canary
+
+List recent issues to find ones worth investigating:
+
+\`\`\`bash
+canary issues list --format markdown
+\`\`\`
+
+Use filters to narrow down:
+
+\`\`\`bash
+canary issues list --severity high --status open --format markdown
+\`\`\`
+
+### 2. Get issue details
+
+Once you identify an issue, fetch its full diagnostics:
+
+\`\`\`bash
+canary issues get <issue-id> --format markdown
+\`\`\`
+
+Note the following from the issue details:
+- **Timestamps** \u2014 when the issue was detected
+- **URLs / endpoints** \u2014 which pages or API routes were involved
+- **Error messages** \u2014 any visible error text captured in screenshots or DOM
+- **HTTP status codes** \u2014 failed network requests
+
+### 3. Access server logs
+
+<!-- ============================================================
+  LOG SOURCE CONFIGURATION
+
+  Replace {{LOG_SOURCE_INSTRUCTIONS}} below with instructions
+  specific to your infrastructure. The AI agent reading this
+  skill will use these instructions to fetch logs.
+
+  Examples:
+
+  **AWS CloudWatch:**
+  Query CloudWatch Logs Insights for the relevant log group:
+  \`\`\`bash
+  aws logs filter-log-events \\
+    --log-group-name /ecs/my-api \\
+    --start-time <epoch-ms> \\
+    --end-time <epoch-ms> \\
+    --filter-pattern "<error-text>"
+  \`\`\`
+
+  **Local log files:**
+  Search local log files for matching entries:
+  \`\`\`bash
+  grep -i "<error-text>" /var/log/my-app/*.log
+  \`\`\`
+
+  **Datadog:**
+  Use the Datadog CLI or API to query logs:
+  \`\`\`bash
+  dog logs list --query "service:my-api status:error" \\
+    --from <ISO-timestamp> --to <ISO-timestamp>
+  \`\`\`
+
+  **kubectl (Kubernetes):**
+  Fetch pod logs for the relevant service:
+  \`\`\`bash
+  kubectl logs -l app=my-api --since=1h | grep "<error-text>"
+  \`\`\`
+============================================================ -->
+
+{{LOG_SOURCE_INSTRUCTIONS}}
+
+### 4. Cross-reference and correlate
+
+Match the Canary issue with log entries using these correlation points:
+
+- **Timestamps** \u2014 find log entries within a few seconds of the issue detection time
+- **Error messages** \u2014 search logs for the same error text shown in the issue
+- **HTTP status codes** \u2014 look for 4xx/5xx responses matching the failed requests
+- **URLs / routes** \u2014 filter logs by the endpoint or page path from the issue
+- **Stack traces** \u2014 identify the code path that produced the error
+- **Request IDs** \u2014 if your app uses correlation/request IDs, trace the full request lifecycle
+
+## Analysis Guidelines
+
+When presenting findings:
+
+1. **State the match confidence** \u2014 clear match, likely match, or circumstantial
+2. **Show the timeline** \u2014 lay out events in chronological order across both sources
+3. **Identify the root cause** \u2014 distinguish between the symptom (what Canary caught) and the cause (what the logs reveal)
+4. **Suggest next steps** \u2014 point to the specific code, service, or configuration that needs attention
+5. **Note gaps** \u2014 if logs are missing or incomplete, say so explicitly rather than speculating
+`
+};
+
+// src/skill-templates/browser-testing.ts
+var browserTestingTemplate = {
+  name: "browser-testing",
+  description: "Use the Canary CLI to control a browser for testing web applications",
+  version: "1.0.0",
+  render: () => `---
+name: browser-testing
+version: 1.0.0
+description: Control a local browser via the Canary CLI to test web applications interactively. Use when the user asks to test, browse, interact with, or verify a web application using canary browser sessions.
+allowed-tools: Bash(canary session:*), Bash(canary login:*), Bash(canary workflow:*), Bash(canary credential:*), Read
+---
+
+# Browser Testing with Canary
+
+Use the \`canary session\` CLI to launch and control a local browser for testing web applications. You interact with pages through **snapshots** (accessibility tree + screenshot), then issue commands to click, type, navigate, and assert.
+
+## Prerequisites
+
+- \`canary\` CLI installed and authenticated (\`canary login\`)
+- Run \`canary session --help\` for the full command reference
+
+## Environments & Authentication
+
+Canary credentials are stored remotely and belong to a **property** (an app with a base URL). When the user asks you to test, determine the environment:
+
+### Remote / Deployed environments (default)
+
+Credentials are pre-configured with storage state. Just use \`--credential\` to load one:
+
+\`\`\`bash
+# Interactive picker \u2014 shows credential name, property name, and base URL
+canary session start --credential
+
+# By name
+canary session start --credential "Admin User" --url https://staging.example.com
+\`\`\`
+
+### Local development
+
+Credentials stored in Canary won't work against localhost because session cookies are bound to the remote domain. When testing a local dev server:
+
+1. **Ask the user to log in manually.** Start a session without credentials and tell them to authenticate in the browser:
+
+\`\`\`bash
+canary session start --url http://localhost:5173
+\`\`\`
+
+Then tell the user: "I've opened a browser to your local app. Please log in, and let me know when you're ready for me to continue."
+
+2. **Wait for confirmation** before proceeding with testing.
+
+3. Alternatively, if the user has a **local storage state file**, use it:
+
+\`\`\`bash
+canary session start --storage-state ./local-auth.json --url http://localhost:5173
+\`\`\`
+
+**Rule:** If the URL is localhost or 127.0.0.1, do NOT use \`--credential\` \u2014 it will download remote session state that won't work locally. Instead, prompt the user to log in.
+
+## Core Workflow
+
+The fundamental loop is: **snapshot \u2192 read \u2192 act \u2192 snapshot \u2192 verify**.
+
+### 1. Start a session
+
+\`\`\`bash
+# Start a headed browser (you can watch it)
+canary session start --url https://your-app.com
+
+# Start with a saved credential (interactive picker shows property + base URL)
+canary session start --credential
+
+# Start with a specific credential by name
+canary session start --credential "Admin User" --url https://your-app.com
+
+# Load a credential into an already-running session
+canary session load-credential
+\`\`\`
+
+### 2. Take a snapshot to see the page
+
+Snapshots are your primary way to understand what's on the page. They return an **accessibility tree** with element references (refs) and a **screenshot**.
+
+\`\`\`bash
+# Full snapshot: accessibility tree + screenshot
+canary session snapshot
+
+# Search for specific elements (fastest way to find what you need)
+canary session snapshot --search "Submit"
+canary session snapshot --search "Email|Password"
+
+# Expand a collapsed section (use the ref shown in the tree, e.g. [e50])
+canary session snapshot --expand e50
+
+# Screenshot only (useful for visual verification)
+canary session snapshot --mode screenshot
+
+# Tree only (useful when you need ref details, no image)
+canary session snapshot --mode tree
+\`\`\`
+
+**Reading snapshot output:**
+
+The accessibility tree shows elements with refs like \`[ref=e15]\`. Use these refs in subsequent commands. The tree is structured to show the page hierarchy \u2014 forms, buttons, links, headings, etc.
+
+When you use \`--search\`, matching elements are highlighted in the output and on the screenshot. Search is OR-matched and case-insensitive. Use search to **locate** elements, not to validate visual states \u2014 search overlays can obscure subtle UI changes.
+
+Large sections of the tree may be collapsed (shown as e.g. \`(127 elements - use expand="e50" to see content)\`). Use \`--expand <ref>\` to reveal the full contents of a collapsed section.
+
+### 3. Interact with the page
+
+Always reference elements by their **ref** from the snapshot.
+
+\`\`\`bash
+# Click an element
+canary session click --ref e15 --element "Submit button"
+
+# Type into an input field
+canary session type --ref e7 --text "user@example.com" --element "Email input"
+
+# Type and submit (presses Enter after typing)
+canary session type --ref e7 --text "search query" --element "Search box" --submit
+
+# Fill multiple form fields at once
+canary session fill --fields '[{"ref":"e3","value":"John"},{"ref":"e4","value":"john@example.com"}]'
+
+# Select a dropdown option
+canary session select --ref e12 --value "admin" --element "Role dropdown"
+
+# Press a keyboard key
+canary session press --key Enter
+canary session press --key Escape
+canary session press --key ArrowDown
+
+# Hover to reveal hidden content (tooltips, dropdowns)
+canary session hover --ref e8 --element "User menu"
+\`\`\`
+
+### 4. Navigate
+
+\`\`\`bash
+canary session navigate --url https://your-app.com/settings
+canary session back
+\`\`\`
+
+### 5. Scroll
+
+\`\`\`bash
+# Scroll down the page
+canary session scroll --direction down
+
+# Scroll with more intensity (1-10, default 3)
+canary session scroll --direction down --amount 8
+
+# Scroll up
+canary session scroll --direction up
+\`\`\`
+
+### 6. Verify results
+
+After every action, take a snapshot to verify the result:
+
+\`\`\`bash
+# Check what happened after clicking submit
+canary session snapshot
+
+# Search for a success message
+canary session snapshot --search "Success|saved"
+
+# Check for error messages
+canary session snapshot --search "Error|failed|invalid"
+
+# Check console for JavaScript errors
+canary session console --only-errors
+
+# Check network requests for failed API calls
+canary session network
+\`\`\`
+
+## Session Management
+
+\`\`\`bash
+# List all active sessions
+canary session list
+
+# Check session details
+canary session status
+
+# Stop a session
+canary session stop
+
+# Stop all sessions
+canary session stop --all
+
+# When multiple sessions are active, specify which one
+canary session snapshot --session s1
+canary session click --ref e5 --element "Button" --session s2
+\`\`\`
+
+## Advanced Techniques
+
+### Waiting for page changes
+
+\`\`\`bash
+# Wait for text to appear (after navigation or async action)
+canary session wait --text "Dashboard loaded"
+
+# Wait for text to disappear (loading spinner)
+canary session wait --text "Loading..."
+
+# Wait a fixed time (use sparingly)
+canary session wait --time 2
+\`\`\`
+
+### Coordinate-based clicking
+
+When ref-based clicking doesn't work (overlays, canvas elements), use coordinates. First take a snapshot, look at the screenshot, estimate coordinates, then click:
+
+\`\`\`bash
+# Click at specific coordinates
+canary session click --x 450 --y 300 --element "Canvas element"
+\`\`\`
+
+### Tab management
+
+\`\`\`bash
+canary session tabs --action list
+canary session tabs --action new
+canary session tabs --action select --index 0
+canary session tabs --action close --index 1
+\`\`\`
+
+### Evaluating JavaScript
+
+\`\`\`bash
+canary session evaluate --js "() => document.title"
+canary session evaluate --js "() => window.location.href"
+canary session evaluate --js "() => document.querySelectorAll('.error').length"
+\`\`\`
+
+### Taking labeled screenshots
+
+\`\`\`bash
+# Take a labeled screenshot for later reference
+canary session screenshot --label "before-submit"
+
+# Full page screenshot
+canary session screenshot --full-page --label "full-page-state"
+\`\`\`
+
+### File downloads
+
+\`\`\`bash
+# List downloaded files
+canary session evaluate --js "() => 'trigger download'"
+# ... after download completes:
+canary session list-downloads
+canary session read-download
+\`\`\`
+
+## Testing Guidelines
+
+1. **Always snapshot after actions** \u2014 never assume an action succeeded. Take a snapshot to verify.
+2. **Use search to locate elements** \u2014 \`--search "Submit"\` is faster than scanning the full tree.
+3. **Use refs, not coordinates** \u2014 ref-based interaction is more reliable. Only fall back to coordinates when refs fail.
+4. **Check for errors** \u2014 after form submissions or navigation, check both the page content and console/network for errors.
+5. **Wait for async operations** \u2014 if an action triggers an API call, use \`wait --text\` for the expected result rather than fixed delays.
+6. **Load credentials for authenticated testing** \u2014 use \`canary session start --credential\` or \`canary session load-credential\` to test as specific users.
+7. **Report what you find** \u2014 describe what you see in snapshots, what worked, what failed, and include relevant refs or error messages.
+
+## Improving Testability (Local Development)
+
+When testing locally, you have access to the source code \u2014 use this advantage. If the accessibility tree is confusing or elements are hard to target, **diagnose why** and suggest concrete improvements to the user.
+
+### When to investigate
+
+If you encounter any of these signals, dig deeper before moving on:
+- Multiple elements with identical or vague labels (e.g., several "Button" or "div" entries)
+- Interactive elements missing from the accessibility tree entirely
+- Custom components that render as opaque containers with no semantic children
+- Difficulty distinguishing between similar repeated elements (e.g., rows in a table)
+- Elements you can see in the screenshot but can't find in the tree
+
+### How to investigate
+
+1. **Use JavaScript evaluation** to inspect the actual DOM structure:
+   \`\`\`bash
+   canary session evaluate --js "() => document.querySelector('[data-testid]')?.outerHTML"
+   canary session evaluate --js "() => document.querySelectorAll('button').length"
+   canary session evaluate --js "() => [...document.querySelectorAll('button')].map(b => ({ text: b.textContent?.trim(), role: b.getAttribute('role'), ariaLabel: b.getAttribute('aria-label') }))"
+   \`\`\`
+
+2. **Read the component source code** \u2014 find and read the relevant component or template file to understand why the accessibility tree looks the way it does.
+
+3. **Compare screenshot vs tree** \u2014 take a screenshot-only snapshot and a tree-only snapshot. If you can see something visually but it's missing or ambiguous in the tree, that's a testability gap.
+
+### What to suggest
+
+When you find testability gaps, suggest specific fixes to the user. Frame suggestions as improvements that help both automated testing and human accessibility:
+
+- **Missing labels**: "The 'Save' buttons in each card are indistinguishable in the accessibility tree. Adding \`aria-label="Save {itemName}"\` or \`data-testid="save-{itemId}"\` would make them individually targetable."
+- **Non-semantic elements**: "This clickable \`<div>\` doesn't appear as a button in the tree. Changing it to \`<button>\` or adding \`role="button"\` would fix this."
+- **Missing headings/landmarks**: "This page section has no heading \u2014 screen readers and test agents can't tell what it contains. Adding an \`<h2>\` or \`aria-label\` to the \`<section>\` would help."
+- **Unlabeled form fields**: "These inputs have placeholder text but no associated \`<label>\`. Adding \`<label htmlFor="...">\` or \`aria-label\` would make them reliably targetable."
+- **Repeated generic elements**: "The table rows are hard to distinguish. Adding \`data-testid="row-{id}"\` or meaningful \`aria-label\` values to each row would make them individually addressable."
+
+**Tone**: These are suggestions, not demands. Present them as quick wins that improve both test reliability and accessibility. Group them at the end of your testing report rather than interrupting the testing flow.
+
+## Creating Tests from Browser Exploration
+
+After exploring an app via \`canary session\`, you can persist what you discovered as a reusable test workflow.
+
+### Explore \u2192 Author \u2192 Create flow
+
+1. **Explore**: Use \`canary session\` to navigate, snapshot, and interact with the app
+2. **Author**: Construct workflow JSON with nodes and playbook steps based on what was observed
+3. **Create**: Pipe JSON to \`canary workflow create\`
+4. **Verify**: Check with \`canary workflow get <id>\`
+
+### Node authoring guidance
+
+- Group related actions into single action nodes (one node per logical step, not per click)
+- Node types: \`login\` (authentication), \`navigate\` (go to URL), \`action\` (interact with elements), \`assertion\` (verify standalone page state), \`end\` (terminal node)
+- Every action node **must** have a \`customActionTitle\` \u2014 a short (3-8 word) human-readable title describing the step
+- **Prefer inline assertions** on action nodes over separate assertion nodes. Add \`inlineAssertions\` to verify outcomes right after the action completes. Use separate \`assertion\` nodes only for standalone page-level verifications (e.g., initial page state before any action)
+- Inline assertion format: \`{ "condition": "...", "severity": "fail" }\`. **Do not author an \`id\` field** \u2014 the server stamps a UUID on persist. Hand-rolled UUIDs (especially placeholders like \`a1b2c3d4-...\`) are rejected and replaced.
+
+### Playbook step authoring guidance
+
+- Use **semantic targets** from the accessibility tree (button text, field labels, placeholder text) \u2014 NOT refs or CSS selectors
+- Target format: describe as a human would ("Submit button", "Email input field", "Status dropdown")
+- For \`fill\` actions: include \`params: { "value": "..." }\`
+- **Always prefer macros over hardcoded test data.** Macros generate fresh values each run, preventing flaky tests from stale or colliding data. Never hardcode emails, names, phone numbers, or dates when a macro can generate them.
+- Prefix test data with "QA Test" for identifiability (e.g., \`"QA Test $FIRST_NAME()"\`)
+- Valid actions: \`click\`, \`fill\`, \`fill_form\`, \`select\`, \`navigate\`, \`wait\`, \`scroll\`, \`hover\`, \`upload\`, \`verify\`, \`press_key\`, \`drag\`, \`resize\`, \`capture\`, \`extract_table\`, \`python_execute\`, \`verify_download\`, \`verify_download_content\`, \`screenshot\`, \`agent_loop\`
+
+### Using macros and variables
+
+Macros are resolved at run time \u2014 each execution gets fresh values, making tests repeatable and collision-free.
+
+**Available macros:**
+
+| Macro | Args | Output | Example |
+|-------|------|--------|---------|
+| \`$EMAIL()\` | \u2014 | Unique test email | \`test-xk9mq2@example-test.com\` |
+| \`$FIRST_NAME()\` | \u2014 | Random first name | \`Jordan\` |
+| \`$LAST_NAME()\` | \u2014 | Random last name | \`Chen\` |
+| \`$PHONE()\` | \u2014 | US phone (555 prefix) | \`+1-555-382-7491\` |
+| \`$UUID()\` | \u2014 | Random UUID v4 | \`a1b2c3d4-...\` |
+| \`$RANDOM_INT(min, max)\` | 2 ints | Random integer (inclusive) | \`$RANDOM_INT(100,999)\` \u2192 \`427\` |
+| \`$RANDOM_STRING(length)\` | 1 int (1\u20131000) | Alphanumeric string | \`$RANDOM_STRING(8)\` \u2192 \`xK9mQ3bR\` |
+| \`$TODAY()\` | \u2014 | Current date (YYYY-MM-DD) | \`2026-04-06\` |
+| \`$DATE(days)\` | 1 int | Date offset from today | \`$DATE(-7)\` \u2192 last week |
+| \`$NOW()\` | \u2014 | ISO 8601 timestamp | \`2026-04-06T14:30:00.000Z\` |
+| \`$TIMESTAMP()\` | \u2014 | Unix milliseconds | \`1771520400000\` |
+| \`$SEQUENCE("name")\` | counter name | Auto-incrementing per run | \`1\`, \`2\`, \`3\`... |
+
+**When to use macros:**
+- Email fields \u2192 \`$EMAIL()\`
+- Name fields \u2192 \`$FIRST_NAME()\` / \`$LAST_NAME()\`
+- Amounts, quantities, identifiers \u2192 \`$RANDOM_INT()\` or \`$RANDOM_STRING()\`
+- Date fields \u2192 \`$TODAY()\` / \`$DATE()\`
+- Sequential numbering \u2192 \`$SEQUENCE("name")\`
+- Macros combine inline: \`"QA Test $FIRST_NAME() $LAST_NAME()"\`, \`"order-$RANDOM_STRING(6)"\`
+
+**Variables (\`$var.name\`):**
+- Steps can reference data captured from earlier steps using \`$var.name\`
+- Variable values are extracted during execution and available to subsequent steps
+- Use step-qualified refs when multiple steps set the same variable: \`$var.Step2_Create_Client.name\`
+
+### Credential selection
+
+**Always use \`credentialId\` (UUID) in the login node \u2014 never just \`credentialName\`.**
+
+1. **List available credentials** before authoring:
+   \`\`\`bash
+   canary credential list --json
+   \`\`\`
+   This returns each credential's \`id\`, \`name\`, \`isDefault\`, \`propertyName\`, and environment info.
+
+2. **Pick the right credential**:
+   - Prefer the **default credential** (\`isDefault: true\`)
+   - **Never** use a credential with "local" in the name \u2014 it won't work in deployed environments
+   - If multiple non-local credentials exist and you're unsure which to use, **ask the user**
+
+3. **Set both \`credentialId\` and \`credentialName\`** in the login node's \`configJson\`:
+   \`\`\`json
+   { "credentialId": "4f6db838-...", "credentialName": "QA User" }
+   \`\`\`
+
+4. **If no matching credential exists**, warn the user that one needs to be created first in the web app.
+
+The CLI will auto-resolve credentials if \`credentialId\` is missing, but it may fail if the choice is ambiguous. Always specify the ID explicitly for reliable uploads.
+
+### Environment-aware publishing
+
+- **CLI-created workflows default to \`published\`** \u2014 no flag needed. Reliability is tracked automatically by the workflow's \`health\` (starts \`unverified\`); a flow that keeps failing becomes \`degraded\` and is skipped in suites until edited or re-enabled.
+- **Deployed/known environment**: Use \`--run-and-publish\` \u2014 test runs immediately, publishes if it passes.
+
+### Usage
+
+\`\`\`bash
+# Create (published by default)
+echo '<workflow JSON>' | canary workflow create --from-stdin
+
+# Run-then-publish for deployed environments
+echo '<workflow JSON>' | canary workflow create --from-stdin --run-and-publish --property "My App"
+
+# From file
+canary workflow create --from-file workflow.json
+\`\`\`
+
+### Example workflow JSON
+
+\`\`\`json
+{
+  "name": "Verify user can create an invoice",
+  "description": "Tests the invoice creation flow end-to-end",
+  "nodes": [
+    {
+      "nodeType": "login",
+      "configJson": {
+        "credentialId": "4f6db838-16be-49e8-8887-8d0be1c83a87",
+        "credentialName": "QA User"
+      }
+    },
+    {
+      "nodeType": "navigate",
+      "configJson": { "pageUrl": "/invoices", "pageTitle": "Invoices" }
+    },
+    {
+      "nodeType": "action",
+      "configJson": {
+        "customActionTitle": "Create a new invoice",
+        "actionDescription": "Fill out the new invoice form and save",
+        "playbookSteps": [
+          { "order": 1, "action": "click", "target": "New Invoice button" },
+          { "order": 2, "action": "fill", "target": "Client name field", "params": { "value": "QA Test $FIRST_NAME()" } },
+          { "order": 3, "action": "fill", "target": "Amount field", "params": { "value": "$RANDOM_INT(100,999)" } },
+          { "order": 4, "action": "click", "target": "Save button" }
+        ],
+        "inlineAssertions": [
+          {
+            "condition": "Success message 'Invoice created' is visible and the new invoice appears in the list",
+            "severity": "fail"
+          }
+        ]
+      }
+    }
+  ]
+}
+\`\`\`
+
+### Updating existing workflows
+
+Use \`canary workflow sync\` to replace a workflow's nodes. It accepts the same
+simple format as create \u2014 no edges, positions, or IDs needed:
+
+\`\`\`bash
+# From stdin
+echo '{"nodes": [...]}' | canary workflow sync <workflowId> --from-stdin
+
+# From file
+canary workflow sync <workflowId> --from-file updated.json
+
+# Create a proposal for review instead of applying directly
+canary workflow sync <workflowId> --from-file updated.json --propose
+\`\`\`
+
+When using \`--propose\` on an existing workflow, fetch the current state first
+and reuse each node's \`id\` for steps you keep \u2014 only omit \`id\` for genuinely
+new steps. This is the best way to ensure the diff stays accurate so reviewers
+see only the fields that actually changed:
+
+\`\`\`bash
+# Round-trip pattern for proposals
+canary workflow get <workflowId> --format json > current.json
+# edit current.json: change configJsons, keep ids you're not replacing
+canary workflow sync <workflowId> --from-file current.json --propose
+\`\`\`
+
+### Generating API sequences
+
+Convert a browser-based workflow to a fast API sequence using its latest successful run:
+
+\`\`\`bash
+# Generate from the workflow's latest run
+canary workflow generate-api-sequence <workflowId>
+
+# With additional guidance
+canary workflow generate-api-sequence <workflowId> --guidance "Focus on the create endpoint"
+
+# JSON output
+canary workflow generate-api-sequence <workflowId> --json
+\`\`\`
+
+### Reference
+
+Run \`canary workflow guide\` for the full authoring reference:
+
+\`\`\`bash
+canary workflow guide                  # All sections
+canary workflow guide node-types       # Available node types
+canary workflow guide macros           # Dynamic test data ($EMAIL, $RANDOM_STRING, etc.)
+canary workflow guide playbook         # Playbook steps and caching
+canary workflow guide seed-workflows   # Seed workflow patterns
+canary workflow guide assertions       # Inline and standalone assertions
+\`\`\`
+`
+};
+
+// src/skill-templates/agent-tasks.ts
+var agentTasksTemplate = {
+  name: "agent-tasks",
+  description: "Manage trigger-based agent tasks for deferred work items",
+  version: "1.0.0",
+  render: () => `---
+name: agent-tasks
+version: 1.0.0
+description: Manage trigger-based agent tasks via the Canary CLI. Use when the user asks to create a task, schedule post-deploy work, set up reminders for flag cleanup, track knob deprecation, or manage deferred work items triggered by system events.
+allowed-tools: Bash(canary task:*), Read, Grep, Glob
+---
+
+# Agent Tasks with Canary
+
+Use \`canary task\` to create and manage **trigger-based work items** \u2014 deferred tasks that become actionable when a system event fires (deploy, flag change, schedule, etc.).
+
+## Prerequisites
+
+- \`canary\` CLI installed and authenticated (\`canary login\`)
+- The **AGENT_TASKS** feature flag must be enabled for the org
+- Run \`canary task --help\` for the full command reference
+
+## Quick Reference
+
+\`\`\`bash
+# Create a task
+canary task create --title "Remove feature flag" \\
+  --description "Delete COOL_FEATURE flag and all gating code" \\
+  --trigger flag-deleted --flag COOL_FEATURE
+
+# List tasks
+canary task list                                    # all tasks
+canary task list --status waiting                   # waiting for trigger
+canary task list --status actionable                # ready to work on
+canary task list --trigger production-deploy        # by trigger type
+
+# Manage tasks
+canary task get <id>                                # view details + event history
+canary task update <id> --title "New title"         # update task fields
+canary task claim <id>                              # mark in progress
+canary task complete <id>                           # mark done
+canary task complete <id> --commit abc123           # done, link to resolution commit
+canary task cancel <id>                             # cancel
+canary task trigger <id>                            # manually fire trigger
+\`\`\`
+
+## Trigger Types
+
+| Type | Fires when... | Auto-fired? | Required flag |
+|------|---------------|-------------|---------------|
+| \`production-deploy\` | Code deployed to production | **Yes** | \u2014 |
+| \`flag-deprecated\` | Feature flag set to deprecated | Yes | \`--flag <name>\` |
+| \`flag-cleanup\` | Feature flag set to ready_for_cleanup | Yes | \`--flag <name>\` |
+| \`flag-deleted\` | Feature flag deleted | Yes | \`--flag <name>\` |
+| \`knob-deprecated\` | Knob set to deprecated | Yes | \`--knob <key>\` |
+| \`knob-cleanup\` | Knob set to ready_for_cleanup | Yes | \`--knob <key>\` |
+| \`knob-deleted\` | Knob deleted | Yes | \`--knob <key>\` |
+| \`scheduled\` | A date/time is reached | Yes | \`--scheduled-date <ISO>\` |
+| \`pr-merged\` | A specific PR is merged | Yes | \`--pr <number>\` |
+| \`immediate\` | Immediately (no waiting) | N/A | \u2014 |
+| \`manual\` | Manually triggered via CLI | N/A | \u2014 |
+
+**Note:** \`pr-merged\` tasks are scoped to the linked repository selected by \`--repo\`, \`--role\`, or \`--repo-id\`.
+
+## Task Lifecycle
+
+\`\`\`
+                   \u250C\u2500\u2500\u2500 immediate \u2500\u2500\u2500\u25BA actionable
+                   \u2502                       \u2502
+  create \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524                     claim
+                   \u2502                       \u2502
+                   \u2514\u2500\u2500\u2500 other types \u2500\u2500\u25BA waiting \u2500\u2500trigger\u2500\u2500\u25BA actionable \u2500\u2500\u25BA in_progress \u2500\u2500\u25BA completed
+                                                                                    \u251C\u2500\u2500\u25BA canceled
+                                                                                    \u2514\u2500\u2500\u25BA expired
+\`\`\`
+
+- **waiting**: Created, waiting for its trigger event
+- **actionable**: Trigger fired (or immediate type), ready to be worked on
+- **in_progress**: Claimed by someone, actively being worked
+- **completed**: Done (optionally linked to a resolution commit)
+- **canceled** / **expired**: Terminated without completion
+
+## Common Workflows
+
+### Post-deploy cleanup (remove temporary code after next production deploy)
+
+\`\`\`bash
+canary task create \\
+  --title "Remove backwards-compat shim for widget API" \\
+  --description "Old endpoint can be removed now that new endpoint is deployed." \\
+  --trigger production-deploy \\
+  --priority 1 \\
+  --tag cleanup --tag api
+\`\`\`
+
+This task automatically becomes actionable after the next successful production deployment.
+
+### Flag removal after GA
+
+When a feature graduates from behind a flag:
+
+\`\`\`bash
+canary task create \\
+  --title "Clean up COOL_FEATURE flag gating code" \\
+  --description "Feature is GA. Remove all gating checks and delete the constant." \\
+  --trigger flag-deprecated --flag COOL_FEATURE \\
+  --tag cleanup --tag feature-flags
+\`\`\`
+
+Auto-fires when someone runs \`canary feature-flag lifecycle COOL_FEATURE --stage deprecated\`.
+
+### Knob deprecation follow-up
+
+\`\`\`bash
+canary task create \\
+  --title "Remove agent.truncation.enabled knob reads" \\
+  --description "Replace all knob reads with the hardcoded final value." \\
+  --trigger knob-deprecated --knob agent.truncation.enabled \\
+  --tag cleanup
+\`\`\`
+
+### Scheduled future work
+
+\`\`\`bash
+canary task create \\
+  --title "Rotate API signing keys" \\
+  --description "Quarterly key rotation per security policy." \\
+  --trigger scheduled --scheduled-date 2026-06-30T00:00:00Z \\
+  --priority 2 --tag security
+\`\`\`
+
+### Immediate task (starts actionable, no trigger wait)
+
+\`\`\`bash
+canary task create \\
+  --title "Fix type error in auth middleware" \\
+  --description "Strict mode caught a missing null check. Needs immediate fix." \\
+  --trigger immediate \\
+  --priority 2 --assign dev@example.com
+\`\`\`
+
+## Integration Points
+
+### Feature Flags \u2192 Tasks
+
+Flag lifecycle changes automatically fire matching task triggers:
+- \`canary feature-flag lifecycle <name> --stage deprecated\` \u2192 fires \`flag-deprecated\` tasks
+- \`canary feature-flag lifecycle <name> --stage ready_for_cleanup\` \u2192 fires \`flag-cleanup\` tasks
+- \`canary feature-flag delete <name>\` \u2192 fires \`flag-deleted\` tasks
+
+### Knobs \u2192 Tasks
+
+Same pattern as flags:
+- \`canary knobs lifecycle <key> --stage deprecated\` \u2192 fires \`knob-deprecated\` tasks
+- \`canary knobs lifecycle <key> --stage ready_for_cleanup\` \u2192 fires \`knob-cleanup\` tasks
+- \`canary knobs delete <key>\` \u2192 fires \`knob-deleted\` tasks
+
+### Production Deploys \u2192 Tasks
+
+The deployment notifier Lambda fires \`production-deploy\` task triggers automatically on successful production deployments. Any waiting tasks with this trigger type transition to \`actionable\`.
+
+## Tips
+
+- \`--commit\` defaults to \`git HEAD\` \u2014 auto-detects the current commit
+- \`--repo\` is auto-selected if the org has a single linked repository
+- \`--tag\` is repeatable: \`--tag cleanup --tag api --tag urgent\`
+- \`--description-file <path>\` reads description from a file (useful for long markdown descriptions)
+- \`--json\` on any command returns structured JSON output for scripting
+- \`--priority\`: 0 = normal (default), 1 = high, 2 = critical
+- \`--expires <ISO date>\` sets an expiry after which the task auto-expires if not completed
+- Use \`canary task trigger <id>\` to manually fire any waiting task's trigger
+`
+};
+
+// src/skill-templates/canary-basic.ts
+var canaryBasicTemplate = {
+  name: "canary-basic",
+  description: "Learn the Canary CLI \u2014 commands, help, and common patterns",
+  version: "1.0.0",
+  render: () => `---
+name: canary-basic
+version: 1.0.0
+description: Reference guide for the Canary CLI. Invoke when anyone mentions canary, canary CLI, or asks about CLI commands for testing, browser sessions, workflows, issues, or releases.
+allowed-tools: Read, Grep, Glob
+---
+
+# Canary CLI Guide
+
+The \`canary\` CLI is a command-line tool for running tests, controlling browser sessions, managing workflows, and inspecting issues.
+
+## Install & Login
+
+\`\`\`bash
+# Install globally
+npm install -g @canaryai/cli
+# or
+bun add -g @canaryai/cli
+
+# Authenticate (opens browser)
+canary login
+
+# Login to a specific org (for multi-org users)
+canary login --org "My Org"
+\`\`\`
+
+### Environment switching
+
+\`\`\`bash
+# Production (default)
+canary login
+
+# Dev
+canary login --app-url https://app.dev.trycanary.ai --api-url https://api.dev.trycanary.ai
+
+# Local
+canary login --app-url http://localhost:5173 --api-url http://localhost:3000
+
+# Or set the env var
+export CANARY_API_URL=http://localhost:3000
+\`\`\`
+
+---
+
+## Command Reference
+
+### Test Suites
+
+\`\`\`bash
+# Trigger a test suite and stream results
+canary test-suite run
+canary test-suite run --tag smoke
+canary test-suite run --property "My App" --environment staging --verbose
+
+# Query test suite results
+canary test-suite list
+canary test-suite get <id> --failures-only
+canary test-suite diagnostics <workflowId> <runId>
+canary test-suite steps <workflowId> <runId>
+\`\`\`
+
+Run options: \`--token\`, \`--property\`, \`--environment\`, \`--tag\`, \`--name-pattern\`, \`--verbose\`
+
+---
+
+### Browser Sessions
+
+Start and control browser sessions for interactive testing.
+
+#### Session lifecycle
+
+\`\`\`bash
+canary session start                          # Start a new session
+canary session start --credential "admin"     # Start with a credential
+canary session start --url https://example.com --headless
+canary session list                           # List active sessions
+canary session status                         # Show session details
+canary session stop                           # Stop the current session
+canary session stop --all                     # Stop all sessions
+canary session load-credential                # Load a credential into a running session
+canary session allow-screenshots              # Grant Claude auto-read for screenshots
+\`\`\`
+
+#### Browser actions
+
+\`\`\`bash
+# Navigation
+canary session navigate --url https://example.com
+canary session back
+
+# Observe the page
+canary session snapshot                       # Get accessibility tree
+canary session snapshot --mode screenshot     # Get a screenshot
+canary session snapshot --mode both           # Tree + screenshot
+canary session snapshot --search "Login"      # Search for text
+canary session snapshot --expand e5           # Expand a collapsed ref
+canary session screenshot --full-page         # Full-page screenshot
+
+# Interact with elements (use ref from snapshot)
+canary session click --ref e12
+canary session type --ref e8 --text "hello" --submit
+canary session fill --fields '[{"ref":"e1","value":"user@example.com"},{"ref":"e2","value":"pass123"}]'
+canary session select --ref e15 --value "option-1"
+canary session hover --ref e3
+canary session press --key Enter
+canary session scroll --direction down --amount 3
+
+# Tabs
+canary session tabs                           # List tabs
+canary session tabs --action new              # Open new tab
+canary session tabs --action select --index 0 # Switch to tab
+canary session tabs --action close            # Close current tab
+
+# Debugging
+canary session wait --text "Success" --timeout 5000
+canary session console --only-errors          # Show console messages
+canary session network                        # Show network requests
+canary session evaluate --js "document.title" # Run JavaScript
+\`\`\`
+
+Common options: \`--session <id|name>\` (target a specific session), \`--json\`, \`--env\`
+
+#### Control (for cloud-connected sessions)
+
+\`\`\`bash
+canary session take-control     # Force CLI control (pauses cloud)
+canary session resume-cloud     # Resume cloud execution
+\`\`\`
+
+---
+
+### Recording
+
+Record browser interactions for creating test workflows.
+
+\`\`\`bash
+canary record
+canary record --credential admin --url https://example.com
+canary record --output ./recordings --no-upload   # Save locally only
+\`\`\`
+
+Options: \`--credential\`, \`--url\`, \`--output\`, \`--env\`, \`--no-upload\`
+
+---
+
+### Workflows
+
+Inspect and manage workflow definitions.
+
+\`\`\`bash
+# List and search
+canary workflow list
+canary workflow list --search "checkout" --status published --json
+
+# Get workflow definition
+canary workflow get <workflowId> --format markdown
+canary workflow get <workflowId> --json
+
+# Create from file or stdin
+canary workflow create --from-file workflow.json
+canary workflow create --run-and-publish --property "My App"
+
+# Update workflow
+canary workflow patch <workflowId> --name "New Name" --status published
+
+# Run a workflow
+canary workflow run <workflowId> --stream
+
+# Replace all nodes/edges
+canary workflow sync <workflowId> --from-file updated.json
+
+# Authoring guide
+canary workflow guide
+canary workflow guide selectors
+\`\`\`
+
+List filters: \`--search\`, \`--flow-type\` (standard|setup|seed|teardown), \`--status\` (draft|published), \`--page\`, \`--page-size\`
+
+Workflow statuses: \`draft\` = editable, not run by suites. \`published\` = active, included in regression runs. Reliability is tracked automatically by the \`health\` dimension \u2014 a flow that keeps failing in suites becomes \`degraded\` and is skipped (shown "degraded \u2014 not run") until it's edited or manually re-enabled.
+
+---
+
+### Issues
+
+Search and inspect QA issues detected by Canary.
+
+\`\`\`bash
+# List issues
+canary issues list
+canary issues list --severity high --status open --format markdown
+canary issues list --search "timeout" --property-id <uuid>
+
+# Get issue details
+canary issues get <issue-id>
+canary issues get <issue-id> --format markdown
+\`\`\`
+
+List options: \`--search\`, \`--severity\` (low|medium|high|unknown), \`--status\` (open|closed|not_a_bug), \`--property-id\`, \`--page\`, \`--page-size\`, \`--json\`, \`--format markdown\`
+
+---
+
+### Release QA (CI/CD)
+
+Trigger and monitor Release QA runs from CI pipelines.
+
+\`\`\`bash
+canary release trigger --property-id <uuid>
+canary release status <run-id> --json
+canary release run --property-id <uuid> --timeout 600   # Trigger and poll
+\`\`\`
+
+---
+
+### Properties & Credentials
+
+\`\`\`bash
+canary property list                    # List properties and linked repos
+canary credential list                  # List credentials with environment info
+\`\`\`
+
+---
+
+### Superadmin Commands
+
+These commands require superadmin access.
+
+\`\`\`bash
+# Knobs (global runtime config)
+canary knobs list
+canary knobs get <key>
+canary knobs set <key> <value> --type boolean|number|string
+canary knobs toggle <key>
+canary knobs delete <key>
+canary knobs lifecycle <key> --stage <stage>
+
+# Feature flags (per-org gating)
+canary feature-flag list
+canary feature-flag create <name> --description "..."
+canary feature-flag enable <name> --org <orgId>
+canary feature-flag disable <name> --org <orgId>
+canary feature-flag delete <name>
+canary feature-flag lifecycle <name> --stage <stage>
+
+# Database (read-only)
+canary psql "SELECT * FROM knobs LIMIT 5" --json
+
+# Redis (read-only)
+canary redis "GET some:key" --json
+
+# Documentation pages
+canary docs <sub-command>
+
+# Debug sessions
+canary debug-session --env dev --json
+\`\`\`
+
+---
+
+## Common Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| \`--json\` | Raw JSON output (most commands) |
+| \`--format markdown\` | Markdown-formatted output (issues, workflows) |
+| \`--env <env>\` | Target environment: \`local\`, \`dev\`, \`prod\` |
+| \`--verbose, -v\` | Show all events / detailed output |
+| \`-h, --help\` | Show help for any command |
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| \`CANARY_API_URL\` | \`https://api.trycanary.ai\` | API endpoint |
+| \`CANARY_APP_URL\` | \`https://app.trycanary.ai\` | App URL for login |
+| \`CANARY_API_TOKEN\` | \u2014 | API key (alternative to \`canary login\`) |
+
+## Getting Help
+
+\`\`\`bash
+canary help              # Show all commands
+canary <command> --help  # Show help for a specific command
+canary version           # Show CLI version
+canary upgrade           # Upgrade to latest version
+\`\`\`
+`
+};
+
+// src/skill-templates/test-cases.ts
+var testCasesTemplate = {
+  name: "test-cases",
+  description: "Author high-quality test cases as `.canary.md` specs that compile straight into Canary workflows. Invoke when the user asks to write test cases, draft a test plan, plan QA scenarios, decide what to test, or convert a PRD/ticket/design into tests.",
+  version: "2.2.0",
+  render: () => `---
+name: test-cases
+version: 2.2.0
+description: Author high-quality test cases as \`.canary.md\` specs that compile straight into Canary workflows. Invoke when the user asks to write test cases, draft a test plan, plan QA scenarios, decide what to test, or convert a PRD/ticket/design into tests.
+allowed-tools: Read, Grep, Glob, Bash, Write
+---
+
+# Test Case Authoring (Canary)
+
+Use this skill when the user asks for test cases, a test plan, QA scenarios, "what should we test for X", or wants to turn a PRD / ticket / design into tests. The output is one or more **\`.canary.md\` spec files** \u2014 each file is one workflow, one journey, one test case. \`canary spec compile <file>\` turns them into runnable Canary workflows; \`canary spec validate <file>\` enforces the structural rules below.
+
+The skill has three layers:
+1. **Industry rubric** \u2014 what makes a test case good (ISTQB-aligned).
+2. **Spec mapping** \u2014 how each rubric piece becomes a section of \`.canary.md\`.
+3. **Domain Context** \u2014 customer-specific sources of truth, filled in once.
+
+Read the Domain Context block at the bottom **first**. If it is unfilled, follow the discovery instructions there before authoring any cases.
+
+---
+
+## 1. The 7-rule rubric
+
+Each case must satisfy all seven. If a rule cannot be satisfied, say so explicitly and explain why \u2014 don't silently skip.
+
+### 1. One coherent journey per case (atomic, but not micro)
+A case covers a single coherent journey \u2014 one user objective, possibly with several verifications along the way. "Atomic" means *coherent*, not *minimal*: if multiple checks share the same setup and naturally flow from one another, they belong in the same case.
+
+- Good (coherent journey, multiple checks): "Onboard an org: create org \u2192 invite a user \u2192 claim invite \u2192 land on dashboard." Each step verifies its own outcome inline.
+- Good (single short journey): "Submit a ticket and confirm it appears in the queue."
+- Bad (unrelated jobs): "Submit a ticket, edit a user, generate a report." \u2014 three journeys, three separate \`.canary.md\` files.
+
+**Rule of thumb:** if isolating a check (e.g. "tagging works") would force you to duplicate most of another case's setup, fold it in as an inline assertion on the larger journey instead. Splitting only pays off when the setup is genuinely different or the failure modes are independent.
+
+### 2. Specific, observable expected results
+Every assertion must be something a stranger could verify without judgement.
+- Good: "URL ends with \`/dashboard\`." / "A row with name \`X\` appears in the table."
+- Bad: "The page looks correct." / "It works."
+
+Lint enforces this as **R1**: a spec with zero \`fail\`-severity assertions warns.
+
+### 3. Independent and self-sufficient
+A case must not depend on another case running first or on long-lived shared state. Provision data inline (\`## Inputs\` + \`## Scenarios\`, or a \`**Seed**\` node) and clean up in \`## Cleanup\`. Use macros (\\$EMAIL, \\$UUID) so reruns don't collide.
+
+### 4. Traceable
+Every case carries \`requirementRef:\` in frontmatter pointing at the ticket / PRD / design. If you can't find one, flag the gap to the user \u2014 untraceable specs rot. Lint **R2** warns when missing.
+
+### 5. Risk-prioritized
+Tag each case with a priority via the \`tags:\` array. Use one of: \`p0\`, \`p1\`, \`p2\`.
+- **p0** \u2014 happy path of the core promise; if this breaks, the feature is broken.
+- **p1** \u2014 primary edge cases, validation, role variants, common error states.
+- **p2** \u2014 rare conditions, visual/agentic checks, low-frequency edges.
+
+### 6. Includes preconditions, data, and cleanup
+- **Auth/role preconditions** \u2192 \`actor:\` in frontmatter.
+- **Other preconditions** (feature flags, seeded data, sister flows) \u2192 bulleted prose in \`## Preflight\`.
+- **Test data** \u2192 \`## Inputs\` (with macros) and per-variant \`## Scenarios\`.
+- **Teardown** \u2192 bulleted prose in \`## Cleanup\`.
+
+### 7. Written as human intent, not UI mechanics
+Action titles describe *what the user is trying to do*; the optional \`> blockquote\` underneath gives just enough context for the recorder/agent. Don't write click-by-click sequences.
+- Good: \`**Action \u2014 Assign the ticket to Support**\`
+- Bad: \`**Action \u2014 Click 'Assign' dropdown, scroll, click 'Support', click Save**\`
+
+Lint **R9** warns when an action reads as click-by-click.
+
+---
+
+## 2. Coverage checklist
+
+Before handing back a set of specs, sanity-check coverage. For each, either include a case or note why it doesn't apply:
+- Happy path (p0)
+- Primary edges / boundary inputs
+- Negative paths / validation errors
+- Permissions and role variants (admin / member / unauthenticated)
+- Empty, loading, and error states
+- Cross-entity side effects (does this change something visible elsewhere?)
+- Cleanup / undo where applicable
+
+Aim for the smallest set that proves the feature works. Five sharp cases beat twenty fuzzy ones.
+
+---
+
+## 3. Authoring \`.canary.md\`
+
+\`.canary.md\` is one workflow per file. Frontmatter sets identity; H2 sections carry prose and structured config; \`## Journey\` is the linear test itself. The compiler validates structure; lint enforces the rubric semantics above.
+
+Run these for the definitive grammar \u2014 do **not** restate them here:
+
+\`\`\`bash
+canary spec --help               # validate / compile / diff commands
+canary spec validate <file>      # parse + lint offline; enforce the rules in \xA71
+canary spec compile <file>       # create or update the workflow (prints the live URL)
+canary workflow guide            # node-shape and macro reference
+\`\`\`
+
+After \`canary spec compile\`, echo the printed \`URL:\` line back to the user verbatim \u2014 it points at the workflow you just created (\`https://app.trycanary.ai/flows/<id>\` for prod, \`https://app.dev.trycanary.ai/flows/<id>\` for dev). Don't construct it yourself.
+
+Mapping at a glance:
+
+| Rubric piece                            | Where it lives in \`.canary.md\`                                          |
+|-----------------------------------------|---------------------------------------------------------------------------|
+| Case title                              | \`frontmatter.name\`                                                       |
+| Requirement / ticket ref                | \`frontmatter.requirementRef\`                                             |
+| Priority (rule 5)                       | \`tags: [p0]\` (or p1/p2) in frontmatter                                   |
+| Auth role precondition                  | \`actor: <X>\` + \`authenticated: true\` in frontmatter. \`<X>\` is a credential **template** name by default (e.g. \`actor: Admin\` or the explicit \`actor: template Admin\`), or a specific raw credential via \`actor: credential <name>\` when the case genuinely needs one named account. Templates resolve at run/suite level; raw credentials bind a single fixed account. List templates with \`canary credential-template list --property "<property>"\`; list credentials with \`canary credential list\`. |
+| Feature flag / seeded data preconditions| Bulleted prose in \`## Preflight\` ("Feature flag X enabled.", "Seed workflow Y published.") |
+| One-paragraph user-visible promise      | \`## Spirit\` (blockquote)                                                 |
+| Workflow-level declared inputs          | \`## Inputs\` (e.g. \`- foo: \\$EMAIL\`) \u2014 parses to \`workflows.inputs_json\`, surfaces in Workflow Settings \u2192 Inputs |
+| Per-step bound values                   | \`- field X: Y\` under an Action \u2014 populates *that* step's Inputs panel with \`Y\` as the default (compiler mirrors fields \u2192 \`dataRequirements\` + \`inputValues\` on the node). Prefer \`## Inputs\` for values shared across actions. |
+| Variants (free / enterprise, etc.)      | \`## Scenarios\` with per-scenario \`values:\` / \`credentials:\` overrides  |
+| Steps (human intent)                    | \`## Journey\` \u2014 \`**Navigate to** \u2026\`, \`**Action \u2014 \u2026**\`, \`**Seed** \u2026\`     |
+| Inline expected results                 | \`- assert (fail \\| warn): <condition>\` under the action that produced it |
+| Standalone assertion                    | \`**Assert** <condition>\` node (prefer inline when possible)              |
+| Role change mid-journey                 | \`**Switch role to** <X>\` \u2014 mirrors \`actor:\`. \`<X>\` is a credential template name by default (\`**Switch role to** Admin\`), or \`credential <name>\` to bind a specific raw credential (\`**Switch role to** credential admin-bob\`). Compiles to a login node with \`performLogin: true\`. Repeat as many times as needed in one journey. |
+| Cross-action data flow                  | \`- capture: <name>\` on the upstream action, \`\\$var.<name>\` downstream  |
+| Cleanup                                 | Bulleted prose in \`## Cleanup\`                                           |
+
+When a journey shares setup and naturally flows end-to-end, emit **one** \`.canary.md\` with multiple action nodes and inline assertions. When journeys are unrelated, emit **one file per journey**; if one journey depends on data created by another, link them with \`**Seed** <spec-name>\` or \`**Setup** <spec-name>\` at the top of the dependent file.
+
+### Inputs defaults \u2014 the decision rule
+
+When you need a value (workflow-level \`## Inputs\` or step-level \`- field\`), pick where it comes from in this order:
+
+1. **Names existing data in the target environment** \u2014 a property name, a credential, a seeded record, an existing org/user/team. **Stop and ask the user for the value before writing the spec.** Don't hand-pick. The right sources of truth:
+   - \`canary property list\` \u2014 properties (target apps)
+   - \`canary credential-template list --property "<property>"\` \u2014 credential templates (these are what \`actor:\` and \`- credential \u2026\` reference)
+   - \`canary workflow list --search <term>\` \u2014 existing workflows to seed/link to
+   - \`canary feature-flag list --env <env>\` \u2014 flag names for Preflight prose
+2. **Synthesizable** \u2014 a new email, a UUID, a throwaway string, an ISO date. Pick a macro (\`\\$EMAIL\`, \`\\$UUID\`, \`\\$ISO_DATE\`) and move on without asking. These render as pills in the Inputs panel and resolve at run time.
+3. **Prefer credential templates** for any auth/role-scoped input. \`actor: Admin\` (frontmatter) and \`- credential admin: Admin\` (inputs) are cleaner than passing \`username:\` + \`password:\` and work across environments. Reach for the raw-credential form (\`actor: credential <name>\`, \`**Switch role to** credential <name>\`, \`- credential admin: <name>\`) only when the case genuinely requires a specific fixed account.
+
+---
+
+## 4. Output format
+
+For each case, write a \`.canary.md\` file alongside a one-row summary line. Default location: \`canary/specs/<slug>.canary.md\` (confirm with the user if their repo uses a different layout \u2014 check Domain Context below).
+
+### Summary table
+
+| file                              | name                                       | priority | requirementRef   |
+|-----------------------------------|--------------------------------------------|----------|------------------|
+| canary/specs/submit-ticket.canary.md | Submit a ticket and confirm it appears in the queue | p0       | <ticket/PRD ref> |
+
+### Per-case file
+
+\`\`\`markdown
+---
+name: <one user goal, action-oriented>
+actor: <credential template name from Domain Context \u2014 verbatim, e.g. "Admin"; or \`credential <name>\` for a specific raw credential>
+authenticated: true
+tags: [p0]            # or p1 / p2; add other tags from Domain Context's tagging conventions
+requirementRef: <ticket id, PRD path, design link>
+---
+
+# <same as name>
+
+## Spirit
+> <one short paragraph: the user-visible promise this case proves>
+
+## Preflight
+- <feature flag / seed / sister flow / role precondition, one per bullet>
+
+## Cleanup
+- <records to delete, flags to reset>
+
+## Inputs
+- <name>: <value or macro>
+
+## Journey
+
+**Navigate to** \\\`/some/path\\\`.
+
+**Action \u2014 <human intent>**
+> <one-sentence context for the recorder/agent>
+- field <name> [(type)]: <value or \\$input>
+- capture: <name>        # optional, only if a later step needs it via \\$var.<name>
+- assert (fail): <observable condition>
+- assert (warn): <softer signal>
+
+**End**.
+\`\`\`
+
+Keep journeys short (3\u20138 nodes). If a case grows past that, it's probably two cases.
+
+---
+
+## 5. Worked example (generic)
+
+Request: "Test the support ticket flow."
+
+| file                                      | name                                                | priority | requirementRef |
+|-------------------------------------------|-----------------------------------------------------|----------|----------------|
+| canary/specs/submit-ticket.canary.md       | Submit a ticket and confirm it appears in the queue | p0       | <fill in>      |
+| canary/specs/ticket-required-fields.canary.md | Required-field validation blocks submit          | p1       | <fill in>      |
+| canary/specs/ticket-non-admin-reassign.canary.md | Non-admin cannot reassign a ticket            | p1       | <fill in>      |
+
+\`canary/specs/submit-ticket.canary.md\`:
+
+\`\`\`markdown
+---
+name: Submit a ticket and confirm it appears in the queue
+actor: Admin
+authenticated: true
+tags: [p0, smoke, support]
+requirementRef: <fill in>
+---
+
+# Submit a ticket and confirm it appears in the queue
+
+## Spirit
+> A member can file a support ticket from the in-app form and immediately
+> see it land in their team's queue without a refresh.
+
+## Preflight
+- At least one Support team exists in the test org (seed workflow \\\`support-team-seed\\\`).
+- Feature flag \\\`support_inbox_v3\\\` is enabled.
+
+## Cleanup
+- Delete the created ticket.
+
+## Inputs
+- subject: "QA \\$UUID"
+- priority: high
+
+## Journey
+
+**Navigate to** \\\`/support/new\\\`.
+
+**Action \u2014 Submit the ticket**
+> Fill subject and priority, then submit.
+- field subject: \\$subject
+- field priority (select): \\$priority
+- assert (warn): Toast contains "Ticket created"
+- assert (fail): URL ends with \\\`/support\\\`
+
+**Navigate to** \\\`/support/queue\\\`.
+
+**Action \u2014 Confirm it appears in the queue**
+> Locate the new ticket in the team queue.
+- assert (fail): A row matching \\\`\\$subject\\\` is visible
+
+**End**.
+\`\`\`
+
+After writing, run \`canary spec validate canary/specs/submit-ticket.canary.md\` and resolve any errors / warnings before handing back.
+
+---
+
+## 6. Anti-patterns
+
+- Mega-files that try to cover five unrelated journeys.
+- The opposite: splitting one coherent journey into N tiny files that each re-create the same setup. Bundle them into one \`## Journey\` instead.
+- Click-by-click action titles ("Click X, scroll, click Y").
+- "Looks correct" / "everything works" assertions.
+- Hardcoded emails, IDs, or names that collide on rerun. Use macros (\\$EMAIL, \\$UUID).
+- Specs that depend on another spec having run first without an explicit \`**Seed**\` / \`**Setup**\` node.
+- Skipping \`requirementRef\` because "it's obvious".
+- Asserting state via toasts only \u2014 confirm the underlying record changed.
+- Dropping the priority tag \u2014 risk-rank every case (\`p0\` / \`p1\` / \`p2\`).
+
+---
+
+## 7. Domain Context
+
+<!-- AGENT/CUSTOMER: fill in this block on first use of the skill, then commit it. -->
+<!-- If any field below is "<unfilled>", do a discovery pass before authoring cases: -->
+<!--   - Read README.md, CLAUDE.md, AGENTS.md, docs/, specs/ for requirement and design pointers. -->
+<!--   - Scan recent git log for ticket-tracker references (JIRA-123, LIN-456, #issue). -->
+<!--   - Run \`canary property list\` and \`canary credential-template list --property "<property>"\` to learn properties + the credential templates that map to \`actor:\` values. -->
+<!--   - (\`canary credential list\` shows live credentials \u2014 useful, but the \`actor:\` field references credential *templates*, not credentials.) -->
+<!--   - Run \`canary workflow list --search <feature>\` to avoid duplicating existing workflows. -->
+<!--   - Run \`canary feature-flag list\` to confirm flag names referenced in Preflight prose. -->
+<!--   - Propose values to the user, get confirmation, then edit this block in place. -->
+
+- **Requirements / PRDs**: <unfilled \u2014 paths or URLs, e.g. \`docs/specs/\`, Notion space, Linear project>
+- **Designs**: <unfilled \u2014 Figma links, design system doc>
+- **Ticket tracker**: <unfilled \u2014 Jira/Linear project key + how to format \`requirementRef\` (e.g. \`PROJ-123\` or a URL)>
+- **Default property**: <unfilled \u2014 the property name to target; find via \`canary property list\`>
+- **Default environment**: <unfilled \u2014 \`prod\` | \`staging\` | \`dev\`>
+- **Credentials / role matrix** (\`actor:\` is a credential template name by default \u2014 list via \`canary credential-template list --property "<property>"\`. Prefix with \`credential \` to bind a specific raw credential \u2014 list via \`canary credential list\`. Use the template form unless the case genuinely needs a fixed named account.): <unfilled \u2014 list the credential template names available on the default property, with a one-line note on which to use when. Common shape: \`actor: Admin\` (standard user), \`actor: Superadmin\` (full access).>
+- **Tagging conventions**: <unfilled \u2014 e.g. \`smoke\`, \`regression\`, plus the priority tags \`p0\` / \`p1\` / \`p2\`>
+- **Spec directory**: <unfilled \u2014 where \`.canary.md\` files live in this repo, e.g. \`canary/specs/\`>
+- **Existing workflows to extend or avoid duplicating**: <unfilled \u2014 search via \`canary workflow list --search <term>\`>
+- **Glossary / domain terms**: <unfilled \u2014 terms that show up in tickets and should appear verbatim in spec names>
+- **Other sources of truth**: <unfilled \u2014 runbooks, support tickets, analytics dashboards>
+
+When this block is fully populated, every case you author should reference at least the **Requirements**, **Default property**, **Spec directory**, and **Credentials** entries.
+`
+};
+
+// src/skill-templates/debug-run.ts
+import { readFileSync, readdirSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var HERE = dirname(fileURLToPath(import.meta.url));
+function resolveSkillDir() {
+  const candidates = [
+    join(HERE, "..", "..", "skills", "debug-run"),
+    // source tree
+    join(HERE, "skills", "debug-run"),
+    // dist
+    join(HERE, "..", "skills", "debug-run")
+    // dist split-chunk variant
+  ];
+  for (const c of candidates) {
+    try {
+      readFileSync(join(c, "version.json"), "utf-8");
+      return c;
+    } catch {
+    }
+  }
+  throw new Error(
+    `Could not locate debug-run skill assets relative to ${HERE}. Tried: ${candidates.join(", ")}`
+  );
+}
+var SKILL_DIR = resolveSkillDir();
+var HISTORY_DIR = join(SKILL_DIR, "history");
+var versionMeta = JSON.parse(
+  readFileSync(join(SKILL_DIR, "version.json"), "utf-8")
+);
+function readVersion(version) {
+  return readFileSync(join(HISTORY_DIR, `${version}.md`), "utf-8");
+}
+function listVersionsOnDisk() {
+  return readdirSync(HISTORY_DIR).filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
+}
+var previousVersions = {};
+for (const v of listVersionsOnDisk()) {
+  if (v !== versionMeta.current) {
+    previousVersions[v] = () => readVersion(v);
+  }
+}
+var debugRunTemplate = {
+  name: "debug-run",
+  description: "Diagnose why a workflow test failed \u2014 root-cause an end-to-end run from its materialised artifacts",
+  version: versionMeta.current,
+  render: () => readVersion(versionMeta.current),
+  previousVersions
+};
+
+// src/skill-templates/index.ts
+var SKILL_TEMPLATES = {
+  "canary-basic": canaryBasicTemplate,
+  "agent-tasks": agentTasksTemplate,
+  "issue-log-xref": issueLogXrefTemplate,
+  "browser-testing": browserTestingTemplate,
+  "test-cases": testCasesTemplate,
+  "debug-run": debugRunTemplate
+};
+
+// src/skill.ts
+var SUPPORTED_AGENTS = ["claude", "codex", "copilot"];
+function isAgentType(value) {
+  return value === "claude" || value === "codex" || value === "copilot";
+}
+function detectAgent(options = {}) {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const pathExists = options.exists ?? existsSync;
+  if (env.CLAUDE) return "claude";
+  if (env.CODEX || env.CODEX_CI || env.CODEX_THREAD_ID || env.CODEX_MANAGED_PACKAGE_ROOT || env.AGENT_MODE === "codex")
+    return "codex";
+  if (env.GITHUB_COPILOT || env.COPILOT_AGENT || env.AGENT_MODE === "copilot")
+    return "copilot";
+  const foundAgents = SUPPORTED_AGENTS.filter(
+    (agent) => pathExists(join2(cwd, agent === "copilot" ? ".github" : `.${agent}`))
+  );
+  if (foundAgents.length === 1) return foundAgents[0] ?? null;
+  return null;
+}
+function resolveInstallDir(skillName, agent, personal, options = {}) {
+  const base = personal ? options.home ?? homedir() : options.cwd ?? process.cwd();
+  switch (agent) {
+    case "claude":
+      return join2(base, ".claude", "skills", skillName);
+    case "codex":
+      return join2(base, ".codex", "skills", skillName);
+    case "copilot":
+      return personal ? join2(base, ".copilot", "skills", skillName) : join2(base, ".github", "skills", skillName);
+  }
+}
+function printSkillHelp() {
+  const lines = [
+    "Usage:",
+    "  canary skill <name>                          Output skill template to stdout",
+    "  canary skill install <name>                  Install skill (auto-detects agent)",
+    "  canary skill install <name> --agent codex    Install for a specific agent",
+    "  canary skill install <name> --personal       Install to ~/.<agent>/skills/",
+    "  canary skill list                            List available skill templates",
+    "  canary skill sync                            Print manifest + instructions for the",
+    "                                               agent to version-compare and update",
+    "                                               installed skills",
+    "  canary skill diff <name> [--from V] [--to V] Unified diff between two versions of",
+    "                                               a skill (defaults: previous \u2192 current)",
+    "  canary skill versions <name>                 List all known versions of a skill",
+    "",
+    "Agent auto-detection:",
+    "  The install command detects which AI agent is running and writes the",
+    "  SKILL.md to the correct location:",
+    "",
+    "  Agent      Project path                   Personal path",
+    "  \u2500\u2500\u2500\u2500\u2500      \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500                   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "  claude     .claude/skills/<name>/         ~/.claude/skills/<name>/",
+    "  codex      .codex/skills/<name>/          ~/.codex/skills/<name>/",
+    "  copilot    .github/skills/<name>/         ~/.copilot/skills/<name>/",
+    "",
+    "  Detection checks (in order):",
+    "    1. CLAUDE env var              \u2192 claude",
+    "    2. CODEX_* env vars            \u2192 codex",
+    "    3. GITHUB_COPILOT env var      \u2192 copilot",
+    "    4. .claude/.codex/.github dirs \u2192 whichever single one exists",
+    "    5. If ambiguous, use --agent to specify explicitly",
+    "",
+    "Available templates:"
+  ];
+  for (const [key, template] of Object.entries(SKILL_TEMPLATES)) {
+    lines.push(
+      `  ${key.padEnd(24)} v${template.version.padEnd(7)} ${template.description}`
+    );
+  }
+  console.log(lines.join("\n"));
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function knownVersions(name) {
+  const t = SKILL_TEMPLATES[name];
+  if (!t) return [];
+  const all = /* @__PURE__ */ new Set([t.version, ...Object.keys(t.previousVersions ?? {})]);
+  return [...all].sort(compareSemver);
+}
+function renderAtVersion(name, version) {
+  const t = SKILL_TEMPLATES[name];
+  if (!t) return null;
+  if (version === t.version) return t.render();
+  const prev = t.previousVersions?.[version];
+  return prev ? prev() : null;
+}
+function parseFlagArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+function runVersions(argv) {
+  const [name] = argv;
+  if (!name || !SKILL_TEMPLATES[name]) {
+    console.error(`Usage: canary skill versions <name>`);
+    process.exit(1);
+  }
+  const versions = knownVersions(name);
+  const current = SKILL_TEMPLATES[name].version;
+  for (const v of versions) {
+    console.log(v === current ? `${v} (current)` : v);
+  }
+}
+function jsUnifiedDiff(a, b, labelA, labelB) {
+  const aLines = a.split("\n");
+  const bLines = b.split("\n");
+  const n = aLines.length;
+  const m = bLines.length;
+  const dp = Array.from(
+    { length: n + 1 },
+    () => Array.from({ length: m + 1 }).fill(0)
+  );
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = aLines[i2] === bLines[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const out = [`--- ${labelA}`, `+++ ${labelB}`];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (aLines[i] === bLines[j]) {
+      out.push(` ${aLines[i]}`);
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      out.push(`-${aLines[i++]}`);
+    } else {
+      out.push(`+${bLines[j++]}`);
+    }
+  }
+  while (i < n) out.push(`-${aLines[i++]}`);
+  while (j < m) out.push(`+${bLines[j++]}`);
+  return out.join("\n") + "\n";
+}
+function runDiff(argv) {
+  const { positional, flags } = parseFlagArgs(argv);
+  const [name] = positional;
+  if (!name) {
+    console.error(
+      "Usage: canary skill diff <name> [--from <version>] [--to <version>]"
+    );
+    process.exit(1);
+  }
+  const template = SKILL_TEMPLATES[name];
+  if (!template) {
+    console.error(`Unknown skill "${name}".`);
+    process.exit(1);
+  }
+  const versions = knownVersions(name);
+  const to = typeof flags.to === "string" ? flags.to : template.version;
+  const from = typeof flags.from === "string" ? flags.from : versions.filter((v) => v !== to).slice(-1)[0];
+  if (!from) {
+    console.error(
+      `No prior version of "${name}" to diff against. Only known version: ${template.version}.`
+    );
+    process.exit(1);
+  }
+  const fromContent = renderAtVersion(name, from);
+  const toContent = renderAtVersion(name, to);
+  if (fromContent === null) {
+    console.error(
+      `Version "${from}" of skill "${name}" is not in the CLI. Known: ${versions.join(", ")}.`
+    );
+    process.exit(1);
+  }
+  if (toContent === null) {
+    console.error(
+      `Version "${to}" of skill "${name}" is not in the CLI. Known: ${versions.join(", ")}.`
+    );
+    process.exit(1);
+  }
+  if (from === to) {
+    console.log(`(no diff \u2014 both sides are v${from})`);
+    return;
+  }
+  process.stdout.write(
+    jsUnifiedDiff(fromContent, toContent, `${name}@${from}`, `${name}@${to}`)
+  );
+}
+function runSync() {
+  const manifest = Object.entries(SKILL_TEMPLATES).map(([key, t]) => ({
+    name: key,
+    version: t.version,
+    description: t.description,
+    knownVersions: knownVersions(key),
+    installedPaths: {
+      claudeProject: `.claude/skills/${key}/SKILL.md`,
+      claudePersonal: join2(homedir(), ".claude", "skills", key, "SKILL.md"),
+      codexProject: `.codex/skills/${key}/SKILL.md`,
+      codexPersonal: join2(homedir(), ".codex", "skills", key, "SKILL.md"),
+      copilotProject: `.github/skills/${key}/SKILL.md`,
+      copilotPersonal: join2(homedir(), ".copilot", "skills", key, "SKILL.md")
+    }
+  }));
+  const instructions = `# Canary Skill Sync \u2014 Instructions for the Agent
+
+You are an AI coding agent (Claude, Codex, Copilot, etc.). The user ran \`canary skill sync\`
+to bring their installed Canary skill templates up to date. Follow these steps:
+
+## Step 1 \u2014 For each skill in the manifest below
+
+Check whether it is installed in any of the \`installedPaths\` (project or personal,
+for your agent type). A skill is considered installed if the \`SKILL.md\` file exists.
+
+## Step 2 \u2014 Read the version of each installed skill
+
+The \`SKILL.md\` frontmatter contains a \`version: X.Y.Z\` line. Parse that value.
+If the frontmatter has no \`version:\` field, treat the installed version as \`0.0.0\`.
+
+## Step 3 \u2014 Compare semver
+
+For each installed skill, compare \`installedVersion\` to the \`version\` in the manifest:
+- If \`installedVersion < manifestVersion\` \u2192 the skill is **outdated**, update it.
+- If equal or greater \u2192 leave it alone.
+
+## Step 4 \u2014 For each outdated skill, inspect what changed
+
+Before overwriting, read the diff so you know what's new:
+
+    canary skill diff <name> --from <installedVersion>
+
+The CLI retains past renders of each skill in \`previousVersions\`, so this prints a
+unified diff from the user's installed version \u2192 the current version. Only versions
+listed in \`knownVersions\` in the manifest can be diffed; if \`installedVersion\` is
+older than the oldest known version, diff against the oldest known version instead
+and warn the user that the older content is no longer reproducible.
+
+Use the diff to:
+- Summarize what changed for the user (new sections, removed guidance, renamed commands).
+- Decide whether any user-local edits to the installed SKILL.md would be clobbered \u2014
+  if the user appears to have edited their local copy, surface that and ask before
+  overwriting.
+
+## Step 5 \u2014 Update outdated skills
+
+Re-install by running:
+
+    canary skill install <name>                # for project installs
+    canary skill install <name> --personal     # for personal installs
+
+Preserve whichever location it was already installed in. Do NOT install skills that
+weren't already installed \u2014 sync only updates existing installs.
+
+## Step 6 \u2014 Report
+
+Print a concise summary: which skills were updated (old \u2192 new version), which were
+already current, and which were not installed (skipped).
+
+## Manifest
+
+\`\`\`json
+${JSON.stringify({ skills: manifest }, null, 2)}
+\`\`\`
+`;
+  process.stdout.write(instructions);
+}
+function parseInstallArgs(argv) {
+  let name;
+  let agent;
+  let personal = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--agent" && i + 1 < argv.length) {
+      const val = argv[++i];
+      if (!isAgentType(val)) {
+        console.error(
+          `Unknown agent "${val}". Supported agents: ${SUPPORTED_AGENTS.join(", ")}`
+        );
+        process.exit(1);
+      }
+      agent = val;
+    } else if (arg === "--personal") {
+      personal = true;
+    } else if (!arg.startsWith("-") && !name) {
+      name = arg;
+    }
+  }
+  return { name, agent, personal };
+}
+async function runInstall(argv) {
+  const { name, agent: explicitAgent, personal } = parseInstallArgs(argv);
+  if (!name) {
+    console.error("Missing skill name.\n");
+    console.error(
+      `Usage: canary skill install <name> [--agent ${SUPPORTED_AGENTS.join("|")}] [--personal]`
+    );
+    process.exit(1);
+  }
+  const template = SKILL_TEMPLATES[name];
+  if (!template) {
+    console.error(`Unknown skill template "${name}".
+`);
+    console.error("Available templates:");
+    for (const [key, t] of Object.entries(SKILL_TEMPLATES)) {
+      console.error(`  ${key.padEnd(24)} ${t.description}`);
+    }
+    process.exit(1);
+  }
+  const agent = explicitAgent ?? detectAgent();
+  if (!agent) {
+    console.error(
+      "Could not auto-detect the AI agent. Use --agent to specify:\n"
+    );
+    console.error(
+      "  canary skill install <name> --agent claude    # Claude Code"
+    );
+    console.error(
+      "  canary skill install <name> --agent codex     # OpenAI Codex"
+    );
+    console.error(
+      "  canary skill install <name> --agent copilot   # GitHub Copilot"
+    );
+    process.exit(1);
+  }
+  const dir = resolveInstallDir(name, agent, personal);
+  const filePath = join2(dir, "SKILL.md");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, template.render(), "utf-8");
+  const relPath = personal ? filePath : filePath.replace(process.cwd() + "/", "");
+  console.log(`Installed ${name} skill for ${agent} \u2192 ${relPath}`);
+}
+async function runSkill(argv) {
+  const [sub] = argv;
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h" || sub === "list") {
+    printSkillHelp();
+    return;
+  }
+  if (sub === "install") {
+    await runInstall(argv.slice(1));
+    return;
+  }
+  if (sub === "sync") {
+    runSync();
+    return;
+  }
+  if (sub === "diff") {
+    runDiff(argv.slice(1));
+    return;
+  }
+  if (sub === "versions") {
+    runVersions(argv.slice(1));
+    return;
+  }
+  const template = SKILL_TEMPLATES[sub];
+  if (!template) {
+    console.error(`Unknown skill template "${sub}".
+`);
+    printSkillHelp();
+    process.exit(1);
+  }
+  process.stdout.write(template.render());
+}
+export {
+  detectAgent,
+  resolveInstallDir,
+  runSkill
+};
+//# sourceMappingURL=skill-KM34LDMO.js.map