docs: add validated examples library demonstrating prompt schema and features

examples/README.md

@@ -0,0 +1,23 @@
+# PromptOpsKit Example Library
+
+This folder contains a small, validation-safe set of prompt examples that demonstrate the main PromptOpsKit features and front matter schema.
+
+## Layout
+
+- `prompts/defaults.md` — folder defaults (provider/model/metadata/system instructions)
+- `prompts/shared/` — reusable includes used by composition examples
+- `prompts/*.md` — standalone examples with a `# Notes` section
+
+## Validate all examples
+
+```bash
+npm run build
+node dist/cli/index.js validate examples/prompts
+```
+
+## Optional: inspect or render a single example
+
+```bash
+node dist/cli/index.js inspect examples/prompts/03-composition-includes.md
+node dist/cli/index.js render examples/prompts/05-response-schema-json.md --json
+```

examples/prompts/01-basic.md

@@ -0,0 +1,21 @@
+---
+id: examples/basic
+schema_version: 1
+description: Minimal prompt with variable interpolation.
+context:
+  inputs:
+    - name: name
+      non_empty: true
+      reject_secrets: true
+---
+
+# Prompt template
+
+Hello {{ name }}! Give a one-sentence welcome.
+
+# Notes
+
+This is the smallest useful prompt example:
+- Inherits `provider` and `model` from `defaults.md`.
+- Declares a single input used in interpolation.
+- Uses a single prompt template section.

examples/prompts/02-context-validation.md

@@ -0,0 +1,40 @@
+---
+id: examples/context-validation
+schema_version: 1
+context:
+  history:
+    max_items: 10
+  inputs:
+    - name: user_message
+      max_size: 2000
+      non_empty:
+        return_message: "Please enter your question."
+      reject_secrets:
+        return_message: "Please remove credentials before sending your message."
+      deny_regex:
+        pattern: '(?:ignore|forget)\s+all\s+instructions'
+        flags: i
+        return_message: "Please avoid prompt-injection text."
+    - name: app_context
+      max_size: 400
+      trim: end
+      allow_regex: '/^[A-Za-z0-9 .,_-]+$/'
+---
+
+# System instructions
+
+Use `app_context` only when relevant to the request.
+
+# Prompt template
+
+Context: {{ app_context }}
+
+User message: {{ user_message }}
+
+# Notes
+
+Demonstrates context hardening and guards:
+- `non_empty` + `reject_secrets` built-ins.
+- Structured `deny_regex` with a return message.
+- `max_size` and `trim` for large values.
+- `history.max_items` for bounded conversation context.

examples/prompts/03-composition-includes.md

@@ -0,0 +1,27 @@
+---
+id: examples/composition
+schema_version: 1
+includes:
+  - ./shared/tone.md
+  - ./shared/safety.md
+context:
+  inputs:
+    - name: topic
+      non_empty: true
+      reject_secrets: true
+---
+
+# System instructions
+
+Prioritize practical examples over abstract theory.
+
+# Prompt template
+
+Teach the basics of {{ topic }} in 5 bullet points.
+
+# Notes
+
+Shows composition with `includes`:
+- Included system instructions are prepended.
+- Local system instructions can add task-specific guidance.
+- Shared files remain reusable across many prompts.

examples/prompts/04-overrides-env-tier.md

@@ -0,0 +1,48 @@
+---
+id: examples/overrides
+schema_version: 1
+model: gpt-5.4
+fallback_models:
+  - gpt-5.4-mini
+reasoning:
+  effort: medium
+sampling:
+  temperature: 0.4
+environments:
+  dev:
+    model: gpt-5.4-mini
+    reasoning:
+      effort: low
+    sampling:
+      temperature: 0.8
+    cache:
+      openai:
+        prompt_cache_key: examples-overrides-dev
+        retention: in_memory
+tiers:
+  fast:
+    model: gpt-5.4-mini
+    sampling:
+      temperature: 0.2
+    cache:
+      openai:
+        prompt_cache_key: examples-overrides-fast
+        retention: in_memory
+context:
+  inputs:
+    - name: user_goal
+      non_empty: true
+      reject_secrets: true
+---
+
+# Prompt template
+
+Generate a short implementation plan for: {{ user_goal }}.
+
+# Notes
+
+Shows override layering:
+- Base config is production-like.
+- `environments.dev` lowers cost and reasoning effort.
+- `tiers.fast` demonstrates runtime performance tuning.
+- Runtime options still apply last (base → env → tier → runtime).

examples/prompts/05-response-schema-json.md

@@ -0,0 +1,40 @@
+---
+id: examples/response-json
+schema_version: 1
+response:
+  format: json
+  schema_name: quick_answer
+  schema_description: Structured answer with confidence and citations.
+  schema_strict: true
+  schema:
+    type: object
+    additionalProperties: false
+    required:
+      - answer
+      - confidence
+      - citations
+    properties:
+      answer:
+        type: string
+      confidence:
+        type: number
+        minimum: 0
+        maximum: 1
+      citations:
+        type: array
+        items:
+          type: string
+context:
+  inputs:
+    - name: question
+      non_empty: true
+      reject_secrets: true
+---
+
+# Prompt template
+
+Answer this question as structured JSON: {{ question }}
+
+# Notes
+
+Shows portable structured output settings via `response`.

examples/prompts/06-tools-and-mcp.md

@@ -0,0 +1,34 @@
+---
+id: examples/tools-mcp
+schema_version: 1
+tools:
+  - web_search
+  - name: lookup_order
+    description: Fetch an order by id.
+    input_schema:
+      type: object
+      required:
+        - order_id
+      properties:
+        order_id:
+          type: string
+mcp:
+  servers:
+    - docs-index
+    - name: billing-db
+      config:
+        readonly: true
+context:
+  inputs:
+    - name: order_id
+      non_empty: true
+      allow_regex: /^[A-Z0-9-]+$/
+---
+
+# Prompt template
+
+Find the order status for {{ order_id }}.
+
+# Notes
+
+Shows both tool declaration styles and MCP server references.

examples/prompts/07-cache-provider-options-raw.md

@@ -0,0 +1,41 @@
+---
+id: examples/provider-controls
+schema_version: 1
+provider: anthropic
+model: claude-sonnet-4-20250514
+cache:
+  anthropic:
+    mode: explicit
+    type: ephemeral
+    ttl: 5m
+    cache_system_instructions: true
+provider_options:
+  anthropic:
+    top_k: 40
+raw:
+  anthropic:
+    metadata:
+      trace_id: example-provider-controls
+context:
+  inputs:
+    - name: support_ticket
+      non_empty: true
+      reject_secrets: true
+      max_size: 6000
+---
+
+# System instructions
+
+Summarize support issues without exposing personal data.
+
+# Prompt template
+
+Support ticket:
+{{ support_ticket }}
+
+# Notes
+
+Demonstrates advanced provider control:
+- Provider-specific caching hints.
+- Provider-specific options (`top_k`).
+- `raw` passthrough for unmodeled request body fields.

examples/prompts/08-openai-responses.md

@@ -0,0 +1,28 @@
+---
+id: examples/openai-responses
+schema_version: 1
+provider: openai-responses
+model: gpt-5.4-mini
+sampling:
+  temperature: 0.3
+response:
+  format: markdown
+context:
+  inputs:
+    - name: changelog
+      non_empty: true
+      max_size: 6000
+---
+
+# System instructions
+
+Write release notes in a clear customer-facing style.
+
+# Prompt template
+
+Turn this changelog into release notes:
+{{ changelog }}
+
+# Notes
+
+Demonstrates the `openai-responses` provider with a simple markdown response format.

examples/prompts/defaults.md

@@ -0,0 +1,15 @@
+---
+provider: openai
+model: gpt-5.4-mini
+metadata:
+  owner: examples-team
+  stable: true
+cache:
+  openai:
+    prompt_cache_key: examples-v1
+    retention: in_memory
+---
+
+# System instructions
+
+You are a clear, practical assistant. Prefer concise, actionable responses.

examples/prompts/shared/safety.md

@@ -0,0 +1,12 @@
+---
+id: shared/safety
+schema_version: 1
+---
+
+# System instructions
+
+Do not invent policies or capabilities. If uncertain, state uncertainty clearly.
+
+# Notes
+
+Shared safety include for composition examples.

examples/prompts/shared/tone.md

@@ -0,0 +1,12 @@
+---
+id: shared/tone
+schema_version: 1
+---
+
+# System instructions
+
+Use plain language, short paragraphs, and a supportive tone.
+
+# Notes
+
+Shared include file for composition examples.