From dcc13f94e08487fff675eb5e4b7eaeaa7cf83af8 Mon Sep 17 00:00:00 2001 From: Emma Thorpe Date: Wed, 19 Aug 2026 17:29:24 +0100 Subject: [PATCH] docs: move prose documentation into docs/ so the docs site publishes it The docs-site build syncs this repo's README.md and docs/ into the site tree; nothing else is copied. All prose apart from the README therefore lived outside the sync and never appeared on https://docs.lyrapup.pet/nixfiles/, and the one page that did publish carried 18 link targets that resolved to nothing. Moves: home/README.md -> docs/shell.md home/KEYBINDINGS.md -> docs/keybindings.md hosts//README.md -> docs/hosts/.md docs/.pages and docs/hosts/.pages give the awesome-pages plugin an explicit order; new pages are picked up by the trailing '...' without an edit. Links are rewritten so a single URL is correct in both Gitea and the published site: absolute Gitea source URLs for .nix files and directories, relative links between pages under docs/, and absolute docs.lyrapup.pet URLs from the root README, which the build republishes at a different depth from the rest of the tree. In-code comments that pointed at a moved README are updated to the new path. The README gains a Documentation section covering the sync contract and the linking rules, and CLAUDE.md carries the short version so future edits do not reintroduce unsynced pages or dead links. Verified by reproducing the docs-site assembly locally against its pinned toolchain (mkdocs 1.6.1, mkdocs-material 9.7.7, awesome-pages 2.10.1): pages render at the URLs used above and in the declared order. --- CLAUDE.md | 11 +++ README.md | 79 +++++++++++++------ docs/.pages | 10 +++ docs/hosts/.pages | 1 + .../Darwin/README.md => docs/hosts/darwin.md | 0 hosts/EDaaS/README.md => docs/hosts/edaas.md | 6 +- .../README.md => docs/hosts/macpro31.md | 6 +- hosts/RPi5/README.md => docs/hosts/rpi5.md | 0 hosts/T400/README.md => docs/hosts/t400.md | 0 home/KEYBINDINGS.md => docs/keybindings.md | 14 ++-- home/README.md => docs/shell.md | 28 +++---- home/shell.nix | 4 +- hosts/MacPro31/configuration.nix | 2 +- hosts/RPi5/configuration.nix | 2 +- hosts/RPi5/hardware-configuration.nix | 2 +- hosts/T400/configuration.nix | 2 +- 16 files changed, 111 insertions(+), 56 deletions(-) create mode 100644 docs/.pages create mode 100644 docs/hosts/.pages rename hosts/Darwin/README.md => docs/hosts/darwin.md (100%) rename hosts/EDaaS/README.md => docs/hosts/edaas.md (90%) rename hosts/MacPro31/README.md => docs/hosts/macpro31.md (93%) rename hosts/RPi5/README.md => docs/hosts/rpi5.md (100%) rename hosts/T400/README.md => docs/hosts/t400.md (100%) rename home/KEYBINDINGS.md => docs/keybindings.md (94%) rename home/README.md => docs/shell.md (95%) diff --git a/CLAUDE.md b/CLAUDE.md index 7c38e2b..ba69032 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,6 +42,17 @@ prettier formats `*.md`, so **documentation edits must be run through `nix fmt`* exactly like code. prettier re-aligns Markdown tables in particular; hand-editing a table almost always leaves it non-conformant and fails the `formatting` check. +Prose documentation lives in `docs/` and is **published** to + by the separate `docs-site` repo, which +clones this one at build time. Two consequences when editing docs: + +- A markdown file outside `docs/` (other than the root `README.md`) is not + synced and will never appear on the site. Put new prose in `docs/`. +- Links must follow the rules in the README's "Documentation" section: absolute + Gitea URLs to source files, relative links between `docs/` pages, and + absolute `docs.lyrapup.pet` URLs from the root README into `docs/`. The site + builds non-strict, so a broken link is silent. + The CI `formatting` step runs on **every** PR — including docs- and config-only changes — so a Markdown/YAML/JSON edit is format-checked before merge, not just after it lands on `main`. (The heavier `deadnix`/`statix`/`pre-commit` lints and diff --git a/README.md b/README.md index 47a6de9..bb8fc52 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,16 @@ single flake. ## Hosts -Defined in the host table in [`flake.nix`](./flake.nix): +Defined in the host table in [`flake.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/flake.nix): -| Configuration | System | Machine | -| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- | -| `lyrathorpe-mbp` | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi) | -| `lyrathorpe-t400` | `x86_64-linux` | ThinkPad T400 — [install notes](./hosts/T400/README.md) | -| `lyrathorpe-macpro31` | `x86_64-linux` | Mac Pro 3,1, desktop — [install notes](./hosts/MacPro31/README.md) | -| `emmathorpe-edaas` | `x86_64-linux` | Work WSL box (NixOS-WSL) — [notes](./hosts/EDaaS/README.md) | -| `lyrathorpe-rpi5` | `aarch64-linux` | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](./hosts/RPi5/README.md) | -| `lyrathorpe-mac` | `aarch64-darwin` | macOS (nix-darwin) — [notes](./hosts/Darwin/README.md) | +| Configuration | System | Machine | +| --------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `lyrathorpe-mbp` | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi) | +| `lyrathorpe-t400` | `x86_64-linux` | ThinkPad T400 — [install notes](https://docs.lyrapup.pet/nixfiles/hosts/t400/) | +| `lyrathorpe-macpro31` | `x86_64-linux` | Mac Pro 3,1, desktop — [install notes](https://docs.lyrapup.pet/nixfiles/hosts/macpro31/) | +| `emmathorpe-edaas` | `x86_64-linux` | Work WSL box (NixOS-WSL) — [notes](https://docs.lyrapup.pet/nixfiles/hosts/edaas/) | +| `lyrathorpe-rpi5` | `aarch64-linux` | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](https://docs.lyrapup.pet/nixfiles/hosts/rpi5/) | +| `lyrathorpe-mac` | `aarch64-darwin` | macOS (nix-darwin) — [notes](https://docs.lyrapup.pet/nixfiles/hosts/darwin/) | Shared layers: `home` (home-manager: shell, git, editor), `modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches), @@ -31,6 +31,7 @@ flake.nix # inputs, mkHost/mkDarwinHost, the host tables, dev shell flake.lock # pinned input revisions (Renovate keeps this fresh) modules/ # reusable NixOS system modules (see "Module catalogue") home/ # home-manager profile: shell, git, editor, claude, secret-service, desktop, sway +docs/ # all prose documentation; published to docs.lyrapup.pet (see "Documentation") users/ # identity registry + per-user home extras (see "Users") hosts// # per-machine config: configuration.nix + hardware-configuration.nix lib/ # small pure helpers (currently the Catppuccin Mocha palette) @@ -50,7 +51,7 @@ host's table entry. ## Module catalogue -Reusable NixOS modules under [`modules/`](./modules). "Imported by" says how a +Reusable NixOS modules under [`modules/`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/modules). "Imported by" says how a module reaches a host: **baseModules** (every NixOS host, via `flake.nix`), **host table** (listed explicitly per host in `flake.nix`), or **transitively** (pulled in by another module's `imports`). @@ -86,7 +87,7 @@ declares what it is and the shared modules derive from that: are level 1). Ignored on non-x86_64 hosts. - `features.claudeCode.enable` — derived: on unless the host is below x86-64-v2, because Claude Code's Node runtime needs SSE4.2/POPCNT. - [`home/claude.nix`](./home/claude.nix) reads it through home-manager's + [`home/claude.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/claude.nix) reads it through home-manager's `osConfig` and installs nothing (CLI, `CLAUDE.md`, output style, memory symlink) when it is off. Hosts with no such option — the Darwin host and the standalone `homeConfigurations` — fall back to enabled. @@ -101,12 +102,12 @@ editing every host. Identity is data, kept separate from the reusable modules: -- [`users/registry.nix`](./users/registry.nix) — one entry per user (display +- [`users/registry.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/registry.nix) — one entry per user (display name, email, supplementary groups, authorized + signing keys). This is the single source of identity; no user data is hardcoded in the modules. - Each host's table entry declares a `users` set keyed by username; every entry lists that user's home-module composition (the shared `./home` bundle plus any - per-user modules, e.g. [`users/emmathorpe/work.nix`](./users/emmathorpe/work.nix)) + per-user modules, e.g. [`users/emmathorpe/work.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/work.nix)) and optional per-host-user system bits such as `linger`. - `mkHost` builds each account from the registry and injects the matching identity into that user's home config as the `identity` module arg. A host can @@ -114,13 +115,13 @@ Identity is data, kept separate from the reusable modules: Per-user home extras live under `users//`: -- [`users/lyrathorpe/home.nix`](./users/lyrathorpe/home.nix) — personal extras +- [`users/lyrathorpe/home.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/lyrathorpe/home.nix) — personal extras (an ssh host shortcut, gammastep coordinates); imported on Lyra's hosts. -- [`users/emmathorpe/work.nix`](./users/emmathorpe/work.nix) — the work +- [`users/emmathorpe/work.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/work.nix) — the work toolchain (kubectl/helm/az/etc.), work-only LSP servers, the corporate ssh handling, and the headless Secret Service that gcx needs for its keychain - tokens (see [`home/secret-service.nix`](./home/secret-service.nix)); imports - [`users/emmathorpe/renovate-review.nix`](./users/emmathorpe/renovate-review.nix), + tokens (see [`home/secret-service.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/secret-service.nix)); imports + [`users/emmathorpe/renovate-review.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/renovate-review.nix), the daily headless Renovate-PR review timer (EDaaS only). ### Portable home (off-NixOS / external consumers) @@ -179,20 +180,20 @@ automatically. ## Shell environment & keybindings - Interactive shell features (zsh, tmux, git, ssh, CLI tools, auto-tmux): - [`home/README.md`](./home/README.md). + [`docs/shell.md`](https://docs.lyrapup.pet/nixfiles/shell/). - Which classic utilities are shadowed by modern replacements, and the flag differences that will bite: - [`home/README.md` → "Replacing the classics"](./home/README.md#replacing-the-classics). + [`docs/shell.md` → "Replacing the classics"](https://docs.lyrapup.pet/nixfiles/shell/#replacing-the-classics). - All Sway / tmux / foot / zsh keyboard shortcuts: - [`home/KEYBINDINGS.md`](./home/KEYBINDINGS.md). + [`docs/keybindings.md`](https://docs.lyrapup.pet/nixfiles/keybindings/). ## Login / greeter Graphical (Sway) hosts log in through a Wayland greeter — `greetd` running ReGreet inside the `cage` kiosk compositor — implemented in -[`modules/sway.nix`](./modules/sway.nix), gated on +[`modules/sway.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/modules/sway.nix), gated on `features.swayDesktop.enable` (the option is declared in -[`modules/features.nix`](./modules/features.nix), so headless hosts +[`modules/features.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/modules/features.nix), so headless hosts can leave it off without importing `modules/sway.nix`). The greeter is forced to Dvorak to match the console and Sway session. Headless hosts (the WSL work box and the Raspberry Pi server) keep plain TTY login. The target account needs a password @@ -212,6 +213,38 @@ To refresh them, copy the firmware extracted during the Asahi install (from [Asahi NixOS docs](https://github.com/tpwrules/nixos-apple-silicon)) into `modules/firmware/` and commit with `git add -f`. +## Documentation + +All prose documentation lives in [`docs/`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/docs); this README is the overview. The pages are +published to **** by the +[`docs-site`](https://code.emmathe.dev/lyrathorpe/docs-site) repository, which clones this repo on +every build (on its own push, nightly, or on demand) and assembles the tree: + +``` +README.md -> docs/nixfiles/index.md # this file becomes the section landing page +docs/ -> docs/nixfiles/ # everything here, ordering from docs/.pages +``` + +Nothing is pushed from this side and there is no build step here — editing a +page and merging is all that is required. Files outside `docs/` (bar this +README) are **not** synced, so a doc kept next to the code it describes will +never appear on the site. + +### Linking rules + +The site has no copy of the source tree, and this README is republished at a +different depth from the rest of `docs/`. Both facts break naive relative +links, so: + +| Link from | To | Use | +| ----------------- | ----------------------- | ---------------------------------------------------------------- | +| anywhere | a source file or dir | absolute `https://code.emmathe.dev/.../src/branch/main/…` | +| a page in `docs/` | another page in `docs/` | relative (`./keybindings.md`) — correct in Gitea and on the site | +| this README | a page in `docs/` | absolute `https://docs.lyrapup.pet/nixfiles/…` | + +`mkdocs build` runs non-strict on the docs-site side, so a broken link fails +silently rather than failing the build. Check links by hand when moving a page. + ## Development A dev shell and a formatting/lint gate are wired through the flake: @@ -227,7 +260,7 @@ A dev shell and a formatting/lint gate are wired through the flake: ## CI -[`.gitea/workflows/ci.yaml`](./.gitea/workflows/ci.yaml) runs `nix flake check` +[`.gitea/workflows/ci.yaml`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/.gitea/workflows/ci.yaml) runs `nix flake check` (formatting, `deadnix`, `statix`, the pre-commit hooks) and evaluates every NixOS and Darwin host configuration on push/PR. It always runs (no `paths:` filter) so the required check never hangs pending; the heavy Nix steps are diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000..8d0a8cc --- /dev/null +++ b/docs/.pages @@ -0,0 +1,10 @@ +# Section ordering for the MkDocs awesome-pages plugin on docs.lyrapup.pet. +# `index.md` is this repository's root README, copied in by the docs-site build +# before this directory is synced over the top. The trailing `...` picks up any +# page added later, so a new file needs no edit here. +nav: + - index.md + - shell.md + - keybindings.md + - hosts + - ... diff --git a/docs/hosts/.pages b/docs/hosts/.pages new file mode 100644 index 0000000..05e672d --- /dev/null +++ b/docs/hosts/.pages @@ -0,0 +1 @@ +title: Hosts diff --git a/hosts/Darwin/README.md b/docs/hosts/darwin.md similarity index 100% rename from hosts/Darwin/README.md rename to docs/hosts/darwin.md diff --git a/hosts/EDaaS/README.md b/docs/hosts/edaas.md similarity index 90% rename from hosts/EDaaS/README.md rename to docs/hosts/edaas.md index 8338198..4b141cf 100644 --- a/hosts/EDaaS/README.md +++ b/docs/hosts/edaas.md @@ -11,7 +11,7 @@ The day-to-day work environment. It layers the corporate Kubernetes / Helm / Terraform / cloud toolchain and a couple of work-only editor language servers on top of the shared home profile. The system config here is thin — it is mostly WSL plumbing; the user-facing tooling lives in -[`../../users/emmathorpe/work.nix`](../../users/emmathorpe/work.nix). +[`../../users/emmathorpe/work.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/work.nix). ## WSL specifics @@ -34,7 +34,7 @@ WSL plumbing; the user-facing tooling lives in The host-table entry sets `users.emmathorpe.linger = true` so the user's `systemd --user` instance stays alive without an open login session. That keeps the daily headless **Renovate PR review** timer firing — defined in -[`../../users/emmathorpe/renovate-review.nix`](../../users/emmathorpe/renovate-review.nix) +[`../../users/emmathorpe/renovate-review.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/renovate-review.nix) (imported only from `work.nix`, so it exists on this machine alone). See that file's header for the auth (Vertex AI ADC), triage policy, and caveats. @@ -53,7 +53,7 @@ name is not activatable". Home-manager's own `services.gnome-keyring` does not work here: it is `WantedBy=graphical-session-pre.target`, which never activates on this headless box, and it cannot unlock the keyring. See -[`../../home/secret-service.nix`](../../home/secret-service.nix) for the full +[`../../home/secret-service.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/secret-service.nix) for the full rationale and the security trade-off of an auto-unlocked keyring. Only the `secrets` component is started. The `ssh` component is deliberately off diff --git a/hosts/MacPro31/README.md b/docs/hosts/macpro31.md similarity index 93% rename from hosts/MacPro31/README.md rename to docs/hosts/macpro31.md index f514f39..8143d50 100644 --- a/hosts/MacPro31/README.md +++ b/docs/hosts/macpro31.md @@ -31,7 +31,7 @@ Partition the disk GPT with an ESP (vfat). The stock card (**ATI Radeon HD 2600 XT** or **NVIDIA GeForce 8800 GT**, depending on the unit) has been replaced with an **NVIDIA Quadro P400** (Pascal, -GP108). Everything driver-related lives in [`nvidia.nix`](./nvidia.nix): +GP108). Everything driver-related lives in [`nvidia.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/hosts/MacPro31/nvidia.nix): - **Driver branch 580** (`nvidiaPackages.legacy_580`), _not_ the nixpkgs default (`production`, currently 595.x). 580 is the last branch that supports @@ -48,7 +48,7 @@ GP108). Everything driver-related lives in [`nvidia.nix`](./nvidia.nix): The driver is unfree, so it is **not in the binary cache**: the kernel module is compiled on the machine, which on these 2008 Xeons is slow — budget for a long first rebuild and again after every kernel bump. The package names are -allowlisted in `unfreePackages` in [`flake.nix`](../../flake.nix). +allowlisted in `unfreePackages` in [`flake.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/flake.nix). Note the Mac Pro shows no EFI boot screen with a stock PC card (no Apple EFI ROM): the machine boots blind until KMS brings the display up. That is expected, @@ -113,7 +113,7 @@ it, so that should not happen). The dual Harpertown Xeons are **x86-64-v1** (SSE4.1, but no SSE4.2/POPCNT) and the Node runtime Claude Code ships on requires x86-64-v2. `configuration.nix` declares `features.cpu.microarchLevel = 1`, which switches the tool off through -the fleet-wide gate in [`../../modules/features.nix`](../../modules/features.nix) +the fleet-wide gate in [`../../modules/features.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/modules/features.nix) — see the root README. Forcing `features.claudeCode.enable` on here is an evaluation error, not a broken install. diff --git a/hosts/RPi5/README.md b/docs/hosts/rpi5.md similarity index 100% rename from hosts/RPi5/README.md rename to docs/hosts/rpi5.md diff --git a/hosts/T400/README.md b/docs/hosts/t400.md similarity index 100% rename from hosts/T400/README.md rename to docs/hosts/t400.md diff --git a/home/KEYBINDINGS.md b/docs/keybindings.md similarity index 94% rename from home/KEYBINDINGS.md rename to docs/keybindings.md index fb6a2fd..84831fb 100644 --- a/home/KEYBINDINGS.md +++ b/docs/keybindings.md @@ -4,13 +4,13 @@ Every keyboard shortcut configured across this desktop, and where it is defined. Everything here is managed declaratively through Nix — edit the listed file and rebuild, never the generated dotfiles. -| Area | Defined in | -| ----------------- | --------------------------------------------------------------------------------------------------------------------- | -| Sway (compositor) | [`sway.nix`](./sway.nix) `config.keybindings` + `config.modes`, plus the home-manager Sway module's built-in defaults | -| tmux | [`shell.nix`](./shell.nix) `programs.tmux` | -| zsh line editor | [`shell.nix`](./shell.nix) `programs.zsh.historySubstringSearch` | -| Neovim | [`editor.nix`](./editor.nix) `programs.nixvim` | -| foot (terminal) | foot package defaults — only colours are themed (in `sway.nix`) | +| Area | Defined in | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Sway (compositor) | [`sway.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/sway.nix) `config.keybindings` + `config.modes`, plus the home-manager Sway module's built-in defaults | +| tmux | [`shell.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/shell.nix) `programs.tmux` | +| zsh line editor | [`shell.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/shell.nix) `programs.zsh.historySubstringSearch` | +| Neovim | [`editor.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/editor.nix) `programs.nixvim` | +| foot (terminal) | foot package defaults — only colours are themed (in `sway.nix`) | **Conventions** diff --git a/home/README.md b/docs/shell.md similarity index 95% rename from home/README.md rename to docs/shell.md index ca37142..f180852 100644 --- a/home/README.md +++ b/docs/shell.md @@ -4,21 +4,21 @@ Everything the shell, terminal multiplexer, git and ssh do beyond their defaults and where each is defined. All of it is managed declaratively through home-manager — edit the listed file and rebuild, never the generated dotfiles. -Keyboard shortcuts have their own reference: [`KEYBINDINGS.md`](./KEYBINDINGS.md). +Keyboard shortcuts have their own reference: [`keybindings.md`](./keybindings.md). -| Area | Defined in | -| -------------------------------------- | ----------------------------------------------------- | -| zsh, CLI tools, tmux, ssh, auto-tmux | [`shell.nix`](./shell.nix) | -| git (+ delta, commitizen) | [`git.nix`](./git.nix) | -| Neovim (nixvim) + LSP | [`editor.nix`](./editor.nix) | -| Claude Code (CLAUDE.md, style, memory) | [`claude.nix`](./claude.nix) | -| GUI apps, GTK/Firefox theming, cursor | [`desktop.nix`](./desktop.nix) (graphical hosts only) | +| Area | Defined in | +| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| zsh, CLI tools, tmux, ssh, auto-tmux | [`shell.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/shell.nix) | +| git (+ delta, commitizen) | [`git.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/git.nix) | +| Neovim (nixvim) + LSP | [`editor.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/editor.nix) | +| Claude Code (CLAUDE.md, style, memory) | [`claude.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/claude.nix) | +| GUI apps, GTK/Firefox theming, cursor | [`desktop.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/desktop.nix) (graphical hosts only) | -Shared by every host via [`default.nix`](./default.nix); the work box also layers -[`work.nix`](../users/emmathorpe/work.nix) on top (its own ssh config, extra +Shared by every host via [`default.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/default.nix); the work box also layers +[`work.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/work.nix) on top (its own ssh config, extra packages, kubecolor, and the C#/Helm language servers). The committer identity (name, email, signing key) comes from the user registry -([`../users/registry.nix`](../users/registry.nix)), not this module. +([`../users/registry.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/registry.nix)), not this module. --- @@ -257,7 +257,7 @@ place of the old (inert) ALE. Leader is `Space`. LSP keymaps (`gd`, `gr`, `K`, `rn`, `ca`) and the file-tree toggle are listed in -[`KEYBINDINGS.md`](./KEYBINDINGS.md#neovim). Add a universal language server by +[`keybindings.md`](./keybindings.md#neovim). Add a universal language server by enabling it under `programs.nixvim.plugins.lsp.servers` in `editor.nix`; host-specific ones go in that host's module — the work box (`work.nix`) adds `omnisharp` (C#) and `helm_ls` (Helm), kept off the personal machines. @@ -310,7 +310,7 @@ forced off there) but still runs the agent. ## Claude Code -Managed declaratively by [`claude.nix`](./claude.nix) on every host whose CPU +Managed declaratively by [`claude.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/claude.nix) on every host whose CPU can run it (the CLI is `pkgs.claude-code`, tracked to unstable via the flake overlay). @@ -332,7 +332,7 @@ and the standalone `homeConfigurations` — keep it enabled. break. **Memory is sourced from this repo.** The files in -[`claude/memory/`](./claude/memory) are the source of truth; they are symlinked +[`claude/memory/`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/claude/memory) are the source of truth; they are symlinked read-only into `~/.claude/memory`, so recall works but the runtime "save a memory" path does not. To add/change/remove a memory, edit `claude/memory/` (one file per memory + the `MEMORY.md` index) and rebuild — `CLAUDE.md` tells diff --git a/home/shell.nix b/home/shell.nix index 5f7c0e4..9fab8b0 100644 --- a/home/shell.nix +++ b/home/shell.nix @@ -31,7 +31,7 @@ in # are aliased over the original name (see shellAliases below); the rest keep # their own name so nothing changes shape under a script's feet. The alias # map and the flag-compatibility differences are documented in - # ./README.md, "Replacing the classics". + # ../docs/shell.md, "Replacing the classics". pkgs.dust # du: tree-shaped, size-sorted disk usage pkgs.dysk # df: mounted filesystems (duf is unmaintained upstream) pkgs.procs # ps: process list with tree, ports and container columns @@ -165,7 +165,7 @@ in # Shadow the classics with their modern equivalents. Only read-only # commands are shadowed: a wrong flag costs a retype, never data. The # flag vocabularies are NOT compatible (`du -sh`, `df -h`, `ps aux` all - # fail here) -- see ./README.md, "Replacing the classics". + # fail here) -- see ../docs/shell.md, "Replacing the classics". # # Blast radius is bounded by where these live: shellAliases lands in # .zshrc, so only interactive zsh sees them. Scripts, `sudo ` and diff --git a/hosts/MacPro31/configuration.nix b/hosts/MacPro31/configuration.nix index 82eee35..cd4322f 100644 --- a/hosts/MacPro31/configuration.nix +++ b/hosts/MacPro31/configuration.nix @@ -1,7 +1,7 @@ # Apple Mac Pro 3,1 (Early 2008, dual Xeon Harpertown, x86_64). Desktop host: # shared graphical/wired options live in ../../modules/desktop.nix; only # host-specific settings are here. Install notes (EFI booting, GPU, partitions): -# see ./README.md. +# see ../../docs/hosts/macpro31.md. { ... }: { diff --git a/hosts/RPi5/configuration.nix b/hosts/RPi5/configuration.nix index 4e3630d..0171520 100644 --- a/hosts/RPi5/configuration.nix +++ b/hosts/RPi5/configuration.nix @@ -2,7 +2,7 @@ # ./docker.nix (Docker host with a network socket) and ./reverse-proxy.nix # (native nginx). The raspberry-pi-5 nixos-hardware profile (kernel, firmware, # device tree) and key-only sshd (../../modules/ssh.nix) are layered on in the -# flake host table. Install notes: see ./README.md. +# flake host table. Install notes: see ../../docs/hosts/rpi5.md. { ... }: { imports = [ diff --git a/hosts/RPi5/hardware-configuration.nix b/hosts/RPi5/hardware-configuration.nix index 8ec7411..45e23d3 100644 --- a/hosts/RPi5/hardware-configuration.nix +++ b/hosts/RPi5/hardware-configuration.nix @@ -4,7 +4,7 @@ # evaluates in CI before the Pi is provisioned. The machine will not boot from # it as-is. On first install, regenerate this file on the device with # nixos-generate-config --root /mnt -# and replace this placeholder with the output (commit it). See ./README.md. +# and replace this placeholder with the output (commit it). See ../../docs/hosts/rpi5.md. # # Like every hardware-configuration.nix in this repo, this file is excluded from # the formatter and linters (see the pre-commit/treefmt excludes in flake.nix). diff --git a/hosts/T400/configuration.nix b/hosts/T400/configuration.nix index 96c05d1..496783e 100644 --- a/hosts/T400/configuration.nix +++ b/hosts/T400/configuration.nix @@ -1,6 +1,6 @@ # ThinkPad T400 (NixOS). Shared laptop options live in ../../modules/laptop.nix; # only host-specific settings are here. Install notes (boot variants, GPU, -# partitions): see ./README.md. +# partitions): see ../../docs/hosts/t400.md. { config, ... }: { -- 2.54.0