From efe5beac3dbfabdbae81df06a0385ad6217fe7fe Mon Sep 17 00:00:00 2001
From: Poby <87608318+smg1024@users.noreply.github.com>
Date: Thu, 26 Mar 2026 21:28:41 +0900
Subject: [PATCH] docs: update agent guidance for dendritic layout

---
 AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 41 insertions(+), 20 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 8b218e8..2135d55 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,18 +2,26 @@
 
 ## Project Structure & Module Organization
 
-This repository is a declarative macOS setup built with Nix flakes.
+This repository is a declarative macOS setup built with Nix flakes, `flake-parts`,
+and a dendritic aspect layout.
 
-- `flake.nix` and `flake.lock`: entrypoint and pinned inputs.
-- `modules/`: system-level nix-darwin modules (`nix-core.nix`, `system.nix`,
-  `apps.nix`, `host-users.nix`).
-- `home/`: Home Manager user configuration, with feature modules such as
-  `git.nix`, `zsh.nix`, and `nvf/`.
-- `secrets/`: encrypted SOPS files (for example `secrets/poby.yaml`).
+- `flake.nix` and `flake.lock`: flake entrypoint and pinned inputs.
+- `modules/flake/`: flake assembly, repo options, shared context modules, and
+  `darwinConfigurations` generation.
+- `modules/aspects/`: public aspect entry modules auto-discovered with
+  `import-tree`. Each aspect may expose `flake.modules.darwin.<feature>` and/or
+  `repo.homeModules.<feature>`.
+- `modules/aspects/_*/`: private implementation trees intentionally excluded
+  from `import-tree`. Import these manually from the owning aspect to keep each
+  feature plug-and-play and in control of its own composition surface.
+- `hosts/`: auto-discovered host declarations that register
+  `repo.hosts.<hostname>.system` and a flat `features` list.
+- `secrets/` and `.sops.yaml`: encrypted SOPS files and path rules.
 - `Justfile`: day-to-day contributor commands.
 
-Prefer adding new configuration as small focused modules, then importing them
-from `home/default.nix` or `flake.nix`.
+Prefer adding a new focused aspect in `modules/aspects/` and keeping host files
+thin. Put reusable internals under a sibling `_/` tree and wire them in
+explicitly from the public aspect entry module.
 
 ## Build, Test, and Development Commands
 
@@ -21,34 +29,45 @@ Use `just` as the primary interface:
 
 - `just darwin <hostname>`: build and switch to the current host (ex: `fenrir`).
 - `just darwin-debug <hostname>`: same as above with verbose trace output.
-- `just fmt`: format all Nix files via `nix fmt` (Alejandra).
+- `just fmt .`: format Nix files from the repository root via `nix fmt`
+  (Alejandra).
 - `just up`: update all flake inputs.
-- `just upp <input>`: update one input (example: `just upp nixpkgs-darwin`).
-- `just history`, `just gc`, `just clean`: inspect and prune Nix
+- `just upp <input>`: update one input (example: `just upp nixpkgs`).
+- `just history`, `just clean`, `just gc`: inspect and prune Nix
   generations/store.
 
 For validation without switching, run:
 `nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'`.
 
+For dependency-graph validation without realizing a full build, run:
+`nix build .#darwinConfigurations.fenrir.system --dry-run --extra-experimental-features 'nix-command flakes'`.
+
 ## Coding Style & Naming Conventions
 
 - Use 2-space indentation in `.nix` files and keep attribute sets readable.
-- Run `just fmt` before committing; formatter is defined in `flake.nix`
+- Run `just fmt .` before committing; formatter is defined in `flake.nix`
   (`alejandra`).
-- Name module files in lowercase kebab-case (example: `host-users.nix`).
-- Keep modules single-purpose and compose through `imports`.
+- Name aspect and helper files in lowercase kebab-case.
+- Keep public aspect filenames aligned with the feature names referenced from
+  `repo.hosts.<hostname>.features`.
+- Keep host files declarative and small: they should select features, not carry
+  large implementation blocks.
+- Use `imports` inside private `_*/` trees to compose internals, but expose the
+  aspect itself through one public entry module in `modules/aspects/`.
 
 ## Testing Guidelines
 
 There is no dedicated unit-test suite in this repo. Treat evaluation/build as
 the test gate:
 
-- Run `just fmt`.
+- Run `just fmt .`.
 - Run `nix build .#darwinConfigurations.fenrir.system`.
-- Use `just darwin-debug` when diagnosing evaluation/runtime issues.
+- Use `nix build .#darwinConfigurations.fenrir.system --dry-run` for a quick
+  validation pass when you only need evaluation and dependency resolution.
+- Use `just darwin-debug <hostname>` when diagnosing evaluation/runtime issues.
 
 Document manual verification for user-facing changes (shell, terminal, window
-manager, app defaults).
+manager, app defaults, Homebrew behavior).
 
 ## Commit & Pull Request Guidelines
 
@@ -65,5 +84,7 @@ Commit history follows Conventional Commit style: `feat:`, `fix:`, `refactor:`,
 
 - Never commit plaintext secrets.
 - Store secrets only in `secrets/*.yaml` and manage keys/rules in `.sops.yaml`.
-- If adding new secret files, ensure `path_regex` coverage and encrypted content
-  before pushing.
+- `.sops.yaml` currently matches `secrets/.*\.yaml$`; keep new secret files
+  within that pattern or update the rule before committing.
+- If adding new secret-backed modules, continue reading from encrypted files via
+  the `secrets` aspect rather than hardcoding credentials into aspect modules.