# HAL — HQ

The single source of truth for what the HAL mesh **is**, what it is **becoming**, and
why. Implementation lives in `modules/`; the reasoning behind it lives here.

## Structure

| Folder | Purpose |
|--------|---------|
| [`00-GENESIS`](00-GENESIS/) | Mission and foundational context. The northern star for every decision. |
| [`01-RESEARCH`](01-RESEARCH/) | Active and historical investigations, before they harden into design. |
| [`02-DESIGN`](02-DESIGN/) | The authoritative specification. Implementation is built against this. |
| [`adr`](adr/) | Numbered architecture decisions — what was chosen, and what was rejected. |

## Rules

- Markdown only.
- No new top-level folders without explicit confirmation.
- Knowledge flows `GENESIS → RESEARCH → DESIGN`. Research graduates into design only
  after analysis against GENESIS confirms alignment.
- **GENESIS and DESIGN are instance-agnostic.** They describe the mesh as a concept — no
  machine names, no counts, no topology. A reader must not be able to tell how many nodes
  the author happened to have.
- **RESEARCH describes real observations, but never identifies the mesh it observed.**
  Evidence is what makes research worth reading, and the shape of a finding survives
  anonymisation intact — *a node publicly named but behind a household NAT* carries the whole
  lesson without naming anything.
- A document that states a rule about the mesh should say how that rule is **checked**.
  This repo has a rule requiring every tools module to declare `brain` as a dependency;
  zero modules do. An unenforced rule is indistinguishable from a wrong one.

### This repository is public

Written for a reader who is not its author and has no access to the mesh it describes.
Concretely, nothing here may contain:

- **routable addresses, real domain names, hosting providers, or node names** — use the
  documentation ranges (RFC 5737 `203.0.113.0/24`, RFC 1918) and role names such as `anchor`,
  `home-server`, `workstation`, `laptop`
- **absolute paths** from anyone's machine, usernames, home directories, or email addresses
- **credentials in any form**, including lengths or hashes of live secrets
- **operational detail that is only useful to an attacker** — which host is the VPN hub, on
  which port, which node is reachable only through a forwarded port

Private-range addresses and the overlay plan are fine: they describe a pattern, not a target.

The test is whether a paragraph would still teach something to a stranger running an entirely
different mesh. If it would, it belongs. If it only makes sense to someone who knows this
particular installation, it is either a note in the wrong place or a disclosure.

## Why this is its own repository

It began inside the code repository, on the reasoning that HAL already has a mesh-native
knowledge store and that adding a fourth knowledge system would repeat the mistake this
folder was created to fix.

**That objection was about a fourth knowledge *system*, and it is answered by indexing, not
by location.** These documents are still indexed into the knowledge base, so
`recall_search` returns them beside everything else. One source, many surfaces — which was
always the actual requirement. Where the source is authored is a separate question.

Answered separately, a repository of its own is the better home:

- **The cadence is different.** A decision changes when thinking changes, not when code
  changes. Tying documents to a code branch means they merge on the code's schedule.
- **The reviewers are different.** A design argument is not reviewed the way an
  implementation is, and it should not queue behind a build.
- **The scope is wider than one repository.** ADR 0001 sends most modules out of the
  monorepo entirely. Documentation that governs several repositories cannot live inside one
  of them.

The trade is real and worth naming: a change to a document and the change to the code it
describes can no longer land in one commit. Keeping them honest is a discipline now rather
than a mechanism — which is why [`DECISIONS.md`](DECISIONS.md) records decisions as they are
taken, and why a document that states a rule should say how the rule is checked.

Recorded as decision 27 in [`DECISIONS.md`](DECISIONS.md).