@xera-ai/cli 0.12.3 → 0.13.1

package/dist/index.js

@@ -7,18 +7,265 @@ import { cac } from "cac";
 import pc4 from "picocolors";
 
 // src/commands/doctor.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { NdjsonLogger, resolveArtifactPaths } from "@xera-ai/core";
 import pc from "picocolors";
 
 // src/checks.ts
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
+import { join as join5 } from "path";
 import { loadConfig, readAuthState } from "@xera-ai/core";
 import { parse as parseYaml } from "yaml";
+
+// src/editors/claude.ts
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
+// src/editors/frontmatter.ts
+var FENCE = "---";
+function parseFrontmatter(md) {
+  if (!md.startsWith(`${FENCE}
+`)) {
+    return { frontmatter: { raw: "", fields: {} }, body: md };
+  }
+  const closeIdx = md.indexOf(`
+${FENCE}
+`, FENCE.length + 1);
+  if (closeIdx < 0) {
+    return { frontmatter: { raw: "", fields: {} }, body: md };
+  }
+  const raw = md.slice(FENCE.length + 1, closeIdx);
+  const body = md.slice(closeIdx + `
+${FENCE}
+`.length);
+  const fields = {};
+  const lines = raw.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim())
+      continue;
+    const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!m)
+      continue;
+    const key = m[1];
+    const value = m[2];
+    if (value === "|") {
+      const collected = [];
+      while (i + 1 < lines.length) {
+        const next = lines[i + 1];
+        if (/^ {2,}/.test(next)) {
+          collected.push(next.replace(/^ {2}/, ""));
+          i++;
+        } else if (next.trim() === "") {
+          collected.push("");
+          i++;
+        } else {
+          break;
+        }
+      }
+      while (collected.length && collected[collected.length - 1] === "")
+        collected.pop();
+      fields[key] = collected.join(`
+`);
+    } else if (value === "true" || value === "false") {
+      fields[key] = value === "true";
+    } else if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+      fields[key] = value.slice(1, -1).replace(/\\"/g, '"');
+    } else {
+      fields[key] = value;
+    }
+  }
+  return { frontmatter: { raw, fields }, body };
+}
+function serializeFrontmatter(fields) {
+  const lines = [FENCE];
+  for (const [key, value] of Object.entries(fields)) {
+    if (typeof value === "boolean") {
+      lines.push(`${key}: ${value}`);
+    } else if (Array.isArray(value)) {
+      lines.push(`${key}: [${value.join(", ")}]`);
+    } else if (value.includes(`
+`)) {
+      lines.push(`${key}: |`);
+      for (const sub of value.split(`
+`))
+        lines.push(`  ${sub}`);
+    } else if (/[:#]/.test(value)) {
+      lines.push(`${key}: "${value.replace(/"/g, "\\\"")}"`);
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+  lines.push(FENCE);
+  return `${lines.join(`
+`)}
+`;
+}
+
+// src/editors/claude.ts
+function renderSource(input) {
+  return serializeFrontmatter(input.frontmatter.fields) + input.body;
+}
+var claudeAdapter = {
+  name: "claude",
+  detect(cwd) {
+    return existsSync(join(cwd, ".claude"));
+  },
+  scaffoldSkill(cwd, input) {
+    const target = join(cwd, ".claude/skills", input.base, "SKILL.md");
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, renderSource(input));
+  },
+  scaffoldCommand(cwd, input) {
+    const target = join(cwd, ".claude/commands", `${input.base}.md`);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, renderSource(input));
+  },
+  legacyMigrate(cwd, base) {
+    const flat = join(cwd, ".claude/skills", `${base}.md`);
+    const dir = join(cwd, ".claude/skills", base, "SKILL.md");
+    if (!existsSync(flat) || existsSync(dir))
+      return false;
+    const content = readFileSync(flat);
+    mkdirSync(dirname(dir), { recursive: true });
+    writeFileSync(dir, content);
+    unlinkSync(flat);
+    return true;
+  },
+  doctorChecks(cwd, requiredSkills) {
+    const skillsDir = join(cwd, ".claude/skills");
+    if (!existsSync(skillsDir)) {
+      return [{ name: "xera skills present (claude)", ok: false, message: "run `xera init`" }];
+    }
+    const missing = [];
+    const legacyFlat = [];
+    for (const base of requiredSkills) {
+      if (existsSync(join(skillsDir, base, "SKILL.md")))
+        continue;
+      if (existsSync(join(skillsDir, `${base}.md`)))
+        legacyFlat.push(base);
+      else
+        missing.push(base);
+    }
+    const check = {
+      name: "xera skills present (claude)",
+      ok: missing.length === 0 && legacyFlat.length === 0
+    };
+    if (missing.length) {
+      check.message = `missing: ${missing.map((b) => `${b}/SKILL.md`).join(", ")}`;
+    } else if (legacyFlat.length) {
+      check.message = `legacy flat layout \u2014 run \`xera init --update --editor claude\` to migrate`;
+    }
+    return [check];
+  }
+};
+
+// src/editors/codex.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+var codexAdapter = {
+  name: "codex",
+  detect(cwd) {
+    return existsSync2(join2(cwd, ".agents"));
+  },
+  scaffoldSkill(cwd, input) {
+    const target = join2(cwd, ".agents/skills", input.base, "SKILL.md");
+    mkdirSync2(dirname2(target), { recursive: true });
+    writeFileSync2(target, serializeFrontmatter(input.frontmatter.fields) + input.body);
+  },
+  doctorChecks(cwd, requiredSkills) {
+    const skillsDir = join2(cwd, ".agents/skills");
+    const missing = requiredSkills.filter((b) => !existsSync2(join2(skillsDir, b, "SKILL.md")));
+    const check = {
+      name: "xera skills present (codex)",
+      ok: missing.length === 0
+    };
+    if (missing.length) {
+      check.message = `missing: ${missing.map((b) => `${b}/SKILL.md`).join(", ")} \u2014 run \`xera init --update --editor codex\``;
+    }
+    return [check];
+  }
+};
+
+// src/editors/cursor.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join3 } from "path";
+function ruleFrontmatter(input) {
+  const desc = input.frontmatter.fields.description;
+  if (desc === undefined) {
+    throw new Error(`Cursor scaffold requires 'description' in source frontmatter for ${input.base}`);
+  }
+  return { description: desc, alwaysApply: false };
+}
+function commandFrontmatter(input) {
+  const desc = input.frontmatter.fields.description;
+  if (desc === undefined) {
+    throw new Error(`Cursor scaffold requires 'description' in source frontmatter for ${input.base}`);
+  }
+  return { description: desc };
+}
+function write(target, content) {
+  mkdirSync3(dirname3(target), { recursive: true });
+  writeFileSync3(target, content);
+}
+var cursorAdapter = {
+  name: "cursor",
+  detect(cwd) {
+    return existsSync3(join3(cwd, ".cursor"));
+  },
+  scaffoldSkill(cwd, input) {
+    const path = join3(cwd, ".cursor/rules", input.base, "RULE.md");
+    write(path, serializeFrontmatter(ruleFrontmatter(input)) + input.body);
+  },
+  scaffoldCommand(cwd, input) {
+    const path = join3(cwd, ".cursor/commands", `${input.base}.md`);
+    write(path, serializeFrontmatter(commandFrontmatter(input)) + input.body);
+  },
+  doctorChecks(cwd, requiredSkills) {
+    const rulesDir = join3(cwd, ".cursor/rules");
+    const cmdsDir = join3(cwd, ".cursor/commands");
+    const missing = [];
+    for (const base of requiredSkills) {
+      if (!existsSync3(join3(rulesDir, base, "RULE.md")))
+        missing.push(`${base}/RULE.md`);
+      if (!existsSync3(join3(cmdsDir, `${base}.md`)))
+        missing.push(`commands/${base}.md`);
+    }
+    const check = {
+      name: "xera skills present (cursor)",
+      ok: missing.length === 0
+    };
+    if (missing.length)
+      check.message = `missing: ${missing.join(", ")} \u2014 run \`xera init --update --editor cursor\``;
+    return [check];
+  }
+};
+
+// src/editors/index.ts
+var ALL_EDITORS = ["claude", "cursor", "codex"];
+var editors = {
+  claude: claudeAdapter,
+  cursor: cursorAdapter,
+  codex: codexAdapter
+};
+
+// src/editors/detect.ts
+import { existsSync as existsSync4 } from "fs";
+import { join as join4 } from "path";
+var MARKERS = {
+  claude: ".claude",
+  cursor: ".cursor",
+  codex: ".agents"
+};
+function detectEditors(cwd) {
+  return ALL_EDITORS.filter((name) => existsSync4(join4(cwd, MARKERS[name])));
+}
+
+// src/checks.ts
 function pushTicketChecks(checks, cwd, ticket, acFieldConfigured) {
-  const ticketDir = join(cwd, ".xera", ticket);
-  if (!existsSync(ticketDir)) {
+  const ticketDir = join5(cwd, ".xera", ticket);
+  if (!existsSync5(ticketDir)) {
     checks.push({
       name: `${ticket}: .xera/${ticket}/ exists`,
       ok: false,
@@ -26,8 +273,8 @@ function pushTicketChecks(checks, cwd, ticket, acFieldConfigured) {
     });
     return;
   }
-  const giPath = join(ticketDir, "graph-input.json");
-  if (!existsSync(giPath)) {
+  const giPath = join5(ticketDir, "graph-input.json");
+  if (!existsSync5(giPath)) {
     checks.push({
       name: `${ticket}: graph-input.json present`,
       ok: false,
@@ -35,7 +282,7 @@ function pushTicketChecks(checks, cwd, ticket, acFieldConfigured) {
     });
   } else {
     try {
-      const data = JSON.parse(readFileSync(giPath, "utf8"));
+      const data = JSON.parse(readFileSync2(giPath, "utf8"));
       if (!Array.isArray(data.modifiesAreas)) {
         checks.push({
           name: `${ticket}: graph-input.json present`,
@@ -57,8 +304,8 @@ function pushTicketChecks(checks, cwd, ticket, acFieldConfigured) {
       });
     }
   }
-  const storyPath = join(ticketDir, "story.md");
-  if (!existsSync(storyPath)) {
+  const storyPath = join5(ticketDir, "story.md");
+  if (!existsSync5(storyPath)) {
     checks.push({
       name: `${ticket}: story.md acceptanceCriteria`,
       ok: false,
@@ -66,7 +313,7 @@ function pushTicketChecks(checks, cwd, ticket, acFieldConfigured) {
     });
     return;
   }
-  const raw = readFileSync(storyPath, "utf8");
+  const raw = readFileSync2(storyPath, "utf8");
   const m = raw.match(/^---\n([\s\S]*?)\n---/);
   if (!m) {
     checks.push({
@@ -88,20 +335,29 @@ function pushTicketChecks(checks, cwd, ticket, acFieldConfigured) {
     return;
   }
   const ac = Array.isArray(fm.acceptanceCriteria) ? fm.acceptanceCriteria : [];
-  if (ac.length === 0) {
-    const hint = acFieldConfigured ? `jira.fields.acceptanceCriteria is configured but Jira returned no AC for this ticket \u2014 check the ticket in Jira` : `no AC in frontmatter; AC-level coverage will be empty. Set jira.fields.acceptanceCriteria in xera.config.ts if your project stores AC in a dedicated Jira field`;
-    checks.push({
-      name: `${ticket}: story.md acceptanceCriteria`,
-      ok: false,
-      message: hint
-    });
-  } else {
+  const source = fm.acceptanceCriteriaSource === "jira-field" || fm.acceptanceCriteriaSource === "body-extraction" || fm.acceptanceCriteriaSource === "none" ? fm.acceptanceCriteriaSource : undefined;
+  if (ac.length > 0) {
+    const suffix = source ? ` from ${source}` : "";
     checks.push({
       name: `${ticket}: story.md acceptanceCriteria`,
       ok: true,
-      message: `${ac.length} AC item(s)`
+      message: `${ac.length} AC item(s)${suffix}`
     });
+    return;
+  }
+  let hint;
+  if (source === "none") {
+    hint = acFieldConfigured ? `jira.fields.acceptanceCriteria is configured but Jira returned no AC for this ticket, and /xera-fetch step 4 found no AC section in the body \u2014 add AC to the Jira ticket` : `AC not in Jira (no custom field configured) and /xera-fetch step 4 found no AC section in the description body \u2014 add AC/DoD to the Jira ticket, or edit story.md frontmatter manually`;
+  } else if (source === "body-extraction") {
+    hint = `acceptanceCriteriaSource: body-extraction but acceptanceCriteria is empty \u2014 re-run /xera-fetch ${ticket}`;
+  } else {
+    hint = acFieldConfigured ? `jira.fields.acceptanceCriteria is configured but Jira returned no AC for this ticket \u2014 check the ticket in Jira` : `no AC in frontmatter; AC-level coverage will be empty. Re-run /xera-fetch ${ticket} so step 4 can extract AC from the body (set jira.fields.acceptanceCriteria in xera.config.ts if your project uses a dedicated Jira field)`;
   }
+  checks.push({
+    name: `${ticket}: story.md acceptanceCriteria`,
+    ok: false,
+    message: hint
+  });
 }
 async function runChecks(cwd, opts = {}) {
   const checks = [];
@@ -153,10 +409,10 @@ async function runChecks(cwd, opts = {}) {
           });
         }
       }
-      const httpAuthDir = join(cwd, ".xera", ".auth", "http");
+      const httpAuthDir = join5(cwd, ".xera", ".auth", "http");
       for (const role of Object.keys(cfg.http.auth.roles)) {
-        const filePath = join(httpAuthDir, `${role}.json`);
-        if (!existsSync(filePath)) {
+        const filePath = join5(httpAuthDir, `${role}.json`);
+        if (!existsSync5(filePath)) {
           checks.push({
             name: `http auth file present: ${role}`,
             ok: false,
@@ -215,7 +471,7 @@ async function runChecks(cwd, opts = {}) {
             });
           }
         } else {
-          const open = existsSync(join(cwd, spec));
+          const open = existsSync5(join5(cwd, spec));
           const openCheck = open ? { name: "OpenAPI spec file present", ok: true } : { name: "OpenAPI spec file present", ok: false, message: `not found at ${spec}` };
           checks.push(openCheck);
         }
@@ -234,10 +490,10 @@ async function runChecks(cwd, opts = {}) {
         message: `${cfg.coverage.staleAfterDays}d is a very large window \u2014 coverage will be slow to react to drift`
       });
     }
-    const snapPath = join(cwd, ".xera/graph/snapshot.json");
-    if (existsSync(snapPath) && cfg.coverage.criticalAreas.length > 0) {
+    const snapPath = join5(cwd, ".xera/graph/snapshot.json");
+    if (existsSync5(snapPath) && cfg.coverage.criticalAreas.length > 0) {
       try {
-        const snap = JSON.parse(readFileSync(snapPath, "utf8"));
+        const snap = JSON.parse(readFileSync2(snapPath, "utf8"));
         const known = new Set(Object.keys(snap.areas ?? {}));
         for (const slug of cfg.coverage.criticalAreas) {
           if (!known.has(slug)) {
@@ -250,9 +506,9 @@ async function runChecks(cwd, opts = {}) {
         }
       } catch {}
     }
-    if (existsSync(snapPath)) {
+    if (existsSync5(snapPath)) {
       try {
-        const snap = JSON.parse(readFileSync(snapPath, "utf8"));
+        const snap = JSON.parse(readFileSync2(snapPath, "utf8"));
         const acByTicket = {};
         for (const node of Object.values(snap.acNodes ?? {})) {
           acByTicket[node.ticketId] = (acByTicket[node.ticketId] ?? 0) + 1;
@@ -280,11 +536,11 @@ async function runChecks(cwd, opts = {}) {
       message: String(e.message)
     });
   }
-  const envPath = join(cwd, ".env");
-  if (!existsSync(envPath)) {
+  const envPath = join5(cwd, ".env");
+  if (!existsSync5(envPath)) {
     checks.push({ name: ".env present", ok: false, message: "copy from .env.example" });
   } else {
-    const env = readFileSync(envPath, "utf8");
+    const env = readFileSync2(envPath, "utf8");
     checks.push({ name: "XERA_AUTH_KEY set", ok: /XERA_AUTH_KEY=[0-9a-fA-F]{64}/.test(env) });
   }
   try {
@@ -297,40 +553,26 @@ async function runChecks(cwd, opts = {}) {
       message: "run: bun add -D @playwright/test"
     });
   }
-  const skillsDir = join(cwd, ".claude/skills");
-  if (!existsSync(skillsDir)) {
-    checks.push({ name: "xera skills present", ok: false, message: "run `xera init`" });
+  const REQUIRED_SKILLS = [
+    "xera-run",
+    "xera-fetch",
+    "xera-feature",
+    "xera-script",
+    "xera-exec",
+    "xera-report",
+    "xera-promote"
+  ];
+  const detected = detectEditors(cwd);
+  if (detected.length === 0) {
+    checks.push({
+      name: "xera editor integration present",
+      ok: false,
+      message: "run `xera init` (scaffolds for Claude Code, Cursor, and/or Codex)"
+    });
   } else {
-    const required = [
-      "xera-run",
-      "xera-fetch",
-      "xera-feature",
-      "xera-script",
-      "xera-exec",
-      "xera-report",
-      "xera-promote"
-    ];
-    const missing = [];
-    const legacyFlat = [];
-    for (const base of required) {
-      if (existsSync(join(skillsDir, base, "SKILL.md")))
-        continue;
-      if (existsSync(join(skillsDir, `${base}.md`))) {
-        legacyFlat.push(base);
-      } else {
-        missing.push(base);
-      }
+    for (const name of detected) {
+      checks.push(...editors[name].doctorChecks(cwd, REQUIRED_SKILLS));
     }
-    const skillsCheck = {
-      name: "xera skills present",
-      ok: missing.length === 0 && legacyFlat.length === 0
-    };
-    if (missing.length) {
-      skillsCheck.message = `missing: ${missing.map((b) => `${b}/SKILL.md`).join(", ")}`;
-    } else if (legacyFlat.length) {
-      skillsCheck.message = `legacy flat layout in .claude/skills/ \u2014 run \`xera init --update\` to migrate to <name>/SKILL.md (Claude Code Skill tool requires the directory layout)`;
-    }
-    checks.push(skillsCheck);
   }
   return checks;
 }
@@ -340,7 +582,7 @@ async function doctorCommand(opts) {
   const cwd = process.cwd();
   if (opts.logs) {
     const paths = resolveArtifactPaths(cwd, opts.logs);
-    if (!existsSync2(paths.logPath)) {
+    if (!existsSync6(paths.logPath)) {
       console.log(`No log at ${paths.logPath}`);
       return 0;
     }
@@ -366,25 +608,47 @@ async function doctorCommand(opts) {
 }
 
 // src/commands/init.ts
-import {
-  appendFileSync,
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync2,
-  readdirSync as readdirSync2,
-  readFileSync as readFileSync3,
-  writeFileSync as writeFileSync2
-} from "fs";
+import { appendFileSync, existsSync as existsSync7, readdirSync as readdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
 import { createRequire } from "module";
-import { dirname as dirname2, join as join3 } from "path";
+import { join as join7 } from "path";
 import * as p from "@clack/prompts";
 import { generateKey } from "@xera-ai/core";
 import pc2 from "picocolors";
 
+// src/editors/resolve.ts
+function parseFlag(flag) {
+  if (flag === "all")
+    return [...ALL_EDITORS];
+  const parts = flag.split(",").map((s) => s.trim()).filter(Boolean);
+  if (parts.length === 0) {
+    throw new Error(`--editor: empty value. Valid: ${ALL_EDITORS.join(", ")} (or 'all').`);
+  }
+  const bad = parts.filter((p) => !ALL_EDITORS.includes(p));
+  if (bad.length) {
+    throw new Error(`--editor: unknown value(s) [${bad.join(", ")}]. Valid: ${ALL_EDITORS.join(", ")} (or 'all').`);
+  }
+  return parts;
+}
+async function resolveEditors(opts) {
+  if (opts.flag !== undefined)
+    return parseFlag(opts.flag);
+  const detected = detectEditors(opts.cwd);
+  if (opts.isUpdate)
+    return detected;
+  if (detected.length > 0)
+    return detected;
+  if (opts.isYes)
+    return [...ALL_EDITORS];
+  if (opts.prompt)
+    return opts.prompt();
+  return [...ALL_EDITORS];
+}
+
 // src/scaffold.ts
-import { mkdirSync, readdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { dirname, join as join2 } from "path";
+import { mkdirSync as mkdirSync4, readdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname4, join as join6 } from "path";
 import { fileURLToPath } from "url";
-var TEMPLATE_ROOT = join2(fileURLToPath(import.meta.url), "..", "..", "templates");
+var TEMPLATE_ROOT = join6(fileURLToPath(import.meta.url), "..", "..", "templates");
 function render(tmpl, vars) {
   let out = tmpl;
   out = out.replace(/\{\{#each (\w+)\}\}([\s\S]*?)\{\{\/each\}\}/g, (_, k, block) => {
@@ -401,9 +665,9 @@ function render(tmpl, vars) {
   return out;
 }
 function scaffoldFile(targetPath, templateName, vars) {
-  const tmpl = readFileSync2(join2(TEMPLATE_ROOT, templateName), "utf8");
-  mkdirSync(dirname(targetPath), { recursive: true });
-  writeFileSync(targetPath, render(tmpl, vars));
+  const tmpl = readFileSync3(join6(TEMPLATE_ROOT, templateName), "utf8");
+  mkdirSync4(dirname4(targetPath), { recursive: true });
+  writeFileSync4(targetPath, render(tmpl, vars));
 }
 
 // src/commands/init.ts
@@ -508,26 +772,26 @@ async function initCommand(opts) {
     authKey: generateKey()
   };
   const configTmpl = shape === "web" ? "xera.config.ts.tmpl" : shape === "api" ? "http-xera.config.ts.tmpl" : "mixed-xera.config.ts.tmpl";
-  scaffoldFile(join3(cwd, "xera.config.ts"), configTmpl, vars);
+  scaffoldFile(join7(cwd, "xera.config.ts"), configTmpl, vars);
   const pwTmpl = shape === "api" ? "http-playwright.config.ts.tmpl" : "playwright.config.ts.tmpl";
-  scaffoldFile(join3(cwd, "playwright.config.ts"), pwTmpl, vars);
-  scaffoldFile(join3(cwd, "tsconfig.json"), "tsconfig.json.tmpl", vars);
+  scaffoldFile(join7(cwd, "playwright.config.ts"), pwTmpl, vars);
+  scaffoldFile(join7(cwd, "tsconfig.json"), "tsconfig.json.tmpl", vars);
   if (shape === "api") {
-    scaffoldFile(join3(cwd, ".env.example"), "http-env.example.tmpl", vars);
+    scaffoldFile(join7(cwd, ".env.example"), "http-env.example.tmpl", vars);
   } else {
-    scaffoldFile(join3(cwd, ".env.example"), "env.example.tmpl", vars);
+    scaffoldFile(join7(cwd, ".env.example"), "env.example.tmpl", vars);
   }
   if (wantsWeb || wantsHttp) {
-    scaffoldFile(join3(cwd, "shared/auth-setup.ts"), "auth-setup.ts.tmpl", vars);
+    scaffoldFile(join7(cwd, "shared/auth-setup.ts"), "auth-setup.ts.tmpl", vars);
   }
-  scaffoldFile(join3(cwd, ".github/workflows/xera-graph.yml"), "xera-graph.yml.template", vars);
+  scaffoldFile(join7(cwd, ".github/workflows/xera-graph.yml"), "xera-graph.yml.template", vars);
   if (wantsHttp && vars.openapiPath && !vars.openapiPath.startsWith("http")) {
-    const openapiTarget = join3(cwd, vars.openapiPath);
-    if (!existsSync3(openapiTarget)) {
+    const openapiTarget = join7(cwd, vars.openapiPath);
+    if (!existsSync7(openapiTarget)) {
       scaffoldFile(openapiTarget, "openapi.yaml.tmpl", vars);
     }
   }
-  const gitignorePath = join3(cwd, ".gitignore");
+  const gitignorePath = join7(cwd, ".gitignore");
   const gitignoreAdditions = [
     "",
     "# xera",
@@ -539,33 +803,55 @@ async function initCommand(opts) {
     "node_modules/"
   ].join(`
 `);
-  if (existsSync3(gitignorePath)) {
-    const current = readFileSync3(gitignorePath, "utf8");
+  if (existsSync7(gitignorePath)) {
+    const current = readFileSync4(gitignorePath, "utf8");
     if (!current.includes("# xera"))
       appendFileSync(gitignorePath, gitignoreAdditions);
   } else {
-    writeFileSync2(gitignorePath, `${gitignoreAdditions.trim()}
+    writeFileSync5(gitignorePath, `${gitignoreAdditions.trim()}
 `);
   }
+  const editorTargets = await resolveEditors({
+    flag: opts.editor,
+    cwd,
+    isUpdate: false,
+    isYes: opts.yes,
+    prompt: async () => {
+      const choice = await p.multiselect({
+        message: "Which editor(s) should xera scaffold for?",
+        options: [
+          { value: "claude", label: "Claude Code (.claude/skills/, .claude/commands/)" },
+          { value: "cursor", label: "Cursor (.cursor/rules/, .cursor/commands/)" },
+          { value: "codex", label: "OpenAI Codex CLI (.agents/skills/)" }
+        ],
+        initialValues: ["claude"],
+        required: true
+      });
+      if (typeof choice === "symbol")
+        cancel2();
+      return choice;
+    }
+  });
   const skillsPkgPath = require2.resolve("@xera-ai/skills/package.json");
-  const skillsSrcDir = join3(skillsPkgPath, "..");
+  const skillsSrcDir = join7(skillsPkgPath, "..");
   const SKILL_IGNORE = new Set(["package.json", "version.json", "CHANGELOG.md"]);
   for (const name of readdirSync2(skillsSrcDir)) {
     if (SKILL_IGNORE.has(name))
       continue;
     if (!name.endsWith(".md"))
       continue;
-    const content = readFileSync3(join3(skillsSrcDir, name));
+    const raw = readFileSync4(join7(skillsSrcDir, name), "utf8");
+    const { frontmatter, body } = parseFrontmatter(raw);
     const base = name.replace(/\.md$/, "");
-    const skillFile = join3(cwd, ".claude/skills", base, "SKILL.md");
-    mkdirSync2(dirname2(skillFile), { recursive: true });
-    writeFileSync2(skillFile, content);
-    const cmdFile = join3(cwd, ".claude/commands", name);
-    mkdirSync2(dirname2(cmdFile), { recursive: true });
-    writeFileSync2(cmdFile, content);
+    const skillInput = { base, body, frontmatter };
+    for (const editorName of editorTargets) {
+      const adapter = editors[editorName];
+      adapter.scaffoldSkill(cwd, skillInput);
+      adapter.scaffoldCommand?.(cwd, skillInput);
+    }
   }
-  const pkgPath = join3(cwd, "package.json");
-  const pkg = existsSync3(pkgPath) ? JSON.parse(readFileSync3(pkgPath, "utf8")) : { name: "xera-project", private: true, type: "module" };
+  const pkgPath = join7(cwd, "package.json");
+  const pkg = existsSync7(pkgPath) ? JSON.parse(readFileSync4(pkgPath, "utf8")) : { name: "xera-project", private: true, type: "module" };
   pkg.scripts = pkg.scripts ?? {};
   pkg.scripts["xera:fetch"] = "xera-internal fetch";
   pkg.scripts["xera:validate-feature"] = "xera-internal validate-feature";
@@ -601,7 +887,17 @@ async function initCommand(opts) {
   pkg.devDependencies["@playwright/test"] = "^1.60.0";
   pkg.devDependencies["@types/node"] = "^25.8.0";
   pkg.devDependencies["typescript"] = "^6.0.3";
-  writeFileSync2(pkgPath, JSON.stringify(pkg, null, 2));
+  writeFileSync5(pkgPath, JSON.stringify(pkg, null, 2));
+  const editorLines = editorTargets.map((e) => {
+    if (e === "claude")
+      return "       Claude Code:       /xera-run <TICKET>";
+    if (e === "cursor")
+      return "       Cursor:            /xera-run <TICKET>  (slash menu)";
+    if (e === "codex")
+      return '       OpenAI Codex CLI:  type "run xera for <TICKET>" \u2014 Codex picks up the xera-run skill';
+    return "";
+  }).join(`
+`);
   const nextSteps = shape === "api" ? `
 Next:
   1) Copy .env.example to .env and set your auth credentials:
@@ -610,7 +906,7 @@ Next:
   2) Run pre-authentication:
        bun run xera:auth-setup
   3) Start testing:
-       Open Claude Code in this directory and run: /xera-run <TICKET>
+${editorLines}
 ` : shape === "mixed" ? `
 Next:
   1) Copy .env.example to .env and set credentials (both web logins and API tokens):
@@ -618,7 +914,7 @@ Next:
   2) Run pre-authentication:
        bun run xera:auth-setup
   3) Start testing:
-       Open Claude Code in this directory and run: /xera-run <TICKET>
+${editorLines}
 ` : `
 Next:
   1) Copy .env.example to .env and set your Jira credentials:
@@ -626,7 +922,7 @@ Next:
   2) Run pre-authentication:
        bun run xera:auth-setup
   3) Start testing:
-       Open Claude Code in this directory and run: /xera-run <TICKET>
+${editorLines}
 `;
   p.note(nextSteps.trim(), "Next steps");
   p.outro(pc2.green("xera initialized!"));
@@ -635,24 +931,23 @@ Next:
 // src/commands/init-update.ts
 import {
   copyFileSync,
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync3,
+  existsSync as existsSync8,
+  mkdirSync as mkdirSync5,
   readdirSync as readdirSync3,
-  readFileSync as readFileSync4,
-  unlinkSync,
-  writeFileSync as writeFileSync3
+  readFileSync as readFileSync5,
+  writeFileSync as writeFileSync6
 } from "fs";
 import { createRequire as createRequire2 } from "module";
-import { dirname as dirname3, join as join4 } from "path";
+import { join as join8 } from "path";
 import * as p2 from "@clack/prompts";
 import pc3 from "picocolors";
 var require3 = createRequire2(import.meta.url);
 var CLI_VERSION2 = require3("../package.json").version;
 function detectAdaptersFromConfig(cwd) {
-  const configPath = join4(cwd, "xera.config.ts");
-  if (!existsSync4(configPath))
+  const configPath = join8(cwd, "xera.config.ts");
+  if (!existsSync8(configPath))
     return null;
-  const cfg = readFileSync4(configPath, "utf8");
+  const cfg = readFileSync5(configPath, "utf8");
   const m = cfg.match(/adapters:\s*\[([^\]]+)\]/);
   if (!m)
     return null;
@@ -703,7 +998,7 @@ ${roles.map((r) => `        ${r}: { envEmail: 'TEST_${r.toUpperCase().replace(/-
     `  web: {`,
     `    baseUrl: { staging: '${baseUrl}' },`,
     `    defaultEnv: 'staging',`,
-    authBlock + `  },`
+    `${authBlock}  },`
   ].join(`
 `);
 }
@@ -729,12 +1024,12 @@ export const web = defineAuthSetup(async (page, _role, creds) => {
 async function initUpdateCommand(opts) {
   const cwd = process.cwd();
   p2.intro(pc3.cyan("xera init --update"));
-  const pkgPath = join4(cwd, "package.json");
-  if (!existsSync4(pkgPath)) {
+  const pkgPath = join8(cwd, "package.json");
+  if (!existsSync8(pkgPath)) {
     p2.cancel("No package.json found \u2014 run `xera init` first.");
     process.exit(1);
   }
-  const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+  const pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
   pkg.dependencies = pkg.dependencies ?? {};
   pkg.dependencies["@xera-ai/core"] = `^${CLI_VERSION2}`;
   pkg.dependencies["@xera-ai/prompts"] = `^${CLI_VERSION2}`;
@@ -754,79 +1049,47 @@ async function initUpdateCommand(opts) {
   pkg.scripts["xera:impact-prepare"] = "xera-internal impact-prepare";
   pkg.scripts["xera:heal-prepare"] = "xera-internal heal-prepare";
   pkg.scripts["xera:disputes"] = "xera-internal disputes";
-  writeFileSync3(pkgPath, JSON.stringify(pkg, null, 2));
-  const wfDir = join4(cwd, ".github/workflows");
-  mkdirSync3(wfDir, { recursive: true });
+  writeFileSync6(pkgPath, JSON.stringify(pkg, null, 2));
+  const wfDir = join8(cwd, ".github/workflows");
+  mkdirSync5(wfDir, { recursive: true });
   try {
     const cliPkgPath = require3.resolve("@xera-ai/cli/package.json");
-    const cliTplPath = join4(cliPkgPath, "..", "templates/xera-graph.yml.template");
-    copyFileSync(cliTplPath, join4(wfDir, "xera-graph.yml"));
+    const cliTplPath = join8(cliPkgPath, "..", "templates/xera-graph.yml.template");
+    copyFileSync(cliTplPath, join8(wfDir, "xera-graph.yml"));
     p2.log.info("scaffolded .github/workflows/xera-graph.yml");
   } catch (_e) {
     p2.log.warn("skipped xera-graph.yml scaffold (re-run `xera init` to create it)");
   }
-  const skillsSrc = require3.resolve("@xera-ai/skills/package.json");
-  const newSkillsDir = join4(skillsSrc, "..");
-  const SKILL_IGNORE = new Set(["package.json", "version.json", "CHANGELOG.md"]);
-  for (const name of readdirSync3(newSkillsDir)) {
-    if (SKILL_IGNORE.has(name))
-      continue;
-    if (!name.endsWith(".md"))
-      continue;
-    const newContent = readFileSync4(join4(newSkillsDir, name), "utf8");
-    const base = name.replace(/\.md$/, "");
-    const skillPath = join4(cwd, ".claude/skills", base, "SKILL.md");
-    const legacyFlatSkillPath = join4(cwd, ".claude/skills", name);
-    const cmdPath = join4(cwd, ".claude/commands", name);
-    let migratedLegacy = false;
-    if (existsSync4(legacyFlatSkillPath) && !existsSync4(skillPath)) {
-      const legacyContent = readFileSync4(legacyFlatSkillPath, "utf8");
-      mkdirSync3(dirname3(skillPath), { recursive: true });
-      writeFileSync3(skillPath, legacyContent);
-      unlinkSync(legacyFlatSkillPath);
-      migratedLegacy = true;
-    }
-    const targets = [];
-    for (const path of [skillPath, cmdPath]) {
-      if (!existsSync4(path)) {
-        targets.push({ path, state: "missing" });
-      } else {
-        const content = readFileSync4(path, "utf8");
-        targets.push({ path, state: content === newContent ? "same" : "diff" });
-      }
-    }
-    if (targets.every((s) => s.state === "missing")) {
-      for (const { path } of targets) {
-        mkdirSync3(dirname3(path), { recursive: true });
-        writeFileSync3(path, newContent);
-      }
-      p2.log.info(`+ ${name}`);
-      continue;
-    }
-    if (targets.every((s) => s.state === "same")) {
-      if (migratedLegacy)
-        p2.log.success(`migrated ${name} to .claude/skills/${base}/SKILL.md`);
-      else
-        p2.log.info(`= ${name}`);
-      continue;
-    }
-    const choice = await p2.select({
-      message: `${name} differs from package version`,
-      options: [
-        { value: "keep", label: "Keep local" },
-        { value: "overwrite", label: "Overwrite with package version" }
-      ]
-    });
-    if (choice === "overwrite") {
-      for (const { path } of targets) {
-        mkdirSync3(dirname3(path), { recursive: true });
-        writeFileSync3(path, newContent);
+  const editorTargets = await resolveEditors({
+    flag: opts.editor,
+    cwd,
+    isUpdate: true,
+    isYes: opts.yes
+  });
+  if (editorTargets.length === 0) {
+    p2.log.warn("No editor integration detected in this project. Pass --editor claude|cursor|codex|all to add one.");
+  } else {
+    const skillsSrc = require3.resolve("@xera-ai/skills/package.json");
+    const newSkillsDir = join8(skillsSrc, "..");
+    const SKILL_IGNORE = new Set(["package.json", "version.json", "CHANGELOG.md"]);
+    for (const name of readdirSync3(newSkillsDir)) {
+      if (SKILL_IGNORE.has(name))
+        continue;
+      if (!name.endsWith(".md"))
+        continue;
+      const rawNew = readFileSync5(join8(newSkillsDir, name), "utf8");
+      const { frontmatter, body } = parseFrontmatter(rawNew);
+      const base = name.replace(/\.md$/, "");
+      const skillInput = { base, body, frontmatter };
+      for (const editorName of editorTargets) {
+        const adapter = editors[editorName];
+        const migrated = adapter.legacyMigrate?.(cwd, base) ?? false;
+        if (migrated)
+          p2.log.success(`migrated ${base} (${editorName}) to new layout`);
+        adapter.scaffoldSkill(cwd, skillInput);
+        adapter.scaffoldCommand?.(cwd, skillInput);
       }
-      p2.log.success(`overwrote ${name}`);
-    } else {
-      if (migratedLegacy)
-        p2.log.success(`migrated ${name} to .claude/skills/${base}/SKILL.md`);
-      p2.log.warn(`kept local ${name}`);
+      p2.log.info(`refreshed ${base} across [${editorTargets.join(", ")}]`);
     }
   }
   const hasShapeFlags = opts.apiBaseUrl !== undefined || opts.openapiPath !== undefined || opts.authStrategy !== undefined || opts.httpRoles !== undefined || opts.stagingUrl !== undefined || opts.authEnabled !== undefined || opts.roles !== undefined;
@@ -924,7 +1187,7 @@ async function main() {
   cli.help();
   cli.version(VERSION);
   cli.usage("<command> [options]");
-  cli.command("init", "Scaffold a new xera project in the current directory").option("--update", "Non-destructive refresh of an existing project").option("-y, --yes", "Accept all defaults (non-interactive)").option("--shape <shape>", "Project shape: web | api | mixed").option("--ju, --jira-base-url <url>", "Jira workspace URL").option("--pk, --project-keys <keys>", "Jira project key(s), comma-separated").option("--sf, --story-field <field>", "Jira field id for user story (default: description)").option("--ac, --ac-field <field>", "Jira field id for acceptance criteria").option("--su, --staging-url <url>", "Web app staging URL").option("--auth-enabled", "App requires login to test most pages").option("--no-auth-enabled", "App does not require login").option("--ro, --roles <roles>", "Test user roles, comma-separated (default: admin,regular)").option("--au, --api-base-url <url>", "API base URL").option("--op, --openapi-path <path>", "OpenAPI spec path or URL").option("--as, --auth-strategy <strategy>", `API auth strategy: ${VALID_AUTH_STRATEGIES.join(" | ")}`).option("--hr, --http-roles <roles>", "HTTP test roles, comma-separated (default: user)").example("xera init").example("xera init -y --shape web").example("xera init -y --shape api --pk MYPROJ --ju https://myco.atlassian.net --au https://api.staging.example.com --as bearer").example("xera init -y --shape mixed --pk PROJ --ju https://myco.atlassian.net --su https://staging.example.com --au https://api.staging.example.com").action(async (opts) => {
+  cli.command("init", "Scaffold a new xera project in the current directory").option("--update", "Non-destructive refresh of an existing project").option("-y, --yes", "Accept all defaults (non-interactive)").option("--shape <shape>", "Project shape: web | api | mixed").option("--editor <list>", 'Editor(s) to scaffold: claude,cursor,codex or "all" (default: auto-detect or all)').option("--ju, --jira-base-url <url>", "Jira workspace URL").option("--pk, --project-keys <keys>", "Jira project key(s), comma-separated").option("--sf, --story-field <field>", "Jira field id for user story (default: description)").option("--ac, --ac-field <field>", "Jira field id for acceptance criteria").option("--su, --staging-url <url>", "Web app staging URL").option("--auth-enabled", "App requires login to test most pages").option("--no-auth-enabled", "App does not require login").option("--ro, --roles <roles>", "Test user roles, comma-separated (default: admin,regular)").option("--au, --api-base-url <url>", "API base URL").option("--op, --openapi-path <path>", "OpenAPI spec path or URL").option("--as, --auth-strategy <strategy>", `API auth strategy: ${VALID_AUTH_STRATEGIES.join(" | ")}`).option("--hr, --http-roles <roles>", "HTTP test roles, comma-separated (default: user)").example("xera init").example("xera init -y --shape web").example("xera init -y --shape web --editor claude,cursor").example("xera init -y --shape api --pk MYPROJ --ju https://myco.atlassian.net --au https://api.staging.example.com --as bearer").example("xera init -y --shape mixed --pk PROJ --ju https://myco.atlassian.net --su https://staging.example.com --au https://api.staging.example.com").action(async (opts) => {
     if (opts.update) {
       const updateOpts = { yes: !!opts.yes };
       if (opts.shape !== undefined) {
@@ -957,6 +1220,8 @@ async function main() {
         updateOpts.authEnabled = opts.authEnabled;
       if (opts.roles !== undefined)
         updateOpts.roles = opts.roles;
+      if (opts.editor !== undefined)
+        updateOpts.editor = opts.editor;
       await initUpdateCommand(updateOpts);
       return;
     }
@@ -999,6 +1264,8 @@ async function main() {
       initOpts.openapiPath = opts.openapiPath;
     if (opts.httpRoles !== undefined)
       initOpts.httpRoles = opts.httpRoles;
+    if (opts.editor !== undefined)
+      initOpts.editor = opts.editor;
     await initCommand(initOpts);
   });
   cli.command("doctor", "Run a health check").option("--strict <ticket>", "Treat ticket-specific checks as required").option("--logs <ticket>", "Pretty-print xera.log for a ticket").option("--usage", "Show token/usage summary from recent runs").action(async (opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/cli",
-  "version": "0.12.3",
+  "version": "0.13.1",
   "type": "module",
   "bin": {
     "xera": "./bin/xera"
@@ -15,8 +15,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@xera-ai/core": "^0.12.3",
-    "@xera-ai/skills": "^0.12.3",
+    "@xera-ai/core": "^0.13.1",
+    "@xera-ai/skills": "^0.13.1",
     "@clack/prompts": "1.4.0",
     "cac": "7.0.0",
     "picocolors": "1.1.1",