Plan: Documentation Pass — UAT Readiness for All Audiences

Following CRAIG’s proven 3-layer documentation model:

New files follow CRAIG’s directory patterns:

Files: .claude/CLAUDE.md, .claude/docs/services.md, CHANGELOG.adoc, docs/modules/ROOT/nav.adoc, docs/modules/ROOT/pages/roadmap.adoc, plan status tables

Files: .claude/docs/shared-crates.md, .claude/docs/rulesets.md, .claude/docs/known-issues.md

shared-crates.md: Document public API surface of all 10 shared crates (canopy-common, canopy-auth, canopy-db, canopy-mq, canopy-api, canopy-store, canopy-reference, canopy-signing, canopy-typst, canopy-rules-client, canopy-test-lib). For each: purpose, key types/traits, example usage.

rulesets.md: JDM format reference, decision table syntax, hit policies (first, collect), rule ordering, jurisdiction patterns (rulesets/federal/ vs rulesets/{jurisdiction}/), jurisdiction.toml structure, how to add a new ruleset.

known-issues.md: Devstack gotchas (Garage rpc_bind_addr, Docker orphan containers, stale test profile cache), Keycloak quirks (password hash format, emailVerified for password grant), nextest concurrency limits, cargo audit transitive typst advisories.

Files: SECURITY.adoc, README.adoc, CONTRIBUTING.adoc

SECURITY.adoc expansion (model after CRAIG): * Supported versions table (current: 0.1.x) * Remediation SLAs: Critical (24h patch + deploy), High (7 business days), Medium (30 days), Low (next scheduled release) * Security measures checklist (15+ items: #![forbid(unsafe_code)], parameterized SQL, OIDC, rustls, Alpine, CSP, rate limiting, audit logging, cargo-deny, SAST, secret detection, container scanning, session security, field encryption, event payload validation)

README.adoc: Verify quick start commands are current, add link to Antora site, ensure non-developer path is clear.

CONTRIBUTING.adoc: Add "your first contribution" section, link to troubleshooting guide.

Files: docs/modules/ROOT/pages/guide/caseworker.adoc

Document all 10 SNAP caseworker workflows with: * Step-by-step instructions (numbered, with expected outcomes) * Screenshots from worker portal (captured in Step 12) * Regulatory context (7 CFR citations for why each step matters) * Common errors and what to do

Workflows: 1. Login and navigation (Keycloak OIDC, sidebar, theme toggle) 2. Case search (htmx live search, name/SSN/case number) 3. Case detail (6 tabs: household, income, determination, notices, appeals, activity) 4. Application processing (expedited screening, eligibility review, approve/deny) 5. Appeal filing (form fields, continued benefits, hearing rights) 6. Interim contact recording (certification midpoint, contact methods) 7. Change report submission (income change, household change, threshold check) 8. ABAWD activity tracking (work hours, qualifying months, exemptions) 9. Verification discrepancy resolution (IEVS income comparison, resolve/dismiss) 10. Renewal queue management (filter by urgency, notice status, interim contacts)

Files: docs/modules/ROOT/pages/deployment-guide.adoc

Files: docs/modules/ROOT/pages/security-operations.adoc, operational runbook sections

Files: docs/modules/ROOT/pages/ato-readiness.adoc, docs/modules/ROOT/pages/nist-architecture-mapping.adoc

ATO readiness checklist: Infrastructure prerequisites, security configuration validation, compliance documentation inventory, NIST control mapping completeness, biennial review schedule.

NIST 800-53 mapping: Map each relevant control family to Canopy implementation: * AC (Access Control) → Keycloak RBAC, role guards, session management * AU (Audit & Accountability) → canopy-security wildcard subscriber, hash chain, breach detection * IA (Identification & Authentication) → Keycloak OIDC, RS256 JWT, JWKS refresh * SC (System & Communications Protection) → rustls, field encryption, CSP, event payload validation * SI (System & Information Integrity) → cargo-deny, SAST, secret detection, input validation * MP (Media Protection) → S3 encryption, database SSL * PE (Physical & Environmental) → defer to cloud provider / state data center

Compliance matrix: IRS Pub 1075 controls → implementation, HIPAA controls → implementation, IEVS controls → implementation. Each control links to ADR, code file, and test that verifies it.

Data retention policy: Per data type (FTI: 5 years per Pub 1075 §4, IEVS: per state CMA, HIPAA PHI: 6 years, general PII: per state records retention schedule).

Files: docs/modules/ROOT/pages/developer-guide.adoc, docs/modules/ROOT/pages/configuration-reference.adoc, docs/modules/ROOT/pages/troubleshooting.adoc

Developer guide additions: * "Your first contribution" walkthrough (add a simple API endpoint end-to-end) * Debugging guide (tracing, RUST_LOG, docker logs, database queries) * cargo xtask command reference with dev refresh, --timing flag * Staleness guard explanation

Configuration reference (new page): All environment variables per service, extracted from canopy-common/src/settings.rs and docker-compose.yml. Grouped by service with defaults and descriptions.

Troubleshooting (new page): Common devstack issues (port conflicts, stale containers, migration failures), Keycloak configuration (password hash, emailVerified, realm import), test failures (infrastructure guard, transient DB connections), cargo audit advisories.

Files: docs/modules/ROOT/pages/evaluator-guide.adoc

Files: docs/modules/ROOT/pages/security-operations.adoc (append new section)

Issue: #264 — remaining gap is data flow diagrams. All other items in #264 were delivered in Steps 6-7.

Add a == Data Flow Diagrams section to the end of security-operations.adoc with 4 Mermaid sequence diagrams. Use [mermaid] / …​. block syntax (asciidoctor-kroki).

Diagram 1 — PII (SSN) Flow:

Key files: services/canopy-persons/src/store/persons.rs:9 (encrypt_ssn), crates/canopy-common/src/crypto.rs:16 (encrypt). SSN stored as [12-byte nonce | ciphertext | 16-byte auth tag] in persons.ssn_encrypted (BYTEA). Decrypted only on authorized read via Claims::require_caseworker_or_above().

Diagram 2 — FTI Flow:

Key files: services/canopy-tanf/migrations/20260325000001_create_fti_audit_log.sql (audit schema), crates/canopy-mq/src/publisher.rs:90 (RESTRICTED_FIELDS, 27 blocked field names). canopy-medicaid has identical isolation (COMPLIANCE.md) but FTI tables not yet implemented (post-UAT).

Diagram 3 — IEVS Flow:

Key files: services/canopy-snap/src/verification.rs:54 (run_verification), services/canopy-snap/src/verification_client.rs:54 (POST to verification), services/canopy-verification/src/api/ievs.rs:63 (handle_ievs_match), services/canopy-verification/src/noop.rs (NoopIevsAdapter for UAT). Tables: ievs_match_results, ievs_discrepancies in canopy-snap DB only.

Diagram 4 — Determination Signing Flow (ADR-002):

Key files: services/canopy-snap/src/determine.rs:295 (sign), services/canopy-snap/src/api/determine_handler.rs:101 (response), services/canopy-eligibility/src/orchestrator.rs:345 (verify), crates/canopy-signing/src/signer.rs (SigningKey), crates/canopy-signing/src/verifier.rs (VerifyingKeyRegistry).

After the 4 diagrams, add a brief encryption inventory table:

Closes: #264

Files: docs/modules/ROOT/pages/api/ directory — one .adoc file per implemented service (12 files)

Issue: #265

Prerequisite: Devstack must be running (cargo xtask dev start). Run cargo xtask api-docs --update to generate fresh OpenAPI JSON snapshots into test-results/openapi/. The snapshots are the authoritative source for endpoint details.

State machine diagrams were completed in MR !64 (Step 13). Data model docs and design specs are deferred to a future pass since they require ER diagram tooling and deeper schema analysis.

Template — each api/canopy-{service}.adoc file follows this structure:

{example request body from OpenAPI schema, or "No request body" for GET}

{example response from OpenAPI schema}

Per-service endpoint counts (from agent research, verified against code):

Implementation steps:

Do not create files for stub services (canopy-exchange, canopy-tanf, canopy-medicaid, canopy-caps, canopy-wic, canopy-portal) — they have no domain routes.

Closes: #265

Files: docs/modules/ROOT/pages/federal-requirements.adoc, docs/modules/ROOT/pages/cli.adoc

Plan archive (plans/archive.adoc) and state machine diagrams (state-machines.adoc) were completed in MR !64. Screenshots are deferred until after the Antora Mermaid/Kroki integration is verified in CI.

federal-requirements.adoc — Map each 7 CFR section to Canopy implementation. Table format:

For TANF (45 CFR Part 261), Medicaid (42 CFR Part 431), CAPS (45 CFR Part 98), and WIC (7 CFR 246): add placeholder rows noting "Planned — see {program}-eligibility plan" since these programs are stub services.

cli.adoc — Document all cargo xtask subcommands. Source: read xtask/src/cmd/*.rs files for argument definitions.

For each command, read the corresponding xtask/src/cmd/{command}.rs file and document all CLI arguments, environment variable overrides, and exit codes.

Files: docs/modules/ROOT/nav.adoc

Rebuild to 6-section hierarchy matching CRAIG: