start-vibing-stacks 2.15.0 → 2.17.0

package/stacks/_shared/skills/hook-development/SKILL.md

@@ -1,93 +1,271 @@
 ---
 name: hook-development
-version: 1.0.0
+version: 2.0.0
+description: "Claude Code hook development for 2026. Covers all 9 supported events (UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact), stdin/stdout JSON contract, decision/continue/systemMessage outputs, matchers (tool patterns), exit-code semantics, cycle detection (stop_hook_active), settings.json registration, run-hook.sh dispatcher (bun → tsx → node fallback). Invoke when creating or modifying any .claude/hooks/* file or settings.json hook entry."
 ---
 
-# Hook Development — Claude Code Hooks
+# Hook Development — Claude Code Hooks (2026)
 
 **ALWAYS invoke when creating or modifying Claude Code hooks.**
 
-## Hook Types
+> Hooks are user-controlled deterministic gates around the model. Anything you want **enforced**, not asked nicely — put in a hook. The agent cannot disable a hook from inside the conversation.
 
-| Event | When | Use Case |
-|-------|------|----------|
-| `UserPromptSubmit` | Before prompt is sent | Inject workflow, validate input |
-| `Stop` | Before task completion | Validate state, block if dirty |
-| `PreToolUse` | Before tool execution | Approve/block dangerous tools |
-| `PostToolUse` | After tool execution | Log, validate output |
+## 1. Supported events (Claude Code, 2026)
 
-## File Structure
+| Event | Fires | Common use |
+|---|---|---|
+| `SessionStart` | When a session begins (new chat or resume) | Inject onboarding context, restore state |
+| `SessionEnd` | When a session ends cleanly | Flush logs, persist state, run cleanup |
+| `UserPromptSubmit` | After user submits, before model receives | Inject workflow rules, block forbidden phrases |
+| `PreToolUse` | Before any tool is invoked | Approve / block / rewrite tool calls (security gate) |
+| `PostToolUse` | After tool completes | Log, validate output, react to specific tool results |
+| `Notification` | When the agent is idle and notifies (e.g. waiting for input) | Desktop notifications, status forwarding |
+| `Stop` | Before the agent ends its turn | Validate completion (clean tree, tests pass, docs updated) |
+| `SubagentStop` | When a Task() subagent finishes | Validate subagent output, persist artifacts |
+| `PreCompact` | Before transcript compaction is triggered | Snapshot/export full transcript first |
+
+`Stop` and `Subagent` events are the most commonly customized. `PreToolUse` is the security workhorse.
+
+## 2. File layout
 
 ```
-.claude/hooks/
-├── run-hook.sh              # Entry point (bash → bun/tsx fallback)
-├── user-prompt-submit.ts    # Prompt injection
-└── stop-validator.ts        # Task completion gate
+.claude/
+├── hooks/
+│   ├── run-hook.sh           # Entry point: bun → tsx → node fallback
+│   ├── session-start.ts
+│   ├── session-end.ts
+│   ├── user-prompt-submit.ts
+│   ├── pre-tool-use.ts
+│   ├── post-tool-use.ts
+│   ├── stop-validator.ts
+│   ├── subagent-stop.ts
+│   ├── pre-compact.ts
+│   └── lib/                  # shared helpers (cmd(), readStdin(), etc.)
+└── settings.json             # registers hooks
 ```
 
-## Hook Input (stdin JSON)
+## 3. Stdin contract (per event)
+
+All hook input arrives as **a single JSON object on stdin**. Read with a timeout — never hang.
 
 ```typescript
-// UserPromptSubmit
-interface PromptInput {
-  user_prompt: string;
+// Common envelope (most events)
+interface HookInput {
   session_id: string;
+  cwd: string;
+  transcript_path?: string;
+  hook_event_name: string;        // e.g. "Stop"
 }
 
-// Stop
-interface StopInput {
-  stop_hook_active?: boolean;  // Cycle detection
-  transcript?: string;
+interface UserPromptSubmitInput extends HookInput {
+  user_prompt: string;
 }
-```
 
-## Hook Output (stdout JSON)
+interface PreToolUseInput extends HookInput {
+  tool_name: string;              // "Bash" | "Edit" | "Write" | ...
+  tool_input: Record<string, unknown>;
+}
 
-```typescript
-// UserPromptSubmit — inject system message
-{ "continue": true, "systemMessage": "WORKFLOW: ..." }
+interface PostToolUseInput extends PreToolUseInput {
+  tool_response: unknown;
+  tool_error?: string;
+}
 
-// Stop — approve or block
-{ "continue": false, "decision": "approve", "reason": "All checks passed" }
-{ "continue": true, "decision": "block", "reason": "Uncommitted files" }
+interface StopInput extends HookInput {
+  stop_hook_active?: boolean;     // TRUE if a previous Stop hook already blocked — don't loop
+}
+
+interface SubagentStopInput extends StopInput {
+  subagent_id: string;
+}
+
+interface PreCompactInput extends HookInput {
+  trigger: "manual" | "auto";
+}
 ```
 
-## Template: Stop Validator
+## 4. Stdout contract (per event)
 
-```typescript
-#!/usr/bin/env node
-import { execSync } from 'child_process';
+Output a **single JSON object on stdout**. Anything else (or invalid JSON) is treated as advisory only.
 
-function cmd(c: string): string {
-  try { return execSync(c, { encoding: 'utf8' }).trim(); } catch { return ''; }
+```typescript
+// Universal fields
+interface HookOutput {
+  continue?: boolean;             // false = stop the agent now (Stop family)
+  decision?: "approve" | "block"; // gate verdict
+  reason?: string;                // shown to user / logged
+  systemMessage?: string;         // injected as system message (UserPromptSubmit, SessionStart)
+  hookSpecificOutput?: Record<string, unknown>;
 }
+```
 
-const branch = cmd('git rev-parse --abbrev-ref HEAD');
-const dirty = cmd('git status --porcelain');
+PreToolUse — block / approve / rewrite a tool call:
+```json
+{ "decision": "approve", "reason": "Edit on src/ allowed" }
+{ "decision": "block",   "reason": "Write outside src/ rejected" }
+```
 
-const result = (!dirty && (branch === 'main' || branch === 'master'))
-  ? { continue: false, decision: 'approve', reason: 'Clean main branch' }
-  : { continue: true, decision: 'block', reason: `Branch: ${branch}, dirty: ${!!dirty}` };
+Stop — block prevents finalization until issues are fixed:
+```json
+{ "continue": true, "decision": "block", "reason": "Uncommitted files" }
+```
 
-console.log(JSON.stringify(result));
+SessionStart — inject context:
+```json
+{ "systemMessage": "ROUTINE: research → plan → implement → test → commit" }
 ```
 
-## settings.json Registration
+## 5. Exit-code semantics
+
+| Exit | Meaning |
+|---|---|
+| `0` | Success — JSON output applied if present |
+| `2` | **Blocking** — message printed to stderr is shown to the user (alternative to `decision: "block"`) |
+| anything else | Non-blocking error — logged, agent continues |
+
+**Never** exit non-zero on a transient error (e.g. network) unless you intend to block. Hooks must be deterministic.
+
+## 6. `settings.json` registration
 
 ```json
 {
   "hooks": {
-    "Stop": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" stop-validator", "timeout": 30 }] }],
-    "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" user-prompt-submit", "timeout": 10 }] }]
+    "SessionStart": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" session-start",
+          "timeout": 10
+        }]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" user-prompt-submit",
+          "timeout": 10
+        }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" pre-tool-use",
+          "timeout": 10
+        }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" stop-validator",
+          "timeout": 30
+        }]
+      }
+    ]
   }
 }
 ```
 
-## Rules
+`matcher` is a regex against `tool_name` (PreToolUse / PostToolUse) or empty for "all". Multiple entries per event are run in registration order.
+
+## 7. `run-hook.sh` dispatcher
+
+Survives whichever runtime the user has installed. Always-zero exit so hook errors don't kill the session.
+
+```bash
+#!/usr/bin/env bash
+# .claude/hooks/run-hook.sh
+set -uo pipefail
+HOOK_NAME="${1:?missing hook name}"
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_FILE="$HOOK_DIR/${HOOK_NAME}.ts"
+
+[[ -f "$HOOK_FILE" ]] || { echo '{"continue":true}'; exit 0; }
+
+if   command -v bun >/dev/null 2>&1; then bun  "$HOOK_FILE"
+elif command -v tsx >/dev/null 2>&1; then tsx  "$HOOK_FILE"
+elif command -v node >/dev/null 2>&1; then npx --yes tsx "$HOOK_FILE"
+else echo '{"continue":true}'; exit 0
+fi
+```
+
+## 8. Stop validator template (gate-aware, with cycle detection)
+
+Use `execFileSync` (not `execSync` with shell strings) — passes args as an array, immune to shell injection.
+
+```typescript
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+
+function git(...args: string[]): string {
+  try { return execFileSync('git', args, { encoding: 'utf8' }).trim(); } catch { return ''; }
+}
+
+const input = JSON.parse(readFileSync(0, 'utf8'));      // stdin
+
+// Cycle detection — if we already blocked once, approve to avoid infinite loop
+if (input.stop_hook_active) {
+  console.log(JSON.stringify({ continue: false, decision: 'approve' }));
+  process.exit(0);
+}
+
+const dirty   = git('status', '--porcelain');
+const issues: string[] = [];
+
+if (dirty)                                                    issues.push(`GIT_TREE_NOT_CLEAN: ${dirty.split('\n').length} file(s)`);
+if (existsSync('CLAUDE.md') &&
+    !readFileSync('CLAUDE.md', 'utf8').includes('Last Change')) issues.push('CLAUDE_MD_NOT_UPDATED');
+
+const result = issues.length === 0
+  ? { continue: false, decision: 'approve', reason: 'All checks passed' }
+  : { continue: true,  decision: 'block',   reason: issues.join(' | ') };
+
+console.log(JSON.stringify(result));
+process.exit(0);
+```
+
+## 9. Performance & safety rules
+
+1. **Timeouts:** 10s for `UserPromptSubmit` / `PreToolUse` / `SessionStart`; 30s for `Stop` / `SubagentStop`.
+2. **Always exit 0** unless intentionally blocking with exit 2 — non-zero kills the session.
+3. **Read stdin with timeout** — `readFileSync(0, 'utf8')` is fine (it returns immediately when EOF).
+4. **Output valid JSON** — invalid JSON is treated as advisory and silently dropped.
+5. **Cycle detection** — check `stop_hook_active` in `Stop` / `SubagentStop`. Without this, a buggy hook can lock the agent in an infinite block-fix-block loop.
+6. **No network calls** in hot-path hooks (`PreToolUse`, `UserPromptSubmit`) — they fire on every tool call / prompt.
+7. **Idempotent** — hooks may be invoked twice (retries, restarts). Don't write to immutable state without a guard.
+8. **Use `execFileSync`, never `execSync` with a shell string** — the latter is shell-injection-prone if any input ever flows in.
+
+## 10. Common patterns
+
+| Goal | Event | Pattern |
+|---|---|---|
+| "Inject the current routine on every prompt" | `UserPromptSubmit` | `{ continue: true, systemMessage: "ROUTINE: ..." }` |
+| "Block writes outside `src/`" | `PreToolUse` | match `Write\|Edit`, inspect `tool_input.path`, `decision: "block"` if outside |
+| "Run quality gate before finishing" | `Stop` | run typecheck/lint/tests, `decision: "block"` if any fail |
+| "Persist subagent output to disk" | `SubagentStop` | parse `tool_response`, write to `.claude/subagent-outputs/{id}.json` |
+| "Snapshot transcript before compaction" | `PreCompact` | copy `transcript_path` to `.claude/transcripts/{session_id}.jsonl` |
+
+## FORBIDDEN
+
+| Pattern | Why |
+|---|---|
+| `process.exit(1)` on transient error | Kills the session |
+| Hook output not valid JSON | Dropped silently — no enforcement |
+| Network call in `PreToolUse` | Adds latency to every tool call |
+| Forgetting `stop_hook_active` check | Infinite block loop |
+| Writing to `CLAUDE.md` from `Stop` hook | Triggers another `Stop` cycle |
+| Hardcoded user paths (`~/Users/me/...`) | Won't run on other machines |
+| Shell-string `execSync` for git/fs commands | Shell-injection surface |
+
+## See Also
 
-1. **Always use `run-hook.sh` as entry** — handles bun/tsx fallback
-2. **Read stdin with timeout** — hooks must not hang
-3. **Exit 0 always** — non-zero kills the session
-4. **Output valid JSON to stdout** — Claude Code parses it
-5. **Cycle detection** — check `stop_hook_active` flag in Stop hooks
-6. **Keep hooks fast** — timeout applies (10s for prompt, 30s for stop)
+- `quality-gate` — the Stop validator's typical payload
+- `git-workflow` — branch / dirty-tree checks
+- `commit-manager` — pairs with Stop validator (validator detects, commit-manager fixes)

package/stacks/_shared/skills/observability/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: observability
-version: 1.0.0
-description: Structured logging, correlation IDs, OpenTelemetry tracing, error tracking (Sentry), metrics, and PII redaction. Invoke when adding logging, instrumentation, or debugging production issues.
+version: 2.0.0
+description: "Structured logging, correlation IDs, OpenTelemetry tracing (semconv 1.41+, including GenAI conventions for Anthropic / OpenAI / AWS Bedrock / Azure AI / MCP), error tracking (Sentry), metrics, PII redaction, audit log separation. Invoke when adding logging, instrumentation, AI/LLM observability, or debugging production issues."
 ---
 
 # Observability — Logs, Traces, Metrics
@@ -285,6 +285,75 @@ Cardinality rule: never tag with user_id, email, or unbounded values — explode
 
 ---
 
+## 6.5. AI / LLM Observability — OTel GenAI Semantic Conventions *(2026)*
+
+OpenTelemetry GenAI conventions (semconv ≥ 1.37, current ≥ 1.41) standardize how LLM calls are traced. They cover: **model spans**, **agent spans**, **events** (inputs/outputs), and provider-specific conventions for **Anthropic, OpenAI, AWS Bedrock, Azure AI Inference, and MCP (Model Context Protocol)**.
+
+> Status: Development (not yet stable). Set `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` to opt in to current attribute names. **Do not use deprecated `gen_ai.prompt` / `gen_ai.completion` attributes** — they were removed in 1.28 in favor of log-based events.
+
+### Required attributes on every LLM span
+
+| Attribute | Example |
+|---|---|
+| `gen_ai.system` | `"anthropic"`, `"openai"`, `"aws.bedrock"`, `"azure.ai.inference"` |
+| `gen_ai.operation.name` | `"chat"`, `"text_completion"`, `"embeddings"` |
+| `gen_ai.request.model` | `"claude-opus-4-5"`, `"gpt-5"`, `"sonnet-4-5"` |
+| `gen_ai.response.model` | The actual model that served the request (may differ on Bedrock/Gateway) |
+| `gen_ai.usage.input_tokens` | Numeric |
+| `gen_ai.usage.output_tokens` | Numeric |
+| `gen_ai.response.finish_reasons` | `["stop"]`, `["length"]`, `["tool_calls"]` |
+
+### Recording inputs/outputs as **events** (not attributes)
+
+```ts
+import { trace, SpanKind } from '@opentelemetry/api';
+const tracer = trace.getTracer('llm');
+
+await tracer.startActiveSpan('chat anthropic', { kind: SpanKind.CLIENT }, async (span) => {
+  span.setAttributes({
+    'gen_ai.system': 'anthropic',
+    'gen_ai.operation.name': 'chat',
+    'gen_ai.request.model': 'claude-opus-4-5',
+  });
+
+  // Inputs/outputs go as EVENTS, not attributes — keeps spans cheap, allows redaction
+  span.addEvent('gen_ai.user.message', { 'gen_ai.message.content': redact(userMsg) });
+
+  const res = await anthropic.messages.create({ /* ... */ });
+
+  span.setAttributes({
+    'gen_ai.response.model': res.model,
+    'gen_ai.usage.input_tokens': res.usage.input_tokens,
+    'gen_ai.usage.output_tokens': res.usage.output_tokens,
+    'gen_ai.response.finish_reasons': [res.stop_reason],
+  });
+  span.addEvent('gen_ai.assistant.message', { 'gen_ai.message.content': redact(res.content) });
+  span.end();
+  return res;
+});
+```
+
+### MCP (Model Context Protocol) spans
+
+For agentic flows that call MCP servers:
+- `gen_ai.system`: `"mcp"`
+- `gen_ai.tool.name`: tool invoked
+- Span kind: `CLIENT` (your agent → MCP server)
+
+### Cost & token metrics
+
+```ts
+const meter = metrics.getMeter('llm');
+const tokensUsed = meter.createCounter('gen_ai.client.token.usage', { unit: '{token}' });
+
+tokensUsed.add(res.usage.input_tokens,  { 'gen_ai.system': 'anthropic', 'gen_ai.token.type': 'input',  'gen_ai.request.model': 'claude-opus-4-5' });
+tokensUsed.add(res.usage.output_tokens, { 'gen_ai.system': 'anthropic', 'gen_ai.token.type': 'output', 'gen_ai.request.model': 'claude-opus-4-5' });
+```
+
+**PII rules still apply** — redact user content in events the same way you redact request bodies in HTTP logs.
+
+---
+
 ## 7. Health Checks
 
 Two endpoints, distinct semantics:
@@ -331,6 +400,7 @@ Different retention (often longer), different access (security team), different
 - [ ] Sentry initialized with `beforeSend` scrubber
 - [ ] Tracing initialized at process start (before app code)
 - [ ] `/healthz` + `/readyz` endpoints exist
+- [ ] LLM calls emit `gen_ai.*` attributes + token-usage metrics; user content redacted
 
 ## FORBIDDEN
 

package/stacks/_shared/skills/openapi-design/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: openapi-design
-version: 1.0.0
-description: OpenAPI 3.1 spec design — resource naming, status codes, problem+json (RFC 9457) errors, pagination, versioning, security schemes, idempotency, deprecation. Stack-agnostic. Invoke when designing or documenting any HTTP/REST API that publishes an OpenAPI spec, regardless of framework (Fastify, Hono, FastAPI, Laravel, Express, etc.).
+version: 2.0.0
+description: "OpenAPI 3.1 / 3.2 spec design — resource naming, status codes, problem+json (RFC 9457) errors, pagination, versioning, security schemes, idempotency, deprecation. Covers OpenAPI 3.2 (Sept 2025) deltas: native Server-Sent Events (SSE), JSON Lines streaming, hierarchical tags (parent/kind), QUERY HTTP method, additionalOperations, querystring location, $self document URI, OAuth2 device flow. Fully backward-compatible with 3.1 (no breaking changes). Stack-agnostic. Invoke when designing or documenting any HTTP/REST API that publishes an OpenAPI spec, regardless of framework (Fastify, Hono, FastAPI, Laravel, Express, etc.)."
 ---
 
-# OpenAPI Design — Universal API Contract
+# OpenAPI Design — Universal API Contract (3.1 + 3.2)
 
 **Invoke before adding a new endpoint, before publishing a public API, and during code review of any route handler.**
 
@@ -12,6 +12,27 @@ description: OpenAPI 3.1 spec design — resource naming, status codes, problem+
 
 This skill covers **what the spec should look like**. For **how to generate it** in your stack, see the per-framework skill (`fastify-api`, `hono-api`, `fastapi-patterns`, `laravel-patterns`, etc.).
 
+## Version policy (2026)
+
+- **OpenAPI 3.2** (Sept 2025): adopt for new specs — fully backward-compatible with 3.1, just bump the `openapi` field. **Zero breaking changes.**
+- **OpenAPI 3.1** (Feb 2021): full JSON Schema 2020-12 — still fine for stable APIs.
+- **OpenAPI 3.0**: legacy. Migrate when convenient.
+
+### What 3.2 adds (cheat sheet)
+
+| Feature | Use when |
+|---|---|
+| **Server-Sent Events (SSE)** as a first-class media type | Long-running progress, AI streaming responses, live dashboards |
+| **JSON Lines** (`application/jsonl`) | Streaming row-oriented data (logs, exports) |
+| **Multipart streaming** | Upload progress with metadata |
+| **Hierarchical tags** (`parent`, `kind`, `summary`) | Replaces vendor-extensions `x-tagGroups`, `x-displayName`. Native nav for large APIs. |
+| **`QUERY` HTTP method** | Safe & idempotent reads with a request body (search APIs that exceed URL limits) |
+| **`additionalOperations`** field | Document custom HTTP verbs without spec extensions |
+| **`querystring` parameter location** | Describe an entire query string as a single typed parameter |
+| **`$self`** document URI | Solves multi-document `$ref` resolution |
+| **OAuth2 Device Authorization flow** | CLI / IoT auth |
+| **Discriminator `defaultMapping`** | Cleaner polymorphic schemas |
+
 ---
 
 ## 1. Resource Naming
@@ -52,6 +73,93 @@ The action sub-resource pattern (`/orders/{id}/cancel`) is the escape hatch when
 
 ---
 
+## 2.5. Streaming Responses *(OpenAPI 3.2)*
+
+Stop documenting streams as `200 application/json` with hand-rolled extensions. 3.2 lets you describe SSE, JSON Lines, and multipart streams natively.
+
+### Server-Sent Events (SSE)
+
+```yaml
+paths:
+  /chat/{id}/stream:
+    get:
+      summary: Stream assistant tokens as they generate
+      responses:
+        '200':
+          description: SSE stream
+          content:
+            text/event-stream:
+              schema:
+                type: object
+                properties:
+                  event: { type: string, enum: [token, tool_call, done] }
+                  data:  { type: object }
+```
+
+### JSON Lines (newline-delimited JSON)
+
+```yaml
+paths:
+  /exports/{id}:
+    get:
+      responses:
+        '200':
+          description: One JSON object per line
+          content:
+            application/jsonl:
+              schema:
+                $ref: '#/components/schemas/Order'
+```
+
+Use SSE for **client subscribes to live updates** (chat tokens, progress); JSON Lines for **bulk row export** (logs, analytics dumps). Document the terminator (`event: done` for SSE; EOF for JSON Lines) so codegen clients know when to stop reading.
+
+---
+
+## 2.6. Hierarchical Tags *(OpenAPI 3.2)*
+
+Replaces the legacy `x-tagGroups` / `x-displayName` extensions. Native nested navigation in tools that support 3.2.
+
+```yaml
+tags:
+  - name: billing
+    summary: Billing
+    kind: nav            # 'nav' = navigation group only, no operations directly under it
+  - name: invoices
+    parent: billing
+    summary: Invoices
+  - name: payments
+    parent: billing
+    summary: Payments
+```
+
+For tools still on 3.1, the same effect is achieved with `x-tagGroups` / `x-displayName`. Specs published as 3.2 should drop the extensions.
+
+---
+
+## 2.7. The `QUERY` HTTP method *(OpenAPI 3.2)*
+
+For **safe & idempotent** reads whose parameters exceed URL length limits (complex search, large filter sets). Bodies on `GET` are technically legal but proxies eat them; `QUERY` is the standardized escape hatch.
+
+```yaml
+paths:
+  /search:
+    additionalOperations:
+      QUERY:
+        summary: Complex search
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchRequest'
+        responses:
+          '200': { $ref: '#/components/responses/SearchResults' }
+```
+
+`QUERY` is **safe** (no side effects) and **idempotent** (same body → same response) — clients and caches treat it like `GET`.
+
+---
+
 ## 3. Error Envelope — `application/problem+json` (RFC 9457)
 
 One shape for every error response in the entire API. Codegen clients can match a single discriminator.