FEATURE: Context input arguments now support max_size to warn and validate when context limits are excessive

Author: PredictabilityAtScale

README.md

@@ -63,7 +63,8 @@ sampling:
 context:
   inputs:
     - user_message
-    - app_context
+    - name: app_context
+      max_size: 2000
 includes:
   - ./shared/tone.md
 ---
@@ -104,6 +105,19 @@ const response = await fetch('https://api.openai.com/v1/chat/completions', {
 });
 ```
 
+You can control context size warning behavior at the kit level:
+
+```typescript
+const kit = createPromptOpsKit({
+  sourceDir: './prompts',
+  warnings: {
+    contextSize: process.env.NODE_ENV === 'production' ? 'off' : 'console-and-result',
+  },
+});
+```
+
+Supported values for `warnings.contextSize` are `auto`, `off`, `result-only`, `console`, and `console-and-result`.
+
 ## Features
 
 - **Prompts as Markdown** — YAML front matter for settings, H1 headings for sections (`# System instructions`, `# Prompt template`, `# Notes`)
@@ -113,6 +127,8 @@ const response = await fetch('https://api.openai.com/v1/chat/completions', {
 - **Overrides** — Environment and tier-based overrides (base → env → tier → runtime)
 - **4 provider adapters** — OpenAI, Anthropic, Gemini, OpenRouter — body-only output
 - **Validation** — Zod schema validation, Levenshtein-based "did you mean?" for typos, variable usage checks
+- **Context size guardrails** — optional per-input `max_size` metadata with non-blocking render-time warnings
+- **Warning controls** — top-level config can suppress or emit context size warnings differently in dev and prod
 - **Caching** — LRU cache with mtime-based invalidation
 - **CLI** — init, validate, compile, render, inspect, skill
 - **Compiled artifacts** — Pre-compile `.md` → JSON or ESM for production
@@ -333,6 +349,7 @@ Creates a `PromptOpsKit` instance.
 | `compiledDir` | `string` | — | Path to compiled artifacts |
 | `mode` | `'auto' \| 'compiled-only' \| 'source-only'` | `'auto'` | Resolution strategy |
 | `cache` | `boolean` | `true` | Enable LRU cache with mtime invalidation |
+| `warnings.contextSize` | `'auto' \| 'off' \| 'result-only' \| 'console' \| 'console-and-result'` | `'auto'` | Control whether render-time context size warnings are returned, logged, both, or suppressed |
 
 ### `kit.renderPrompt(options)`
 
@@ -347,6 +364,7 @@ Renders a prompt for a specific provider. Returns `{ resolved, request, warnings
 | `environment` | `string` | Environment override name |
 | `tier` | `string` | Tier override name |
 | `history` | `Array<{ role, content }>` | Conversation history |
+| `toolRegistry` | `Record<string, unknown>` | Tool definitions for resolving string tool references |
 | `strict` | `boolean` | Fail on missing variables |
 
 ### `kit.loadPrompt(path)` / `kit.resolvePrompt(path, options)` / `kit.validatePrompt(path)`
@@ -375,7 +393,7 @@ Prompt files use YAML front matter with these fields:
 | `response` | `object` | `{ format, stream }` |
 | `tools` | `array` | Tool references (string names or inline definitions) |
 | `mcp` | `object` | MCP server references |
-| `context` | `object` | `{ inputs, history }` — declare expected variables |
+| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `max_size` budgets |
 | `includes` | `string[]` | Paths to included prompt files |
 | `environments` | `object` | Named environment overrides |
 | `tiers` | `object` | Named tier overrides |

SKILL.md

@@ -29,7 +29,8 @@ provider: openai
 model: gpt-5.4
 context:
   inputs:
-    - name
+    - name: name
+      max_size: 2000
 ---
 
 # System instructions
@@ -65,7 +66,7 @@ the fields required by that specific file:
 | `response` | object | no | `{ format: text|json|markdown, stream: boolean }` |
 | `tools` | array | no | Tool names (strings) or inline definitions with `{ name, description, input_schema }` |
 | `mcp` | object | no | `{ servers: [string | { name, config }] }` |
-| `context.inputs` | string[] | no | Declared variable names used in templates |
+| `context.inputs` | `Array<string | { name, max_size? }>` | no | Declared variable names used in templates, with optional size budgets |
 | `context.history` | object | no | `{ max_items: number }` |
 | `includes` | string[] | no | Relative paths to other prompt files to include |
 | `environments` | object | no | Per-environment overrides (see Overrides) |
@@ -98,10 +99,23 @@ Rules:
 - Declare all variables in `context.inputs` — validation warns on undeclared usage
 - 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
 - Escape literal braces with `\{{` and `\}}`
 - In strict mode, missing variables throw an error
 - In permissive mode, unresolved placeholders are left intact
 
+Example with a size budget:
+
+```yaml
+context:
+  inputs:
+    - user_message
+    - name: account_summary
+      max_size: 4096
+```
+
+If a rendered value exceeds `max_size`, `renderPrompt()` emits a non-blocking `POK030` warning.
+
 Example: this is the minimal valid shape for a prompt that references
 `{{ pull_request }}` even when provider/model are inherited from defaults:
 
@@ -238,19 +252,32 @@ import { createPromptOpsKit } from 'promptopskit';
 const kit = createPromptOpsKit({ sourceDir: './prompts' });
 
 // Load → resolve includes → apply overrides → render
-const request = await kit.renderPrompt('greeting', {
+const result = await kit.renderPrompt({
+  path: 'greeting',
+  provider: 'openai',
   variables: { name: 'Alice' },
   environment: 'production',
 });
 
-// request.body is ready for the provider's API
+// result.request.body is ready for the provider's API
 const response = await fetch('https://api.openai.com/v1/chat/completions', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
     Authorization: `Bearer ${apiKey}`,
   },
-  body: JSON.stringify(request.body),
+  body: JSON.stringify(result.request.body),
+});
+```
+
+You can control render-time context size warnings at the top level:
+
+```typescript
+const kit = createPromptOpsKit({
+  sourceDir: './prompts',
+  warnings: {
+    contextSize: process.env.NODE_ENV === 'production' ? 'off' : 'console-and-result',
+  },
 });
 ```
 
@@ -307,7 +334,7 @@ const asset = parsePrompt(source);
 const result = validateAsset(asset);
 
 if (!result.valid) {
-  console.error(result.errors); // Error codes: POK001-POK021
+  console.error(result.errors); // Validation error codes: POK001-POK021
 }
 ```
 

docs/api-reference.md

@@ -12,6 +12,9 @@ const kit = createPromptOpsKit({
   compiledDir: './dist/prompts',
   mode: 'auto',
   cache: true,
+  warnings: {
+    contextSize: 'auto',
+  },
 });
 ```
 
@@ -21,6 +24,7 @@ const kit = createPromptOpsKit({
 | `compiledDir` | `string` | — | Path to compiled artifacts |
 | `mode` | `'auto' \| 'compiled-only' \| 'source-only'` | `'auto'` | Resolution strategy |
 | `cache` | `boolean` | `true` | Enable LRU cache with mtime invalidation |
+| `warnings.contextSize` | `'auto' \| 'off' \| 'result-only' \| 'console' \| 'console-and-result'` | `'auto'` | Control whether render-time context size warnings are returned, logged, both, or suppressed |
 
 ### Resolution modes
 
@@ -69,10 +73,12 @@ Either `path` or `source` must be provided.
 interface RenderResult {
   resolved: ResolvedPromptAsset;  // Fully resolved asset
   request: ProviderRequest;       // { body, provider, model }
-  warnings: string[];             // Non-fatal provider warnings
+  warnings: string[];             // Non-fatal provider and render-time warnings
 }
 ```
 
+`warnings` may include provider adapter warnings and render-time `POK030` context size warnings when configured to be included in results.
+
 ## `kit.loadPrompt(path)`
 
 Load a prompt asset from compiled or source (based on mode). Returns a `PromptAsset`.
@@ -101,6 +107,8 @@ const result = await kit.validatePrompt('support/reply');
 // { valid: boolean, errors: ValidationError[], warnings: ValidationError[] }
 ```
 
+`validatePrompt()` covers schema, include-graph, and variable declaration issues. Render-time context size warnings are produced by `renderPrompt()`, not validation.
+
 ## `kit.clearCache()`
 
 Clear the internal LRU cache.
@@ -234,6 +242,7 @@ const result = await renderPrompt({
   provider: 'openai',
   variables: { name: 'World' },
   sourceDir: './prompts',  // defaults to '.'
+  warnings: { contextSize: 'result-only' },
 });
 ```
 

docs/getting-started.md

@@ -87,6 +87,17 @@ const response = await fetch('https://api.openai.com/v1/chat/completions', {
 });
 ```
 
+To make context size warnings loud in development and silent in production, configure the kit once:
+
+```typescript
+const kit = createPromptOpsKit({
+  sourceDir: './prompts',
+  warnings: {
+    contextSize: process.env.NODE_ENV === 'production' ? 'off' : 'console-and-result',
+  },
+});
+```
+
 `renderPrompt` returns `{ resolved, request, warnings }`:
 
 | Field | Type | Description |

docs/prompt-format.md

@@ -160,13 +160,21 @@ context:
   inputs:
     - name
     - company
-    - app_context
+    - name: app_context
+      max_size: 2000
 ```
 
+Each entry can be either a string variable name or an object with:
+
+- `name` — the template variable name
+- `max_size` — optional UTF-8 byte limit for the injected value
+
 The validator warns about:
 - Variables used in templates but not declared in `context.inputs`
 - Variables declared in `context.inputs` but never used
 
+At render time, PromptOpsKit also emits a non-blocking `POK030` warning when a provided variable exceeds its declared `max_size`. In source and auto modes, the warning is also written to `console.warn` to make local development issues visible early.
+
 ## Minimal example
 
 The simplest valid prompt:
@@ -204,7 +212,8 @@ response:
 context:
   inputs:
     - user_message
-    - account_summary
+    - name: account_summary
+      max_size: 8000
   history:
     max_items: 8
 tools:

docs/schema.md

@@ -131,17 +131,29 @@ mcp:
 context:
   inputs:
     - user_message
-    - account_summary
+    - name: account_summary
+      max_size: 4096
   history:
     max_items: 8
 ```
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `inputs` | `string[]` | Expected variable names (used for validation) |
+| `inputs` | `Array<string | { name, max_size? }>` | Expected variable names, optionally with a UTF-8 byte budget for render-time warnings |
 | `history` | `object` | History settings |
 | `history.max_items` | `number` | Maximum history items |
 
+String-form inputs remain valid:
+
+```yaml
+context:
+  inputs:
+    - user_message
+    - account_summary
+```
+
+Object-form inputs add optional `max_size`, which is checked during `renderPrompt()` and can produce a `POK030` warning when the injected value exceeds the declared budget.
+
 ## `includes`
 
 ```yaml

docs/validation.md

@@ -1,6 +1,6 @@
 # Validation
 
-PromptOpsKit validates prompts at multiple levels — schema structure, front matter keys, variable usage, and include graphs.
+PromptOpsKit validates prompts at multiple levels — schema structure, front matter keys, variable usage, and include graphs. Render-time context size limits are checked separately during prompt rendering.
 
 ## Quick start
 
@@ -18,6 +18,12 @@ const result = await kit.validatePrompt('support/reply');
 // { valid: boolean, errors: ValidationError[], warnings: ValidationError[] }
 ```
 
+`validatePrompt()` does not execute render-time context size checks. Those warnings are produced by `renderPrompt()` when variables are provided.
+
+## Render-time warnings
+
+`renderPrompt()` can emit `POK030` when a provided variable exceeds the `max_size` declared for a context input.
+
 ## Error codes
 
 | Code | Severity | Description |
@@ -58,6 +64,36 @@ context:
 Hello {{ name }} from {{ company }}!   <!-- POK011 warning: company used but not declared -->
 ```
 
+Object-form inputs can also declare size limits:
+
+```yaml
+context:
+  inputs:
+    - name: account_summary
+      max_size: 4096
+```
+
+If `account_summary` is rendered with a value larger than 4096 UTF-8 bytes, `renderPrompt()` returns a `POK030` warning. In source and auto modes, PromptOpsKit also writes the warning to `console.warn` so oversized context is visible during local development.
+
+You can override that behavior at the kit level:
+
+```typescript
+const kit = createPromptOpsKit({
+  sourceDir: './prompts',
+  warnings: {
+    contextSize: 'off',
+  },
+});
+```
+
+`warnings.contextSize` supports:
+
+- `auto` — default behavior; include in `renderPrompt().warnings`, and log to console outside `compiled-only`
+- `off` — suppress context size warnings entirely
+- `result-only` — return warnings but do not log them
+- `console` — log warnings but do not include them in the returned `warnings` array
+- `console-and-result` — log and return warnings in all modes
+
 ## Include validation
 
 `validateAssetWithIncludes` resolves the full include graph and catches: