Skip to content

Docs Update Checklist

Last refreshed: 2026-07-08

Core Vs State

Update docs/core when durable system behavior changes.

Update docs/state when implementation locations, commands, operational assumptions, known gaps, routes, workflows, collections, or recent decisions change.

Update docs/changes/<change> when using the large-change workflow.

Report product-main sync needs when local work affects product behavior, repository ownership, cross-repository contracts, release readiness, or docs publishing status.

flowchart LR
  change["Code or behavior change"] --> durable{"Durable system behavior?"}
  change --> operational{"Paths, commands, maps, gaps?"}
  change --> large{"Large-change workflow?"}
  change --> productMain{"Product-main sync needed?"}
  durable -->|yes| core["Update docs/core"]
  operational -->|yes| state["Update docs/state"]
  large -->|yes| changeDocs["Update docs/changes/<change>"]
  productMain -->|yes| sync["Record issue, PR, or progress sync note"]

Change Type Checklist

Presentation Video flow:

  • docs/core/PresentationVideoWorkflow.md
  • docs/core/PresentationConfig.md
  • docs/state/ServerActionsMap.md
  • docs/state/WorkflowMap.md
  • docs/state/KnownGaps.md

Mastra agents/workflows/tools:

  • docs/core/MastraAgentsAndTools.md
  • docs/state/WorkflowMap.md
  • docs/state/ScriptsAndCommands.md
  • docs/state/KnownGaps.md

Payload schema:

  • docs/core/PayloadDataModel.md
  • docs/state/CollectionMap.md
  • generated src/payload-types.ts
  • generated import map when admin components change

Auth/workspace:

  • docs/core/AuthAndWorkspace.md
  • docs/state/ServerActionsMap.md
  • docs/state/KnownGaps.md

RAG/source handling:

  • docs/core/RagAndSources.md
  • docs/state/CollectionMap.md
  • docs/state/ScriptsAndCommands.md
  • docs/state/KnownGaps.md

Billing/coins/entitlements:

  • docs/core/BillingAndEntitlements.md
  • docs/state/CollectionMap.md
  • docs/state/EnvAndServices.md
  • docs/state/KnownGaps.md

Workers/jobs/scripts:

  • docs/core/WorkersAndJobs.md
  • docs/state/ScriptsAndCommands.md
  • docs/state/EnvAndServices.md

Routes:

  • docs/state/RouteMap.md
  • relevant core doc if behavior changed

Testing:

  • docs/core/TestingAndVerification.md
  • tests/integration/README.md when harness conventions change

Stale-Term Scan

Useful scans before finishing a docs/process alignment change:

rg -n "anuva-engineering-handbook|Engineering Platform|Handbook docs impact|shared handbook|old template|shared-skill|shared skill" AGENTS.md docs README.md mkdocs.yml
rg -n "docs/state/ROUTING_LAYOUT_MAP|docs/state/BACKEND_CONFIG|docs/state/SERVER_ACTIONS_AND_DATA_FETCHING|docs/state/SYSTEM_ANUVA" .
rg -n "TODO|stale|legacy|deprecated|A0|W0" docs/core docs/state

Docs-Only Verification

  • Run git diff --check.
  • Run mkdocs build --strict when MkDocs is available.
  • Do not run implementation tests unless implementation code changed.
  • Record skipped verification and the reason in the final report or PR completion report.

Generated File Reminders

  • Payload schema change: run pnpm generate:types.
  • Payload admin registration change: run pnpm generate:importmap.
  • Route/action behavior change: run targeted tests and update route/action maps.
  • Model/provider change: run the Mastra provider registry script first.