@easysociable/cli 0.1.11 → 0.1.13

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(),
@@ -16297,11 +16304,13 @@ function isRetryableStatus(status) {
 function sleep(ms) {
   return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
-var TemplateGatewayError, TemplateGatewayClient;
+var DEFAULT_TEMPLATE_PAGE_SIZE, MAX_TEMPLATE_PAGE_SIZE, TemplateGatewayError, TemplateGatewayClient;
 var init_client = __esm({
   "../../packages/template-gateway-client/src/client.ts"() {
     "use strict";
     init_src();
+    DEFAULT_TEMPLATE_PAGE_SIZE = 20;
+    MAX_TEMPLATE_PAGE_SIZE = 50;
     TemplateGatewayError = class extends Error {
       code;
       retryable;
@@ -16347,6 +16356,13 @@ var init_client = __esm({
         return response.json;
       }
       async listTemplates(query) {
+        return (await this.listTemplatesPage(query)).templates;
+      }
+      /**
+       * Same as listTemplates plus `nextCursor` so Agents know the catalog is paged.
+       * Derived client-side (full page ⇒ maybe more) to keep the strict v1 envelope.
+       */
+      async listTemplatesPage(query) {
         const parsed = parseListTemplatesQuery(query ?? {});
         const params = new URLSearchParams();
         const appendList = (key, values) => {
@@ -16375,7 +16391,23 @@ var init_client = __esm({
         const qs = params.toString();
         const response = await this.request("GET", qs ? `/v1/templates?${qs}` : "/v1/templates");
         this.throwIfError(response.status, response.json);
-        return parseTemplateSummaryList(response.json);
+        const templates = parseTemplateSummaryList(response.json);
+        const limit = parsed.limit ?? DEFAULT_TEMPLATE_PAGE_SIZE;
+        const offset = Number.parseInt(parsed.cursor ?? "0", 10) || 0;
+        return { templates, nextCursor: templates.length >= limit ? String(offset + limit) : null };
+      }
+      /** Drain every page for a filtered query (platform catalogs are tens of templates). */
+      async listAllTemplates(query) {
+        const all = [];
+        let cursor;
+        for (let page = 0; page < 40; page += 1) {
+          const result = await this.listTemplatesPage({ ...query, limit: MAX_TEMPLATE_PAGE_SIZE, cursor });
+          all.push(...result.templates);
+          if (!result.nextCursor)
+            return all;
+          cursor = result.nextCursor;
+        }
+        return all;
       }
       async getTemplate(templateId) {
         const response = await this.request("GET", `/v1/templates/${encodeURIComponent(templateId)}`);
@@ -16543,6 +16575,12 @@ var init_client = __esm({
         this.throwIfError(response.status, response.json);
         return parseSlideshowRun(response.json);
       }
+      /** Per-page shortlist (hard filter → fit score → recent-family penalty → explore slot). Agent still picks. */
+      async recommendSlideshowTemplates(input) {
+        const response = await this.request("POST", "/v1/slideshow/template-recommendations", input);
+        this.throwIfError(response.status, response.json);
+        return response.json.data;
+      }
       async listSlideshowRuns(query = {}) {
         const input = listSlideshowRunsQuerySchema.parse(query);
         const params = new URLSearchParams();
@@ -16607,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}`;
@@ -16802,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;
@@ -31720,7 +31758,7 @@ var init_src4 = __esm({
       {
         name: "list_templates",
         title: "List templates",
-        description: "List public template catalog summaries from Gateway (filterable; no AST)",
+        description: "List public template catalog summaries from Gateway (filterable; no AST). Paged: follow nextCursor, or pass all=true with platforms to get the whole platform catalog before choosing. For Slideshow page choice prefer recommend_slideshow_templates.",
         effect: "read-only",
         inputSchema: {
           type: "object",
@@ -31734,11 +31772,13 @@ var init_src4 = __esm({
             requiresImage: { type: "boolean" },
             locale: { type: "string" },
             q: { type: "string" },
-            limit: { type: "number" }
+            limit: { type: "number" },
+            cursor: { type: "string" },
+            all: { type: "boolean" }
           },
           additionalProperties: false
         },
-        outputSchema: { type: "object", properties: { templates: { type: "array" } } }
+        outputSchema: { type: "object", properties: { templates: { type: "array" }, nextCursor: { type: ["string", "null"] } } }
       },
       {
         name: "get_template",
@@ -32057,7 +32097,7 @@ var init_src4 = __esm({
         };
         try {
           if (toolName === "list_templates") {
-            const templates = await this.client.listTemplates({
+            const query = {
               platforms: args.platforms,
               roles: args.roles,
               contentFamily: args.contentFamily,
@@ -32066,10 +32106,16 @@ var init_src4 = __esm({
               canvasPreset: args.canvasPreset,
               requiresImage: typeof args.requiresImage === "boolean" ? args.requiresImage : void 0,
               locale: args.locale,
-              q: typeof args.q === "string" ? args.q : void 0,
-              limit: typeof args.limit === "number" ? args.limit : void 0
+              q: typeof args.q === "string" ? args.q : void 0
+            };
+            if (args.all === true)
+              return { ok: true, data: { templates: await this.client.listAllTemplates(query), nextCursor: null }, meta: meta4 };
+            const page = await this.client.listTemplatesPage({
+              ...query,
+              limit: typeof args.limit === "number" ? args.limit : void 0,
+              cursor: typeof args.cursor === "string" ? args.cursor : void 0
             });
-            return { ok: true, data: { templates }, meta: meta4 };
+            return { ok: true, data: page, meta: meta4 };
           }
           if (toolName === "get_template") {
             const template = await this.client.getTemplate(String(args.templateId));
@@ -32277,6 +32323,7 @@ var init_src5 = __esm({
     objectSchema = { type: "object", properties: {}, additionalProperties: true };
     slideshowToolRegistry = [
       { name: "list_runs", title: "List slideshow runs", description: "List owner-scoped Slideshow Runs with optional filters.", effect: "read-only", inputSchema: { ...objectSchema, properties: { q: { type: "string" }, platform: { type: "string" }, profileId: { type: "string" }, brandProfileId: { type: "string" }, contentSlug: { type: "string" }, status: { type: "string" } } }, outputSchema: objectSchema },
+      { name: "recommend_templates", title: "Recommend slideshow page templates", description: "Before create_run: send the Page Contracts (role, density, slotSummary per page) and get a shortlist per page with reasons. Recently used Layout Families are demoted and one unused family is always kept. Pick one templateId per page yourself; gaps list pages needing more templates.", effect: "read-only", inputSchema: { ...objectSchema, properties: { platform: { type: "string" }, canvasPreset: { type: "string" }, pages: { type: "array", items: { type: "object", properties: { role: { type: "string" }, density: { type: "string" }, slotSummary: { type: "object" }, requiresImage: { type: "boolean" } }, required: ["role"] } }, k: { type: "integer", minimum: 2, maximum: 5 }, seed: { type: "string" } }, required: ["platform", "pages"] }, outputSchema: objectSchema },
       { name: "create_run", title: "Create slideshow run", description: "Create an ADR-0026 Slideshow Run from a ContentPack.", effect: "local-write-job", inputSchema: { ...objectSchema, properties: { pack: { type: "object" }, brandId: { type: "string" }, brandProfileId: { type: "string" }, contentSlug: { type: "string" } }, required: ["pack"] }, outputSchema: objectSchema },
       { name: "get_run", title: "Get slideshow run", description: "Get an owner-scoped Slideshow Run.", effect: "read-only", inputSchema: { ...objectSchema, properties: { runId: { type: "string" } }, required: ["runId"] }, outputSchema: objectSchema },
       { name: "update_run", title: "Update slideshow run", description: "Edit page-instance slots/layout/style/decorations or presentation preference with optimistic revision.", effect: "local-write-job", inputSchema: { ...objectSchema, properties: { runId: { type: "string" }, pack: { type: "object" }, brandId: { type: "string" }, brandProfileId: { type: "string" }, contentSlug: { type: "string" }, baseRevision: { type: "integer", minimum: 1 }, pageIndex: { type: "integer", minimum: 0 }, slots: { type: "object" }, layout: { type: "object" }, style: { type: "object" }, decorations: { type: "array" } }, required: ["runId"] }, outputSchema: objectSchema },
@@ -32305,6 +32352,8 @@ var init_src5 = __esm({
                 contentSlug: args.contentSlug,
                 status: args.status
               }), meta: m };
+            case "recommend_templates":
+              return { ok: true, data: await this.client.recommendSlideshowTemplates({ platform: String(args.platform), pages: args.pages, canvasPreset: args.canvasPreset, k: args.k, seed: args.seed }), meta: m };
             case "create_run":
               return { ok: true, data: await this.client.createSlideshowRun({ pack: args.pack, brandId: args.brandId, brandProfileId: args.brandProfileId, contentSlug: args.contentSlug }), meta: m };
             case "get_run":
@@ -32376,6 +32425,7 @@ var init_src6 = __esm({
     };
     slideshowNames = {
       list_runs: "list_slideshow_runs",
+      recommend_templates: "recommend_slideshow_templates",
       create_run: "create_slideshow_run",
       get_run: "get_slideshow_run",
       update_run: "update_slideshow_run",
@@ -32508,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
@@ -33190,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;
@@ -33203,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 {
@@ -33229,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);
@@ -33252,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({
@@ -33270,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)
@@ -33288,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,
@@ -33307,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)}`)
     ])
   };
 }
@@ -33323,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);
@@ -33331,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:
@@ -33478,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}.
 `);
   });
@@ -33503,7 +33871,20 @@ function buildV1Cli() {
   jsonOption(images.command("search").requiredOption("--q <query>")).action(withClient(async (client, opts) => client.requestJson("GET", `/v1/images?q=${encodeURIComponent(String(opts.q))}`)));
   jsonOption(images.command("attest").requiredOption("--id <id>")).action(withClient(async (client, opts) => client.requestJson("POST", `/v1/images/${opts.id}/attest`, { accepted: true })));
   const templates = program.command("templates").description("Create and manage Page Template drafts");
-  jsonOption(templates.command("list")).action(withClient(async (client) => client.listTemplates()));
+  jsonOption(templates.command("list").option("--platform <platform>", "tiktok | instagram | linkedin | threads | xiaohongshu").option("--canvas <preset>", "Canvas preset e.g. 9:16, 4:5").option("--role <role>", "Page role filter (weak tag)").option("--limit <n>", "Page size (max 50)").option("--cursor <cursor>", "Offset cursor from a previous page").option("--all", "Return every matching template (drains pages)")).action(withClient(async (client, opts) => {
+    const query = {
+      platforms: opts.platform ? [String(opts.platform)] : void 0,
+      canvasPreset: opts.canvas ? String(opts.canvas) : void 0,
+      roles: opts.role ? [String(opts.role)] : void 0
+    };
+    if (opts.all === true)
+      return client.listAllTemplates(query);
+    const page = await client.listTemplatesPage({ ...query, limit: opts.limit ? Number(opts.limit) : void 0, cursor: opts.cursor ? String(opts.cursor) : void 0 });
+    if (page.nextCursor)
+      process.stderr.write(`More templates: --cursor ${page.nextCursor} or --all
+`);
+    return page.templates;
+  }));
   jsonOption(templates.command("get").requiredOption("--id <id>")).action(withClient(async (client, opts) => client.getTemplate(String(opts.id))));
   jsonOption(templates.command("create-draft").requiredOption("--file <path>")).action(withClient(async (client, opts) => client.createDraft(JSON.parse(await readFile(String(opts.file), "utf8")))));
   jsonOption(templates.command("update-draft").requiredOption("--id <id>").requiredOption("--file <path>")).action(withClient(async (client, opts) => client.updateDraft(String(opts.id), JSON.parse(await readFile(String(opts.file), "utf8")))));
@@ -33531,6 +33912,10 @@ function buildV1Cli() {
     contentSlug: opts.contentSlug ? String(opts.contentSlug) : void 0,
     status: opts.status ? String(opts.status) : void 0
   })));
+  jsonOption(slideshows.command("recommend").description("Shortlist Page Templates per page from Page Contracts JSON ({ platform, pages: [{ role, density?, slotSummary? }], seed? })").requiredOption("--file <path>").option("--seed <seed>", "Tie-break seed, e.g. the content slug")).action(withClient(async (client, opts) => {
+    const input = JSON.parse(await readFile(String(opts.file), "utf8"));
+    return client.recommendSlideshowTemplates(opts.seed ? { ...input, seed: String(opts.seed) } : input);
+  }));
   jsonOption(slideshows.command("create").requiredOption("--file <path>").option("--allow-local-fixture", "Allow workspace_local fixture keys (dev only)")).action(withClient(async (client, opts) => {
     await assertHumanStudioIdentity(client, { allowLocalFixture: opts.allowLocalFixture === true });
     return client.createSlideshowRun({ pack: JSON.parse(await readFile(String(opts.file), "utf8")) });
@@ -33569,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);
@@ -33598,5 +34077,5 @@ async function runV1Cli(argv = process.argv) {
 
 // src/bin.ts
 var exitCode = await runV1Cli();
-process.exit(exitCode);
+process.stdout.write("", () => process.exit(exitCode));
 //# sourceMappingURL=easysociable.js.map