@frankieai/core 0.2.4 → 0.2.6

package/dist/index.cjs

@@ -21,6 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   FIREWORKS_MODELS: () => FIREWORKS_MODELS,
+  SKILL_TOOL_NAME: () => SKILL_TOOL_NAME,
+  STANDARD_AGENT_IDS: () => STANDARD_AGENT_IDS,
+  STARTER_PROMPT_ICONS: () => STARTER_PROMPT_ICONS,
   activeSkills: () => activeSkills,
   agentConfigSchema: () => agentConfigSchema,
   apiCapabilitySchema: () => apiCapabilitySchema,
@@ -39,14 +42,32 @@ __export(index_exports, {
   evaluateToolPolicy: () => evaluateToolPolicy,
   featuresConfigSchema: () => featuresConfigSchema,
   frankieConfigSchema: () => frankieConfigSchema,
+  inferTheme: () => inferTheme,
+  insertImport: () => insertImport,
+  installAgentIds: () => installAgentIds,
+  installBranch: () => installBranch,
+  installTitle: () => installTitle,
+  knowledgeBaseSchema: () => knowledgeBaseSchema,
+  knowledgeSourceSchema: () => knowledgeSourceSchema,
   limitsConfigSchema: () => limitsConfigSchema,
   matchPath: () => matchPath,
+  matchesAnyPagePattern: () => matchesAnyPagePattern,
+  matchesInstallBranch: () => matchesInstallBranch,
+  matchesPagePattern: () => matchesPagePattern,
   mcpServerSchema: () => mcpServerSchema,
   modelChoiceSchema: () => modelChoiceSchema,
   modelConfigSchema: () => modelConfigSchema,
+  moduleImporter: () => moduleImporter,
+  mountWidget: () => mountWidget,
+  normalizeColor: () => normalizeColor,
   operationId: () => operationId,
   parseFrankieConfig: () => parseFrankieConfig,
+  personaEnvKey: () => personaEnvKey,
+  personaProfileSchema: () => personaProfileSchema,
+  plainText: () => plainText,
   planHostedInstall: () => planHostedInstall,
+  renderJson: () => renderJson,
+  resolvePersonaConfig: () => resolvePersonaConfig,
   sdkUpdateWorkflow: () => sdkUpdateWorkflow,
   skillSchema: () => skillSchema,
   starterPromptSchema: () => starterPromptSchema,
@@ -55,7 +76,8 @@ __export(index_exports, {
   toolDescriptions: () => toolDescriptions,
   toolPolicySchema: () => toolPolicySchema,
   validateApiDocument: () => validateApiDocument,
-  widgetThemeSchema: () => widgetThemeSchema
+  widgetThemeSchema: () => widgetThemeSchema,
+  withDependencies: () => withDependencies
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -87,12 +109,31 @@ function matches(toolName, pattern) {
   if (toolName === pattern) return true;
   return toolName.startsWith(`${pattern}__`);
 }
+var SKILL_TOOL_NAME = "frankie__use_skill";
 function describeTool(toolName, input) {
+  if (toolName === SKILL_TOOL_NAME) {
+    const skill = typeof input === "object" && input !== null ? input["skill"] : void 0;
+    return typeof skill === "string" && skill.trim() ? `Using skill: ${skill.trim()}` : "Using a skill";
+  }
+  const builtIn = /^frankie__([a-z0-9]+)__(.+)$/.exec(toolName);
+  if (builtIn) {
+    const [, group, action] = builtIn;
+    if (group === "docs") return "Search the docs";
+    if (group === "escalate") return "Escalate to a person";
+    return humanise(action ?? toolName);
+  }
   const mcp = /^mcp__([^_]+(?:_[^_]+)*)__(.+)$/.exec(toolName);
   if (mcp) {
     const [, server, tool] = mcp;
     return `${humanise(tool ?? toolName)} \xB7 ${server}`;
   }
+  if (toolName.startsWith("api__")) {
+    const rest = toolName.slice("api__".length);
+    const sep = rest.indexOf("__");
+    const operation = (sep >= 0 ? rest.slice(sep + 2) : rest).replace(/__+/g, "_");
+    const verb = /^(get|post|put|patch|delete|head|options)_(.+)$/i.exec(operation);
+    return verb ? `${verb[1].toUpperCase()} ${humanise(verb[2])}` : humanise(operation);
+  }
   const inputRecord = typeof input === "object" && input !== null ? input : {};
   const hint = inputRecord["path"] ?? inputRecord["url"] ?? inputRecord["query"] ?? inputRecord["command"];
   return typeof hint === "string" ? `${humanise(toolName)}: ${truncate(hint, 60)}` : humanise(toolName);
@@ -132,16 +173,21 @@ function toolDescriptions(config, toolIds) {
   for (const source of config.apis) {
     for (const capability of source.capabilities) {
       const id = `api__${source.name}__${capability.operationId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 48)}`;
-      if (wanted.has(id)) found.set(id, `${capability.method} ${capability.path}` + (capability.summary ? ` \u2014 ${capability.summary}` : ""));
+      if (wanted.has(id)) {
+        found.set(id, {
+          description: `${capability.method} ${capability.path}` + (capability.summary ? ` \u2014 ${capability.summary}` : ""),
+          ...capability.inputs ? { inputs: capability.inputs } : {}
+        });
+      }
     }
   }
   for (const source of config.mcpServers) {
     for (const tool of source.discoveredTools) {
       const id = `mcp__${source.name}__${tool.name}`;
-      if (wanted.has(id)) found.set(id, tool.description || tool.name);
+      if (wanted.has(id)) found.set(id, { description: tool.description || tool.name, ...tool.inputs ? { inputs: tool.inputs } : {} });
     }
   }
-  return toolIds.map((id) => ({ id, description: found.get(id) ?? id }));
+  return toolIds.map((id) => ({ id, ...found.get(id) ?? { description: id } }));
 }
 function suggestedPromptsFromSkills(config) {
   const seen = /* @__PURE__ */ new Set();
@@ -179,6 +225,8 @@ function draftSkill(goal, tools) {
     "",
     "Required inputs: note what each tool below needs, and ask the user for anything missing before calling it.",
     "",
+    "Quality bar: what makes a good result, not just a valid request. List the optional fields a complete item has (a description, a level, a length\u2026) and what a good value looks like; draft them from the conversation, ask for facts only the user knows, and show the full item for confirmation before saving.",
+    "",
     "Steps:",
     ...tools.map((tool, index) => `${index + 1}. ${tool.id}${tool.label ? ` \u2014 ${tool.label}` : ""}`),
     "Call only the tool that matches the user's actual request; respect the signed-in user's own permissions and confirm before any consequential write.",
@@ -284,7 +332,19 @@ var featuresConfigSchema = import_zod2.z.object({
    * Internal dashboard mode: help administer existing workspaces, tools and
    * conversations without restarting the onboarding procedure.
    */
-  configurationAssistant: import_zod2.z.boolean().default(false)
+  configurationAssistant: import_zod2.z.boolean().default(false),
+  /**
+   * Human escalation: give the agent a built-in tool to hand a conversation to
+   * the workspace's team when it can't resolve something or the visitor asks
+   * for a person. Each escalation is recorded on the conversation (a dashboard
+   * inbox) and, when `webhookUrl` is set, POSTed there (Slack, Zapier, a
+   * ticketing intake…). For support/landing-page agents.
+   */
+  escalation: import_zod2.z.object({
+    enabled: import_zod2.z.boolean().default(false),
+    /** Optional HTTPS endpoint that receives each escalation as JSON. */
+    webhookUrl: import_zod2.z.string().url().startsWith("https://").max(2e3).optional()
+  }).prefault({})
 }).prefault({});
 var mcpServerSchema = import_zod2.z.object({
   name: import_zod2.z.string().min(1).regex(/^[a-z0-9][a-z0-9_-]*$/i, "MCP server names must be alphanumeric with - or _"),
@@ -298,7 +358,8 @@ var mcpServerSchema = import_zod2.z.object({
   enabled: import_zod2.z.boolean().default(true),
   /** Explicit tool selection. Omitted keeps legacy all-tools behavior; [] disables all. */
   selectedTools: import_zod2.z.array(import_zod2.z.string().min(1)).optional(),
-  discoveredTools: import_zod2.z.array(import_zod2.z.object({ name: import_zod2.z.string(), description: import_zod2.z.string().optional() })).default([]),
+  /** Tools the server listed at discovery; `inputs` summarizes each one's input schema for skill writing. */
+  discoveredTools: import_zod2.z.array(import_zod2.z.object({ name: import_zod2.z.string(), description: import_zod2.z.string().optional(), inputs: import_zod2.z.string().optional() })).default([]),
   /** `http` covers streamable HTTP; `sse` is the legacy transport. */
   transport: import_zod2.z.enum(["http", "sse"]).default("http"),
   url: import_zod2.z.string().url(),
@@ -318,6 +379,14 @@ var apiCapabilitySchema = import_zod2.z.object({
   method: import_zod2.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
   path: import_zod2.z.string().min(1),
   summary: import_zod2.z.string().optional(),
+  /**
+   * One line naming what the operation takes — its path/query parameters and
+   * the request body's top-level fields, each marked required where the spec
+   * says so, with its description or allowed values. This is what lets a
+   * skill say which inputs to collect before calling the tool (and which it
+   * must never invent), instead of "check the tool's own parameters".
+   */
+  inputs: import_zod2.z.string().optional(),
   /**
    * True when this is a write operation the spec requires auth for, but the
    * source has no way to authorize it as the specific calling user — no
@@ -425,10 +494,26 @@ var toolPolicySchema = import_zod2.z.object({
    */
   denyByDefault: import_zod2.z.boolean().default(true)
 });
+var STARTER_PROMPT_ICONS = [
+  "sparkles",
+  "wand",
+  "book",
+  "chat",
+  "chart",
+  "bolt",
+  "music",
+  "mic",
+  "image",
+  "compass",
+  "lightbulb",
+  "file"
+];
 var starterPromptSchema = import_zod2.z.object({
   title: import_zod2.z.string().trim().min(1).max(80),
   description: import_zod2.z.string().trim().max(160).optional(),
-  message: import_zod2.z.string().trim().min(1).max(2e3)
+  message: import_zod2.z.string().trim().min(1).max(2e3),
+  /** One of STARTER_PROMPT_ICONS; unknown values fall back to a default icon. */
+  icon: import_zod2.z.enum(STARTER_PROMPT_ICONS).optional()
 });
 var agentConfigSchema = import_zod2.z.object({
   /** Prepended to the runtime's own operating instructions. */
@@ -502,6 +587,46 @@ var brandingConfigSchema = import_zod2.z.object({
   avatarUrl: import_zod2.z.string().url().optional(),
   launcherLabel: import_zod2.z.string().default("Need a hand?")
 });
+var knowledgeSourceSchema = import_zod2.z.object({
+  url: import_zod2.z.string().url().startsWith("https://").max(2e3)
+});
+var knowledgeBaseSchema = import_zod2.z.object({
+  enabled: import_zod2.z.boolean().default(false),
+  sources: import_zod2.z.array(knowledgeSourceSchema).max(20).default([]),
+  /** Cap on pages fetched per source during a crawl. */
+  maxPages: import_zod2.z.number().int().positive().max(200).default(40)
+}).prefault({});
+var personaProfileSchema = import_zod2.z.object({
+  /** Stable lowercase slug, unique within the workspace. Baked into env var, branch and mount module. */
+  id: import_zod2.z.string().min(1).max(40).regex(/^[a-z0-9][a-z0-9-]*$/, "Persona ids are lowercase slugs."),
+  /** Tab label and install-PR title suffix, e.g. "Knowledge base". */
+  label: import_zod2.z.string().trim().min(1).max(60),
+  /** This persona's own publishable key. One key maps to exactly one persona. */
+  publishableKey: import_zod2.z.string().min(8),
+  /** App-Router path globs this persona shows on. Empty = every page no other agent claims. */
+  pagePatterns: import_zod2.z.array(import_zod2.z.string().trim().min(1).max(200)).max(20).default([]),
+  /**
+   * Whether visitors may chat with this persona without signing in to the host
+   * app. Unset inherits the workspace's `auth.allowAnonymous`. A support or docs
+   * agent on public pages needs this on, or every logged-out visitor is told to
+   * sign in.
+   */
+  allowAnonymous: import_zod2.z.boolean().optional(),
+  /**
+   * Shallow-merged over the workspace branding. Each field is optional with no
+   * default, so only the keys the persona sets override the workspace's — an
+   * absent field keeps the workspace value rather than resetting it.
+   */
+  branding: import_zod2.z.object({
+    name: import_zod2.z.string().optional(),
+    tagline: import_zod2.z.string().optional(),
+    avatarUrl: import_zod2.z.string().url().optional(),
+    launcherLabel: import_zod2.z.string().optional()
+  }).optional(),
+  agent: agentConfigSchema.prefault({}),
+  features: featuresConfigSchema,
+  knowledgeBase: knowledgeBaseSchema
+});
 var frankieConfigSchema = import_zod2.z.object({
   tenantId: import_zod2.z.string().min(1),
   branding: brandingConfigSchema.prefault({}),
@@ -516,7 +641,18 @@ var frankieConfigSchema = import_zod2.z.object({
   skills: import_zod2.z.array(skillSchema).max(30).default([]),
   limits: limitsConfigSchema.prefault({}),
   /** Opt-in end-user chat capabilities (attachments, model picker). */
-  features: featuresConfigSchema
+  features: featuresConfigSchema,
+  /** Documentation the agent answers from, indexed for semantic retrieval. */
+  knowledgeBase: knowledgeBaseSchema,
+  /** App-Router path globs the primary (product) agent shows on. Empty = every page no persona claims. */
+  pagePatterns: import_zod2.z.array(import_zod2.z.string().trim().min(1).max(200)).max(20).default([]),
+  /**
+   * Additional embedded personas on this workspace. Empty for a single-agent
+   * workspace — the top-level agent/features/knowledgeBase + `auth.publishableKey`
+   * is the primary persona. Each entry resolves to its own one-agent config via
+   * its own publishable key, so the data plane still sees one config per key.
+   */
+  personas: import_zod2.z.array(personaProfileSchema).max(8).default([])
 });
 var LEAKY_MODEL_MIGRATION = {
   "accounts/fireworks/models/kimi-k2p7-code": "accounts/fireworks/models/kimi-k3"
@@ -532,8 +668,64 @@ function parseFrankieConfig(input) {
 function defineFrankieConfig(config) {
   return config;
 }
+function resolvePersonaConfig(config, publishableKey) {
+  if (publishableKey === config.auth.publishableKey) return config;
+  const persona = config.personas.find((entry) => entry.publishableKey === publishableKey);
+  if (!persona) return null;
+  return parseFrankieConfig({
+    ...config,
+    personas: [],
+    branding: { ...config.branding, ...persona.branding ?? {} },
+    auth: { ...config.auth, publishableKey: persona.publishableKey, allowAnonymous: persona.allowAnonymous ?? config.auth.allowAnonymous },
+    pagePatterns: persona.pagePatterns,
+    agent: persona.agent,
+    features: persona.features,
+    knowledgeBase: persona.knowledgeBase
+  });
+}
+function normalizeRoutePath(value) {
+  let path = (value || "/").split(/[?#]/)[0].trim();
+  if (!path.startsWith("/")) path = "/" + path;
+  if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+  return path;
+}
+function matchesPagePattern(pathname, pattern) {
+  const path = normalizeRoutePath(pathname);
+  const pat = normalizeRoutePath(pattern);
+  const trailingDeep = pat.endsWith("/**");
+  const core = trailingDeep ? pat.slice(0, -3) : pat;
+  const escaped = core.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const body = escaped.split("**").map((chunk) => chunk.replace(/\*/g, "[^/]*")).join(".*");
+  return new RegExp("^" + body + (trailingDeep ? "(?:/.*)?" : "") + "$").test(path);
+}
+function matchesAnyPagePattern(pathname, patterns) {
+  return patterns.length === 0 || patterns.some((pattern) => matchesPagePattern(pathname, pattern));
+}
 
 // src/install.ts
+function personaEnvKey(personaId) {
+  return "NEXT_PUBLIC_FRANKIE_KEY_" + personaId.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+var STANDARD_AGENT_IDS = ["support", "docs"];
+function installAgentIds(personaIds = []) {
+  const custom = [...new Set(personaIds)].filter((id) => /^[a-z0-9][a-z0-9-]*$/.test(id) && !STANDARD_AGENT_IDS.includes(id)).sort();
+  return [...STANDARD_AGENT_IDS, ...custom];
+}
+function installBranch(workspaceId, baseSha, personaId) {
+  return "frankie/install-" + workspaceId + (personaId ? "--" + personaId : "") + "-" + baseSha.slice(0, 8);
+}
+function plainText(value, max = 80) {
+  const text = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/[`<>[\]()*_#|!\\]/g, "").replace(/\s+/g, " ").trim();
+  return text.length > max ? text.slice(0, max - 1).trimEnd() + "\u2026" : text;
+}
+function installTitle(personaLabel) {
+  return personaLabel ? "Install Frankie: " + plainText(personaLabel, 60) : "Install Frankie";
+}
+function matchesInstallBranch(ref, workspaceId, personaId) {
+  const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const mid = personaId ? escape(workspaceId) + "--?" + escape(personaId) : escape(workspaceId);
+  return new RegExp("^frankie/install-" + mid + "-[0-9a-f]{8}$").test(ref);
+}
 function assertNoCommittedFrankieKeys(files) {
   for (const file of files) {
     if (/\bpk_live_[0-9a-f]{24}\b/i.test(file.content) || /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/.test(file.content)) {
@@ -541,8 +733,17 @@ function assertNoCommittedFrankieKeys(files) {
     }
   }
 }
+var ENV_BLOCK_START = "# --- Frankie (managed) ---";
+var ENV_BLOCK_END = "# --- end Frankie ---";
+var LEGACY_ENV_COMMENTS = [
+  "# Public at runtime, but inject it through your deployment environment instead of committing a workspace value.",
+  "# Server only: use the secret from this workspace. Never commit its value.",
+  "# This persona's publishable key. Public at runtime; set it in your deployment environment, don't commit a value."
+];
 function planHostedInstall(input) {
   const { files, workspace } = input;
+  const product = !input.persona;
+  const anonymous = workspace.allowAnonymous;
   const layouts = Object.keys(files).filter((p) => /(?:^|\/)(?:src\/)?app(?:\/\([^/]+\))?\/layout\.tsx$/.test(p));
   const roots = new Set(layouts.map((path) => path.replace(/app\/(?:\([^/]+\)\/)?layout\.tsx$/, "app/")));
   if (roots.size > 1) throw new Error("Multiple Next.js applications found. Run the installer from the intended app with the CLI; Frankie will not guess which app to modify.");
@@ -556,34 +757,70 @@ function planHostedInstall(input) {
   const pkg = JSON.parse(files[pkgPath] ?? "{}");
   if (!pkg.dependencies?.next) throw new Error("The selected app must have Next.js in dependencies.");
   const out = /* @__PURE__ */ new Map();
+  const deletions = [];
   const notes = [];
-  const existingMount = files[layoutPath].includes("FrankieWidgetMount");
   const sourceRoot = appRoot.endsWith("src/app/") ? root + "src/" : root;
   const tokenPath = appRoot + "api/frankie/token/route.ts";
   const healthPath = appRoot + "api/frankie/health/route.ts";
-  const auth = detectAuth(files, sourceRoot, pkg.dependencies);
-  const authStrategy = workspace.allowAnonymous ? "anonymous" : files[tokenPath] ? "existing" : auth?.strategy ?? "unconfigured";
+  const agentsPath = appRoot + "frankie/FrankieAgents.tsx";
+  const chatModulePath = appRoot + "frankie/FrankieChatPage.tsx";
+  const importer = moduleImporter(files, root, sourceRoot);
+  const auth = detectAuth(files, sourceRoot, pkg.dependencies, (module2) => importer(tokenPath, module2));
+  const existingToken = files[tokenPath];
+  const authStrategy = anonymous ? "anonymous" : auth?.strategy ?? (existingToken && !existingToken.includes("AUTH_NOT_CONFIGURED") ? "existing" : "unconfigured");
   const needsAuthSetup = authStrategy === "unconfigured";
-  if (needsAuthSetup) notes.push("No session lookup was detected. Export getCurrentUser from lib/frankie-auth.ts (see the generated token endpoint); until then it answers 501 and chat reports that sign-in is not wired.");
-  if (authStrategy === "supabase") notes.push("Detected Supabase auth: the token endpoint verifies the user's Supabase access token and the widget forwards it automatically. Users must be signed in through Supabase.");
-  pkg.dependencies = { ...pkg.dependencies, "@frankieai/react": pkg.dependencies["@frankieai/react"] ?? "^0.2.1", ...!workspace.allowAnonymous ? { jose: pkg.dependencies.jose ?? "^6.0.11" } : {} };
-  out.set(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-  const authProp = workspace.allowAnonymous ? "" : " getUserToken={getUserToken}";
-  const shared = `import { FrankieProvider, FrankieWidget, FrankieChatPage } from "@frankieai/react";
-import "@frankieai/react/styles.css";
-`;
-  const clientAuthImport = auth?.client && !workspace.allowAnonymous ? `import { ${auth.client.name} } from "@/lib/supabase";
+  if (product && needsAuthSetup) notes.push("No session lookup was detected. Export getCurrentUser from lib/frankie-auth.ts (see the generated token endpoint); until then it answers 501 and chat reports that sign-in is not wired.");
+  if (product && authStrategy === "supabase") notes.push("Detected Supabase auth: the token endpoint verifies the user's Supabase access token and the widget forwards it automatically. Users must be signed in through Supabase.");
+  pkg.dependencies = withDependencies(pkg.dependencies, { "@frankieai/react": "^0.2.1", ...!anonymous ? { jose: "^6.0.11" } : {} });
+  out.set(pkgPath, renderJson(pkg, files[pkgPath]));
+  let manifest = {};
+  try {
+    const parsed = JSON.parse(files[root + "frankie.install.json"] ?? "{}");
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) manifest = parsed;
+  } catch {
+  }
+  const priorChat = manifest.workspaceId === workspace.id && (manifest.chatPath === "/chat" || manifest.chatPath === "/frankie/chat") ? manifest.chatPath : void 0;
+  const chatPath = priorChat ?? (files[integrationAppRoot + "chat/page.tsx"] ? "/frankie/chat" : "/chat");
+  let legacyChat = false;
+  for (const path of Object.keys(files).sort()) {
+    if (!path.startsWith(appRoot)) continue;
+    const legacy = path.match(/(?:^|\/)frankie\/(?:FrankieWidgetMount|FrankieSetupChat)\.tsx$/);
+    if (legacy) {
+      const exportsChat = /\bWorkspaceChatPage\b/.test(files[path]);
+      legacyChat ||= exportsChat;
+      out.set(path, `// Frankie now mounts every agent from FrankieAgents in the root layout.
+// This module stays so existing imports keep working; it renders nothing.
+export function FrankieWidgetMount() {
+  return null;
+}
+${exportsChat ? `export { WorkspaceChatPage } from "${relativeImport(path, chatModulePath.slice(0, -4))}";
+` : ""}`);
+    }
+    if (/(?:^|\/)frankie\/FrankieWidget\.[a-z0-9][a-z0-9-]*\.tsx$/.test(path)) deletions.push(path);
+  }
+  const clientAuth = anonymous ? void 0 : auth?.client;
+  const clientAuthImport = clientAuth ? `import { ${clientAuth.name} } from "${importer(agentsPath, "lib/supabase")}";
 ` : "";
-  const getToken = workspace.allowAnonymous ? "" : auth?.client ? `
-async function getUserToken() {
-  const session = (await ${auth.client.name}?.auth.getSession())?.data.session;
-  if (!session?.access_token) return undefined;
-  const response = await fetch("/api/frankie/token", { method: "POST", headers: { Authorization: \`Bearer \${session.access_token}\` } });
+  const tokenHelpers = anonymous ? "" : clientAuth ? `
+async function supabaseToken() {
+  const session = (await ${clientAuth.name}?.auth.getSession())?.data.session;
+  return session?.access_token;
+}
+/** The signed-in user's Frankie token, or undefined when nobody is signed in. */
+export async function getUserToken() {
+  const accessToken = await supabaseToken();
+  if (!accessToken) return undefined;
+  const response = await fetch("/api/frankie/token", { method: "POST", headers: { Authorization: \`Bearer \${accessToken}\` } });
   if (!response.ok) return undefined;
   return ((await response.json()) as { token?: string }).token;
 }
+const optionalUserToken = getUserToken;
+async function productAvailable() {
+  return Boolean(await supabaseToken());
+}
 ` : `
-async function getUserToken() {
+/** The signed-in user's Frankie token; throws the reason chat can't start. */
+export async function getUserToken() {
   const response = await fetch("/api/frankie/token", { method: "POST", credentials: "same-origin" });
   if (response.ok) return ((await response.json()) as { token?: string }).token;
   if (response.status === 401) throw new Error("Sign in to this app to use chat.");
@@ -591,65 +828,153 @@ async function getUserToken() {
   if (response.status === 503) throw new Error("Chat is not configured on the server yet (FRANKIE_JWT_SECRET is missing).");
   throw new Error("The chat sign-in endpoint returned " + response.status + ".");
 }
+/** Support and docs agents chat with visitors too: who is signed in, if anyone. */
+async function optionalUserToken() {
+  try {
+    const response = await fetch("/api/frankie/token", { method: "POST", credentials: "same-origin" });
+    return response.ok ? ((await response.json()) as { token?: string }).token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+/** The product agent is for signed-in users. 501/503 still show it, so the widget can say what to fix. */
+async function productAvailable() {
+  try {
+    const response = await fetch("/api/frankie/token", { method: "POST", credentials: "same-origin" });
+    return response.ok || response.status === 501 || response.status === 503;
+  } catch {
+    return false;
+  }
+}
 `;
-  const hostApiHeaders = auth?.client && !workspace.allowAnonymous ? `
-  headers: async () => {
-    const session = (await ${auth.client.name}?.auth.getSession())?.data.session;
+  const hostApiHeaders = clientAuth ? `
+  headers: async (): Promise<Record<string, string>> => {
+    const session = (await ${clientAuth.name}?.auth.getSession())?.data.session;
     return session?.access_token ? { Authorization: \`Bearer \${session.access_token}\` } : {};
   },` : "";
-  const hostApi = `const hostApi = {
+  const hostApi = `export const hostApi = {
   baseUrl: typeof window !== "undefined" ? window.location.origin : "",
-  credentials: "${auth?.client || workspace.allowAnonymous ? "same-origin" : "include"}" as const,${hostApiHeaders}
+  credentials: "${clientAuth || anonymous ? "same-origin" : "include"}" as const,${hostApiHeaders}
 };
 `;
-  const apiProp = " api={hostApi}";
-  let priorChat;
-  try {
-    const previous = JSON.parse(files[root + "frankie.install.json"] ?? "{}");
-    if (previous.workspaceId === workspace.id && ["/chat", "/frankie/chat"].includes(previous.chatPath)) priorChat = previous.chatPath;
-  } catch {
-  }
-  const chatPath = priorChat ?? (files[integrationAppRoot + "chat/page.tsx"] ? "/frankie/chat" : "/chat");
-  if (!priorChat && files[integrationAppRoot + chatPath.slice(1) + "/page.tsx"]) throw new Error("Both /chat and /frankie/chat already exist. Choose a chat route manually.");
-  out.set(root + "frankie.install.json", JSON.stringify({ workspaceId: workspace.id, chatPath }, null, 2) + "\n");
-  if (chatPath !== "/chat") notes.push("Existing /chat preserved. Frankie chat is available at /frankie/chat.");
-  const mount = `"use client";
+  const personaIds = installAgentIds([...input.agents ?? [], ...input.persona ? [input.persona.id] : []]);
+  const agentsModule = `"use client";
+// Generated by Frankie. Every Frankie agent in this app mounts here, once, from
+// the root layout. An agent turns on when its publishable key is set in the
+// deployment environment, and shows on the pages chosen for it in Frankie.
+import { useEffect, useState } from "react";
 import { usePathname } from "next/navigation";
-${shared}${clientAuthImport}${getToken}${hostApi}
-export function FrankieWidgetMount() {
-  const pathname = usePathname();
-  const key = process.env.NEXT_PUBLIC_FRANKIE_KEY;
-  if (!key || pathname === ${JSON.stringify(chatPath)}) return null;
-  return <FrankieProvider publishableKey={key}${authProp}${apiProp}><FrankieWidget /></FrankieProvider>;
+import { FrankieClient, FrankieProvider, FrankieWidget, type PublicWidgetConfig } from "@frankieai/react";
+import "@frankieai/react/styles.css";
+${clientAuthImport}${tokenHelpers}${hostApi}
+type Agent = { id: string; key: string | undefined };
+// Literal process.env reads, so Next.js inlines each key at build time. Where
+// two agents' pages overlap the earlier one wins; the product agent takes
+// every page no other agent claims.
+const PERSONAS: Agent[] = [
+${personaIds.map((id) => `  { id: ${JSON.stringify(id)}, key: process.env.${personaEnvKey(id)} },`).join("\n")}
+];
+const PRODUCT: Agent = { id: "product", key: process.env.NEXT_PUBLIC_FRANKIE_KEY };
+// The full-page chat never gets a floating launcher on top of it.
+const CHAT_PATHS = ["/chat", "/frankie/chat"];
+
+type Loaded = { config: PublicWidgetConfig | undefined; pages: string[] };
+const loading = new Map<string, Promise<Loaded>>();
+function load(key: string): Promise<Loaded> {
+  let pending = loading.get(key);
+  if (!pending) {
+    pending = new FrankieClient({ publishableKey: key })
+      .getConfig()
+      .then((config) => ({ config, pages: (config as { pages?: string[] }).pages ?? [] }))
+      .catch(() => ({ config: undefined, pages: [] }));
+    loading.set(key, pending);
+  }
+  return pending;
 }
+
+function matchesAny(pathname: string, patterns: string[]): boolean {
+  if (!patterns.length) return true;
+  const path = (pathname || "/").split(/[?#]/)[0]!.replace(/(.)\\/+$/, "$1");
+  return patterns.some((pattern) => {
+    const pat = (pattern || "/").replace(/(.)\\/+$/, "$1");
+    const deep = pat.endsWith("/**");
+    const core = (deep ? pat.slice(0, -3) : pat).replace(/[.+^\${}()|[\\]\\\\]/g, "\\\\$&");
+    const body = core.split("**").map((chunk) => chunk.replace(/\\*/g, "[^/]*")).join(".*");
+    return new RegExp("^" + body + (deep ? "(?:/.*)?" : "") + "$").test(path);
+  });
+}
+
+function pick(pathname: string, loaded: Record<string, Loaded>, signedIn: boolean): { agent: Agent; key: string } | undefined {
+  if (CHAT_PATHS.includes(pathname)) return undefined;
+  const live = [...PERSONAS, PRODUCT].flatMap((agent) => (agent.key ? [{ agent, key: agent.key }] : []));
+  // Decide once every agent's pages are known, so one never flashes in before another.
+  if (live.some(({ key }) => !loaded[key])) return undefined;
+  const personas = live.filter(({ agent, key }) => agent !== PRODUCT && loaded[key]!.config);
+  const claimed = personas.find(({ key }) => loaded[key]!.pages.length > 0 && matchesAny(pathname, loaded[key]!.pages));
+  if (claimed) return claimed;
+  const product = live.find(({ agent }) => agent === PRODUCT);
+  if (product && signedIn && matchesAny(pathname, loaded[product.key]!.pages)) return product;
+  return personas.find(({ key }) => loaded[key]!.pages.length === 0);
+}
+
+export function FrankieAgents() {
+  const pathname = usePathname() || "/";
+  const [loaded, setLoaded] = useState<Record<string, Loaded>>({});
+  useEffect(() => {
+    let live = true;
+    for (const { key } of [...PERSONAS, PRODUCT]) {
+      if (key) void load(key).then((result) => { if (live) setLoaded((prev) => ({ ...prev, [key]: result })); });
+    }
+    return () => { live = false; };
+  }, []);
+${anonymous ? `  const signedIn = true;
+` : `  const [signedIn, setSignedIn] = useState(false);
+  useEffect(() => {
+    if (!PRODUCT.key) return;
+    let live = true;
+    void productAvailable().then((ok) => { if (live) setSignedIn(ok); });
+    return () => { live = false; };
+  }, [pathname]);
+`}  const active = pick(pathname, loaded, signedIn);
+  if (!active) return null;
+  return (
+    <FrankieProvider key={active.key} publishableKey={active.key} config={loaded[active.key]?.config}${anonymous ? "" : ` getUserToken={active.agent === PRODUCT ? getUserToken : optionalUserToken}`} api={hostApi}>
+      <FrankieWidget />
+    </FrankieProvider>
+  );
+}
+`;
+  out.set(agentsPath, agentsModule);
+  const rootLayout = files[rootLayoutPath];
+  if (!rootLayout.includes("FrankieAgents")) {
+    const mounted = mountWidget(rootLayout, "FrankieAgents");
+    if (!mounted) throw new Error("The root layout has no safe mount point. Add <FrankieAgents /> inside <body> manually.");
+    out.set(rootLayoutPath, insertImport(mounted, `import { FrankieAgents } from "./frankie/FrankieAgents";`));
+  }
+  if (product || legacyChat) {
+    out.set(chatModulePath, `"use client";
+import { FrankieChatPage } from "@frankieai/react";
+import "@frankieai/react/styles.css";
+import { ${anonymous ? "" : "getUserToken, "}hostApi } from "./FrankieAgents";
+
 export function WorkspaceChatPage() {
   const key = process.env.NEXT_PUBLIC_FRANKIE_KEY;
   if (!key) return <p>Chat is not configured. Set NEXT_PUBLIC_FRANKIE_KEY in your deployment.</p>;
-  return <FrankieChatPage publishableKey={key}${authProp}${apiProp} />;
+  return <FrankieChatPage publishableKey={key}${anonymous ? "" : " getUserToken={getUserToken}"} api={hostApi} />;
 }
-`;
-  const moduleName = existingMount ? "FrankieSetupChat" : "FrankieWidgetMount";
-  out.set(integrationAppRoot + "frankie/" + moduleName + ".tsx", mount);
-  if (!existingMount) {
-    const layout = files[layoutPath];
-    const importLine = `import { FrankieWidgetMount } from "./frankie/FrankieWidgetMount";
-`;
-    const withImport = /^["']use client["'];/.test(layout) ? layout.replace(/^(['"]use client['"];)/, "$1\n" + importLine) : importLine + layout;
-    if (withImport.includes("</body>")) {
-      out.set(layoutPath, withImport.replace("</body>", "  <FrankieWidgetMount />\n</body>"));
-    } else if (withImport.includes("</main>")) {
-      out.set(layoutPath, withImport.replace("</main>", "  <FrankieWidgetMount />\n</main>"));
-    } else if (withImport.includes("{children}")) {
-      out.set(layoutPath, withImport.replace("{children}", "{children}<FrankieWidgetMount />"));
-    } else {
-      throw new Error("The selected layout has no safe widget mount point. Add FrankieWidgetMount manually.");
-    }
+`);
   }
-  const pageImport = chatPath === "/chat" ? "../frankie/" : "../../frankie/";
-  out.set(integrationAppRoot + chatPath.slice(1) + "/page.tsx", `import { WorkspaceChatPage } from "${pageImport}${moduleName}";
+  if (product) {
+    if (!priorChat && files[integrationAppRoot + chatPath.slice(1) + "/page.tsx"]) throw new Error("Both /chat and /frankie/chat already exist. Choose a chat route manually.");
+    const pagePath = integrationAppRoot + chatPath.slice(1) + "/page.tsx";
+    out.set(pagePath, `import { WorkspaceChatPage } from "${relativeImport(pagePath, chatModulePath.slice(0, -4))}";
 export default WorkspaceChatPage;
 `);
-  if (!workspace.allowAnonymous && !files[tokenPath]) {
+    const { personas: _legacyPersonas, ...kept2 } = manifest;
+    out.set(root + "frankie.install.json", JSON.stringify({ ...kept2, workspaceId: workspace.id, chatPath }, null, 2) + "\n");
+    if (chatPath !== "/chat") notes.push("Existing /chat preserved. Frankie chat is available at /frankie/chat.");
+  }
+  if (product && !anonymous && !files[tokenPath]) {
     const lookup = auth?.lookup ?? `// Frankie could not find your session lookup. Export it from lib/frankie-auth.ts:
 //   export async function getCurrentUser(): Promise<{ id: string; name?: string; email?: string } | null>
 // then import it here in place of this stub.
@@ -677,8 +1002,7 @@ export async function POST(${auth?.handlerParam ?? ""}) {
 }
 `);
   }
-  if (!files[healthPath]) {
-    out.set(healthPath, `import { NextResponse } from "next/server";
+  out.set(healthPath, `import { NextResponse } from "next/server";
 
 export const dynamic = "force-dynamic";
 
@@ -687,88 +1011,128 @@ export async function GET() {
     {
       frankie: true,
       publishableKey: Boolean(process.env.NEXT_PUBLIC_FRANKIE_KEY),
+      agents: {
+${personaIds.map((id) => `        ${JSON.stringify(id)}: Boolean(process.env.${personaEnvKey(id)}),`).join("\n")}
+      },
       jwtSecret: Boolean(process.env.FRANKIE_JWT_SECRET),
       auth: ${JSON.stringify(authStrategy)},
-      chatPath: ${JSON.stringify(chatPath)},
     },
     { headers: { "cache-control": "no-store", "access-control-allow-origin": "*" } },
   );
 }
 `);
-  }
-  let doc;
-  for (const [path, content] of Object.entries(files)) {
-    if (!/(?:openapi|swagger)[^/]*\.json$/i.test(path)) continue;
-    try {
-      const parsed = JSON.parse(content);
-      if (parsed.openapi && parsed.paths) {
-        doc = parsed;
-        break;
+  let operationCount = 0;
+  const specPath = root + "public/frankie.openapi.json";
+  if (product) {
+    let doc;
+    for (const [path, content] of Object.entries(files)) {
+      if (!/(?:openapi|swagger)[^/]*\.json$/i.test(path)) continue;
+      try {
+        const parsed = JSON.parse(content);
+        if (parsed.openapi && parsed.paths) {
+          doc = parsed;
+          break;
+        }
+      } catch {
       }
-    } catch {
     }
-  }
-  const middlewareMatchers = nextMiddlewareMatchers(files, sourceRoot, root);
-  const paths = {};
-  let withheld = 0;
-  for (const [file, content] of Object.entries(files)) {
-    if (/\.(test|spec)\.[tj]sx?$/.test(file)) continue;
-    const nextRoute = file.match(/(?:^|\/)app(\/.*)\/route\.[tj]s$/);
-    if (nextRoute) {
-      const path = nextRoute[1].replace(/\/\([^/]+\)/g, "").replace(/\[([^\]]+)\]/g, "{$1}");
-      if (path.includes("...") || /\/(?:auth|frankie)(?:\/|$)/.test(path)) continue;
-      const guarded = matchesAnyMatcher(middlewareMatchers, path) || IN_HANDLER_AUTH_GUARD.test(content);
-      for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE"]) {
-        if (new RegExp("export\\s+(?:(?:async\\s+)?function\\s+" + method + "\\b|(?:const|let)\\s+" + method + "\\s*=)").test(content)) {
-          if (!addInstallOperation(paths, method, path, file, guarded)) withheld += 1;
+    const middlewareMatchers = nextMiddlewareMatchers(files, sourceRoot, root);
+    const paths = {};
+    let withheld = 0;
+    for (const [file, content] of Object.entries(files)) {
+      if (/\.(test|spec)\.[tj]sx?$/.test(file)) continue;
+      const nextRoute = file.match(/(?:^|\/)app(\/.*)\/route\.[tj]s$/);
+      if (nextRoute) {
+        const path = nextRoute[1].replace(/\/\([^/]+\)/g, "").replace(/\[([^\]]+)\]/g, "{$1}");
+        if (path.includes("...") || /\/(?:auth|frankie)(?:\/|$)/.test(path)) continue;
+        const guarded = matchesAnyMatcher(middlewareMatchers, path) || IN_HANDLER_AUTH_GUARD.test(content);
+        for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE"]) {
+          if (new RegExp("export\\s+(?:(?:async\\s+)?function\\s+" + method + "\\b|(?:const|let)\\s+" + method + "\\s*=)").test(content)) {
+            if (!addInstallOperation(paths, method, path, file, guarded)) withheld += 1;
+          }
         }
+      } else if (/\.[tj]s$/.test(file) && /(?:routes?|api)\//.test(file)) {
+        for (const match of content.matchAll(/\b(?:app|router|fastify)\.(get|post|put|patch|delete)(?:\s*<[^;]{1,1600}?>)?\s*\(\s*["']([^"']+)["'](\s*,\s*[A-Za-z_$][\w$]*\s*,)?/g))
+          if (!addInstallOperation(paths, match[1].toUpperCase(), match[2].replace(/:([A-Za-z0-9_]+)/g, "{$1}"), file, Boolean(match[3]))) withheld += 1;
       }
-    } else if (/\.[tj]s$/.test(file) && /(?:routes?|api)\//.test(file)) {
-      for (const match of content.matchAll(/\b(?:app|router|fastify)\.(get|post|put|patch|delete)(?:\s*<[^;]{1,1600}?>)?\s*\(\s*["']([^"']+)["'](\s*,\s*[A-Za-z_$][\w$]*\s*,)?/g))
-        if (!addInstallOperation(paths, match[1].toUpperCase(), match[2].replace(/:([A-Za-z0-9_]+)/g, "{$1}"), file, Boolean(match[3]))) withheld += 1;
     }
+    doc ??= { openapi: "3.0.3", info: { title: workspace.name + " API", version: "1.0.0", description: "Generated route inventory. Review schemas, authorization, and the deployed origin before enabling tools." }, paths };
+    for (const [path, item] of Object.entries(paths)) doc.paths[path] = { ...item, ...doc.paths[path] };
+    operationCount = Object.values(doc.paths).reduce((n, item) => n + Object.keys(item).filter((m) => /^(get|post|put|patch|delete)$/.test(m)).length, 0);
+    out.set(specPath, JSON.stringify(doc, null, 2) + "\n");
+    if (!operationCount) notes.push("No supported API routes detected. The OpenAPI draft has no operations; add the real schema before connecting tools.");
+    if (withheld) notes.push(`Withheld ${withheld} newly discovered write operation(s) with no detected authorization guard (no Express/Fastify middleware argument, Next.js middleware.ts matcher covering the route, or in-handler auth check). Add them to the spec yourself once they're protected.`);
+    notes.push("Generated OpenAPI includes read and write routes. Review schemas before approving tools; new connections still default to GET-only access.");
+    notes.push("No public spec endpoint is required: Frankie connects this committed spec on install and reads later changes from your repository through the GitHub connection.");
+    notes.push("The token endpoint issues a signed user JWT, but your product API must validate it and enforce user/resource permissions before exposing tools.");
+  } else {
+    const envKey = personaEnvKey(input.persona.id);
+    notes.push(`${plainText(input.persona.label, 60)} turns on when ${envKey} is set in each frontend environment. Its pages come from Frankie at runtime, so changing them later needs no new pull request.`);
   }
-  doc ??= { openapi: "3.0.3", info: { title: workspace.name + " API", version: "1.0.0", description: "Generated route inventory. Review schemas, authorization, and the deployed origin before enabling tools." }, paths };
-  for (const [path, item] of Object.entries(paths)) doc.paths[path] = { ...item, ...doc.paths[path] };
-  const specPath = root + "public/frankie.openapi.json";
-  const operationCount = Object.values(doc.paths).reduce((n, item) => n + Object.keys(item).filter((m) => /^(get|post|put|patch|delete)$/.test(m)).length, 0);
-  out.set(specPath, JSON.stringify(doc, null, 2) + "\n");
-  if (!operationCount) notes.push("No supported API routes detected. The OpenAPI draft has no operations; add the real schema before connecting tools.");
-  if (withheld) notes.push(`Withheld ${withheld} newly discovered write operation(s) with no detected authorization guard (no Express/Fastify middleware argument, Next.js middleware.ts matcher covering the route, or in-handler auth check). Add them to the spec yourself once they're protected.`);
-  notes.push("Generated OpenAPI includes read and write routes. Review schemas before approving tools; new connections still default to GET-only access.");
-  notes.push("No public spec endpoint is required: Frankie connects this committed spec on install and reads later changes from your repository through the GitHub connection.");
-  notes.push("The token endpoint issues a signed user JWT, but your product API must validate it and enforce user/resource permissions before exposing tools.");
   const envPath = root + ".env.example";
-  const env = (files[envPath] ?? "").replace(/^NEXT_PUBLIC_FRANKIE_KEY=.*\n?/gm, "").replace(/^FRANKIE_JWT_SECRET=.*\n?/gm, "").trimEnd();
-  out.set(envPath, env + "\n# Public at runtime, but inject it through your deployment environment instead of committing a workspace value.\nNEXT_PUBLIC_FRANKIE_KEY=\n" + (workspace.allowAnonymous ? "" : "# Server only: use the secret from this workspace. Never commit its value.\nFRANKIE_JWT_SECRET=\n"));
-  out.set(root + "FRANKIE_SETUP.md", `# Frankie setup
+  const keyLine = /^(?:NEXT_PUBLIC_FRANKIE_KEY(?:_[A-Z0-9_]+)?|FRANKIE_JWT_SECRET)=.*$/;
+  const kept = [];
+  let inBlock = false;
+  for (const line of (files[envPath] ?? "").split("\n")) {
+    if (line === ENV_BLOCK_START) {
+      inBlock = true;
+      continue;
+    }
+    if (line === ENV_BLOCK_END) {
+      inBlock = false;
+      continue;
+    }
+    if (inBlock || keyLine.test(line) || LEGACY_ENV_COMMENTS.includes(line)) continue;
+    kept.push(line);
+  }
+  const before = kept.join("\n").trimEnd();
+  const block = [
+    ENV_BLOCK_START,
+    "# Publishable keys are public at runtime, but set them in your deployment environment instead of committing values. An agent stays off until its key is set.",
+    "NEXT_PUBLIC_FRANKIE_KEY=",
+    ...personaIds.map((id) => personaEnvKey(id) + "="),
+    ...anonymous ? [] : ["# Server only: the secret from your Frankie workspace. Never commit its value or expose it to the browser.", "FRANKIE_JWT_SECRET="],
+    ENV_BLOCK_END
+  ].join("\n");
+  out.set(envPath, (before ? before + "\n\n" : "") + block + "\n");
+  if (product) {
+    const keys = ["NEXT_PUBLIC_FRANKIE_KEY", ...personaIds.map(personaEnvKey)];
+    out.set(root + "FRANKIE_SETUP.md", `# Frankie setup
 
-Workspace: ${workspace.name}
+Workspace: ${plainText(workspace.name)}
 
-1. Copy NEXT_PUBLIC_FRANKIE_KEY from Frankie \u2192 Workspace \u2192 Developer details into the frontend deployment environment. Frankie deliberately leaves the value blank in this PR.
-${workspace.allowAnonymous ? "" : "2. Add FRANKIE_JWT_SECRET from this workspace to the server hosting /api/frankie/token. Never commit the value.\n"}3. Run your package manager and commit the updated lockfile (for pnpm: pnpm install --lockfile-only). The remote GitHub installer cannot safely synthesize a lockfile.
-4. Nothing to expose: this PR commits your spec to the repository, Frankie connects it for you on install, and later spec changes are read from your repository through the GitHub connection \u2014 no public spec endpoint or middleware bypass is required.
+1. Copy NEXT_PUBLIC_FRANKIE_KEY from Frankie \u2192 Workspace \u2192 Developer details into every frontend deployment environment (Preview and Production). Frankie deliberately leaves the value blank in this PR.
+${anonymous ? "" : "2. Add FRANKIE_JWT_SECRET from this workspace to the server hosting /api/frankie/token only. Never commit the value or expose it to the browser.\n"}3. Run your package manager and commit the updated lockfile (for pnpm: pnpm install --lockfile-only). The remote GitHub installer cannot safely synthesize a lockfile.
+4. Nothing to expose: this PR commits your spec to the repository, Frankie connects it for you on install, and later spec changes are read from your repository through the GitHub connection.
 5. Open ${chatPath}. It is created inside the detected authenticated dashboard group when one exists; add its link to the host sidebar during review.
-6. In Frankie \u2192 Tools & MCP, approve the operations you want and choose access limits (the spec is already connected from this PR; it includes read and write routes). After merging later spec changes, use GitHub integration \u2192 Refresh Frankie from merged spec.
+6. In Frankie \u2192 Tools & MCP, approve the operations you want and choose access limits. After merging later spec changes, use GitHub integration \u2192 Refresh Frankie from merged spec.
 7. Forwarding sends the Frankie-signed JWT. Your API must validate it and enforce user/resource permissions. It is not automatically interchangeable with a Firebase or OAuth access token.
-8. Add NEXT_PUBLIC_FRANKIE_KEY to every frontend deployment environment (Preview and Production). ${workspace.allowAnonymous ? "" : "Add FRANKIE_JWT_SECRET only to the server environment running /api/frankie/token; never expose it to the browser.\n"}9. Review conversations in Workspace \u2192 Chat sessions.
+
+## More agents
+
+Every Frankie agent mounts from \`frankie/FrankieAgents.tsx\` in the root layout. To turn on another agent (Support, Docs), set its key in the deployment \u2014 no code change:
+
+${keys.map((key) => "- `" + key + "`").join("\n")}
+
+Each agent shows on the pages chosen for it in Frankie; those are read at runtime.
 
 ## Remaining setup
 
 ${notes.map((n) => "- " + n).join("\n")}
 `);
-  const planned = [...out].map(([path, content]) => ({ path, content }));
+  }
+  const planned = [...out].filter(([path, content]) => files[path] !== content).map(([path, content]) => ({ path, content }));
   assertNoCommittedFrankieKeys(planned);
-  return { files: planned, root, chatPath, specPath, operationCount, needsAuthSetup, authStrategy, notes };
+  return { files: planned, deletions, root, chatPath, specPath, operationCount, needsAuthSetup, authStrategy, notes };
 }
 var GET_CURRENT_USER = /export\s+(?:async\s+function\s+getCurrentUser\b|(?:const|let)\s+getCurrentUser\b|\{[^}]*\bgetCurrentUser\b[^}]*\})/;
 var CUSTOM_AUTH_MODULES = ["lib/frankie-auth", "frankie/auth", "lib/auth", "lib/session", "lib/current-user", "lib/user", "server/auth", "auth"];
-function detectAuth(files, sourceRoot, deps) {
+function detectAuth(files, sourceRoot, deps, ref) {
   for (const module2 of CUSTOM_AUTH_MODULES) {
     for (const ext of [".ts", ".tsx", ".js"]) {
       const source = files[sourceRoot + module2 + ext];
       if (source && GET_CURRENT_USER.test(source)) {
-        return { strategy: "custom", lookup: `import { getCurrentUser } from "@/${module2}";
+        return { strategy: "custom", lookup: `import { getCurrentUser } from "${ref(module2)}";
 ` };
       }
     }
@@ -777,8 +1141,8 @@ function detectAuth(files, sourceRoot, deps) {
     return {
       strategy: "firebase",
       lookup: `import { cookies } from "next/headers";
-import { getAdminAuth } from "@/lib/firebase-admin";
-import { SESSION_COOKIE } from "@/lib/session";
+import { getAdminAuth } from "${ref("lib/firebase-admin")}";
+import { SESSION_COOKIE } from "${ref("lib/session")}";
 async function getCurrentUser() {
   const cookie = (await cookies()).get(SESSION_COOKIE)?.value;
   if (!cookie) return null;
@@ -792,7 +1156,7 @@ async function getCurrentUser() {
   if (authFile?.includes("NextAuth") && /export\s+(?:const|let)\s*\{[^}]*\bauth\b/.test(authFile)) {
     return {
       strategy: "nextauth",
-      lookup: `import { auth } from "@/auth";
+      lookup: `import { auth } from "${ref("auth")}";
 async function getCurrentUser() {
   const session = await auth();
   const user = session?.user as { id?: string; name?: string | null; email?: string | null } | undefined;
@@ -870,6 +1234,107 @@ function matchesAnyMatcher(matchers, path) {
     return new RegExp(`^${regexBody}$`).test(path);
   });
 }
+function insertImport(source, importLine) {
+  const skip = [/^\s+/, /^\/\/[^\n]*/, /^\/\*[\s\S]*?\*\//];
+  const keep = [/^["'][^"'\n]*["'][ \t]*;?/, /^import\s+(?:type\s+)?(?:[^"'`;]*?\sfrom\s*)?["'][^"'\n]+["'][ \t]*;?/];
+  let at = 0;
+  let afterPrologue = 0;
+  let afterComments = 0;
+  for (; ; ) {
+    const rest = source.slice(at);
+    const skipped = skip.map((pattern) => rest.match(pattern)?.[0]).find((hit) => hit);
+    if (skipped) {
+      at += skipped.length;
+      if (!/^\s+$/.test(skipped) && afterPrologue === 0) afterComments = at;
+      continue;
+    }
+    const kept = keep.map((pattern) => rest.match(pattern)?.[0]).find((hit) => hit);
+    if (!kept) break;
+    at += kept.length;
+    afterPrologue = at;
+  }
+  const end = afterPrologue || afterComments;
+  if (end === 0) return `${importLine}
+
+${source}`;
+  return `${source.slice(0, end)}
+${importLine}${source.slice(end)}`;
+}
+function mountWidget(layout, component = "FrankieWidgetMount") {
+  const mount = `<${component} />`;
+  for (const tag of ["</body>", "</main>"]) {
+    const at = layout.indexOf(tag);
+    if (at === -1) continue;
+    const lineStart = layout.lastIndexOf("\n", at) + 1;
+    const lead = layout.slice(lineStart, at);
+    if (!/^[ \t]*$/.test(lead)) return `${layout.slice(0, at)}${mount}${layout.slice(at)}`;
+    const unit = lead.includes("	") ? "	" : "  ";
+    return `${layout.slice(0, lineStart)}${lead}${unit}${mount}
+${layout.slice(lineStart)}`;
+  }
+  return layout.includes("{children}") ? layout.replace("{children}", `{children}${mount}`) : void 0;
+}
+function withDependencies(current, added) {
+  const existing = current ?? {};
+  const merged = { ...existing };
+  for (const [name, range] of Object.entries(added)) merged[name] ??= range;
+  const names = Object.keys(existing);
+  const sorted = [...names].sort((a, b) => a.localeCompare(b, "en"));
+  if (names.some((name, index) => name !== sorted[index])) return merged;
+  return Object.fromEntries(Object.keys(merged).sort((a, b) => a.localeCompare(b, "en")).map((name) => [name, merged[name]]));
+}
+function renderJson(value, original) {
+  const indent = original?.match(/^([ \t]+)"/m)?.[1] ?? "  ";
+  const text = JSON.stringify(value, null, indent);
+  return original === void 0 || original.endsWith("\n") ? `${text}
+` : text;
+}
+function moduleImporter(files, root, sourceRoot) {
+  const tsconfig = files[root + "tsconfig.json"];
+  if (tsconfig === void 0) return (_from, module2) => `@/${module2}`;
+  const alias = aliasFor(tsconfig, root, sourceRoot);
+  if (alias !== void 0) return (_from, module2) => `${alias}${module2}`;
+  return (from, module2) => relativeImport(from, sourceRoot + module2);
+}
+function aliasFor(tsconfig, root, sourceRoot) {
+  let options;
+  try {
+    const parsed = JSON.parse(tsconfig.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "").replace(/,(\s*[}\]])/g, "$1"));
+    options = parsed.compilerOptions;
+  } catch {
+    return void 0;
+  }
+  const paths = options?.paths;
+  if (!paths || typeof paths !== "object") return void 0;
+  const baseUrl = typeof options?.baseUrl === "string" ? options.baseUrl : ".";
+  const target = normalizePath(sourceRoot);
+  for (const [pattern, targets] of Object.entries(paths)) {
+    if (!pattern.endsWith("/*") || !Array.isArray(targets)) continue;
+    for (const entry of targets) {
+      if (typeof entry !== "string" || !entry.endsWith("/*")) continue;
+      if (normalizePath(`${root}${baseUrl}/${entry.slice(0, -1)}`) === target) return pattern.slice(0, -1);
+    }
+  }
+  return void 0;
+}
+function normalizePath(path) {
+  const out = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") out.pop();
+    else out.push(part);
+  }
+  return out.join("/") + "/";
+}
+function relativeImport(fromFile, module2) {
+  const from = normalizePath(fromFile.slice(0, fromFile.lastIndexOf("/") + 1)).split("/").filter(Boolean);
+  const to = module2.split("/").filter((part) => part !== "" && part !== ".");
+  let common = 0;
+  while (common < from.length && common < to.length && from[common] === to[common]) common += 1;
+  const up = from.length - common;
+  const rel = [...Array(up).fill(".."), ...to.slice(common)].join("/");
+  return up === 0 ? `./${rel}` : rel;
+}
 
 // src/sdk-updates.ts
 function sdkUpdateWorkflow(mode) {
@@ -1109,9 +1574,147 @@ function compareApiDocuments(before, after) {
     unchangedIds: [...next].filter(([key, value]) => old.get(key)?.fingerprint === value.fingerprint).map(([, value]) => value.id)
   };
 }
+
+// src/theme-infer.ts
+var hex2 = (value) => Math.round(Math.min(255, Math.max(0, value))).toString(16).padStart(2, "0");
+var toHex = (r, g, b) => "#" + hex2(r) + hex2(g) + hex2(b);
+function hslToHex(h, s, l) {
+  const sat = s / 100, light = l / 100;
+  const k = (n) => (n + h / 30) % 12;
+  const a = sat * Math.min(light, 1 - light);
+  const f = (n) => light - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return toHex(f(0) * 255, f(8) * 255, f(4) * 255);
+}
+function oklchToHex(l, c, hDeg) {
+  const h = hDeg * Math.PI / 180;
+  const a = c * Math.cos(h), b = c * Math.sin(h);
+  const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  const linear = [
+    4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+    -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+    -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_
+  ];
+  const gamma = (x) => (x <= 31308e-7 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055) * 255;
+  return toHex(gamma(linear[0]), gamma(linear[1]), gamma(linear[2]));
+}
+var NUMBER = String.raw`-?\d*\.?\d+`;
+var parts = (body) => body.replace(/\/.*$/, "").split(/[\s,]+/).filter(Boolean);
+function normalizeColor(raw) {
+  const value = raw.trim().replace(/\s*!important$/, "").toLowerCase();
+  let match = value.match(/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/);
+  if (match) {
+    const digits = match[1];
+    return digits.length <= 4 ? "#" + [...digits.slice(0, 3)].map((d) => d + d).join("") : "#" + digits.slice(0, 6);
+  }
+  match = value.match(/^rgba?\(([^)]*)\)$/);
+  if (match) {
+    const [r, g, b] = parts(match[1]).map((part) => part.endsWith("%") ? parseFloat(part) * 2.55 : parseFloat(part));
+    return [r, g, b].every((n) => Number.isFinite(n)) ? toHex(r, g, b) : void 0;
+  }
+  match = value.match(/^hsla?\(([^)]*)\)$/) ?? value.match(new RegExp(`^(${NUMBER}(?:deg)?\\s+${NUMBER}%\\s+${NUMBER}%)$`));
+  if (match) {
+    const [h, s, l] = parts(match[1]).map((part) => parseFloat(part));
+    return [h, s, l].every((n) => Number.isFinite(n)) ? hslToHex(h, s, l) : void 0;
+  }
+  match = value.match(/^oklch\(([^)]*)\)$/);
+  if (match) {
+    const [lRaw, cRaw, hRaw] = parts(match[1]);
+    const l = lRaw?.endsWith("%") ? parseFloat(lRaw) / 100 : parseFloat(lRaw ?? "");
+    const c = cRaw?.endsWith("%") ? parseFloat(cRaw) / 100 * 0.4 : parseFloat(cRaw ?? "");
+    const h = hRaw === void 0 || hRaw === "none" ? 0 : parseFloat(hRaw);
+    return [l, c, h].every((n) => Number.isFinite(n)) ? oklchToHex(l, c, h) : void 0;
+  }
+  return void 0;
+}
+function rootVariables(css) {
+  const vars = /* @__PURE__ */ new Map();
+  const source = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const blocks = /([^{}]*)\{([^{}]*)\}/g;
+  for (let block = blocks.exec(source); block; block = blocks.exec(source)) {
+    const selector = block[1].split(";").pop().trim();
+    if (!/(?:^|[\s,]):root\b(?![^,]*\.dark)|^@theme\b/.test(selector) || /\.dark|\[data-theme/.test(selector)) continue;
+    for (const declaration of block[2].split(";")) {
+      const found = declaration.match(/^\s*(--[\w-]+)\s*:\s*([\s\S]+?)\s*$/);
+      if (found && !vars.has(found[1])) vars.set(found[1], found[2]);
+    }
+  }
+  return vars;
+}
+function resolve(value, vars, depth = 0) {
+  if (depth > 4) return void 0;
+  const reference = value.match(/^(?:(hsla?|oklch|rgba?)\(\s*)?var\(\s*(--[\w-]+)\s*(?:,[^)]*)?\)\s*\)?$/i);
+  if (!reference) return normalizeColor(value);
+  const inner = vars.get(reference[2]);
+  if (!inner) return void 0;
+  const wrapper = reference[1]?.toLowerCase();
+  return wrapper && !/^\s*(?:#|[a-z]+\()/i.test(inner) ? normalizeColor(wrapper + "(" + inner + ")") : resolve(inner, vars, depth + 1);
+}
+function radiusOption(value) {
+  const match = value.trim().match(/^(\d*\.?\d+)(rem|px)?$/);
+  if (!match) return void 0;
+  const rem = match[2] === "px" ? parseFloat(match[1]) / 16 : parseFloat(match[1]);
+  return rem < 0.525 ? "0.35" : rem < 0.9 ? "0.7" : "1.1";
+}
+var CSS_PRIORITY = [/(?:^|\/)app\/globals\.css$/, /(?:^|\/)styles\/globals\.css$/, /globals\.css$/, /\.css$/];
+var PRIMARY_VARS = ["--primary", "--color-primary", "--brand", "--color-brand", "--accent", "--color-accent"];
+function rank(path) {
+  const index = CSS_PRIORITY.findIndex((pattern) => pattern.test(path));
+  return index === -1 ? CSS_PRIORITY.length : index;
+}
+function inferTheme(files, root = "") {
+  const inRoot = (path) => path.startsWith(root) && !/(?:^|\/)(?:node_modules|dist|\.next|vendor|coverage)\//.test(path);
+  const theme = {};
+  const sources = [];
+  const set = (field, value, path) => {
+    if (!value || theme[field]) return;
+    theme[field] = value;
+    sources.push({ field, path });
+  };
+  const cssFiles = Object.keys(files).filter((path) => inRoot(path) && path.endsWith(".css")).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+  const vars = /* @__PURE__ */ new Map();
+  const varPath = /* @__PURE__ */ new Map();
+  for (const path of cssFiles) {
+    for (const [name, value] of rootVariables(files[path])) if (!vars.has(name)) {
+      vars.set(name, value);
+      varPath.set(name, path);
+    }
+  }
+  for (const name of PRIMARY_VARS) if (vars.has(name)) set("primary", resolve(vars.get(name), vars), varPath.get(name));
+  for (const name of ["--background", "--color-background"]) if (vars.has(name)) set("background", resolve(vars.get(name), vars), varPath.get(name));
+  for (const name of ["--foreground", "--color-foreground"]) if (vars.has(name)) set("foreground", resolve(vars.get(name), vars), varPath.get(name));
+  if (vars.has("--radius")) set("radius", radiusOption(vars.get("--radius")), varPath.get("--radius"));
+  for (const path of Object.keys(files).filter((p) => inRoot(p) && /(?:^|\/)tailwind\.config\.[cm]?[jt]s$/.test(p)).sort()) {
+    const source = files[path];
+    for (const key of ["primary", "brand", "accent"]) {
+      const direct = source.match(new RegExp(`["']?${key}["']?\\s*:\\s*["'\`]([^"'\`]+)["'\`]`));
+      const nested = source.match(new RegExp(`["']?${key}["']?\\s*:\\s*\\{[^}]*?DEFAULT\\s*:\\s*["'\`]([^"'\`]+)["'\`]`));
+      const raw = direct?.[1] ?? nested?.[1];
+      if (raw) set("primary", resolve(raw, vars), path);
+    }
+  }
+  for (const path of Object.keys(files).filter((p) => inRoot(p) && /(?:^|\/)app\/(?:\([^/]+\)\/)?layout\.tsx$/.test(p)).sort()) {
+    const raw = files[path].match(/themeColor\s*:\s*(?:\[\s*\{[^}]*?color\s*:\s*)?["'`]([^"'`]+)["'`]/)?.[1];
+    if (raw) set("primary", normalizeColor(raw), path);
+  }
+  for (const path of Object.keys(files).filter((p) => inRoot(p) && /(?:^|\/)(?:manifest\.json|site\.webmanifest|manifest\.webmanifest)$/.test(p)).sort()) {
+    try {
+      const manifest = JSON.parse(files[path]);
+      if (typeof manifest.theme_color === "string") set("primary", normalizeColor(manifest.theme_color), path);
+      if (typeof manifest.background_color === "string") set("background", normalizeColor(manifest.background_color), path);
+    } catch {
+    }
+  }
+  if (!theme.primary) return void 0;
+  return { theme: { ...theme, primary: theme.primary }, sources };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FIREWORKS_MODELS,
+  SKILL_TOOL_NAME,
+  STANDARD_AGENT_IDS,
+  STARTER_PROMPT_ICONS,
   activeSkills,
   agentConfigSchema,
   apiCapabilitySchema,
@@ -1130,14 +1733,32 @@ function compareApiDocuments(before, after) {
   evaluateToolPolicy,
   featuresConfigSchema,
   frankieConfigSchema,
+  inferTheme,
+  insertImport,
+  installAgentIds,
+  installBranch,
+  installTitle,
+  knowledgeBaseSchema,
+  knowledgeSourceSchema,
   limitsConfigSchema,
   matchPath,
+  matchesAnyPagePattern,
+  matchesInstallBranch,
+  matchesPagePattern,
   mcpServerSchema,
   modelChoiceSchema,
   modelConfigSchema,
+  moduleImporter,
+  mountWidget,
+  normalizeColor,
   operationId,
   parseFrankieConfig,
+  personaEnvKey,
+  personaProfileSchema,
+  plainText,
   planHostedInstall,
+  renderJson,
+  resolvePersonaConfig,
   sdkUpdateWorkflow,
   skillSchema,
   starterPromptSchema,
@@ -1146,6 +1767,7 @@ function compareApiDocuments(before, after) {
   toolDescriptions,
   toolPolicySchema,
   validateApiDocument,
-  widgetThemeSchema
+  widgetThemeSchema,
+  withDependencies
 });
 //# sourceMappingURL=index.cjs.map