FIX: Allow environment and tier to be passed to providers with compiled prompts

Author: PredictabilityAtScale

README.md

@@ -182,6 +182,29 @@ import { geminiAdapter } from 'promptopskit/gemini';
 import { openrouterAdapter } from 'promptopskit/openrouter';
 ```
 
+Direct adapter rendering also accepts `environment` and `tier` selectors. This is useful for compiled JSON/ESM assets in browser, edge, or worker code:
+
+```typescript
+import type { ResolvedPromptAsset } from 'promptopskit';
+import { openaiAdapter } from 'promptopskit/openai';
+import compiledPrompt from './dist/prompts/summarizePullRequest.mjs';
+
+const prompt = compiledPrompt as ResolvedPromptAsset;
+
+const validation = openaiAdapter.validate(prompt, { environment: 'dev' });
+if (!validation.valid) {
+  throw new Error(validation.errors.join(' '));
+}
+
+const request = openaiAdapter.render(prompt, {
+  environment: 'dev',
+  variables: {
+    pull_request_body: 'Implement theming and dark mode across the app.',
+  },
+  strict: true,
+});
+```
+
 ## Optional UsageTap Tracking
 
 PromptOpsKit can also help you track provider calls with UsageTap.com while keeping the core render API body-only.

SKILL.md

@@ -281,6 +281,55 @@ const kit = createPromptOpsKit({
 });
 ```
 
+### Browser / client-side demos
+
+For browser code, client components, or frontend-only demos:
+
+- Do not import `createPromptOpsKit`, `loadPromptFile`, or other top-level runtime helpers from `promptopskit` in client code. The top-level entry loads Node file-system/path modules for source and compiled prompt loading.
+- Instead, use a precompiled prompt artifact or an inlined `ResolvedPromptAsset` object and render it with a provider subpath adapter such as `promptopskit/openai`.
+- If the prompt lives in files, compile it ahead of time with `npx promptopskit compile ./prompts ./dist/prompts --format esm` and import the generated ESM artifact into the client.
+- Provider adapters accept `environment` and `tier` in `validate()` and `render()`, so use those options directly when selecting overrides for compiled or inline assets.
+- For small demos, it is acceptable to inline the resolved prompt asset directly in the client file.
+- Keep transport and auth in the application layer. If a demo intentionally calls a provider from the browser, treat that key as demo-only and note the security tradeoff.
+
+Example:
+
+```typescript
+import type { ResolvedPromptAsset } from 'promptopskit';
+import { openaiAdapter } from 'promptopskit/openai';
+
+const prompt: ResolvedPromptAsset = {
+  id: 'summarizePullRequest',
+  schema_version: 1,
+  provider: 'openai',
+  model: 'gpt-5.4',
+  context: {
+    inputs: [{ name: 'pull_request_body', max_size: 8000 }],
+  },
+  sections: {
+    system_instructions: 'You summarize pull requests clearly and concisely.',
+    prompt_template: 'Summarize this pull request:\n\n{{ pull_request_body }}',
+  },
+};
+
+const validation = openaiAdapter.validate(prompt, {
+  environment: 'prod',
+});
+if (!validation.valid) {
+  throw new Error(validation.errors.join(' '));
+}
+
+const request = openaiAdapter.render(prompt, {
+  environment: 'prod',
+  variables: {
+    pull_request_body: 'Add theming and dark mode support to the application.',
+  },
+  strict: true,
+});
+
+// request.body is ready for the OpenAI SDK or fetch.
+```
+
 ### Step-by-step API
 
 ```typescript

docs/api-reference.md

@@ -226,10 +226,16 @@ Get a provider adapter by name.
 
 ```typescript
 const adapter = getAdapter('openai');
-const validation = adapter.validate(resolvedAsset);
-const request = adapter.render(resolvedAsset, { variables: { name: 'World' } });
+const validation = adapter.validate(resolvedAsset, { environment: 'dev' });
+const request = adapter.render(resolvedAsset, {
+  environment: 'dev',
+  tier: 'pro',
+  variables: { name: 'World' },
+});
 ```
 
+`RuntimeRenderOptions` for direct adapter rendering supports `environment`, `tier`, `runtime`, `variables`, `history`, `toolRegistry`, and `strict`.
+
 ## Standalone `renderPrompt`
 
 A convenience wrapper that creates a temporary `PromptOpsKit` instance:

docs/providers.md

@@ -45,11 +45,63 @@ Each adapter implements the `ProviderAdapter` interface:
 ```typescript
 interface ProviderAdapter {
   name: string;
-  validate(asset: ResolvedPromptAsset): ValidationResult;
+  validate(asset: ResolvedPromptAsset, runtime?: RuntimeRenderOptions): ValidationResult;
   render(asset: ResolvedPromptAsset, runtime: RuntimeRenderOptions): ProviderRequest;
 }
 ```
 
+Direct adapter rendering accepts the same `environment` and `tier` selectors as `kit.renderPrompt()`. This is especially useful with compiled JSON/ESM assets in browser, edge, or worker code.
+
+## Browser / client-side usage
+
+The top-level `promptopskit` runtime is Node-oriented. It supports prompt loading and compilation flows that import file-system/path modules, so do not use `createPromptOpsKit()` inside browser-only code or client components.
+
+For frontend demos or browser rendering:
+
+- Precompile prompts to ESM with `promptopskit compile ./prompts ./dist/prompts --format esm` and import the generated artifact, or
+- Inline a `ResolvedPromptAsset` object directly in the client bundle for a small demo.
+- Pass `environment` and `tier` directly to `adapter.validate()` and `adapter.render()` when you need overrides on the client side.
+
+Then render with a provider subpath adapter:
+
+```typescript
+import type { ResolvedPromptAsset } from 'promptopskit';
+import { openaiAdapter } from 'promptopskit/openai';
+
+const prompt: ResolvedPromptAsset = {
+  id: 'summarizePullRequest',
+  schema_version: 1,
+  provider: 'openai',
+  model: 'gpt-5.4',
+  context: {
+    inputs: [{ name: 'pull_request_body', max_size: 8000 }],
+  },
+  sections: {
+    system_instructions: 'You summarize pull requests clearly and concisely.',
+    prompt_template: 'Summarize this pull request:\n\n{{ pull_request_body }}',
+  },
+};
+
+const validation = openaiAdapter.validate(prompt, {
+  environment: 'prod',
+});
+if (!validation.valid) {
+  throw new Error(validation.errors.join(' '));
+}
+
+const { body } = openaiAdapter.render(prompt, {
+  environment: 'prod',
+  variables: {
+    pull_request_body: 'Implement theming and dark mode across the app.',
+  },
+  strict: true,
+});
+
+// Send `body` with the OpenAI SDK or fetch.
+```
+
+This pattern keeps PromptOpsKit responsible for prompt rendering while leaving HTTP transport, auth, and browser-specific safety decisions in the app.
+
 ## Optional UsageTap tracking
 
 If you want UsageTap begin/end tracking around a provider call, use the optional `promptopskit/usagetap` helper layer.
@@ -220,6 +272,9 @@ Each adapter validates the asset before rendering. Common checks:
 
 ```typescript
 const adapter = getAdapter('openai');
-const validation = adapter.validate(resolvedAsset);
+const validation = adapter.validate(resolvedAsset, {
+  environment: 'dev',
+  tier: 'pro',
+});
 // { valid: boolean, errors: string[], warnings: string[] }
 ```

src/cli/commands/defaults-root.ts

@@ -0,0 +1,24 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export function findDefaultsRoot(filePath: string): string {
+  let current = resolve(dirname(filePath));
+  let root = current;
+  let foundDefaults = false;
+
+  while (true) {
+    if (existsSync(join(current, 'defaults.md'))) {
+      root = current;
+      foundDefaults = true;
+    } else if (foundDefaults) {
+      return root;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return root;
+    }
+
+    current = parent;
+  }
+}

src/cli/commands/inspect.ts

@@ -1,5 +1,6 @@
 import { loadPromptFile } from '../../parser/index.js';
 import { resolveIncludes } from '../../composition/index.js';
+import { findDefaultsRoot } from './defaults-root.js';
 
 const HELP = `
 promptopskit inspect <file>
@@ -22,7 +23,8 @@ export async function inspect(args: string[]): Promise<void> {
     process.exit(1);
   }
 
-  const { asset: parsed } = await loadPromptFile(file);
+  const defaultsRoot = findDefaultsRoot(file);
+  const { asset: parsed } = await loadPromptFile(file, { defaultsRoot });
 
   // Resolve includes so the output shows the fully resolved asset
   const asset = (parsed.includes && parsed.includes.length > 0)

src/cli/commands/render.ts

@@ -4,6 +4,7 @@ import { loadPromptFile } from '../../parser/index.js';
 import { resolveIncludes } from '../../composition/index.js';
 import { applyOverrides } from '../../overrides/index.js';
 import { interpolate } from '../../renderer/interpolate.js';
+import { findDefaultsRoot } from './defaults-root.js';
 
 const HELP = `
 promptopskit render <file> [options]
@@ -56,7 +57,8 @@ export async function render(args: string[]): Promise<void> {
     }
   }
 
-  const { asset: parsed } = await loadPromptFile(file);
+  const defaultsRoot = findDefaultsRoot(file);
+  const { asset: parsed } = await loadPromptFile(file, { defaultsRoot });
 
   // Resolve includes (matching the library pipeline)
   const resolved = (parsed.includes && parsed.includes.length > 0)

src/index.ts

@@ -10,7 +10,7 @@ import { getAdapter } from './providers/index.js';
 import { validateAsset } from './validation/index.js';
 import { PromptCache } from './cache.js';
 import { collectContextSizeWarnings } from './context.js';
-import type { PromptAsset, ResolvedPromptAsset } from './schema/index.js';
+import type { PromptAsset, PromptAssetOverrides, ResolvedPromptAsset } from './schema/index.js';
 import type { ProviderRequest, RuntimeRenderOptions } from './providers/types.js';
 import type { PromptValidationResult } from './validation/index.js';
 
@@ -94,6 +94,8 @@ export interface RenderPromptOptions {
   environment?: string;
   /** Tier override */
   tier?: string;
+  /** Runtime overrides applied after environment and tier */
+  runtime?: Partial<PromptAssetOverrides>;
   /** Variables for interpolation */
   variables?: Record<string, string>;
   /** Conversation history */
@@ -236,7 +238,7 @@ export class PromptOpsKit {
    */
   async resolvePrompt(
     promptPath: string,
-    options: { environment?: string; tier?: string } = {},
+    options: { environment?: string; tier?: string; runtime?: Partial<PromptAssetOverrides> } = {},
   ): Promise<ResolvedPromptAsset> {
     let asset = await this.loadPrompt(promptPath);
 
@@ -250,6 +252,7 @@ export class PromptOpsKit {
     asset = applyOverrides(asset, {
       environment: options.environment,
       tier: options.tier,
+      runtime: options.runtime,
     });
 
     return asset as ResolvedPromptAsset;
@@ -267,12 +270,14 @@ export class PromptOpsKit {
       const overridden = applyOverrides(asset, {
         environment: options.environment,
         tier: options.tier,
+        runtime: options.runtime,
       });
       resolved = overridden as ResolvedPromptAsset;
     } else if (options.path) {
       resolved = await this.resolvePrompt(options.path, {
         environment: options.environment,
         tier: options.tier,
+        runtime: options.runtime,
       });
     } else {
       throw new Error('Either "path" or "source" must be provided to renderPrompt()');

src/providers/anthropic.ts

@@ -6,6 +6,7 @@ import type {
   RuntimeRenderOptions,
 } from './types.js';
 import { renderSections } from '../renderer/index.js';
+import { resolveAssetForProvider } from './resolve-asset.js';
 
 /**
  * Anthropic provider adapter.
@@ -14,29 +15,31 @@ import { renderSections } from '../renderer/index.js';
 export const anthropicAdapter: ProviderAdapter = {
   name: 'anthropic',
 
-  validate(asset: ResolvedPromptAsset): ValidationResult {
+  validate(asset: ResolvedPromptAsset, runtime?: RuntimeRenderOptions): ValidationResult {
+    const resolvedAsset = resolveAssetForProvider(asset, runtime);
     const errors: string[] = [];
     const warnings: string[] = [];
 
-    if (!asset.model) {
+    if (!resolvedAsset.model) {
       errors.push('Anthropic adapter requires a model to be specified.');
     }
 
-    if (asset.sampling?.frequency_penalty !== undefined) {
+    if (resolvedAsset.sampling?.frequency_penalty !== undefined) {
       warnings.push('Anthropic does not support frequency_penalty. It will be ignored.');
     }
-    if (asset.sampling?.presence_penalty !== undefined) {
+    if (resolvedAsset.sampling?.presence_penalty !== undefined) {
       warnings.push('Anthropic does not support presence_penalty. It will be ignored.');
     }
-    if (asset.reasoning?.effort !== undefined) {
+    if (resolvedAsset.reasoning?.effort !== undefined) {
       warnings.push('Anthropic uses budget_tokens for thinking, not effort. effort will be mapped approximately.');
     }
 
     return { valid: errors.length === 0, errors, warnings };
   },
 
   render(asset: ResolvedPromptAsset, runtime: RuntimeRenderOptions): ProviderRequest {
-    const sections = renderSections(asset, {
+    const resolvedAsset = resolveAssetForProvider(asset, runtime);
+    const sections = renderSections(resolvedAsset, {
       variables: runtime.variables,
       strict: runtime.strict,
     });
@@ -56,7 +59,7 @@ export const anthropicAdapter: ProviderAdapter = {
     }
 
     const body: Record<string, unknown> = {
-      model: asset.model,
+      model: resolvedAsset.model,
       messages,
     };
 
@@ -66,32 +69,32 @@ export const anthropicAdapter: ProviderAdapter = {
     }
 
     // Sampling params
-    if (asset.sampling?.temperature !== undefined) body.temperature = asset.sampling.temperature;
-    if (asset.sampling?.top_p !== undefined) body.top_p = asset.sampling.top_p;
-    if (asset.sampling?.stop !== undefined) body.stop_sequences = asset.sampling.stop;
-    if (asset.sampling?.max_output_tokens !== undefined) {
-      body.max_tokens = asset.sampling.max_output_tokens;
+    if (resolvedAsset.sampling?.temperature !== undefined) body.temperature = resolvedAsset.sampling.temperature;
+    if (resolvedAsset.sampling?.top_p !== undefined) body.top_p = resolvedAsset.sampling.top_p;
+    if (resolvedAsset.sampling?.stop !== undefined) body.stop_sequences = resolvedAsset.sampling.stop;
+    if (resolvedAsset.sampling?.max_output_tokens !== undefined) {
+      body.max_tokens = resolvedAsset.sampling.max_output_tokens;
     } else {
       // Anthropic requires max_tokens
       body.max_tokens = 4096;
     }
 
     // Thinking/reasoning
-    if (asset.reasoning?.budget_tokens) {
+    if (resolvedAsset.reasoning?.budget_tokens) {
       body.thinking = {
         type: 'enabled',
-        budget_tokens: asset.reasoning.budget_tokens,
+        budget_tokens: resolvedAsset.reasoning.budget_tokens,
       };
     }
 
     // Streaming
-    if (asset.response?.stream !== undefined) {
-      body.stream = asset.response.stream;
+    if (resolvedAsset.response?.stream !== undefined) {
+      body.stream = resolvedAsset.response.stream;
     }
 
     // Tools
-    if (asset.tools && asset.tools.length > 0) {
-      body.tools = asset.tools.map((tool) => {
+    if (resolvedAsset.tools && resolvedAsset.tools.length > 0) {
+      body.tools = resolvedAsset.tools.map((tool) => {
         if (typeof tool === 'string') {
           const def = runtime.toolRegistry?.[tool];
           if (def) return def;
@@ -108,7 +111,7 @@ export const anthropicAdapter: ProviderAdapter = {
     return {
       body,
       provider: 'anthropic',
-      model: asset.model ?? 'unknown',
+      model: resolvedAsset.model ?? 'unknown',
     };
   },
 };