@funkai/cli 0.1.4 → 0.3.0

package/src/lib/prompts/__tests__/flatten.test.ts

@@ -10,7 +10,7 @@ describe(flattenPartials, () => {
   describe("param parsing", () => {
     it("resolves a single literal param", () => {
       const template = "{% render 'identity', role: 'Bot' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("You are Bot, .");
@@ -19,14 +19,14 @@ describe(flattenPartials, () => {
 
     it("resolves multiple literal params", () => {
       const template = "{% render 'identity', role: 'TestBot', desc: 'a test agent' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are TestBot, a test agent.");
     });
 
     it("accepts an empty string as a valid literal param value", () => {
       const template = "{% render 'identity', role: '', desc: 'helper' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are , helper.");
       expect(result).not.toContain("{% render");
@@ -35,7 +35,7 @@ describe(flattenPartials, () => {
     it("throws when the first param uses a variable reference", () => {
       const template = "{% render 'identity', role: agentRole, desc: 'helper' %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow(
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
         'parameter "role" uses a variable reference',
       );
     });
@@ -43,7 +43,7 @@ describe(flattenPartials, () => {
     it("throws when a non-first param uses a variable reference", () => {
       const template = "{% render 'identity', role: 'Bot', desc: myDesc %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow(
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
         'parameter "desc" uses a variable reference',
       );
     });
@@ -51,19 +51,21 @@ describe(flattenPartials, () => {
     it("throws when all params are variable references", () => {
       const template = "{% render 'identity', role: agentRole, desc: agentDesc %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow("uses a variable reference");
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow(
+        "uses a variable reference",
+      );
     });
 
     it("handles extra whitespace around colons in params", () => {
       const template = "{% render 'identity', role  :  'Bot', desc  :  'helper' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
     });
 
     it("handles param values containing spaces", () => {
       const template = "{% render 'identity', role: 'Test Bot', desc: 'a helpful assistant' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Test Bot, a helpful assistant.");
     });
@@ -72,12 +74,12 @@ describe(flattenPartials, () => {
   describe("render tag parsing", () => {
     it("returns template unchanged when no render tags exist", () => {
       const template = "<identity>\nYou are a bot.\n</identity>";
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("parses a render tag with no params", () => {
       const template = "{% render 'identity' %}\n\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("</identity>");
@@ -86,7 +88,7 @@ describe(flattenPartials, () => {
 
     it("parses left-only whitespace trim {%-", () => {
       const template = "{%- render 'identity', role: 'Bot', desc: 'helper' %}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("{%-");
@@ -94,7 +96,7 @@ describe(flattenPartials, () => {
 
     it("parses right-only whitespace trim -%}", () => {
       const template = "{% render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("-%}");
@@ -102,7 +104,7 @@ describe(flattenPartials, () => {
 
     it("parses both-side whitespace trim {%- -%}", () => {
       const template = "{%- render 'identity', role: 'Bot', desc: 'helper' -%}\nDone.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).not.toContain("{%");
@@ -110,19 +112,19 @@ describe(flattenPartials, () => {
 
     it("handles extra whitespace between {% and render keyword", () => {
       const template = "{%    render 'identity', role: 'Bot', desc: 'helper' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
     });
 
     it("does not match render tags with double quotes", () => {
       const template = '{% render "identity" %}';
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("does not match malformed render tags without closing %}", () => {
       const template = "{% render 'identity'";
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
   });
 
@@ -130,7 +132,7 @@ describe(flattenPartials, () => {
     it("flattens identity partial with literal params", () => {
       const template =
         "{% render 'identity', role: 'TestBot', desc: 'a test agent' %}\n\nFollow instructions.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<identity>");
       expect(result).toContain("You are TestBot, a test agent.");
@@ -141,7 +143,7 @@ describe(flattenPartials, () => {
 
     it("flattens constraints partial with no bindings", () => {
       const template = "{% render 'constraints' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<constraints>");
       expect(result).toContain("</constraints>");
@@ -153,7 +155,7 @@ describe(flattenPartials, () => {
 
     it("flattens tools partial with no bindings (else branch)", () => {
       const template = "{% render 'tools' %}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("<tools>");
       expect(result).toContain("</tools>");
@@ -168,7 +170,7 @@ describe(flattenPartials, () => {
         "{% render 'identity', role: 'Agent', desc: 'analyzer' %}",
       ].join("\n");
 
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, helper.");
       expect(result).toContain("You are Agent, analyzer.");
@@ -178,7 +180,7 @@ describe(flattenPartials, () => {
     it("preserves surrounding markdown content", () => {
       const template =
         "# System Prompt\n\n{% render 'identity', role: 'Bot', desc: 'helper' %}\n\n## Instructions\n\nDo the thing.";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toMatch(/^# System Prompt/);
       expect(result).toContain("You are Bot, helper.");
@@ -188,13 +190,13 @@ describe(flattenPartials, () => {
     it("throws when partial file does not exist", () => {
       const template = "{% render 'nonexistent' %}";
 
-      expect(() => flattenPartials(template, [PARTIALS_DIR])).toThrow();
+      expect(() => flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toThrow();
     });
 
     it("searches multiple partialsDirs in order", () => {
       const emptyDir = resolve(import.meta.dirname);
       const template = "{% render 'identity', role: 'Bot', desc: 'test' %}";
-      const result = flattenPartials(template, [emptyDir, PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [emptyDir, PARTIALS_DIR] });
 
       expect(result).toContain("You are Bot, test.");
     });
@@ -203,13 +205,13 @@ describe(flattenPartials, () => {
   describe("template preservation", () => {
     it("preserves {{ var }} and {% if %} expressions", () => {
       const template = "Hello {{ name }}.\n{% if context %}{{ context }}{% endif %}";
-      expect(flattenPartials(template, [PARTIALS_DIR])).toBe(template);
+      expect(flattenPartials({ template, partialsDirs: [PARTIALS_DIR] })).toBe(template);
     });
 
     it("flattens render tag while preserving surrounding Liquid blocks", () => {
       const template =
         "{% if show_identity %}\n{% render 'identity', role: 'Bot', desc: 'helper' %}\n{% endif %}\n\n{{ instructions }}";
-      const result = flattenPartials(template, [PARTIALS_DIR]);
+      const result = flattenPartials({ template, partialsDirs: [PARTIALS_DIR] });
 
       expect(result).toContain("{% if show_identity %}");
       expect(result).toContain("{% endif %}");
@@ -219,12 +221,12 @@ describe(flattenPartials, () => {
     });
 
     it("returns empty string unchanged", () => {
-      expect(flattenPartials("", [PARTIALS_DIR])).toBe("");
+      expect(flattenPartials({ template: "", partialsDirs: [PARTIALS_DIR] })).toBe("");
     });
 
     it("returns whitespace-only template unchanged", () => {
       const ws = "   \n\n   ";
-      expect(flattenPartials(ws, [PARTIALS_DIR])).toBe(ws);
+      expect(flattenPartials({ template: ws, partialsDirs: [PARTIALS_DIR] })).toBe(ws);
     });
   });
 });

package/src/lib/prompts/__tests__/frontmatter.test.ts

@@ -5,20 +5,20 @@ import { parseFrontmatter } from "@/lib/prompts/frontmatter.js";
 describe(parseFrontmatter, () => {
   it("parses name from frontmatter", () => {
     const content = "---\nname: my-prompt\n---\nHello";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.name).toBe("my-prompt");
   });
 
   it("parses group and version", () => {
     const content = "---\nname: test\ngroup: agents/test\nversion: 2\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.group).toBe("agents/test");
     expect(result.version).toBe("2");
   });
 
   it("parses schema with shorthand type strings", () => {
     const content = "---\nname: test\nschema:\n  scope: string\n  target: string\n---\n";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.schema).toEqual([
       { name: "scope", type: "string", required: true },
       { name: "target", type: "string", required: true },
@@ -39,7 +39,7 @@ describe(parseFrontmatter, () => {
       "---",
       "",
     ].join("\n");
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.schema).toEqual([
       { name: "scope", type: "string", required: true, description: "The scope" },
       { name: "target", type: "string", required: false },
@@ -48,42 +48,44 @@ describe(parseFrontmatter, () => {
 
   it("returns empty schema when no schema field", () => {
     const content = "---\nname: test\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.schema).toEqual([]);
   });
 
   it("throws on missing frontmatter", () => {
-    expect(() => parseFrontmatter("No frontmatter", "test.prompt")).toThrow("No frontmatter");
+    expect(() => parseFrontmatter({ content: "No frontmatter", filePath: "test.prompt" })).toThrow(
+      "No frontmatter",
+    );
   });
 
   it("throws on missing name", () => {
-    expect(() => parseFrontmatter("---\nversion: 1\n---\n", "test.prompt")).toThrow(
-      'Missing or empty "name"',
-    );
+    expect(() =>
+      parseFrontmatter({ content: "---\nversion: 1\n---\n", filePath: "test.prompt" }),
+    ).toThrow('Missing or empty "name"');
   });
 
   it("throws on invalid name format", () => {
-    expect(() => parseFrontmatter("---\nname: My Prompt\n---\n", "test.prompt")).toThrow(
-      "Invalid prompt name",
-    );
+    expect(() =>
+      parseFrontmatter({ content: "---\nname: My Prompt\n---\n", filePath: "test.prompt" }),
+    ).toThrow("Invalid prompt name");
   });
 
   it("returns undefined group when not specified", () => {
     const content = "---\nname: test\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.group).toBeUndefined();
   });
 
   it("should throw on invalid group segment", () => {
     const content = "---\nname: test\ngroup: agents/INVALID\n---\nBody";
-    expect(() => parseFrontmatter(content, "test.prompt")).toThrow(
+    expect(() => parseFrontmatter({ content, filePath: "test.prompt" })).toThrow(
       'Invalid group segment "INVALID"',
     );
   });
 
   it("should accept valid multi-segment group", () => {
     const content = "---\nname: test\ngroup: agents/specialized\n---\nBody";
-    const result = parseFrontmatter(content, "test.prompt");
+    const result = parseFrontmatter({ content, filePath: "test.prompt" });
     expect(result.group).toBe("agents/specialized");
   });
 });

package/src/lib/prompts/codegen.ts

@@ -13,6 +13,10 @@ export interface ParsedPrompt {
   readonly sourcePath: string;
 }
 
+// ---------------------------------------------------------------------------
+// Private
+// ---------------------------------------------------------------------------
+
 /**
  * Convert a kebab-case name to PascalCase.
  *
@@ -55,6 +59,30 @@ function escapeTemplateLiteral(str: string): string {
     .replaceAll("${", "\\${");
 }
 
+/** @private */
+function formatGroupValue(group: string | undefined): string {
+  if (group) {
+    return `'${group}' as const`;
+  }
+  return "undefined";
+}
+
+/** @private */
+function formatGroupJsdoc(group: string | undefined): readonly string[] {
+  if (group) {
+    return [" *", ` * @group ${group}`];
+  }
+  return [];
+}
+
+/** @private */
+function parseGroupSegments(group: string | undefined): readonly string[] {
+  if (group) {
+    return group.split("/").map(toCamelCase);
+  }
+  return [];
+}
+
 /**
  * Generate the Zod schema expression for a list of schema variables.
  *
@@ -68,13 +96,9 @@ function generateSchemaExpression(vars: readonly SchemaVariable[]): string {
   const fields = vars
     .map((v) => {
       const base = "z.string()";
-      // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-      const expr: string = (() => {
-        if (v.required) {
-          return base;
-        }
-        return `${base}.optional()`;
-      })();
+      const expr = match(v.required)
+        .with(true, () => base)
+        .otherwise(() => `${base}.optional()`);
       return `  ${v.name}: ${expr},`;
     })
     .join("\n");
@@ -82,40 +106,79 @@ function generateSchemaExpression(vars: readonly SchemaVariable[]): string {
   return `z.object({\n${fields}\n})`;
 }
 
-const HEADER = [
-  "/*",
-  "|==========================================================================",
-  "| AUTO-GENERATED — DO NOT EDIT",
-  "|==========================================================================",
-  "|",
-  "| Run `funkai prompts generate` to regenerate.",
-  "|",
-  "*/",
-].join("\n");
+/** @private */
+function formatHeader(sourcePath?: string): string {
+  let sourceLine = "";
+  if (sourcePath) {
+    sourceLine = `//  Source:      ${sourcePath}\n`;
+  }
+  return [
+    "// ─── AUTO-GENERATED ────────────────────────────────────────",
+    `${sourceLine}//  Regenerate:  funkai prompts generate`,
+    "// ───────────────────────────────────────────────────────────",
+  ].join("\n");
+}
+
+/**
+ * Derive a unique file slug from group + name.
+ *
+ * Ungrouped prompts use the name alone. Grouped prompts
+ * join group segments and name with hyphens.
+ *
+ * @param name - The prompt name (kebab-case).
+ * @param group - Optional group path (e.g., 'core/agent').
+ * @returns The file slug string.
+ *
+ * @example
+ * ```ts
+ * toFileSlug('system', 'core/agent')      // => 'core-agent-system'
+ * toFileSlug('greeting', undefined)        // => 'greeting'
+ * ```
+ */
+export function toFileSlug(name: string, group?: string): string {
+  if (group) {
+    return `${group.replaceAll("/", "-")}-${name}`;
+  }
+  return name;
+}
+
+/**
+ * Derive a unique import name (camelCase) from group + name.
+ *
+ * @param name - The prompt name (kebab-case).
+ * @param group - Optional group path (e.g., 'core/agent').
+ * @returns The camelCase import identifier.
+ *
+ * @example
+ * ```ts
+ * toImportName('system', 'core/agent')     // => 'coreAgentSystem'
+ * toImportName('greeting', undefined)       // => 'greeting'
+ * ```
+ */
+export function toImportName(name: string, group?: string): string {
+  return toCamelCase(toFileSlug(name, group));
+}
 
 /**
  * Generate a per-prompt TypeScript module with a default export.
  *
- * The module contains the Zod schema, inlined template, and
- * `render` / `validate` functions.
+ * The module uses `createPrompt` from `@funkai/prompts` to
+ * encapsulate the Zod schema, inlined template, and render logic.
+ *
+ * @param prompt - The parsed prompt configuration.
+ * @returns The generated TypeScript module source code.
  */
 export function generatePromptModule(prompt: ParsedPrompt): string {
   const escaped = escapeTemplateLiteral(prompt.template);
   const schemaExpr = generateSchemaExpression(prompt.schema);
-  // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-  const groupValue: string = (() => {
-    if (prompt.group) {
-      return `'${prompt.group}' as const`;
-    }
-    return "undefined";
-  })();
+  const groupValue = formatGroupValue(prompt.group);
+  const header = formatHeader(prompt.sourcePath);
 
-  const lines: string[] = [
-    HEADER,
-    `// Source: ${prompt.sourcePath}`,
+  const lines: readonly string[] = [
+    header,
     "",
     "import { z } from 'zod'",
-    "import { liquidEngine } from '@funkai/prompts/runtime'",
+    "import { createPrompt } from '@funkai/prompts'",
     "",
     `const schema = ${schemaExpr}`,
     "",
@@ -123,28 +186,16 @@ export function generatePromptModule(prompt: ParsedPrompt): string {
     "",
     `const template = \`${escaped}\``,
     "",
-    "export default {",
-    `  name: '${prompt.name}' as const,`,
+    "/**",
+    ` * **${prompt.name}** prompt module.`,
+    ...formatGroupJsdoc(prompt.group),
+    " */",
+    "export default createPrompt<Variables>({",
+    `  name: '${prompt.name}',`,
     `  group: ${groupValue},`,
+    "  template,",
     "  schema,",
-    ...match(prompt.schema.length)
-      .with(0, () => [
-        "  render(variables?: undefined): string {",
-        "    return liquidEngine.parseAndRenderSync(template, {})",
-        "  },",
-        "  validate(variables?: undefined): Variables {",
-        "    return schema.parse(variables ?? {})",
-        "  },",
-      ])
-      .otherwise(() => [
-        "  render(variables: Variables): string {",
-        "    return liquidEngine.parseAndRenderSync(template, schema.parse(variables))",
-        "  },",
-        "  validate(variables: unknown): Variables {",
-        "    return schema.parse(variables)",
-        "  },",
-      ]),
-    "}",
+    "})",
     "",
   ];
 
@@ -162,6 +213,9 @@ interface TreeNode {
 /**
  * Build a nested tree from sorted prompts, grouped by their `group` field.
  *
+ * Leaf values are the unique import name derived from group+name,
+ * so prompts with the same name in different groups do not collide.
+ *
  * @param prompts - Sorted parsed prompts.
  * @returns A tree where leaves are import names and branches are group namespaces.
  * @throws If a prompt name collides with a group namespace at the same level.
@@ -170,14 +224,9 @@ interface TreeNode {
  */
 function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
   return prompts.reduce<Record<string, unknown>>((root, prompt) => {
-    const importName = toCamelCase(prompt.name);
-    // oxlint-disable-next-line unicorn/prefer-ternary -- no-ternary rule forbids ternaries
-    const segments: string[] = (() => {
-      if (prompt.group) {
-        return prompt.group.split("/").map(toCamelCase);
-      }
-      return [];
-    })();
+    const leafKey = toCamelCase(prompt.name);
+    const importName = toImportName(prompt.name, prompt.group);
+    const segments = parseGroupSegments(prompt.group);
 
     const target = segments.reduce<Record<string, unknown>>((current, segment) => {
       const existing = current[segment];
@@ -192,13 +241,13 @@ function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
       return current[segment] as Record<string, unknown>;
     }, root);
 
-    if (typeof target[importName] === "object" && target[importName] !== null) {
+    if (typeof target[leafKey] === "object" && target[leafKey] !== null) {
       throw new Error(
-        `Collision: prompt "${importName}" conflicts with existing group namespace "${importName}" at the same level.`,
+        `Collision: prompt "${leafKey}" conflicts with existing group namespace "${leafKey}" at the same level.`,
       );
     }
 
-    target[importName] = importName;
+    target[leafKey] = importName;
     return root;
   }, {}) as TreeNode;
 }
@@ -212,22 +261,23 @@ function buildTree(prompts: readonly ParsedPrompt[]): TreeNode {
  *
  * @private
  */
-function serializeTree(node: TreeNode, indent: number): string[] {
+function serializeTree(node: TreeNode, indent: number): readonly string[] {
   const pad = "  ".repeat(indent);
 
-  const lines: string[] = [];
-  for (const [key, value] of Object.entries(node)) {
-    if (typeof value === "string") {
-      lines.push(`${pad}${key},`);
-    } else {
-      lines.push(`${pad}${key}: {`);
-      for (const child of serializeTree(value, indent + 1)) {
-        lines.push(child);
-      }
-      lines.push(`${pad}},`);
-    }
-  }
-  return lines;
+  return Object.entries(node).flatMap(([key, value]) =>
+    match(typeof value)
+      .with("string", () => {
+        if (key === value) {
+          return [`${pad}${key},`];
+        }
+        return [`${pad}${key}: ${value as string},`];
+      })
+      .otherwise(() => [
+        `${pad}${key}: {`,
+        ...serializeTree(value as TreeNode, indent + 1),
+        `${pad}},`,
+      ]),
+  );
 }
 
 /**
@@ -236,19 +286,39 @@ function serializeTree(node: TreeNode, indent: number): string[] {
  *
  * Prompts are organized into a nested object structure based on their
  * `group` field, with each `/`-separated segment becoming a nesting level.
+ *
+ * @param prompts - Sorted parsed prompts to include in the registry.
+ * @returns The generated TypeScript source for the registry index module.
+ *
+ * @example
+ * ```ts
+ * const source = generateRegistry([
+ *   { name: 'system', group: 'core/agent', schema: [], template: '...', sourcePath: 'prompts/system.prompt' },
+ * ])
+ * writeFileSync('index.ts', source)
+ * ```
  */
 export function generateRegistry(prompts: readonly ParsedPrompt[]): string {
-  const sorted = [...prompts].toSorted((a, b) => a.name.localeCompare(b.name));
+  const sorted = [...prompts].toSorted((a, b) => {
+    const slugA = toFileSlug(a.name, a.group);
+    const slugB = toFileSlug(b.name, b.group);
+    return slugA.localeCompare(slugB);
+  });
 
   const imports = sorted
-    .map((p) => `import ${toCamelCase(p.name)} from './${p.name}.js'`)
+    .map((p) => {
+      const importName = toImportName(p.name, p.group);
+      const fileSlug = toFileSlug(p.name, p.group);
+      return `import ${importName} from './${fileSlug}.js'`;
+    })
     .join("\n");
 
   const tree = buildTree(sorted);
   const treeLines = serializeTree(tree, 1);
+  const header = formatHeader();
 
-  const lines: string[] = [
-    HEADER,
+  const lines: readonly string[] = [
+    header,
     "",
     "import { createPromptRegistry } from '@funkai/prompts'",
     imports,