agentic-dev/docs/work/epics/security-headers-rate-limit-sbom/11-documentation/_story.md

id, epic, title, type, status, feature, depends-on, blocks, created, updated

id	epic	title	type	status	feature	depends-on	blocks	created	updated
11-documentation	security-headers-rate-limit-sbom	Documentation and conformance reference updates	technical-story	done	core-shared	05-auth-signin-rate-limit-backfill 08-app-wiring-web-next 09-app-wiring-web-tanstack-and-cms 10-sbom-ci-workflow		2026-05-20T00:00:00Z	2026-05-20T11:49:44.873Z

Goal

Write the consumer-facing cookbooks (security-headers.md, rate-limiting.md) and update the cross-cutting reference docs (glossary, CLAUDE.md, conformance quickref) so downstream consumers, AI agents, and compliance officers can discover and apply security headers, rate-limiting, and SBOM from a single reading session.

Why

Implementations are complete after Story 10, but the institutional knowledge of how to use them, customize them, and understand their conformance contracts lives only in code. The cookbooks close that gap by walking concrete wiring steps, key-naming conventions, and verification workflows. The CLAUDE.md and conformance-quickref updates keep the conformance rule count accurate (12 → 13) and surface the rateLimit manifest field in the authoritative reference every agent reads at session start.

Done when

• docs/guides/security-headers.md covers: per-framework middleware wiring (Next.js, TanStack, CMS), nonce threading for consumer-added inline scripts, CSP allowlist customization (allowedConnectOrigins etc.), Sentry nonce integration steps, securityheaders.com verification workflow.
• docs/guides/rate-limiting.md covers: manifest rateLimit field declaration, canonical key-naming convention <feature>:<scope>:<key>, multi-budget patterns, InMemoryRateLimit for dev/test, guidance on wiring a production backend via BindContext.rateLimit.
• docs/glossary.md has entries for: IRateLimit, RateLimited (brand), withRateLimit, SecurityHeadersConfig, buildSecurityHeaders, SBOM (CycloneDX context), nonce (CSP context).
• CLAUDE.md conformance rule count updated 12 → 13; rateLimit?: RateLimitBudget[] documented in the manifest field table.
• docs/guides/conformance-quickref.md updated to list no-undeclared-rate-limit as the 13th rule.
• pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff all pass after each task.

In scope

• docs/guides/security-headers.md (new file).
• docs/guides/rate-limiting.md (new file).
• docs/glossary.md — new entries only; no existing entry edits.
• CLAUDE.md — conformance rule count bump (12 → 13) + rateLimit manifest field row.
• docs/guides/conformance-quickref.md — add no-undeclared-rate-limit entry.

Out of scope

• ADR-023 amendment — Story 10.
• Any new code changes — docs only; all implementation is done.
• Compliance fill-in docs (incident runbook, password policy) — Epic D.

Tasks

• Write docs/guides/security-headers.md (per-framework wiring, nonce threading for consumer inline scripts, CSP allowlist customization, Sentry nonce integration, securityheaders.com verification) and docs/guides/rate-limiting.md (manifest field, key-naming convention <feature>:<scope>:<key>, multi-budget patterns, dev/staging/prod backend wiring); all gates pass.
• Add entries for IRateLimit, RateLimited brand, withRateLimit, SecurityHeadersConfig, buildSecurityHeaders, SBOM, nonce (CSP context) to docs/glossary.md; update CLAUDE.md conformance rule count 12 → 13 and add rateLimit?: RateLimitBudget[] to the manifest field documentation; add no-undeclared-rate-limit as the 13th rule in docs/guides/conformance-quickref.md; all gates pass.