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/README.md

@@ -0,0 +1,28 @@
+# 00-GENESIS
+
+The **northern star**. What HAL is, the environment it runs in, and what changes when it
+works. Every research effort and design decision is checked against this folder.
+
+| File | Purpose |
+|------|---------|
+| [`mission.md`](mission.md) | Vision, mission, and the values that decide arguments |
+| [`context.md`](context.md) | The environment — conditions, not aspirations |
+| [`effect.md`](effect.md) | What is different when the work is done |
+| [`how-we-build.md`](how-we-build.md) | Rules that hold across the mesh, each one earned |
+
+## Rules
+
+- Markdown only.
+- **Stable by nature.** Changes here reflect a genuine shift in intent, not iteration.
+- Research and design must be traceable back to what is written here.
+
+## Note on `VISION.md`
+
+The repository root carries `VISION.md`, an architecture overview predating this folder.
+It is a useful description of *how* the mesh works and should be folded into
+[`02-DESIGN`](../02-DESIGN/), not here — GENESIS answers *why*.
+
+It has also drifted: it lists "Symlinks, not copies" as a key design principle, while the
+operating rules forbid creating symlinks at all after one caused production data loss.
+A founding document contradicting a hard rule is precisely the failure this folder exists
+to prevent.

00-GENESIS/context.md

@@ -0,0 +1,39 @@
+# Engineering Context
+
+The conditions the mesh is built for. Properties, not an inventory — no node here is
+named, and nothing should be designed around a particular one existing.
+
+## Mandatory
+
+- **Nodes are heterogeneous.** Desktops, laptops and servers, with different hardware,
+  different operating systems and wildly different uptime. A design that assumes uniform
+  nodes does not survive contact.
+- **Some nodes are mobile and frequently absent.** They sleep, change networks and lose
+  addressability. A node being unreachable is ordinary operation, never an incident.
+- **At least one node must be stably addressable.** Central components — transport,
+  registry, artifact storage — can only live where they can always be reached. That is a
+  property some node must have, not an identity a particular node holds.
+- **Human agents are few — often one — and usually asleep.** There is no team, no rota, no
+  second reviewer. Anything requiring a human to notice it will be noticed late.
+- **Nodes are personal.** A human agent works on the same node the mesh runs on. The mesh
+  is a guest there and must not make a node worse to use.
+
+## Default
+
+- **Self-hosted throughout.** Transport, state, artifacts and memory run on nodes the mesh
+  owns, not a managed service.
+- **A hosted model provider** supplies the thinking for non-human agents, drawn from a
+  shared pool of subscriptions — which is why budget pacing is a first-class concern.
+- **Long-lived user services** rather than an orchestrator. No cluster scheduler, no cloud
+  control plane.
+
+Defaults, not mandates. A second model provider is anticipated by design; nothing in the
+domain may assume one vendor's credential lifecycle.
+
+## Deviations
+
+- **No enterprise identity.** No directory, no SSO. Identity is mesh-internal.
+- **Public exposure is minimal.** Only nodes that must terminate public traffic do so.
+- **Agents share a pool of provider subscriptions** rather than holding billing
+  relationships of their own. A consequence of personal-scale infrastructure, and the
+  reason spend must be paced rather than merely billed.

00-GENESIS/effect.md

@@ -0,0 +1,43 @@
+# Effect
+
+Imagine the mesh works as intended. What is different?
+
+## You ask, and it happens
+
+An agent says what it wants — from a terminal, a phone, a message — and the mesh takes it
+from there. It works out which nodes are involved, does the work, and returns a
+result. Nobody opens a console, recalls which node holds what, or follows a runbook
+written months ago.
+
+The interface is intent. The mesh handles the rest.
+
+## The nodes look after themselves
+
+Updates land, services recover, disks are kept clear, certificates renew, and the mesh
+notices when something is wrong before you do. Maintenance stops being a thing you
+schedule and becomes a thing that has already happened.
+
+When something genuinely needs a decision, you are asked — with the context, not a log
+line.
+
+## Work continues while nobody is watching
+
+Agents keep working overnight and across the week. What they did is legible afterwards
+because it is all in one record: what was asked, what was decided, what changed. The
+overnight work can be trusted, which is what makes it worth doing at all.
+
+## The mesh remembers
+
+Nothing has to be explained twice. What was learned — how a thing works, why a decision
+went the way it did, what broke last time — is available to whoever needs it next,
+whether that is an agent working at 4am or a human agent six months later.
+
+## A human agent's environment is part of it
+
+The node a human agent sits at is not outside the mesh looking in. The desktop, the
+notifications, the shell are how that agent acts — maintained by the mesh, exactly as a
+spawned session is for an agent that is not human.
+
+## The difference for a human agent
+
+Less time spent operating the mesh. More time spent deciding what it should do.

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.

00-GENESIS/mission.md

@@ -0,0 +1,67 @@
+# Mission
+
+## Vision
+
+**A mesh that controls itself.**
+
+An agent states an intent — in words, from wherever they already are — and the mesh
+carries it out. It takes the request in, works out what it means, does the work across
+whichever nodes it needs, and returns a result. No console to open, no runbook to follow,
+no remembering which node holds which thing.
+
+Not automation, which does what it was told to do in advance. Self-control: the mesh
+holds the context, decides how, and acts.
+
+## Mission
+
+Build the layer that turns a set of nodes into one self-controlling mesh.
+
+- **Intake, process, deliver.** A request arrives, is understood, becomes work, and
+  returns an answer. That loop is the product; everything else exists to make it possible.
+- **Agents inhabit the mesh.** They are not scripts that run and exit. They hold identity,
+  memory and skills, run on whichever node has room, and act continuously.
+- **The mesh brokers everything the work needs.** Storage, credentials, compute,
+  knowledge, delivery — requested by capability, resolved by the mesh, never by the
+  requester knowing where things are.
+
+## Agents, some of whom are human
+
+There is one kind of participant: the **agent**. Some agents are human and some are not,
+and the mesh does not treat that as a category difference. Both hold identity, both hold
+credentials, both act, remember and coordinate. What differs is **modality** — how an
+agent acts:
+
+- a non-human agent acts through a spawned session and the record
+- a human agent acts through a shell, a desktop, a message from a phone
+
+That is why a desktop environment is as much a core concern as a knowledge store. One is
+how some agents remember; the other is how some agents act. Neither is a courtesy
+extended to a user outside the system.
+
+### What belongs in the mesh's own domain
+
+A **core** module supports an agent's *participation* — acting, remembering,
+coordinating, or interfacing with the mesh.
+
+A media server supports a human, but not their participation. It is therefore not a core
+module. It is still a perfectly valid HAL module — the
+mesh installs it, provisions for it, brokers its capabilities and ships it through the
+same pipeline. Entirely legitimate as a module, and no part of the mesh's own domain.
+
+The distinction is **core module** versus **module the mesh runs**, not module versus
+not-a-module. Both use the same manifest, the same pipeline, the same provisioning —
+which is exactly what makes the mesh's own components no more privileged than anything
+else it carries.
+
+## Core values
+
+- **Evidence over assertion.** A claim that cannot be checked will quietly stop being
+  true. Say what was measured.
+- **Failure must be loud.** The expensive faults are always the silent ones — work that
+  reported success and did nothing. Prefer failing to lying.
+- **The mesh owns the truth.** State lives in the mesh and is derived onto nodes. A file
+  edited on a node is a bug with a delay on it.
+- **Sovereignty.** The mesh runs on nodes it owns. External dependencies are
+  deliberate and few.
+- **Dogfood everything.** The mesh's own components ship through the same machinery as
+  anything else it runs. If they need an exception, the machinery is not finished.