maintaining-docs.md

Maintaining the docs

The documentation in docs/ is the single source of truth. It is only as useful as it is current, so updating it is part of the Definition of Done for any code change.

Definition of Done

A change is done only when the relevant docs are updated alongside the code:

• architecture or an interaction contract changed → update docs/architecture/*;
• a package's public API / purpose changed → update docs/packages/<dir>.md;
• a package was added/removed → add/remove docs/packages/<dir>.md (otherwise pnpm docs:check fails) and update the links in index.md;
• a roadmap.md item was completed → move it to the Done section;
• a notable technical decision was made → add an ADR.

Run pnpm docs:check before a PR (package coverage + link validity).

Trigger table: code path → what to update

You change	Update
apps/web/src/server/**, SSR, res.locals	architecture/web-ssr.md
apps/backend/** (modules, guard, Supabase)	architecture/backend.md
Backend DTO / handler return types	architecture/api-contract.md + regenerate schemas
Data layer (Query / DataSource)	architecture/data-layer.md
i18n messages / locale pipeline	architecture/i18n.md
Cross-package dependencies, FSD layers	architecture/package-interaction.md
A package's public exports	docs/packages/<dir>.md
A package's scripts	the package's README.md (docs link to scripts, they don't duplicate them)

Where the pointers live

Agents see the same rule set through thin pointers (the prose lives only here and in docs/):

• AGENTS.md — cross-tool entry point (read natively by Cursor).
• CLAUDE.md — imports AGENTS.md and the key docs via @-references.
• .cursor/rules/*.mdc — pull the relevant page by globs while you edit code.

Edit rules in docs/, not in the pointers, so they can't drift.