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: vocabulary, ownership, and rationale.
Agent instructions: repository collaboration boundaries.
Current work: 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:

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:

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.