Docs Update

docs/CONTRIBUTING-DOCS.md

@@ -0,0 +1,83 @@
+# Contributing to Bare OS documentation
+
+This repository ships documentation as **GitHub-flavored Markdown** (no static site generator in-tree). Changes are validated by **`npm run pretest`** (link checks, terminology rules, compatibility-matrix strings, roadmap row counts, and more). Read [scripts/README.md](../scripts/README.md) for the full verifier list.
+
+---
+
+## Where content lives
+
+| Audience | Tree | Role |
+| --- | --- | --- |
+| Operators / first run | [users-manual/](../users-manual/README.md) | Step-by-step: install, seeder/booter, shell, identity, troubleshooting |
+| Narrative / architecture | [handbook/](../handbook/README.md) | Why the system is shaped this way; trust, protocol, runtime |
+| Extenders / contributors | [developer-guide/](../developer-guide/README.md) | `ctx`, `/bin`, Pear, testing, security |
+| Specs / matrices / schemas | [docs/reference/](reference/README.md), [docs/architecture/](architecture/KERNEL_CONTRACT.md), [docs/schemas/](schemas/), [docs/adr/](adr/README.md) | Canonical numbers, env vars, wire formats |
+
+**Canonical glossary:** [docs/glossary.md](glossary.md). Do not duplicate long definitions in the user manual README; link here instead.
+
+---
+
+## Admonitions (callouts)
+
+Use a consistent blockquote pattern so callouts render clearly on GitHub:
+
+```markdown
+> **Note**  
+> Supplementary context that helps interpretation.
+
+> **Tip**  
+> A shortcut or workflow that saves time.
+
+> **Warning**  
+> Risk of data loss, security issue, or broken replication if ignored.
+
+> **Important**  
+> Non-obvious requirement or contract readers must not miss.
+```
+
+Keep the **bold label** on the first line, then a line break, then the body.
+
+---
+
+## Mermaid diagrams
+
+- Use **camelCase or underscores** for node IDs. Avoid spaces inside IDs (Mermaid parsing).
+- Avoid reserved words as node IDs (`end`, `graph`, `subgraph` as the sole id).
+- For subgraphs use explicit ids: `subgraph id [Human-readable label]`.
+- Prefer `flowchart TB/LR` and `sequenceDiagram` for boot and replication flows.
+- When edge labels need parentheses or special characters, wrap the label in quotes: `A -->|"O(1) lookup"| B`.
+
+If a diagram would need pixel-perfect branding or screenshots, add a **placeholder image** under [docs/images/](images/README.md) and reference it from the relevant page.
+
+---
+
+## Links and paths
+
+- Use **relative** `.md` links between docs so [scripts/verify-doc-links.mjs](../scripts/verify-doc-links.mjs) can resolve targets.
+- The link checker walks `docs/`, `handbook/`, `developer-guide/`, `users-manual/`, `scripts/`, `packages/`, `kernel/`, plus root `README.md`, `DOCUMENTATION.md`, and `PEAR-RUN.md`.
+- **`packages/bare-os-seeder/kernel/**`** is skipped (mirror of `kernel/`); fix links in **`kernel/**`** only.
+
+---
+
+## Terminology governance
+
+[scripts/verify-banned-terminology.mjs](../scripts/verify-banned-terminology.mjs) rejects certain **rollout metaphor** wording (for example “wave N”, “tranche”, “mega-phase”). Prefer **capability words**, **boot stages**, and **kernel program batches** as described in [developer-guide/kernel-program.md](../developer-guide/kernel-program.md).
+
+If you must quote a banned substring for wire-compat or third-party context, add a **justified** line to [docs/data/terminology-line-allowlist.txt](data/terminology-line-allowlist.txt) (see comments in that file).
+
+---
+
+## Single source of truth
+
+- **Version fields, offsets, feature bits, matrix tables:** update the **reference** page or JSON first; narrative chapters should link to it.
+- **`bareOsCtxApiVersion`:** history in [packages/bare-os-booter/CHANGELOG.md](../packages/bare-os-booter/CHANGELOG.md); summary row in [docs/reference/compatibility-matrix.md](reference/compatibility-matrix.md).
+
+---
+
+## Before you open a PR
+
+```bash
+npm run pretest
+```
+
+Fix any reported broken links or verifier failures. For doc-only edits, `pretest` is usually sufficient; full `npm test` matches CI more closely.