@funkai/prompts 0.4.0 → 0.4.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @funkai/prompts@0.4.0 build /home/runner/work/funkai/funkai/packages/prompts
+> @funkai/prompts@0.4.1 build /home/runner/work/funkai/funkai/packages/prompts
 > tsdown && cp -r src/prompts dist/prompts
 
 ℹ tsdown v0.21.4 powered by rolldown v1.0.0-rc.9
@@ -8,13 +8,13 @@
 ℹ target: node22
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/lib/index.mjs                  3.92 kB │ gzip: 1.53 kB
+ℹ dist/lib/index.mjs                  3.99 kB │ gzip: 1.56 kB
 ℹ dist/lib/cli.mjs                    1.39 kB │ gzip: 0.75 kB
 ℹ dist/lib/runtime.mjs                0.08 kB │ gzip: 0.08 kB
-ℹ dist/lib/index.mjs.map              5.72 kB │ gzip: 2.08 kB
+ℹ dist/lib/index.mjs.map              6.42 kB │ gzip: 2.30 kB
 ℹ dist/lib/cli.mjs.map                1.86 kB │ gzip: 0.90 kB
-ℹ dist/lib/engine-CPKs9QbX.mjs.map    1.67 kB │ gzip: 0.85 kB
-ℹ dist/lib/engine-CPKs9QbX.mjs        1.17 kB │ gzip: 0.62 kB
+ℹ dist/lib/engine-Bhv5Zxdu.mjs.map    1.75 kB │ gzip: 0.87 kB
+ℹ dist/lib/engine-Bhv5Zxdu.mjs        1.21 kB │ gzip: 0.64 kB
 ℹ dist/lib/types-DmnHC99v.d.mts.map   0.66 kB │ gzip: 0.34 kB
 ℹ dist/lib/index.d.mts.map            0.45 kB │ gzip: 0.25 kB
 ℹ dist/lib/engine-BAYeiay3.d.mts.map  0.22 kB │ gzip: 0.17 kB
@@ -24,5 +24,5 @@
 ℹ dist/lib/runtime.d.mts              0.08 kB │ gzip: 0.08 kB
 ℹ dist/lib/types-DmnHC99v.d.mts       2.17 kB │ gzip: 0.94 kB
 ℹ dist/lib/engine-BAYeiay3.d.mts      1.08 kB │ gzip: 0.58 kB
-ℹ 16 files, total: 24.62 kB
-✔ Build complete in 2257ms
+ℹ 16 files, total: 25.52 kB
+✔ Build complete in 2824ms

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @funkai/prompts
 
+## 0.4.1
+
+### Patch Changes
+
+- ef51bd7: fix(packages/prompts): enable strictVariables, fix deepFreeze mutation, add @throws docs
+
+  - Add `strictVariables: true` to shared liquid engine — template/schema mismatches now throw instead of silently rendering empty strings
+  - Fix `deepFreeze` to shallow-copy nested namespace objects before freezing (previously mutated caller references)
+  - Replace `for...of` loop in `deepFreeze` with `Object.entries().reduce()`
+  - Add `@throws {ZodError}` documentation to `render()` and `validate()` methods
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -39,7 +39,7 @@ You are a {{ tone }} writer.
 ### Generate typed modules
 
 ```bash
-npx funkai prompts generate --out .prompts/client --roots src/agents
+npx funkai prompts generate --out .prompts/client --includes "src/agents/**"
 ```
 
 ### Consume prompts
@@ -94,8 +94,8 @@ Use `{% render 'name', key: 'value' %}` to include shared partials. Partials res
 
 ## Documentation
 
-For comprehensive documentation, see [docs/overview.md](docs/overview.md).
+For comprehensive documentation, see the [Prompts concept](/concepts/prompts) and [Prompts CLI reference](/reference/prompts/cli).
 
 ## License
 
-[MIT](../../LICENSE)
+[MIT](https://github.com/joggrdocs/funkai/blob/main/LICENSE)

package/dist/lib/cli.mjs

@@ -1,4 +1,4 @@
-import { t as createEngine } from "./engine-CPKs9QbX.mjs";
+import { t as createEngine } from "./engine-Bhv5Zxdu.mjs";
 import { flow } from "es-toolkit";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/lib/engine-BAYeiay3.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-BAYeiay3.d.mts","names":[],"sources":["../../src/engine.ts"],"mappings":";;;;;;AAcA;;;;;;;;iBAAgB,YAAA,CAAa,WAAA,UAAqB,OAAA,GAAU,OAAA,CAAQ,mBAAA,IAAuB,MAAA;;;;;;;AAsB3F;;;cAAa,YAAA,EAAY,MAAA"}
+{"version":3,"file":"engine-BAYeiay3.d.mts","names":[],"sources":["../../src/engine.ts"],"mappings":";;;;;;AAcA;;;;;;;;iBAAgB,YAAA,CAAa,WAAA,UAAqB,OAAA,GAAU,OAAA,CAAQ,mBAAA,IAAuB,MAAA;;;;;;;AAuB3F;;;cAAa,YAAA,EAAY,MAAA"}

package/dist/lib/{engine-CPKs9QbX.mjs → engine-Bhv5Zxdu.mjs}

@@ -18,6 +18,7 @@ function createEngine(partialsDir, options) {
 		cache: true,
 		...options,
 		strictFilters: true,
+		strictVariables: true,
 		ownPropertyOnly: true
 	});
 }
@@ -32,9 +33,10 @@ function createEngine(partialsDir, options) {
 */
 const liquidEngine = new Liquid({
 	strictFilters: true,
+	strictVariables: true,
 	ownPropertyOnly: true
 });
 //#endregion
 export { liquidEngine as n, createEngine as t };
 
-//# sourceMappingURL=engine-CPKs9QbX.mjs.map
+//# sourceMappingURL=engine-Bhv5Zxdu.mjs.map

package/dist/lib/{engine-CPKs9QbX.mjs.map → engine-Bhv5Zxdu.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"engine-CPKs9QbX.mjs","names":[],"sources":["../../src/engine.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    ...options,\n    // Safety defaults — applied after spread so callers cannot disable them\n    strictFilters: true,\n    ownPropertyOnly: true,\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 *\n * @type {Liquid}\n */\nexport const liquidEngine = new Liquid({\n  strictFilters: true,\n  ownPropertyOnly: true,\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,GAAG;EAEH,eAAe;EACf,iBAAiB;EAClB,CAAC;;;;;;;;;;;AAYJ,MAAa,eAAe,IAAI,OAAO;CACrC,eAAe;CACf,iBAAiB;CAClB,CAAC"}
+{"version":3,"file":"engine-Bhv5Zxdu.mjs","names":[],"sources":["../../src/engine.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    ...options,\n    // Safety defaults — applied after spread so callers cannot disable them\n    strictFilters: true,\n    strictVariables: true,\n    ownPropertyOnly: true,\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 *\n * @type {Liquid}\n */\nexport const liquidEngine = new Liquid({\n  strictFilters: true,\n  strictVariables: true,\n  ownPropertyOnly: true,\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,GAAG;EAEH,eAAe;EACf,iBAAiB;EACjB,iBAAiB;EAClB,CAAC;;;;;;;;;;;AAYJ,MAAa,eAAe,IAAI,OAAO;CACrC,eAAe;CACf,iBAAiB;CACjB,iBAAiB;CAClB,CAAC"}

package/dist/lib/index.mjs

@@ -1,4 +1,4 @@
-import { n as liquidEngine } from "./engine-CPKs9QbX.mjs";
+import { n as liquidEngine } from "./engine-Bhv5Zxdu.mjs";
 //#region src/group.ts
 /**
 * Create a prompt group namespace from a record of prompt modules.
@@ -118,9 +118,13 @@ function isPromptModule(value) {
 * @private
 */
 function deepFreeze(obj) {
-	Object.freeze(obj);
-	for (const value of Object.values(obj)) if (typeof value === "object" && value !== null && !Object.isFrozen(value) && !isPromptModule(value)) deepFreeze(value);
-	return obj;
+	const copied = Object.entries(obj).reduce((acc, [key, value]) => {
+		if (typeof value === "object" && value !== null && !isPromptModule(value)) acc[key] = deepFreeze({ ...value });
+		else acc[key] = value;
+		return acc;
+	}, {});
+	Object.freeze(copied);
+	return copied;
 }
 //#endregion
 export { createPrompt, createPromptGroup, createPromptRegistry };

package/dist/lib/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/group.ts","../../src/prompt.ts","../../src/registry.ts"],"sourcesContent":["import type { PromptModule } from \"./types.js\";\n\n/**\n * Create a prompt group namespace from a record of prompt modules.\n *\n * Sets the `group` field on each module to the given group name,\n * producing a new namespace object without mutating the originals.\n *\n * @param name - Group name applied to each prompt (e.g. `'agents'`, `'agents/core'`).\n * @param prompts - Record of prompt modules to group.\n * @returns A new {@link PromptNamespace} with group-tagged prompt modules.\n *\n * @example\n * ```ts\n * import { createPrompt, createPromptGroup } from '@funkai/prompts'\n * import { z } from 'zod'\n *\n * const agents = createPromptGroup('agents', {\n *   greeting: createPrompt({\n *     name: 'greeting',\n *     template: 'Hello {{ name }}!',\n *     schema: z.object({ name: z.string() }),\n *   }),\n * })\n *\n * agents.greeting.render({ name: 'Alice' })\n * ```\n */\nexport function createPromptGroup<T extends Record<string, PromptModule>>(\n  name: string,\n  prompts: T,\n): T {\n  return Object.fromEntries(\n    Object.entries(prompts).map(([key, module]) => [key, { ...module, group: name }]),\n  ) as T;\n}\n","import { liquidEngine } from \"./engine.js\";\nimport type { PromptConfig, PromptModule } from \"./types.js\";\n\n/**\n * Create a prompt module from a config object.\n *\n * Encapsulates template rendering (via LiquidJS) and variable validation\n * (via Zod) into a single {@link PromptModule}. Works for both codegen\n * output and runtime on-the-fly prompt construction.\n *\n * @param config - Prompt configuration with name, template, schema, and optional group.\n * @returns A {@link PromptModule} with `render` and `validate` methods.\n *\n * @example\n * ```ts\n * import { createPrompt } from '@funkai/prompts'\n * import { z } from 'zod'\n *\n * const greeting = createPrompt({\n *   name: 'greeting',\n *   template: 'Hello {{ name }}, welcome to {{ place }}!',\n *   schema: z.object({ name: z.string(), place: z.string() }),\n * })\n *\n * greeting.render({ name: 'Alice', place: 'Wonderland' })\n * // => \"Hello Alice, welcome to Wonderland!\"\n * ```\n */\nexport function createPrompt<T>(config: PromptConfig<T>): PromptModule<T> {\n  const { name, group, template, schema } = config;\n\n  return {\n    name,\n    group,\n    schema,\n    render(variables: T): string {\n      return liquidEngine.parseAndRenderSync(\n        template,\n        schema.parse(variables) as Record<string, unknown>,\n      );\n    },\n    validate(variables: unknown): T {\n      return schema.parse(variables);\n    },\n  };\n}\n","import type { PromptModule, PromptNamespace, PromptRegistry } from \"./types.js\";\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\n// ---------------------------------------------------------------------------\n// Private\n// ---------------------------------------------------------------------------\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 intentionally left unfrozen\n * to avoid breaking Zod internal state.\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  for (const value of Object.values(obj)) {\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,kBACd,MACA,SACG;AACH,QAAO,OAAO,YACZ,OAAO,QAAQ,QAAQ,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,KAAK;EAAE,GAAG;EAAQ,OAAO;EAAM,CAAC,CAAC,CAClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACNH,SAAgB,aAAgB,QAA0C;CACxE,MAAM,EAAE,MAAM,OAAO,UAAU,WAAW;AAE1C,QAAO;EACL;EACA;EACA;EACA,OAAO,WAAsB;AAC3B,UAAO,aAAa,mBAClB,UACA,OAAO,MAAM,UAAU,CACxB;;EAEH,SAAS,WAAuB;AAC9B,UAAO,OAAO,MAAM,UAAU;;EAEjC;;;;;;;;;;;;;;;;;;;;;;;ACvBH,SAAgB,qBAAgD,SAA+B;AAC7F,QAAO,WAAW,EAAE,GAAG,SAAS,CAAC;;;;;;;;AAanC,SAAS,eAAe,OAAuC;AAC7D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,YAAY,SACZ,YAAY,SACZ,UAAU;;;;;;;;;;;;;AAed,SAAS,WAAsC,KAA2B;AACxE,QAAO,OAAO,IAAI;AAClB,MAAK,MAAM,SAAS,OAAO,OAAO,IAAI,CACpC,KACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,OAAO,SAAS,MAAM,IACvB,CAAC,eAAe,MAAM,CAEtB,YAAW,MAAyB;AAGxC,QAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/group.ts","../../src/prompt.ts","../../src/registry.ts"],"sourcesContent":["import type { PromptModule } from \"./types.js\";\n\n/**\n * Create a prompt group namespace from a record of prompt modules.\n *\n * Sets the `group` field on each module to the given group name,\n * producing a new namespace object without mutating the originals.\n *\n * @param name - Group name applied to each prompt (e.g. `'agents'`, `'agents/core'`).\n * @param prompts - Record of prompt modules to group.\n * @returns A new {@link PromptNamespace} with group-tagged prompt modules.\n *\n * @example\n * ```ts\n * import { createPrompt, createPromptGroup } from '@funkai/prompts'\n * import { z } from 'zod'\n *\n * const agents = createPromptGroup('agents', {\n *   greeting: createPrompt({\n *     name: 'greeting',\n *     template: 'Hello {{ name }}!',\n *     schema: z.object({ name: z.string() }),\n *   }),\n * })\n *\n * agents.greeting.render({ name: 'Alice' })\n * ```\n */\nexport function createPromptGroup<T extends Record<string, PromptModule>>(\n  name: string,\n  prompts: T,\n): T {\n  return Object.fromEntries(\n    Object.entries(prompts).map(([key, module]) => [key, { ...module, group: name }]),\n  ) as T;\n}\n","import { liquidEngine } from \"./engine.js\";\nimport type { PromptConfig, PromptModule } from \"./types.js\";\n\n/**\n * Create a prompt module from a config object.\n *\n * Encapsulates template rendering (via LiquidJS) and variable validation\n * (via Zod) into a single {@link PromptModule}. Works for both codegen\n * output and runtime on-the-fly prompt construction.\n *\n * @param config - Prompt configuration with name, template, schema, and optional group.\n * @returns A {@link PromptModule} with `render` and `validate` methods.\n *\n * @example\n * ```ts\n * import { createPrompt } from '@funkai/prompts'\n * import { z } from 'zod'\n *\n * const greeting = createPrompt({\n *   name: 'greeting',\n *   template: 'Hello {{ name }}, welcome to {{ place }}!',\n *   schema: z.object({ name: z.string(), place: z.string() }),\n * })\n *\n * greeting.render({ name: 'Alice', place: 'Wonderland' })\n * // => \"Hello Alice, welcome to Wonderland!\"\n * ```\n */\nexport function createPrompt<T>(config: PromptConfig<T>): PromptModule<T> {\n  const { name, group, template, schema } = config;\n\n  return {\n    name,\n    group,\n    schema,\n    /**\n     * Render the prompt template with the given variables.\n     *\n     * @param variables - Template variables matching the prompt schema.\n     * @returns The rendered prompt string.\n     * @throws {ZodError} If variables fail schema validation.\n     */\n    render(variables: T): string {\n      return liquidEngine.parseAndRenderSync(\n        template,\n        schema.parse(variables) as Record<string, unknown>,\n      );\n    },\n    /**\n     * Validate variables against the prompt schema.\n     *\n     * @param variables - Variables to validate.\n     * @returns The parsed and validated variables.\n     * @throws {ZodError} If variables fail schema validation.\n     */\n    validate(variables: unknown): T {\n      return schema.parse(variables);\n    },\n  };\n}\n","import type { PromptModule, PromptNamespace, PromptRegistry } from \"./types.js\";\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\n// ---------------------------------------------------------------------------\n// Private\n// ---------------------------------------------------------------------------\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 intentionally left unfrozen\n * to avoid breaking Zod internal state.\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  const copied = Object.entries(obj).reduce<Record<string, unknown>>((acc, [key, value]) => {\n    const isNamespace = typeof value === \"object\" && value !== null && !isPromptModule(value);\n    if (isNamespace) {\n      acc[key] = deepFreeze({ ...value } as PromptNamespace);\n    } else {\n      acc[key] = value;\n    }\n    return acc;\n  }, {});\n\n  Object.freeze(copied);\n  return copied as PromptRegistry<T>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,kBACd,MACA,SACG;AACH,QAAO,OAAO,YACZ,OAAO,QAAQ,QAAQ,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,KAAK;EAAE,GAAG;EAAQ,OAAO;EAAM,CAAC,CAAC,CAClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACNH,SAAgB,aAAgB,QAA0C;CACxE,MAAM,EAAE,MAAM,OAAO,UAAU,WAAW;AAE1C,QAAO;EACL;EACA;EACA;EAQA,OAAO,WAAsB;AAC3B,UAAO,aAAa,mBAClB,UACA,OAAO,MAAM,UAAU,CACxB;;EASH,SAAS,WAAuB;AAC9B,UAAO,OAAO,MAAM,UAAU;;EAEjC;;;;;;;;;;;;;;;;;;;;;;;ACrCH,SAAgB,qBAAgD,SAA+B;AAC7F,QAAO,WAAW,EAAE,GAAG,SAAS,CAAC;;;;;;;;AAanC,SAAS,eAAe,OAAuC;AAC7D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,YAAY,SACZ,YAAY,SACZ,UAAU;;;;;;;;;;;;;AAed,SAAS,WAAsC,KAA2B;CACxE,MAAM,SAAS,OAAO,QAAQ,IAAI,CAAC,QAAiC,KAAK,CAAC,KAAK,WAAW;AAExF,MADoB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,eAAe,MAAM,CAEvF,KAAI,OAAO,WAAW,EAAE,GAAG,OAAO,CAAoB;MAEtD,KAAI,OAAO;AAEb,SAAO;IACN,EAAE,CAAC;AAEN,QAAO,OAAO,OAAO;AACrB,QAAO"}

package/dist/lib/runtime.mjs

@@ -1,2 +1,2 @@
-import { n as liquidEngine } from "./engine-CPKs9QbX.mjs";
+import { n as liquidEngine } from "./engine-Bhv5Zxdu.mjs";
 export { liquidEngine };

package/docs/cli/commands.md

@@ -6,14 +6,14 @@ 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                           |
+| Flag         | Alias | Required | Description                               |
+| ------------ | ----- | -------- | ----------------------------------------- |
+| `--out`      | `-o`  | Yes      | Output directory for generated files      |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files |
+| `--silent`   | ---   | No       | Suppress output except errors             |
 
 ```bash
-prompts generate --out .prompts/client --roots prompts src/agents src/workflows
+prompts generate --out .prompts/client --includes "prompts/**" "src/agents/**" "src/workflows/**"
 ```
 
 Custom partials are auto-discovered from the sibling `partials/` directory (relative to `--out`).
@@ -26,7 +26,7 @@ Validate `.prompt` files without generating output.
 
 | Flag         | Alias | Required | Description                                              |
 | ------------ | ----- | -------- | -------------------------------------------------------- |
-| `--roots`    | `-r`  | Yes      | Directories to scan                                      |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files                |
 | `--partials` | `-p`  | No       | Custom partials directory (default: `.prompts/partials`) |
 | `--silent`   | ---   | No       | Suppress output except errors                            |
 
@@ -38,7 +38,7 @@ Validate `.prompt` files without generating output.
 | Warn  | Schema variable not used in template     |
 
 ```bash
-prompts lint --roots prompts src/agents
+prompts lint --includes "prompts/**" "src/agents/**"
 ```
 
 ## `prompts create`

package/docs/cli/overview.md

@@ -61,7 +61,7 @@ Add a generate script to your `package.json`:
 ```json
 {
   "scripts": {
-    "prompts:generate": "prompts generate --out .prompts/client --roots prompts src/agents"
+    "prompts:generate": "prompts generate --out .prompts/client --includes \"prompts/**\" \"src/agents/**\""
   }
 }
 ```

package/docs/cli.md

@@ -0,0 +1,132 @@
+# CLI
+
+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 --includes globs
+    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 Reference
+
+### `prompts generate`
+
+Generate typed TypeScript modules from `.prompt` files.
+
+**Alias:** `gen`
+
+| Flag         | Alias | Required | Description                               |
+| ------------ | ----- | -------- | ----------------------------------------- |
+| `--out`      | `-o`  | Yes      | Output directory for generated files      |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files |
+| `--silent`   | ---   | No       | Suppress output except errors             |
+
+```bash
+prompts generate --out .prompts/client --includes "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                                              |
+| ------------ | ----- | -------- | -------------------------------------------------------- |
+| `--includes` | `-r`  | Yes      | Glob patterns to scan for `.prompt` files                |
+| `--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 --includes "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`)
+
+## Integration
+
+Add a generate script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "prompts:generate": "prompts generate --out .prompts/client --includes \"prompts/**\" \"src/agents/**\""
+  }
+}
+```
+
+## References
+
+- [File Format](file-format.md)
+- [Code Generation & Library](codegen.md)
+- [Setup](setup.md)
+- [Troubleshooting](troubleshooting.md)

package/docs/codegen.md

@@ -0,0 +1,142 @@
+# Code Generation & Library
+
+The CLI transforms `.prompt` source files into typed TypeScript modules. This doc covers the pipeline stages, generated output shape, and the runtime library API.
+
+## 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.
+
+## Runtime Library API
+
+The library surface provides the runtime engine and registry used by generated code and consuming packages.
+
+### Exports
+
+| Export                 | Type                                | Description                                                                |
+| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| `engine`               | `Liquid`                            | Shared LiquidJS instance (no filesystem, strict filters)                   |
+| `createEngine`         | `(partialsDir, options?) => Liquid` | Factory for filesystem-backed engines (used by CLI for partial resolution) |
+| `clean`                | `(content: string) => string`       | Strips frontmatter, returns render-ready template                          |
+| `createPromptRegistry` | `(modules) => PromptRegistry`       | Creates typed registry from prompt module map                              |
+
+### Engine
+
+The shared `engine` instance is configured with `ownPropertyOnly: true` and `strictFilters: true` for security. No filesystem access -- templates are rendered from strings via `parseAndRenderSync`.
+
+`createEngine` accepts a `partialsDir` and optional overrides. It enables filesystem-backed partial resolution (`.prompt` extension, caching enabled) for use during codegen flattening.
+
+### Registry
+
+`createPromptRegistry` accepts a (possibly nested) record of `PromptModule` objects and namespace nodes. It returns a deep-frozen `PromptRegistry` with direct property access:
+
+```ts
+const prompts = createPromptRegistry({
+  agents: { coverageAssessor },
+  greeting,
+});
+prompts.agents.coverageAssessor.render({ scope: "full" });
+prompts.greeting.render();
+```
+
+Nesting is driven by the `group` field in frontmatter. Each `/`-separated segment becomes a nesting level, with all names converted to camelCase. The registry is frozen at creation time to prevent mutation.
+
+## Consumer Import Pattern
+
+The generated `index.ts` calls `createPromptRegistry` with all prompt modules organized by group and exports a `prompts` const object. Consumers import via the `~prompts` tsconfig alias:
+
+```ts
+import { prompts } from "~prompts";
+
+// Flat (no group)
+const text = prompts.greeting.render();
+
+// Nested (group: agents)
+const text = prompts.agents.coverageAssessor.render({ scope: "full" });
+```
+
+Types are inferred from the object structure, giving full type safety on `render` and `validate` arguments at every nesting level.
+
+## Types Reference
+
+| Type                  | Description                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `PromptModule`        | Interface: `name`, `group`, `schema` (ZodType), `render(vars)`, `validate(vars)`                                          |
+| `PromptNamespace`     | A nested namespace node -- values are `PromptModule` leaves or further nested namespaces                                  |
+| `PromptRegistry`      | Deep-readonly mapped type over a `PromptNamespace` tree                                                                   |
+| `CreateEngineOptions` | Options for `createEngine`: `root`, `partials`, `extname`, `cache`, `strictFilters`, `strictVariables`, `ownPropertyOnly` |
+| `Liquid`              | Re-exported LiquidJS engine type                                                                                          |
+
+## References
+
+- [File Format](file-format.md)
+- [CLI](cli.md)

package/docs/file-format/overview.md

@@ -44,7 +44,7 @@ Names must match `^[a-z0-9-]+$` (lowercase, digits, hyphens). The `name` field i
 
 ## 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.
+The CLI scans `--includes` glob patterns 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.
 

package/docs/file-format.md

@@ -0,0 +1,306 @@
+# .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.
+
+## File Anatomy
+
+Every `.prompt` file has two sections: a YAML frontmatter block delimited by `---` fences, and a LiquidJS template body.
+
+```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 Syntax
+
+| 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.
+
+## Frontmatter Reference
+
+The YAML frontmatter block defines metadata and the variable schema.
+
+### 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                        |
+
+### 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)
+- Missing or empty `name` throws a parse error with the file path
+- Non-object frontmatter (e.g. a bare string) is rejected
+
+## 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
+```
+
+Shorthand `scope: string` expands to `{ type: 'string', required: true }`.
+
+### 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) |
+
+## Naming and Discovery
+
+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`).
+
+The CLI scans `--includes` glob patterns 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.
+
+### Recommended File Structure
+
+```text
+src/
+  agents/
+    coverage-assessor/
+      prompt.prompt
+  prompts/
+    identity.prompt
+    constraints.prompt
+```
+
+## Partials
+
+Partials are reusable template fragments included with `{% render %}` tags. They are resolved and flattened at build time -- the generated output contains no render tags.
+
+### Syntax
+
+```liquid
+{% render 'identity', role: 'Coverage Assessor', desc: 'an expert at assessing documentation coverage' %}
+```
+
+Only literal string parameters are supported. Variable references (e.g. `key: myVar`) are not allowed and throw an error at codegen time. Whitespace trim variants `{%-` and `-%}` are supported.
+
+### Resolution Order
+
+Partials are resolved from two locations, searched in order (first match wins):
+
+| Priority | Location             | Description                                      |
+| -------- | -------------------- | ------------------------------------------------ |
+| 1        | `.prompts/partials/` | Custom project partials (committed to git)       |
+| 2        | SDK `src/prompts/`   | Built-in partials shipped with `@funkai/prompts` |
+
+Custom partials take precedence -- a custom partial with the same name as a built-in overrides it.
+
+### Built-in Partials
+
+| Partial       | Parameters                                         | Purpose                                             |
+| ------------- | -------------------------------------------------- | --------------------------------------------------- |
+| `identity`    | `role`, `desc`, `context` (optional)               | Agent identity block (`<identity>` wrapper)         |
+| `constraints` | `in_scope`, `out_of_scope`, `rules` (all optional) | Scoping constraints block (`<constraints>` wrapper) |
+| `tools`       | `tools` (optional)                                 | Tool listing block (`<tools>` wrapper)              |
+
+**identity** source:
+
+```liquid
+<identity>
+You are {{ role }}, {{ desc }}.
+{% if context %}
+{{ context }}
+{% endif %}
+</identity>
+```
+
+**constraints** source:
+
+```liquid
+<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>
+```
+
+### Custom Partials
+
+Place custom `.prompt` files in `.prompts/partials/`:
+
+```text
+.prompts/
+  client/       # Generated (gitignored)
+  partials/     # Custom partials (committed)
+    summary.prompt
+```
+
+The CLI auto-discovers this directory:
+
+- `prompts generate` derives it from `--out` (sibling `partials/` dir)
+- `prompts lint` defaults to `.prompts/partials` (configurable via `--partials`)
+
+**Creating a custom partial:**
+
+```bash
+prompts create summary --partial
+```
+
+Or create `.prompts/partials/<name>.prompt` by hand:
+
+```liquid
+<summary>
+{{ content }}
+{% if notes %}
+Notes: {{ notes }}
+{% endif %}
+</summary>
+```
+
+Use it in a `.prompt` file:
+
+```liquid
+{% render 'summary', content: 'Analysis complete' %}
+```
+
+Run `prompts generate` -- the partial is flattened into the generated output. No `{% render %}` tags remain.
+
+**Overriding built-ins:** Create a file with the same name in `.prompts/partials/` (e.g. `.prompts/partials/identity.prompt`). Custom partials take precedence over SDK built-ins.
+
+**Adding a built-in partial (SDK contributors):**
+
+1. Create `packages/prompts/src/prompts/<name>.prompt`
+2. Write the partial template using XML-style wrapper tags and Liquid variables
+3. Test with a consumer `.prompt` file and run `prompts generate`
+
+## Authoring Walkthrough
+
+### Prerequisites
+
+- `@funkai/prompts` installed
+- Project configured ([Setup guide](setup.md))
+
+### Steps
+
+1. **Scaffold** with the CLI:
+
+```bash
+prompts create my-agent --out src/agents/my-agent
+```
+
+2. **Edit** the frontmatter -- set `name`, `group`, and `schema` variables.
+
+3. **Write** the template body using `{{ var }}` syntax and conditionals.
+
+4. **Add partials** if needed:
+
+```liquid
+{% render 'identity', role: 'Analyzer', desc: 'a code analyzer' %}
+```
+
+5. **Lint:**
+
+```bash
+prompts lint --includes "src/agents/**"
+```
+
+6. **Generate:**
+
+```bash
+prompts generate --out .prompts/client --includes "src/agents/**"
+```
+
+7. **Import and use:**
+
+```ts
+import { prompts } from "~prompts";
+
+const text = prompts.myAgent.render({ scope: "full" });
+```
+
+### Verification
+
+- `prompts lint` reports no errors
+- Generated file exists at `.prompts/client/my-agent.ts`
+- TypeScript compiles without errors
+
+### Troubleshooting
+
+#### Undefined variable error
+
+**Fix:** Add the variable to the frontmatter `schema` block.
+
+#### Duplicate prompt name
+
+**Fix:** Two `.prompt` files share the same `name` -- rename one to a unique kebab-case identifier.
+
+#### TypeScript can't find `~prompts`
+
+**Fix:** Run `prompts setup` or add the path alias to `tsconfig.json`. See [setup.md](setup.md).
+
+#### Variable reference not supported in partial
+
+**Fix:** Only literal string params are allowed in `{% render %}` tags. Replace variable references with string literals.
+
+#### Partial not found
+
+**Fix:** Verify the file is in `.prompts/partials/` (custom) or `src/prompts/` (built-in) with `.prompt` extension.
+
+## References
+
+- [Code Generation & Library](codegen.md)
+- [CLI](cli.md)
+- [Setup](setup.md)

package/docs/guides/author-prompt.md

@@ -26,13 +26,13 @@ prompts create my-agent --out src/agents/my-agent
 5. Lint:
 
 ```bash
-prompts lint --roots src/agents
+prompts lint --includes "src/agents/**"
 ```
 
 6. Generate:
 
 ```bash
-prompts generate --out .prompts/client --roots src/agents
+prompts generate --out .prompts/client --includes "src/agents/**"
 ```
 
 7. Import and use:

package/docs/guides/setup-project.md

@@ -50,7 +50,7 @@ Or configure manually (steps 3-6).
 ```json
 {
   "scripts": {
-    "prompts:generate": "prompts generate --out .prompts/client --roots prompts src/agents"
+    "prompts:generate": "prompts generate --out .prompts/client --includes \"prompts/**\" \"src/agents/**\""
   }
 }
 ```

package/docs/overview.md

@@ -1,4 +1,4 @@
-# Prompts SDK Overview
+# Prompts SDK
 
 Prompt authoring SDK with two surfaces: a **CLI** for build-time code generation from `.prompt` files, and a **library** for runtime template rendering with full type safety.
 
@@ -51,28 +51,6 @@ flowchart LR
   classDef gateway fill:#313244,stroke:#fab387,stroke-width:2px,color:#cdd6f4
 ```
 
-## Package Structure
-
-```
-📁 packages/prompts/
-├── 📁 src/
-│   ├── 📁 prompts/            # Built-in partials (identity, constraints, tools)
-│   ├── 📄 engine.ts           # LiquidJS engine factory
-│   ├── 📄 registry.ts         # Typed prompt registry
-│   ├── 📄 clean.ts            # Frontmatter stripping pipeline
-│   ├── 📄 partials-dir.ts     # PARTIALS_DIR export for CLI/consumers
-│   ├── 📄 types.ts            # PromptModule, PromptNamespace, PromptRegistry types
-│   └── 📄 index.ts            # Public exports
-└── 📁 docs/
-
-📁 packages/cli/               # @funkai/cli — CLI binary (see @funkai/cli README)
-├── 📁 commands/               # generate, lint, create, setup
-├── 📁 src/lib/                # codegen, frontmatter, flatten, lint, paths
-└── 📄 index.ts                # CLI entry point (kidd-cli)
-```
-
-> **Note:** The CLI was extracted to `@funkai/cli`. Install it separately for the `prompts` binary.
-
 ## Dual Surface
 
 | Surface | When       | What                                                                         |
@@ -83,20 +61,15 @@ flowchart LR
 ## Quick Start
 
 1. Create a `.prompt` file with YAML frontmatter and a LiquidJS template body.
-2. Run `prompts generate --out .prompts/client --roots src/agents` to produce typed modules.
+2. Run `prompts generate --out .prompts/client --includes "src/agents/**"` to produce typed modules.
 3. Import from the `~prompts` alias in your application code.
 4. Call `.render({ vars })` with full type safety derived from the Zod schema in frontmatter.
 
-## References
+## Documentation
 
-- [File Format](file-format/overview.md)
-- [Frontmatter](file-format/frontmatter.md)
-- [Partials](file-format/partials.md)
-- [CLI](cli/overview.md)
-- [CLI Commands](cli/commands.md)
-- [Code Generation](codegen/overview.md)
-- [Library API](library/overview.md)
-- [Guide: Author a Prompt](guides/author-prompt.md)
-- [Guide: Setup Project](guides/setup-project.md)
-- [Guide: Add a Partial](guides/add-partial.md)
-- [Troubleshooting](troubleshooting.md)
+| Topic                                   | Description                                                               |
+| --------------------------------------- | ------------------------------------------------------------------------- |
+| [File Format](file-format.md)           | .prompt anatomy, frontmatter, schema variables, partials, authoring guide |
+| [Code Generation & Library](codegen.md) | Build pipeline, generated output, runtime API, consumer patterns          |
+| [Project Setup](setup.md)               | VSCode, .gitignore, tsconfig, package.json configuration                  |
+| [Troubleshooting](troubleshooting.md)   | Common errors and fixes                                                   |

package/docs/setup.md

@@ -0,0 +1,76 @@
+# Setup Prompt Development
+
+## Prerequisites
+
+- Node 24
+- pnpm workspace
+
+## Steps
+
+1. Install:
+
+```bash
+pnpm add @funkai/prompts --workspace
+```
+
+2. Run interactive setup:
+
+```bash
+prompts setup
+```
+
+Or configure manually (steps 3-6).
+
+3. Add VSCode file association in `.vscode/settings.json`:
+
+```json
+{
+  "files.associations": {
+    "*.prompt": "markdown"
+  }
+}
+```
+
+4. Add `.prompts/client/` to `.gitignore`.
+
+5. Add `~prompts` path alias to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "~prompts": ["./.prompts/client/index.ts"]
+    }
+  }
+}
+```
+
+6. Add generate script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "prompts:generate": "prompts generate --out .prompts/client --includes \"prompts/**\" \"src/agents/**\""
+  }
+}
+```
+
+## Verification
+
+Run `prompts generate` and verify `.prompts/client/` directory is created with an `index.ts`.
+
+## Troubleshooting
+
+### VSCode not highlighting `.prompt` files
+
+**Fix:** Check `.vscode/settings.json` file association is set correctly.
+
+### TypeScript can't resolve `~prompts`
+
+**Fix:** Verify `tsconfig.json` paths alias points to `./.prompts/client/index.ts`.
+
+## References
+
+- [CLI](cli.md)
+- [File Format](file-format.md)
+- [Code Generation & Library](codegen.md)

package/docs/troubleshooting.md

@@ -14,7 +14,7 @@
 
 ## Invalid prompt name
 
-**Fix:** Names must match `^[a-z0-9-]+$` — lowercase letters, digits, and hyphens only.
+**Fix:** Names must match `^[a-z0-9-]+$` -- lowercase letters, digits, and hyphens only.
 
 ## Partial variable reference error
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funkai/prompts",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "description": "Prompt SDK with LiquidJS templating and Zod validation",
   "keywords": [
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "es-toolkit": "^1.45.1",
-    "liquidjs": "^10.25.0",
+    "liquidjs": "^10.25.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/engine.ts

@@ -21,6 +21,7 @@ export function createEngine(partialsDir: string, options?: Partial<CreateEngine
     ...options,
     // Safety defaults — applied after spread so callers cannot disable them
     strictFilters: true,
+    strictVariables: true,
     ownPropertyOnly: true,
   });
 }
@@ -36,5 +37,6 @@ export function createEngine(partialsDir: string, options?: Partial<CreateEngine
  */
 export const liquidEngine = new Liquid({
   strictFilters: true,
+  strictVariables: true,
   ownPropertyOnly: true,
 });

package/src/prompt.ts

@@ -33,12 +33,26 @@ export function createPrompt<T>(config: PromptConfig<T>): PromptModule<T> {
     name,
     group,
     schema,
+    /**
+     * Render the prompt template with the given variables.
+     *
+     * @param variables - Template variables matching the prompt schema.
+     * @returns The rendered prompt string.
+     * @throws {ZodError} If variables fail schema validation.
+     */
     render(variables: T): string {
       return liquidEngine.parseAndRenderSync(
         template,
         schema.parse(variables) as Record<string, unknown>,
       );
     },
+    /**
+     * Validate variables against the prompt schema.
+     *
+     * @param variables - Variables to validate.
+     * @returns The parsed and validated variables.
+     * @throws {ZodError} If variables fail schema validation.
+     */
     validate(variables: unknown): T {
       return schema.parse(variables);
     },

package/src/registry.ts

@@ -55,16 +55,16 @@ function isPromptModule(value: unknown): value is PromptModule {
  * @private
  */
 function deepFreeze<T extends PromptNamespace>(obj: T): PromptRegistry<T> {
-  Object.freeze(obj);
-  for (const value of Object.values(obj)) {
-    if (
-      typeof value === "object" &&
-      value !== null &&
-      !Object.isFrozen(value) &&
-      !isPromptModule(value)
-    ) {
-      deepFreeze(value as PromptNamespace);
+  const copied = Object.entries(obj).reduce<Record<string, unknown>>((acc, [key, value]) => {
+    const isNamespace = typeof value === "object" && value !== null && !isPromptModule(value);
+    if (isNamespace) {
+      acc[key] = deepFreeze({ ...value } as PromptNamespace);
+    } else {
+      acc[key] = value;
     }
-  }
-  return obj as PromptRegistry<T>;
+    return acc;
+  }, {});
+
+  Object.freeze(copied);
+  return copied as PromptRegistry<T>;
 }

package/tsconfig.json

@@ -5,21 +5,28 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "lib": ["ES2024"],
+    "types": ["node"],
+
     "strict": true,
-    "esModuleInterop": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
+
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
+
     "outDir": "./dist",
     "rootDir": ".",
     "paths": {
       "@/*": ["./src/*"]
-    },
-    "types": ["node"]
+    }
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist"]