Docs review: align provider examples with app_context runtime variables

PredictabilityAtScale · PredictabilityAtScale · commit 26a27e32befa · 2026-04-19T10:14:03.000-07:00
diff --git a/README.md b/README.md
@@ -59,13 +59,14 @@ sampling:
 context:
   inputs:
     - user_message
+    - app_context
 includes:
   - ./shared/tone.md
 ---
 
 # System instructions
 
-You are a helpful support assistant.
+You are a helpful support assistant working in {{ app_context }}.
 
 # Prompt template
 
@@ -82,7 +83,10 @@ const kit = createPromptOpsKit({ sourceDir: './prompts' });
 const result = await kit.renderPrompt({
   path: 'support/reply',
   provider: 'openai',
-  variables: { user_message: 'How do I reset my password?' },
+  variables: {
+    user_message: 'How do I reset my password?',
+    app_context: 'Account settings page',
+  },
 });
 
 // result.request.body is ready for fetch()
@@ -116,19 +120,35 @@ Each adapter produces a `{ body, provider, model }` object shaped for the target
 // OpenAI
 import { createPromptOpsKit } from 'promptopskit';
 const kit = createPromptOpsKit({ sourceDir: './prompts' });
-const { request } = await kit.renderPrompt({ path: 'hello', provider: 'openai', variables: { name: 'World' } });
+const { request } = await kit.renderPrompt({
+  path: 'hello',
+  provider: 'openai',
+  variables: { name: 'World', app_context: 'Welcome screen' },
+});
 // request.body → { model, messages, temperature, reasoning_effort, ... }
 
 // Anthropic — system is a top-level field, max_tokens defaults to 4096
-const { request } = await kit.renderPrompt({ path: 'hello', provider: 'anthropic', variables: { name: 'World' } });
+const { request } = await kit.renderPrompt({
+  path: 'hello',
+  provider: 'anthropic',
+  variables: { name: 'World', app_context: 'Welcome screen' },
+});
 // request.body → { model, messages, system, max_tokens, ... }
 
 // Gemini — contents/systemInstruction/generationConfig structure
-const { request } = await kit.renderPrompt({ path: 'hello', provider: 'gemini', variables: { name: 'World' } });
+const { request } = await kit.renderPrompt({
+  path: 'hello',
+  provider: 'gemini',
+  variables: { name: 'World', app_context: 'Welcome screen' },
+});
 // request.body → { contents, systemInstruction, generationConfig, ... }
 
 // OpenRouter — same shape as OpenAI, different provider label
-const { request } = await kit.renderPrompt({ path: 'hello', provider: 'openrouter', variables: { name: 'World' } });
+const { request } = await kit.renderPrompt({
+  path: 'hello',
+  provider: 'openrouter',
+  variables: { name: 'World', app_context: 'Welcome screen' },
+});
 ```
 
 Provider adapters are also available as direct imports:
diff --git a/docs/cli.md b/docs/cli.md
@@ -108,6 +108,8 @@ promptopskit render <file> [--env <name>] [--tier <name>] [--vars <file>] [--jso
 
 If no `--vars` file is provided, the command auto-loads a `.test.yaml` sidecar file (same name as the prompt, with `.test.yaml` extension) and uses the first test case's variables.
 
+`--vars` keys map directly to placeholder names in `{{ name }}` syntax.
+
 Readable output:
 ```
 ── support.reply (openai, gpt-5.4) ────────────────────────
diff --git a/docs/composition.md b/docs/composition.md
@@ -2,6 +2,8 @@
 
 `includes` lets you define shared system instructions once and reuse them across prompts. Included instructions are prepended before local system instructions.
 
+Included files can also contain runtime placeholders (`{{ variable }}`), so shared guidance can consume app-specific context passed at render time.
+
 ## How it works
 
 1. List paths in the `includes` front matter field (relative to the prompt file).
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -43,13 +43,14 @@ sampling:
 context:
   inputs:
     - user_message
+    - app_context
 includes:
   - ./shared/tone.md
 ---
 
 # System instructions
 
-You are a helpful support assistant.
+You are a helpful support assistant helping inside {{ app_context }}.
 
 # Prompt template
 
@@ -68,7 +69,10 @@ const kit = createPromptOpsKit({ sourceDir: './prompts' });
 const result = await kit.renderPrompt({
   path: 'support/reply',
   provider: 'openai',
-  variables: { user_message: 'How do I reset my password?' },
+  variables: {
+    user_message: 'How do I reset my password?',
+    app_context: 'Billing settings page',
+  },
 });
 
 // result.request.body is ready for fetch()
diff --git a/docs/prompt-format.md b/docs/prompt-format.md
@@ -65,6 +65,7 @@ Use `{{ mustache }}` syntax for variable interpolation:
 # Prompt template
 
 Hello {{ name }}, welcome to {{ company }}.
+Runtime context: {{ app_context }}.
 ```
 
 Variable names must match `[a-zA-Z_][a-zA-Z0-9_]*`.
@@ -95,6 +96,7 @@ context:
   inputs:
     - name
     - company
+    - app_context
 ```
 
 The validator warns about:
diff --git a/docs/providers.md b/docs/providers.md
@@ -21,7 +21,7 @@ const kit = createPromptOpsKit({ sourceDir: './prompts' });
 const { request } = await kit.renderPrompt({
   path: 'hello',
   provider: 'openai',
-  variables: { name: 'World' },
+  variables: { name: 'World', app_context: 'Welcome screen' },
 });
 
 // request.body is ready for fetch()
diff --git a/fixtures/prompts/hello.md b/fixtures/prompts/hello.md
@@ -6,11 +6,12 @@ model: gpt-5.4
 context:
   inputs:
     - name
+    - app_context
 ---
 
 # System instructions
 
-You are a friendly assistant.
+You are a friendly assistant helping in {{ app_context }}.
 
 # Prompt template
 
diff --git a/fixtures/prompts/hello.test.yaml b/fixtures/prompts/hello.test.yaml
@@ -2,6 +2,8 @@ cases:
   - name: basic
     variables:
       name: "World"
+      app_context: "Onboarding flow"
   - name: named
     variables:
       name: "Alice"
+      app_context: "Dashboard"
diff --git a/fixtures/prompts/support/reply.md b/fixtures/prompts/support/reply.md
@@ -16,6 +16,7 @@ context:
   inputs:
     - user_message
     - account_summary
+    - app_context
   history:
     max_items: 8
 tools:
@@ -42,6 +43,7 @@ metadata:
 # System instructions
 
 You are a careful support assistant. Follow refund policy exactly.
+Current app context: {{ app_context }}.
 
 # Prompt template
 
diff --git a/src/cli/commands/init.ts b/src/cli/commands/init.ts
@@ -19,13 +19,15 @@ model: gpt-5.4
 context:
   inputs:
     - name
+    - app_context
 includes:
   - ./shared/tone.md
 ---
 
 # System instructions
 
 You are a friendly assistant. Be helpful and concise.
+Current app context: {{ app_context }}.
 
 # Prompt template
 
@@ -46,9 +48,11 @@ const TEST_SIDECAR = `cases:
   - name: basic-greeting
     variables:
       name: "World"
+      app_context: "Welcome screen"
   - name: named-greeting
     variables:
       name: "Alice"
+      app_context: "Settings page"
 `;
 
 export async function init(args: string[]): Promise<void> {
diff --git a/tests/interpolate.test.ts b/tests/interpolate.test.ts
@@ -17,6 +17,11 @@ describe('interpolate', () => {
     expect(result).toBe('Bob and Bob');
   });
 
+  it('supports runtime context placeholders by key name', () => {
+    const result = interpolate('Context: {{ app_context }}', { app_context: 'Billing screen' });
+    expect(result).toBe('Context: Billing screen');
+  });
+
   it('leaves missing variables as-is in permissive mode', () => {
     const result = interpolate('Hello {{ name }}!', {});
     expect(result).toBe('Hello {{ name }}!');
@@ -44,6 +49,11 @@ describe('extractVariables', () => {
     expect(vars).toEqual(['name', 'user_id']);
   });
 
+  it('extracts runtime context variables by key name', () => {
+    const vars = extractVariables('Use {{ app_context }} for {{ user_goal }}.');
+    expect(vars).toEqual(['app_context', 'user_goal']);
+  });
+
   it('deduplicates', () => {
     const vars = extractVariables('{{ x }} and {{ x }}');
     expect(vars).toEqual(['x']);
diff --git a/tests/runtime-context-placeholders.test.ts b/tests/runtime-context-placeholders.test.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createPromptOpsKit } from '../src/index.js';
+
+describe('runtime context placeholders across modes', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'pok-context-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('renders {{ key }} placeholders in source-only mode with dev overrides', async () => {
+    const sourceDir = join(tmpDir, 'prompts');
+    await mkdir(sourceDir, { recursive: true });
+
+    await writeFile(join(sourceDir, 'context-aware.md'), `---
+id: context.aware
+schema_version: 1
+provider: openai
+model: gpt-5.4
+environments:
+  dev:
+    model: gpt-5.4-mini
+context:
+  inputs:
+    - app_context
+---
+
+# System instructions
+
+You are helping inside {{ app_context }}.
+
+# Prompt template
+
+User is currently in {{ app_context }}.
+`);
+
+    const kit = createPromptOpsKit({ sourceDir, mode: 'source-only', cache: false });
+    const result = await kit.renderPrompt({
+      path: 'context-aware',
+      provider: 'openai',
+      environment: 'dev',
+      variables: { app_context: 'Billing settings' },
+    });
+
+    expect(result.request.model).toBe('gpt-5.4-mini');
+    const messages = result.request.body.messages as Array<{ role: string; content: string }>;
+    expect(messages[0].content).toContain('Billing settings');
+    expect(messages[1].content).toContain('Billing settings');
+  });
+
+  it('renders {{ key }} placeholders in compiled-only mode with prod overrides', async () => {
+    const sourceDir = join(tmpDir, 'prompts');
+    const compiledDir = join(tmpDir, 'dist');
+    await mkdir(sourceDir, { recursive: true });
+    await mkdir(compiledDir, { recursive: true });
+
+    await writeFile(join(compiledDir, 'context-aware.json'), JSON.stringify({
+      id: 'context.aware',
+      schema_version: 1,
+      provider: 'openai',
+      model: 'gpt-5.4-mini',
+      environments: {
+        prod: { model: 'gpt-5.4' },
+      },
+      context: { inputs: ['app_context'] },
+      sections: {
+        system_instructions: 'You are helping inside {{ app_context }}.',
+        prompt_template: 'User is currently in {{ app_context }}.',
+      },
+    }));
+
+    const kit = createPromptOpsKit({
+      sourceDir,
+      compiledDir,
+      mode: 'compiled-only',
+      cache: false,
+    });
+
+    const result = await kit.renderPrompt({
+      path: 'context-aware',
+      provider: 'openai',
+      environment: 'prod',
+      variables: { app_context: 'Team dashboard' },
+    });
+
+    expect(result.request.model).toBe('gpt-5.4');
+    const messages = result.request.body.messages as Array<{ role: string; content: string }>;
+    expect(messages[0].content).toContain('Team dashboard');
+    expect(messages[1].content).toContain('Team dashboard');
+  });
+});
