Repository architecture

Document areas

Location	Purpose
Governance	Controlled planning documents: business plan (zh and en), product plan, market and commercial models, compliance matrix, assumptions register, open questions, internal PPT guide
Product packages	One package per product with fixed slots (spec, design, guide, brief, evaluations); shared/ holds the CAN protocol and configuration schema; diagrams/ holds the SVG matrix and its JSON source
Research	market/, industry/, engineering/ topic directories of reports, proposals, and reviews; vendors/{pdm,gateway,switch,keypad}/ supplier catalogues; data/ and sources/ evidence archives
Project records	PMA task and plan records, decisions, changelog, this page, the documentation standard, and page templates
refs/	Third-party manuals kept in the repository and excluded from the website

bizplan/ is Chinese except business-plan.en.md; project records under docs/ are English. The documentation standard defines document kinds, frontmatter, filenames, product package slots, index rules, and the quality gate; every page under bizplan/ carries frontmatter and every page-bearing directory has an index.md.

Navigation and document authority

Readers enter through the home page and directory index.md pages. Each package index.md is the only inventory of that package; research topic indexes classify pages as current, evidence, or historical; vendor category indexes list suppliers with domain columns because every page in them is a catalogue record.

The product plan governs product tiers, prices, milestones, and unresolved engineering decisions. A product spec is the only requirement source for its package; design documents must not change Level 1 values; guides restate requirements for suppliers; briefs restate capability for buyers; evaluations are never cited as requirements. Research proposals do not revise controlled specifications until adopted through the project workflow, and a superseded page names its successor in frontmatter and in its first paragraph.

Use relative Markdown links resolved from the containing file. A renamed or moved page gets a line in .vitepress/public/_redirects. Retired task and plan IDs link to their changelog entries.

Site and publication

VitePress renders Markdown in place with clean URLs, such as /bizplan/product/core/P01-core. There are no locale route rewrites. The sidebar is the explorer: one collapsible tree of every published page, generated from the file system by .vitepress/site-tree.ts (folder labels from each index.md title, page labels from frontmatter title, order following each directory's index tables); the same tree produces the breadcrumb labels and the sitemap page, which is rewritten on every build and must not be edited by hand. The English business plan is served at /bizplan/governance/business-plan.en.

• .vitepress/config.mts defines navigation, Chinese local search, the generated sidebar and breadcrumb map, the table scroll wrapper, the public directory for _redirects, and asset copying.
• .vitepress/theme/index.ts mounts Breadcrumb.vue and DocMeta.vue above page content; DocMeta renders the standard frontmatter (kind, status, version, updated, lifecycle, superseded banner). custom.css gives tables a scroll container and a minimum column width, sets the 320 px tree and the 1100 px content column, and compacts the tree rows.
• scripts/lint-docs.mjs enforces the standard; bun run docs:lint runs it.
• bun run docs:dev serves the site locally; bun run docs:build writes .vitepress/dist/.
• Non-Markdown files under bizplan/ are copied at their source paths, except individual files larger than 25 MiB. The Bertram 43 and Bertram 700 original manuals remain repository-only archives; the source catalog identifies their publisher downloads.
• refs/, tmp/, docs/templates/, and the root instruction files are excluded from rendered pages.
• .github/workflows/deploy.yml lints, builds, and deploys Cloudflare Workers static assets only when manually dispatched; wrangler.jsonc identifies the output directory and 404 behavior. Workers static assets honour the _redirects file copied from .vitepress/public/.

Verification

Run bun run docs:lint && bun run docs:build && git diff --check. Also check rendered internal links, fragment IDs, and downloadable assets: a successful build alone does not validate every fragment or ensure oversized source assets were published. Keep task/plan index markers consistent with their detail records.