Skip to content

Docs Update Checklist

Last refreshed: 2026-05-18

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.

flowchart LR
  change["🛠️ Code or behavior change"] --> durable{"Durable system behavior?"}
  change --> operational{"Paths, commands, maps, gaps?"}
  change --> large{"Large-change workflow?"}
  durable -->|yes| core["Update docs/core"]
  operational -->|yes| state["Update docs/state"]
  large -->|yes| changeDocs["Update docs/changes/<change>"]

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 change:

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

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.