@headways/cli 0.2.1 → 0.4.0

package/dist/index.js

@@ -2,14 +2,20 @@
 import {
   apiRequest,
   rawRequest
-} from "./chunk-QXOLSB3Q.js";
+} from "./chunk-HYEL7L5Z.js";
 import {
-  HEADWAYS_DIR,
+  registerSetupCommand,
+  registerSyncCommands,
+  registerUninstallCommand
+} from "./chunk-OZULVVQC.js";
+import {
+  INSTALLED_DIR,
   getApiUrl,
+  getAppUrl,
   readConfig,
   requireAuth,
   writeConfig
-} from "./chunk-VLKLEV4U.js";
+} from "./chunk-T2H7EXOV.js";
 
 // src/index.ts
 import "dotenv/config";
@@ -17,9 +23,12 @@ import { program } from "commander";
 
 // src/commands/auth.ts
 import "commander";
+import * as http from "http";
 import * as readline from "readline/promises";
+import { execSync } from "child_process";
+var NO_KEY_MSG = "No API key configured. Run `headways login` or `headways config --api-key <key>`.";
 async function promptApiKey(opts) {
-  let token = opts.token;
+  let token = opts.apiKey;
   if (!token) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     token = (await rl.question("API key (sk_\u2026): ")).trim();
@@ -32,11 +41,20 @@ async function promptApiKey(opts) {
   return token;
 }
 function registerAuthCommands(program2) {
-  const configure = program2.command("configure").description("Set your Headways API key and optional API URL").option("--token <token>", "API key (skip interactive prompt)").option("--api-url <url>", "API base URL (default: https://api.headways.ai)").option("--app-url <url>", "Web app URL (default: https://app.headways.ai)").action(async (opts) => {
-    const token = await promptApiKey(opts);
+  const configure = program2.command("config").description("Set API key, URLs, or view/clear saved credentials").option("--api-key <key>", "API key (skip interactive prompt)").option("--api-url <url>", "API base URL (default: https://api.headways.ai)").option("--app-url <url>", "Web app URL (default: https://app.headways.ai)").action(async (opts) => {
     const cfg = readConfig();
     if (opts.apiUrl) cfg.apiUrl = opts.apiUrl;
     if (opts.appUrl) cfg.appUrl = opts.appUrl;
+    if (!opts.apiKey && (opts.apiUrl || opts.appUrl)) {
+      writeConfig(cfg);
+      const parts = [
+        opts.apiUrl && `API URL: ${opts.apiUrl}`,
+        opts.appUrl && `App URL: ${opts.appUrl}`
+      ].filter(Boolean);
+      console.log(parts.join(" | "));
+      return;
+    }
+    const token = await promptApiKey(opts);
     try {
       const me = await rawRequest(
         "/v1/me",
@@ -45,6 +63,7 @@ function registerAuthCommands(program2) {
         cfg.apiUrl
       );
       cfg.token = token;
+      cfg.setupComplete = true;
       if (me.type === "api_key" && me.organization) {
         cfg.orgSlug = me.organization.slug;
         cfg.orgId = me.organization.id;
@@ -58,34 +77,88 @@ function registerAuthCommands(program2) {
       process.exit(1);
     }
   });
+  configure.command("clear").description("Clear credentials and reset setup state (keeps API and app URLs)").action(() => {
+    const cfg = readConfig();
+    writeConfig({ apiUrl: cfg.apiUrl, appUrl: cfg.appUrl });
+    console.log("Credentials cleared. The desktop app will show onboarding on next launch.");
+  });
   configure.command("status").description("Show current API key and org").action(() => {
     const cfg = readConfig();
     if (!cfg.token) {
-      console.log("No API key configured. Run `headways configure`.");
+      console.log(NO_KEY_MSG);
     } else {
       console.log(
         `API key: ${cfg.token.slice(0, 12)}\u2026 | Org: ${cfg.orgSlug ?? "(none set)"} | API: ${cfg.apiUrl ?? "https://api.headways.ai"}`
       );
     }
   });
-  configure.command("clear").description("Remove stored API key and org").action(() => {
+  program2.command("logout").description("Remove stored credentials (keeps API and app URLs)").action(() => {
     const cfg = readConfig();
     delete cfg.token;
     delete cfg.orgSlug;
     delete cfg.orgId;
+    delete cfg.setupComplete;
     writeConfig(cfg);
-    console.log("Configuration cleared.");
+    console.log("Logged out.");
+  });
+  program2.command("login").description("Sign in via browser (SSO) \u2014 opens your browser to authenticate").option("--timeout <seconds>", "seconds to wait for browser callback", "120").action(async (opts) => {
+    const cfg = readConfig();
+    const state = crypto.randomUUID();
+    const port = await findFreePort();
+    const callbackUrl = `http://localhost:${port}/callback`;
+    const appUrl = getAppUrl();
+    const apiUrl = getApiUrl();
+    const loginUrl = `${appUrl}/auth/device?state=${encodeURIComponent(state)}&callback=${encodeURIComponent(callbackUrl)}`;
+    console.log("Opening browser to sign in\u2026");
+    openBrowser(loginUrl);
+    console.log(`
+If the browser did not open, visit:
+  ${loginUrl}
+`);
+    const timeoutMs = Math.max(10, parseInt(opts.timeout, 10)) * 1e3;
+    let grant;
+    try {
+      grant = await waitForCallback(port, state, timeoutMs);
+    } catch (err) {
+      console.error(`
+Sign-in timed out or failed: ${String(err)}`);
+      process.exit(1);
+    }
+    let result;
+    try {
+      const res = await fetch(`${apiUrl}/v1/auth/device/exchange`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ grant })
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Exchange failed (${res.status}): ${body}`);
+      }
+      result = await res.json();
+    } catch (err) {
+      console.error(`Sign-in failed: ${String(err)}`);
+      process.exit(1);
+    }
+    writeConfig({
+      ...cfg,
+      token: result.token,
+      orgId: result.orgId,
+      orgSlug: result.orgSlug,
+      setupComplete: true
+    });
+    console.log(`Signed in. Org: ${result.orgSlug}`);
   });
   program2.command("org").description("Manage org context").command("use <slug>").description("Set active org by slug").action(async (slug) => {
     const cfg = readConfig();
     if (!cfg.token) {
-      console.error("No API key configured. Run `headways configure` first.");
+      console.error(NO_KEY_MSG);
       process.exit(1);
     }
     try {
       await rawRequest("/v1/me", cfg.token);
     } catch {
-      console.error("Invalid API key. Run `headways configure` again.");
+      console.error("Invalid API key. Run `headways config` again.");
       process.exit(1);
     }
     cfg.orgSlug = slug;
@@ -93,6 +166,58 @@ function registerAuthCommands(program2) {
     console.log(`Active org set to: ${slug}`);
   });
 }
+function openBrowser(url) {
+  try {
+    const platform = process.platform;
+    if (platform === "darwin") execSync(`open ${JSON.stringify(url)}`);
+    else if (platform === "win32") execSync(`start "" ${JSON.stringify(url)}`);
+    else execSync(`xdg-open ${JSON.stringify(url)}`);
+  } catch {
+  }
+}
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const srv = http.createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      srv.close(() => {
+        if (addr && typeof addr === "object") resolve(addr.port);
+        else reject(new Error("Could not bind to port"));
+      });
+    });
+  });
+}
+function waitForCallback(port, expectedState, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+      const grant = url.searchParams.get("grant");
+      const state = url.searchParams.get("state");
+      if (state !== expectedState || !grant) {
+        res.writeHead(400);
+        res.end("Invalid callback");
+        return;
+      }
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(
+        '<html><head><meta charset="utf-8"></head><body style="font-family:system-ui;text-align:center;padding:4rem"><h2>Signed in to Headways \u2713</h2><p>You can close this tab and return to the terminal.</p></body></html>'
+      );
+      server.close();
+      resolve(grant);
+    });
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error("Timed out waiting for browser callback"));
+    }, timeoutMs);
+    server.listen(port, "127.0.0.1", () => {
+    });
+    server.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    server.on("close", () => clearTimeout(timer));
+  });
+}
 
 // src/commands/skills/index.ts
 import "commander";
@@ -154,6 +279,13 @@ runtimes: [claude-code]
     kind: outcome
     description: 'Captures the main output artifact'
     schema: {}
+`
+    );
+    await fs.writeFile(
+      path.join(dir, "connections.yaml"),
+      `# connections:
+#   - connector: slack
+#     purpose: "Post skill output to a Slack channel"
 `
     );
     await fs.mkdir(path.join(dir, "fixtures"), { recursive: true });
@@ -269,16 +401,47 @@ async function readSkillDir(dir) {
     capabilities = { raw: capYaml };
   } catch {
   }
-  return { body, headline, capabilities };
+  let connections;
+  const connYamlPath = path3.join(dir, "connections.yaml");
+  try {
+    const connYaml = await fs3.readFile(connYamlPath, "utf-8");
+    const items = parseConnectionsYaml(connYaml);
+    if (items.length > 0) connections = items;
+  } catch {
+  }
+  return { body, headline, capabilities, connections };
+}
+function parseConnectionsYaml(yaml) {
+  const items = [];
+  const connectorRe = /^\s*-\s+connector:\s*(.+)$/;
+  const purposeRe = /^\s+purpose:\s*["']?(.+?)["']?\s*$/;
+  const lines = yaml.split("\n");
+  let current = null;
+  for (const line of lines) {
+    if (line.trimStart().startsWith("#")) continue;
+    const connMatch = connectorRe.exec(line);
+    if (connMatch) {
+      if (current?.connector && current.purpose) items.push(current);
+      current = { connector: (connMatch[1] ?? "").trim() };
+      continue;
+    }
+    if (current) {
+      const purposeMatch = purposeRe.exec(line);
+      if (purposeMatch) current.purpose = (purposeMatch[1] ?? "").trim();
+    }
+  }
+  if (current?.connector && current.purpose) items.push(current);
+  return items;
 }
 async function pushSkill(slug, dir) {
-  const { body, headline, capabilities } = await readSkillDir(dir);
+  const { body, headline, capabilities, connections } = await readSkillDir(dir);
   await apiRequest(`/v1/skills/${slug}/draft`, {
     method: "PUT",
     body: JSON.stringify({
       body,
       ...headline ? { headline } : {},
-      ...capabilities ? { capabilities } : {}
+      ...capabilities ? { capabilities } : {},
+      ...connections ? { connections } : {}
     })
   });
   console.log(`Pushed '${slug}' draft`);
@@ -308,153 +471,164 @@ function registerPushCommand(program2) {
   });
 }
 
-// src/commands/skills/capture.ts
-import "commander";
-import * as fs4 from "fs/promises";
-import * as path4 from "path";
-import { homedir } from "os";
-var SETTINGS_PATH = path4.join(homedir(), ".claude", "settings.json");
-async function readSettingsJson() {
-  try {
-    const raw = await fs4.readFile(SETTINGS_PATH, "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return {};
-  }
-}
-async function writeSettingsJson(settings) {
-  await fs4.mkdir(path4.dirname(SETTINGS_PATH), { recursive: true });
-  await fs4.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
-}
-async function injectCaptureHooks(slug, apiUrl, token) {
-  const settings = await readSettingsJson();
-  const hooks = settings["hooks"] ?? {};
-  const postToolUse = hooks["PostToolUse"] ?? [];
-  const preToolUse = hooks["PreToolUse"] ?? [];
-  const postHookId = `headways-capture-post-${slug}`;
-  const preHookId = `headways-capture-pre-${slug}`;
-  if (!postToolUse.some((h) => h["id"] === postHookId)) {
-    postToolUse.push({
-      id: postHookId,
-      matcher: "*",
-      hooks: [
-        {
-          type: "command",
-          command: `headways capture-record --slug ${slug} --event tool.{{tool_name}} --status {{tool_result_is_error}} 2>/dev/null || true`
-        }
-      ]
-    });
-  }
-  if (!preToolUse.some((h) => h["id"] === preHookId)) {
-    preToolUse.push({
-      id: preHookId,
-      matcher: "*",
-      hooks: [
-        {
-          type: "command",
-          command: `headways capture-record --slug ${slug} --event tool.pre.{{tool_name}} 2>/dev/null || true`
-        }
-      ]
-    });
-  }
-  hooks["PostToolUse"] = postToolUse;
-  hooks["PreToolUse"] = preToolUse;
-  settings["hooks"] = hooks;
-  await writeSettingsJson(settings);
-  console.log(`Injected capture hooks for ${slug} into ${SETTINGS_PATH}`);
-}
-async function removeCaptureHooks(slug) {
-  const settings = await readSettingsJson();
-  const hooks = settings["hooks"] ?? {};
-  const postHookId = `headways-capture-post-${slug}`;
-  const preHookId = `headways-capture-pre-${slug}`;
-  if (Array.isArray(hooks["PostToolUse"])) {
-    hooks["PostToolUse"] = hooks["PostToolUse"].filter(
-      (h) => h["id"] !== postHookId
-    );
-  }
-  if (Array.isArray(hooks["PreToolUse"])) {
-    hooks["PreToolUse"] = hooks["PreToolUse"].filter(
-      (h) => h["id"] !== preHookId
-    );
-  }
-  settings["hooks"] = hooks;
-  await writeSettingsJson(settings);
-  console.log(`Removed capture hooks for ${slug}`);
-}
-function registerCaptureCommand(program2) {
-  program2.command("capture <slug>").description("Capture a live skill run session and upload as sample run").option("--version <version>", "Skill version to capture against", "draft").option("--stop", "Stop capturing and upload the session").action(async (slug, opts) => {
-    const { token, orgId } = requireAuth();
-    const apiUrl = getApiUrl();
-    if (opts.stop) {
-      await removeCaptureHooks(slug);
-      const sessionFile2 = path4.join(homedir(), ".headways", `capture-${slug}.json`);
-      let session = null;
-      try {
-        const raw = await fs4.readFile(sessionFile2, "utf8");
-        session = JSON.parse(raw);
-      } catch {
-        console.error("No active capture session found. Run `headways capture <slug>` first.");
-        process.exit(1);
-      }
-      const res = await fetch(
-        `${apiUrl}/v1/skills/${slug}/versions/${opts.version ?? "draft"}/sample-run/capture-upload`,
-        {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${token}`,
-            "x-headways-org-id": orgId
-          },
-          body: JSON.stringify(session)
-        }
-      );
-      if (!res.ok) {
-        console.error(`Upload failed: ${res.status} ${await res.text()}`);
-        process.exit(1);
-      }
-      const result = await res.json();
-      await fs4.unlink(sessionFile2).catch(() => {
-      });
-      console.log(`Capture uploaded. Run ID: ${result.skillRunId}`);
-      return;
-    }
-    await injectCaptureHooks(slug, apiUrl, token);
-    const sessionFile = path4.join(homedir(), ".headways", `capture-${slug}.json`);
-    await fs4.mkdir(path4.dirname(sessionFile), { recursive: true });
-    await fs4.writeFile(
-      sessionFile,
-      JSON.stringify(
-        {
-          skill_slug: slug,
-          version: opts.version ?? "draft",
-          invocation_prompt: "",
-          tool_calls: [],
-          hook_emissions: [],
-          fixture_reads: [],
-          artifact_writes: [],
-          duration_ms: 0,
-          captured_at: (/* @__PURE__ */ new Date()).toISOString()
-        },
-        null,
-        2
-      )
-    );
-    console.log(`Capturing ${slug}. Run the skill in Claude Code, then stop with:`);
-    console.log(`  headways capture ${slug} --stop`);
-  });
-}
-
 // src/commands/skills/index.ts
+var SKILLS_GUIDE = `
+# Headways Skill Authoring Guide
+
+## Workflow
+
+\`\`\`bash
+headways skills new --slug <slug> --headline "<headline>"  # scaffold + register in org
+# Edit the skill body
+vim <slug>/SKILL.md
+headways skills push <slug>   # push local edits as a draft
+# Publish via web UI at app.headways.ai/skills/<slug>
+\`\`\`
+
+## Field Constraints
+
+| 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) |
+| \`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.
+
+## File Bundle (\`<slug>/\`)
+
+\`\`\`
+<slug>/
+  SKILL.md            # skill body \u2014 instructions for the AI agent
+  headways.yaml       # metadata: slug, name, headline, channel, runtimes
+  capabilities.yaml   # what the skill is allowed to do
+  connections.yaml    # MCP connectors this skill requires (optional)
+  hooks.yaml          # structured hooks the skill exposes (optional)
+\`\`\`
+
+### SKILL.md
+
+\`\`\`markdown
+---
+description: One-sentence summary used in skill listings.
+allowed_tools:
+  - Bash
+  - Read
+  - Edit
+---
+
+# Skill Title
+
+Full instructions for the AI agent. Be explicit: cover inputs, outputs,
+edge cases, and concrete examples. Vague goals produce poor results.
+\`\`\`
+
+### headways.yaml
+
+\`\`\`yaml
+slug: my-skill
+name: My Skill
+headline: Verb-first summary of the outcome (\u226490 chars)
+channel: prompt   # prompt | auto | manual
+runtimes:
+  - claude-code
+\`\`\`
+
+### capabilities.yaml
+
+\`\`\`yaml
+reads: []           # file glob patterns the skill reads
+writes: []          # file glob patterns the skill writes
+external: []        # external domains the skill contacts
+data_classes: none  # none | pii | phi | pci
+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.
+
+\`\`\`yaml
+- connector: slack    # connector identifier (e.g. slack, github, jira, linear, notion, google-drive)
+  purpose: Read channel messages and threads via Slack MCP tools
+- connector: github
+  purpose: Read pull requests and issues
+\`\`\`
+
+Omit the file entirely if the skill has no connector dependencies.
+
+### hooks.yaml (omit if unused)
+
+\`\`\`yaml
+- name: my-hook
+  kind: pre_tool_use   # pre_tool_use | post_tool_use | notification | stop
+  description: What this hook does.
+  schema:
+    type: object
+    properties: {}
+\`\`\`
+
+## Importing an Existing Skill
+
+Use \`import\` when you have an existing prompt file, SKILL.md bundle, or YAML you want to
+register in Headways rather than authoring from scratch.
+
+\`\`\`bash
+headways skills import <path>            # file (.md, .yaml) or directory containing SKILL.md
+headways skills import <path> --slug <slug>   # override the derived slug
+\`\`\`
+
+**Format detection (automatic):**
+
+| Input                        | Detected format   |
+|------------------------------|-------------------|
+| Directory with \`SKILL.md\`    | \`skill-md\`        |
+| \`.yaml\` / \`.yml\` file        | \`headways-yaml\`   |
+| Any other \`.md\` / text file  | \`markdown\`        |
+
+The slug is derived from the filename by default (lowercased, non-alphanumeric \u2192 \`-\`).
+Use \`--slug\` to override. Same slug constraints apply: \`^[a-z0-9-]+$\`, 1\u201364 chars.
+
+After import, a draft is created in your org. Review and edit via the web UI or push
+local edits with \`headways skills push <slug>\`.
+
+## What Makes a High-Quality Skill
+
+- **Headline and description**: always verb-first and action-oriented \u2014 describe what the
+  skill *does*, not what it *is*.
+  - Good: "Scaffold a typed REST endpoint from an OpenAPI spec"
+  - Good: "Review a PR diff for security vulnerabilities"
+  - Bad:  "This skill helps with REST endpoints" (passive, no action)
+  - Bad:  "Security review skill" (noun phrase, no verb)
+- **SKILL.md body**: step-by-step instructions, not goals. Cover what to do,
+  what files to touch, what to avoid, and example invocations.
+- **\`allowed_tools\`**: list only tools the skill actually needs.
+- **\`capabilities.yaml\`**: declare all external domains and file patterns.
+  Undeclared capabilities are blocked at runtime.
+- **\`data_classes\`**: set to \`pii\`/\`phi\`/\`pci\` if the skill touches sensitive data.
+
+## 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.
+- Passive or noun-phrase headline \u2192 poor discoverability; rewrite as a verb phrase.
+`.trim();
 function registerSkillsCommands(program2) {
   const skills = program2.command("skills").description("Manage skills");
   registerNewCommand(skills);
   registerImportCommand(skills);
   registerPushCommand(skills);
-  registerCaptureCommand(program2);
+  skills.command("guide").description("Print skill authoring reference (constraints, file bundle, examples)").action(() => {
+    console.log(SKILLS_GUIDE);
+  });
   skills.command("list").description("List skills in the active org").action(async () => {
-    const { requireAuth: requireAuth2 } = await import("./config-GRE3MIQL.js");
-    const { apiRequest: apiRequest2 } = await import("./api-WUIL5TMR.js");
+    const { requireAuth: requireAuth2 } = await import("./config-SHMIVRAP.js");
+    const { apiRequest: apiRequest2 } = await import("./api-2BK6MGZB.js");
     requireAuth2();
     const result = await apiRequest2("/v1/skills");
     if (result.data.length === 0) {
@@ -465,276 +639,71 @@ function registerSkillsCommands(program2) {
       }
     }
   });
-}
-
-// src/commands/sync/index.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join5 } from "path";
-import { createGunzip } from "zlib";
-import { Readable } from "stream";
-import "stream/promises";
-import "commander";
-var PENDING_FILE = join5(HEADWAYS_DIR, "pending.json");
-var SYNC_STATE_FILE = join5(HEADWAYS_DIR, "sync-state.json");
-var INSTALLED_DIR = join5(HEADWAYS_DIR, "installed");
-function readSyncState() {
-  if (!existsSync(SYNC_STATE_FILE)) return {};
-  try {
-    return JSON.parse(readFileSync(SYNC_STATE_FILE, "utf8"));
-  } catch {
-    return {};
-  }
-}
-function writeSyncState(state) {
-  if (!existsSync(HEADWAYS_DIR)) mkdirSync(HEADWAYS_DIR, { recursive: true });
-  writeFileSync(SYNC_STATE_FILE, JSON.stringify(state, null, 2) + "\n");
-}
-function readPending() {
-  if (!existsSync(PENDING_FILE)) return [];
-  try {
-    return JSON.parse(readFileSync(PENDING_FILE, "utf8"));
-  } catch {
-    return [];
-  }
-}
-function writePending(updates) {
-  if (!existsSync(HEADWAYS_DIR)) mkdirSync(HEADWAYS_DIR, { recursive: true });
-  writeFileSync(PENDING_FILE, JSON.stringify(updates, null, 2) + "\n");
-}
-function deviceHeaders(state) {
-  return {
-    Authorization: `Bearer ${state.device_token ?? ""}`,
-    "x-headways-device-id": state.device_id ?? "",
-    "x-headways-timestamp": String(Math.floor(Date.now() / 1e3))
-  };
-}
-async function registerDevice(token, orgId, apiUrl) {
-  const res = await fetch(`${apiUrl}/v1/sync/devices/register`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${token}`,
-      "x-headways-org-id": orgId
-    },
-    body: JSON.stringify({
-      publicKey: Buffer.from(`stub-pubkey-${Date.now()}`).toString("base64url"),
-      platform: process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : "linux",
-      hostname: (await import("os")).hostname()
-    })
-  });
-  if (!res.ok) throw new Error(`Device registration failed: ${res.status}`);
-  const data = await res.json();
-  return { device_id: data.deviceId, device_token: data.deviceToken };
-}
-async function pollCatalog(state, apiUrl) {
-  const url = state.etag ? `${apiUrl}/v1/sync/catalog?since=${encodeURIComponent(state.etag)}` : `${apiUrl}/v1/sync/catalog`;
-  const res = await fetch(url, { headers: deviceHeaders(state) });
-  if (res.status === 304) return null;
-  if (!res.ok) throw new Error(`Catalog poll failed: ${res.status}`);
-  return res.json();
-}
-async function downloadAndMaterialize(slug, version, state, apiUrl) {
-  const res = await fetch(`${apiUrl}/v1/sync/bundles/${slug}/${version}`, {
-    redirect: "follow",
-    headers: deviceHeaders(state)
-  });
-  if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
-  const buf = Buffer.from(await res.arrayBuffer());
-  const skillsDir = join5(homedir2(), ".claude", "skills");
-  const dest = join5(skillsDir, slug);
-  const staging = join5(skillsDir, `.${slug}-staging`);
-  mkdirSync(staging, { recursive: true });
-  await extractTarGz(buf, staging);
-  if (existsSync(dest)) rmSync(dest, { recursive: true });
-  renameSync(staging, dest);
-  mkdirSync(INSTALLED_DIR, { recursive: true });
-  writeFileSync(
-    join5(INSTALLED_DIR, `${slug}.json`),
-    JSON.stringify(
-      { slug, version, runtime: "claude-code", installed_at: (/* @__PURE__ */ new Date()).toISOString() },
-      null,
-      2
-    )
-  );
-  console.log(`Materialized ${slug}@${version} \u2192 ${dest}`);
-}
-async function extractTarGz(buf, destDir) {
-  const decompressed = await new Promise((resolve, reject) => {
-    const chunks = [];
-    const gunzip = createGunzip();
-    const src = Readable.from(buf);
-    src.pipe(gunzip);
-    gunzip.on("data", (chunk) => chunks.push(chunk));
-    gunzip.on("end", () => resolve(Buffer.concat(chunks)));
-    gunzip.on("error", reject);
-  });
-  let offset = 0;
-  const { writeFileSync: wf, mkdirSync: md } = await import("fs");
-  const { dirname: dirname2 } = await import("path");
-  while (offset + 512 <= decompressed.length) {
-    const header = decompressed.slice(offset, offset + 512);
-    const name = header.slice(0, 100).toString("utf8").replace(/\0/g, "").trim();
-    if (!name) break;
-    const sizeOctal = header.slice(124, 136).toString("utf8").replace(/\0/g, "").trim();
-    const size = parseInt(sizeOctal, 8) || 0;
-    const typeFlag = header[156];
-    offset += 512;
-    if (typeFlag === 53 || name.endsWith("/")) {
-      md(join5(destDir, name), { recursive: true });
-    } else if (typeFlag === 0 || typeFlag === 48 || typeFlag === void 0) {
-      const filePath = join5(destDir, name);
-      md(dirname2(filePath), { recursive: true });
-      wf(filePath, decompressed.slice(offset, offset + size));
-    }
-    offset += Math.ceil(size / 512) * 512;
-  }
-}
-function registerSyncCommands(program2) {
-  const sync = program2.command("sync").description("Sync skills from Headways to local Claude Code");
-  sync.command("start").description("Register device and pull latest skill catalog from Headways").option("--daemon", "Run as background daemon (60s poll loop)").action(async (opts) => {
-    const cfg = readConfig();
-    if (!cfg.token || !cfg.orgId) {
-      console.error("Not logged in. Run: headways login");
-      process.exit(1);
-    }
-    const apiUrl = getApiUrl();
-    let state = readSyncState();
-    if (!state.device_id || !state.device_token) {
-      console.log("Registering device with Headways\u2026");
-      try {
-        const deviceState = await registerDevice(cfg.token, cfg.orgId, apiUrl);
-        state = { ...state, ...deviceState };
-        writeSyncState(state);
-        console.log(`Device registered: ${state.device_id}`);
-      } catch (err) {
-        console.error(`Registration failed: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
-      }
-    }
-    const doPoll = async () => {
-      try {
-        const delta = await pollCatalog(state, apiUrl);
-        if (!delta) {
-          console.log("Catalog up to date.");
-          return;
-        }
-        state.etag = delta.etag;
-        state.last_poll = (/* @__PURE__ */ new Date()).toISOString();
-        writeSyncState(state);
-        const pendingMap = new Map(readPending().map((p) => [p.slug, p]));
-        for (const ev of delta.events) {
-          if (ev.kind === "version_published") {
-            if (ev.channel === "auto") {
-              console.log(`Auto-installing: ${ev.skill_slug}@${ev.version}`);
-              await downloadAndMaterialize(ev.skill_slug, ev.version, state, apiUrl);
-              pendingMap.delete(ev.skill_slug);
-            } else {
-              pendingMap.set(ev.skill_slug, {
-                slug: ev.skill_slug,
-                version: ev.version,
-                user_visible_change: ev.user_visible_change,
-                channel: ev.channel,
-                capabilities_delta_empty: ev.capabilities_delta_empty
-              });
-              console.log(
-                `Queued: ${ev.skill_slug}@${ev.version}${ev.user_visible_change ? ` \u2014 ${ev.user_visible_change}` : ""}`
-              );
-            }
-          } else if (ev.kind === "skill_archived" || ev.kind === "entitlement_revoked") {
-            pendingMap.delete(ev.skill_slug);
-            console.log(`Removed: ${ev.skill_slug}`);
-          }
+  skills.command("accept <slug>").description("Accept a pending skill update and install it locally").action(async (slug) => {
+    const { acceptSkill } = await import("./sync-6PKI35ZY.js");
+    await acceptSkill(slug);
+    try {
+      const { apiRequest: apiRequest2 } = await import("./api-2BK6MGZB.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}`);
         }
-        writePending([...pendingMap.values()]);
-        console.log(`Synced. ETag: ${delta.etag}`);
-      } catch (err) {
-        console.error(`Poll error: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    };
-    await doPoll();
-    if (opts.daemon) {
-      console.log("Running sync daemon (60s interval). Press Ctrl-C to stop.");
-      setInterval(doPoll, 6e4);
-    }
-  });
-  sync.command("status").description("Show current sync status and pending updates").action(() => {
-    const state = readSyncState();
-    const pending = readPending();
-    if (!state.device_id) {
-      console.log("Device not registered. Run: headways sync start");
-      return;
-    }
-    console.log(`Device ID  : ${state.device_id}`);
-    console.log(`Last poll  : ${state.last_poll ?? "never"}`);
-    console.log(`Catalog ETag: ${state.etag ?? "none"}`);
-    if (pending.length === 0) {
-      console.log("\nAll skills up to date. No pending updates.");
-    } else {
-      console.log(`
-Pending updates (${pending.length}):`);
-      for (const p of pending) {
-        const change = p.user_visible_change ? ` \u2014 ${p.user_visible_change}` : "";
-        const caps = p.capabilities_delta_empty ? "" : " [CAPS CHANGED]";
-        console.log(`  ${p.slug}@${p.version}${change}${caps}`);
+        console.log("");
+        console.log("To authorize these connectors, use the Headways desktop app");
+        console.log("or run: headways connections add <provider>");
       }
-      console.log("\nRun `headways accept <skill>` to install.");
+    } catch {
     }
   });
-  program2.command("accept <skill>").description("Accept a pending skill update and materialize it locally").action(async (skillSlug) => {
+  skills.command("feedback <slug>").description("Submit feedback about a skill").option(
+    "--reaction <type>",
+    "thumbs_up, thumbs_down, wrong_output, missing_step",
+    "thumbs_down"
+  ).option("--note <text>", "Free-text note").option("--run-id <runId>", "Skill run ID (or set HEADWAYS_RUN_ID env var)").action(async (slug, opts) => {
     const cfg = readConfig();
-    if (!cfg.token || !cfg.orgId) {
-      console.error("Not logged in. Run: headways login");
-      process.exit(1);
-    }
-    const pending = readPending();
-    const update = pending.find((p) => p.slug === skillSlug);
-    if (!update) {
-      console.error(`No pending update for skill: ${skillSlug}`);
-      console.log("Run `headways sync status` to see pending updates.");
+    if (!cfg.token) {
+      console.error("Not authenticated. Run `headways login` first.");
       process.exit(1);
     }
-    const state = readSyncState();
-    if (!state.device_id || !state.device_token) {
-      console.error("Device not registered. Run: headways sync start");
+    const runId = opts.runId ?? process.env["HEADWAYS_RUN_ID"];
+    try {
+      await rawRequest(`/v1/skills/${slug}/feedback?source=runtime_cli`, cfg.token, {
+        method: "POST",
+        body: JSON.stringify({ reaction: opts.reaction, note: opts.note, runId })
+      });
+      console.log(`Feedback submitted for ${slug}.`);
+    } catch (err) {
+      console.error(`Error: ${String(err)}`);
       process.exit(1);
     }
-    console.log(`Accepting ${skillSlug}@${update.version}\u2026`);
-    await downloadAndMaterialize(skillSlug, update.version, state, getApiUrl());
-    writePending(pending.filter((p) => p.slug !== skillSlug));
-    console.log(
-      `${skillSlug} is ready \u2014 invoke it in Claude Code with the skill's invocation phrase.`
-    );
   });
 }
 
-// src/commands/feedback.ts
+// src/commands/connections/index.ts
 import "commander";
-function registerFeedbackCommand(program2) {
-  program2.command("feedback <skillSlug>").description("Submit feedback about a skill (posts to Headways API)").option(
-    "--reaction <type>",
-    "Reaction type: thumbs_up, thumbs_down, wrong_output, missing_step",
-    "thumbs_down"
-  ).option("--note <text>", "Free-text note about the issue").option("--run-id <runId>", "Skill run ID (or set HEADWAYS_RUN_ID env var)").action(
-    async (skillSlug, opts) => {
-      const cfg = readConfig();
-      if (!cfg.token) {
-        console.error("Not authenticated. Run `headways auth login` first.");
-        process.exit(1);
-      }
-      const runId = opts.runId ?? process.env["HEADWAYS_RUN_ID"];
-      try {
-        await rawRequest(`/v1/skills/${skillSlug}/feedback?source=runtime_cli`, cfg.token, {
-          method: "POST",
-          body: JSON.stringify({ reaction: opts.reaction, note: opts.note, runId })
-        });
-        console.log(`Feedback submitted for ${skillSlug}.`);
-      } catch (err) {
-        console.error(`Error: ${String(err)}`);
-        process.exit(1);
-      }
-    }
-  );
+function registerConnectionsCommands(program2) {
+  const connections = program2.command("connections").description("Manage connector authorizations");
+  connections.command("add [provider]").description("Authorize a connector (opens the desktop app)").action((provider) => {
+    const target = provider ? `the ${provider} connector` : "connectors";
+    console.log(`To authorize ${target}, open the Headways desktop app.`);
+    console.log("");
+    console.log("  1. Open Headways");
+    console.log("  2. Go to Settings \u2192 Connections");
+    console.log('  3. Click "Connect" next to the connector you want to authorize');
+    console.log("");
+    console.log(
+      "Alternatively, install a skill that requires the connector and it will be set up automatically."
+    );
+  });
+  connections.command("list").description("List authorized connections (opens the desktop app)").action(() => {
+    console.log("To view your connections, open the Headways desktop app.");
+    console.log("Go to Settings \u2192 Connections to see and manage your authorized connectors.");
+  });
 }
 
 // src/sdk/emit.ts
@@ -777,11 +746,113 @@ function registerEmitCommand(program2) {
   );
 }
 
+// src/commands/prime.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import "commander";
+function registerPrimeCommand(program2) {
+  program2.command("prime").description("Output Headways workflow context for AI coding assistants").action(() => {
+    const cfg = readConfig();
+    const skills = getInstalledSkills();
+    const lines = [
+      "# Headways \u2014 AI Skill Manager",
+      "",
+      "Headways distributes versioned skills (system prompts + context files) to AI coding agents.",
+      "Skills live in `~/.claude/skills/<slug>/` and are loaded automatically by Claude Code hooks.",
+      "",
+      "> **For AI agents:** Before acting on any Headways task, run the relevant command with",
+      "> `--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.",
+      "",
+      "## Auth & Config",
+      "",
+      `Status: ${cfg.token ? `Signed in (org: ${cfg.orgSlug ?? cfg.orgId ?? "unknown"})` : "Not signed in \u2014 run `headways login`"}`,
+      `Config: ~/.headways/config.json`,
+      "",
+      "## Key Commands",
+      "",
+      "```bash",
+      "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 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)",
+      "```",
+      "",
+      "## 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",
+      "",
+      "## Installed Skills",
+      ""
+    ];
+    if (skills.length === 0) {
+      lines.push(
+        "No skills installed. Run `headways sync start` then `headways accept <skill>`."
+      );
+    } else {
+      for (const skill of skills) {
+        const runLine = skill.lastRunAt ? `last run ${new Date(skill.lastRunAt).toLocaleDateString()}` : "never run";
+        lines.push(`- **${skill.slug}** v${skill.version} (${skill.runtime}, ${runLine})`);
+        if (skill.connectionRequirements.length > 0) {
+          const connectors = skill.connectionRequirements.map((r) => r.connector).join(", ");
+          lines.push(`  - Requires connectors: ${connectors}`);
+        }
+      }
+    }
+    lines.push("", "## Skill Files", "");
+    lines.push("Installed skill bundles land in `~/.claude/skills/<slug>/`.");
+    lines.push("Claude Code automatically discovers them via the skills directory.");
+    console.log(lines.join("\n"));
+  });
+}
+function getInstalledSkills() {
+  if (!existsSync(INSTALLED_DIR)) return [];
+  try {
+    return readdirSync(INSTALLED_DIR).filter((f) => f.endsWith(".json")).map((f) => {
+      const slug = f.replace(/\.json$/, "");
+      try {
+        const raw = JSON.parse(readFileSync(`${INSTALLED_DIR}/${f}`, "utf8"));
+        return {
+          slug,
+          version: String(raw.version ?? ""),
+          runtime: String(raw.runtime ?? "claude-code"),
+          lastRunAt: raw.last_run_at ?? null,
+          connectionRequirements: Array.isArray(raw.connection_requirements) ? raw.connection_requirements : []
+        };
+      } catch {
+        return null;
+      }
+    }).filter((s) => s !== null);
+  } catch {
+    return [];
+  }
+}
+
 // src/index.ts
-program.name("headways").description("Headways CLI \u2014 skill authoring, sync, and runtime SDK").version("0.1.0");
+program.name("headways").description("Headways CLI \u2014 skill authoring, sync, and runtime SDK").version("0.2.1");
 registerAuthCommands(program);
 registerSkillsCommands(program);
+registerConnectionsCommands(program);
 registerSyncCommands(program);
-registerFeedbackCommand(program);
 registerEmitCommand(program);
+registerPrimeCommand(program);
+registerSetupCommand(program);
+registerUninstallCommand(program);
 program.parse();