# 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`](https://github.com/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:

   ```markdown
   <!-- 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:

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

Debug what would render without touching the README:

```bash
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.