@higrowth/cli 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @higrowth/cli
+
+Log in to a Higrowth workspace from your terminal and install the
+Claude Code skills that drive it. The replacement for `cp -r skills/
+higrowth ~/.claude/skills/` and copy-paste tokens.
+
+## Install
+
+```bash
+npm install -g @higrowth/cli
+# or, for the curl-piped flow:
+curl -fsSL https://hg-engine.app/install.sh | sh
+```
+
+## Quick start
+
+```bash
+# 60-second browser-auth handshake. Opens the approval page; you click
+# Approve; token lands in ~/.claude/mcp.json.
+higrowth login
+
+# Install the five Claude Code skills (workspace-setup, populate-kb,
+# marketing-strategy, apply-work-orders, login).
+higrowth skills install
+
+# Restart Claude Code. /mcp should now list higrowth.
+```
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `higrowth login [--host URL] [--device]` | Browser-auth handshake (PKCE by default; `--device` for SSH/containers). Writes the MCP entry into `~/.claude/mcp.json`. |
+| `higrowth whoami` | Show the currently-configured workspace + token name. |
+| `higrowth logout` | Remove the higrowth entry from `~/.claude/mcp.json`. Local-only — does NOT revoke the token (do that in Settings). |
+| `higrowth skills install [--target TARGET]` | Copy the five skill files into your agent's skills dir. Auto-detects Claude Code, Cursor, Claude Desktop; pass `--target claude\|cursor\|claude-desktop\|all` to override. |
+| `higrowth skills list` | Show installed skills + which are out of date relative to the bundle. |
+| `higrowth skills update` | Re-install (overwrite) the latest skill versions. |
+
+## Flags
+
+| Flag | Default | What it does |
+|------|---------|--------------|
+| `--host URL` | `https://hg-engine.app` | Override the Higrowth host (for self-hosted or staging). |
+| `--device` | off | Use OAuth 2.0 device-code flow instead of PKCE. For SSH / containers. |
+| `--target TARGET` | auto-detect | `claude` / `cursor` / `claude-desktop` / `all`. |
+| `--config PATH` | platform default | Override the MCP config file path. |
+
+## What it does NOT do
+
+- Doesn't manage tokens server-side. Token rotation / revocation
+  happens in the Higrowth UI under Settings → API tokens.
+- Doesn't restart Claude Code for you. After `login` or `skills
+  install`, restart manually so the new config takes effect.
+- Doesn't store secrets outside `~/.claude/mcp.json` (mode 600 where
+  possible).
+
+## License
+
+Apache-2.0

package/dist/index.js

@@ -0,0 +1,1285 @@
+#!/usr/bin/env node
+
+// src/commands/login.ts
+import { spawn } from "child_process";
+import { hostname, platform as platform2 } from "os";
+
+// src/lib/api.ts
+var ApiError = class extends Error {
+  constructor(httpStatus, message) {
+    super(message);
+    this.httpStatus = httpStatus;
+    this.name = "ApiError";
+  }
+  httpStatus;
+};
+var AuthApi = class {
+  constructor(host) {
+    this.host = host;
+  }
+  host;
+  initPkce(input) {
+    return this.post("/api/auth/cli/init", {
+      ...input,
+      codeChallengeMethod: "S256"
+    });
+  }
+  exchangePkce(input) {
+    return this.post("/api/auth/cli/exchange", input);
+  }
+  initDevice(input) {
+    return this.post("/api/auth/device/code", input);
+  }
+  pollDevice(deviceCode) {
+    return this.post("/api/auth/device/token", {
+      deviceCode
+    });
+  }
+  async post(path, body) {
+    const res = await fetch(`${this.host}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      let message = `HTTP ${res.status} ${path}`;
+      try {
+        const parsed = JSON.parse(text);
+        if (parsed.error) message = parsed.error;
+      } catch {
+        if (text) message = text.slice(0, 300);
+      }
+      throw new ApiError(res.status, message);
+    }
+    return await res.json();
+  }
+};
+
+// src/lib/pkce.ts
+import { randomBytes, createHash } from "crypto";
+var VERIFIER_BYTES = 32;
+function generatePkce() {
+  const verifier = base64UrlEncode(randomBytes(VERIFIER_BYTES));
+  const challenge = base64UrlEncode(
+    createHash("sha256").update(verifier).digest()
+  );
+  return { verifier, challenge };
+}
+function base64UrlEncode(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// src/lib/mcp-config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
+import { dirname, join } from "path";
+import { homedir, platform } from "os";
+function configPaths() {
+  const home = homedir();
+  return [
+    { target: "claude", path: join(home, ".claude", "mcp.json") },
+    { target: "cursor", path: join(home, ".cursor", "mcp.json") },
+    { target: "claude-desktop", path: claudeDesktopPath(home) }
+  ];
+}
+function claudeDesktopPath(home) {
+  const p = platform();
+  if (p === "darwin") {
+    return join(
+      home,
+      "Library",
+      "Application Support",
+      "Claude",
+      "claude_desktop_config.json"
+    );
+  }
+  if (p === "win32") {
+    return join(
+      process.env.APPDATA ?? join(home, "AppData", "Roaming"),
+      "Claude",
+      "claude_desktop_config.json"
+    );
+  }
+  return join(
+    process.env.XDG_CONFIG_HOME ?? join(home, ".config"),
+    "Claude",
+    "claude_desktop_config.json"
+  );
+}
+function detectExistingTarget() {
+  for (const { target, path } of configPaths()) {
+    if (existsSync(path)) return target;
+  }
+  return "claude";
+}
+function resolveConfigPath(target) {
+  const resolved = target === "auto" ? detectExistingTarget() : target;
+  const found = configPaths().find((c) => c.target === resolved);
+  if (!found) throw new Error(`Unknown target: ${resolved}`);
+  return found;
+}
+function readConfig(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Could not parse existing MCP config at ${path}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function writeHigrowthEntry(input) {
+  const existing = readConfig(input.path);
+  const next = {
+    ...existing,
+    mcpServers: {
+      ...existing.mcpServers ?? {},
+      higrowth: {
+        url: `${input.host}/api/mcp`,
+        headers: {
+          Authorization: `Bearer ${input.token}`
+        }
+      }
+    }
+  };
+  mkdirSync(dirname(input.path), { recursive: true });
+  writeFileSync(input.path, `${JSON.stringify(next, null, 2)}
+`, "utf-8");
+  tryChmod600(input.path);
+}
+function removeHigrowthEntry(path) {
+  if (!existsSync(path)) return false;
+  const existing = readConfig(path);
+  if (!existing.mcpServers || !existing.mcpServers.higrowth) return false;
+  const { higrowth: _, ...rest } = existing.mcpServers;
+  const next = { ...existing, mcpServers: rest };
+  if (Object.keys(rest).length === 0) {
+    delete next.mcpServers;
+  }
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}
+`, "utf-8");
+  return true;
+}
+function readHigrowthEntry(path) {
+  if (!existsSync(path)) return null;
+  const cfg = readConfig(path);
+  const entry = cfg.mcpServers?.higrowth;
+  if (!entry?.url) return null;
+  const authHeader = entry.headers?.Authorization ?? "";
+  const match = authHeader.match(/^Bearer\s+(\S+)$/);
+  if (!match) return null;
+  return { url: entry.url, token: match[1] };
+}
+function tryChmod600(path) {
+  if (platform() === "win32") return;
+  try {
+    chmodSync(path, 384);
+  } catch {
+  }
+}
+
+// src/commands/login.ts
+var POLL_INTERVAL_MS = 2e3;
+var POLL_DEADLINE_MS = 10 * 6e4;
+async function loginCommand(opts) {
+  const host = opts.host.replace(/\/+$/, "");
+  const api = new AuthApi(host);
+  const client = {
+    clientName: "higrowth-cli",
+    clientHostname: tryHostname()
+  };
+  let token;
+  let organizationId;
+  if (opts.device) {
+    ({ token, organizationId } = await runDeviceFlow(api, client));
+  } else {
+    ({ token, organizationId } = await runPkceFlow(api, client));
+  }
+  const cfg = opts.configOverride !== void 0 ? { target: opts.target === "auto" ? "claude" : opts.target, path: opts.configOverride } : resolveConfigPath(opts.target);
+  writeHigrowthEntry({ path: cfg.path, host, token });
+  process.stdout.write(`
+\u2713 Logged in to ${host}
+`);
+  process.stdout.write(`  workspace: ${organizationId}
+`);
+  process.stdout.write(`  config:    ${cfg.path}
+`);
+  process.stdout.write(`  target:    ${cfg.target}
+
+`);
+  process.stdout.write(
+    "Restart your agent so the MCP connection picks up the new token.\n"
+  );
+  process.stdout.write(
+    "Next:  higrowth skills install   (drops the 4 playbook SKILL.md files into your agent's skills dir)\n"
+  );
+}
+async function runPkceFlow(api, client) {
+  const { verifier, challenge } = generatePkce();
+  const init = await api.initPkce({ ...client, codeChallenge: challenge });
+  process.stdout.write(
+    `
+Opening the approval page in your browser\u2026
+  \u2192 ${init.approvalUrl}
+
+`
+  );
+  openInBrowser(init.approvalUrl);
+  process.stdout.write("Waiting for approval (Ctrl-C to cancel)\u2026\n");
+  const started = Date.now();
+  while (Date.now() - started < POLL_DEADLINE_MS) {
+    try {
+      const result = await api.exchangePkce({
+        flowId: init.flowId,
+        codeVerifier: verifier
+      });
+      return { token: result.token, organizationId: result.organizationId };
+    } catch (err) {
+      if (err instanceof ApiError) {
+        await sleep(POLL_INTERVAL_MS);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error(
+    "Login timed out. Approval wasn't received within 10 minutes."
+  );
+}
+async function runDeviceFlow(api, client) {
+  const init = await api.initDevice(client);
+  process.stdout.write("\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+  process.stdout.write(`Open this URL on any device with a browser:
+
+  ${init.verificationUri}
+
+`);
+  process.stdout.write(`Enter the code:  ${init.userCode}
+`);
+  process.stdout.write(`Or open directly:  ${init.verificationUriComplete}
+`);
+  process.stdout.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n");
+  process.stdout.write(`Polling every ${init.interval}s. Ctrl-C to cancel.
+`);
+  const intervalMs = init.interval * 1e3;
+  const started = Date.now();
+  while (Date.now() - started < POLL_DEADLINE_MS) {
+    await sleep(intervalMs);
+    const res = await api.pollDevice(init.deviceCode);
+    if (res.status === "approved") {
+      return { token: res.token, organizationId: res.organizationId };
+    }
+    if (res.status === "denied" || res.status === "expired") {
+      throw new Error(`Login ${res.status}.`);
+    }
+    process.stdout.write(".");
+  }
+  process.stdout.write("\n");
+  throw new Error("Login timed out. Approval wasn't received within 10 minutes.");
+}
+function openInBrowser(url) {
+  const cmd = platform2() === "darwin" ? "open" : platform2() === "win32" ? "start" : "xdg-open";
+  const child = spawn(cmd, [url], { stdio: "ignore", detached: true });
+  child.on("error", () => {
+    process.stdout.write(
+      `(Couldn't auto-open the browser. Open this URL manually:
+  ${url}
+)
+`
+    );
+  });
+  child.unref();
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function tryHostname() {
+  try {
+    return hostname();
+  } catch {
+    return "unknown";
+  }
+}
+
+// src/commands/logout.ts
+async function logoutCommand() {
+  let removed = 0;
+  for (const cfg of configPaths()) {
+    if (removeHigrowthEntry(cfg.path)) {
+      process.stdout.write(`\u2713 Removed higrowth entry from ${cfg.path}
+`);
+      removed += 1;
+    }
+  }
+  if (removed === 0) {
+    process.stdout.write("No higrowth entries found in any agent config.\n");
+    return;
+  }
+  process.stdout.write(
+    "\nNote: this only deletes the local config entry. The token itself is still valid\nuntil you revoke it in Settings \u2192 API tokens.\n"
+  );
+}
+
+// src/commands/whoami.ts
+async function whoamiCommand() {
+  let foundAny = false;
+  for (const cfg of configPaths()) {
+    const entry = readHigrowthEntry(cfg.path);
+    if (!entry) continue;
+    foundAny = true;
+    process.stdout.write(`${cfg.target.padEnd(15)}  ${entry.url}
+`);
+    process.stdout.write(`${"".padEnd(15)}  ${maskToken(entry.token)}
+`);
+    process.stdout.write(`${"".padEnd(15)}  ${cfg.path}
+
+`);
+    const summary = await probeToken(entry.url, entry.token);
+    if (summary) {
+      process.stdout.write(`${"".padEnd(15)}  \u2713 ${summary}
+
+`);
+    } else {
+      process.stdout.write(
+        `${"".padEnd(15)}  \u2717 token did not authenticate (revoked or stale?)
+
+`
+      );
+    }
+  }
+  if (!foundAny) {
+    process.stdout.write("Not logged in to any agent config.\n");
+    process.stdout.write("Run:  higrowth login\n");
+  }
+}
+function maskToken(token) {
+  if (token.length < 12) return "***";
+  return `${token.slice(0, 8)}\u2026${token.slice(-4)}`;
+}
+async function probeToken(baseUrl, token) {
+  try {
+    const url = baseUrl.replace(/\/api\/mcp$/, "/api/entities");
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.status === 401) return null;
+    if (!res.ok) return `connected (HTTP ${res.status} on probe)`;
+    const body = await res.json();
+    const ents = body.entities ?? [];
+    if (ents.length === 0) return "connected, no entities in workspace";
+    return `connected \u2014 ${ents.length} entit${ents.length === 1 ? "y" : "ies"}: ${ents.slice(0, 3).map((e) => e.name ?? e.domain).join(", ")}${ents.length > 3 ? "\u2026" : ""}`;
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/skills.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+import { homedir as homedir2, platform as platform3 } from "os";
+
+// src/skills/workspace-setup.ts
+var WORKSPACE_SETUP = `---
+name: higrowth-workspace-setup
+description: Walks a Higrowth user through first-time workspace setup \u2014 adding their website, connecting Google Search Console, and kicking off the first diagnostic. Use whenever a user mentions they're new to Higrowth, just signed up, or has an empty workspace.
+allowed-tools: mcp__higrowth__execute_typescript
+---
+
+# Higrowth \u2014 Workspace setup
+
+You are helping a new user get Higrowth productive in the next 30 minutes.
+You have one MCP tool: \`execute_typescript\`. The user has a bearer token
+configured; you don't need to ask for credentials.
+
+## When to use this skill
+
+Trigger on: "set up Higrowth", "I just signed up", "where do I start",
+"new to Higrowth", or when \`api.get('/api/entities')\` returns an empty
+list.
+
+## The interview
+
+Don't dump everything on the user. Walk them through one question at a time.
+
+### 1. Confirm the website
+
+Ask: **"What's the primary domain you want to analyze?"** Accept things
+like \`acme.com\`, \`https://acme.com\`, or \`https://www.acme.com\` \u2014 strip
+the protocol + \`www.\` yourself before creating the entity.
+
+\`\`\`ts
+const ents = await api.get('/api/entities');
+const existing = ents.entities.find(e => e.domain === domain);
+if (existing) {
+  console.log('Already exists:', existing.id);
+} else {
+  const created = await api.post('/api/entities', { domain, name });
+  console.log('Created entity:', created.id);
+}
+\`\`\`
+
+### 2. Discover URLs
+
+Run discovery and report back what was found.
+
+\`\`\`ts
+const result = await api.post(\`/api/entities/\${entityId}/discover\`, {});
+console.log(\`Found \${result.totalUrls} URLs across \${result.groups.length} segments\`);
+\`\`\`
+
+If \`totalUrls\` is suspiciously low (< 20 for a real site), tell the user
+their sitemap may be incomplete and ask if they want to point us at a
+specific path prefix.
+
+### 3. Connect Search Console
+
+You can't OAuth on the user's behalf. Tell them:
+
+> "Open Settings \u2192 Integrations and click Connect Search Console.
+> Come back when it's done \u2014 I'll verify it landed."
+
+Then poll:
+
+\`\`\`ts
+const gsc = await api.get('/api/gsc/status');
+console.log(gsc.connections.length > 0 ? 'GSC connected \u2713' : 'Still waiting\u2026');
+\`\`\`
+
+Don't be pushy. If they don't want GSC right now, tell them honestly:
+*"You can run the diagnostic without it, but a third of the
+opportunities will go dark and outcome verification won't work. It's a
+90-second OAuth flow \u2014 strongly recommended."*
+
+### 4. Suggest building a minimum-viable KB BEFORE the diagnostic
+
+Diagnostic output is much better when the KB has at least personas and
+voice. Offer to walk them through it: *"Want to spend 10 minutes on
+your knowledge base now so the diagnostic respects your voice and ICP?
+I can ask you a few questions."*
+
+If yes, hand off to the **populate-kb** playbook
+(\`api.get('/api/mcp/playbooks/populate-kb')\`).
+
+If no, proceed \u2014 they can populate later.
+
+### 5. Run the first diagnostic
+
+\`\`\`ts
+const dx = await api.post(\`/api/diagnostics\`, { entityId });
+console.log('Diagnostic started:', dx.id, '\u2014 estimated 8-12 minutes');
+\`\`\`
+
+Don't sit and poll. Tell the user the diagnostic is running, give them
+the diagnostic ID, and offer to walk through the report when it lands
+(use the **marketing-strategy** playbook).
+
+## What success looks like
+
+End the session with:
+- Entity created
+- URLs discovered (report the count)
+- GSC connected (or explicit user decline)
+- Diagnostic dispatched (report the ID + ETA)
+- One concrete next step for them ("Come back in ~10 minutes and ask
+  me to walk you through the report")
+
+## What NOT to do
+
+- Don't run the diagnostic before confirming the entity is set up correctly.
+- Don't run multiple diagnostics in a row "to be safe" \u2014 one is enough.
+- Don't refuse to proceed without GSC. Inform, don't gatekeep.
+- Don't ask 12 questions in one message. One at a time.
+`;
+
+// src/skills/populate-kb.ts
+var POPULATE_KB = `---
+name: higrowth-populate-kb
+description: Interviews the user about their business and populates Higrowth's Knowledge Base (personas, use cases, voice, brand facts). Use when the user asks to set up the KB, fill in personas, or wants strategy output to sound on-brand.
+allowed-tools: mcp__higrowth__execute_typescript
+---
+
+# Higrowth \u2014 Populate the KB
+
+You are the user's content strategist for the next 15 minutes. Your job
+is to extract enough structured knowledge that every downstream brief
+and work order respects their voice and ICP. The KB has four layers:
+**personas, use cases, voice, brand facts**.
+
+## When to use this skill
+
+Trigger on: "set up the KB", "fill in personas", "what's a use case
+here", "make the briefs sound like us", or when the strategic profile
+returns empty.
+
+## Mental model
+
+The KB is a structured config, not a creative brief. Brevity beats
+prose. Three sharp personas beat ten fuzzy ones. Don't let the user
+over-engineer.
+
+\`\`\`ts
+// What you're filling in. All optional; you can do this in any order.
+{
+  personas:    [{ name, occupation, stance }],         // 2-5
+  useCases:    [{ name, theme, personas: [name] }],    // 3-5
+  voice:       string,                                 // one paragraph
+  brandFacts:  [{ name, description, locked: bool }],  // 5+
+  important:   [string],                               // 10+ entities
+}
+\`\`\`
+
+## The interview \u2014 six questions
+
+Ask each in sequence. Don't combine. Wait for the answer before moving on.
+
+### Q1. Who does this product matter to?
+
+> "Who buys or uses your product? Give me the top 2-3 by name and one
+> sentence each on when they buy."
+
+Listen for: titles ("VP RevOps", "DevOps lead"), buying triggers ("losing
+deals to a cheaper competitor"), business context ("after their first
+incident with the legacy tool"). Bad answers ("decision makers",
+"businesses 50-500"). If you get a bad answer, gently push: *"Who
+specifically \u2014 name a title or a real customer?"*
+
+Write personas as you go:
+
+\`\`\`ts
+await api.post(\`/api/entities/\${entityId}/facts\`, {
+  factType: 'persona',
+  name: 'VP RevOps',
+  description: 'Owns the revenue stack at mid-market SaaS (50-500 reps). Buys when their AE comp plan needs a redesign after a comp committee blow-up.',
+  dataJson: {
+    occupation: 'VP RevOps',
+    stance: 'Buys when ...',
+    journeyStages: ['consideration', 'decision'],
+  },
+});
+\`\`\`
+
+### Q2. What are the jobs-to-be-done?
+
+> "Forget your product for a second \u2014 what jobs is someone hiring it to
+> do? Two-word phrases, 3-5 of them."
+
+Good: "incident triage", "post-call summary", "revenue forecasting".
+Bad: "make life easier", "save time". Push back on abstractions.
+
+\`\`\`ts
+await api.post(\`/api/entities/\${entityId}/facts\`, {
+  factType: 'use_case',
+  name: 'Incident triage',
+  description: 'Reducing time-to-first-acknowledge for production incidents.',
+  dataJson: {
+    theme: 'incident triage',
+    personas: ['DevOps lead', 'SRE manager'],
+    naturalness: 0.9,  // how organically the product can be mentioned 0..1
+  },
+});
+\`\`\`
+
+**Important \u2014 naturalness scoring.** Ask the user: *"For this use case,
+on a scale of 1-10, how naturally can you mention your product in
+content about this topic without it feeling forced?"* Map their answer
+to 0..1. Default 0.6 if they don't know.
+
+### Q3. How do you talk?
+
+> "Pick a piece of your best marketing \u2014 a landing page, an email, a
+> launch post. Paste it. I'll extract the voice."
+
+Read the sample. Write one paragraph that captures the voice with
+specifics \u2014 banned words, sentence rhythm, formality. Show it to the
+user, ask: *"Does this sound right?"* Edit until they say yes.
+
+\`\`\`ts
+const voiceFact = await api.post(\`/api/entities/\${entityId}/facts\`, {
+  factType: 'voice',
+  name: 'Brand voice',
+  description: "We write the way we talk in a sales call \u2014 direct, ...",
+  dataJson: { locked: true },
+});
+\`\`\`
+
+### Q4. Brand facts they want preserved
+
+> "Give me 5 things every page on your site must respect.
+> Positioning, pricing tier, what you call your product, who you sell
+> to. I'll lock these so nothing overrides them."
+
+\`\`\`ts
+for (const fact of brandFacts) {
+  const created = await api.post(\`/api/entities/\${entityId}/facts\`, {
+    factType: 'brand_fact',
+    name: fact.name,
+    description: fact.description,
+  });
+  await api.post(\`/api/facts/\${created.id}/verify\`, {}); // marks as locked
+}
+\`\`\`
+
+### Q5. Important entities
+
+> "Quick list \u2014 competitor names, your product names, key integrations,
+> technologies you talk about. 10-20 strings is plenty."
+
+These keep the engine from accidentally treating proper nouns as
+common words during topic analysis.
+
+\`\`\`ts
+await api.post(\`/api/entities/\${entityId}/facts\`, {
+  factType: 'entity_list',
+  name: 'Important entities',
+  description: 'Proper nouns the engine should always preserve',
+  dataJson: { entities: ['Stripe', 'Snowflake', 'Looker', 'Acme RevOps', ...] },
+});
+\`\`\`
+
+### Q6. ICP weighting (last; can skip on v1)
+
+> "Of the personas we listed, which one should our content lean toward
+> hardest? Score each 0-1 by share-of-voice."
+
+Defaults are fine for v1 (all 0.5). Don't burn time on this.
+
+## What success looks like
+
+Read back the summary:
+
+\`\`\`ts
+const facts = await api.get(\`/api/entities/\${entityId}/facts\`);
+console.log(\`KB now has \${facts.facts.length} entries\`);
+\`\`\`
+
+End with: *"I've saved \${N} entries to your KB. From now on, every brief
+and work order will read this context. If you want to refine anything,
+just say which one \u2014 you don't have to redo the whole interview."*
+
+## What NOT to do
+
+- Don't auto-generate personas without asking. They sound off.
+- Don't lock brand facts the user hasn't explicitly confirmed.
+- Don't ask all six questions in one message.
+- Don't try to fill in everything in one session. v1 KB is *enough to
+  start*; refinement is a separate session.
+- Don't argue with the user about their voice. Reflect what they tell
+  you; if they say "we're playful", write playful.
+`;
+
+// src/skills/marketing-strategy.ts
+var MARKETING_STRATEGY = `---
+name: higrowth-marketing-strategy
+description: Helps the user interpret a Higrowth diagnostic, pick which pillars to prioritize, and shape the next 2-4 week sprint. Use when the user wants to talk through their report, decide what to ship, or plan.
+allowed-tools: mcp__higrowth__execute_typescript
+---
+
+# Higrowth \u2014 Marketing strategy chat
+
+You are the user's strategy partner for the next 30 minutes. They have a
+diagnostic open; your job is to help them turn 80 opportunities into a
+focused 5-10-item plan.
+
+## When to use this skill
+
+Trigger on: "what should I focus on", "walk me through my report",
+"prioritize this", "what's the move", "plan my sprint".
+
+## Mental model
+
+The diagnostic surfaces opportunities ranked by data score. Strategy
+ranks them by **leverage** \u2014 which work will compound. Your job is to
+push the user from "rank by score" thinking to "rank by pillar
+strategy" thinking.
+
+## The conversation
+
+### Step 1 \u2014 Pull the synthesis
+
+Don't dump opportunities. Start with the LLM-written narrative.
+
+\`\`\`ts
+const dx = await api.get(\`/api/diagnostics/\${diagnosticId}\`);
+console.log(dx.synthesis);
+\`\`\`
+
+Read it. Then ask the user: *"Did that match your read of how the site
+is doing right now? Anything missing?"*
+
+Listen for context the diagnostic can't know \u2014 recent launches,
+seasonal pages, things that are about to change. Note these. They
+should shape priorities.
+
+### Step 2 \u2014 Pick ONE pillar
+
+This is the most important step. Most users want to spray-and-pray
+across all pillars. Don't let them.
+
+\`\`\`ts
+const topics = await api.get(\`/api/diagnostics/\${diagnosticId}/topics\`);
+const pillars = topics.topics.flatMap(c => c.pillars);
+// Rank by impressions \xD7 priority
+\`\`\`
+
+Show the top 3 pillars by impressions, with their priority tier and a
+one-line gap summary. Ask: *"If we could only fix ONE topic area in the
+next 2 weeks, which one would change your business the most?"*
+
+If they pick the one with the most opportunities: good.
+If they pick the one with the most strategic value: better.
+If they say "all of them": push back. *"Sprint focus beats sprint
+breadth. We'll get to the others \u2014 pick the one that, if it wins, you
+can point to."*
+
+### Step 3 \u2014 Read the pillar dashboard with them
+
+\`\`\`ts
+const pillar = await api.get(\`/api/topics/\${pillarId}\`);
+const dashboard = await api.get(\`/api/topics/\${pillarId}/dashboard\`);
+\`\`\`
+
+Walk them through:
+- **AEO readiness** \u2014 what's missing (schema gaps, low stat density,
+  buried answers)
+- **Sub-topic coverage** \u2014 uncovered slots = new_brief candidates
+- **"Who to beat"** \u2014 the named competitor(s) winning in this pillar
+- **Top 5 striking-distance opportunities** \u2014 quick wins on existing pages
+
+For each, give your opinion. Be a strategist, not a librarian.
+
+> "Your fresh-page % is 28 \u2014 way below where it should be. Your top
+> competitor refreshes monthly. I'd start with 3 \`freshness_refresh\`
+> work orders on your highest-impression pages."
+
+### Step 4 \u2014 Build the shortlist
+
+Together, pick 5-10 opportunities. Sequence matters: ship cheap-and-safe
+first (schema, internal links), then medium (title rewrites, freshness),
+then invasive (section rewrites, new briefs). Add to a plan as you go.
+
+\`\`\`ts
+const plan = await api.post('/api/plans', {
+  entityId,
+  name: \`\${pillar.name} \u2014 sprint 1\`,
+  description: 'What hypothesis are we testing this sprint',
+});
+
+for (const oppKey of selectedKeys) {
+  await api.post(\`/api/plans/\${plan.plan.id}/candidates\`, {
+    opportunityKeys: [oppKey],
+  });
+}
+\`\`\`
+
+### Step 5 \u2014 Generate briefs + propose work orders
+
+\`\`\`ts
+await api.post(\`/api/plans/\${plan.plan.id}/generate\`);
+\`\`\`
+
+Then for each plan item, propose its work order. Tell the user the
+plan is ready for review and they should approve in the work-orders
+UI when they're ready.
+
+### Step 6 \u2014 Set expectations
+
+End with reality:
+
+> "Outcome verdicts take 14 days minimum because GSC needs that long
+> to stabilize. Re-run the diagnostic in 2 weeks and reconcile the
+> plan. Plan to ship a second sprint at the same time you read sprint
+> 1's outcomes \u2014 that's the flywheel."
+
+## Strong opinions to bring
+
+The user will look to you to break ties. Hold these:
+
+- **One pillar per sprint.** Always.
+- **Schema and internal links first.** Lowest risk, highest velocity.
+- **Don't promise CTR lift in week 1.** The data takes 14 days.
+- **Inconclusive \u2260 failed.** Many flip to verified on the next window.
+- **Re-run cadence is 2 weeks.** Not 2 days. Not 2 months.
+- **Plans have a defined end.** Archive after 4-6 weeks, even if
+  unfinished \u2014 open-ended plans become graveyards.
+
+## What success looks like
+
+- One pillar picked
+- One plan created
+- 5-10 candidates added
+- Briefs generated
+- Work orders proposed for at least 3 of them
+- User knows when to come back (14 days for outcomes, ~immediately for
+  approvals)
+
+## What NOT to do
+
+- Don't sort opportunities by score and list the top 10. That's not
+  strategy.
+- Don't tell the user "it depends" when they ask what to ship first.
+  Have an opinion.
+- Don't promise outcomes you can't deliver. The engine measures wins
+  honestly; you should too.
+- Don't gloss over the KB. If their KB is empty, stop and run the
+  populate-kb playbook first. Strategy without KB context is generic.
+`;
+
+// src/skills/apply-work-orders.ts
+var APPLY_WORK_ORDERS = `---
+name: higrowth-apply-work-orders
+description: Picks up dispatched Higrowth work orders, applies them to the user's project (repo or CMS), and reports back. Use when the user says "apply the next work order", "ship the dispatched work", or points you at a project directory like projects/phoenix.
+allowed-tools: mcp__higrowth__execute_typescript, Read, Edit, Write, Bash, Grep, Glob
+---
+
+# Higrowth \u2014 Apply work orders
+
+You are the user's executor for dispatched Higrowth work orders.
+Your job: fetch each bundle, make the edit in their repo or CMS,
+report the result. Higrowth verifies; you don't.
+
+## When to use this skill
+
+Trigger on: "apply the next work order", "ship dispatched work",
+"run the agent against \`projects/X\`", or when the user opens a
+project directory and asks you to do their backlog.
+
+## The loop, per work order
+
+Five steps. Don't skip any.
+
+### 1. Fetch the dispatched work orders
+
+\`\`\`ts
+const wos = await api.get('/api/work-orders', {
+  entityId: '...',
+  status: 'dispatched',
+});
+console.log(\`\${wos.length} dispatched work orders\`);
+\`\`\`
+
+If there are 0, stop and tell the user. Don't pretend to work.
+
+### 2. Pick one and fetch the bundle
+
+For each work order:
+
+\`\`\`ts
+const bundle = await api.get(\`/api/work-orders/\${wo.id}\`);
+\`\`\`
+
+Read the **whole bundle**:
+- \`targetUrl\` \u2014 which page
+- \`kbSnapshot\` \u2014 the frozen voice + ICP context to respect
+- \`items\` \u2014 each one's \`kind\`, \`intent\`, \`proposedValue\`, \`grounding\`, \`acceptance\`
+- \`beforeSnapshot\` \u2014 what the page looked like at dispatch (title + meta)
+
+If anything in the bundle conflicts with what you see in the user's
+repo (e.g. the file doesn't exist anymore, the page URL doesn't map
+to a file), STOP. Report a \`skipped\` item with the reason. Don't
+guess.
+
+### 3. Apply the items
+
+For each item, do the kind-specific edit. Use the user's filesystem
+tools (Read/Edit/Write) or CMS API (if the user has provided
+credentials in a config file).
+
+| Kind | What to do |
+|------|------------|
+| add_internal_link | Find the right paragraph; insert the link with the proposed anchor text |
+| title_meta_rewrite | Update frontmatter (\`title\`, \`description\`) to proposedValue verbatim |
+| section_refresh | Rewrite the named section to match intent.summary, within intent.constraints |
+| add_schema | Inject the JSON-LD \`<script type="application/ld+json">\` block from proposedValue.scriptBlock |
+| add_stat_or_quote | Add the proposed stat with its proposed source citation |
+| answer_first_restructure | Move the lead so the first 100 words contain the direct answer; preserve existing copy below |
+| freshness_refresh | Update "last updated" date in frontmatter; refresh stats/examples per intent |
+| expand_subtopic_coverage | Add a new H2 section covering proposedValue.subtopic |
+| entity_coverage | Add explicit mentions of proposedValue.entities, with one-sentence context each |
+| new_brief | Create a new file at proposedValue.targetPath. Outline \u2192 flesh out per KB voice |
+| consolidate | Add 301 redirect at proposedValue.sourceUrl \u2192 proposedValue.canonicalUrl. Append the loser's content into the winner |
+| seed_reddit_quora | Stop. This isn't a repo task. Tell the user this WO is for them to handle manually |
+| claim_review_profile | Same \u2014 manual, can't be automated |
+
+**Respect the KB snapshot.** If the voice paragraph says "no
+exclamation marks", don't add any. If brandFacts say the product is
+called "X" not "Y", use "X".
+
+### 4. Commit (repo projects only)
+
+One branch + one commit per work order:
+
+\`\`\`bash
+git checkout -b hg/wo-\${shortId}
+git add <changed files>
+git commit -m "hg: apply work order \${woId}
+
+\${one-line per item}
+
+Higrowth-WorkOrder: \${woId}
+Higrowth-Items: \${kinds joined by ', '}"
+
+git push -u origin hg/wo-\${shortId}
+\`\`\`
+
+If \`gh\` CLI is available, open a PR; otherwise just print the
+\`git push\` URL.
+
+### 5. Report each item
+
+\`\`\`ts
+for (const item of bundle.items) {
+  await api.post(
+    \`/api/work-orders/\${bundle.id}/items/\${item.id}/result\`,
+    {
+      status: 'applied',  // or 'skipped' / 'failed'
+      appliedReport: {
+        whatChanged: '...concrete sentence...',
+        urls: ['https://site.com/page'],
+        anchors: item.kind === 'add_internal_link' ? [theAnchorText] : undefined,
+        notes: \`Branch hg/wo-\${shortId}\${prNumber ? ', PR #' + prNumber : ''}\`,
+      },
+    },
+  );
+}
+\`\`\`
+
+**\`whatChanged\` matters.** "Done." is not a useful report. Six months
+from now the user will read it and not remember what happened. Spend
+the extra 10 seconds.
+
+## Status codes
+
+| Status | When |
+|--------|------|
+| \`applied\` | You made the edit and committed it |
+| \`skipped\` | The edit doesn't make sense for this codebase (file missing, redundant change, page deleted). Always include \`skipReason\` |
+| \`failed\` | You tried and it didn't work (test failure, build error, missing creds) |
+
+Never report \`verified\` \u2014 that's Higrowth's job, not yours.
+
+## What success looks like
+
+End the session with:
+
+\`\`\`ts
+const summary = bundleResults.map(b => ({
+  workOrder: b.id,
+  applied: b.items.filter(i => i.status === 'applied').length,
+  skipped: b.items.filter(i => i.status === 'skipped').length,
+  failed: b.items.filter(i => i.status === 'failed').length,
+  branch: \`hg/wo-\${b.shortId}\`,
+}));
+console.log(summary);
+\`\`\`
+
+Tell the user: *"Applied \${N} work orders. Branches pushed; review and
+merge when ready. Mechanical verification runs automatically \u2014 you'll
+see verdicts on the work-orders dashboard."*
+
+## What NOT to do
+
+- Don't apply across multiple work orders without committing per WO.
+  Merge conflicts will eat you.
+- Don't push to \`main\` directly. Always a \`hg/wo-\u2026\` branch.
+- Don't edit pages outside the bundle's scope. If the agent finds a
+  typo on a different page, mention it but don't fix it inline \u2014 it
+  poisons outcome verification.
+- Don't report \`applied\` if the change didn't actually happen.
+- Don't run two of yourself in parallel against the same repo.
+`;
+
+// src/skills/index.ts
+var SKILLS = [
+  {
+    slug: "higrowth-workspace-setup",
+    title: "First-time workspace setup",
+    description: "Add the website, connect GSC, run the first diagnostic.",
+    body: WORKSPACE_SETUP
+  },
+  {
+    slug: "higrowth-populate-kb",
+    title: "Populate the Knowledge Base",
+    description: "Interview-driven KB population \u2014 personas, voice, brand facts.",
+    body: POPULATE_KB
+  },
+  {
+    slug: "higrowth-marketing-strategy",
+    title: "Marketing strategy chat",
+    description: "Walk a diagnostic, pick a pillar, build the sprint plan.",
+    body: MARKETING_STRATEGY
+  },
+  {
+    slug: "higrowth-apply-work-orders",
+    title: "Apply dispatched work orders",
+    description: "Fetch bundles, edit the repo or CMS, commit, post results.",
+    body: APPLY_WORK_ORDERS
+  }
+];
+
+// src/commands/skills.ts
+async function skillsInstallCommand(opts) {
+  const targets = resolveTargets(opts.target);
+  if (targets.length === 0) {
+    process.stdout.write(
+      "No supported skills directory detected. Pass --target claude|cursor|claude-desktop|all.\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let totalInstalled = 0;
+  let totalUpdated = 0;
+  for (const t of targets) {
+    const dir = skillsDir(t);
+    process.stdout.write(`
+\u2192 ${t}  (${dir})
+`);
+    for (const skill of SKILLS) {
+      const target = join2(dir, skill.slug, "SKILL.md");
+      const existing = existsSync2(target) ? readFileSync2(target, "utf-8") : null;
+      if (existing === skill.body) {
+        process.stdout.write(`    = ${skill.slug}  (up to date)
+`);
+        continue;
+      }
+      mkdirSync2(dirname2(target), { recursive: true });
+      writeFileSync2(target, skill.body, "utf-8");
+      if (existing === null) {
+        process.stdout.write(`    + ${skill.slug}  (installed)
+`);
+        totalInstalled += 1;
+      } else {
+        process.stdout.write(`    \u21BB ${skill.slug}  (updated)
+`);
+        totalUpdated += 1;
+      }
+    }
+  }
+  process.stdout.write(
+    `
+Done. ${totalInstalled} installed, ${totalUpdated} updated.
+Restart your agent so the new skills are picked up.
+`
+  );
+}
+async function skillsListCommand(opts) {
+  const targets = resolveTargets(opts.target);
+  for (const t of targets) {
+    const dir = skillsDir(t);
+    process.stdout.write(`
+${t}  (${dir})
+`);
+    for (const skill of SKILLS) {
+      const target = join2(dir, skill.slug, "SKILL.md");
+      const state = compareSkill(target, skill);
+      process.stdout.write(`  [${state}]  ${skill.slug.padEnd(32)}  ${skill.title}
+`);
+    }
+  }
+}
+async function skillsUpdateCommand(opts) {
+  await skillsInstallCommand(opts);
+}
+function resolveTargets(t) {
+  const all = [
+    "claude",
+    "cursor",
+    "claude-desktop"
+  ];
+  if (t === "all") return all;
+  if (t === "auto") {
+    const present = all.filter((x) => existsSync2(skillsDir(x)));
+    return present.length > 0 ? present : ["claude"];
+  }
+  return [t];
+}
+function skillsDir(t) {
+  const home = homedir2();
+  if (t === "claude") return join2(home, ".claude", "skills");
+  if (t === "cursor") return join2(home, ".cursor", "skills");
+  if (platform3() === "darwin") {
+    return join2(home, "Library", "Application Support", "Claude", "skills");
+  }
+  if (platform3() === "win32") {
+    return join2(
+      process.env.APPDATA ?? join2(home, "AppData", "Roaming"),
+      "Claude",
+      "skills"
+    );
+  }
+  return join2(
+    process.env.XDG_CONFIG_HOME ?? join2(home, ".config"),
+    "Claude",
+    "skills"
+  );
+}
+function compareSkill(path, skill) {
+  if (!existsSync2(path)) return " missing  ";
+  try {
+    const existing = readFileSync2(path, "utf-8");
+    return existing === skill.body ? "installed" : " stale    ";
+  } catch {
+    return " unread   ";
+  }
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var DEFAULT_HOST = "https://hg-engine.app";
+var USAGE = `higrowth \u2014 Connect your agent to a Higrowth workspace
+
+USAGE
+  higrowth <command> [flags]
+
+COMMANDS
+  login [--host URL] [--device] [--target TARGET]
+      Browser-auth handshake. Writes the higrowth MCP entry into your
+      agent's config (~/.claude/mcp.json by default). Pass --device for
+      OAuth 2.0 device-code flow (SSH / no-browser environments).
+
+  whoami
+      Show the currently-configured higrowth MCP entry across all
+      detected agents, plus a live token-validity probe.
+
+  logout
+      Remove the higrowth entry from every agent config. Does NOT
+      revoke the token server-side \u2014 do that in Settings \u2192 API tokens.
+
+  skills install [--target TARGET]
+      Install the four Higrowth playbook skill files into your agent's
+      skills dir.
+
+  skills list [--target TARGET]
+      Show which skills are installed and whether they're current.
+
+  skills update [--target TARGET]
+      Re-install the bundled skill versions.
+
+  version
+      Print version + exit.
+
+FLAGS
+  --host URL          Override Higrowth host (default: ${DEFAULT_HOST}).
+  --device            Use OAuth device-code flow instead of PKCE.
+  --target TARGET     One of: auto (default) | claude | cursor |
+                      claude-desktop | all.
+  --config PATH       Override the MCP config file path.
+
+EXAMPLES
+  higrowth login
+  higrowth login --device
+  higrowth login --host https://staging.hg-engine.app
+  higrowth skills install --target all
+  higrowth whoami
+`;
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        flags[key] = next;
+        i += 1;
+      } else {
+        flags[key] = true;
+      }
+    } else if (a.startsWith("-")) {
+      flags[a.slice(1)] = true;
+    } else {
+      positional.push(a);
+    }
+  }
+  return {
+    command: positional[0] ?? "",
+    subcommand: positional[1],
+    flags
+  };
+}
+function resolveTarget(raw) {
+  if (raw === void 0) return "auto";
+  if (raw === true) return "auto";
+  const s = String(raw).toLowerCase();
+  if (s === "auto" || s === "claude" || s === "cursor" || s === "claude-desktop" || s === "all") {
+    return s;
+  }
+  throw new Error(
+    `Unknown target "${s}". Use auto | claude | cursor | claude-desktop | all.`
+  );
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const host = typeof args.flags.host === "string" ? args.flags.host : DEFAULT_HOST;
+  const target = resolveTarget(args.flags.target);
+  const device = args.flags.device === true;
+  const configOverride = typeof args.flags.config === "string" ? args.flags.config : void 0;
+  switch (args.command) {
+    case "":
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(USAGE);
+      return;
+    case "version":
+    case "--version":
+    case "-v":
+      process.stdout.write(`higrowth ${VERSION}
+`);
+      return;
+    case "login":
+      if (target === "all") {
+        process.stderr.write(
+          "login writes to a single config file. Use --target claude | cursor | claude-desktop (or omit for auto-detect). To install skills across all agents, use `higrowth skills install --target all` after login.\n"
+        );
+        process.exitCode = 2;
+        return;
+      }
+      await loginCommand({ host, device, target, configOverride });
+      return;
+    case "whoami":
+      await whoamiCommand();
+      return;
+    case "logout":
+      await logoutCommand();
+      return;
+    case "skills":
+      if (args.subcommand === "install" || args.subcommand === void 0) {
+        await skillsInstallCommand({ target });
+        return;
+      }
+      if (args.subcommand === "list") {
+        await skillsListCommand({ target });
+        return;
+      }
+      if (args.subcommand === "update") {
+        await skillsUpdateCommand({ target });
+        return;
+      }
+      process.stderr.write(
+        `Unknown skills subcommand: ${args.subcommand}
+Use:  higrowth skills install | list | update
+`
+      );
+      process.exitCode = 2;
+      return;
+    default:
+      process.stderr.write(`Unknown command: ${args.command}
+
+${USAGE}`);
+      process.exitCode = 2;
+      return;
+  }
+}
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`\u2717 ${msg}
+`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@higrowth/cli",
+  "version": "0.1.0",
+  "description": "Higrowth CLI — log in via browser, install Claude Code skills, manage the MCP connection.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "bin": {
+    "higrowth": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "check": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3"
+  },
+  "keywords": ["higrowth", "seo", "aeo", "mcp", "claude-code", "agent"],
+  "homepage": "https://github.com/higrowth-ai/hg-engine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/higrowth-ai/hg-engine.git",
+    "directory": "cli"
+  }
+}