# 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 / folder | 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) | The rules that hold across the mesh, each one earned. **The source of the mesh constitution** — the governed page the mesh injects into design sessions is derived from it. |
| [`repos.md`](repos.md) | Where implementation lives, and what each repository owns |
| [`process/`](process/) | The playbooks — how work moves through this repository, for engineers and agents alike |

## Rules

- Markdown only.
- **Stable by nature.** Changes here reflect a genuine shift in intent, not iteration. The one
  exception is `how-we-build.md`, which changes whenever a rule is earned — and only through
  its amendment process.
- Research and design must be traceable back to what is written here.
- **Instance-agnostic.** These documents describe the mesh as a concept. No machine names, no
  counts, no topology.

## On the architecture overview in the code repository

The code repository carries an architecture overview predating this folder. It is a useful
description of *how* the mesh works, and its content now lives — anonymised and checked against
the implementation — in [`02-DESIGN/00-as-is/`](../02-DESIGN/00-as-is/). GENESIS answers *why*;
that document answered *how*, which is the design layer's job.

It had also drifted from the implementation in ways worth recording, since both were found by
comparing it against the code rather than by anyone noticing:

- It described the pipeline as having a separate builder process and a build stage that
  packages. Neither was true after 2026-08-04; the documents stayed stale until 2026-08-06
  ([ADR 0014](../adr/0014-build-publish-and-deploy-are-three-silos.md)).
- It listed the mesh as spanning a fixed number of named machines, which is exactly the
  content this repository cannot carry.

One earlier note in this file has been withdrawn as **wrong**, and is recorded here rather than
deleted. It claimed the overview's "symlinks, not copies" principle contradicted the mesh's
hard rule against symlinks. It does not. The rule forbids *creating* a symlink by hand; the
installer creates and reconciles every link the mesh needs, deliberately
([ADR 0011](../adr/0011-the-installer-owns-linking.md)). The rule is about who may link, not
about whether the mesh links — a misreading common enough that the ADR now says so explicitly.