Improve the links in the secrets documentation.

secrets.md

@@ -8,16 +8,16 @@ This document explains how we manage secrets for the PRG server configuration us
 
 ## Quick overview
 
-We encrypt secrets with sops using the age tool. The repository contains a `.sops.yaml` that documents which public recipients can decrypt which files (via creation_rules). Encrypted files are safe to commit to git; only machines with the corresponding private age keys can decrypt them.
+We encrypt secrets with sops using the age tool. The repository contains a *[.sops.yaml](.sops.yaml)* that documents which public recipients can decrypt which files (via creation_rules). Encrypted files are safe to commit to git; only machines with the corresponding private age keys can decrypt them.
 
 
 ## Files and conventions (what to look for)
 
-- `.sops.yaml` - repository configuration that lists public age recipients and creation_rules that map file paths to key groups.
+- *[.sops.yaml](.sops.yaml)* - repository configuration that lists public age recipients and creation_rules that map file paths to key groups.
 - `nix-system-configs/secrets/...` - the repository path where secrets are stored, organized by subsystem (for example `database`, `mail`, `songsheet`, `build_machine`, `traefik`, etc.).
-- Nix module files that use sops (examples in `nix-system-configs/modules/secrets-config/`) - those show how secrets are exported into NixOS as file or string secrets.
+- Nix module files that use sops (examples in *[secrets-config](nix-system-configs/modules/secrets-config)* - those show how secrets are exported into NixOS as file or string secrets.
 
-Inspect the repository's `.sops.yaml` (example shown later) and the secrets folders before creating or editing secrets.
+Inspect the repository's *[.sops.yaml](.sops.yaml)* (example shown later) and the secrets folders before creating or editing secrets.
 
 
 ## Creating and registering age keys (on the machine that will hold the private key)
@@ -38,15 +38,15 @@ nix-shell -p age --run 'sudo mkdir -p /var/lib/sops-nix && sudo chown $USER /var
 What the generated key file contains (example):
 
 - private key: starts with `AGE-SECRET-KEY-` (keep private)
-- public key (recipient): looks like `age1...` - this is what you add to `.sops.yaml`
+- public key (recipient): looks like `age1...` - this is what you add to *[.sops.yaml](.sops.yaml)*
 
 
-## Inspecting / editing `.sops.yaml`
+## Inspecting / editing *[.sops.yaml](.sops.yaml)*
 
 > [!NOTE]
-> `.sops.yaml` controls which public keys can decrypt files and where new secret files should live. When adding a public key, add the recipient under the `keys:` list and update `creation_rules:` if needed.
+> *[.sops.yaml](.sops.yaml)* controls which public keys can decrypt files and where new secret files should live. When adding a public key, add the recipient under the `keys:` list and update `creation_rules:` if needed.
 
-Example `.sops.yaml` entries (repository already contains similar entries):
+Example *[.sops.yaml](.sops.yaml)* entries (repository already contains similar entries):
 
 ```yaml
 keys:
@@ -62,13 +62,13 @@ creation_rules:
 ```
 
 Notes:
-- The repository's actual `.sops.yaml` uses YAML anchors (for example `&admin_christine`) and path-specific creation_rules for `songsheet`, `traefik`, `database`, `christine`, `wireguard`, `build_machine`, and `mail`.
+- The repository's actual *[.sops.yaml](.sops.yaml)* uses YAML anchors (for example `&admin_christine`) and path-specific creation_rules for `songsheet`, `traefik`, `database`, `christine`, `wireguard`, `build_machine`, and `mail`.
 - `path_regex` is matched relative to the repository root. Keep the files under `nix-system-configs/secrets/...` for consistency with existing rules.
 
 
 ## Creating a new encrypted secret file
 
-1. Ensure the public recipient(s) for the intended end systems exist in `.sops.yaml`.
+1. Ensure the public recipient(s) for the intended end systems exist in *[.sops.yaml](.sops.yaml)*.
 2. Use sops to create or edit an encrypted file. If sops cannot find an age key in the usual locations, pass `SOPS_AGE_KEY_FILE` pointing to the generated private key (only when editing locally with your private key present).
 
 Example (editor micro) - note we use a temporary environment so sops can locate the key you generated locally:
@@ -91,7 +91,7 @@ After saving, sops will replace plaintext with encrypted blocks and add a `sops:
 
 #### Example secret file
 
-The repository includes `nix-system-configs/secrets/build_machine/secrets.yaml` which contains an encrypted `runner_token` plus the sops metadata. That file shows the encrypted enc blocks and recipients under `sops:`, thus you can use it as a reference for structure.
+The repository includes *[secrets.yaml](nix-system-configs/secrets/build_machine/secrets.yaml)* (at `nix-system-configs/secrets/build_machine/secrets.yaml`) which contains an encrypted example plus the sops metadata. That file shows the encrypted enc blocks and recipients under `sops:`, thus you can use it as a reference for structure.
 
 
 ## How to add a new secrets set and wire it into Nix (step‑by‑step)
@@ -162,9 +162,9 @@ imports = [
 
 
 > [!NOTE]
-> This section is only required if you did not already generate and register age keys for the target end system. If you pregenerated the key pair and added the public recipient to `.sops.yaml`, you can skip these steps.
+> This section is only required if you did not already generate and register age keys for the target end system. If you pregenerated the key pair and added the public recipient to *[.sops.yaml](.sops.yaml)*, you can skip these steps.
 >
-> If `sops.age.generateKey = true` and no key exists, the module will create `/var/lib/sops-nix/key.txt` on the target end system when the module activates. After the module generates a key, extract the public recipient (the `age1...` line) and add it to the repository `.sops.yaml` under `keys:` and to the appropriate `creation_rules` so future `sops` edits include the new recipient.
+> If `sops.age.generateKey = true` and no key exists, the module will create `/var/lib/sops-nix/key.txt` on the target end system when the module activates. After the module generates a key, extract the public recipient (the `age1...` line) and add it to the repository *[.sops.yaml](.sops.yaml)* under `keys:` and to the appropriate `creation_rules` so future `sops` edits include the new recipient.
 >
 > Example commands to extract the public recipient (run on the target machine; use sudo if needed):
 >
@@ -173,10 +173,10 @@ imports = [
 > sudo cat /var/lib/sops-nix/key.txt
 > ```
 >
-> Important: never commit the private key (the `AGE-SECRET-KEY-...` line) into the repository - only the `age1...` public recipient belongs in `.sops.yaml`.
+> Important: never commit the private key (the `AGE-SECRET-KEY-...` line) into the repository - only the `age1...` public recipient belongs in *[.sops.yaml](.sops.yaml)*.
 
 > [!NOTE]
-> After you add a new public `age1...` recipient to `.sops.yaml`, update any existing encrypted files so the new recipient is included in each file's recipients list. Use `sops updatekeys <file>` to update a single file; sops must be able to decrypt the file locally (for example by having a private key available or by setting `SOPS_AGE_KEY_FILE`).
+> After you add a new public `age1...` recipient to *[.sops.yaml](.sops.yaml)*, update any existing encrypted files so the new recipient is included in each file's recipients list. Use `sops updatekeys <file>` to update a single file; sops must be able to decrypt the file locally (for example by having a private key available or by setting `SOPS_AGE_KEY_FILE`).
 >
 > Examples:
 >
@@ -218,8 +218,8 @@ This instructs the generated Nix expression to reference the secret name (which
 
 ## Common pitfalls & troubleshooting
 
-- Never commit private keys. Only public age recipients belong in `.sops.yaml`.
+- Never commit private keys. Only public age recipients belong in *[.sops.yaml](.sops.yaml)*.
 - If sops fails to encrypt/decrypt locally, check that you have the corresponding private key available and `SOPS_AGE_KEY_FILE` points to it when running from a shell that cannot otherwise find it.
-- `path_regex` in `.sops.yaml` is matched relative to the repo root - use it carefully so creation rules apply where expected.
-- If `sops.age.generateKey` is enabled and you rely on the module to generate keys, remember you must register the generated public recipient in the repo `.sops.yaml` after first activation. Extract the `age1...` line with one of the commands above and add it to `keys:` and the appropriate `creation_rules`.
+- `path_regex` in *[.sops.yaml](.sops.yaml)* is matched relative to the repo root - use it carefully so creation rules apply where expected.
+- If `sops.age.generateKey` is enabled and you rely on the module to generate keys, remember you must register the generated public recipient in the repo *[.sops.yaml](.sops.yaml)* after first activation. Extract the `age1...` line with one of the commands above and add it to `keys:` and the appropriate `creation_rules`.
 - If the Nix module expects the private key at `/var/lib/sops-nix/key.txt`, make sure that is where the key is placed on the target end system and that ownership/mode are correct for the system service that reads it.