---
id: 11-documentation
epic: security-headers-rate-limit-sbom
title: Documentation and conformance reference updates
type: technical-story
status: done
feature: core-shared
depends-on:
  [
    05-auth-signin-rate-limit-backfill,
    08-app-wiring-web-next,
    09-app-wiring-web-tanstack-and-cms,
    10-sbom-ci-workflow,
  ]
blocks: []
created: 2026-05-20T00:00:00Z
updated: 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

- [x] 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.
- [x] 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.
