Documentation upgrade status & roadmap

Purpose

See at a glance which pages were added, strengthened, or aligned with code.
Prioritize further work: generated DocType reference vs curated pages, automation, and diagrams.

Scope: docs/src/content/docs, the docs/ package (inventory CSV, doctype-overlays/README.md, etc.).

Scale (inventory baseline): about 272 Markdown/MDX files; roughly 212 under doctype-reference/ are generated DocType reference pages.

1. Upgraded and new documentation

1.1 New pages (handover & operations)

Path	Role
Architecture decisions (ADR)	ADR template and initial samples
Environment & integration matrix	Secret names, storage hints, audit questions
Handover completion checklist	Technical handover sign-off
Test evidence & CI	Test evidence, CI, `bench run-tests`
Documentation inventory (CSV)	Line-count inventory and regeneration
Operational runbook	Migrate, rollback, integration triage
Domain documentation strategy	Bulk DocType pages vs domain deep dives
Domain deep dive — Finance & AR	D1 narrative, code map, overlay P1/P2/P3 for finance-ar-integrations
Domain deep dive — Incorporation & application	D1 narrative for Application / website / PDFs; overlays for `orders`, `package_types`, `printouts_table`
Domain deep dive — Payroll & HR	D1 narrative for SG payroll scripts + settings; overlays for `payboy_settings`, `payslip_settings`, `cpf_contribution_rates`
Domain deep dive — Corporate AGM	D1 narrative for AGM cron/ACRA; overlays for `agm`, `status_of_agm`, `agm_cron_log`
Domain deep dive — Automation & communications	Auto-email, templates, DocuSign queue; overlays for `auto_email_configuration`, `email_templates_configuration`, `docusign_email_queue`
Domain deep dive — Time tracking	`time_tracking_module`; overlays for `time_tracker_settings`, `time_tracking_project`, `time_tracking_user`
Domain deep dive — Platform & admin	Portal/Singpass/AI; overlays for `singpass_token`, `userlka`, `openai_settings`
Domain deep dive — Accounting & compliance	Compliance progress and reports; overlays for `progress_of_accounting`, `auditing`, `acra_settings`
Domain deep dive — CRM & sales	Tickets and promos; overlays for `support_ticket`, `client_info`, `promotion_code`

1.2 Repository `docs/` (outside Starlight body)

Path	Content
`docs/docs-inventory.csv` / `docs/public/docs-inventory.csv`	Per-page line counts
`docs/doctype-overlays/README.md`	`overlays.json` schema and workflow
`docs/README.md`	Handover content edit and build workflow

1.3 Heavily expanded curated pages (examples)

Start & scope: Home, Start guide, Introduction — Overview, How to read, Glossary, Reference vs implementation, Handover deliverables.

Architecture: System context, System overview, Request flow.

Deploy & ops: Deployment & operations, Cloudflare Pages.

Security: Security checklist.

Integrations: Xero, Stripe, DocuSign, Singpass.

API: API inventory.

Reference: Platform primer, Documentation conventions, Diagram roadmap, Feature inventory by category.

Data & modules: Custom DocTypes, ER diagrams by domain, Module catalog, MOD mapping, Lee Kim Alliance subtree, payroll, time tracking, socket, incorporate, payroll-plus, tutorials, hooks, flows, features, reports, overrides, Known issues, Technology stack.

1.4 Code alignment (examples)

Document	Alignment
Doc events	`doc_events` paths, Salary Slip validation order, commented/disabled handlers
Stripe	`website_route_rules` path table

1.5 “Deep” curated pages (line-count signal)

Examples that grew substantial (non-generated): API inventory, Start guide, Stripe, Payroll, Xero, Operational runbook, Architecture overview, System context, Cloudflare Pages, Doc events.

2. Remaining work and direction

2.1 Generated DocType reference (`doctype-reference/**`, ~212 files)

Situation	Direction
Mostly field tables + short Overview + “Add narrative” placeholders	A 500-line target per file is unrealistic. Prioritize: (1) long-form English only for critical DocTypes (payments, incorporation, Xero, payroll); (2) `doctype-overlays/overlays.json` one-liners for role and hooks; (3) single deep-dive page per domain linking clusters (same as domain documentation strategy).
Category `index.md` files often ~17–32 lines	Add one page per domain folder: business purpose, diagram, key links.

2.2 Shorter curated pages (expansion candidates)

Pages in the ~24–71 line band often have room for scenarios, metrics, and evidence tables. Treat Test evidence, Documentation inventory, and Domain documentation strategy as organization-standard anchors — see tables on those pages.

Document (examples)	Direction
Feature inventory by category	Single table mirrors `astro.config.mjs` — add sidebar change checklist or plan auto-extraction (design only).
Payroll Plus, Incorporate, Auto Repeat override	Add 1–2 user scenarios (steps + validation points) and one line on where to look in logs when things fail.
Feature catalog	Update process and owning team column so the table stays operable.
Introduction — Overview	NFR template (SLO, RPO/RTO) table — template-only is enough to tie to commercial acceptance.

2.3 Visualization

Situation	Direction
Diagram roadmap lists recommended types	Finish Billing / Xero / Payroll sequences first; add one container-level diagram when extending System context.

2.4 Automation & quality gates (process, not only prose)

Item	Direction
API docs	API inventory is table-driven — long term, consider OpenAPI or generated inventory from code.
Inventory CSV	Decide whether PR checks verify CSV freshness (script).
`hooks.py` vs docs	Doc events and Schedulers are manual sync — add “refresh doc tables” to release checklist.

2.5 External-only / outside repo

Item	Direction
User/admin PDF manuals	Not duplicated here; a single mapping table (screen → DocType → code) helps developer handover.
ERD draw.io	Ship with formal package per Deliverables; keep Mermaid on site as summary.

3. Recommended execution order (planning)

Domain deep dive: All nine CATEGORY_META generator folders now have a matching data/domain-*.md page (see Domain documentation strategy). Next (optional): expand category index.md intros under doctype-reference/*/, Diagram roadmap sequences, or inventory CSV PR check per Documentation inventory.
Short curated pages: Test evidence → Feature inventory by category → Payroll Plus / Incorporate — tables and operability first.
212 DocType pages: grow overlay JSON keys gradually; long MD only for selected DocTypes.
Process: add hooks/API doc sync checks to release notes.