# Novox HQ The single source of truth for what Novox builds — what it **is**, what it is **becoming**, and why. Today that is almost entirely **Novox Mesh**, the substrate everything else runs on. Implementation lives in `modules/`; the reasoning behind it lives here. ## Structure | Folder | Purpose | |--------|---------| | [`00-META`](00-META/) | Mission, foundational context, the rules that hold across the mesh, the repository map, and the process playbooks. The northern star for every decision. | | [`01-RESEARCH`](01-RESEARCH/) | Active and historical investigations, before they harden into design. | | [`02-DECISIONS`](02-DECISIONS/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. | | [`03-DESIGN`](03-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](03-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](03-DESIGN/01-to-be/) — the one being built toward. | | [`04-ISSUES`](04-ISSUES/) | The front door for "something is wrong" at the level of design or governance. | **The numbering is the flow.** Research produces a decision; the decision authorises a design. That is why decisions are `02` and design is `03` — a reader following the numbers walks the process in the order it happens. ## The flow ``` idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo) │ │ │ │ │ └─► 03-DESIGN/00-as-is once shipped │ └────► abandoned (recorded, kept) └─(small/obvious, still recorded in 02-DECISIONS)──────────► 03-DESIGN directly symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment 00-META/how-we-build.md ──► sync ──► the constitution the mesh injects into design sessions ``` Implementation lives in the code repositories — see [`00-META/repos.md`](00-META/repos.md). Every workflow is a playbook in [`00-META/process/`](00-META/process/); agents operate through them and not outside them. ## Rules - Markdown only. - No new top-level folders without explicit confirmation. - Knowledge flows `GENESIS → RESEARCH → DESIGN`. Research graduates into design only after analysis against GENESIS confirms alignment, and only through a recorded decision. - **Status lives in frontmatter**, never in a central status file. Cross-cutting views are generated on demand, never hand-maintained. - **GENESIS and DESIGN are instance-agnostic.** They describe the mesh as a concept — no machine names, no counts, no topology. A reader must not be able to tell how many nodes the author happened to have. - **RESEARCH describes real observations, but never identifies the mesh it observed.** Evidence is what makes research worth reading, and the shape of a finding survives anonymisation intact — *a node publicly named but behind a household NAT* carries the whole lesson without naming anything. - **The as-is layer records what is, not what should be** — including behaviour nobody would choose again. A layer that keeps only the good decisions is a brochure. - A document that states a rule about the mesh should say how that rule is **checked**. This repository has a rule requiring every capability-exposing module to declare the core runtime as a dependency; zero modules do. An unenforced rule is indistinguishable from a wrong one. ### This repository is public Written for a reader who is not its author and has no access to the mesh it describes. Concretely, nothing here may contain: - **routable addresses, real domain names, hosting providers, or node names** — use the documentation ranges (RFC 5737 `203.0.113.0/24`, RFC 1918) and role names such as `anchor`, `home-server`, `workstation`, `laptop` - **absolute paths** from anyone's machine, usernames, home directories, or email addresses - **credentials in any form**, including lengths or hashes of live secrets - **operational detail that is only useful to an attacker** — which host is the VPN hub, on which port, which node is reachable only through a forwarded port Private-range addresses and the overlay plan are fine: they describe a pattern, not a target. The test is whether a paragraph would still teach something to a stranger running an entirely different mesh. If it would, it belongs. If it only makes sense to someone who knows this particular installation, it is either a note in the wrong place or a disclosure. ## Why this is its own repository It began inside the code repository, on the reasoning that the mesh already has a mesh-native knowledge store and that adding a fourth knowledge system would repeat the mistake this folder was created to fix. **That objection was about a fourth knowledge *system*, and the answer offered was indexing rather than location** — that these documents would be indexed into the knowledge base, so a symptom search returns them beside everything else. One source, many surfaces. Where the source is authored is then a separate question. **That indexing does not exist.** It was checked on 2026-08-23 and returns nothing; it appears never to have existed. Until it does, the objection stands unanswered and this repository is the fourth knowledge system 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), and left standing here rather than quietly reworded, because a claim that held up a decision and was never checked is precisely the failure this repository exists to name. Answered separately, a repository of its own is the better home: - **The cadence is different.** A decision changes when thinking changes, not when code changes. Tying documents to a code branch means they merge on the code's schedule. - **The reviewers are different.** A design argument is not reviewed the way an implementation is, and it should not queue behind a build. - **The scope is wider than one repository.** [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the monorepo entirely. Documentation that governs several repositories cannot live inside one of them. The trade is real and worth naming: a change to a document and the change to the code it describes can no longer land in one commit. Keeping them honest is a discipline now rather than a mechanism — which is why every decision is recorded in [`02-DECISIONS`](02-DECISIONS/) as it is taken, and why a document that states a rule should say how the rule is checked. Recorded as [ADR 0019](02-DECISIONS/0019-hq-is-its-own-repository.md).