# Decisions

The architecture decisions (ADRs) of Nereus, one file per decision, each opening with an "In short" block. The format and the rule for numbers are in [ADR 0001](../adr/0001-record-architecture-decisions.md).

| Decision | Status | In short |
|---|---|---|
| [0001. Record architecture decisions](../adr/0001-record-architecture-decisions.md) | Accepted | Every architecture decision is recorded in `docs/adr/`, one file per decision in Nygard's format. A number is valid only once its ADR is merged into `main`. |
| [0002. Conceptual model: reef, Instance, Mandate, Nereid, Tool](../adr/0002-conceptual-model.md) | Proposed | The platform is five layers plus Vendor: reef, Instance, Mandate, Nereid and Tool. A reef is a capability, an API group, and may exist with no Nereid. |
| [0003. `nereus init` prepares the platform; reefs and Nereids are added at runtime](../adr/0003-init-and-nereids-at-runtime.md) | Proposed | `nereus init` prepares a cluster with the built-in `core` reef and a profile's reefs; every other capability arrives later as a reef, with Nereids added at runtime. What init installs is revised by ADR 0014. |
| [0004. Reefs and their Nereids extend the CLI with their own commands](../adr/0004-reefs-extend-the-cli.md) | Proposed | Each reef describes its commands as data published in `status`, and the CLI builds them at runtime, grouped by reef, never by Nereid or Tool. |
| [0005. One writer per field](../adr/0005-one-writer-per-field.md) | Proposed | The API writes `spec`; each Nereid writes only its own part of `status`. A field that needs two writers is split. |
| [0006. Authentication is a reef](../adr/0006-authentication-reef.md) | Proposed | `authentication` is a reef: logins are always OIDC, the platform proves itself outwards through a Mandate per identity, and the User belongs to core. |
| [0007. Public by design](../adr/0007-public-by-design.md) | Accepted | The project is Apache-2.0 and public by design: no identifying data in any commit, and public names chosen as if already public. |
| [0008. The CLI is written in Python, with uv and typer](../adr/0008-cli-in-python.md) | Accepted | The CLI is written in Python, managed with `uv`, with `typer` for commands and the official `kubernetes` client. |
| [0009. Each reef is an API group `<reef>.getnereus.dev`](../adr/0009-api-group.md) | Proposed | Each reef is its own API group `<reef>.getnereus.dev`, starting at `v1alpha1`; the platform's own kinds live in `core.getnereus.dev`. |
| [0010. Reefs are added at runtime; commands are grouped by reef](../adr/0010-reefs-at-runtime.md) | Proposed | A reef is added at runtime from its contract, and a Nereid is added on its own and looks after one or more reefs. The `release` reef has four kinds. |
| [0011. Reefs, Nereids and Mandates, managed with top-level commands](../adr/0011-reefs-nereids-and-mandates.md) | Proposed | Reefs, Nereids and Mandates are managed with top-level commands, with `--reef` and `--nereid` as the flags everywhere; a Mandate binds one reef to one Nereid. |
| [0012. Every error message says what happened and how to fix it](../adr/0012-error-messages.md) | Proposed | Every error message, from the CLI or a Nereid, follows eight rules: what happened, the cause, how to check, how to fix, what changed, no traceback, and a fitness function. |
| [0013. Command conventions](../adr/0013-command-conventions.md) | Proposed | Commands share one shape, `nereus <noun> <verb> <name>`, with kubectl's verbs, dry runs, examples, and refusals that list the commands to run. |
| [0014. Profiles](../adr/0014-profiles.md) | Proposed | Core is only the engine; a profile lists the reefs, Nereids and Mandates to install, run as the commands a person would type. It revises what `nereus init` installs (ADR 0003). |
| [0015. Tenancy](../adr/0015-tenancy.md) | Proposed | Tenancy is a reef whose kinds come from each instance, with one fixed shape: every kind is a tree node with an optional parent, and one kind is the boundary. |
| [0016. The catalog reef](../adr/0016-catalog-reef.md) | Proposed | A `catalog` reef holds two kinds split by lifecycle, `Workload` for what runs and `Package` for what is published, with three characteristics and configurable types. |
| [0017. Resource reefs](../adr/0017-resource-reefs.md) | Accepted | Five resource reefs, each a small contract kind per family, with the provider chosen in the Mandate and a Mandate selected by its `match`. |
| [0018. The Nereus API is the one door](../adr/0018-nereus-api.md) | Proposed | The Nereus API is the one door of the platform: clients talk to it with the person's token, and the Kubernetes API stays behind it. |
| [0019. The messaging reef](../adr/0019-messaging-reef.md) | Proposed | The conversation joins the `messaging` reef as records (`Thread`, `Order`, `Claim`, `Message`), with a bus behind a Nereid. |
| [0020. The delivery reef](../adr/0020-delivery-reef.md) | Proposed | A `delivery` reef with one kind, `Delivery`, takes a Workload to an Environment; the Nereid, never the client, resolves an image tag to a digest. |
| [0021. The registry reef](../adr/0021-registry-reef.md) | Proposed | A `registry` reef with `Registry` and `Repository` kinds; images are read with one read-only credential per Registry, over TLS, and published through the platform. |
| [0022. A reef adds a screen to the portal as a Web Component its Nereid serves](../adr/0022-reef-screens-in-the-portal.md) | Accepted | A reef adds a screen to the portal as a Web Component its Nereid serves, named in its contract, loaded at runtime. |
| [0023. An external registry's push credential is the Repository's secret](../adr/0023-external-registry-push-credential.md) | Proposed | An external registry's push credential is the Repository's `secretRef`, read by the Nereid through a SecretBinding, never on the person's machine. |
| [0024. The scm reef](../adr/0024-scm-reef.md) | Proposed | An `scm` reef holds what a source host is to Nereus: a `Connection` names an organisation, reached through the App its scm Mandate names, and a `Mirror` copies a repository. |
| [0025. The platform receives metrics from anywhere through the CLI and the Nereus API](../adr/0025-metrics-intake.md) | Accepted | Metrics enter only through the Nereus API, with the CLI as the official client: declared sources, a spool, late-send alerts with a heartbeat, and machine identities. |
| [0026. The environment reef](../adr/0026-environment-reef.md) | Proposed | The `environment` reef has one kind, `Environment`, which is only the request; the cluster kept for it is `naxos`. |
| [0027. Teams](../adr/0027-teams-roles-and-users.md) | Accepted | A role is bound to a team, a position or a User on a node of the tenancy tree, and the Nereus API asks before it acts. Access roles, teams and Users are kept apart. |
| [0028. The presentations reef](../adr/0028-presentations-reef.md) | Accepted | The `presentations` reef keeps the deck as a `Presentation` and each time it is given as a `Session`. |
| [0029. A reef declares its MCP tools in the Nereid contract](../adr/0029-mcp-tools.md) | Proposed | MCP is a door of the Nereus API, not a reef: each reef declares its MCP tools in its Nereid contract, and the API serves them at `/mcp`. |
| [0030. Triton is the messaging reef's Nereid of rooms and peers](../adr/0030-triton-messaging-nereid.md) | Proposed | Triton is the messaging reef's Nereid of rooms and peers, an internal service reached only through the Nereus API. |
