promptopskit 0.5.0 → 0.6.2

package/dist/cli/index.js

@@ -5,7 +5,7 @@ import { readFileSync as readFileSync2 } from "fs";
 
 // src/cli/commands/validate.ts
 import { readdir, stat } from "fs/promises";
-import { join as join3, extname } from "path";
+import { join as join3, extname as extname2 } from "path";
 
 // src/parser/parser.ts
 import matter from "gray-matter";
@@ -41,10 +41,26 @@ var ResponseSchema = z.object({
   format: z.enum(["text", "json", "markdown"]).optional(),
   stream: z.boolean().optional(),
   schema: z.record(z.unknown()).optional(),
+  schema_ref: z.string().min(1).optional(),
+  schema_source: z.object({
+    mode: z.enum(["inline", "schema_ref_json", "schema_ref_zod_module"]).optional(),
+    ref: z.string().optional(),
+    resolved_path: z.string().optional(),
+    hash: z.string().optional()
+  }).optional(),
   schema_name: z.string().optional(),
   schema_description: z.string().optional(),
   schema_strict: z.boolean().optional()
 });
+var ResponseSchemaWithValidation = ResponseSchema.superRefine((value, ctx) => {
+  if (value.schema !== void 0 && value.schema_ref !== void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "response.schema and response.schema_ref are mutually exclusive",
+      path: ["schema_ref"]
+    });
+  }
+});
 var AnthropicProviderOptionsSchema = z.object({
   top_k: z.number().int().min(0).optional(),
   tool_choice: z.record(z.unknown()).optional(),
@@ -136,6 +152,8 @@ var ContextBuiltInValidatorSchema = z.union([
 ]);
 var ContextInputDefinitionObjectSchema = z.object({
   name: z.string(),
+  optional: z.boolean().optional(),
+  warnings: z.boolean().optional(),
   max_size: z.number().int().positive().optional(),
   trim: z.union([z.boolean(), z.enum(["start", "end", "both"])]).optional(),
   allow_regex: ContextRegexSchema.optional(),
@@ -165,7 +183,7 @@ var PromptAssetOverridesSchema = z.object({
   fallback_models: z.array(z.string()).optional(),
   reasoning: ReasoningSchema.optional(),
   sampling: SamplingSchema.optional(),
-  response: ResponseSchema.optional(),
+  response: ResponseSchemaWithValidation.optional(),
   cache: CacheSchema.optional(),
   raw: RawProviderBodySchema.optional(),
   tools: z.array(ToolRefSchema).optional(),
@@ -183,7 +201,19 @@ var SectionsSchema = z.object({
 var PromptDefaultsSchema = z.object({
   provider: z.enum(["openai", "openai-responses", "anthropic", "google", "gemini", "openrouter", "llmasaservice", "any"]).optional(),
   model: z.string().optional(),
+  fallback_models: z.array(z.string()).optional(),
+  reasoning: ReasoningSchema.optional(),
+  sampling: SamplingSchema.optional(),
+  response: ResponseSchema.optional(),
   cache: CacheSchema.optional(),
+  raw: RawProviderBodySchema.optional(),
+  tools: z.array(ToolRefSchema).optional(),
+  provider_options: ProviderOptionsSchema.optional(),
+  mcp: MCPSchema.optional(),
+  context: ContextSchema.optional(),
+  includes: z.array(z.string()).optional(),
+  environments: z.record(PromptAssetOverridesSchema).optional(),
+  tiers: z.record(PromptAssetOverridesSchema).optional(),
   metadata: MetadataSchema.optional(),
   sections: z.object({
     system_instructions: z.string().optional()
@@ -198,7 +228,7 @@ var PromptAssetSchema = z.object({
   fallback_models: z.array(z.string()).optional(),
   reasoning: ReasoningSchema.optional(),
   sampling: SamplingSchema.optional(),
-  response: ResponseSchema.optional(),
+  response: ResponseSchemaWithValidation.optional(),
   cache: CacheSchema.optional(),
   raw: RawProviderBodySchema.optional(),
   tools: z.array(ToolRefSchema).optional(),
@@ -390,16 +420,122 @@ function parsePrompt(content, filePath) {
 }
 
 // src/parser/loader.ts
-import { readFile } from "fs/promises";
-import { dirname, join, resolve } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { dirname as dirname2, join, relative, resolve as resolve2 } from "path";
 import matter2 from "gray-matter";
+
+// src/parser/response-schema-ref.ts
+import { readFile } from "fs/promises";
+import { createHash } from "crypto";
+import { dirname, extname, resolve } from "path";
+import { pathToFileURL } from "url";
+import { z as z2 } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+var SUPPORTED_SCHEMA_REF_EXTENSIONS = /* @__PURE__ */ new Set([".json", ".js", ".mjs", ".cjs"]);
+async function resolveJsonSchemaRef(schemaRef, promptFilePath) {
+  const resolvedPath = resolve(dirname(promptFilePath), schemaRef);
+  let raw;
+  try {
+    raw = await readFile(resolvedPath, "utf-8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") {
+      throw new Error(`POK050: response.schema_ref "${schemaRef}" not found (resolved from ${promptFilePath})`);
+    }
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`POK050: response.schema_ref "${schemaRef}" is not valid JSON`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`POK050: response.schema_ref "${schemaRef}" must resolve to a JSON object schema`);
+  }
+  return {
+    schema: parsed,
+    resolvedPath,
+    hash: createHash("sha256").update(raw).digest("hex")
+  };
+}
+async function resolveZodSchemaRef(schemaRef, promptFilePath) {
+  const resolvedPath = resolve(dirname(promptFilePath), schemaRef);
+  let moduleSource;
+  try {
+    moduleSource = await readFile(resolvedPath, "utf-8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") {
+      throw new Error(`POK051: response.schema_ref "${schemaRef}" not found (resolved from ${promptFilePath})`);
+    }
+    throw error;
+  }
+  let imported;
+  try {
+    imported = await import(pathToFileURL(resolvedPath).href);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`POK051: response.schema_ref "${schemaRef}" could not be imported as a module (${message})`);
+  }
+  const mod = imported;
+  const candidate = mod.default ?? mod.schema;
+  if (!(candidate instanceof z2.ZodType)) {
+    throw new Error('POK051: zod schema modules must export a Zod schema as default export or named export "schema"');
+  }
+  const jsonSchema = zodToJsonSchema(candidate, {
+    target: "jsonSchema7",
+    $refStrategy: "none"
+  });
+  if (!jsonSchema || typeof jsonSchema !== "object" || Array.isArray(jsonSchema)) {
+    throw new Error(`POK051: response.schema_ref "${schemaRef}" did not produce a valid JSON schema object`);
+  }
+  return {
+    schema: jsonSchema,
+    resolvedPath,
+    hash: createHash("sha256").update(moduleSource).digest("hex")
+  };
+}
+async function resolveResponseSchemaRef(asset, promptFilePath) {
+  const schemaRef = asset.response?.schema_ref;
+  if (!schemaRef) return asset;
+  const ext = extname(schemaRef).toLowerCase();
+  if (!SUPPORTED_SCHEMA_REF_EXTENSIONS.has(ext)) {
+    throw new Error(`POK051: response.schema_ref "${schemaRef}" has unsupported extension "${ext}". Use .json, .js, .mjs, or .cjs`);
+  }
+  const resolved = ext === ".json" ? await resolveJsonSchemaRef(schemaRef, promptFilePath) : await resolveZodSchemaRef(schemaRef, promptFilePath);
+  return {
+    ...asset,
+    response: {
+      ...asset.response,
+      schema: resolved.schema,
+      schema_ref: void 0,
+      schema_source: {
+        mode: ext === ".json" ? "schema_ref_json" : "schema_ref_zod_module",
+        ref: schemaRef,
+        resolved_path: resolved.resolvedPath,
+        hash: resolved.hash
+      }
+    }
+  };
+}
+
+// src/parser/loader.ts
 var DEFAULTS_FILE_NAME = "defaults.md";
 async function loadPromptFile(filePath, options = {}) {
-  const content = await readFile(filePath, "utf-8");
+  const content = await readFile2(filePath, "utf-8");
   const parsed = parsePrompt(content, filePath);
-  const root = options.defaultsRoot ?? dirname(filePath);
+  const root = options.defaultsRoot ?? dirname2(filePath);
   const defaults = await loadDefaultsForPath(filePath, root);
-  const asset = applyDefaults(parsed.asset, defaults);
+  const withDefaults = applyDefaults(parsed.asset, defaults);
+  const resolved = await resolveResponseSchemaRef(withDefaults, filePath);
+  const asset = resolved.response?.schema !== void 0 && !resolved.response?.schema_source ? {
+    ...resolved,
+    response: {
+      ...resolved.response,
+      schema_source: { mode: "inline" }
+    }
+  } : resolved;
   return {
     ...parsed,
     asset
@@ -411,8 +547,8 @@ async function loadDefaultsForPath(filePath, defaultsRoot) {
   for (const dir of directories) {
     const defaultsPath = join(dir, DEFAULTS_FILE_NAME);
     try {
-      const defaultsContent = await readFile(defaultsPath, "utf-8");
-      const defaults = parseDefaults(defaultsContent);
+      const defaultsContent = await readFile2(defaultsPath, "utf-8");
+      const defaults = normalizeDefaultIncludes(parseDefaults(defaultsContent), defaultsPath, filePath);
       merged = mergeDefaults(merged, defaults);
     } catch (error) {
       if (error.code !== "ENOENT") {
@@ -424,14 +560,14 @@ async function loadDefaultsForPath(filePath, defaultsRoot) {
 }
 function getDirectoriesToCheck(filePath, defaultsRoot) {
   const dirs = [];
-  let current = resolve(dirname(filePath));
-  const boundary = defaultsRoot ? resolve(defaultsRoot) : void 0;
+  let current = resolve2(dirname2(filePath));
+  const boundary = defaultsRoot ? resolve2(defaultsRoot) : void 0;
   while (true) {
     dirs.unshift(current);
-    if (boundary && current === boundary || current === dirname(current)) {
+    if (boundary && current === boundary || current === dirname2(current)) {
       break;
     }
-    current = dirname(current);
+    current = dirname2(current);
   }
   return dirs;
 }
@@ -449,7 +585,19 @@ function mergeDefaults(base, local) {
   return {
     provider: local.provider ?? base.provider,
     model: local.model ?? base.model,
+    fallback_models: local.fallback_models ?? base.fallback_models,
+    reasoning: mergeRecordBlock(base.reasoning, local.reasoning),
+    sampling: mergeRecordBlock(base.sampling, local.sampling),
+    response: mergeRecordBlock(base.response, local.response),
     cache: mergeCache(base.cache, local.cache),
+    raw: mergeRaw(base.raw, local.raw),
+    tools: local.tools ?? base.tools,
+    provider_options: mergeProviderOptions(base.provider_options, local.provider_options),
+    mcp: mergeMcp(base.mcp, local.mcp),
+    context: mergeContext(base.context, local.context),
+    includes: local.includes ?? base.includes,
+    environments: mergeOverrideMap(base.environments, local.environments),
+    tiers: mergeOverrideMap(base.tiers, local.tiers),
     metadata: {
       ...base.metadata ?? {},
       ...local.metadata ?? {}
@@ -462,11 +610,20 @@ function mergeDefaults(base, local) {
 }
 function applyDefaults(asset, defaults) {
   const cache = mergeCache(defaults.cache, asset.cache);
+  const raw = mergeRaw(defaults.raw, asset.raw);
+  const providerOptions = mergeProviderOptions(defaults.provider_options, asset.provider_options);
+  const reasoning = mergeRecordBlock(defaults.reasoning, asset.reasoning);
+  const sampling = mergeRecordBlock(defaults.sampling, asset.sampling);
+  const response = mergeRecordBlock(defaults.response, asset.response);
+  const mcp = mergeMcp(defaults.mcp, asset.mcp);
+  const context = mergeContext(defaults.context, asset.context);
+  const environments = mergeOverrideMap(defaults.environments, asset.environments);
+  const tiers = mergeOverrideMap(defaults.tiers, asset.tiers);
   const hasDefaultMetadata = defaults.metadata && Object.keys(defaults.metadata).length > 0;
   const hasDefaultSystem = !!defaults.sections?.system_instructions;
-  const hasDefaultScalars = defaults.provider !== void 0 || defaults.model !== void 0;
-  const hasDefaultCache = cache !== void 0;
-  if (!hasDefaultMetadata && !hasDefaultSystem && !hasDefaultScalars && !hasDefaultCache) {
+  const hasDefaultScalars = defaults.provider !== void 0 || defaults.model !== void 0 || defaults.fallback_models !== void 0 || defaults.tools !== void 0 || defaults.includes !== void 0;
+  const hasDefaultObjects = cache !== void 0 || raw !== void 0 || providerOptions !== void 0 || reasoning !== void 0 || sampling !== void 0 || response !== void 0 || mcp !== void 0 || context !== void 0 || environments !== void 0 || tiers !== void 0;
+  if (!hasDefaultMetadata && !hasDefaultSystem && !hasDefaultScalars && !hasDefaultObjects) {
     return asset;
   }
   const mergedMetadata = {
@@ -480,11 +637,52 @@ function applyDefaults(asset, defaults) {
     ...asset,
     provider: asset.provider ?? defaults.provider,
     model: asset.model ?? defaults.model,
+    fallback_models: asset.fallback_models ?? defaults.fallback_models,
+    reasoning,
+    sampling,
+    response,
     cache,
+    raw,
+    tools: asset.tools ?? defaults.tools,
+    provider_options: providerOptions,
+    mcp,
+    context,
+    includes: asset.includes ?? defaults.includes,
+    environments,
+    tiers,
     metadata,
     sections
   };
 }
+function normalizeDefaultIncludes(defaults, defaultsPath, filePath) {
+  if (!defaults.includes) return defaults;
+  const promptDir = dirname2(filePath);
+  const defaultsDir = dirname2(defaultsPath);
+  const includes = defaults.includes.map((includePath) => {
+    const relativePath = relative(promptDir, resolve2(defaultsDir, includePath)).replace(/\\/g, "/");
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+  });
+  return {
+    ...defaults,
+    includes
+  };
+}
+function mergeRecordBlock(base, local) {
+  if (base === void 0) return local;
+  if (local === void 0) return base;
+  return { ...base, ...local };
+}
+function mergeMcp(base, local) {
+  return mergeRecordBlock(base, local);
+}
+function mergeContext(base, local) {
+  const merged = {
+    ...base ?? {},
+    ...local ?? {},
+    history: mergeRecordBlock(base?.history, local?.history)
+  };
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
 function mergeCache(base, local) {
   const merged = {
     ...base ?? {},
@@ -512,6 +710,72 @@ function mergeCache(base, local) {
   if (merged.google && Object.keys(merged.google).length === 0) delete merged.google;
   return Object.keys(merged).length > 0 ? merged : void 0;
 }
+function mergeRaw(base, local) {
+  const merged = {
+    ...base ?? {},
+    ...local ?? {},
+    openai: mergeRecordBlock(base?.openai, local?.openai),
+    "openai-responses": mergeRecordBlock(base?.["openai-responses"], local?.["openai-responses"]),
+    openai_responses: mergeRecordBlock(base?.openai_responses, local?.openai_responses),
+    anthropic: mergeRecordBlock(base?.anthropic, local?.anthropic),
+    gemini: mergeRecordBlock(base?.gemini, local?.gemini),
+    google: mergeRecordBlock(base?.google, local?.google),
+    openrouter: mergeRecordBlock(base?.openrouter, local?.openrouter),
+    llmasaservice: mergeRecordBlock(base?.llmasaservice, local?.llmasaservice)
+  };
+  removeEmptyProviderBlocks(merged);
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function mergeProviderOptions(base, local) {
+  const merged = {
+    ...base ?? {},
+    ...local ?? {},
+    anthropic: mergeRecordBlock(base?.anthropic, local?.anthropic),
+    gemini: mergeRecordBlock(base?.gemini, local?.gemini),
+    openrouter: mergeRecordBlock(base?.openrouter, local?.openrouter),
+    llmasaservice: mergeRecordBlock(base?.llmasaservice, local?.llmasaservice)
+  };
+  removeEmptyProviderBlocks(merged);
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function mergeOverrideMap(base, local) {
+  const merged = { ...base ?? {} };
+  for (const [name, localOverride] of Object.entries(local ?? {})) {
+    merged[name] = mergeOverrideConfig(merged[name], localOverride);
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function mergeOverrideConfig(base, local) {
+  const merged = {
+    ...base ?? {},
+    ...local
+  };
+  const reasoning = mergeRecordBlock(base?.reasoning, local.reasoning);
+  const sampling = mergeRecordBlock(base?.sampling, local.sampling);
+  const response = mergeRecordBlock(base?.response, local.response);
+  const cache = mergeCache(base?.cache, local.cache);
+  const raw = mergeRaw(base?.raw, local.raw);
+  const providerOptions = mergeProviderOptions(base?.provider_options, local.provider_options);
+  if (reasoning !== void 0) merged.reasoning = reasoning;
+  if (sampling !== void 0) merged.sampling = sampling;
+  if (response !== void 0) merged.response = response;
+  if (cache !== void 0) merged.cache = cache;
+  if (raw !== void 0) merged.raw = raw;
+  if (providerOptions !== void 0) merged.provider_options = providerOptions;
+  return merged;
+}
+function removeEmptyProviderBlocks(value) {
+  for (const key of Object.keys(value)) {
+    const block = value[key];
+    if (block === void 0) {
+      delete value[key];
+      continue;
+    }
+    if (block !== null && typeof block === "object" && !Array.isArray(block) && Object.keys(block).length === 0) {
+      delete value[key];
+    }
+  }
+}
 
 // src/renderer/interpolate.ts
 var VARIABLE_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
@@ -519,12 +783,13 @@ var ESCAPED_OPEN = /\\\{\\\{/g;
 var ESCAPE_PLACEHOLDER = "\0ESCAPED_OPEN\0";
 function interpolate(template, variables, options = {}) {
   const { strict = false } = options;
+  const optionalVariables = new Set(options.optionalVariables ?? []);
   let result = template.replace(ESCAPED_OPEN, ESCAPE_PLACEHOLDER);
   result = result.replace(VARIABLE_RE, (match, name) => {
     if (name in variables) {
       return variables[name];
     }
-    if (strict) {
+    if (strict && !optionalVariables.has(name)) {
       throw new Error(`Missing required variable: "${name}"`);
     }
     return match;
@@ -542,59 +807,19 @@ function extractVariables(template) {
   return [...vars];
 }
 
-// src/composition/resolve-includes.ts
-import { readFile as readFile2 } from "fs/promises";
-import { resolve as resolve2, dirname as dirname2 } from "path";
-async function resolveIncludes(asset, basePath, visited = /* @__PURE__ */ new Set()) {
-  if (!asset.includes || asset.includes.length === 0) {
-    return asset;
-  }
-  const baseDir = dirname2(basePath);
-  const resolvedPath = resolve2(basePath);
-  if (visited.has(resolvedPath)) {
-    throw new Error(`Circular include detected: ${resolvedPath}`);
-  }
-  visited.add(resolvedPath);
-  let mergedSystemInstructions = "";
-  for (const includePath of asset.includes) {
-    const fullPath = resolve2(baseDir, includePath);
-    if (visited.has(fullPath)) {
-      throw new Error(`Circular include detected: ${fullPath} (included from ${basePath})`);
-    }
-    const content = await readFile2(fullPath, "utf-8");
-    const { asset: includedAsset } = parsePrompt(content, fullPath);
-    const resolved = await resolveIncludes(includedAsset, fullPath, new Set(visited));
-    if (resolved.sections?.system_instructions) {
-      mergedSystemInstructions += resolved.sections.system_instructions + "\n\n";
-    }
-  }
-  const localSystem = asset.sections?.system_instructions ?? "";
-  const combinedSystem = (mergedSystemInstructions + localSystem).trim() || void 0;
-  return {
-    ...asset,
-    sections: {
-      ...asset.sections,
-      system_instructions: combinedSystem
-    },
-    // Drop includes from the resolved asset — they've been inlined
-    includes: void 0
-  };
-}
-
 // src/context.ts
 var textEncoder = new TextEncoder();
 function getContextInputs(asset) {
   return (asset.context?.inputs ?? []).map(normalizeContextInput);
 }
-function getContextInputNames(asset) {
-  return getContextInputs(asset).map((input) => input.name);
-}
 function normalizeContextInput(input) {
   if (typeof input === "string") {
     return { name: input };
   }
   return {
     name: input.name,
+    optional: input.optional,
+    warnings: input.warnings,
     max_size: input.max_size,
     trim: input.trim,
     allow_regex: normalizeContextRegex(input.allow_regex),
@@ -603,6 +828,9 @@ function normalizeContextInput(input) {
     reject_secrets: normalizeBuiltInValidator(input.reject_secrets)
   };
 }
+function areContextInputWarningsEnabled(input) {
+  return input.warnings !== false;
+}
 function normalizeContextRegex(value) {
   if (value === void 0) {
     return void 0;
@@ -689,6 +917,45 @@ function compileContextRegex(regex, details) {
   }
 }
 
+// src/composition/resolve-includes.ts
+import { readFile as readFile3 } from "fs/promises";
+import { resolve as resolve3, dirname as dirname3 } from "path";
+async function resolveIncludes(asset, basePath, visited = /* @__PURE__ */ new Set()) {
+  if (!asset.includes || asset.includes.length === 0) {
+    return asset;
+  }
+  const baseDir = dirname3(basePath);
+  const resolvedPath = resolve3(basePath);
+  if (visited.has(resolvedPath)) {
+    throw new Error(`Circular include detected: ${resolvedPath}`);
+  }
+  visited.add(resolvedPath);
+  let mergedSystemInstructions = "";
+  for (const includePath of asset.includes) {
+    const fullPath = resolve3(baseDir, includePath);
+    if (visited.has(fullPath)) {
+      throw new Error(`Circular include detected: ${fullPath} (included from ${basePath})`);
+    }
+    const content = await readFile3(fullPath, "utf-8");
+    const { asset: includedAsset } = parsePrompt(content, fullPath);
+    const resolved = await resolveIncludes(includedAsset, fullPath, new Set(visited));
+    if (resolved.sections?.system_instructions) {
+      mergedSystemInstructions += resolved.sections.system_instructions + "\n\n";
+    }
+  }
+  const localSystem = asset.sections?.system_instructions ?? "";
+  const combinedSystem = (mergedSystemInstructions + localSystem).trim() || void 0;
+  return {
+    ...asset,
+    sections: {
+      ...asset.sections,
+      system_instructions: combinedSystem
+    },
+    // Drop includes from the resolved asset — they've been inlined
+    includes: void 0
+  };
+}
+
 // src/validation/levenshtein.ts
 function levenshtein(a, b) {
   const m = a.length;
@@ -733,6 +1000,18 @@ var KNOWN_FRONT_MATTER_KEYS = /* @__PURE__ */ new Set([
   "provider_options",
   "raw"
 ]);
+function collectSchemaKeywords(value, acc) {
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    for (const item of value) collectSchemaKeywords(item, acc);
+    return;
+  }
+  const record = value;
+  for (const [key, child] of Object.entries(record)) {
+    acc.add(key);
+    collectSchemaKeywords(child, acc);
+  }
+}
 var RISKY_UNBOUNDED_INPUT_NAMES = [
   "message",
   "prompt",
@@ -784,7 +1063,9 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       }
     }
   }
-  const declaredInputs = new Set(getContextInputNames(asset));
+  const contextInputs = getContextInputs(asset);
+  const declaredInputs = new Set(contextInputs.map((input) => input.name));
+  const declaredInputsByName = new Map(contextInputs.map((input) => [input.name, input]));
   const usedVars = /* @__PURE__ */ new Set();
   if (asset.sections?.system_instructions) {
     for (const v of extractVariables(asset.sections.system_instructions)) {
@@ -806,7 +1087,8 @@ function validateAsset(asset, frontMatterKeys, filePath) {
     }
   }
   for (const v of declaredInputs) {
-    if (!usedVars.has(v)) {
+    const input = declaredInputsByName.get(v);
+    if (!usedVars.has(v) && input?.optional !== true && areContextInputWarningsEnabled(input ?? {})) {
       warnings.push({
         code: "POK012",
         message: `Variable "${v}" is declared in context.inputs but never used`,
@@ -822,9 +1104,10 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       suggestion: "Declare context.inputs to enable input policy validation."
     });
   }
-  for (const input of getContextInputs(asset)) {
+  for (const input of contextInputs) {
     const lowerName = input.name.toLowerCase();
-    if (input.max_size === void 0 && RISKY_UNBOUNDED_INPUT_NAMES.some((needle) => lowerName.includes(needle))) {
+    const inputWarningsEnabled = areContextInputWarningsEnabled(input);
+    if (inputWarningsEnabled && input.max_size === void 0 && RISKY_UNBOUNDED_INPUT_NAMES.some((needle) => lowerName.includes(needle))) {
       warnings.push({
         code: "POK040",
         message: `Context input "${input.name}" has no max_size and appears unbounded.`,
@@ -832,7 +1115,7 @@ function validateAsset(asset, frontMatterKeys, filePath) {
         suggestion: "Add max_size to constrain prompt payload growth."
       });
     }
-    if (input.allow_regex === void 0 && input.deny_regex === void 0 && input.non_empty === void 0 && input.reject_secrets === void 0) {
+    if (inputWarningsEnabled && input.optional !== true && input.allow_regex === void 0 && input.deny_regex === void 0 && input.non_empty === void 0 && input.reject_secrets === void 0) {
       warnings.push({
         code: "POK041",
         message: `Context input "${input.name}" has no input hardening validators.`,
@@ -840,7 +1123,7 @@ function validateAsset(asset, frontMatterKeys, filePath) {
         suggestion: "Consider non_empty/reject_secrets and allow/deny regex validators."
       });
     }
-    if (input.trim !== void 0 && input.trim !== false && input.max_size === void 0) {
+    if (inputWarningsEnabled && input.trim !== void 0 && input.trim !== false && input.max_size === void 0) {
       warnings.push({
         code: "POK014",
         message: `Context input "${input.name}" sets trim but has no max_size; trim-to-budget will be skipped.`,
@@ -867,6 +1150,30 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       }
     }
   }
+  if (asset.response?.schema && asset.provider) {
+    const keywords = /* @__PURE__ */ new Set();
+    collectSchemaKeywords(asset.response.schema, keywords);
+    const openAIUnsupported = ["patternProperties", "unevaluatedProperties", "$dynamicRef"];
+    const geminiUnsupported = ["patternProperties", "$dynamicRef", "dependentSchemas"];
+    const anthropicCaution = ["if", "then", "else"];
+    const checks = [
+      { provider: ["openai", "openai-responses", "openrouter", "llmasaservice"], unsupported: openAIUnsupported, code: "POK052" },
+      { provider: ["gemini", "google"], unsupported: geminiUnsupported, code: "POK053" },
+      { provider: ["anthropic"], unsupported: anthropicCaution, code: "POK054" }
+    ];
+    for (const check of checks) {
+      if (!check.provider.includes(asset.provider)) continue;
+      const hits = check.unsupported.filter((k) => keywords.has(k));
+      if (hits.length > 0) {
+        warnings.push({
+          code: check.code,
+          message: `response.schema includes provider-sensitive JSON Schema keywords for "${asset.provider}": ${hits.join(", ")}`,
+          filePath,
+          suggestion: "Validate schema compatibility with your provider docs or simplify the schema dialect."
+        });
+      }
+    }
+  }
   if (asset.provider) {
     let providerCache;
     let cacheSuggestionField;
@@ -993,9 +1300,9 @@ function isRecord(value) {
 }
 
 // src/prompt-resolution.ts
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 import { existsSync, statSync as statSync2 } from "fs";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 
 // src/cache.ts
 import { statSync } from "fs";
@@ -1075,24 +1382,24 @@ function mergeOverride(base, override) {
     result.cache = {
       ...result.cache,
       ...override.cache,
-      openai: mergeRecordBlock(result.cache?.openai, override.cache.openai),
-      anthropic: mergeRecordBlock(result.cache?.anthropic, override.cache.anthropic),
-      gemini: mergeRecordBlock(result.cache?.gemini, override.cache.gemini),
-      google: mergeRecordBlock(result.cache?.google, override.cache.google)
+      openai: mergeRecordBlock2(result.cache?.openai, override.cache.openai),
+      anthropic: mergeRecordBlock2(result.cache?.anthropic, override.cache.anthropic),
+      gemini: mergeRecordBlock2(result.cache?.gemini, override.cache.gemini),
+      google: mergeRecordBlock2(result.cache?.google, override.cache.google)
     };
   }
   if (override.raw !== void 0) {
     result.raw = {
       ...result.raw,
       ...override.raw,
-      openai: mergeRecordBlock(result.raw?.openai, override.raw.openai),
-      "openai-responses": mergeRecordBlock(result.raw?.["openai-responses"], override.raw["openai-responses"]),
-      openai_responses: mergeRecordBlock(result.raw?.openai_responses, override.raw.openai_responses),
-      anthropic: mergeRecordBlock(result.raw?.anthropic, override.raw.anthropic),
-      gemini: mergeRecordBlock(result.raw?.gemini, override.raw.gemini),
-      google: mergeRecordBlock(result.raw?.google, override.raw.google),
-      openrouter: mergeRecordBlock(result.raw?.openrouter, override.raw.openrouter),
-      llmasaservice: mergeRecordBlock(result.raw?.llmasaservice, override.raw.llmasaservice)
+      openai: mergeRecordBlock2(result.raw?.openai, override.raw.openai),
+      "openai-responses": mergeRecordBlock2(result.raw?.["openai-responses"], override.raw["openai-responses"]),
+      openai_responses: mergeRecordBlock2(result.raw?.openai_responses, override.raw.openai_responses),
+      anthropic: mergeRecordBlock2(result.raw?.anthropic, override.raw.anthropic),
+      gemini: mergeRecordBlock2(result.raw?.gemini, override.raw.gemini),
+      google: mergeRecordBlock2(result.raw?.google, override.raw.google),
+      openrouter: mergeRecordBlock2(result.raw?.openrouter, override.raw.openrouter),
+      llmasaservice: mergeRecordBlock2(result.raw?.llmasaservice, override.raw.llmasaservice)
     };
   }
   if (override.provider_options !== void 0) {
@@ -1119,7 +1426,7 @@ function mergeOverride(base, override) {
   }
   return result;
 }
-function mergeRecordBlock(base, override) {
+function mergeRecordBlock2(base, override) {
   if (override === void 0) return base;
   return { ...base, ...override };
 }
@@ -1135,9 +1442,9 @@ var sharedPromptCache = new PromptCache();
 
 // src/cli/commands/defaults-root.ts
 import { existsSync as existsSync2 } from "fs";
-import { dirname as dirname3, join as join2, resolve as resolve4 } from "path";
+import { dirname as dirname4, join as join2, resolve as resolve5 } from "path";
 function findDefaultsRoot(filePath) {
-  let current = resolve4(dirname3(filePath));
+  let current = resolve5(dirname4(filePath));
   let root = current;
   let foundDefaults = false;
   while (true) {
@@ -1147,7 +1454,7 @@ function findDefaultsRoot(filePath) {
     } else if (foundDefaults) {
       return root;
     }
-    const parent = dirname3(current);
+    const parent = dirname4(current);
     if (parent === current) {
       return root;
     }
@@ -1242,7 +1549,7 @@ function getFlag(args, ...flags) {
 async function collectPromptFiles(target) {
   const targetStats = await stat(target);
   if (targetStats.isFile()) {
-    if (extname(target) !== ".md" || target.endsWith("defaults.md") || target.endsWith(".test.md")) {
+    if (extname2(target) !== ".md" || target.endsWith("defaults.md") || target.endsWith(".test.md")) {
       return [];
     }
     return [target];
@@ -1250,7 +1557,7 @@ async function collectPromptFiles(target) {
   const results = [];
   const entries = await readdir(target, { withFileTypes: true, recursive: true });
   for (const entry of entries) {
-    if (entry.isFile() && extname(entry.name) === ".md" && !entry.name.endsWith(".test.md") && entry.name !== "defaults.md") {
+    if (entry.isFile() && extname2(entry.name) === ".md" && !entry.name.endsWith(".test.md") && entry.name !== "defaults.md") {
       results.push(join3(entry.parentPath ?? target, entry.name));
     }
   }
@@ -1259,7 +1566,7 @@ async function collectPromptFiles(target) {
 
 // src/cli/commands/compile.ts
 import { readdir as readdir2, writeFile, mkdir, rm } from "fs/promises";
-import { join as join4, extname as extname2, relative, dirname as dirname5 } from "path";
+import { join as join4, extname as extname3, relative as relative2, dirname as dirname6 } from "path";
 var HELP2 = `
 promptopskit compile [sourceDir] [outputDir] [options]
 
@@ -1299,7 +1606,7 @@ async function compile(args) {
   let compiled = 0;
   let errors = 0;
   for (const file of files) {
-    const rel = relative(sourceDir, file).replace(/\.md$/, "");
+    const rel = relative2(sourceDir, file).replace(/\.md$/, "");
     const outExt = format === "esm" ? ".mjs" : ".json";
     const outPath = join4(outputDir, rel + outExt);
     try {
@@ -1312,7 +1619,7 @@ async function compile(args) {
       if (dryRun) {
         console.log(`  Would create: ${outPath}`);
       } else {
-        await mkdir(dirname5(outPath), { recursive: true });
+        await mkdir(dirname6(outPath), { recursive: true });
         if (format === "esm") {
           const esmContent = `export default ${JSON.stringify(asset, null, 2)};
 `;
@@ -1368,7 +1675,7 @@ async function collectPromptFiles2(dir) {
   const results = [];
   const entries = await readdir2(dir, { withFileTypes: true, recursive: true });
   for (const entry of entries) {
-    if (entry.isFile() && extname2(entry.name) === ".md" && !entry.name.endsWith(".test.md") && entry.name !== "defaults.md") {
+    if (entry.isFile() && extname3(entry.name) === ".md" && !entry.name.endsWith(".test.md") && entry.name !== "defaults.md") {
       results.push(join4(entry.parentPath ?? dir, entry.name));
     }
   }
@@ -1376,7 +1683,7 @@ async function collectPromptFiles2(dir) {
 }
 
 // src/cli/commands/render.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 var HELP3 = `
 promptopskit render <file> [options]
@@ -1407,13 +1714,13 @@ async function render(args) {
   const jsonOutput = args.includes("--json");
   let variables = {};
   if (varsFile) {
-    const varsContent = await readFile4(varsFile, "utf-8");
+    const varsContent = await readFile5(varsFile, "utf-8");
     variables = JSON.parse(varsContent);
   } else {
     const sidecarPath = file.replace(/\.md$/, ".test.yaml");
     if (existsSync3(sidecarPath)) {
       const { default: yaml } = await import("gray-matter");
-      const sidecarContent = await readFile4(sidecarPath, "utf-8");
+      const sidecarContent = await readFile5(sidecarPath, "utf-8");
       const parsed2 = yaml(`---
 ${sidecarContent}---
 `);
@@ -1512,7 +1819,7 @@ async function inspect(args) {
 
 // src/cli/commands/init.ts
 import { writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
-import { join as join5, dirname as dirname6, relative as relative2 } from "path";
+import { join as join5, dirname as dirname7, relative as relative3 } from "path";
 import { existsSync as existsSync4, readFileSync } from "fs";
 var HELP5 = `
 promptopskit init [dir]
@@ -1663,8 +1970,8 @@ async function init(args) {
     return;
   }
   const dir = args.find((a) => !a.startsWith("--")) ?? "./prompts";
-  const testFilePath = join5(dirname6(dir), "tests", "hello.prompt.test.mjs");
-  const promptsDirFromTest = relative2(dirname6(testFilePath), dir) || ".";
+  const testFilePath = join5(dirname7(dir), "tests", "hello.prompt.test.mjs");
+  const promptsDirFromTest = relative3(dirname7(testFilePath), dir) || ".";
   const helloPromptTest = createHelloPromptTest(promptsDirFromTest);
   const files = [
     { path: join5(dir, "defaults.md"), content: DEFAULTS },
@@ -1682,7 +1989,7 @@ async function init(args) {
       skipped++;
       continue;
     }
-    await mkdir2(dirname6(file.path), { recursive: true });
+    await mkdir2(dirname7(file.path), { recursive: true });
     await writeFile2(file.path, file.content, "utf-8");
     console.log(`  \u2713 ${file.path}`);
     created++;
@@ -1750,8 +2057,8 @@ test('hello prompt can return a deterministic response without calling a model',
 }
 
 // src/cli/commands/skill.ts
-import { writeFile as writeFile3, readFile as readFile5, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname7 } from "path";
+import { writeFile as writeFile3, readFile as readFile6, mkdir as mkdir3 } from "fs/promises";
+import { dirname as dirname8 } from "path";
 import { existsSync as existsSync5 } from "fs";
 var MARKER_START = "<!-- promptopskit:start -->";
 var MARKER_END = "<!-- promptopskit:end -->";
@@ -1839,7 +2146,7 @@ async function skill(args) {
     }
     const markedContent = config.wrap(wrapMarkers(STUB_CONTENT));
     if (existsSync5(filePath) && !force) {
-      const existing = await readFile5(filePath, "utf-8");
+      const existing = await readFile6(filePath, "utf-8");
       const merged = mergeContent(existing, markedContent);
       if (merged === existing) {
         console.log(`  skip ${filePath} (already up to date)`);
@@ -1850,7 +2157,7 @@ async function skill(args) {
       written++;
       continue;
     }
-    await mkdir3(dirname7(filePath), { recursive: true });
+    await mkdir3(dirname8(filePath), { recursive: true });
     await writeFile3(filePath, markedContent, "utf-8");
     console.log(`  \u2713 ${filePath}`);
     written++;
@@ -1863,12 +2170,12 @@ async function skill(args) {
 async function deployClaude(filePath, force) {
   const content = CLAUDE_LINE + "\n";
   if (!existsSync5(filePath) || force) {
-    await mkdir3(dirname7(filePath), { recursive: true });
+    await mkdir3(dirname8(filePath), { recursive: true });
     await writeFile3(filePath, content, "utf-8");
     console.log(`  \u2713 ${filePath}`);
     return 1;
   }
-  const existing = await readFile5(filePath, "utf-8");
+  const existing = await readFile6(filePath, "utf-8");
   if (existing.split("\n").some((line) => line.trim() === CLAUDE_LINE)) {
     console.log(`  skip ${filePath} (already up to date)`);
     return 0;