# 00-META

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 [`03-DESIGN/00-as-is/`](../03-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](../02-DECISIONS/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.

It also lists **"symlinks, not copies" as a key design principle**, and that is a genuine
contradiction rather than a stale detail. The mesh's stated intent is that it creates no
symlinks at all — the rule is not merely "only the installer may link", and a founding document
elevating linking to a principle points the opposite way from where this is going.

What exists today is that the installer owns and reconciles every link
([ADR 0011](../02-DECISIONS/0011-the-installer-owns-linking.md)) — an as-is fact, recorded in
[`03-DESIGN/00-as-is/05-runtime-and-installation.md`](../03-DESIGN/00-as-is/05-runtime-and-installation.md).
Centralising who may link narrowed the incident class; it did not close it. The intent is to
remove the mechanism, recorded as [ADR 0018](../02-DECISIONS/0018-the-mesh-creates-no-symlinks.md).

A founding document contradicting the direction of travel is precisely the failure this folder
exists to prevent.