Documentation system¶
How the mcc-systems knowledge base is organised, where to put new documentation, and how to update the documentation site.
Directory structure¶
All documentation lives in the docs/ directory of the repo, organised into four subdirectories. The deciding factor for where something goes is audience and purpose.
docs/live/ — Feature documentation (regression defence)¶
Feature documentation for built and deployed features. These are the primary regression defence — they describe intended behaviour, design decisions, and known edge cases for key functional areas. Claude Code is required to read the relevant doc before modifying any files in that area. Any change that breaks the behaviour documented here is treated as a regression.
Each doc in docs/live/ has a corresponding entry in CLAUDE.md so Claude Code knows when to read it.
Current docs cover: BMS architecture, pricing model, service hierarchy and quoting, proposal/contract lifecycle, proposal send and unlock flow, organisation details data flow, contract clause variables, portal architecture, legacy tender responses, portal external integrations, portal legacy pages, and deployment safety nets.
docs/admin/ — Governance and conventions¶
Development governance docs, conventions, automated check configuration, and reports. These describe how the codebase is managed rather than what the features do. Referenced by CLAUDE.md, automated checks, and developers working in the repo.
Subdirectory docs/admin/audit/ holds the audit artefacts that support the automated checks:
file-size-limits.json— default limit, per-file overrides with reasons, and skip listbundle-baselines.json— bundle size baselines for the 20% growth thresholdaccepted-exceptions.md— explanatory context for patterns that are intentionally accepted (e.g.staleTime: 0is intentional, legacy tender files are frozen). Read by the weekly AI review so it doesn't flag accepted patterns as issueshealth-reports/— directory where daily and weekly health check reports are saved automaticallydoco-reports/— directory where weekly documentation review reports and the baseline registry are saved automatically
Weekly documentation review¶
A separate automated scan runs every Sunday at 4am AEST / 5am AEDT (via .github/workflows/doco-review.yml) to check documentation accuracy. It reads each reference doc alongside the source files it references and flags contradictions, stale paths, and missing coverage. Findings are classified as new, previously reported, or fixed, and a GitHub Issue is created if new issues are found.
Documentation coverage (ensuring new features have reference docs) is enforced via the development workflow, not by the scanner.
The scan maintains a baseline of open issues in doco-reports/baseline.json. Weekly runs are incremental (only checking docs affected by the last 7 days of changes); full scans can be triggered manually to re-check everything.
Full detail: docs/admin/automated-doco-review.md
docs/user/ — Human-readable documentation¶
Documentation aimed at a broader audience — Jordan, Gian, future staff — who may not work in the repo day-to-day. Includes high-level overviews, onboarding guides, system explanations, and business context documents. This directory is the source for the documentation site at docs.matthewscleaningco.com.au.
docs/plans/ — Project plans¶
Living project plans for larger bodies of work that span multiple sessions or threads. Unlike specs (which describe what to build), plans describe what work remains and in what order. Updated as work progresses, with completed items checked off and new findings added.
Thread continuation documents serve a similar purpose for individual conversation threads; plans cover work that may span many threads over days or weeks.
Where to put new documentation¶
docs/live/ — When it describes intended behaviour and design decisions that Claude Code needs to respect when editing code. Put it here if CC needs to read it before making a code change. Add a corresponding entry to CLAUDE.md.
docs/admin/ — When it describes how the codebase is managed: enforcement rules, conventions, automated checks, or development workflows.
docs/user/ — When it's aimed at a broader audience and doesn't need to be read by Claude Code. High-level overviews, onboarding material, system explanations. Add a nav entry to mkdocs.yml so it appears on the documentation site.
docs/plans/ — When the work will span multiple threads or days and you need a persistent record of what's done, what's next, and the approach.
When it's not obvious: ask whether Claude Code needs to read this doc before making a code change. If yes, it goes in docs/live/ or docs/admin/. If it's purely for human understanding, it goes in docs/user/.
Some topics exist in multiple places at different levels of detail — for example, migration conventions have a full technical reference in docs/admin/migration-schema-conventions.md and a summary in this site's governance overview. That's fine. The repo doc is the source of truth; the documentation site summary helps people get oriented without reading the full technical reference.
Front matter conventions¶
Pages in docs/user/ may include YAML front matter at the top of the file, enclosed by --- fences. Currently used properties:
owner— the person responsible for keeping the doc currentlast_updated— the date of the last substantive review
Do not add status: to front matter. The MkDocs Material theme renders a status icon in the nav whenever a page has a status property. Without a matching extra.status.<identifier> entry in mkdocs.yml, that icon renders silently (no tooltip) and offers no value. We've deliberately chosen not to maintain the extra.status config, so the convention is to omit status: entirely.
The nightly health check enforces this — any .md file in docs/user/ with a status: key in its front matter is flagged as a violation (pattern label FRONT_MATTER_STATUS).
This convention applies only to docs/user/ (the MkDocs scope). Files in docs/live/, docs/admin/, and docs/plans/ are not served by MkDocs, so front matter choices there have no rendering effect.
Docs index¶
Every reference doc in docs/live/, docs/admin/, and docs/user/ is indexed in docs/admin/docs-index.json. The index maps each doc to the functional areas and systems it covers, using a controlled vocabulary of tags defined in the index file's taxonomy block.
Why it matters: When a new feature lands, Claude Code uses the index to identify which existing docs may need updating — filtering by the feature's relevant areas and systems rather than reviewing every doc in the repo. The nightly health check validates the index mechanically, flagging new docs that haven't been indexed (INDEX_MISSING_ENTRY), stale paths (INDEX_STALE_PATH), and invalid tags (INDEX_UNKNOWN_TAG).
When you create a new doc: Add a corresponding entry to docs/admin/docs-index.json with appropriate areas and systems tags from the taxonomy. If the doc covers an area or system not in the taxonomy, flag it so the vocabulary can be extended.
How to update the documentation site¶
The documentation site is built with MkDocs (Material theme) and hosted on Cloudflare Pages. It serves content directly from docs/user/ in the repo — there is no separate publishing step beyond pushing to master.
To edit an existing page: Edit the markdown file in docs/user/ (either directly or via Claude Code), commit, and push to master. Cloudflare Pages will automatically rebuild and deploy the site within about a minute.
To add a new page: Create the markdown file in the appropriate subfolder under docs/user/. Then add a nav entry for it in mkdocs.yml at the repo root — the nav: section controls what appears in the sidebar and in what order. Commit and push.
To add a new section: Add a new top-level entry under nav: in mkdocs.yml, create the corresponding subfolder in docs/user/, and add your markdown files. Commit and push.
Site configuration: mkdocs.yml at the repo root controls the site name, theme settings, navigation structure, plugins, and markdown extensions. Custom CSS lives in docs/user/stylesheets/extra.css. Theme overrides live in docs/user/overrides/.
Access control: The site is protected by Cloudflare Access. Only @matthewscleaningco.com.au email addresses can log in via one-time code. To grant access to someone outside the domain, add their email in the Cloudflare Zero Trust dashboard under Access → Applications → MCC System Documentation.
Quick reference¶
| What | Location |
|---|---|
| Feature docs (regression defence) | docs/live/ |
| Governance docs | docs/admin/ |
| Audit config and reports | docs/admin/audit/ |
| User documentation | docs/user/ |
| Development plans | docs/plans/ |
| Documentation site content | docs/user/ |
| Documentation site config | mkdocs.yml (repo root) |
| Documentation site CSS | docs/user/stylesheets/extra.css |