---
status: accepted
date: 2026-08-22
deciders: jochen
reconstructed: false
supersedes: none
---

# 19. HQ is its own repository, and it is public

## Context

The mesh's reasoning — mission, research, design, decisions — began inside the code
repository, under a folder there. The objection to moving it out was specific and good: the
mesh already has an operational memory and a structured archive, and adding a third store
repeats the mistake that consolidation was meant to fix.

## Considered options

1. **Keep it in the code repository.** Rejected, but the objection it rests on is correct and
   is answered rather than dismissed — see Consequences.
2. **Put it in the structured archive**, alongside the governed documents. Rejected: the
   archive is not reviewable as a diff, and a design argument is exactly the thing that needs
   line-by-line review and a branch.
3. **Its own repository.** Chosen.

## Decision

HQ is its own repository, and it is **public** — written for a reader who is not its author
and has no access to the mesh it describes.

Three reasons it is separate:

- **The cadence differs.** A decision changes when thinking changes, not when code changes.
  Tying documents to a code branch merges them on the code's schedule.
- **The reviewers differ.** A design argument is not reviewed the way an implementation is,
  and should not queue behind a build.
- **The scope is wider than one repository.**
  [ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the
  monorepo; documentation governing several repositories cannot live inside one of them.

Being public is not incidental. It is enforceable only because
[ADR 0003](0003-the-mesh-database-is-the-source-of-truth.md) made the code repository
node-agnostic: there is no per-node content to leak. Nothing here may carry routable
addresses, real domain names, hosting providers, node names, absolute paths, usernames,
credentials, or operational detail useful only to an attacker.

The test is whether a paragraph would still teach a stranger running an entirely different
mesh.

## Consequences

- A document and the code it describes can no longer land in one commit. Keeping them honest
  is a discipline rather than a mechanism — which is why decisions are recorded as they are
  taken, and why a document stating a rule must say how the rule is checked.
- Research must state evidence without identifying the mesh it observed. The shape of a
  finding survives anonymisation; the instance does not travel.
- **The objection is answered by indexing, not by location** — the claim being that these
  documents remain searchable beside everything else, one source with many surfaces.
  **That indexing does not exist.** Checked 2026-08-23, it returns nothing. Until it does, the
  objection stands unanswered and this repository is the third knowledge store it was argued
  not to be. Recorded as
  [`04-ISSUES/006`](../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md).

## References

- Supersedes the earlier position that documentation lives inside the code repository under a
  folder there. That position was never recorded separately and has no record of its own.
- [`README.md`](../README.md) — the public-repository rule in full.