@frankieai/core 0.2.3 → 0.2.5

package/dist/index.d.cts

@@ -179,10 +179,60 @@ declare const toolPolicySchema: z.ZodObject<{
     deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
     denyByDefault: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * The icons a starter card may use, shared by the dashboard picker and the SDK
+ * so the choices stay in step. Each maps to a concrete icon in the widget.
+ */
+declare const STARTER_PROMPT_ICONS: readonly ["sparkles", "wand", "book", "chat", "chart", "bolt", "music", "mic", "image", "compass", "lightbulb", "file"];
+type StarterPromptIcon = (typeof STARTER_PROMPT_ICONS)[number];
+/**
+ * A starter card shown on the empty chat screen: an icon, a title and short
+ * description the reader sees, and the message that is sent as if they typed it
+ * when they click the card. Configured per workspace in the dashboard's
+ * Appearance tab.
+ */
+declare const starterPromptSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+    icon: z.ZodOptional<z.ZodEnum<{
+        file: "file";
+        sparkles: "sparkles";
+        wand: "wand";
+        book: "book";
+        chat: "chat";
+        chart: "chart";
+        bolt: "bolt";
+        music: "music";
+        mic: "mic";
+        image: "image";
+        compass: "compass";
+        lightbulb: "lightbulb";
+    }>>;
+}, z.core.$strip>;
 declare const agentConfigSchema: z.ZodObject<{
     systemPrompt: z.ZodDefault<z.ZodString>;
     greeting: z.ZodDefault<z.ZodString>;
     suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+        icon: z.ZodOptional<z.ZodEnum<{
+            file: "file";
+            sparkles: "sparkles";
+            wand: "wand";
+            book: "book";
+            chat: "chat";
+            chart: "chart";
+            bolt: "bolt";
+            music: "music";
+            mic: "mic";
+            image: "image";
+            compass: "compass";
+            lightbulb: "lightbulb";
+        }>>;
+    }, z.core.$strip>>>;
     maxTurns: z.ZodDefault<z.ZodNumber>;
     maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
     tools: z.ZodPrefault<z.ZodObject<{
@@ -267,6 +317,25 @@ declare const frankieConfigSchema: z.ZodObject<{
         systemPrompt: z.ZodDefault<z.ZodString>;
         greeting: z.ZodDefault<z.ZodString>;
         suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            message: z.ZodString;
+            icon: z.ZodOptional<z.ZodEnum<{
+                file: "file";
+                sparkles: "sparkles";
+                wand: "wand";
+                book: "book";
+                chat: "chat";
+                chart: "chart";
+                bolt: "bolt";
+                music: "music";
+                mic: "mic";
+                image: "image";
+                compass: "compass";
+                lightbulb: "lightbulb";
+            }>>;
+        }, z.core.$strip>>>;
         maxTurns: z.ZodDefault<z.ZodNumber>;
         maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
         tools: z.ZodPrefault<z.ZodObject<{
@@ -589,6 +658,14 @@ interface CreateSessionResponse {
         anonymous: boolean;
     };
 }
+/** A starter card on the empty chat screen: what the reader sees, and the message clicking it sends. */
+interface StarterPrompt {
+    title: string;
+    description?: string;
+    message: string;
+    /** One of STARTER_PROMPT_ICONS; the widget maps it to a concrete icon. */
+    icon?: string;
+}
 /** The subset of tenant config the widget is allowed to see. */
 interface PublicWidgetConfig {
     tenantId: string;
@@ -600,6 +677,8 @@ interface PublicWidgetConfig {
     };
     greeting: string;
     suggestedPrompts: string[];
+    /** Explicit starter cards (title + description + message). Take precedence over `suggestedPrompts` on the empty screen. Optional so older servers stay compatible. */
+    starterPrompts?: StarterPrompt[];
     theme: WidgetTheme;
     /** Whether the widget may open a session without a host-signed user token. */
     allowAnonymous: boolean;
@@ -658,6 +737,13 @@ interface ToolDecision {
  * also allows every tool on the `acme` server.
  */
 declare function evaluateToolPolicy(toolName: string, policy: ToolPolicy): ToolDecision;
+/**
+ * The agent-harness tool a skill-following agent calls to announce which
+ * reviewed workspace skill it is about to apply. It grants no permissions and
+ * does nothing on its own — it exists so a skill shows up in the transcript like
+ * any other tool call, instead of being followed invisibly.
+ */
+declare const SKILL_TOOL_NAME = "frankie__use_skill";
 /** A short human label for a tool call, for the "Frankie is …" line in the UI. */
 declare function describeTool(toolName: string, input: unknown): string;
 
@@ -724,6 +810,19 @@ declare function toolDescriptions(config: FrankieConfig, toolIds: string[]): Arr
     id: string;
     description: string;
 }>;
+/**
+ * Starter suggestion prompts derived from the workspace's own published,
+ * runnable skills, so an empty chat offers what this assistant can actually do
+ * instead of a blank screen. Each entry is a clean action title ("Generate a
+ * lesson"), optionally with a short subtitle after " — " when the skill's goal
+ * adds real information. The chat empty state shows the title as the card title
+ * and the subtitle beneath it, and sends only the title. Auto-generated skill
+ * names (e.g. "product · generate lesson") and their boilerplate CRUD goals are
+ * cleaned up so the cards read like real suggestions, not internal ids. Used
+ * only when the workspace hasn't authored its own `suggestedPrompts`; deduped
+ * and capped to the config limit (6).
+ */
+declare function suggestedPromptsFromSkills(config: FrankieConfig): string[];
 /**
  * Deterministic starter for the manual editor — not a claim that anything
  * was executed, and not model-generated. Follows the same structure asked of
@@ -766,4 +865,4 @@ declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     unchangedIds: string[];
 };
 
-export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type AuthStrategy, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, FIREWORKS_MODELS, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type HostToolRequest, type HostToolResult, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type ToolResultBody, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, thinkingLevelSchema, toolDescriptions, toolPolicySchema, validateApiDocument, widgetThemeSchema };
+export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type AuthStrategy, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, FIREWORKS_MODELS, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type HostToolRequest, type HostToolResult, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, SKILL_TOOL_NAME, STARTER_PROMPT_ICONS, type StarterPrompt, type StarterPromptIcon, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type ToolResultBody, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, starterPromptSchema, suggestedPromptsFromSkills, thinkingLevelSchema, toolDescriptions, toolPolicySchema, validateApiDocument, widgetThemeSchema };

package/dist/index.d.ts

@@ -179,10 +179,60 @@ declare const toolPolicySchema: z.ZodObject<{
     deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
     denyByDefault: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * The icons a starter card may use, shared by the dashboard picker and the SDK
+ * so the choices stay in step. Each maps to a concrete icon in the widget.
+ */
+declare const STARTER_PROMPT_ICONS: readonly ["sparkles", "wand", "book", "chat", "chart", "bolt", "music", "mic", "image", "compass", "lightbulb", "file"];
+type StarterPromptIcon = (typeof STARTER_PROMPT_ICONS)[number];
+/**
+ * A starter card shown on the empty chat screen: an icon, a title and short
+ * description the reader sees, and the message that is sent as if they typed it
+ * when they click the card. Configured per workspace in the dashboard's
+ * Appearance tab.
+ */
+declare const starterPromptSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+    icon: z.ZodOptional<z.ZodEnum<{
+        file: "file";
+        sparkles: "sparkles";
+        wand: "wand";
+        book: "book";
+        chat: "chat";
+        chart: "chart";
+        bolt: "bolt";
+        music: "music";
+        mic: "mic";
+        image: "image";
+        compass: "compass";
+        lightbulb: "lightbulb";
+    }>>;
+}, z.core.$strip>;
 declare const agentConfigSchema: z.ZodObject<{
     systemPrompt: z.ZodDefault<z.ZodString>;
     greeting: z.ZodDefault<z.ZodString>;
     suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+        icon: z.ZodOptional<z.ZodEnum<{
+            file: "file";
+            sparkles: "sparkles";
+            wand: "wand";
+            book: "book";
+            chat: "chat";
+            chart: "chart";
+            bolt: "bolt";
+            music: "music";
+            mic: "mic";
+            image: "image";
+            compass: "compass";
+            lightbulb: "lightbulb";
+        }>>;
+    }, z.core.$strip>>>;
     maxTurns: z.ZodDefault<z.ZodNumber>;
     maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
     tools: z.ZodPrefault<z.ZodObject<{
@@ -267,6 +317,25 @@ declare const frankieConfigSchema: z.ZodObject<{
         systemPrompt: z.ZodDefault<z.ZodString>;
         greeting: z.ZodDefault<z.ZodString>;
         suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            message: z.ZodString;
+            icon: z.ZodOptional<z.ZodEnum<{
+                file: "file";
+                sparkles: "sparkles";
+                wand: "wand";
+                book: "book";
+                chat: "chat";
+                chart: "chart";
+                bolt: "bolt";
+                music: "music";
+                mic: "mic";
+                image: "image";
+                compass: "compass";
+                lightbulb: "lightbulb";
+            }>>;
+        }, z.core.$strip>>>;
         maxTurns: z.ZodDefault<z.ZodNumber>;
         maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
         tools: z.ZodPrefault<z.ZodObject<{
@@ -589,6 +658,14 @@ interface CreateSessionResponse {
         anonymous: boolean;
     };
 }
+/** A starter card on the empty chat screen: what the reader sees, and the message clicking it sends. */
+interface StarterPrompt {
+    title: string;
+    description?: string;
+    message: string;
+    /** One of STARTER_PROMPT_ICONS; the widget maps it to a concrete icon. */
+    icon?: string;
+}
 /** The subset of tenant config the widget is allowed to see. */
 interface PublicWidgetConfig {
     tenantId: string;
@@ -600,6 +677,8 @@ interface PublicWidgetConfig {
     };
     greeting: string;
     suggestedPrompts: string[];
+    /** Explicit starter cards (title + description + message). Take precedence over `suggestedPrompts` on the empty screen. Optional so older servers stay compatible. */
+    starterPrompts?: StarterPrompt[];
     theme: WidgetTheme;
     /** Whether the widget may open a session without a host-signed user token. */
     allowAnonymous: boolean;
@@ -658,6 +737,13 @@ interface ToolDecision {
  * also allows every tool on the `acme` server.
  */
 declare function evaluateToolPolicy(toolName: string, policy: ToolPolicy): ToolDecision;
+/**
+ * The agent-harness tool a skill-following agent calls to announce which
+ * reviewed workspace skill it is about to apply. It grants no permissions and
+ * does nothing on its own — it exists so a skill shows up in the transcript like
+ * any other tool call, instead of being followed invisibly.
+ */
+declare const SKILL_TOOL_NAME = "frankie__use_skill";
 /** A short human label for a tool call, for the "Frankie is …" line in the UI. */
 declare function describeTool(toolName: string, input: unknown): string;
 
@@ -724,6 +810,19 @@ declare function toolDescriptions(config: FrankieConfig, toolIds: string[]): Arr
     id: string;
     description: string;
 }>;
+/**
+ * Starter suggestion prompts derived from the workspace's own published,
+ * runnable skills, so an empty chat offers what this assistant can actually do
+ * instead of a blank screen. Each entry is a clean action title ("Generate a
+ * lesson"), optionally with a short subtitle after " — " when the skill's goal
+ * adds real information. The chat empty state shows the title as the card title
+ * and the subtitle beneath it, and sends only the title. Auto-generated skill
+ * names (e.g. "product · generate lesson") and their boilerplate CRUD goals are
+ * cleaned up so the cards read like real suggestions, not internal ids. Used
+ * only when the workspace hasn't authored its own `suggestedPrompts`; deduped
+ * and capped to the config limit (6).
+ */
+declare function suggestedPromptsFromSkills(config: FrankieConfig): string[];
 /**
  * Deterministic starter for the manual editor — not a claim that anything
  * was executed, and not model-generated. Follows the same structure asked of
@@ -766,4 +865,4 @@ declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     unchangedIds: string[];
 };
 
-export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type AuthStrategy, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, FIREWORKS_MODELS, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type HostToolRequest, type HostToolResult, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type ToolResultBody, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, thinkingLevelSchema, toolDescriptions, toolPolicySchema, validateApiDocument, widgetThemeSchema };
+export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type AuthStrategy, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, FIREWORKS_MODELS, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type HostToolRequest, type HostToolResult, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, SKILL_TOOL_NAME, STARTER_PROMPT_ICONS, type StarterPrompt, type StarterPromptIcon, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type ToolResultBody, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, starterPromptSchema, suggestedPromptsFromSkills, thinkingLevelSchema, toolDescriptions, toolPolicySchema, validateApiDocument, widgetThemeSchema };

package/dist/index.js

@@ -26,12 +26,24 @@ 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 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);
@@ -82,6 +94,36 @@ function toolDescriptions(config, toolIds) {
   }
   return toolIds.map((id) => ({ id, description: found.get(id) ?? id }));
 }
+function suggestedPromptsFromSkills(config) {
+  const seen = /* @__PURE__ */ new Set();
+  const prompts = [];
+  for (const skill of activeSkills(config)) {
+    const title = cleanSkillName(skill.name);
+    if (!title) continue;
+    const key = title.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const detail = summarizeGoal(skill.goal, title);
+    prompts.push(detail ? `${title} \u2014 ${detail}` : title);
+    if (prompts.length >= 6) break;
+  }
+  return prompts;
+}
+function cleanSkillName(name) {
+  const trimmed = name.trim();
+  const withoutSource = trimmed.replace(/^[^·/:]{1,40}?\s*[·/:]\s*/, "");
+  const cleaned = (withoutSource || trimmed).replace(/[·/_]+/g, " ").replace(/\s+/g, " ").trim();
+  return cleaned ? cleaned.charAt(0).toUpperCase() + cleaned.slice(1) : "";
+}
+function summarizeGoal(goal, title) {
+  let cleaned = goal.trim().replace(/^use this(?: skill)?(?: when (?:the user (?:asks?(?: you)?(?: to| for| about)?|wants?(?: to)?|needs?(?: to)?)|you (?:need|want) to)| to)\s+/i, "").replace(/\s+/g, " ").replace(/[.\s]+$/, "");
+  const restatement = cleaned.match(/^.{1,40}?\s+[—–-]\s+(.+)$/);
+  if (restatement) cleaned = restatement[1];
+  if (/^(listing|creating|reading|updating|managing)\b/i.test(cleaned) || /^(create|read|update|delete|list|manage),/i.test(cleaned)) return "";
+  if (!cleaned || cleaned.toLowerCase() === title.toLowerCase()) return "";
+  const capped = cleaned.length > 80 ? cleaned.slice(0, 80).replace(/\s+\S*$/, "") + "\u2026" : cleaned;
+  return capped.charAt(0).toUpperCase() + capped.slice(1);
+}
 function draftSkill(goal, tools) {
   return [
     `Use this when: ${goal}`,
@@ -334,12 +376,39 @@ var toolPolicySchema = z2.object({
    */
   denyByDefault: z2.boolean().default(true)
 });
+var STARTER_PROMPT_ICONS = [
+  "sparkles",
+  "wand",
+  "book",
+  "chat",
+  "chart",
+  "bolt",
+  "music",
+  "mic",
+  "image",
+  "compass",
+  "lightbulb",
+  "file"
+];
+var starterPromptSchema = z2.object({
+  title: z2.string().trim().min(1).max(80),
+  description: z2.string().trim().max(160).optional(),
+  message: z2.string().trim().min(1).max(2e3),
+  /** One of STARTER_PROMPT_ICONS; unknown values fall back to a default icon. */
+  icon: z2.enum(STARTER_PROMPT_ICONS).optional()
+});
 var agentConfigSchema = z2.object({
   /** Prepended to the runtime's own operating instructions. */
   systemPrompt: z2.string().default(""),
   /** First message the widget shows before the user types anything. */
   greeting: z2.string().default("Hi! I can walk you through getting set up. What are you trying to do?"),
   suggestedPrompts: z2.array(z2.string()).max(6).default([]),
+  /**
+   * Explicit starter cards for the empty chat screen (title + description +
+   * the message clicking sends). When set, these take precedence over
+   * `suggestedPrompts` and over any skill-derived defaults.
+   */
+  starterPrompts: z2.array(starterPromptSchema).max(6).default([]),
   maxTurns: z2.number().int().positive().max(50).default(12),
   /** Hard stop on estimated spend per session. */
   maxBudgetUsd: z2.number().positive().optional(),
@@ -490,6 +559,17 @@ async function getUserToken() {
   throw new Error("The chat sign-in endpoint returned " + response.status + ".");
 }
 `;
+  const hostApiHeaders = auth?.client && !workspace.allowAnonymous ? `
+  headers: async () => {
+    const session = (await ${auth.client.name}?.auth.getSession())?.data.session;
+    return session?.access_token ? { Authorization: \`Bearer \${session.access_token}\` } : {};
+  },` : "";
+  const hostApi = `const hostApi = {
+  baseUrl: typeof window !== "undefined" ? window.location.origin : "",
+  credentials: "${auth?.client || workspace.allowAnonymous ? "same-origin" : "include"}" as const,${hostApiHeaders}
+};
+`;
+  const apiProp = " api={hostApi}";
   let priorChat;
   try {
     const previous = JSON.parse(files[root + "frankie.install.json"] ?? "{}");
@@ -502,17 +582,17 @@ async function getUserToken() {
   if (chatPath !== "/chat") notes.push("Existing /chat preserved. Frankie chat is available at /frankie/chat.");
   const mount = `"use client";
 import { usePathname } from "next/navigation";
-${shared}${clientAuthImport}${getToken}
+${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}><FrankieWidget /></FrankieProvider>;
+  return <FrankieProvider publishableKey={key}${authProp}${apiProp}><FrankieWidget /></FrankieProvider>;
 }
 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} />;
+  return <FrankieChatPage publishableKey={key}${authProp}${apiProp} />;
 }
 `;
   const moduleName = existingMount ? "FrankieSetupChat" : "FrankieWidgetMount";
@@ -623,7 +703,7 @@ export async function GET() {
   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("Verify the public spec URL is reachable without dashboard authentication before connecting it.");
+  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();
@@ -634,9 +714,9 @@ Workspace: ${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. Confirm https://YOUR_APP/frankie.openapi.json is public. If your Next.js middleware protects all paths, explicitly bypass /frankie.openapi.json before connecting it.
+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.
 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. Connect https://YOUR_APP/frankie.openapi.json in Frankie \u2192 Tools & MCP. The document includes read and write routes; approve tools and choose access limits separately.
+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.
 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.
 
@@ -998,6 +1078,8 @@ function compareApiDocuments(before, after) {
 }
 export {
   FIREWORKS_MODELS,
+  SKILL_TOOL_NAME,
+  STARTER_PROMPT_ICONS,
   activeSkills,
   agentConfigSchema,
   apiCapabilitySchema,
@@ -1026,6 +1108,8 @@ export {
   planHostedInstall,
   sdkUpdateWorkflow,
   skillSchema,
+  starterPromptSchema,
+  suggestedPromptsFromSkills,
   thinkingLevelSchema,
   toolDescriptions,
   toolPolicySchema,