# NixOS configuration

One shared daily environment on Polaris and Zenith, with shared services on Orion.
NixOS and Home Manager are composed through flake-parts and import-tree.

## Start here

- [Design](docs/design.md): vocabulary, ownership, and rationale.
- [Agent instructions](AGENTS.md): repository collaboration boundaries.
- [Current work](docs/current-work.md): accepted scope, open decisions, and next step.

## Configuration map

| Owner | Location | Responsibility |
| --- | --- | --- |
| Hosts | `modules/hosts/<host>/` | Identity, hardware, machine-specific selection |
| Profiles | `modules/profiles/` | Combinations of capabilities |
| Capabilities | `modules/capabilities/` | Behavior and integration across NixOS and Home Manager |
| Facts | `modules/facts.nix` | Shared identity and topology; host facts are declared with hosts |
| Composition | `flake.nix`, `modules/flake-parts.nix` | Inputs, discovery, host construction |
| Secrets | `modules/secrets/` | Existing SOPS declarations and encrypted data |

Discovery makes named modules available; imports select them. Underscore-prefixed
helpers and directories are excluded from automatic discovery and imported explicitly.
Add shared behavior to its capability and select it through the relevant profile.
Keep machine differences in hosts. A capability can own system and user modules.

The primary editor is selected in `host-base.nix`, the primary terminal in
`workstation-base.nix`. `modules/capabilities/theme.nix` selects the complete theme;
Kanagawa lives in `modules/capabilities/_themes/kanagawa.nix`. Appearance belongs
there; interaction and layout belong with the capability.

## Work environment (provisional)

Both workstations import `modules/profiles/work.nix`: company network/development
integration, Garden tools, and work Git settings. This is a trial boundary, not
an independent workstation variant. SharePoint remains Zenith-only for now.

The tools-only environment is owned by
`modules/capabilities/yookr-dev/environment.nix`. It shares Garden definitions in
`_packages.nix` with installed tools and uses the system's nixpkgs pin:

```console
nix develop --quiet ~/.config/nixos#workbench --command bash --norc
```

This does not clear inherited credentials; start from a clean environment for
agent work. It does not load secrets, mount storage, or install Python dependencies.
Workspace `.envrc` files select it; the workbench's human credential and mount
steps remain workspace-owned. Requests, queries, analysis, and `uv.lock` stay there.
After loader changes, the user must review and re-allow the changed `.envrc` files
with direnv. No loader is sourced as part of validation.

## Maintenance

Run from this repository:

```console
just validate          # format, evaluate, build every host and the workbench
just validate polaris  # same workflow, build only the named host(s)
```

The command includes current tracked files and non-ignored new files, respects
working-tree deletions, and never changes the Git index. It resolves the pinned
formatter from a temporary source snapshot, formats included Nix files in the
working tree, then refreshes the snapshot for evaluation and builds. Ignored
untracked files and `.git` are excluded. Avoid concurrent edits during validation:
results describe the snapshot, not subsequent changes.

Output is limited to stage results and a short excerpt on failure. Full logs remain
in the printed `/tmp/nixos-validate-*` directory; source snapshots are removed on
exit. Failed stages stop the command. Inputs are not updated, no result links are
created, and nothing is activated. Host names are discovered from the flake.

`just` and Python are already declared for both workstations. The implementation
is `scripts/validate.py`; the justfile is only its entry point. The formatter output
currently targets this repository's sole system, `x86_64-linux`.

Use full validation after a configuration batch and targeted hosts during iteration.
Documentation-only edits need review, local link checks, and `git diff --check`,
not system builds. Evaluation, build, activation, and confirmed behavior are
separate evidence. Outside this wrapper, ordinary Git-backed flake commands still
require intended new files to be added to Git.

The user activates with `nh os switch`. Edit encrypted data with
`sops edit modules/secrets/secrets.yaml`; keep plaintext out of Nix expressions
and the store. No new credential-delivery design is selected yet.

Historical material under `docs/.archive/` is evidence, not current instructions
or a backlog. Consult it only for relevant unresolved questions.