Establish repository foundation and shared work environment

2026-09-19 13:28:22 +02:00
1 parent 3c022ad2f9
commit f164d8b76e
@@ -1,24 +1,90 @@
 # NixOS configuration

-Host identity and topology live in `modules/hosts/<host>/default.nix`; shared account,
-service, external-device, and server-topology facts live in `modules/facts.nix`.
+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.

- Add a package used by both workstations to the relevant Home Manager capability,
-  or to `workstation-apps` in `modules/capabilities/desktop-defaults.nix` when it needs
-  no configuration.
- Add a host-specific capability to that host's import list in
-  `modules/hosts/<host>/default.nix`.
- Change the selected terminal or editor by replacing the corresponding
-  `primary-terminal-*` import in `modules/profiles/workstation-base.nix` or
-  `primary-editor-*` import in `modules/profiles/host-base.nix`.
- Keep native theme settings with the application. Explicit Kanagawa color mappings
-  may import `modules/capabilities/_kanagawa.nix`.
+## Start here

-Common commands:
+- [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 fmt
-nix flake check --no-build
-nh os switch
-sops edit modules/secrets/secrets.yaml
+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.