Documentation Maintenance

This document gathers the maintenance procedures for all parts of the documentation portal. Use as a reference when adding, modifying, or removing content.

---

Build Flow Overview

docs:openapi   →   docs:typedoc   →   vitepress build
   │                   │                   │
   │                   │                   └── final site
   │                   │                       at docs/.vitepress/dist/
   │                   │
   │                   └── docs/reference/typedoc/
   │                   └── docs/public/reference/typedoc/
   │
   └── docs/reference/api/openapi.json
   └── docs/public/reference/api/openapi.json

---

Phase 1 — VitePress Portal

How to add a new page to the portal

1. Create the .md file in the corresponding folder (e.g. docs/frontend/my-page.md)
2. Add YAML frontmatter (see pattern below)
3. Add the page to the ptSidebar array in docs/.vitepress/config.mts
4. Run pnpm docs:build — VitePress validates internal links

Standard frontmatter

Every markdown document in the portal must start with:

---
title: Page Name
description: One-line summary of the page's purpose.
status: published | draft
owner: engineering | product | design
lastReviewed: 2026-08-09
---

How to change navigation

• Top navbar: edit themeConfig.nav inside locales.root.themeConfig in config.mts
• Sidebar: edit the ptSidebar array in the same file
• Footer: edit themeConfig.footer within locales.root

Portal language

The portal ships pt-BR only (ADR-0046). There is no translation layer to maintain, and no freshness pins.

• docs/en/index.md is the single page in the en locale: a notice that English translations are in progress, linking back to the pt-BR portal.
• docs/public/_redirects maps every /en/... URL to that notice page on Cloudflare Pages. VitePress still renders a per-page language link into /en/ on every pt-BR page; those URLs have no built counterpart, which is why check-doc-links.sh excludes ^$BASE/en/.+ from its crawl.
• Do not add pages under docs/en/ unless the English translation effort is actually restarted — a half-translated locale is exactly what ADR-0046 removed.

Source Language Policy

• The docs in docs/ are the canonical pt-BR source, and pt-BR is the only shipped locale.
• Pending conversion (English-bodied roots): docs/index.md, docs/maintenance.md (this guide), docs/community/security-policy.md and docs/community/code-of-conduct.md are still English-bodied. docs/product/prd.md and docs/architecture/srs.md were translated to pt-BR in ADR-0046; the rest of this list is the remaining conversion backlog. These pages are not language-neutral — the exemption is time-boxed, and translating them is a content pass, not a policy change.
• docs/quality/testing-category.md is a permanent language-neutral exception (a taxonomy whose terms are identical in any language).

Commands

Command	Action
pnpm docs:dev	Development server (hot-reload)
pnpm docs:build	Full production build
pnpm docs:preview	Build preview
pnpm docs:lint	markdownlint on all docs
pnpm docs:links	lychee dead-link check on the built site
pnpm docs:staleness	lastReviewed staleness warning
pnpm docs:check	lint + build (what the CI docs job runs, plus lychee/staleness)

---

Phase 2 — Editorial Taxonomy

Folder structure

docs/
├── index.md                  ← Portal landing page
├── getting-started/          ← Onboarding for new contributors
│   ├── overview.md
│   ├── quickstart.md
│   ├── repository-structure.md
│   └── contributor-workflow.md
├── product/                  ← Business vision and product requirements
│   ├── index.md
│   ├── prd.md
│   ├── business-rules.md
│   ├── roles-and-permissions.md
│   ├── scope.md
│   └── success-criteria.md
├── architecture/             ← Architecture and design
│   ├── index.md
│   ├── srs.md
│   ├── sdd.md
│   ├── context-map.md
│   ├── domain-model.md
│   ├── sync-architecture.md
│   ├── auth-architecture.md
│   └── adr/                  ← Architectural decisions (individual files)
│       ├── index.md
│       ├── archive/           ← Consolidated ADRs (archived)
│       └── ...
├── frontend/                 ← Frontend SPA documentation
│   ├── index.md
│   ├── app-overview.md
│   ├── offline-mode.md
│   ├── import-export.md
│   ├── reports.md
│   └── ui-flows.md
├── workers/                  ← Backend documentation
│   ├── index.md
│   ├── workers-overview.md
│   ├── api-overview.md
│   ├── api-guide.md          ← Guide on how to add routes
│   ├── auth.md
│   ├── idempotency.md
│   ├── d1-schema.md
│   └── legacy-fastify.md
├── operations/               ← Operations and deployment
│   ├── index.md
│   ├── environments.md
│   ├── deployment.md
│   ├── migrations.md
│   ├── seed.md
│   ├── backup-restore.md
│   ├── security.md
│   ├── lgpd.md
│   └── troubleshooting.md
├── quality/                  ← Quality and testing
│   ├── index.md
│   ├── mtp.md
│   ├── rtm.md                ← Automatically generated (csv → md)
│   ├── production-readiness-gates.md
│   ├── hardening-backlog.md
│   ├── test-execution-handbook.md
│   └── testing-patterns.md
├── reference/                ← Technical reference
│   ├── index.md
│   ├── api/
│   │   ├── index.md
│   │   ├── api-contract.md
│   │   └── openapi.json      ← Automatically generated
│   ├── typedoc/              ← Automatically generated (gitignored)
│   ├── schemas.md
│   ├── permissions.md
│   ├── data-dictionary.md
│   └── extending-student-fields.md
├── community/                ← Community documents
│   ├── index.md
│   ├── contributing.md
│   ├── security-policy.md
│   ├── code-of-conduct.md
│   └── changelog.md
├── agents/                   ← Internal Reasonix workflow docs (outside portal)
├── archive/                  ← Preserved obsolete documents
└── RTM.csv                   ← Source for rtm.md generation

Rules

1. Each section must have an index.md with overview and link list
2. Links between documents use relative markdown paths (../product/prd.md)
3. The VitePress sidebar is the source of truth for navigation — keep it in sync
4. docs/agents/ contains internal Reasonix workflow documentation — do not link in the portal
5. docs/archive/ contains obsolete documents preserved for historical reference

How to move or rename a document

1. Move/rename the file
2. Update the sidebar in docs/.vitepress/config.mts (the ptSidebar array)
3. Update internal links in other documents that pointed to the old path
4. Update REDIRECT.md or third-party links (README.md, CONTEXT-MAP.md, AGENTS.md, REASONIX.md)
5. Run pnpm docs:build to check for dead links

---

Phase 3 — OpenAPI / Live API

See the full guide in API Guide.

Summary flow

1. Add the handler in workers/src/routes/
2. Import and register in workers/src/router.ts (via route() helper with declarative middlewares)
3. Add entry in scripts/openapi-registry.ts (with Zod schema, example, auth)
4. Run pnpm docs:openapi to validate coverage and generate openapi.json

Automatic validation

The scripts/generate-openapi.ts script verifies that every route in router.ts has a corresponding entry in the registry. If missing, the build fails with:

Route POST /api/v1/customers is NOT documented in openapi-registry.ts

Files

File	Purpose	Editable?
scripts/openapi-registry.ts	Registry with schemas, examples, and metadata for each route	✅ Yes
scripts/generate-openapi.ts	OpenAPI 3.1 generator	Rarely
docs/reference/api/openapi.json	Generated spec (source)	❌ Generated
docs/public/reference/api/openapi.json	Spec for VitePress build	❌ Generated

---

Phase 4 — TypeDoc

How to add a new entry point

1. Edit typedoc.json, add the file path to entryPoints
2. Edit typedoc.tsconfig.json, add to include
3. Run pnpm docs:typedoc to generate
4. If you want a sidebar link, add it in docs/.vitepress/config.mts under Reference > TypeDoc (sub-item)

Common error resolution

Error	Cause	Solution
TS2322: Uint8Array not assignable to BufferSource	Workers-specific runtime type	Exclude the file from entry points
TS2339: timingSafeEqual does not exist	Workers API not available in standard TypeScript	Exclude the file from entry points
Module has no exported member	Path alias not resolved	Add to paths in typedoc.tsconfig.json

Files

File	Purpose	Editable?
typedoc.json	TypeDoc config (entry points, output)	✅ Yes
typedoc.tsconfig.json	TSConfig for TypeDoc to resolve workspace packages	Rarely
scripts/generate-typedoc.sh	Script that generates + copies to docs/public/	Rarely
docs/reference/typedoc/	Generated HTML	❌ Generated (gitignored)
docs/public/reference/typedoc/	Copy for VitePress build	❌ Generated (gitignored)

Current entry points

Entry Point	Content
packages/permissions/index.ts	PERMISSIONS, UserRole, Permission
packages/schemas/src/index.ts	All Zod schemas + enums + utils (HttpError, sanitizePayload)
workers/src/modules/auth/sessionTokens.ts	signAccessToken, verifyAccessToken, createRefreshToken, hashRefreshToken
workers/src/modules/idempotency.ts	payloadHash
workers/src/schemas.ts	HTTP API schemas (auth, student, attendance, sync)

---

Phase 5 — RTM (Requirement Traceability Matrix)

The automatic RTM generation pipeline was removed in #640 (ADR-0037). docs/RTM.csv remains as the manual traceability source (referenced by the MTP and the test execution handbook); the generated pages docs/quality/rtm.md + rtm-from-code.json were removed.

How to update requirements

1. Edit docs/RTM.csv (spreadsheet with 6 columns: RequirementID, Category, RequirementSummary, PrimarySuite, TestCaseRefs, CoverageStatus)
2. Run pnpm docs:build to verify

CSV fields

Column	Example	Required
RequirementID	FR-001	Yes
Category	Functional	Yes
RequirementSummary	Support all defined roles	Yes
PrimarySuite	RBAC	Yes
TestCaseRefs	TC-RBAC-001;TC-RBAC-002	Yes (separated by ;)
CoverageStatus	Planned, Implemented, Passed, Failed	Yes

New requirements

• IDs follow the format <PREFIX>-<NUMBER>: FR-, NFR-, DR-, SR-, SCR-
• Insert at the end of the corresponding section or reorder freely (order in the CSV is preserved)
• When changing TestCaseRefs, use ; as separator — no spaces
• For coverage status, use Planned (not tested), Implemented (code exists), Passed (tests pass), Failed (tests break)

Files

File	Purpose	Editable?
docs/RTM.csv	Data source	✅ Yes (manual editing or spreadsheet)

---

Script Summary

Script	Phase	Generates	Validates	Frequency
—	1	—	docs:build validates dead links	Always on build
scripts/generate-openapi.ts + openapi-registry.ts	2	openapi.json	✅ Coverage against router.ts	New route
scripts/generate-typedoc.sh	3	docs/reference/typedoc/	—	New entry point

---

Checklist for New Content

• .md file created in the correct folder
• YAML frontmatter present (title, description, status, owner, lastReviewed)
• Sidebar updated in docs/.vitepress/config.mts (the ptSidebar array)
• If it's a new route: handler → router.ts (via route() helper with declarative middlewares) → openapi-registry.ts
• If it's a new requirement: update docs/RTM.csv (manual traceability; the RTM generator was removed in #640)
• If it's a new TypeDoc entry point: typedoc.json + typedoc.tsconfig.json
• pnpm docs:build passes without errors