Skip to content

docs: resolve documentation audit findings for 2026-04-08#27

Draft
j-shilling wants to merge 5 commits intomainfrom
codex/docs-audit-2026-04-08
Draft

docs: resolve documentation audit findings for 2026-04-08#27
j-shilling wants to merge 5 commits intomainfrom
codex/docs-audit-2026-04-08

Conversation

@j-shilling
Copy link
Copy Markdown
Collaborator

Summary

  • add a dated documentation audit report at docs/audit/2026-04-08_09:26:34.md
  • repair runtime, setup, guide, feature, research, and AGENTS.md drift around current routes, skip-auth behavior, and the versioned OpenAPI entrypoint
  • replace the stale Cognito feature page with a branch-accurate skip-auth identity page

What Was Fixed

  • runtime docs now reflect GET /health, GET /api-spec/v1/verify, POST /api/v0/education-enrollments, and POST /api/v0/veteran-disability-ratings
  • setup docs now reflect the actual config surface and committed docker-compose.yml services
  • contract-oriented guides now clearly distinguish checked-in OpenAPI expectations from current runtime auth behavior
  • AGENTS.md now points at api-spec/v0/openapi.yaml

What Remains Unresolved

  • the branch still has a contract-vs-runtime auth gap: the OpenAPI and consumer guides describe OAuth2 bearer-token usage, while the running Go service does not yet implement in-process bearer-token validation
  • this PR documents that gap explicitly but does not change runtime auth behavior or Terraform-related infrastructure

Audit Report

  • docs/audit/2026-04-08_09:26:34.md

Validation

  • pnpm exec markdownlint-cli2 AGENTS.md README.md api-spec/README.md schema/README.md 'docs/**/*.md'

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant