Versioning and keeping docs in sync with the build

Last updated: 2026–05-26

This page describes how we version documentation and keep it aligned with product changes (including full feature rehauls and moving features around).

---

Versioning

• Per page: Use VitePress frontmatter — see _templates/page-frontmatter.md. Required fields: featureArea, audience, roles, lastVerified, externalVisibility.
• Doc-wide: Record changes in CHANGELOG.md with date, section, and a short description.
• Optional: Maintain a VERSION file in docs/ when publishing a labeled docs release.

For multiple product versions, use a branch per release or versioned folders (docs/v1/, docs/v2/) and point the site at the right branch.

---

Keeping docs in sync with the build

1. Structure mirrors the app

• Each doc section maps to Django URL mounts (repo/lendapi/urls.py), per-app APIs under repo/<app>/urls.py, and v2 UI in lend-frontend-repo (routes.ts, LendAPIApp.tsx, src/features/).
• The documentation map and _meta.md list these mappings. When you rehaul or move a feature:
  • Update code (routes, UI, nav).
  • Update the corresponding doc section (rename docs/<section>/ if needed).
  • Update the map and _meta.md in the same PR.

2. Single source of truth

• _meta.md is the authoritative doc ↔ product map for automation.
• docs-automation/docs-intel/feature-inventory.json is generated from code + _meta.md (node docs-automation/check-docs-sync.js --write-inventory).
• docs-automation/check-docs-sync.js reports:
  • Errors: missing doc folders listed in _meta.md, or orphan docs/<folder>/ not in the map.
  • Warnings: backend mounts or frontend feature folders with no mapped doc section (optional areas are listed explicitly in _meta.md).

3. Process

• PR rule: User-facing feature changes should update the relevant docs/ section and _meta.md when routes or nav change.
• Release/sprint: Run a doc pass for features shipped that sprint; bump lastVerified on touched pages.

4. Drift check (CI / local)

# From monorepo root
node docs-automation/check-docs-sync.js

# Machine-readable report
node docs-automation/check-docs-sync.js --json

# Regenerate inventory after map changes
node docs-automation/check-docs-sync.js --write-inventory

What the check does not do yet (Milestone 2+): compare prose on each page to live UI, or open PRs automatically. It validates folder structure and code ↔ map alignment only.

5. Release snapshot (foundation)

Before a doc sprint or AI-assisted update pass:

node docs-automation/docs-intel/collect-snapshot.js

This writes docs-automation/docs-intel/snapshot.json with recent git activity in lend-frontend-repo and repo, plus an excerpt of docs-claude/product-context/active-state.md. Use DOCS_INTEL_SINCE_TAG=<tag> to scope commits since a release tag.

---

Related tooling

Monorepo automation (not published in this site):

• docs-automation/README.md — automation tooling index
• docs-automation/docs-intel/README.md — docs intelligence pipeline