@easysociable/cli 0.1.12 → 0.1.13

package/README.md

@@ -71,7 +71,8 @@ Default `--root` / `--engine` parent is `/workspace` when that directory exists,
 ## Authentication
 
 ```bash
-easysociable auth login --api-key <key> --gateway-url https://gateway.easysociable.com
+easysociable auth login            # opens the browser; approve and the key is stored automatically
+easysociable auth login --api-key <key> --gateway-url https://gateway.easysociable.com   # headless / CI
 easysociable auth status
 easysociable templates list --json
 easysociable mcp serve --transport stdio

package/dist/easysociable.js

@@ -15545,7 +15545,8 @@ var init_src = __esm({
       previewImageUrl: external_exports.string().url().optional(),
       /** Layout Family id — catalog UIs group variants by this (ADR-0033). */
       familyId: external_exports.string().optional(),
-      familyRole: external_exports.enum(["master", "variant"]).optional()
+      familyRole: external_exports.enum(["master", "variant"]).optional(),
+      familyName: external_exports.string().optional()
     }).strict();
     publicTemplateSlotTypeSchema = external_exports.enum(["text", "number", "image"]);
     publicTemplateSlotSchema = external_exports.object({
@@ -16061,6 +16062,7 @@ var init_src = __esm({
       previewThemeId: external_exports.string().nullable().optional(),
       familyId: external_exports.string().optional(),
       familyRole: external_exports.enum(["master", "variant"]).optional(),
+      familyName: external_exports.string().optional(),
       variants: external_exports.array(authoringDraftVariantSchema).optional(),
       intendedPlatforms: external_exports.array(external_exports.string()).optional(),
       name: external_exports.string(),
@@ -16115,10 +16117,14 @@ var init_src = __esm({
     ]);
     publicSlotValueSchema = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
     contentPackPageSchema = external_exports.object({
-      pageTemplateId: external_exports.string().min(1),
+      pageTemplateId: external_exports.string().min(1).optional(),
+      layoutFamilyId: external_exports.string().min(1).optional(),
       role: pageRoleSchema,
       slots: external_exports.record(external_exports.string(), publicSlotValueSchema)
-    }).strict();
+    }).strict().refine((page) => page.pageTemplateId || page.layoutFamilyId, {
+      message: "page requires layoutFamilyId or pageTemplateId",
+      path: ["layoutFamilyId"]
+    });
     contentPackSchema = external_exports.object({
       schemaVersion: external_exports.literal("content-pack.v1"),
       platform: slideshowPlatformSchema,
@@ -16143,6 +16149,7 @@ var init_src = __esm({
       index: external_exports.number().int().nonnegative(),
       role: pageRoleSchema,
       pageTemplateId: external_exports.string().min(1).optional(),
+      layoutFamilyId: external_exports.string().min(1).optional(),
       slots: external_exports.record(external_exports.string(), publicSlotValueSchema),
       layout: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
       style: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
@@ -16638,7 +16645,7 @@ var init_client = __esm({
             code: "TEMPLATE_API_KEY_REQUIRED",
             message: "Template API key is required",
             retryable: false,
-            suggestedAction: "Run `easysociable auth login --api-key <key>`"
+            suggestedAction: "Run `easysociable auth login` and approve in the browser"
           });
         }
         const url2 = `${this.options.baseUrl.replace(/\/$/, "")}/v1/slideshow/runs/${encodeURIComponent(runId)}/artifacts/${pageIndex}`;
@@ -16833,7 +16840,7 @@ var init_client = __esm({
             code: "TEMPLATE_API_KEY_REQUIRED",
             message: "Template API key is required",
             retryable: false,
-            suggestedAction: "Run `easysociable auth login --api-key <key>` or set EASYSOCIABLE_ALLOW_ENV_CREDENTIALS=true for local tests"
+            suggestedAction: "Run `easysociable auth login` (browser approval) or set EASYSOCIABLE_ALLOW_ENV_CREDENTIALS=true for local tests"
           });
         }
         const maxRetries = this.options.maxRetries ?? 2;
@@ -32551,9 +32558,9 @@ var init_v1_mcp = __esm({
 // src/v1-cli.ts
 init_src2();
 import { cp, readFile, writeFile, mkdir, chmod, copyFile, rm } from "fs/promises";
-import { existsSync as existsSync4, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join4, resolve as resolve2 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync5, statSync as statSync2 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join6, resolve as resolve2 } from "path";
 import { Command } from "commander";
 
 // src/runtime/mcp-hosts.ts
@@ -33233,7 +33240,7 @@ function validateRun(moduleUrl, args) {
 
 // src/studioIdentity.ts
 var FIXTURE_WORKSPACE_IDS = /* @__PURE__ */ new Set(["workspace_local"]);
-var IDENTITY_CHAIN_HINT = "Studio login \u2192 Dashboard create API key \u2192 easysociable auth login --api-key <key> \u2192 create Run \u2192 open studioUrl as the same account. See docs/operations/studio-identity-chain.md";
+var IDENTITY_CHAIN_HINT = "Run `easysociable auth login` (approve in the browser you use for Studio) \u2192 create Run \u2192 open studioUrl as the same account. See docs/operations/studio-identity-chain.md";
 async function assertHumanStudioIdentity(client, options = {}) {
   if (options.allowLocalFixture === true || process.env.EASYSOCIABLE_ALLOW_LOCAL_FIXTURE === "1")
     return;
@@ -33246,25 +33253,329 @@ async function assertHumanStudioIdentity(client, options = {}) {
   }
 }
 
+// src/browserLogin.ts
+import { spawn as spawn2 } from "child_process";
+import { randomBytes } from "crypto";
+import { createServer } from "http";
+var DONE_HTML = '<!doctype html><meta charset="utf-8"><title>EasySociable</title><body style="font-family:system-ui;text-align:center;padding:64px"><h1>Agent connected</h1><p>You can close this tab and return to your Agent.</p></body>';
+function openBrowser(url2) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url2]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url2]] : ["xdg-open", [url2]];
+  try {
+    spawn2(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {
+    }).unref();
+  } catch {
+  }
+}
+function waitForBrowserLogin(options) {
+  const state = randomBytes(16).toString("hex");
+  return new Promise((resolve3, reject) => {
+    const server = createServer((req, res) => {
+      if (req.method !== "POST" || !req.url?.startsWith("/callback")) {
+        res.writeHead(404).end();
+        return;
+      }
+      let body = "";
+      req.on("data", (chunk) => {
+        body += chunk;
+      });
+      req.on("end", () => {
+        const form = new URLSearchParams(body);
+        const apiKey = form.get("apiKey") ?? "";
+        if (form.get("state") !== state || !apiKey.startsWith("es_")) {
+          res.writeHead(400, { "content-type": "text/plain" }).end("Invalid login callback");
+          return;
+        }
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(DONE_HTML);
+        finish(null, { apiKey, gatewayUrl: (form.get("gatewayUrl") ?? "").replace(/\/$/, "") });
+      });
+    });
+    const timer = setTimeout(() => finish(new Error("Browser login timed out. Re-run `easysociable auth login`.")), options.timeoutMs ?? 5 * 6e4);
+    function finish(error52, result) {
+      clearTimeout(timer);
+      server.close();
+      if (error52) reject(error52);
+      else resolve3(result);
+    }
+    server.on("error", (error52) => finish(error52));
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      const url2 = new URL("/cli/authorize", options.siteUrl);
+      url2.searchParams.set("port", String(port));
+      url2.searchParams.set("state", state);
+      options.onReady(url2.toString());
+    });
+  });
+}
+
+// src/formulas.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join4 } from "path";
+var DEFAULT_CANDIDATES = [
+  process.env.EASYSOCIABLE_FORMULA_CATALOG,
+  join4(homedir3(), "Documents", "Obsidian Vault", "TikTok Radar", "graph")
+].filter((p) => Boolean(p));
+function resolveCatalogDir(explicit) {
+  if (explicit) {
+    if (!existsSync4(join4(explicit, "catalog.json"))) {
+      throw new Error(`No catalog.json under ${explicit}`);
+    }
+    return explicit;
+  }
+  for (const candidate of DEFAULT_CANDIDATES) {
+    if (existsSync4(join4(candidate, "catalog.json"))) return candidate;
+  }
+  throw new Error(
+    `Formula catalog not found. Set EASYSOCIABLE_FORMULA_CATALOG to the graph/ dir (expected catalog.json). Tried: ${DEFAULT_CANDIDATES.join(", ")}`
+  );
+}
+function readJson(path) {
+  return JSON.parse(readFileSync3(path, "utf8"));
+}
+function loadCatalog(dir) {
+  const root = resolveCatalogDir(dir);
+  return readJson(join4(root, "catalog.json"));
+}
+function listFormulas(opts = {}) {
+  const root = resolveCatalogDir(opts.dir);
+  const formulasDir = join4(root, "formulas");
+  if (!existsSync4(formulasDir)) return [];
+  const cards = [];
+  for (const name of readdirSync2(formulasDir)) {
+    if (!name.startsWith("F-") || !name.endsWith(".json")) continue;
+    const card = readJson(join4(formulasDir, name));
+    if (opts.recipe && card.recipe !== opts.recipe) continue;
+    if (opts.niche && card.niche !== opts.niche) continue;
+    if (opts.status && card.status !== opts.status) continue;
+    if (opts.platform && card.platform !== opts.platform) continue;
+    cards.push(card);
+  }
+  return cards.sort((a, b) => {
+    const statusRank = (s) => s === "published" ? 0 : 1;
+    const d = statusRank(a.status) - statusRank(b.status);
+    if (d !== 0) return d;
+    return (b.evidence.account_count || 0) - (a.evidence.account_count || 0);
+  });
+}
+function getFormula(id, dir) {
+  const root = resolveCatalogDir(dir);
+  const path = join4(root, "formulas", `${id}.json`);
+  if (!existsSync4(path)) throw new Error(`Formula not found: ${id}`);
+  const looksPath = join4(root, "looks.json");
+  const looks = existsSync4(looksPath) ? readJson(looksPath)[id] : void 0;
+  return { ...readJson(path), looks: looks ?? [] };
+}
+async function fetchHostedFormula(id, baseUrl, fetchImpl = fetch) {
+  const response = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/v1/formulas/${encodeURIComponent(id)}`);
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body?.ok || !body.data) {
+    throw new Error(`Formula not found: ${id} (${body?.error?.message ?? `HTTP ${response.status}`})`);
+  }
+  return body.data;
+}
+async function resolveFormula(id, opts) {
+  if (opts.dir) return getFormula(id, opts.dir);
+  try {
+    return getFormula(id);
+  } catch {
+    return fetchHostedFormula(id, opts.baseUrl, opts.fetchImpl);
+  }
+}
+function recommendFormulas(input) {
+  const limit = input.limit ?? 5;
+  const all = listFormulas({
+    dir: input.dir,
+    recipe: input.recipe,
+    platform: input.platform
+  });
+  const scored = all.map((card) => {
+    let score = 0;
+    const reasons = [];
+    if (card.recipe === input.recipe) {
+      score += 5;
+      reasons.push("recipe match");
+    }
+    if (input.niche && card.niche === input.niche) {
+      score += 2;
+      reasons.push("niche match");
+    } else if (input.niche && card.fit?.length) {
+      score += 0.5;
+      reasons.push("cross-niche kept");
+    }
+    if (card.status === "published") {
+      score += 2;
+      reasons.push(`published (${card.evidence.account_count} accounts)`);
+    } else {
+      reasons.push("hypothesis \u2014 weak evidence");
+    }
+    const points = card.beats.filter((b) => b.role === "point").length;
+    if (typeof input.factCount === "number" && input.factCount > 0) {
+      if (input.factCount >= points) {
+        score += 1.5;
+        reasons.push("enough facts for point beats");
+      } else {
+        score -= 1;
+        reasons.push(`need ~${points} facts, have ${input.factCount}`);
+      }
+    }
+    const newest = card.evidence.newest_days_ago;
+    if (typeof newest === "number" && newest <= 60) {
+      score += 0.5;
+      reasons.push("recent evidence");
+    }
+    score += Math.min(card.evidence.account_count, 5) * 0.3;
+    return { ...card, score, reasons };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  const top = scored.slice(0, limit);
+  const best = top[0]?.score ?? 0;
+  if (!top.length || best < 4) {
+    return {
+      cards: top,
+      stop: true,
+      message: "Top score is low \u2014 change the angle or recipe rather than forcing a card."
+    };
+  }
+  return { cards: top, stop: false };
+}
+
+// src/hooks.ts
+import { existsSync as existsSync5, readFileSync as readFileSync4, readdirSync as readdirSync3 } from "fs";
+import { join as join5 } from "path";
+function readJson2(path) {
+  return JSON.parse(readFileSync4(path, "utf8"));
+}
+function loadHooksCatalog(dir) {
+  const root = resolveCatalogDir(dir);
+  const path = join5(root, "hooks_catalog.json");
+  if (!existsSync5(path)) {
+    throw new Error(`No hooks_catalog.json under ${root}. Run: python3 scripts/compile_hooks.py`);
+  }
+  return readJson2(path);
+}
+function listHooks(opts = {}) {
+  const root = resolveCatalogDir(opts.dir);
+  const hooksDir = join5(root, "hooks");
+  if (!existsSync5(hooksDir))
+    return [];
+  const cards = [];
+  for (const name of readdirSync3(hooksDir)) {
+    if (!name.startsWith("H-") || !name.endsWith(".json"))
+      continue;
+    const card = readJson2(join5(hooksDir, name));
+    if (opts.type && card.hook_type !== opts.type)
+      continue;
+    if (opts.niche && card.niche !== opts.niche)
+      continue;
+    if (opts.status && card.status !== opts.status)
+      continue;
+    if (opts.formula && !(card.formula_ids || []).includes(opts.formula))
+      continue;
+    cards.push(card);
+  }
+  return cards.sort((a, b) => {
+    const statusRank = (s) => s === "published" ? 0 : 1;
+    const d = statusRank(a.status) - statusRank(b.status);
+    if (d !== 0)
+      return d;
+    return (b.evidence.account_count || 0) - (a.evidence.account_count || 0);
+  });
+}
+function getHook(id, dir) {
+  const root = resolveCatalogDir(dir);
+  const path = join5(root, "hooks", `${id}.json`);
+  if (!existsSync5(path))
+    throw new Error(`Hook not found: ${id}`);
+  return readJson2(path);
+}
+async function fetchHostedHook(id, baseUrl, fetchImpl = fetch) {
+  const response = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/v1/hooks/${encodeURIComponent(id)}`);
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body?.ok || !body.data) {
+    throw new Error(`Hook not found: ${id} (${body?.error?.message ?? `HTTP ${response.status}`})`);
+  }
+  return body.data;
+}
+async function resolveHook(id, opts) {
+  if (opts.dir)
+    return getHook(id, opts.dir);
+  try {
+    return getHook(id);
+  } catch {
+    return fetchHostedHook(id, opts.baseUrl, opts.fetchImpl);
+  }
+}
+function recommendHooks(input) {
+  const limit = input.limit ?? 5;
+  const all = listHooks({
+    dir: input.dir,
+    type: input.type
+  });
+  const topic = (input.topic || "").toLowerCase();
+  const scored = all.map((card) => {
+    let score = 0;
+    const reasons = [];
+    if (input.type && card.hook_type === input.type) {
+      score += 3;
+      reasons.push("hook_type match");
+    }
+    if (input.niche && card.niche === input.niche) {
+      score += 2;
+      reasons.push("niche match");
+    } else if (input.niche) {
+      score += 0.25;
+      reasons.push("cross-niche kept");
+    }
+    if (card.status === "published") {
+      score += 2;
+      reasons.push(`published (${card.evidence.account_count} accounts)`);
+    } else {
+      reasons.push("hypothesis \u2014 weak evidence");
+    }
+    const newest = card.evidence.newest_days_ago;
+    if (typeof newest === "number" && newest <= 60) {
+      score += 0.5;
+      reasons.push("recent evidence");
+    }
+    score += Math.min(card.evidence.account_count, 5) * 0.3;
+    if (topic && card.format.toLowerCase().includes("{x}")) {
+      score += 0.25;
+      reasons.push("format has {X} slot");
+    }
+    return { ...card, score, reasons };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  const top = scored.slice(0, limit);
+  const best = top[0]?.score ?? 0;
+  if (!top.length || best < 2) {
+    return {
+      cards: top,
+      stop: true,
+      message: "Top score is low \u2014 try another niche/type or gather more labeled hooks."
+    };
+  }
+  return { cards: top, stop: false };
+}
+
 // src/v1-cli.ts
 var CLI_MODULE_URL = import.meta.url;
 function readCliVersion() {
   try {
-    const pkg = JSON.parse(readFileSync3(join4(cliPackageRoot(CLI_MODULE_URL), "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync5(join6(cliPackageRoot(CLI_MODULE_URL), "package.json"), "utf8"));
     return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
 var HEADLESS_RENDER_DISABLED = "PNG delivery is Studio Download (browser ZIP). CLI/MCP hosted PNG jobs are retired. Open the Run in Studio and use Download.";
-var credentialPath = join4(homedir3(), ".config", "easysociable", "credentials.json");
+var credentialPath = join6(homedir4(), ".config", "easysociable", "credentials.json");
 function resolveInstallSkillIds(options) {
   return parseInstallSkills(typeof options.skills === "string" ? options.skills : void 0);
 }
 function readStoredCredentials() {
   try {
-    if (!existsSync4(credentialPath)) return null;
-    const parsed = JSON.parse(readFileSync3(credentialPath, "utf8"));
+    if (!existsSync6(credentialPath)) return null;
+    const parsed = JSON.parse(readFileSync5(credentialPath, "utf8"));
     if (typeof parsed.apiKey !== "string" || typeof parsed.baseUrl !== "string") return null;
     return { apiKey: parsed.apiKey, baseUrl: parsed.baseUrl };
   } catch {
@@ -33272,7 +33583,7 @@ function readStoredCredentials() {
   }
 }
 async function writeStoredCredentials(credentials) {
-  await mkdir(join4(homedir3(), ".config", "easysociable"), { recursive: true, mode: 448 });
+  await mkdir(join6(homedir4(), ".config", "easysociable"), { recursive: true, mode: 448 });
   await writeFile(credentialPath, `${JSON.stringify(credentials, null, 2)}
 `, { mode: 384 });
   await chmod(credentialPath, 384);
@@ -33295,10 +33606,13 @@ function commandWantsJson(command) {
   const withGlobals = typeof command.optsWithGlobals === "function" ? command.optsWithGlobals() : {};
   return withGlobals.json === true;
 }
+function gatewayBaseUrl(stored = readStoredCredentials()) {
+  return stored?.baseUrl ?? process.env.EASYSOCIABLE_GATEWAY_URL ?? process.env.EASYSOCIABLE_API_URL ?? "http://127.0.0.1:8787";
+}
 function clientFromEnv() {
   const stored = readStoredCredentials();
   const allowEnv = process.env.EASYSOCIABLE_ALLOW_ENV_CREDENTIALS === "true";
-  const baseUrl = stored?.baseUrl ?? process.env.EASYSOCIABLE_GATEWAY_URL ?? process.env.EASYSOCIABLE_API_URL ?? "http://127.0.0.1:8787";
+  const baseUrl = gatewayBaseUrl(stored);
   const apiKey = stored?.apiKey ?? (allowEnv ? process.env.EASYSOCIABLE_API_KEY : void 0);
   if (!apiKey) throw new Error("EASYSOCIABLE_API_KEY is required. Run `easysociable auth login` first.");
   return new TemplateGatewayClient({
@@ -33313,14 +33627,14 @@ function jsonOption(command) {
 }
 function defaultEngineRoot() {
   try {
-    if (existsSync4("/workspace") && statSync2("/workspace").isDirectory())
+    if (existsSync6("/workspace") && statSync2("/workspace").isDirectory())
       return "/workspace";
   } catch {
   }
   return process.cwd();
 }
 function installHome(options) {
-  return typeof options.home === "string" && options.home ? String(options.home) : homedir3();
+  return typeof options.home === "string" && options.home ? String(options.home) : homedir4();
 }
 function installSource(options) {
   if (typeof options.source === "string" && options.source)
@@ -33331,17 +33645,17 @@ function installSource(options) {
 }
 function detectedHosts(home) {
   const candidates = [
-    { host: "codex", dir: join4(home, ".codex") },
-    { host: "claude", dir: join4(home, ".claude") }
+    { host: "codex", dir: join6(home, ".codex") },
+    { host: "claude", dir: join6(home, ".claude") }
   ];
-  return candidates.filter((item) => existsSync4(item.dir)).map((item) => ({ host: item.host, configPath: join4(item.dir, "mcp.json"), skillsPath: join4(item.dir, "skills") }));
+  return candidates.filter((item) => existsSync6(item.dir)).map((item) => ({ host: item.host, configPath: join6(item.dir, "mcp.json"), skillsPath: join6(item.dir, "skills") }));
 }
 async function planInstallation(options) {
   const home = installHome(options);
   const source = installSource(options);
   const hosts = detectedHosts(home);
   const skillNames = resolveInstallSkillIds(options);
-  const missingSkills = skillNames.filter((name) => !existsSync4(join4(source, name)));
+  const missingSkills = skillNames.filter((name) => !existsSync6(join6(source, name)));
   return {
     source,
     home,
@@ -33350,7 +33664,7 @@ async function planInstallation(options) {
     missingSkills,
     changes: hosts.flatMap((host) => [
       `merge ${host.configPath} with one easysociable MCP registration`,
-      ...skillNames.map((name) => `install ${join4(host.skillsPath, name)}`)
+      ...skillNames.map((name) => `install ${join6(host.skillsPath, name)}`)
     ])
   };
 }
@@ -33366,7 +33680,7 @@ async function applyInstallation(options) {
   const backupSuffix = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const backups = [];
   for (const host of detectedHosts(String(plan.home))) {
-    if (existsSync4(host.configPath)) {
+    if (existsSync6(host.configPath)) {
       const backupPath = `${host.configPath}.bak.${backupSuffix}`;
       await copyFile(host.configPath, backupPath);
       backups.push(backupPath);
@@ -33374,7 +33688,7 @@ async function applyInstallation(options) {
     await installHostConfig({ host: host.host, dataDir: "", configPath: host.configPath });
     await mkdir(host.skillsPath, { recursive: true, mode: 448 });
     for (const skill of resolveInstallSkillIds(options))
-      await cp(join4(String(plan.source), skill), join4(host.skillsPath, skill), { recursive: true, force: false, errorOnExist: false });
+      await cp(join6(String(plan.source), skill), join6(host.skillsPath, skill), { recursive: true, force: false, errorOnExist: false });
   }
   if (options.json !== true) {
     process.stdout.write(`Installed skills your Agent will use:
@@ -33521,12 +33835,23 @@ function buildV1Cli() {
   jsonOption(auth.command("status").description("Show authentication status")).action(async (...args) => {
     const command = args.at(-1);
     const stored = readStoredCredentials();
-    print({ authenticated: Boolean(stored), baseUrl: stored?.baseUrl ?? process.env.EASYSOCIABLE_GATEWAY_URL ?? process.env.EASYSOCIABLE_API_URL ?? "http://127.0.0.1:8787", credentialPath }, Boolean(command.opts().json));
+    print({ authenticated: Boolean(stored), baseUrl: gatewayBaseUrl(stored), credentialPath }, Boolean(command.opts().json));
   });
-  auth.command("login").description("Store an API key in the OS user credential file").requiredOption("--api-key <key>").option("--gateway-url <url>", "Gateway URL", "http://127.0.0.1:8787").action(async (...args) => {
+  auth.command("login").description("Sign in via the browser (or store an existing API key with --api-key)").option("--api-key <key>").option("--gateway-url <url>", "Gateway URL").option("--site-url <url>", "EasySociable site URL", process.env.EASYSOCIABLE_SITE_URL ?? "https://easysociable.com").action(async (...args) => {
     const command = args.at(-1);
     const opts = command.opts();
-    await writeStoredCredentials({ apiKey: opts.apiKey, baseUrl: opts.gatewayUrl.replace(/\/$/, "") });
+    const login = opts.apiKey ? { apiKey: opts.apiKey, gatewayUrl: "" } : await waitForBrowserLogin({
+      siteUrl: opts.siteUrl,
+      onReady: (url2) => {
+        process.stdout.write(`Opening your browser to connect this Agent:
+  ${url2}
+Waiting for approval\u2026
+`);
+        openBrowser(url2);
+      }
+    });
+    const baseUrl = (opts.gatewayUrl ?? (login.gatewayUrl || gatewayBaseUrl(null))).replace(/\/$/, "");
+    await writeStoredCredentials({ apiKey: login.apiKey, baseUrl });
     process.stdout.write(`Stored EasySociable credentials at ${credentialPath}.
 `);
   });
@@ -33629,6 +33954,100 @@ function buildV1Cli() {
   jsonOption(renders.command("export").description("Retired: PNG packs come from Studio Download").requiredOption("--id <id>").requiredOption("--output <path>")).action(withClient(async () => {
     throw new Error(HEADLESS_RENDER_DISABLED);
   }));
+  const formulas = program.command("formulas").description("Read Formula cards (local TikTok Radar graph/; `get` falls back to the hosted catalog)");
+  formulas.option("--catalog <path>", "Path to graph/ dir containing catalog.json (or set EASYSOCIABLE_FORMULA_CATALOG)");
+  jsonOption(formulas.command("list").option("--recipe <recipe>").option("--niche <niche>").option("--status <status>").option("--platform <platform>")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    const cards = listFormulas({
+      dir: opts.catalog ? String(opts.catalog) : void 0,
+      recipe: opts.recipe ? String(opts.recipe) : void 0,
+      niche: opts.niche ? String(opts.niche) : void 0,
+      status: opts.status ? String(opts.status) : void 0,
+      platform: opts.platform ? String(opts.platform) : void 0
+    });
+    print(cards.map((c) => ({
+      id: c.id,
+      recipe: c.recipe,
+      niche: c.niche,
+      swipe: c.swipe,
+      status: c.status,
+      accounts: c.evidence.account_count,
+      posts: c.evidence.post_count,
+      title_template: c.title_template
+    })), commandWantsJson(command));
+  });
+  jsonOption(formulas.command("get").requiredOption("--id <id>")).action(async (...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    const card = await resolveFormula(String(opts.id), { dir: opts.catalog ? String(opts.catalog) : void 0, baseUrl: gatewayBaseUrl() });
+    print(card, commandWantsJson(command));
+  });
+  jsonOption(formulas.command("catalog")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    print(loadCatalog(opts.catalog ? String(opts.catalog) : void 0), commandWantsJson(command));
+  });
+  jsonOption(formulas.command("recommend").description("Rank cards for a recipe (niche is a bonus). Pass --recipe from Jev theme\u2192recipe.").requiredOption("--recipe <recipe>").option("--niche <niche>").option("--platform <platform>", "tiktok").option("--fact-count <n>", "How many user facts are available to fill point beats").option("--limit <n>", "Max cards", "5")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    const result = recommendFormulas({
+      recipe: String(opts.recipe),
+      niche: opts.niche ? String(opts.niche) : void 0,
+      platform: opts.platform ? String(opts.platform) : void 0,
+      factCount: opts.factCount != null ? Number(opts.factCount) : void 0,
+      dir: opts.catalog ? String(opts.catalog) : void 0,
+      limit: opts.limit != null ? Number(opts.limit) : 5
+    });
+    print(result, commandWantsJson(command));
+  });
+  const hooks = program.command("hooks").description("Read Hook format molds (local graph/hooks/; `get` falls back to hosted catalog)");
+  hooks.option("--catalog <path>", "Path to graph/ dir (or set EASYSOCIABLE_FORMULA_CATALOG)");
+  jsonOption(hooks.command("list").option("--type <hook_type>", "contrast | list-tease | identity | number | other").option("--niche <niche>").option("--status <status>").option("--formula <formula_id>", "Only hooks soft-linked to this formula")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    const cards = listHooks({
+      dir: opts.catalog ? String(opts.catalog) : void 0,
+      type: opts.type ? String(opts.type) : void 0,
+      niche: opts.niche ? String(opts.niche) : void 0,
+      status: opts.status ? String(opts.status) : void 0,
+      formula: opts.formula ? String(opts.formula) : void 0
+    });
+    print(cards.map((c) => ({
+      id: c.id,
+      hook_type: c.hook_type,
+      niche: c.niche,
+      status: c.status,
+      accounts: c.evidence.account_count,
+      posts: c.evidence.post_count,
+      formula_ids: c.formula_ids,
+      title: c.title,
+      format: c.format
+    })), commandWantsJson(command));
+  });
+  jsonOption(hooks.command("get").requiredOption("--id <id>")).action(async (...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    const card = await resolveHook(String(opts.id), { dir: opts.catalog ? String(opts.catalog) : void 0, baseUrl: gatewayBaseUrl() });
+    print(card, commandWantsJson(command));
+  });
+  jsonOption(hooks.command("catalog")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    print(loadHooksCatalog(opts.catalog ? String(opts.catalog) : void 0), commandWantsJson(command));
+  });
+  jsonOption(hooks.command("recommend").description("Rank hook molds for a topic/niche. Agent then fills format with the topic (do not copy example).").option("--topic <topic>", "User topic for {X}").option("--niche <niche>").option("--type <hook_type>").option("--limit <n>", "Max hooks", "5")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.optsWithGlobals();
+    const result = recommendHooks({
+      topic: opts.topic ? String(opts.topic) : void 0,
+      niche: opts.niche ? String(opts.niche) : void 0,
+      type: opts.type ? String(opts.type) : void 0,
+      dir: opts.catalog ? String(opts.catalog) : void 0,
+      limit: opts.limit != null ? Number(opts.limit) : 5
+    });
+    print(result, commandWantsJson(command));
+  });
   const mcp = program.command("mcp").description("Install and run the unified EasySociable MCP server");
   jsonOption(mcp.command("install").requiredOption("--host <host>", "codex, claude, hermes, or openclaw").option("--config-path <path>")).action((...args) => {
     const command = args.at(-1);