promptopskit 0.5.0 → 0.6.2

package/README.md

@@ -59,7 +59,7 @@ This creates:
 
 ```
 prompts/
-├── defaults.md         # Folder-level defaults (provider, model, metadata, system instructions)
+├── defaults.md         # Folder-level defaults (provider, model, options, metadata, system instructions)
 ├── hello.md            # Sample prompt with variables
 ├── hello.test.yaml     # Test sidecar with sample inputs and hardcoded responses
 └── shared/
@@ -146,7 +146,7 @@ Supported values for `warnings.contextSize` are `auto`, `off`, `result-only`, `c
 - **Prompts as Markdown** — YAML front matter for settings, H1 headings for sections (`# System instructions`, `# Prompt template`, `# Notes`)
 - **Variable interpolation** — `{{ variable }}` syntax with strict and permissive modes
 - **Composition** — `includes` to share system instructions across prompts, with circular detection
-- **Folder defaults** — `defaults.md` inheritance for shared provider, model, metadata, and system instructions
+- **Folder defaults** — `defaults.md` inheritance for shared provider, model, options, metadata, and system instructions
 - **Overrides** — Environment and tier-based overrides (base → env → tier → runtime)
 - **6 provider adapters** — OpenAI (Chat), OpenAI (Responses), Anthropic, Gemini, OpenRouter, LLMAsAService
 - **Provider-aware input caching controls** — optional `cache` front matter maps to OpenAI prompt cache hints, Anthropic `cache_control`, and Gemini `cachedContent`
@@ -261,7 +261,7 @@ In browser or client-side code, keep provider credentials on the server. Use the
 
 ### Provider-specific fields and raw passthrough
 
-Use normalized fields first (`sampling`, `response`, `cache`, `tools`) so prompts stay portable. `response.schema` is the neutral JSON Schema path; adapters emit it as OpenAI/OpenRouter/LLMAsAService `response_format`, OpenAI Responses `text.format`, Anthropic `output_config.format`, and Gemini `generationConfig.responseJsonSchema`.
+Use normalized fields first (`sampling`, `response`, `cache`, `tools`) so prompts stay portable. `response.schema` is the neutral JSON Schema path; adapters emit it as OpenAI/OpenRouter/LLMAsAService `response_format`, OpenAI Responses `text.format`, Anthropic `output_config.format`, and Gemini `generationConfig.responseJsonSchema`. You can also provide `response.schema_ref` to load schema from a prompt-relative `.json` file or `.js/.mjs/.cjs` zod module (mutually exclusive with `response.schema`).
 
 Use `provider_options` when PromptOpsKit has a known provider-specific mapping, such as Anthropic `top_k`, Gemini's native `response_schema`, OpenRouter routing fields, or LLMAsAService gateway routing/customer metadata.
 
@@ -496,13 +496,15 @@ Handle support requests carefully.
 
 Define a `defaults.md` file in `prompts/` (and optional subfolders) to provide inherited defaults for prompts:
 
-- Shared `provider` and `model` in front matter
+- Shared `provider`, `model`, `fallback_models`, `reasoning`, `sampling`, `response`, `cache`, `provider_options`, `raw`, `tools`, `mcp`, `context`, `includes`, `environments`, and `tiers` in front matter
 - Shared `metadata` defaults in front matter
 - Shared `# System instructions` in body
 - Nearest subfolder `defaults.md` overrides parent defaults
 - Prompt-local values always win over defaults
 - Included files (`includes`) are not affected by folder defaults
 
+Scalars and arrays are replaced by nearer values. Object blocks are shallow-merged, including provider sub-blocks such as `provider_options.llmasaservice` and `cache.openai`.
+
 > `promptopskit init` scaffolds a starter `defaults.md` in the prompts root.
 
 ```text
@@ -630,7 +632,7 @@ Renders a prompt for a specific provider. Returns `{ resolved, request?, returnM
 | `tier` | `string` | Tier override name |
 | `history` | `Array<{ role, content }>` | Conversation history. If the prompt declares `context.history.max_items`, older turns are compacted into one preserved history item before provider rendering. |
 | `toolRegistry` | `Record<string, unknown>` | Tool definitions for resolving string tool references |
-| `strict` | `boolean` | Fail on missing variables |
+| `strict` | `boolean` | Fail on missing variables except object-form inputs marked `optional: true` |
 | `openaiResponses` | `object` | Optional Responses API extras (`previous_response_id`, `conversation`, `instructions`, `parallel_tool_calls`, `max_tool_calls`, `store`, `metadata`, `include`, `background`) |
 
 ### `kit.loadPrompt(path)` / `kit.resolvePrompt(path, options)` / `kit.validatePrompt(path)`
@@ -656,13 +658,13 @@ Prompt files use YAML front matter with these fields:
 | `fallback_models` | `string[]` | Fallback model list |
 | `reasoning` | `object` | `{ effort, budget_tokens }` |
 | `sampling` | `object` | `{ temperature, top_p, frequency_penalty, presence_penalty, stop, max_output_tokens }` |
-| `response` | `object` | `{ format, stream, schema, schema_name, schema_description, schema_strict }` |
+| `response` | `object` | `{ format, stream, schema, schema_ref, schema_name, schema_description, schema_strict }` |
 | `cache` | `object` | Provider-specific cache controls (`openai`, `anthropic`, `gemini`/`google`) |
 | `tools` | `array` | Tool references (string names or inline definitions) |
 | `provider_options` | `object` | Provider-specific non-portable options (`anthropic`, `gemini`, `openrouter`, `llmasaservice`) |
 | `raw` | `object` | Provider-scoped request-body passthrough (`openai`, `openai-responses`, `anthropic`, `gemini`/`google`, `openrouter`, `llmasaservice`) |
 | `mcp` | `object` | MCP server references |
-| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `max_size`, `trim`, structured or literal `allow_regex`/`deny_regex`, built-in `non_empty` / `reject_secrets` validators, and `history.max_items` compaction |
+| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `optional`, `warnings`, `max_size`, `trim`, structured or literal `allow_regex`/`deny_regex`, built-in `non_empty` / `reject_secrets` validators, and `history.max_items` compaction |
 | `includes` | `string[]` | Paths to included prompt files |
 | `environments` | `object` | Named environment overrides |
 | `tiers` | `object` | Named tier overrides |

package/SKILL.md

@@ -387,7 +387,7 @@ the fields required by that specific file:
 | `provider_options` | object | no | Provider-specific advanced options (`anthropic`, `gemini`, `openrouter`, `llmasaservice`) |
 | `raw` | object | no | Provider-scoped request-body passthrough for unmodeled vendor fields |
 | `mcp` | object | no | `{ servers: [string | { name, config }] }` |
-| `context.inputs` | `Array<string | { name, max_size?, trim?, allow_regex?, deny_regex?, non_empty?, reject_secrets? }>` | no | Declared variable names used in templates, with optional size budgets and runtime hardening controls |
+| `context.inputs` | `Array<string | { name, optional?, warnings?, max_size?, trim?, allow_regex?, deny_regex?, non_empty?, reject_secrets? }>` | no | Declared variable names used in templates, with optionality, warning controls, size budgets, and runtime hardening controls |
 | `context.history` | object | no | `{ max_items: number }`; caps rendered history by compacting older turns into one preserved message |
 | `includes` | string[] | no | Relative paths to other prompt files to include |
 | `environments` | object | no | Per-environment overrides (see Overrides) |
@@ -421,6 +421,8 @@ Rules:
 - Before finishing a new prompt file, scan the body for every `{{ variable }}` and
   ensure each exact variable name appears in `context.inputs`
 - Use object-form inputs with `max_size` when a variable is likely to grow large and should trigger early warnings
+- Use `optional: true` when a variable may be absent; strict rendering will not throw for that missing variable
+- Use `warnings: false` sparingly for intentional exceptions that should not emit input-scoped validation or size warnings
 - Use `trim` to enforce byte budgets before interpolation when `max_size` is set
 - Use `allow_regex` for allowlist checks and `deny_regex` for blocklist checks on risky inputs
 - Prefer unquoted `/pattern/i` literals for regex validators so backslash escapes such as `\s` and `\b` stay copyable from regex tools
@@ -442,7 +444,7 @@ context:
       max_size: 4096
 ```
 
-If a rendered value exceeds `max_size`, `renderPrompt()` emits a non-blocking `POK030` warning.
+If a rendered value exceeds `max_size`, `renderPrompt()` emits a non-blocking `POK030` warning unless the input sets `warnings: false`.
 At render time, callers can also pass `onContextOverflow` to transform oversized values before warnings/rendering.
 
 If a validator declares `return_message`, `renderPrompt()` returns that message in a structured result and omits the provider request instead of throwing for that validation failure. Invalid regex definitions still fail during `validate` and `compile` as `POK013` prompt-authoring errors.
@@ -522,28 +524,32 @@ folder:
 
 ```text
 prompts/
-├── defaults.md          # global provider, model, metadata + system instructions
+├── defaults.md          # global provider, model, options, metadata + system instructions
 └── support/
     ├── defaults.md      # overrides for support/*
     └── reply.md         # inherits from support/defaults.md
 ```
 
 Supported default fields:
-- `provider` (front matter) — default provider for the folder
-- `model` (front matter) — default model for the folder
-- `cache` (front matter) — default provider-specific cache hints
+- `provider`, `model`, `fallback_models` (front matter) — default routing
+- `reasoning`, `sampling`, `response` (front matter) — default model behavior
+- `cache`, `provider_options`, `raw` (front matter) — default provider-specific options
+- `tools`, `mcp`, `context`, `includes` (front matter) — default bindings and input/include configuration
+- `environments`, `tiers` (front matter) — default override maps
 - `metadata` (front matter) — merged with prompt-local metadata
 - `# System instructions` (body section) — used when the prompt has none
 
 This lets you configure app-wide settings like `provider` and `model`
 in a single root `defaults.md`, so individual prompts only declare what's unique to them.
 
-Important: `defaults.md` does not declare or infer `context.inputs` for a prompt.
-If a prompt body uses placeholders, the prompt file itself must declare them.
+Important: use shared `context.inputs` in `defaults.md` only when every prompt
+under that folder uses the same placeholders. Prompt-local `context.inputs`
+replace the inherited array.
 
 Rules:
 - Nearest subfolder `defaults.md` overrides parent defaults
 - Prompt-local values always take precedence over defaults
+- Inherited `includes` are authored relative to the `defaults.md` file that declares them
 - `defaults.md` files are skipped during compilation and validation
 - `loadPromptFile` defaults the search boundary to the file's own directory;
   pass `defaultsRoot` to enable ancestor traversal
@@ -889,8 +895,8 @@ Hello {{ name }}
 
 1. **One prompt per file** — each `.md` file is a single prompt asset
 2. **Always set `id` and `schema_version: 1`** unless a surrounding tool explicitly generates those fields
-3. **Declare every placeholder** in `context.inputs`; do not rely on defaults or includes to infer variables
-4. **Use `defaults.md` for shared provider, model, metadata, and fallback system instructions**
+3. **Declare every placeholder** in `context.inputs`; use `defaults.md` only for input declarations that apply to every prompt under that folder
+4. **Use `defaults.md` for shared provider, model, provider options, metadata, and fallback system instructions**
 5. **Use includes for reusable system behavior**, not for user-specific prompt bodies
 6. **Prefer `createPromptOpsKit().renderPrompt()` for server-side app code** when prompts live as source files
 7. **Prefer direct adapters for compiled assets or provider-specific integration points**

package/dist/{chunk-6VLKZCNS.js → chunk-55B7QQBK.js}

@@ -4,7 +4,7 @@ import {
   renderSections,
   resolveAssetForProvider,
   withPromptInputSupport
-} from "./chunk-KN7H4JRK.js";
+} from "./chunk-JR7252DG.js";
 
 // src/providers/openai-responses.ts
 var openaiResponsesAdapter = withPromptInputSupport({
@@ -112,4 +112,4 @@ var openaiResponsesAdapter = withPromptInputSupport({
 export {
   openaiResponsesAdapter
 };
-//# sourceMappingURL=chunk-6VLKZCNS.js.map
+//# sourceMappingURL=chunk-55B7QQBK.js.map

package/dist/{chunk-6BOUQVSX.js → chunk-FNCIBZJF.js}

@@ -1,11 +1,11 @@
 import {
   openaiAdapter
-} from "./chunk-D75HKF64.js";
+} from "./chunk-GLT3YYWK.js";
 import {
   applyRawProviderBody,
   resolveAssetForProvider,
   withPromptInputSupport
-} from "./chunk-KN7H4JRK.js";
+} from "./chunk-JR7252DG.js";
 
 // src/providers/llmasaservice.ts
 var LLMASASERVICE_BASE_URL = "https://gateway.llmasaservice.io";
@@ -127,4 +127,4 @@ export {
   createLLMAsAServiceOpenAIConfig,
   llmasaserviceAdapter
 };
-//# sourceMappingURL=chunk-6BOUQVSX.js.map
+//# sourceMappingURL=chunk-FNCIBZJF.js.map

package/dist/{chunk-D75HKF64.js → chunk-GLT3YYWK.js}

@@ -4,7 +4,7 @@ import {
   renderSections,
   resolveAssetForProvider,
   withPromptInputSupport
-} from "./chunk-KN7H4JRK.js";
+} from "./chunk-JR7252DG.js";
 
 // src/providers/openai.ts
 var openaiAdapter = withPromptInputSupport({
@@ -107,4 +107,4 @@ var openaiAdapter = withPromptInputSupport({
 export {
   openaiAdapter
 };
-//# sourceMappingURL=chunk-D75HKF64.js.map
+//# sourceMappingURL=chunk-GLT3YYWK.js.map

package/dist/{chunk-IN4KT5EU.js → chunk-IPFD5Y3O.js}

@@ -1,11 +1,11 @@
 import {
   openaiAdapter
-} from "./chunk-D75HKF64.js";
+} from "./chunk-GLT3YYWK.js";
 import {
   applyRawProviderBody,
   resolveAssetForProvider,
   withPromptInputSupport
-} from "./chunk-KN7H4JRK.js";
+} from "./chunk-JR7252DG.js";
 
 // src/providers/openrouter.ts
 var openrouterAdapter = withPromptInputSupport({
@@ -58,4 +58,4 @@ var openrouterAdapter = withPromptInputSupport({
 export {
   openrouterAdapter
 };
-//# sourceMappingURL=chunk-IN4KT5EU.js.map
+//# sourceMappingURL=chunk-IPFD5Y3O.js.map