HQ — the mesh's own documentation

What the mesh is, what it is becoming, and why. Implementation lives in the
code repositories; the reasoning lives here.

  00-GENESIS   mission, engineering context, effect, and the rules that hold
  01-RESEARCH  investigations, before they harden into design
  02-DESIGN    the authoritative specification
  adr          numbered decisions — what was chosen, and what was rejected
  DECISIONS.md the ledger: every decision, in the order it was taken

Written for a reader who is not its author and has no access to the mesh it
describes. Addresses use the documentation ranges of RFC 5737 and RFC 1918;
nodes are named by role.

Single initial commit by intent. The prior history came from a private
repository and carried operational detail — a routable address identified as a
VPN hub, real domain names, a hosting provider — which sanitising a tip commit
would not have removed from the log.

00-GENESIS/how-we-build.md

@@ -0,0 +1,42 @@
+# How we build
+
+Working notes on the rules that hold across the mesh. Short, and each one earned.
+
+## Name a context after its aggregate, not after a metaphor
+
+`hal/agents` owns **Agent**. A *brain* — memory, thoughts, cognition — is something an
+agent **has**, a concept inside the aggregate. It is not a module.
+
+The cost of getting this wrong is visible today: `hal/brain` names the node runtime, so
+the most evocative word in the system points at infrastructure, and `hal/cortex`
+describes itself as "mesh messaging" in its manifest while the anatomy documentation
+calls it the interactive runtime — and it runs on no node at all.
+
+Anatomy makes attractive names and poor boundaries. Name the thing the domain calls it.
+
+## Ubiquitous language is checked, not assumed
+
+If a document states a rule about the mesh, say how the rule is verified. This repository
+has a documented requirement that every module exposing tools declares `brain` as a
+dependency. Zero modules do. An unenforced rule is indistinguishable from a wrong one,
+and costs more, because people believe it.
+
+## Contexts integrate through the record, never through a shared schema
+
+Publish to the stream; do not join across a boundary. Today five domains share one
+45-table schema, which is why work that belongs to one context keeps having to be
+implemented in another.
+
+## A failed step must stop the steps after it
+
+Scripted work runs as a sequence, and a sequence that continues past a failure does the
+next thing in the wrong place. Gate each step on the last: `cd X || exit`, not `cd X`
+followed by a newline.
+
+Earned the obvious way. A `git worktree add` failed because the branch name collided with
+an existing namespace; the `cd` into that worktree failed too; and the `cp`, `git add` and
+`git commit` that followed ran in the shared checkout and committed to local `main`. The
+error was printed and scrolled past.
+
+This is the same shape as the faults this refactor exists to remove — a step reported
+failure, nothing stopped, and the damage happened somewhere nobody was looking.