@headways/cli 0.4.2 → 1.1.0

package/dist/index.js

@@ -2,72 +2,22 @@
 import {
   apiRequest,
   rawRequest
-} from "./chunk-2INXZHRG.js";
-import {
-  registerSetupCommand,
-  registerSyncCommands,
-  registerUninstallCommand
-} from "./chunk-XTEQBKIN.js";
+} from "./chunk-GN2N6M4B.js";
 import {
   CLAUDE_SKILLS_DIR,
   INSTALLED_DIR,
+  RUNS_DIR,
   getApiUrl,
   getAppUrl,
   readConfig,
   requireAuth,
   writeConfig
-} from "./chunk-UUFIIGTZ.js";
+} from "./chunk-COGZMSYS.js";
 
 // src/index.ts
 import "dotenv/config";
 import { program } from "commander";
 
-// package.json
-var package_default = {
-  name: "@headways/cli",
-  version: "0.4.2",
-  type: "module",
-  description: "Headways CLI \u2014 authoring, sync, and runtime SDK",
-  license: "MIT",
-  files: [
-    "dist",
-    "LICENSE",
-    "README.md"
-  ],
-  bin: {
-    headways: "./dist/index.js"
-  },
-  publishConfig: {
-    access: "public"
-  },
-  scripts: {
-    build: "tsup",
-    dev: "tsx src/index.ts",
-    test: "vitest run",
-    "test:unit": "vitest run",
-    "type-check": "tsc -p tsconfig.json --noEmit",
-    prepublishOnly: "pnpm build"
-  },
-  dependencies: {
-    "@headways/db": "workspace:*",
-    "@modelcontextprotocol/sdk": "^1.15.0",
-    chalk: "^5.3.0",
-    commander: "^12.1.0",
-    dotenv: "^16.4.7",
-    "node-fetch": "^3.3.2",
-    yaml: "^2.5.1",
-    zod: "^3.25.28"
-  },
-  devDependencies: {
-    "@headways/config": "workspace:*",
-    "@types/node": "^22.16.5",
-    tsup: "^8.5.1",
-    tsx: "^4.21.0",
-    typescript: "^5.8.3",
-    vitest: "^3.2.4"
-  }
-};
-
 // src/commands/auth.ts
 import "commander";
 import * as http from "http";
@@ -285,6 +235,12 @@ function registerNewCommand(program2) {
       console.error("slug and headline are required.");
       process.exit(1);
     }
+    if (headline.length > 90) {
+      console.error(
+        `Headline is ${headline.length} chars \u2014 must be \u2264 90. Shorten to one sentence.`
+      );
+      process.exit(1);
+    }
     const dir = path.join(process.cwd(), slug);
     await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(
@@ -356,96 +312,64 @@ runtimes: [claude-code]
 
 // src/commands/skills/import.ts
 import "commander";
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+
+// src/commands/skills/push.ts
+import "commander";
 import * as fs2 from "fs/promises";
 import * as path2 from "path";
-var ORG_PROFILES = {
-  hippocratic: {
-    connectorHints: ["ehr.read", "ehr.write", "phi.access"],
-    fixtureTemplate: "patient-encounter",
-    channelPolicy: "stable"
-  },
-  revive: {
-    connectorHints: ["email.read", "calendar.read", "ads.read"],
-    fixtureTemplate: "campaign-brief",
-    channelPolicy: "beta"
-  }
-};
-function registerImportCommand(program2) {
-  program2.command("import <path>").description("Import a skill from a file, directory, or URL").option("--slug <slug>", "Override derived slug").option(
-    "--org <orgProfile>",
-    "Apply org-specific connector hints + fixture templates (hippocratic, revive)"
-  ).action(async (inputPath, opts) => {
-    requireAuth();
-    let source;
-    let format = "auto";
+import { watch, existsSync } from "fs";
+import * as YAML from "yaml";
+var RESERVED_TOP_LEVEL = /* @__PURE__ */ new Set([
+  "SKILL.md",
+  "headways.yaml",
+  "capabilities.yaml",
+  "connections.yaml",
+  "hooks.yaml"
+]);
+var IGNORE_NAMES = /* @__PURE__ */ new Set([".git", "node_modules", ".DS_Store", ".gitkeep"]);
+async function collectExtraFiles(dir) {
+  const result = {};
+  async function walk(current, prefix) {
+    let entries;
     try {
-      const stat2 = await fs2.stat(inputPath);
-      if (stat2.isDirectory()) {
-        const skillMdPath = path2.join(inputPath, "SKILL.md");
-        source = await fs2.readFile(skillMdPath, "utf-8");
-        format = "skill-md";
-      } else {
-        source = await fs2.readFile(inputPath, "utf-8");
-        if (inputPath.endsWith(".yaml") || inputPath.endsWith(".yml")) {
-          format = "headways-yaml";
-        } else {
-          format = "markdown";
-        }
-      }
+      entries = await fs2.readdir(current, { withFileTypes: true });
     } catch {
-      console.error(`Cannot read '${inputPath}': file or directory not found.`);
-      process.exit(1);
-    }
-    const profile = opts.org ? ORG_PROFILES[opts.org] : void 0;
-    if (opts.org && !profile) {
-      console.warn(
-        `Unknown org profile '${opts.org}'. Known profiles: ${Object.keys(ORG_PROFILES).join(", ")}`
-      );
+      return;
     }
-    const derivedSlug = opts.slug ?? path2.basename(inputPath, path2.extname(inputPath)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-    const result = await apiRequest("/v1/skills/import", {
-      method: "POST",
-      body: JSON.stringify({
-        source,
-        format,
-        suggestedSlug: derivedSlug,
-        connectorHints: profile?.connectorHints,
-        channelPolicy: profile?.channelPolicy
-      })
-    });
-    console.log(`Imported as '${result.slug}' (format: ${result.detectedFormat})`);
-    console.log(`  Headline: ${result.headline}`);
-    console.log(`  Skill ID: ${result.skillId}`);
-    if (profile) {
-      console.log(`  Org profile: ${opts.org}`);
-      console.log(`  Connector hints: ${profile.connectorHints.join(", ")}`);
-      console.log(`  Fixture template: ${profile.fixtureTemplate}`);
+    for (const entry of entries) {
+      if (IGNORE_NAMES.has(entry.name) || entry.name.startsWith(".")) continue;
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const abs = path2.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(abs, rel);
+      } else if (!prefix && RESERVED_TOP_LEVEL.has(entry.name)) {
+      } else {
+        result[rel] = await fs2.readFile(abs, "utf-8");
+      }
     }
-    console.log(`  Run 'headways skills push ${result.slug}' to sync edits.`);
-  });
+  }
+  await walk(dir, "");
+  return result;
 }
-
-// src/commands/skills/push.ts
-import "commander";
-import * as fs3 from "fs/promises";
-import * as path3 from "path";
-import { watch, existsSync } from "fs";
 var catchMissing = (e) => {
   if (e.code === "ENOENT") return null;
   throw e;
 };
 async function readSkillDir(dir) {
-  const skillMdPath = path3.join(dir, "SKILL.md");
+  const skillMdPath = path2.join(dir, "SKILL.md");
   let body;
   try {
-    body = await fs3.readFile(skillMdPath, "utf-8");
+    body = await fs2.readFile(skillMdPath, "utf-8");
   } catch {
     throw new Error(`SKILL.md not found in ${dir}`);
   }
-  const [headwaysYaml, capabilitiesYaml, connectionsYaml] = await Promise.all([
-    fs3.readFile(path3.join(dir, "headways.yaml"), "utf-8").catch(catchMissing),
-    fs3.readFile(path3.join(dir, "capabilities.yaml"), "utf-8").catch(catchMissing),
-    fs3.readFile(path3.join(dir, "connections.yaml"), "utf-8").catch(catchMissing)
+  const [headwaysYaml, capabilitiesYaml, connectionsYaml, hooksYaml] = await Promise.all([
+    fs2.readFile(path2.join(dir, "headways.yaml"), "utf-8").catch(catchMissing),
+    fs2.readFile(path2.join(dir, "capabilities.yaml"), "utf-8").catch(catchMissing),
+    fs2.readFile(path2.join(dir, "connections.yaml"), "utf-8").catch(catchMissing),
+    fs2.readFile(path2.join(dir, "hooks.yaml"), "utf-8").catch(catchMissing)
   ]);
   let headline;
   if (headwaysYaml) {
@@ -457,7 +381,35 @@ async function readSkillDir(dir) {
     const items = parseConnectionsYaml(connectionsYaml);
     if (items.length > 0) connections = items;
   }
-  return { body, headline, capabilities: capabilitiesYaml ?? void 0, connections };
+  let capabilities;
+  if (capabilitiesYaml) {
+    try {
+      capabilities = YAML.parse(capabilitiesYaml);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse capabilities.yaml: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  let hooks;
+  if (hooksYaml) {
+    try {
+      hooks = YAML.parse(hooksYaml);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse hooks.yaml: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  const extraFiles = await collectExtraFiles(dir);
+  return {
+    body,
+    headline,
+    capabilities,
+    hooks,
+    connections,
+    files: Object.keys(extraFiles).length > 0 ? extraFiles : void 0
+  };
 }
 function parseConnectionsYaml(yaml) {
   const items = [];
@@ -482,28 +434,36 @@ function parseConnectionsYaml(yaml) {
   return items;
 }
 async function pushSkill(slug, dir) {
-  const { body, headline, capabilities, connections } = await readSkillDir(dir);
+  const { body, headline, capabilities, hooks, connections, files } = await readSkillDir(dir);
+  if (headline && headline.length > 90) {
+    throw new Error(
+      `Headline is ${headline.length} chars \u2014 must be \u2264 90. Shorten to one sentence in headways.yaml.`
+    );
+  }
   await apiRequest(`/v1/skills/${slug}/draft`, {
     method: "PUT",
     body: JSON.stringify({
       body,
       ...headline ? { headline } : {},
       ...capabilities ? { capabilities } : {},
-      ...connections ? { connections } : {}
+      ...hooks ? { hooks } : {},
+      ...connections ? { connections } : {},
+      ...files ? { files } : {}
     })
   });
-  console.log(`Pushed '${slug}' draft`);
+  const fileCount = files ? Object.keys(files).length : 0;
+  console.log(`Pushed '${slug}' draft${fileCount > 0 ? ` (${fileCount} extra file${fileCount === 1 ? "" : "s"})` : ""}`);
 }
 function resolveSkillDir(slug) {
   if (!slug) return process.cwd();
-  const installedPath = path3.join(CLAUDE_SKILLS_DIR, slug);
+  const installedPath = path2.join(CLAUDE_SKILLS_DIR, slug);
   if (existsSync(installedPath)) return installedPath;
-  return path3.join(process.cwd(), slug);
+  return path2.join(process.cwd(), slug);
 }
 function registerPushCommand(program2) {
   program2.command("push [slug]").description("Push local skill files as a draft to Headways").option("--watch", "Watch for file changes and auto-push").option("--dir <dir>", "Skill directory (default: installed location, then ./<slug>)").action(async (slug, opts) => {
     requireAuth();
-    const resolvedSlug = slug ?? path3.basename(process.cwd());
+    const resolvedSlug = slug ?? path2.basename(process.cwd());
     const dir = opts.dir ?? resolveSkillDir(slug);
     await pushSkill(resolvedSlug, dir);
     if (opts.watch) {
@@ -525,6 +485,86 @@ function registerPushCommand(program2) {
   });
 }
 
+// src/commands/skills/import.ts
+var ORG_PROFILES = {
+  hippocratic: {
+    connectorHints: ["ehr.read", "ehr.write", "phi.access"],
+    fixtureTemplate: "patient-encounter",
+    channelPolicy: "stable"
+  },
+  revive: {
+    connectorHints: ["email.read", "calendar.read", "ads.read"],
+    fixtureTemplate: "campaign-brief",
+    channelPolicy: "beta"
+  }
+};
+function registerImportCommand(program2) {
+  program2.command("import <path>").description("Import a skill from a file, directory, or URL").option("--slug <slug>", "Override derived slug").option(
+    "--org <orgProfile>",
+    "Apply org-specific connector hints + fixture templates (hippocratic, revive)"
+  ).action(async (inputPath, opts) => {
+    requireAuth();
+    let source;
+    let format = "auto";
+    let extraFiles = {};
+    try {
+      const stat2 = await fs3.stat(inputPath);
+      if (stat2.isDirectory()) {
+        const skillMdPath = path3.join(inputPath, "SKILL.md");
+        source = await fs3.readFile(skillMdPath, "utf-8");
+        format = "skill-md";
+        extraFiles = await collectExtraFiles(inputPath);
+      } else {
+        source = await fs3.readFile(inputPath, "utf-8");
+        if (inputPath.endsWith(".yaml") || inputPath.endsWith(".yml")) {
+          format = "headways-yaml";
+        } else {
+          format = "markdown";
+        }
+      }
+    } catch {
+      console.error(`Cannot read '${inputPath}': file or directory not found.`);
+      process.exit(1);
+    }
+    const profile = opts.org ? ORG_PROFILES[opts.org] : void 0;
+    if (opts.org && !profile) {
+      console.warn(
+        `Unknown org profile '${opts.org}'. Known profiles: ${Object.keys(ORG_PROFILES).join(", ")}`
+      );
+    }
+    const derivedSlug = opts.slug ?? path3.basename(inputPath, path3.extname(inputPath)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const result = await apiRequest("/v1/skills/import", {
+      method: "POST",
+      body: JSON.stringify({
+        source,
+        format,
+        suggestedSlug: derivedSlug,
+        connectorHints: profile?.connectorHints,
+        channelPolicy: profile?.channelPolicy,
+        ...Object.keys(extraFiles).length > 0 ? { files: extraFiles } : {}
+      })
+    });
+    if (result.headline.length > 90) {
+      console.warn(
+        `  Warning: headline is ${result.headline.length} chars (\u2264 90 required to publish). Edit headways.yaml and run 'headways skills push ${result.slug}'.`
+      );
+    }
+    const fileCount = Object.keys(extraFiles).length;
+    console.log(`Imported as '${result.slug}' (format: ${result.detectedFormat})`);
+    console.log(`  Headline: ${result.headline}`);
+    console.log(`  Skill ID: ${result.skillId}`);
+    if (fileCount > 0) {
+      console.log(`  Files: ${fileCount} extra file${fileCount === 1 ? "" : "s"} uploaded`);
+    }
+    if (profile) {
+      console.log(`  Org profile: ${opts.org}`);
+      console.log(`  Connector hints: ${profile.connectorHints.join(", ")}`);
+      console.log(`  Fixture template: ${profile.fixtureTemplate}`);
+    }
+    console.log(`  Run 'headways skills push ${result.slug}' to sync edits.`);
+  });
+}
+
 // src/commands/skills/index.ts
 var SKILLS_GUIDE = `
 # Headways Skill Authoring Guide
@@ -544,12 +584,12 @@ headways skills push <slug>   # push local edits as a draft
 | Field          | Rule                                                           |
 |----------------|----------------------------------------------------------------|
 | \`slug\`         | \`^[a-z0-9-]+$\`, 1\u201364 chars, immutable after creation          |
-| \`headline\`     | 1\u2013200 chars at creation; **\u2264 90 chars to submit** (hard gate) |
+| \`headline\`     | **One short sentence, \u2264 90 chars** \u2014 hard gate at submit      |
 | \`name\`         | 1\u2013120 chars (display name, defaults to headline)               |
 | \`channel\`      | \`prompt\` (default) | \`auto\` | \`manual\`                       |
 | \`data_classes\` | \`none\` (default) | \`pii\` | \`phi\` | \`pci\`                   |
 
-> Critical: headline must be \u2264 90 characters or the web UI will block submission.
+> Critical: headline must be one short sentence, \u2264 90 characters. The web UI blocks submission if exceeded.
 
 ## File Bundle (\`<slug>/\`)
 
@@ -584,7 +624,7 @@ edge cases, and concrete examples. Vague goals produce poor results.
 \`\`\`yaml
 slug: my-skill
 name: My Skill
-headline: Verb-first summary of the outcome (\u226490 chars)
+headline: One short sentence, verb-first (\u2264 90 chars)
 channel: prompt   # prompt | auto | manual
 runtimes:
   - claude-code
@@ -602,8 +642,8 @@ auto_send: false    # true = skill may act without user confirmation
 
 ### connections.yaml (required for any skill that uses MCP connector tools)
 
-Declare every MCP connector the skill depends on. Users see this list on \`headways skills accept\`
-and the Headways app gates installation on the connectors being configured.
+Declare every MCP connector the skill depends on. Users see this list when they install the skill
+via the Headways desktop app, which gates installation on the connectors being configured.
 
 \`\`\`yaml
 - connector: slack    # connector identifier (e.g. slack, github, atlassian, linear, notion, google-drive, stripe, asana, hubspot, datadog)
@@ -614,6 +654,38 @@ and the Headways app gates installation on the connectors being configured.
 
 Omit the file entirely if the skill has no connector dependencies.
 
+## Runtime Events
+
+Skills can emit events during execution that show up in the Headways dashboard.
+Two layers fire events:
+
+1. **Automatic** \u2014 Claude Code hooks emit \`tool.*\` (per tool call) and \`turn.end\`
+   (per response turn) for every skill invocation. A \`skill.start\`-style record is created
+   by the desktop app's \`UserPromptSubmit\` hook when the user invokes \`/<slug>\`. You don't write these.
+
+2. **Manual** \u2014 Inside your skill body, call \`headways emit\` to record concrete
+   outcomes the agent produced.
+
+\`\`\`bash
+headways emit --hook outcome.pr_created -f url=https://github.com/...
+headways emit --hook outcome.email_sent -f to=user@example.com
+headways emit --hook outcome.doc_written -f path=wiki/pages/x.md
+\`\`\`
+
+### Hook name format
+
+All hook names must match \`<namespace>.<name>\` where namespace is one of:
+
+| Namespace   | Emitted by    | Example                              |
+|-------------|---------------|--------------------------------------|
+| \`skill.*\`   | Hook (auto)   | \`skill.start\`                        |
+| \`tool.*\`    | Hook (auto)   | \`tool.Read\`, \`tool.Bash\`             |
+| \`turn.*\`    | Hook (auto)   | \`turn.end\`                           |
+| \`outcome.*\` | Skill (manual)| \`outcome.pr_created\`, \`outcome.email_sent\` |
+
+Names outside these four namespaces are rejected with HTTP 422. Pick a short,
+verb-past-tense suffix for outcomes: \`pr_created\`, not \`creating_pr\`.
+
 ### hooks.yaml (omit if unused)
 
 \`\`\`yaml
@@ -666,7 +738,6 @@ local edits with \`headways skills push <slug>\`.
 
 ## Common Failure Modes
 
-- Headline > 90 chars \u2192 submit blocked with 422. Shorten before pushing.
 - Uppercase or special chars in slug \u2192 rejected at creation. Use \`a-z\`, \`0-9\`, \`-\` only.
 - Missing \`capabilities.yaml\` entries \u2192 skill silently blocked at runtime.
 - Missing \`connections.yaml\` for MCP-dependent skills \u2192 users install the skill but hit tool-not-found errors at runtime with no explanation. Always create this file when the skill calls MCP tools.
@@ -681,8 +752,8 @@ function registerSkillsCommands(program2) {
     console.log(SKILLS_GUIDE);
   });
   skills.command("list").description("List skills in the active org").action(async () => {
-    const { requireAuth: requireAuth2 } = await import("./config-XQHAXREA.js");
-    const { apiRequest: apiRequest2 } = await import("./api-5EKGGFQ6.js");
+    const { requireAuth: requireAuth2 } = await import("./config-APIR4RCR.js");
+    const { apiRequest: apiRequest2 } = await import("./api-H34ZX4FL.js");
     requireAuth2();
     const result = await apiRequest2("/v1/skills");
     if (result.data.length === 0) {
@@ -693,27 +764,6 @@ function registerSkillsCommands(program2) {
       }
     }
   });
-  skills.command("accept <slug>").description("Accept a pending skill update and install it locally").action(async (slug) => {
-    const { acceptSkill } = await import("./sync-Q3OQUWOD.js");
-    await acceptSkill(slug);
-    try {
-      const { apiRequest: apiRequest2 } = await import("./api-5EKGGFQ6.js");
-      const metadata = await apiRequest2(`/v1/skills/${slug}/bundle/metadata`);
-      const reqs = metadata.connectionRequirements ?? [];
-      if (reqs.length > 0) {
-        console.log("");
-        console.log("This skill requires the following connectors:");
-        console.log("");
-        for (const req of reqs) {
-          console.log(`  - ${req.connector.padEnd(20)} ${req.purpose}`);
-        }
-        console.log("");
-        console.log("To authorize these connectors, use the Headways desktop app");
-        console.log("or run: headways connections add <provider>");
-      }
-    } catch {
-    }
-  });
   skills.command("feedback <slug>").description("Submit feedback about a skill").option(
     "--reaction <type>",
     "thumbs_up, thumbs_down, wrong_output, missing_step",
@@ -762,14 +812,95 @@ function registerConnectionsCommands(program2) {
 
 // src/sdk/emit.ts
 import "commander";
+
+// src/lib/run-session.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { join as join4 } from "path";
+var THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1e3;
+async function readHookStdin() {
+  if (process.stdin.isTTY) return null;
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function sessionFilePath(sessionId) {
+  return join4(RUNS_DIR, sessionId);
+}
+function writeSessionRun(sessionId, run) {
+  if (!existsSync2(RUNS_DIR)) mkdirSync(RUNS_DIR, { recursive: true });
+  writeFileSync(sessionFilePath(sessionId), JSON.stringify(run));
+}
+function readSessionRun(sessionId) {
+  const path4 = sessionFilePath(sessionId);
+  if (!existsSync2(path4)) return null;
+  try {
+    return JSON.parse(readFileSync(path4, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function cleanupStaleRuns(now = Date.now()) {
+  if (!existsSync2(RUNS_DIR)) return;
+  let entries;
+  try {
+    entries = readdirSync(RUNS_DIR);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const path4 = join4(RUNS_DIR, name);
+    try {
+      const stat2 = statSync(path4);
+      if (now - stat2.mtimeMs > THIRTY_DAYS_MS) unlinkSync(path4);
+    } catch {
+    }
+  }
+}
+
+// src/sdk/emit.ts
+var HOOK_NAME_RE = /^(skill|tool|turn|outcome)\.[A-Za-z0-9_]+$/;
+var HOOK_NAME_HELP = "Hook name must be <namespace>.<name> where namespace is one of: skill, tool, turn, outcome.\n  skill.*    lifecycle             (e.g. skill.start)\n  tool.*     tool call events      (e.g. tool.Read, tool.Bash)\n  turn.*     conversation turns    (e.g. turn.end)\n  outcome.*  concrete artifacts    (e.g. outcome.pr_created, outcome.email_sent)";
 function registerEmitCommand(program2) {
-  program2.command("emit").description("Emit a skill run event (used by Claude Code hooks)").option("--run-id <runId>", "Skill run ID (or set HEADWAYS_RUN_ID env var)").option("--hook <hookName>", "Hook name to emit").option("--event <event>", "Legacy alias for --hook").option("--status <status>", "Tool result status (true=error, false=ok)").option("-f, --field <entries...>", "Field values in key=value format").allowUnknownOption(true).action(
+  program2.command("emit").description(
+    "Emit a skill run event (used by Claude Code hooks and from inside skills).\n" + HOOK_NAME_HELP
+  ).option("--run-id <runId>", "Skill run ID (or set HEADWAYS_RUN_ID env var)").option("--hook <hookName>", "Hook name to emit, e.g. outcome.pr_created").option("--event <event>", "Legacy alias for --hook").option("--status <status>", "Tool result status (true=error, false=ok)").option("-f, --field <entries...>", "Field values in key=value format").allowUnknownOption(true).action(
     async (opts) => {
+      const hookName = opts.hook ?? opts.event ?? "tool.unknown";
+      if (!HOOK_NAME_RE.test(hookName)) {
+        console.error(`headways emit: invalid --hook "${hookName}"
+
+${HOOK_NAME_HELP}`);
+        process.exitCode = 1;
+        return;
+      }
       const cfg = readConfig();
       if (!cfg.token) return;
-      const runId = opts.runId ?? process.env["HEADWAYS_RUN_ID"];
+      let runId = opts.runId ?? process.env["HEADWAYS_RUN_ID"];
+      if (!runId) {
+        const input = await readHookStdin();
+        const sessionId = input?.session_id;
+        if (typeof sessionId === "string") {
+          const session = readSessionRun(sessionId);
+          if (session) runId = session.runId;
+        }
+      }
       if (!runId) return;
-      const hookName = opts.hook ?? opts.event ?? "tool.unknown";
       const payload = {};
       if (opts.status !== void 0) {
         payload["tool_result_is_error"] = opts.status === "true" || opts.status === "1";
@@ -800,8 +931,67 @@ function registerEmitCommand(program2) {
   );
 }
 
+// src/commands/skill-run.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join5 } from "path";
+import "commander";
+var SLASH_COMMAND_RE = /^\/([a-z0-9-]+(?::[a-z0-9-]+)?)\b/;
+function resolveSkillSlug(input, isInstalled) {
+  const direct = input.tool_input?.skill;
+  if (typeof direct === "string" && direct.length > 0) return direct;
+  if (typeof input.prompt === "string") {
+    const m = SLASH_COMMAND_RE.exec(input.prompt);
+    if (m && m[1]) {
+      const slug = m[1];
+      if (isInstalled(slug)) return slug;
+    }
+  }
+  return null;
+}
+function defaultIsInstalled(slug) {
+  return existsSync3(join5(INSTALLED_DIR, `${slug}.json`));
+}
+function registerSkillRunCommands(program2) {
+  const skillRun = program2.command("skill-run").description("Skill-run lifecycle commands (invoked by Claude Code hooks).");
+  skillRun.command("start").description(
+    "Create a skill run from a Claude Code hook. Accepts UserPromptSubmit (parses /<slug> from prompt) or PreToolUse(Skill) (tool_input.skill). POSTs /v1/skill-runs and writes ~/.headways/runs/<session_id>."
+  ).action(async () => {
+    cleanupStaleRuns();
+    const cfg = readConfig();
+    if (!cfg.token) return;
+    const input = await readHookStdin();
+    if (!input) return;
+    const sessionId = input.session_id;
+    if (typeof sessionId !== "string") return;
+    const skillSlug = resolveSkillSlug(input, defaultIsInstalled);
+    if (!skillSlug) return;
+    let runId;
+    try {
+      const res = await fetch(`${getApiUrl()}/v1/skill-runs`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${cfg.token}`
+        },
+        body: JSON.stringify({ skillSlug, runtime: "claude-code" })
+      });
+      if (!res.ok) return;
+      const body = await res.json();
+      if (!body.runId) return;
+      runId = body.runId;
+    } catch {
+      return;
+    }
+    writeSessionRun(sessionId, {
+      runId,
+      skill: skillSlug,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  });
+}
+
 // src/commands/prime.ts
-import { existsSync as existsSync2, readdirSync, readFileSync } from "fs";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync2 } from "fs";
 import "commander";
 function registerPrimeCommand(program2) {
   program2.command("prime").description("Output Headways workflow context for AI coding assistants").action(() => {
@@ -817,6 +1007,11 @@ function registerPrimeCommand(program2) {
       "> `--help` to discover full options, or run `headways skills guide` before authoring a skill.",
       "> Do not guess at flags or constraints \u2014 discover them at runtime.",
       "",
+      "## Responsibility split",
+      "",
+      "- **Desktop app (macOS):** installs skills, syncs the catalog, manages Claude Code hooks. Open it from `/Applications/Headways.app`.",
+      "- **CLI (this tool):** skill *authoring* (push, import, new, list) plus runtime helpers Claude Code shells out to (`prime`, `emit`, `skill-run start`).",
+      "",
       "## Auth & Config",
       "",
       `Status: ${cfg.token ? `Signed in (org: ${cfg.orgSlug ?? cfg.orgId ?? "unknown"})` : "Not signed in \u2014 run `headways login`"}`,
@@ -828,37 +1023,33 @@ function registerPrimeCommand(program2) {
       "headways login                     # Browser SSO sign-in",
       "headways logout                    # Remove stored credentials",
       "headways config status             # Show saved key, org, URLs",
-      "headways config clear              # Clear credentials + reset setup state",
-      "",
-      "headways sync start                # Pull catalog updates once",
-      "headways sync start --daemon       # Poll every 60s in background",
-      "headways sync status               # Show pending skill updates",
+      "headways config clear              # Clear credentials",
       "",
       "headways skills list               # List skills in your org",
       "headways skills new                # Scaffold a new skill",
       "headways skills import <path>      # Create a new skill from a local file or directory",
       "headways skills push <slug>        # Push edits to an existing skill (import or new first)",
-      "headways skills accept <slug>      # Install a pending skill update",
       "headways skills feedback <slug>    # Submit feedback on a skill",
       "headways skills guide              # Authoring reference (run before creating a skill)",
       "",
-      "headways setup claude              # Install Claude Code hooks (SessionStart + PreCompact)",
-      "headways prime                     # Print this context (used by hooks)",
+      "# Runtime helpers (invoked automatically by Claude Code hooks; rarely run by hand):",
+      "headways prime                     # Print this context",
+      "headways emit                      # Emit a skill-run event",
+      "headways skill-run start           # Start a skill run from a UserPromptSubmit hook",
       "```",
       "",
       "## Workflow",
       "",
-      "1. `headways sync start` \u2014 pull the latest catalog from your org",
-      "2. `headways accept <skill>` \u2014 install a skill locally",
-      "3. Skills are automatically available to Claude Code via `~/.claude/skills/<slug>/`",
-      "4. Run `headways sync start --daemon` to keep skills up to date in the background",
+      "1. Open the **Headways desktop app** \u2014 it syncs the catalog, shows pending updates, and clicks-to-install bundles.",
+      "2. New skill versions appear in the Library view; click **Install** to bring them onto this machine.",
+      "3. To author skills: `headways skills new` or `headways skills import <path>`, edit, then `headways skills push <slug>`. Publish via the web UI.",
       "",
       "## Installed Skills",
       ""
     ];
     if (skills.length === 0) {
       lines.push(
-        "No skills installed. Run `headways sync start` then `headways accept <skill>`."
+        "No skills installed. Open the Headways desktop app to sync your org's catalog."
       );
     } else {
       for (const skill of skills) {
@@ -877,12 +1068,12 @@ function registerPrimeCommand(program2) {
   });
 }
 function getInstalledSkills() {
-  if (!existsSync2(INSTALLED_DIR)) return [];
+  if (!existsSync4(INSTALLED_DIR)) return [];
   try {
-    return readdirSync(INSTALLED_DIR).filter((f) => f.endsWith(".json")).map((f) => {
+    return readdirSync2(INSTALLED_DIR).filter((f) => f.endsWith(".json")).map((f) => {
       const slug = f.replace(/\.json$/, "");
       try {
-        const raw = JSON.parse(readFileSync(`${INSTALLED_DIR}/${f}`, "utf8"));
+        const raw = JSON.parse(readFileSync2(`${INSTALLED_DIR}/${f}`, "utf8"));
         return {
           slug,
           version: String(raw.version ?? ""),
@@ -899,14 +1090,125 @@ function getInstalledSkills() {
   }
 }
 
+// src/commands/upgrade.ts
+import { chmodSync, renameSync, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
+import { delimiter, basename as basename3, dirname, join as join6 } from "path";
+import { existsSync as existsSync5, statSync as statSync2 } from "fs";
+import "commander";
+var GCS_BASE = "https://storage.googleapis.com/headways-releases/cli";
+var NPM_PACKAGE = "@headways/cli";
+function registerUpgradeCommand(program2) {
+  program2.command("upgrade").description("Upgrade the Headways CLI to the latest version").option("--force", "Reinstall even if already on the latest version").action(async (opts) => {
+    warnIfShadowed();
+    const mode = detectInstallMode();
+    if (mode.kind === "npm") {
+      console.log(
+        `This binary was installed via npm. Upgrade with:
+
+  npm i -g ${NPM_PACKAGE}@latest
+`
+      );
+      return;
+    }
+    if (mode.kind === "unknown") {
+      console.error(
+        `Could not determine how this CLI was installed (execPath: ${process.execPath}).
+If installed via npm:    npm i -g ${NPM_PACKAGE}@latest
+If installed via desktop: re-run the Install step from the Headways app.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    await selfUpdate(mode.binPath, opts.force ?? false);
+  });
+}
+function detectInstallMode() {
+  const exec = process.execPath;
+  const execName = basename3(exec).toLowerCase();
+  if (execName === "node" || execName === "bun" || execName.startsWith("node")) {
+    return { kind: "npm" };
+  }
+  if (execName === "headways" || execName.startsWith("headways")) {
+    return { kind: "standalone", binPath: exec };
+  }
+  return { kind: "unknown" };
+}
+function detectTriple() {
+  if (process.platform !== "darwin") return null;
+  if (process.arch === "arm64") return "aarch64-apple-darwin";
+  if (process.arch === "x64") return "x86_64-apple-darwin";
+  return null;
+}
+async function selfUpdate(binPath, force) {
+  const triple = detectTriple();
+  if (!triple) {
+    console.error(
+      `No prebuilt binary for ${process.platform}/${process.arch}. Standalone binaries are macOS-only; on other platforms use: npm i -g ${NPM_PACKAGE}@latest`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Checking for updates\u2026 (current: ${"1.1.0"})`);
+  const latestRes = await fetch(`${GCS_BASE}/latest.txt`);
+  if (!latestRes.ok) {
+    console.error(`Failed to fetch latest version: ${latestRes.status} ${latestRes.statusText}`);
+    process.exitCode = 1;
+    return;
+  }
+  const latest = (await latestRes.text()).trim();
+  if (latest === "1.1.0" && !force) {
+    console.log(`Already on the latest version (${latest}).`);
+    return;
+  }
+  console.log(`Downloading ${latest} for ${triple}\u2026`);
+  const binRes = await fetch(`${GCS_BASE}/${latest}/headways-${triple}`);
+  if (!binRes.ok) {
+    console.error(`Failed to download binary: ${binRes.status} ${binRes.statusText}`);
+    process.exitCode = 1;
+    return;
+  }
+  const bin = Buffer.from(await binRes.arrayBuffer());
+  const tmpPath = join6(dirname(binPath), `.headways.upgrade.${process.pid}`);
+  writeFileSync2(tmpPath, bin);
+  try {
+    chmodSync(tmpPath, 493);
+    renameSync(tmpPath, binPath);
+  } catch (e) {
+    try {
+      unlinkSync2(tmpPath);
+    } catch {
+    }
+    throw e;
+  }
+  console.log(`Upgraded to ${latest} \u2192 ${binPath}`);
+}
+function warnIfShadowed() {
+  const exec = process.execPath;
+  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const found = [];
+  for (const dir of pathDirs) {
+    const candidate = join6(dir, "headways");
+    try {
+      if (existsSync5(candidate) && statSync2(candidate).isFile()) {
+        found.push(candidate);
+      }
+    } catch {
+    }
+  }
+  if (found.length > 0 && found[0] !== exec) {
+    console.error(
+      `note: another 'headways' is earlier on PATH at ${found[0]} \u2014 running upgrade here won't change which binary your shell picks.`
+    );
+  }
+}
+
 // src/index.ts
-program.name("headways").description("Headways CLI \u2014 skill authoring, sync, and runtime SDK").version(package_default.version);
+program.name("headways").description("Headways CLI \u2014 skill authoring + Claude Code runtime helpers").version("1.1.0");
 registerAuthCommands(program);
 registerSkillsCommands(program);
 registerConnectionsCommands(program);
-registerSyncCommands(program);
 registerEmitCommand(program);
+registerSkillRunCommands(program);
 registerPrimeCommand(program);
-registerSetupCommand(program);
-registerUninstallCommand(program);
+registerUpgradeCommand(program);
 program.parse();