Updating docs after a code change

Use this checklist whenever your PR changes a module's surface — new screen, endpoint, event, permission, or major behaviour change. Lives beside new-module.md and is referenced by the "When adding X, do Y" table in root CLAUDE.md.

The full reference is docs/technical/documentation-portal.md.

---

TL;DR

If you changed…	Touch this	And bump
A page under <module>/frontend/pages/**	docs/user-manual/{en,es}/<module>/screens/<slug>.md	last_verified_commit
A @router.{get,post,...} decorator path or method	docs/technical/<module>/permissions.md and the screen MD that uses it	last_verified_commit on each touched MD
event_bus.publish(...) calls or new EventType constant	docs/technical/<module>/events.md + docs/events-catalog.md (regenerate)	last_verified_commit
get_permissions() return value	docs/technical/<module>/permissions.md + frontend/app/config/permissions.ts	last_verified_commit
Module purpose, models, services in a non-trivial way	docs/technical/<module>/overview.md	last_verified_commit
Anything user-facing on a screen	The matching screen MD in both en/ and es/. New screenshots if the visual changed.	last_verified_commit (each locale)

After the touched files are saved:

# Regenerate the auto-generated catalogs.
python backend/scripts/generate_catalogs.py

# Run the coverage check (warning-only at first).
python backend/scripts/check_docs_coverage.py

Bump the per-module CHANGELOG (backend/app/modules/<module>/CHANGELOG.md) under ## Unreleased.

---

Adding a new screen

1. Decide the screen slug (filename stem of the page — index.vue → list, [id].vue → detail, new.vue → create).
2. Create both locale files:

   docs/user-manual/en/<module>/screens/<slug>.md
   docs/user-manual/es/<module>/screens/<slug>.md

3. Use the frontmatter contract.
4. Take screenshots → docs/screenshots/<module>/<slug>-<state>.png.
5. Bump the per-module CHANGELOG.

Adding a new module

After the standard module bootstrap in new-module.md:

1. Create docs/technical/<module>/{overview,events,permissions}.md.
2. If the module has Nuxt pages, create docs/user-manual/{en,es}/<module>/ with index.md plus a screen MD per page.
3. Run python backend/scripts/generate_catalogs.py.
4. Run python backend/scripts/check_docs_coverage.py to verify.

Bumping last_verified_commit

• When: every time you change anything described by the doc, or when the doc still reads correctly after a related code change you didn't author but you happened to verify.
• What: the short SHA of the current commit your PR is based on. git rev-parse --short HEAD after the change is staged.
• Don't automate it. Bumping the SHA is an affirmation that you read the doc and it still applies. Automation defeats the point.

Verifying locally

# Build the portal — confirms the new MDs render and the sidebar picks them up.
cd docs/portal && npm install && npm run build

# Preview at http://localhost:5173
npm run preview

If the stale badge appears on a page you've just edited, check that you bumped last_verified_commit in the frontmatter.

When the coverage check complains

The coverage check (warning-only first; blocking after backfill) tells you exactly which artifact is missing. The most common cases:

• "<module> ships a route /foo without a screen MD." — Create the two locale screen files.
• "Endpoint GET /api/v1/foo is not listed in any docs/technical/<m>/permissions.md." — Add the row.
• "Permission module.read is unused." — You removed an endpoint but not the permission row.

Don't silence warnings. Either fix the doc or document why the warning is wrong (the script accepts inline # ignore: <reason> comments at the head of the related MD).