0.3 documentation

0.3. Documentation & Badges

Wiki conventions

The project documentation lives in the repository, under .wiki/, and is published as the GitHub wiki. Conventions:

• Numbered files: 0-topic.md for foundations, N.M-topic.md for subpages of section N.
• index.md holds the table of contents and a navigation matrix — update it whenever a page is added, renamed, or removed.
• One concern per page; keep pages verifiable against the current code (commands, file paths, endpoints must be real).
• Cross-link sibling pages with relative paths (1.1-rest.md), README with .wiki/0-introduction.md-style paths.
• Screenshots and large assets live at the repo root or in docs/assets/ — never inside .wiki/.

Prefix	Section
0-*	Orientation: introduction, quick start, docker, documentation
1-*	Server (NestJS): overview + subsystem pages
2-*	Dashboard (Vue 3): overview + subsystem pages
3-*	Methodology and positioning essays

Badges with depbadge

Dependency and status badges in the per-app READMEs are generated, not handwritten. We use @ehildt/depbadge — the same tool this project's style of README was designed around.

How it works

1. Each package root contains a depbadgerc.yml (server/depbadgerc.yml, dashboard/depbadgerc.yml) declaring:

   • manifest: package.json — the dependency source (dependencies / devDependencies / peerDependencies);
   • target: README.md — the file receiving the badges;
   • output: [markdown] — also renders previews under .depbadge/ (git-ignored scratch space);
   • dependencies, devDependencies, statusBadges sections with layout/style (YAML anchors) and the curated items list.

2. Only packages explicitly listed in depbadgerc.yml get a badge; versions are read live from the manifest. Unlisted manifest entries are ignored — this is curation, keep it intentional.

3. Badges render via shields.io, styled with the project palette (labelColor: 333, logo width 40).

4. The generated block is injected into server/README.md / dashboard/README.md between markers:

   <!-- DEPBADGE:START -->
   <!-- DEPBADGE:END -->

   Never edit between these markers by hand — the integrity: checksum at the top of depbadgerc.yml makes the generation deterministic and lets the tool detect drift.

Running it locally

Run it from the package root, where its depbadgerc.yml lives:

cd server    && npx @ehildt/depbadge
cd dashboard && npx @ehildt/depbadge

Debug what would render without touching the README:

npx @ehildt/depbadge -g markdown   # previews into .depbadge/
npx @ehildt/depbadge -g json       # resolved badge definitions

Running it in CI (already wired)

release.ci.yml regenerates badges on main after changesets version bumps:

- name: Depbadge — Server
  run:  cd server && npx @ehildt/depbadge
- name: Depbadge — Dashboard
  run:  cd dashboard && npx @ehildt/depbadge
- name: Commit badge bump
  uses: stefanzweifel/git-auto-commit-action@v7   # "BADGE BUMP"

Depbadge also ships as a GitHub Action (uses: ehildt/depbadge@v1) should we ever move to a dedicated workflow.

When you add or drop a dependency badge

1. Add/remove the items: entry (name must match the manifest key; provide the project link).
2. Re-run depbadge in that package.
3. Commit README.md + depbadgerc.yml together — the integrity checksum travels with the config.

The root README.md status badges (release, stars, license, codecov) are not generated — root has no depbadgerc.yml. Edit those by hand.