docs: expose response schema, cache and provider_options; add vendor schema gap analysis

[PredictabilityAtScale]

Motivation

• Surface structured-output options and schema metadata in the prompt front matter so prompts can declare portable JSON schemas and OpenAI/OpenAI Responses specific names/strictness.
• Add provider-specific knobs and cache controls to the schema so adapters can expose non-portable options and vendor caching hints.
• Expand provider enumerations to include openai-responses and document how overrides and defaults interact with the new fields.
• Provide a vendor schema gap analysis to track parity between PromptOpsKit schema and current vendor API capabilities.

Description

• Added response.schema, response.schema_name, and response.schema_strict to the front-matter schema and examples across README.md, SKILL.md, and docs/schema.md.
• Introduced a cache block and documented provider-specific cache controls in README.md, SKILL.md, docs/schema.md, docs/overrides.md, and defaults guidance.
• Added provider_options for non-portable vendor-specific settings (examples for anthropic and gemini) and surfaced it in overrides and schema docs.
• Included openai-responses in provider enumerations and updated overridable-fields and shallow-merge semantics to include cache and provider_options.
• Added a new docs/vendor-schema-gap-analysis.md file summarizing current vendor capabilities, gaps, and recommended next steps.
• Updated docs/index.md to link to the new vendor schema gap analysis.

Testing

• This is a documentation/schema surface change with no runtime code changes and no unit tests modified.
• Built the docs site with npm run docs:build and ran markdown linting (npm run lint:md) and both completed successfully.
• No schema-breaking changes detected by the repository's docs and schema linter during the run.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3fbb9cf0d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Stop documenting cache as an overridable field

This change adds cache to the overridable fields and says it is shallow-merged, but override application currently ignores it: mergeOverride in src/overrides/apply-overrides.ts has no override.cache handling, so environment/tier/runtime cache values never take effect. Users following this doc will believe cache strategy can be overridden when it is silently ignored at render time.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove defaults cache guidance until it is implemented

This new bullet says defaults.md supports cache, but defaults loading does not merge or apply cache settings (src/parser/loader.ts only merges provider/model/metadata/sections in mergeDefaults/applyDefaults). That means prompt trees configured per this guidance will silently lose default cache config, which is a behavior mismatch users cannot detect from the docs alone.

Useful? React with 👍 / 👎.