docs: 0.21 capture-integrity directives in SKILL.md + README

[drewstone]

Summary

Documentation follow-up to #36. The four primitives shipped in 0.21.0 (RawProviderSink, assertLlmRoute, assertRunCaptured, traceAnalystOnRunComplete) are operational discipline, not analytical surface — they only prevent the launch-grade-failure bug class if consumers actually wire them. This PR encodes them as required SKILL.md directives with shipped-bug rationale, and adds a runnable composed example to the README.

Why this matters before publishing 0.21.0 to npm

If the npm tarball's README.md doesn't show the four directives, the next consumer reaches for the analytical surface only and re-hits the same wall (raw events not captured, route silently wrong, integrity not asserted, analyst never ran). Land this before tagging.

SKILL.md changes

• "Decide where to start" table: 5 new rows pointing at researchReport + the four capture-integrity primitives.
• "Production-rigor primitives" table: rows for researchReport, RawProviderSink, assertLlmRoute, assertRunCaptured, onRunComplete hooks — each with use-case, location, and a forward-link to its directive.
• New "Capture integrity (REQUIRED for launch-grade adoption)" section with four directives. Each carries:
  • The runnable shape.
  • The "why" (paid-bug rationale).
  • The shipped incident (blueprint-agent matrix run).
  • Plus a composed-shape snippet showing how the four wire together.
• New pitfalls 12–15:
  • researchReport is async (0.21+).
  • Default minPairs raised from 6 to 20; hard floor 6 enforced via RESEARCH_REPORT_HARD_PAIR_FLOOR.
  • RawProviderSink redaction is allowlist-of-strip, not allowlist-of-keep — custom auth headers won't auto-strip.
  • onRunComplete hooks swallow + log errors by default; opt into propagation via hookErrors: 'throw'.

README.md changes

• "Core Pieces" table: rows for the four capture-integrity primitives.
• New "Capture integrity (0.21+)" section with the composed runnable example + back-link to SKILL.md.

Test plan

• No code changes; SKILL.md and README only.
• pnpm typecheck clean.
• pnpm test — 867 / 867 still passing.
• Skim rendered SKILL.md on GitHub for table/heading regressions before publishing.

[tangletools]

✅ No Blockers — 503aa18a

Readiness 95/100 · Confidence 95/100 · 0 findings (none)

	kimi-code	deepseek	aggregate
Readiness	98	95	95
Confidence	98	95	95
Correctness	100	95	95
Security	100	95	95
Testing	95	90	90
Architecture	100	95	95

This is a documentation-only PR updating SKILL.md and README.md to document the 0.21+ 'Capture integrity' four-directive pattern and related APIs (researchReport, RawProviderSink, assertLlmRoute, assertRunCaptured, traceAnalystOnRunComplete). I verified every referenced API exists in the source (src/summary-report.ts, src/llm-client.ts, src/trace/integrity.ts, src/trace-analyst/hook.ts, src/trace/raw-provider-sink.ts, src/trace/emitter.ts), every export path (./traces) is declared in package.json, and every linked doc (docs/research-report-methodology.md, docs/concepts.md) exists. Tests show 7

No findings.

---

_{tangletools · 2026-05-08T16:53:36Z · trace}

[tangletools]

✅ Clean

This is a documentation-only PR updating SKILL.md and README.md to document the 0.21+ 'Capture integrity' four-directive pattern and related APIs (researchReport, RawProviderSink, assertLlmRoute, assertRunCaptured, traceAnalystOnRunComplete). I verified every referenced API exists in the source (src/summary-report.ts, src/llm-client.ts, src/trace/integrity.ts, src/trace-analyst/hook.ts, src/trace/raw-provider-sink.ts, src/trace/emitter.ts), every export path (./traces) is declared in package.json, and every linked doc (docs/research-report-methodology.md, docs/concepts.md) exists. Tests show 7

No findings.

---

_{tangletools · 2026-05-08T16:53:36Z · trace}