From 2b0f01d99c416da9be7d5948b7593b515614a861 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?ryan4yin=20=7C=20=E4=BA=8C=E8=8A=B1?= Date: Fri, 2 Oct 2026 11:16:24 +0800 Subject: [PATCH] chore(agents): workspace layout, related repositories, and ~/src checkouts (#340) * docs(skills): point nix-config-secrets at the private repo under ~/codes Record where the private nix-secrets checkout lives and that agents should do the mechanical secret work themselves, handing back only the interactive/sudo agenix operations and pushes. * docs(agents): add related repositories to nix-config * chore(agents): adopt ~/src for source checkouts Move third-party/source checkouts from ~/codes/src to ~/src so the home layout reads as three siblings: ~/codes (personal), ~/work (work), ~/src (checkouts). Preserve and back up the new path, and update the global rule and the two nixpkgs skill references. * docs(agents): tighten the code layout rule * docs(agents): fold the work-confidentiality note into the layout line * docs(agents): base the confidentiality rule on repo visibility * docs(agents): drop the stale KubeVirt mention --- .agents/skills/nix-config-secrets/SKILL.md | 22 ++++++++++++---------- .agents/skills/nixpkgs-patched/SKILL.md | 2 +- .agents/skills/nixpkgs-review/SKILL.md | 6 +++--- AGENTS.md | 15 +++++++++++++++ agents/AGENTS.md | 7 ++++--- hosts/idols-ai/preservation.nix | 3 ++- hosts/idols-ai/restic.nix | 1 + 7 files changed, 38 insertions(+), 18 deletions(-) diff --git a/.agents/skills/nix-config-secrets/SKILL.md b/.agents/skills/nix-config-secrets/SKILL.md index feabdd26..8f77d82d 100644 --- a/.agents/skills/nix-config-secrets/SKILL.md +++ b/.agents/skills/nix-config-secrets/SKILL.md @@ -7,9 +7,10 @@ description: # Working with secrets -Secrets are age-encrypted files in a separate private repository (`nix-secrets`), pulled in as the -`mysecrets` flake input and declared here in `secrets/nixos.nix` and `secrets/darwin.nix`. No secret -value is ever stored in this repository. +Secrets are age-encrypted files in the private repository `~/codes/nix-secrets` +(`git@github.com:ryan4yin/nix-secrets.git`), pulled in as the `mysecrets` flake input and declared +here in `secrets/nixos.nix` and `secrets/darwin.nix`. No secret value is ever stored in this +repository. Read [secrets/README.md](../../../secrets/README.md) for the private-repository workflow and the recipient rule. @@ -37,7 +38,7 @@ recipient rule. | Piece | Location | | --------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Recipient list, encrypted files, `agenix` CLI | the private `nix-secrets` repository | +| Recipient list, encrypted files, `agenix` CLI | `~/codes/nix-secrets` (private; `git@github.com:ryan4yin/nix-secrets.git`) | | The pinned revision of that repository | `flake.lock`, input `mysecrets` | | Declaration: file, mode/owner, `/etc` copy | `secrets/nixos.nix`, `secrets/darwin.nix` | | Which host gets which group | `modules.secrets..enable` in `outputs//src/.nix` or a host module | @@ -46,13 +47,14 @@ recipient rule. ## 2. Add or change a secret -These steps are user-run unless the user explicitly authorizes that exact operation and target: -editing the private repository, `agenix -e`/`-r` (interactive, and they handle key material), -anything under `sudo`, and the push. +Do the mechanical work yourself: edit `secrets.nix` in `~/codes/nix-secrets`, run the +non-interactive steps, bump the lock, and add the declaration and consumer. Hand back only what +needs a human: `sudo agenix -e`/`-r` (interactive, and they handle key material) and anything else +under `sudo`. Commits and pushes follow the global git rules. -1. In the private repository, on a desktop: add the file to `secrets.nix` with the recipient set - from core rule 3, create or edit it with - `sudo agenix -e ./xxx.age -i /etc/ssh/ssh_host_ed25519_key`, commit, and push. +1. In `~/codes/nix-secrets`, add the file to `secrets.nix` with the recipient set from core rule 3. + Then ask the user to create or edit it on a desktop: + `sudo agenix -e ./xxx.age -i /etc/ssh/ssh_host_ed25519_key`. 2. Here: `just upp mysecrets` (commits the lock) or `nix flake update mysecrets` (leaves it for you to commit). `git diff flake.lock` should show only `mysecrets` moving. 3. Declare it in `secrets/nixos.nix` or `secrets/darwin.nix` under the right diff --git a/.agents/skills/nixpkgs-patched/SKILL.md b/.agents/skills/nixpkgs-patched/SKILL.md index efdc14bc..bd01d507 100644 --- a/.agents/skills/nixpkgs-patched/SKILL.md +++ b/.agents/skills/nixpkgs-patched/SKILL.md @@ -35,7 +35,7 @@ those names; do not infer a remote from its position in the remote list. ## 2. Refresh the patched branch -Do this in the nixpkgs checkout (`~/codes/src/nixpkgs`), preserving any existing work: +Do this in the nixpkgs checkout (`~/src/nixpkgs`), preserving any existing work: 1. Save a rollback ref to the current patched tip. 2. Align the branch with the current `upstream/nixos-unstable`. diff --git a/.agents/skills/nixpkgs-review/SKILL.md b/.agents/skills/nixpkgs-review/SKILL.md index 38e4d4fd..d47d7527 100644 --- a/.agents/skills/nixpkgs-review/SKILL.md +++ b/.agents/skills/nixpkgs-review/SKILL.md @@ -60,9 +60,9 @@ downloads, so use them only when you want that extra pass. ## 2. Run locally first -From a full, non-shallow nixpkgs checkout (for example `~/codes/src/nixpkgs`); a shallow clone -fails. A source hash for another platform cannot be verified by evaluation on this Linux host, so -build it through the GHA workflow or leave it unchecked rather than claiming it is covered. +From a full, non-shallow nixpkgs checkout (for example `~/src/nixpkgs`); a shallow clone fails. A +source hash for another platform cannot be verified by evaluation on this Linux host, so build it +through the GHA workflow or leave it unchecked rather than claiming it is covered. ```bash nix run 'nixpkgs#nixpkgs-review' -- pr diff --git a/AGENTS.md b/AGENTS.md index cd800b49..d73270b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,21 @@ is discovered by OpenCode and compatible tools. - [`.agents/skills/nixpkgs-patched/SKILL.md`](./.agents/skills/nixpkgs-patched/SKILL.md) — carrying selected unmerged nixpkgs changes through the personal patched fork safely. +## Related Repositories + +When a change here affects one of these, make both edits in the same task, one branch or PR per +repository, and cross-link them — no need to be told. + +- `~/codes/k8s-gitops` — Flux cluster state for the k3s cluster whose hosts are defined in + `hosts/k8s` and `hosts/12kingdoms-youko` (NFS golden store, kube-vip block, `br0`). Host + networking, VM images, or cluster addons usually change both repositories together. +- `~/codes/containers` — container images consumed by k8s-gitops; a tag bump is often a two-repo + change. +- `~/codes/nix-secrets` — agenix files and recipients for secrets declared here (see the + `nix-config-secrets` skill). +- `wallpapers`, `nur-packages`, `pyclipsync`, `nu_scripts` — flake inputs; bump with + `just upp ` after their source changes, do not edit them from here. + ## Further Context - [Repository overview](./README.md) diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 422503d8..3a8ac1b9 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -121,9 +121,10 @@ For an impactful change, follow these steps in order, scaled to its risk: for one-off tools, and the project's existing toolchain (e.g. its flake, `uv`, `pnpm`) for its dependencies; ask before creating a flake or installing another way. - Use `gh` for authorized GitHub operations; keep SSH for GitHub Git remotes. -- Upstream source checkouts (nixpkgs and similar) live under `~/codes/src/`. Before reading a - lot of upstream source, check there first; if the checkout exists, `git pull` it and read it - locally instead of relying only on the GitHub API or making a fresh clone. +- Code layout: `~/codes` = personal, `~/work` = work code, `~/src/` = source checkouts. +- Publish only to repositories that are already public; treat everything else as confidential. +- For upstream source, prefer an up-to-date `~/src/` checkout over the GitHub API or a fresh + clone. ### Tool execution diff --git a/hosts/idols-ai/preservation.nix b/hosts/idols-ai/preservation.nix index a9bd9c66..bbb920a0 100644 --- a/hosts/idols-ai/preservation.nix +++ b/hosts/idols-ai/preservation.nix @@ -116,7 +116,8 @@ in # Codes / Work / Playground # ====================================== "codes" # for personal code - "work" # for work contains a .gitconfig with my work email. + "work" # work code tree + "src" # third-party source checkouts "nix-config" "tmp" diff --git a/hosts/idols-ai/restic.nix b/hosts/idols-ai/restic.nix index 2cb11b7d..8def7767 100644 --- a/hosts/idols-ai/restic.nix +++ b/hosts/idols-ai/restic.nix @@ -25,6 +25,7 @@ "/home/ryan/work" "/home/ryan/Pictures" "/home/ryan/codes" + "/home/ryan/src" "/home/ryan/nix-config" "/home/ryan/.local/state" ];