From 2d8c7d14794c0ea6c046fb8aae214bc0e8fe76be Mon Sep 17 00:00:00 2001 From: File Magic Date: Fri, 17 Jul 2026 01:15:14 +0000 Subject: [PATCH] AGENTS.md: add cluster-state.md as desired-state source of truth --- AGENTS.md | 4 +++- 1 file(s) changed, 3 insertion(s)(+), 1 deletion(s)(-) diff --git a/AGENTS.md b/AGENTS.md --- a/AGENTS.md +++ b/AGENTS.md @@ -76,7 +76,8 @@ ## Doc purposes (single source of truth per type) | Doc | Purpose | What goes here | What does NOT go here | |-----|---------|---------------|----------------------| -| `resume-state.md` | Cluster state snapshot | What's running, node list, git commits, known issues (facts only), SSH/tofu commands | Debugging explanations, root cause analysis, lengthy how-tos | +| `cluster-state.md` | Desired cluster state | What *should* be running: node count, IP allocation, component versions, expected Helm charts, expected NixOS config, expected security posture. Source of truth for "is this cluster correct?" | Debugging notes, historical changes, actual-vs-desired comparison results | +| `resume-state.md` | Cluster state snapshot | What *is* running right now: node list, git commits, known issues (facts only), SSH/tofu commands | Debugging explanations, root cause analysis, lengthy how-tos | | `security-hardening.md` | Security changes + verification | What was changed and why, verified test results, security posture summary, debugging techniques, useful links | Duplicated component state (reference `resume-state.md` instead) | | `debugging.md` | Debugging notes | Root cause analysis, investigation techniques, fix details, infrastructure commands (OVMF, virsh, rebuild cycles) | State snapshots, security posture | | `session-state-YYYY-MM-DD.md` | Historical session log | What was changed in this session, design decisions, commits made | Full cluster state, duplicated debugging fixes (reference `debugging.md`) | @@ -85,6 +86,7 @@ | `AGENTS.md` | Agent behavior rules | How to work in this repo (commit style, DRY, testing, docs) | Project-specific technical details | ## When to add more documentation +- **Cluster state changes:** Update `cluster-state.md` whenever the desired cluster topology, components, or configuration changes. This is the source of truth for what the cluster *should* look like. - **New feature or component:** Create a new doc (e.g., `networking.md`, `monitoring.md`) when a feature is complex enough to need its own workflow, commands, or gotchas. Don't cram everything into `security-hardening.md`. - **New debugging technique:** Add to `debugging.md` under a `## Section Name` heading with a `---` separator. - **New security change:** Add to `security-hardening.md` under `## Changes Made` with What/Why/Test/Verify format. -- tangled.sh