@funkai/prompts 0.1.0

package/dist/lib/index.d.mts

@@ -0,0 +1,99 @@
+import { Liquid, Liquid as Liquid$1, LiquidOptions } from "liquidjs";
+import { ZodType } from "zod";
+
+//#region src/types.d.ts
+/**
+ * Options for creating a custom LiquidJS engine.
+ */
+type CreateEngineOptions = Pick<LiquidOptions, "root" | "partials" | "extname" | "cache" | "strictFilters" | "strictVariables" | "ownPropertyOnly">;
+/**
+ * A single prompt module produced by codegen.
+ *
+ * Each `.prompt` file generates a default export conforming to this shape.
+ */
+interface PromptModule<T = unknown> {
+  readonly name: string;
+  readonly group: string | undefined;
+  readonly schema: ZodType<T>;
+  render(variables: T): string;
+  validate(variables: unknown): T;
+}
+/**
+ * A nested namespace node in the prompt tree.
+ * Values are either PromptModule leaves or further nested namespaces.
+ */
+type PromptNamespace = {
+  readonly [key: string]: PromptModule | PromptNamespace;
+};
+/**
+ * Deep-readonly version of a prompt tree.
+ * Prevents reassignment at any nesting level.
+ *
+ * @example
+ * ```ts
+ * type MyRegistry = PromptRegistry<{
+ *   agents: { coverageAssessor: PromptModule }
+ *   greeting: PromptModule
+ * }>
+ * ```
+ */
+type PromptRegistry<T extends PromptNamespace> = { readonly [K in keyof T]: T[K] extends PromptModule ? T[K] : T[K] extends PromptNamespace ? PromptRegistry<T[K]> : T[K] };
+//#endregion
+//#region src/engine.d.ts
+/**
+ * Create a LiquidJS engine with custom options.
+ *
+ * The `partialsDir` is used as the root for `{% render %}` resolution.
+ * The `.prompt` extension is appended automatically.
+ *
+ * @param partialsDir - Root directory for `{% render %}` partial resolution.
+ * @param options - Optional overrides for the LiquidJS engine configuration.
+ * @returns A configured {@link Liquid} engine instance.
+ */
+declare function createEngine(partialsDir: string, options?: Partial<CreateEngineOptions>): Liquid$1;
+/**
+ * Shared LiquidJS engine for rendering prompt templates at runtime.
+ *
+ * Partials are flattened at codegen time by the CLI, so this engine
+ * only needs to handle `{{ var }}` expressions and basic Liquid
+ * control flow (`{% if %}`, `{% for %}`). No filesystem access required.
+ */
+declare const engine: Liquid$1;
+//#endregion
+//#region src/clean.d.ts
+/**
+ * Clean a raw `.prompt` file into a render-ready template.
+ *
+ * Runs the source through a pipeline of transforms — currently
+ * strips frontmatter, with more steps added over time.
+ */
+declare function clean(text: string): string;
+//#endregion
+//#region src/partials-dir.d.ts
+/** Absolute path to the SDK's built-in partials directory. */
+declare const PARTIALS_DIR: string;
+//#endregion
+//#region src/registry.d.ts
+/**
+ * Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.
+ *
+ * The registry is typically created by generated code — the CLI produces
+ * an `index.ts` that calls `createPromptRegistry()` with all discovered
+ * prompt modules keyed by camelCase name, nested by group.
+ *
+ * @param modules - Record mapping camelCase prompt names (or group namespaces) to their modules.
+ * @returns A deep-frozen, typed record with direct property access.
+ *
+ * @example
+ * ```ts
+ * const prompts = createPromptRegistry({
+ *   agents: { coverageAssessor },
+ *   greeting,
+ * })
+ * prompts.agents.coverageAssessor.render({ scope: 'full' })
+ * ```
+ */
+declare function createPromptRegistry<T extends PromptNamespace>(modules: T): PromptRegistry<T>;
+//#endregion
+export { type CreateEngineOptions, type Liquid, PARTIALS_DIR, type PromptModule, type PromptNamespace, type PromptRegistry, clean, createEngine, createPromptRegistry, engine };
+//# sourceMappingURL=index.d.mts.map

package/dist/lib/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/engine.ts","../../src/clean.ts","../../src/partials-dir.ts","../../src/registry.ts"],"mappings":";;;;;;AAMA;KAAY,mBAAA,GAAsB,IAAA,CAChC,aAAA;;;;AAeF;;UAAiB,YAAA;EAAA,SACN,IAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA,EAAQ,OAAA,CAAQ,CAAA;EACzB,MAAA,CAAO,SAAA,EAAW,CAAA;EAClB,QAAA,CAAS,SAAA,YAAqB,CAAA;AAAA;;;;;KAOpB,eAAA;EAAA,UACA,GAAA,WAAc,YAAA,GAAe,eAAA;AAAA;;;;;;;;AADzC;;;;;KAgBY,cAAA,WAAyB,eAAA,2BACd,CAAA,GAAI,CAAA,CAAE,CAAA,UAAW,YAAA,GAClC,CAAA,CAAE,CAAA,IACF,CAAA,CAAE,CAAA,UAAW,eAAA,GACX,cAAA,CAAe,CAAA,CAAE,CAAA,KACjB,CAAA,CAAE,CAAA;;;;;AAjDV;;;;;AAgBA;;;iBCRgB,YAAA,CAAa,WAAA,UAAqB,OAAA,GAAU,OAAA,CAAQ,mBAAA,IAAuB,QAAA;;;;;;;;cAmB9E,MAAA,EAAM,QAAA;;;;;;;AD3BnB;;iBEgBgB,KAAA,CAAM,IAAA;;;;cClBT,YAAA;;;;;;AHEb;;;;;AAgBA;;;;;;;;;;;iBIwCgB,oBAAA,WAA+B,eAAA,CAAA,CAAiB,OAAA,EAAS,CAAA,GAAI,cAAA,CAAe,CAAA"}

package/dist/lib/index.mjs

@@ -0,0 +1,117 @@
+import { Liquid } from "liquidjs";
+import { flow } from "es-toolkit";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/engine.ts
+/**
+* Create a LiquidJS engine with custom options.
+*
+* The `partialsDir` is used as the root for `{% render %}` resolution.
+* The `.prompt` extension is appended automatically.
+*
+* @param partialsDir - Root directory for `{% render %}` partial resolution.
+* @param options - Optional overrides for the LiquidJS engine configuration.
+* @returns A configured {@link Liquid} engine instance.
+*/
+function createEngine(partialsDir, options) {
+	return new Liquid({
+		root: [partialsDir],
+		partials: [partialsDir],
+		extname: ".prompt",
+		cache: true,
+		strictFilters: true,
+		ownPropertyOnly: true,
+		...options
+	});
+}
+/**
+* Shared LiquidJS engine for rendering prompt templates at runtime.
+*
+* Partials are flattened at codegen time by the CLI, so this engine
+* only needs to handle `{{ var }}` expressions and basic Liquid
+* control flow (`{% if %}`, `{% for %}`). No filesystem access required.
+*/
+const engine = new Liquid({
+	strictFilters: true,
+	ownPropertyOnly: true
+});
+//#endregion
+//#region src/clean.ts
+const FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
+/**
+* Remove YAML frontmatter from the beginning of a string.
+*
+* Frontmatter is a block delimited by `---` at the start of the file.
+* If no frontmatter is present, the string is returned unchanged.
+*/
+function stripFrontmatter(text) {
+	return text.replace(FRONTMATTER_RE, "");
+}
+const pipeline = flow(stripFrontmatter);
+/**
+* Clean a raw `.prompt` file into a render-ready template.
+*
+* Runs the source through a pipeline of transforms — currently
+* strips frontmatter, with more steps added over time.
+*/
+function clean(text) {
+	return pipeline(text);
+}
+//#endregion
+//#region src/partials-dir.ts
+/** Absolute path to the SDK's built-in partials directory. */
+const PARTIALS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../prompts");
+//#endregion
+//#region src/registry.ts
+/**
+* Check whether a value looks like a PromptModule leaf.
+* Leaves have `name`, `schema`, and `render` — namespaces do not.
+*
+* @private
+*/
+function isPromptModule(value) {
+	return typeof value === "object" && value !== null && "render" in value && "schema" in value && "name" in value;
+}
+/**
+* Recursively freeze a prompt namespace tree.
+* Only recurses into plain namespace nodes — PromptModule leaves
+* (which contain Zod schemas) are frozen shallowly.
+*
+* @param obj - The namespace object to freeze.
+* @returns The frozen object cast to its deep-readonly type.
+*
+* @private
+*/
+function deepFreeze(obj) {
+	Object.freeze(obj);
+	Object.values(obj).forEach((value) => {
+		if (typeof value === "object" && value !== null && !Object.isFrozen(value) && !isPromptModule(value)) deepFreeze(value);
+	});
+	return obj;
+}
+/**
+* Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.
+*
+* The registry is typically created by generated code — the CLI produces
+* an `index.ts` that calls `createPromptRegistry()` with all discovered
+* prompt modules keyed by camelCase name, nested by group.
+*
+* @param modules - Record mapping camelCase prompt names (or group namespaces) to their modules.
+* @returns A deep-frozen, typed record with direct property access.
+*
+* @example
+* ```ts
+* const prompts = createPromptRegistry({
+*   agents: { coverageAssessor },
+*   greeting,
+* })
+* prompts.agents.coverageAssessor.render({ scope: 'full' })
+* ```
+*/
+function createPromptRegistry(modules) {
+	return deepFreeze({ ...modules });
+}
+//#endregion
+export { PARTIALS_DIR, clean, createEngine, createPromptRegistry, engine };
+
+//# sourceMappingURL=index.mjs.map

package/dist/lib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/engine.ts","../../src/clean.ts","../../src/partials-dir.ts","../../src/registry.ts"],"sourcesContent":["import { Liquid } from \"liquidjs\";\n\nimport type { CreateEngineOptions } from \"./types.js\";\n\n/**\n * Create a LiquidJS engine with custom options.\n *\n * The `partialsDir` is used as the root for `{% render %}` resolution.\n * The `.prompt` extension is appended automatically.\n *\n * @param partialsDir - Root directory for `{% render %}` partial resolution.\n * @param options - Optional overrides for the LiquidJS engine configuration.\n * @returns A configured {@link Liquid} engine instance.\n */\nexport function createEngine(partialsDir: string, options?: Partial<CreateEngineOptions>): Liquid {\n  return new Liquid({\n    root: [partialsDir],\n    partials: [partialsDir],\n    extname: \".prompt\",\n    cache: true,\n    strictFilters: true,\n    ownPropertyOnly: true,\n    ...options,\n  });\n}\n\n/**\n * Shared LiquidJS engine for rendering prompt templates at runtime.\n *\n * Partials are flattened at codegen time by the CLI, so this engine\n * only needs to handle `{{ var }}` expressions and basic Liquid\n * control flow (`{% if %}`, `{% for %}`). No filesystem access required.\n */\nexport const engine = new Liquid({\n  strictFilters: true,\n  ownPropertyOnly: true,\n});\n","import { flow } from \"es-toolkit\";\n\nconst FRONTMATTER_RE = /^---\\r?\\n[\\s\\S]*?\\r?\\n---\\r?\\n?/;\n\n/**\n * Remove YAML frontmatter from the beginning of a string.\n *\n * Frontmatter is a block delimited by `---` at the start of the file.\n * If no frontmatter is present, the string is returned unchanged.\n */\nfunction stripFrontmatter(text: string): string {\n  return text.replace(FRONTMATTER_RE, \"\");\n}\n\nconst pipeline = flow(stripFrontmatter);\n\n/**\n * Clean a raw `.prompt` file into a render-ready template.\n *\n * Runs the source through a pipeline of transforms — currently\n * strips frontmatter, with more steps added over time.\n */\nexport function clean(text: string): string {\n  return pipeline(text);\n}\n","import { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n/** Absolute path to the SDK's built-in partials directory. */\nexport const PARTIALS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), \"../prompts\");\n","import type { PromptModule, PromptNamespace, PromptRegistry } from \"./types.js\";\n\n/**\n * Check whether a value looks like a PromptModule leaf.\n * Leaves have `name`, `schema`, and `render` — namespaces do not.\n *\n * @private\n */\nfunction isPromptModule(value: unknown): value is PromptModule {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"render\" in value &&\n    \"schema\" in value &&\n    \"name\" in value\n  );\n}\n\n/**\n * Recursively freeze a prompt namespace tree.\n * Only recurses into plain namespace nodes — PromptModule leaves\n * (which contain Zod schemas) are frozen shallowly.\n *\n * @param obj - The namespace object to freeze.\n * @returns The frozen object cast to its deep-readonly type.\n *\n * @private\n */\nfunction deepFreeze<T extends PromptNamespace>(obj: T): PromptRegistry<T> {\n  Object.freeze(obj);\n  Object.values(obj).forEach((value) => {\n    if (\n      typeof value === \"object\" &&\n      value !== null &&\n      !Object.isFrozen(value) &&\n      !isPromptModule(value)\n    ) {\n      deepFreeze(value as PromptNamespace);\n    }\n  });\n  return obj as PromptRegistry<T>;\n}\n\n/**\n * Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.\n *\n * The registry is typically created by generated code — the CLI produces\n * an `index.ts` that calls `createPromptRegistry()` with all discovered\n * prompt modules keyed by camelCase name, nested by group.\n *\n * @param modules - Record mapping camelCase prompt names (or group namespaces) to their modules.\n * @returns A deep-frozen, typed record with direct property access.\n *\n * @example\n * ```ts\n * const prompts = createPromptRegistry({\n *   agents: { coverageAssessor },\n *   greeting,\n * })\n * prompts.agents.coverageAssessor.render({ scope: 'full' })\n * ```\n */\nexport function createPromptRegistry<T extends PromptNamespace>(modules: T): PromptRegistry<T> {\n  return deepFreeze({ ...modules });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,SAAgB,aAAa,aAAqB,SAAgD;AAChG,QAAO,IAAI,OAAO;EAChB,MAAM,CAAC,YAAY;EACnB,UAAU,CAAC,YAAY;EACvB,SAAS;EACT,OAAO;EACP,eAAe;EACf,iBAAiB;EACjB,GAAG;EACJ,CAAC;;;;;;;;;AAUJ,MAAa,SAAS,IAAI,OAAO;CAC/B,eAAe;CACf,iBAAiB;CAClB,CAAC;;;AClCF,MAAM,iBAAiB;;;;;;;AAQvB,SAAS,iBAAiB,MAAsB;AAC9C,QAAO,KAAK,QAAQ,gBAAgB,GAAG;;AAGzC,MAAM,WAAW,KAAK,iBAAiB;;;;;;;AAQvC,SAAgB,MAAM,MAAsB;AAC1C,QAAO,SAAS,KAAK;;;;;ACnBvB,MAAa,eAAe,QAAQ,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,aAAa;;;;;;;;;ACI1F,SAAS,eAAe,OAAuC;AAC7D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,YAAY,SACZ,YAAY,SACZ,UAAU;;;;;;;;;;;;AAcd,SAAS,WAAsC,KAA2B;AACxE,QAAO,OAAO,IAAI;AAClB,QAAO,OAAO,IAAI,CAAC,SAAS,UAAU;AACpC,MACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,OAAO,SAAS,MAAM,IACvB,CAAC,eAAe,MAAM,CAEtB,YAAW,MAAyB;GAEtC;AACF,QAAO;;;;;;;;;;;;;;;;;;;;;AAsBT,SAAgB,qBAAgD,SAA+B;AAC7F,QAAO,WAAW,EAAE,GAAG,SAAS,CAAC"}

package/dist/prompts/constraints.prompt

@@ -0,0 +1,20 @@
+<constraints>
+{% if in_scope %}
+## In Scope
+{% for item in in_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if out_of_scope %}
+## Out of Scope
+{% for item in out_of_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if rules %}
+## Rules
+{% for rule in rules %}
+- {{ rule }}
+{% endfor %}
+{% endif %}
+</constraints>

package/dist/prompts/identity.prompt

@@ -0,0 +1,6 @@
+<identity>
+You are {{ role }}, {{ desc }}.
+{% if context %}
+{{ context }}
+{% endif %}
+</identity>

package/dist/prompts/prompts/constraints.prompt

@@ -0,0 +1,20 @@
+<constraints>
+{% if in_scope %}
+## In Scope
+{% for item in in_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if out_of_scope %}
+## Out of Scope
+{% for item in out_of_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if rules %}
+## Rules
+{% for rule in rules %}
+- {{ rule }}
+{% endfor %}
+{% endif %}
+</constraints>

package/dist/prompts/prompts/identity.prompt

@@ -0,0 +1,6 @@
+<identity>
+You are {{ role }}, {{ desc }}.
+{% if context %}
+{{ context }}
+{% endif %}
+</identity>

package/dist/prompts/prompts/tools.prompt

@@ -0,0 +1,14 @@
+<tools>
+You have access to the following tools:
+{% if tools %}
+{% for tool in tools %}
+**{{ tool.name }}** -- {{ tool.description }}
+{% for param in tool.params %}
+- `{{ param.name }}` ({{ param.type }}{% if param.required %}, required{% endif %}) -- {{ param.description }}
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No tools are configured for this agent.
+{% endif %}
+</tools>

package/dist/prompts/tools.prompt

@@ -0,0 +1,14 @@
+<tools>
+You have access to the following tools:
+{% if tools %}
+{% for tool in tools %}
+**{{ tool.name }}** -- {{ tool.description }}
+{% for param in tool.params %}
+- `{{ param.name }}` ({{ param.type }}{% if param.required %}, required{% endif %}) -- {{ param.description }}
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No tools are configured for this agent.
+{% endif %}
+</tools>

package/docs/cli/commands.md

@@ -0,0 +1,73 @@
+# CLI Commands Reference
+
+## `prompts generate`
+
+Generate typed TypeScript modules from `.prompt` files.
+
+**Alias:** `gen`
+
+| Flag       | Alias | Required | Description                                             |
+| ---------- | ----- | -------- | ------------------------------------------------------- |
+| `--out`    | `-o`  | Yes      | Output directory for generated files                    |
+| `--roots`  | `-r`  | Yes      | Space-separated directories to scan for `.prompt` files |
+| `--silent` | ---   | No       | Suppress output except errors                           |
+
+```bash
+prompts generate --out .prompts/client --roots prompts src/agents src/workflows
+```
+
+Custom partials are auto-discovered from the sibling `partials/` directory (relative to `--out`).
+
+Runs lint validation automatically before generating. Exits with code 1 on lint errors.
+
+## `prompts lint`
+
+Validate `.prompt` files without generating output.
+
+| Flag         | Alias | Required | Description                                              |
+| ------------ | ----- | -------- | -------------------------------------------------------- |
+| `--roots`    | `-r`  | Yes      | Directories to scan                                      |
+| `--partials` | `-p`  | No       | Custom partials directory (default: `.prompts/partials`) |
+| `--silent`   | ---   | No       | Suppress output except errors                            |
+
+**Diagnostics:**
+
+| Level | Meaning                                  |
+| ----- | ---------------------------------------- |
+| Error | Template variable not declared in schema |
+| Warn  | Schema variable not used in template     |
+
+```bash
+prompts lint --roots prompts src/agents
+```
+
+## `prompts create`
+
+Scaffold a new `.prompt` file.
+
+| Arg/Flag    | Required | Description                                                   |
+| ----------- | -------- | ------------------------------------------------------------- |
+| `<name>`    | Yes      | Prompt name (kebab-case)                                      |
+| `--out`     | No       | Output directory (defaults to cwd)                            |
+| `--partial` | No       | Create as a partial in `.prompts/partials/` (ignores `--out`) |
+
+```bash
+prompts create coverage-assessor --out src/agents/coverage-assessor
+prompts create summary --partial
+```
+
+## `prompts setup`
+
+Interactive project configuration for `.prompt` development. No flags -- fully interactive.
+
+Configures:
+
+1. VSCode file association (`*.prompt` -> Markdown)
+2. VSCode Liquid extension recommendation
+3. `.gitignore` entry for generated `.prompts/client/` directory
+4. `tsconfig.json` path alias (`~prompts` -> `./.prompts/client/index.ts`)
+
+## References
+
+- [CLI Overview](overview.md)
+- [Troubleshooting](../troubleshooting.md)

package/docs/cli/overview.md

@@ -0,0 +1,73 @@
+# CLI Overview
+
+The `prompts` CLI discovers, validates, and generates typed TypeScript from `.prompt` files.
+
+## Installation
+
+Available as the `prompts` binary from `@funkai/cli`. Install it as a workspace dependency:
+
+```bash
+pnpm add @funkai/cli --workspace
+```
+
+## Workflow
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#313244',
+    'primaryTextColor': '#cdd6f4',
+    'primaryBorderColor': '#6c7086',
+    'lineColor': '#89b4fa',
+    'secondaryColor': '#45475a',
+    'tertiaryColor': '#1e1e2e',
+    'actorBkg': '#313244',
+    'actorBorder': '#89b4fa',
+    'actorTextColor': '#cdd6f4',
+    'signalColor': '#cdd6f4',
+    'signalTextColor': '#cdd6f4'
+  }
+}}%%
+sequenceDiagram
+    participant Dev as Developer
+    participant CLI as prompts CLI
+    participant FS as File System
+
+    Dev->>CLI: prompts generate
+    CLI->>FS: Discover .prompt files from roots
+    CLI->>CLI: Parse frontmatter + extract variables
+    CLI->>CLI: Lint (schema vs template match)
+    CLI->>CLI: Flatten partials
+    CLI->>FS: Write generated .ts modules
+    FS-->>Dev: Import typed prompts from ~prompts
+```
+
+## Commands
+
+| Command            | Alias | Description                                    |
+| ------------------ | ----- | ---------------------------------------------- |
+| `prompts generate` | `gen` | Generate typed TS modules from `.prompt` files |
+| `prompts lint`     | ---   | Validate `.prompt` files without generating    |
+| `prompts create`   | ---   | Scaffold a new `.prompt` file                  |
+| `prompts setup`    | ---   | Interactive project configuration              |
+
+See the [Commands Reference](commands.md) for flags, examples, and diagnostics.
+
+## Integration
+
+Add a generate script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "prompts:generate": "prompts generate --out .prompts/client --roots prompts src/agents"
+  }
+}
+```
+
+## References
+
+- [Commands Reference](commands.md)
+- [Code Generation](../codegen/overview.md)
+- [Setup Guide](../guides/setup-project.md)

package/docs/codegen/overview.md

@@ -0,0 +1,83 @@
+# Code Generation
+
+The CLI transforms `.prompt` source files into typed TypeScript modules. This doc explains the pipeline stages and the shape of generated output.
+
+## Pipeline
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#313244',
+    'primaryTextColor': '#cdd6f4',
+    'primaryBorderColor': '#6c7086',
+    'lineColor': '#89b4fa',
+    'secondaryColor': '#45475a',
+    'tertiaryColor': '#1e1e2e',
+    'background': '#1e1e2e',
+    'mainBkg': '#313244',
+    'clusterBkg': '#1e1e2e',
+    'clusterBorder': '#45475a'
+  },
+  'flowchart': { 'curve': 'basis', 'padding': 15 }
+}}%%
+flowchart TD
+  classDef core fill:#313244,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+  classDef agent fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+
+  subgraph Per Prompt
+    A[discoverPrompts]:::core --> B[parseFrontmatter]:::core
+    B --> C[clean]:::core
+    C --> D[flattenPartials]:::core
+    D --> E[extractVariables]:::core
+    E --> F[lintPrompt]:::core
+  end
+
+  subgraph Output
+    F --> G[generatePromptModule]:::agent
+    F --> H[generateRegistry]:::agent
+  end
+```
+
+## Pipeline Stages
+
+| Stage             | Input                        | Output                             | Description                                             |
+| ----------------- | ---------------------------- | ---------------------------------- | ------------------------------------------------------- |
+| Discover          | Root directories             | `DiscoveredPrompt[]`               | Scans for `.prompt` files (max depth 5)                 |
+| Parse Frontmatter | Raw file content             | `{ name, group, version, schema }` | Extracts and validates YAML metadata                    |
+| Clean             | Raw content                  | Template string                    | Strips frontmatter delimiters                           |
+| Flatten Partials  | Template with `{% render %}` | Resolved template                  | Inlines partial content with bound params               |
+| Extract Variables | Template string              | `string[]`                         | Finds `{{ var }}`, `{% if var %}`, `{% for x in var %}` |
+| Lint              | Schema + variables           | Diagnostics                        | Checks schema/template variable alignment               |
+
+## Generated Output
+
+### Per-Prompt Module (`<name>.ts`)
+
+Each module exports a default object conforming to `PromptModule`:
+
+| Member                | Type                     | Description                                      |
+| --------------------- | ------------------------ | ------------------------------------------------ |
+| `name`                | `string` (const)         | Prompt name from frontmatter                     |
+| `group`               | `string \| undefined`    | Optional grouping key                            |
+| `schema`              | `ZodObject`              | Zod schema built from frontmatter `schema` block |
+| `render(variables)`   | `(Variables) => string`  | Validates input then renders via LiquidJS        |
+| `validate(variables)` | `(unknown) => Variables` | Zod parse only                                   |
+
+### Registry (`index.ts`)
+
+Aggregates all per-prompt modules into a single entry point:
+
+| Export    | Type                  | Description                                                                                            |
+| --------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `prompts` | `PromptRegistry<...>` | Deep-frozen const object with dot-access, nested by group. Use `typeof prompts` for type-level access. |
+
+## Output Directory
+
+Generated files go to the `--out` directory (conventionally `.prompts/client/`). This subdirectory should be gitignored. The parent `.prompts/` directory also holds `partials/` for custom partials (committed to git). Import generated code via the `~prompts` tsconfig alias.
+
+## References
+
+- [File Format](../file-format/overview.md)
+- [Library API](../library/overview.md)
+- [CLI Commands](../cli/commands.md)

package/docs/file-format/frontmatter.md

@@ -0,0 +1,55 @@
+# Frontmatter Reference
+
+The YAML frontmatter block defines metadata and the variable schema for a `.prompt` file. It is delimited by `---` fences at the top of the file.
+
+## Fields
+
+| Field     | Required | Type     | Description                                      |
+| --------- | -------- | -------- | ------------------------------------------------ |
+| `name`    | Yes      | `string` | Unique kebab-case identifier (`^[a-z0-9-]+$`)    |
+| `group`   | No       | `string` | Namespace path (e.g. `agents/coverage-assessor`) |
+| `version` | No       | `string` | Version identifier                               |
+| `schema`  | No       | `object` | Variable declarations map                        |
+
+## Schema Variables
+
+Each key under `schema` declares a template variable. Two syntaxes are supported.
+
+**Shorthand** -- type string only, defaults to required:
+
+```yaml
+schema:
+  scope: string
+```
+
+**Full object** -- explicit control over all fields:
+
+```yaml
+schema:
+  scope:
+    type: string
+    required: true
+    description: Assessment scope
+```
+
+### Variable Fields
+
+| Field         | Default  | Description                                          |
+| ------------- | -------- | ---------------------------------------------------- |
+| `type`        | `string` | Variable type (only `string` supported)              |
+| `required`    | `true`   | Whether the variable must be provided at render time |
+| `description` | --       | Human-readable description (used in generated JSDoc) |
+
+## Validation Rules
+
+- `name` is required and must match `^[a-z0-9-]+$`
+- Frontmatter must be valid YAML between `---` delimiters
+- `schema` must be an object (not an array)
+- Shorthand `scope: string` expands to `{ type: 'string', required: true }`
+- Missing or empty `name` throws a parse error with the file path
+- Non-object frontmatter (e.g. a bare string) is rejected
+
+## References
+
+- [File Format Overview](overview.md)
+- [Code Generation](../codegen/overview.md)

package/docs/file-format/overview.md

@@ -0,0 +1,67 @@
+# .prompt File Format
+
+A `.prompt` file is a LiquidJS template with YAML frontmatter. It is a declarative prompt authoring format compiled to typed TypeScript at build time.
+
+## Anatomy
+
+```text
+---
+name: coverage-assessor
+group: agents/coverage-assessor
+schema:
+  scope:
+    type: string
+    description: Assessment scope
+  target:
+    type: string
+    required: false
+---
+
+You are a coverage assessor for {{ scope }}.
+{% if target %}Targeting {{ target }} docs.{% endif %}
+```
+
+| Section             | Description                                                   |
+| ------------------- | ------------------------------------------------------------- |
+| Frontmatter (`---`) | YAML metadata block defining name, group, and variable schema |
+| Body                | LiquidJS template rendered at runtime with typed variables    |
+
+## Template Language
+
+| Syntax                                  | Purpose                             |
+| --------------------------------------- | ----------------------------------- |
+| `{{ var }}`                             | Variable output                     |
+| `{{ var \| filter }}`                   | Filtered output                     |
+| `{% if var %}...{% endif %}`            | Conditional                         |
+| `{% for item in list %}...{% endfor %}` | Iteration                           |
+| `{% render 'name', key: 'value' %}`     | Partial inclusion (build-time only) |
+
+Strict filters are enabled -- unknown filters throw an error. Variable access is restricted to own properties only.
+
+## Naming Convention
+
+Names must match `^[a-z0-9-]+$` (lowercase, digits, hyphens). The `name` field in frontmatter is required and takes precedence. A file named `prompt.prompt` derives its name from the parent directory (e.g. `agents/gap-detector/prompt.prompt` becomes `gap-detector`).
+
+## Discovery
+
+The CLI scans `--roots` directories recursively (max depth 5). Files must have the `.prompt` extension. Symbolic links are skipped. Duplicate names across roots cause an error with paths listed.
+
+Results are sorted alphabetically by name.
+
+## File Structure
+
+```text
+📁 src/
+├── 📁 agents/
+│   └── 📁 coverage-assessor/
+│       └── 📄 prompt.prompt
+├── 📁 prompts/
+│   ├── 📄 identity.prompt
+│   └── 📄 constraints.prompt
+```
+
+## References
+
+- [Frontmatter Reference](frontmatter.md)
+- [Partials](partials.md)
+- [Author a Prompt](../guides/author-prompt.md)