Add provider-specific cache front matter and wiring for OpenAI/Anthropic/Gemini

[PredictabilityAtScale]

Motivation

• Provide a standard cache front matter block to express vendor-specific prompt/context caching hints and allow adapters to map those hints to provider APIs.

Description

• Add cache schemas (CacheSchema, OpenAICacheSchema, AnthropicCacheSchema, GeminiCacheSchema) to the prompt schema and wire cache into PromptAsset, PromptDefaults, and overrides.
• Wire cache handling into adapters: OpenAI maps openai.prompt_cache_key/retention to prompt_cache_key/prompt_cache_retention; Anthropic supports mode: automatic → top-level cache_control and mode: explicit → block-level cache_control on system, prompt, and tools; Gemini maps gemini.cached_content (or google.cached_content) to cachedContent and warns when both differ.
• Update docs (README.md, docs/prompt-format.md, docs/providers.md, docs/schema.md) and the promptopskit init scaffold to document and demonstrate cache usage.
• Update validation to recognize cache as a known front-matter key.

Testing

• Added and ran adapter unit tests in tests/providers.test.ts covering OpenAI, Anthropic, and Gemini cache behaviors, and they passed when running the test suite.
• Existing provider tests and shared prompt-input tests were executed as part of the test run and succeeded.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9f5d8edd0c

ℹ️ 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]

Merge cache in applyOverrides before rendering

Adding cache to override schema here makes environments/tiers/runtime cache blocks validate, but mergeOverride in src/overrides/apply-overrides.ts never applies override.cache. That means resolveAssetForProvider silently drops all cache overrides, so cache behavior cannot actually vary by environment or tier even though this commit documents cache as overridable.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Propagate defaults cache into loaded prompt assets

This makes defaults.md accept a cache block, but defaults application in src/parser/loader.ts does not merge or apply defaults.cache (the merge and short-circuit checks still only handle provider/model/metadata/system). As a result, cache settings in folder defaults are parsed but never inherited by prompt files, so the new defaults examples and init template cache config are no-ops.

Useful? React with 👍 / 👎.