---
status: canonical
updated: 2026-08-23
---

# The Novox repositories

The map of where implementation lives. Humans use it for orientation; agents use it for issue
triage (playbook [`process/03-issues.md`](process/03-issues.md)). The `code:` frontmatter
field in design documents points at entries here.

Repository *names* are recorded; hosts, URLs and owners are not — this repository is public,
and a forge address is an operational detail (see [`README`](../README.md)).

| Repository | Owns |
|---|---|
| `hal` | The monorepo — the node runtime, the module catalogue, the delivery machinery, and the bootstrap scripts. Every core module lives here. |
| `hq` | This repository, under the company organisation — mission, research, design, decisions, issue diagnosis. Company-scoped ([ADR 0028](../02-DECISIONS/0028-hq-is-company-scoped.md)); the mesh is its first product. The source of truth for *why*. Carries no implementation. |
| *(one per application)* | Every standalone application, site or side-project gets its own repository, with `module.yml` at the root. Registered with the mesh as a build source; built and deployed by the same pipeline as anything in the monorepo. |

## What lives where inside the monorepo

Named by role, because the layout is itself part of the as-is design — see
[`03-DESIGN/00-as-is/`](../03-DESIGN/00-as-is/).

| Area | Holds |
|---|---|
| Module catalogue | One directory per module, each with a manifest. Core modules sit under the mesh's own namespace; everything else at the top level. |
| Node runtime | The daemon and interactive runtime that every node runs. |
| Bootstrap scripts | First-node initialisation, joining an existing mesh, and node rescue. |
| Shared library | The SDK every module builds against. |
| Pipeline test harness | End-to-end coverage of the delivery pipeline. Currently unbuildable — see [`04-ISSUES/005`](../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md). |

## Why applications do not live in the monorepo

A standalone application in the monorepo is a convention violation, and reviewers reject it.
The reasoning is recorded in [`02-DECISIONS/0010`](../02-DECISIONS/0010-applications-live-in-their-own-repository.md):
the mesh installs, provisions for, and ships an application through exactly the same machinery
whether or not its source sits beside the mesh's own — so co-location buys nothing and costs
the monorepo's review cadence.

## There is no npm workspace

Each module is a standalone package that consumes its dependencies from the private registry,
not from a sibling directory. The workspace was removed after it caused build-versus-development
divergence — a workspace member importing another resolved to local unbuilt source in the
pipeline and to a published version in development. Recorded in
[`02-DECISIONS/0007`](../02-DECISIONS/0007-no-npm-workspace.md).

Consequence, and it is a real one: a cross-package change is two steps — publish, then consume
— and a repository-wide `npm install` does not exist.