@runcofactor/cli 0.10.0 → 0.13.0

package/dist/{skill-KM34LDMO.js → skill-23WAHUOB.js}

@@ -1,8 +1,12 @@
 import { createRequire as __cr } from "module"; const require = __cr(import.meta.url);
+import {
+  brandSkillContentFor,
+  command
+} from "./chunk-JZMJUPZP.js";
 import "./chunk-VKVL7WBN.js";
 
 // src/skill.ts
-import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join as join2 } from "path";
 
@@ -448,7 +452,7 @@ After exploring an app via \`canary session\`, you can persist what you discover
 - 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.
+- Inline assertion format: \`{ "condition": "...", "severity": "fatal" | "fail" | "warn" }\` (fatal = halt the test now, fail = mark run failed but continue, warn = record only). **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
 
@@ -1103,22 +1107,22 @@ 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",
+  description: "Author high-quality test cases as `.cofactor.md` specs that compile straight into Cofactor 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.3.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.
+version: 2.3.0
+description: Author high-quality test cases as \`.cofactor.md\` specs that compile straight into Cofactor 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)
+# Test Case Authoring (Cofactor)
 
-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.
+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 **\`.cofactor.md\` spec files** \u2014 each file is one workflow, one journey, one test case. \`cofactor spec compile <file>\` turns them into runnable Cofactor workflows; \`cofactor spec validate <file>\` enforces the structural rules below. (Legacy \`.canary.md\` files still validate and compile; new specs default to \`.cofactor.md\`.)
 
 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\`.
+2. **Spec mapping** \u2014 how each rubric piece becomes a section of \`.cofactor.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.
@@ -1134,7 +1138,7 @@ A case covers a single coherent journey \u2014 one user objective, possibly with
 
 - 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.
+- Bad (unrelated jobs): "Submit a ticket, edit a user, generate a report." \u2014 three journeys, three separate \`.cofactor.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.
 
@@ -1143,7 +1147,7 @@ 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.
+Lint enforces this as **R1**: a spec with zero run-failing (\`fail\`/\`fatal\`) 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.
@@ -1187,52 +1191,52 @@ Aim for the smallest set that proves the feature works. Five sharp cases beat tw
 
 ---
 
-## 3. Authoring \`.canary.md\`
+## 3. Authoring \`.cofactor.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.
+\`.cofactor.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
+cofactor spec --help               # validate / compile / diff commands
+cofactor spec validate <file>      # parse + lint offline; enforce the rules in \xA71
+cofactor spec compile <file>       # create or update the workflow (prints the live URL)
+cofactor 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.
+After \`cofactor 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\`                                          |
+| Rubric piece                            | Where it lives in \`.cofactor.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\`. |
+| 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 \`cofactor credential-template list --property "<property>"\`; list credentials with \`cofactor 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 |
+| Inline expected results                 | \`- assert (fatal \\| fail \\| warn): <condition>\` under the action that produced it. \`fatal\` ends the test now (gating preconditions), \`fail\` marks the run failed but keeps going (feature claims), \`warn\` records without failing (cosmetics) |
 | 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.
+When a journey shares setup and naturally flows end-to-end, emit **one** \`.cofactor.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
+   - \`cofactor property list\` \u2014 properties (target apps)
+   - \`cofactor credential-template list --property "<property>"\` \u2014 credential templates (these are what \`actor:\` and \`- credential \u2026\` reference)
+   - \`cofactor workflow list --search <term>\` \u2014 existing workflows to seed/link to
+   - \`cofactor 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.
 
@@ -1240,13 +1244,13 @@ When you need a value (workflow-level \`## Inputs\` or step-level \`- field\`),
 
 ## 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).
+For each case, write a \`.cofactor.md\` file alongside a one-row summary line. Default location: \`cofactor/specs/<slug>.cofactor.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> |
+| cofactor/specs/submit-ticket.cofactor.md | Submit a ticket and confirm it appears in the queue | p0       | <ticket/PRD ref> |
 
 ### Per-case file
 
@@ -1281,8 +1285,9 @@ requirementRef: <ticket id, PRD path, design link>
 > <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>
+- assert (fatal): <gating precondition \u2014 test must stop if wrong>
+- assert (fail): <observable condition \u2014 feature is broken if wrong>
+- assert (warn): <softer signal \u2014 cosmetic, run still passes>
 
 **End**.
 \`\`\`
@@ -1297,11 +1302,11 @@ 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>      |
+| cofactor/specs/submit-ticket.cofactor.md       | Submit a ticket and confirm it appears in the queue | p0       | <fill in>      |
+| cofactor/specs/ticket-required-fields.cofactor.md | Required-field validation blocks submit          | p1       | <fill in>      |
+| cofactor/specs/ticket-non-admin-reassign.cofactor.md | Non-admin cannot reassign a ticket            | p1       | <fill in>      |
 
-\`canary/specs/submit-ticket.canary.md\`:
+\`cofactor/specs/submit-ticket.cofactor.md\`:
 
 \`\`\`markdown
 ---
@@ -1349,7 +1354,7 @@ requirementRef: <fill in>
 **End**.
 \`\`\`
 
-After writing, run \`canary spec validate canary/specs/submit-ticket.canary.md\` and resolve any errors / warnings before handing back.
+After writing, run \`cofactor spec validate cofactor/specs/submit-ticket.cofactor.md\` and resolve any errors / warnings before handing back.
 
 ---
 
@@ -1373,21 +1378,21 @@ After writing, run \`canary spec validate canary/specs/submit-ticket.canary.md\`
 <!-- 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. -->
+<!--   - Run \`cofactor property list\` and \`cofactor credential-template list --property "<property>"\` to learn properties + the credential templates that map to \`actor:\` values. -->
+<!--   - (\`cofactor credential list\` shows live credentials \u2014 useful, but the \`actor:\` field references credential *templates*, not credentials.) -->
+<!--   - Run \`cofactor workflow list --search <feature>\` to avoid duplicating existing workflows. -->
+<!--   - Run \`cofactor 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 property**: <unfilled \u2014 the property name to target; find via \`cofactor 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).>
+- **Credentials / role matrix** (\`actor:\` is a credential template name by default \u2014 list via \`cofactor credential-template list --property "<property>"\`. Prefix with \`credential \` to bind a specific raw credential \u2014 list via \`cofactor 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>\`>
+- **Spec directory**: <unfilled \u2014 where \`.cofactor.md\` files live in this repo, e.g. \`cofactor/specs/\`>
+- **Existing workflows to extend or avoid duplicating**: <unfilled \u2014 search via \`cofactor 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>
 
@@ -1456,6 +1461,70 @@ var SKILL_TEMPLATES = {
 };
 
 // src/skill.ts
+var SKILL_SOURCE_KEY = "skill-source";
+function renderForActiveBrand(template) {
+  return brandSkillContentFor(template.render(), command);
+}
+function splitFrontmatter(content) {
+  const lines = content.split("\n");
+  if (lines[0] !== "---") return null;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      return {
+        frontmatter: lines.slice(1, i).join("\n"),
+        // Keep the closing `---` and everything after it in the body so a
+        // round-trip with `applyInstallIdentity` reproduces the file exactly.
+        body: lines.slice(i).join("\n")
+      };
+    }
+  }
+  return null;
+}
+function readFrontmatterField(frontmatter, key) {
+  for (const line of frontmatter.split("\n")) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match && match[1] === key) return match[2].trim();
+  }
+  return null;
+}
+function installedSourceKey(content) {
+  const parts = splitFrontmatter(content);
+  if (!parts) return null;
+  return readFrontmatterField(parts.frontmatter, SKILL_SOURCE_KEY) ?? readFrontmatterField(parts.frontmatter, "name");
+}
+function applyInstallIdentity(content, installName, templateKey) {
+  if (installName === templateKey) return content;
+  const parts = splitFrontmatter(content);
+  if (!parts) return content;
+  const out = [];
+  let wroteName = false;
+  let wroteSource = false;
+  for (const line of parts.frontmatter.split("\n")) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    const key = match?.[1];
+    if (key === "name") {
+      out.push(`name: ${installName}`);
+      out.push(`${SKILL_SOURCE_KEY}: ${templateKey}`);
+      wroteName = true;
+      wroteSource = true;
+    } else if (key === SKILL_SOURCE_KEY) {
+      if (!wroteSource) {
+        out.push(`${SKILL_SOURCE_KEY}: ${templateKey}`);
+        wroteSource = true;
+      }
+    } else {
+      out.push(line);
+    }
+  }
+  if (!wroteName) out.unshift(`name: ${installName}`);
+  if (!wroteSource) {
+    const nameIdx = out.findIndex((l) => l.startsWith("name:"));
+    out.splice(nameIdx >= 0 ? nameIdx + 1 : 0, 0, `${SKILL_SOURCE_KEY}: ${templateKey}`);
+  }
+  return `---
+${out.join("\n")}
+${parts.body}`;
+}
 var SUPPORTED_AGENTS = ["claude", "codex", "copilot"];
 function isAgentType(value) {
   return value === "claude" || value === "codex" || value === "copilot";
@@ -1493,6 +1562,8 @@ function printSkillHelp() {
     "  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 install <name> --name <as>      Install under a custom skill name",
+    "  canary skill install <name> --force          Overwrite a name held by another skill",
     "  canary skill list                            List available skill templates",
     "  canary skill sync                            Print manifest + instructions for the",
     "                                               agent to version-compare and update",
@@ -1518,6 +1589,21 @@ function printSkillHelp() {
     "    4. .claude/.codex/.github dirs \u2192 whichever single one exists",
     "    5. If ambiguous, use --agent to specify explicitly",
     "",
+    "Custom skill names (--name):",
+    "  By default a skill installs under its template name. Pass --name to install",
+    "  it under a name of your choosing \u2014 useful when you want every Canary-provided",
+    "  skill namespaced (e.g. canary-browser-testing) to avoid colliding with your",
+    "  own skills. --name sets both the install directory and the SKILL.md",
+    "  frontmatter name: (agents require those to match), and records the source",
+    "  template in a skill-source: field so `sync` and `diff` keep tracking updates",
+    "  even under the renamed install.",
+    "",
+    "    canary skill install browser-testing --name canary-browser-testing",
+    "",
+    "  Installing a different skill onto an existing custom name is refused unless",
+    "  you pass --force. When an agent installs skills on your behalf, it should",
+    "  follow your naming convention.",
+    "",
     "Available templates:"
   ];
   for (const [key, template] of Object.entries(SKILL_TEMPLATES)) {
@@ -1678,10 +1764,25 @@ function runSync() {
 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
+## Step 1 \u2014 Discover installed skills (including renamed ones)
+
+Skills can be installed under a **custom name** (\`canary skill install <name> --name <as>\`),
+so do not rely only on the canonical \`installedPaths\` below. List every \`SKILL.md\`
+under your agent's skills directory \u2014 both project and personal:
+
+    .claude/skills/*/SKILL.md   and  ~/.claude/skills/*/SKILL.md     (claude)
+    .codex/skills/*/SKILL.md    and  ~/.codex/skills/*/SKILL.md      (codex)
+    .github/skills/*/SKILL.md   and  ~/.copilot/skills/*/SKILL.md    (copilot)
 
-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.
+For each file, read its frontmatter and resolve which manifest skill it came from:
+- If a \`skill-source: <key>\` line is present, that \`<key>\` is the template name
+  (the skill was installed under a custom \`--name\`). The install directory is the
+  custom name; remember it for Step 5.
+- Otherwise the \`name:\` value is the template name (a default install, where the
+  install name equals the template key).
+
+Match that resolved key against the manifest \`name\` field. Ignore any \`SKILL.md\`
+whose resolved key is not in the manifest (it isn't a Canary skill).
 
 ## Step 2 \u2014 Read the version of each installed skill
 
@@ -1696,9 +1797,11 @@ For each installed skill, compare \`installedVersion\` to the \`version\` in the
 
 ## Step 4 \u2014 For each outdated skill, inspect what changed
 
-Before overwriting, read the diff so you know what's new:
+Before overwriting, read the diff so you know what's new. Diff by the **template
+key** you resolved in Step 1 (not the custom install name) \u2014 the diff compares
+source renders and is independent of how the skill was named on disk:
 
-    canary skill diff <name> --from <installedVersion>
+    canary skill diff <templateKey> --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
@@ -1714,13 +1817,19 @@ Use the diff to:
 
 ## Step 5 \u2014 Update outdated skills
 
-Re-install by running:
+Re-install with the template key, preserving both the location AND the custom name
+it was installed under (the install directory name from Step 1):
 
-    canary skill install <name>                # for project installs
-    canary skill install <name> --personal     # for personal installs
+    canary skill install <templateKey>                              # default-named project install
+    canary skill install <templateKey> --personal                   # default-named personal install
+    canary skill install <templateKey> --name <installDir>          # custom-named project install
+    canary skill install <templateKey> --name <installDir> --personal
 
-Preserve whichever location it was already installed in. Do NOT install skills that
-weren't already installed \u2014 sync only updates existing installs.
+Preserve whichever location and name it was already installed in \u2014 if it lived in
+\`canary-browser-testing/\`, re-install with \`--name canary-browser-testing\` so the
+update lands in place rather than creating a second default-named copy. Do NOT install
+skills that weren't already installed \u2014 sync only updates existing installs. When the
+user has a naming convention, keep installing under their chosen names on their behalf.
 
 ## Step 6 \u2014 Report
 
@@ -1735,10 +1844,15 @@ ${JSON.stringify({ skills: manifest }, null, 2)}
 `;
   process.stdout.write(instructions);
 }
+function isValidInstallName(value) {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value);
+}
 function parseInstallArgs(argv) {
-  let name;
+  let templateName;
+  let installName;
   let agent;
   let personal = false;
+  let force = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--agent" && i + 1 < argv.length) {
@@ -1750,26 +1864,43 @@ function parseInstallArgs(argv) {
         process.exit(1);
       }
       agent = val;
+    } else if (arg === "--name" && i + 1 < argv.length) {
+      const val = argv[++i];
+      if (!isValidInstallName(val)) {
+        console.error(
+          `Invalid skill name "${val}". Use letters, digits, hyphens, or underscores (e.g. canary-browser-testing).`
+        );
+        process.exit(1);
+      }
+      installName = val;
     } else if (arg === "--personal") {
       personal = true;
-    } else if (!arg.startsWith("-") && !name) {
-      name = arg;
+    } else if (arg === "--force" || arg === "-f") {
+      force = true;
+    } else if (!arg.startsWith("-") && !templateName) {
+      templateName = arg;
     }
   }
-  return { name, agent, personal };
+  return { templateName, installName: installName ?? templateName, agent, personal, force };
 }
 async function runInstall(argv) {
-  const { name, agent: explicitAgent, personal } = parseInstallArgs(argv);
-  if (!name) {
+  const {
+    templateName,
+    installName,
+    agent: explicitAgent,
+    personal,
+    force
+  } = parseInstallArgs(argv);
+  if (!templateName || !installName) {
     console.error("Missing skill name.\n");
     console.error(
-      `Usage: canary skill install <name> [--agent ${SUPPORTED_AGENTS.join("|")}] [--personal]`
+      `Usage: canary skill install <name> [--name <install-name>] [--agent ${SUPPORTED_AGENTS.join("|")}] [--personal] [--force]`
     );
     process.exit(1);
   }
-  const template = SKILL_TEMPLATES[name];
+  const template = SKILL_TEMPLATES[templateName];
   if (!template) {
-    console.error(`Unknown skill template "${name}".
+    console.error(`Unknown skill template "${templateName}".
 `);
     console.error("Available templates:");
     for (const [key, t] of Object.entries(SKILL_TEMPLATES)) {
@@ -1793,12 +1924,27 @@ async function runInstall(argv) {
     );
     process.exit(1);
   }
-  const dir = resolveInstallDir(name, agent, personal);
+  const dir = resolveInstallDir(installName, agent, personal);
   const filePath = join2(dir, "SKILL.md");
+  if (existsSync(filePath) && !force) {
+    const existingSource = installedSourceKey(readFileSync2(filePath, "utf-8"));
+    if (existingSource && existingSource !== templateName) {
+      console.error(
+        `\u2717 ${installName} already holds '${existingSource}'. Pass --force to overwrite.`
+      );
+      process.exit(1);
+    }
+  }
+  const content = applyInstallIdentity(
+    renderForActiveBrand(template),
+    installName,
+    templateName
+  );
   mkdirSync(dir, { recursive: true });
-  writeFileSync(filePath, template.render(), "utf-8");
+  writeFileSync(filePath, content, "utf-8");
   const relPath = personal ? filePath : filePath.replace(process.cwd() + "/", "");
-  console.log(`Installed ${name} skill for ${agent} \u2192 ${relPath}`);
+  const named = installName === templateName ? "" : ` as ${installName}`;
+  console.log(`Installed ${templateName} skill for ${agent}${named} \u2192 ${relPath}`);
 }
 async function runSkill(argv) {
   const [sub] = argv;
@@ -1829,11 +1975,15 @@ async function runSkill(argv) {
     printSkillHelp();
     process.exit(1);
   }
-  process.stdout.write(template.render());
+  process.stdout.write(renderForActiveBrand(template));
 }
 export {
+  SKILL_SOURCE_KEY,
+  applyInstallIdentity,
   detectAgent,
+  installedSourceKey,
+  isValidInstallName,
   resolveInstallDir,
   runSkill
 };
-//# sourceMappingURL=skill-KM34LDMO.js.map
+//# sourceMappingURL=skill-23WAHUOB.js.map