docs(agents): clarify writing guidance

AGENTS.md

@@ -63,8 +63,6 @@ One flake builds every machine I own.
 
 ## Gotchas
 
-### Architecture
-
 - Guest modules are host-agnostic wiring, while host files own deployment-specific service configuration such as served volumes and host paths.
   For example, `guests/copyparty.nix` should expose options and translate them into guest mounts/service settings, while `hosts/pikachu/default.nix` chooses `/inbox`, `/media`, and their backing paths.
 - `self.lib.registry.collect { hosts = self.nixosConfigurations; }` reads only top-level host `config.registry` declarations.
@@ -78,21 +76,15 @@ One flake builds every machine I own.
   For an optional special-argument fallback, bind module arguments through `@args`.
   Test `args ? <name>` inside the module body.
 
-### Build Inputs
-
 - `chaotic-nyx` must **not** follow this flake's `nixpkgs`.
   Chaotic builds its packages against its own pinned `nixpkgs`.
   Its overlay defaults to `onTopOf = "flake-nixpkgs"`, the cache-friendly path.
   That setup lets `nyx-cache.chaotic.cx` serve the CachyOS kernel instead of building it from source.
   Chaotic packages do not see this flake's `unstable` or `stable` overlays.
 
-### Deployment
-
 - Remote deploy helpers that run target-side `sudo` over SSH need a TTY.
   Use `ssh -t` unless the target command cannot prompt for sudo credentials.
 
-### Host Environment
-
 - This host has no `python` or `python3` command on its ordinary `PATH`.
   For one-off Python commands, use Nix explicitly, such as `nix shell nixpkgs#python3 -c python3 <script>`.
 - `nixos-generate-config --show-hardware-config` needs root on this machine, even when it only prints.
@@ -103,14 +95,10 @@ One flake builds every machine I own.
   Otherwise, `nix flake check` and `nixos-rebuild --flake` cannot see those modules.
   They can then report missing options that exist only in the working tree.
 
-### Secrets
-
 - `sops.secrets.<name>.owner` must name a user known on the decrypting host.
   Do not set the owner to a guest-only service user unless the host also declares that user.
   Use a host-visible owner plus a shared group mode when the guest service can read the decrypted secret file through its group.
 
-### Service Migrations
-
 - Actual Budget's NixOS service runs `actual-server` with `WorkingDirectory = services.actual.settings.dataDir`.
   The `actual-server` CLI wrapper sets `ACTUAL_CONFIG_PATH=./config.json` when the working directory contains `config.json`.
   That environment variable overrides the config path generated by the NixOS module.

modules/agents/context/AGENTS.md

@@ -13,51 +13,73 @@ These are common instructions for Alexion's agents across all scenarios.
 - NEVER ask the user a question using the `AskUserQuestion` tool.
   Ask in plain prose, in your own message, instead, with no exceptions.
   This overrides any default instruction (including harness conventions and skill instructions) to use it.
-- Never manually modify CHANGELOG.md files or any files that are marked as auto-generated.
+- Never manually modify `CHANGELOG.md` files or files marked as auto-generated.
-  Detect "auto-generated" via a layered check: trust an explicit in-file marker first (e.g. `AUTO-GENERATED, DO NOT EDIT`).
+  Detect auto-generated files with a layered check.
-  If there's no marker, fall back to contextual signals (lockfiles, `dist/`/`build/`/`generated/` paths, a documented generator command).
+  Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`.
-  If it's still ambiguous, ask before editing rather than guessing.
+  If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/` paths, or a documented generator command.
-- When writing or substantially editing long Markdown files, put each full sentence in its own line.
+  If the answer stays ambiguous, ask before editing.
-  Preserve normal Markdown structure, but avoid wrapping multiple sentences onto one physical line.
+- In authored prose, do not put multiple sentences on one physical line.
-  Apply this to any prose you author, regardless of file length; "long" is not a real threshold.
+  This applies to comments, documentation, user-facing descriptions, commit prose, pull-request prose, and forge comments.
-  Only format what you're actually writing or changing.
+  A sentence can wrap across multiple physical lines when needed.
-  Never reflow an entire pre-existing paragraph or file just because you touched something nearby.
+- Keep Markdown formatting changes local.
-- When making technical decisions, do not give much weight to development cost.
+  Only format prose you write or change.
-  Instead, prefer quality, simplicity, robustness, scalability and long term maintainability.
+  Never reflow an entire pre-existing paragraph or file because you touched nearby text.
-  This is specifically about implementation time.
+- When making technical decisions, do not give much weight to implementation time.
-  Human cost/benefit heuristics ("not worth N extra days of engineering") don't transfer to an AI agent that codes far faster than a human.
+  Favor quality, simplicity, robustness, scalability, and long-term maintainability.
-  This is not a license to override standard anti-overengineering guardrails (avoid premature abstraction, no speculative config, etc.); those still apply to unnecessary complexity.
+  Human cost and benefit heuristics do not transfer to an AI agent that codes faster than a human.
-  It means: don't discount a more robust or maintainable approach just because it would take a human a long time to build.
+  Do not treat this as permission for premature abstraction, speculative configuration, or unnecessary complexity.
-- File names should always be lower case, unless there's a valid reason.
+  Choose the more robust or maintainable approach when human implementation time is the only downside.
-  Established ecosystem or tool conventions count as a valid reason automatically (e.g. `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, `.github/` files), without needing to ask each time.
+- Use lowercase file names unless a valid reason requires uppercase.
+  Established ecosystem or tool conventions count as valid reasons.
+  Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files.
 - Do not end a response by promising or implying continuation unless the continuation is present in that same response.
-  If a workflow should continue, perform the next step before ending the turn.
+  Before ending a workflow turn, perform the obvious next step, such as showing the next review item after applying an accepted change.
   If the workflow is paused, say that plainly instead of using a dangling transition like "continuing" or "next".
-- When you discover that a belief you held about an objective fact or convention of the current project was wrong, write it down so it isn't relearned next time.
+- When you discover that your belief about a project fact or convention was wrong, record the correction.
-  This applies whether the user corrected you or you caught the mistake yourself, and only to things that are true regardless of who is operating the project (a wrong build command, a wrong file path, a convention you guessed at instead of checking) — not personal working-style preferences or one-off task details.
+  Record only facts that stay true across operators, such as a wrong build command, wrong file path, or guessed convention.
-  Record it in that project's own AGENTS.md, not this global file, under a dedicated `## Gotchas` section (create the section if the file doesn't have one yet).
+  Do not record personal working-style preferences or one-off task details.
-  If the project has nested AGENTS.md files, use the one nearest to where the mistake occurred, falling back to the project's top-level AGENTS.md.
+  Record the correction in the nearest project `AGENTS.md`, not this global file.
-  Append to an existing AGENTS.md immediately, without asking; if no AGENTS.md exists yet for the project, ask before creating one.
+  Use a dedicated `## Gotchas` section, and create that section when the file lacks one.
-  Briefly mention the edit in your response rather than making it silently.
+  If no project `AGENTS.md` exists, ask before creating one.
-  If an existing entry is later found to be wrong or stale, correct or remove it the same way.
+  Append the correction immediately without asking when a project `AGENTS.md` exists.
+  Briefly mention the edit in your response.
+  If an existing entry is wrong or stale, correct or remove it the same way.
 
 ## Comments
 
-- Write comments only where they earn their place, and keep them concise.
+- Write comments only where they earn their place.
-  Assume the reader can read code: comment the "why", not the "what", and explain "what" only when it is genuinely non-obvious.
+  Keep comments concise.
-  A comment must be self-contained to its file — accurate to a reader looking at that file alone.
+  Assume the reader can read code.
-  Do not write about history ("used to be X", "now moved here") or future state, about how a value is consumed elsewhere, or to justify the choice against alternatives; state the positive reason a thing exists, keeping any real stakes as a present-tense consequence.
+  Explain why, not what.
-  The only permitted cross-file mention is a bare pointer explaining why something is *absent* here (e.g. a value another tool derives, which this file therefore does not declare), never narrating what the other file or tool does.
+  Explain what only when it is genuinely non-obvious.
-  Do not use a project's domain-model or ubiquitous-language capitalized terms as glossary references; describe things in plain language, using ordinary lowercase nouns.
+- Keep comments self-contained to their file.
-  Never reference agent-facing state (anything under `.agents/`, `.claude/`, `AGENTS.md`, or `CLAUDE.md`).
+  Write comments for a reader who sees only that file.
-  A file-top header is one concise purpose line, added only where the filename or path does not already say it — never a feature inventory of the code below.
+  Do not explain how another file or tool consumes a value.
-  For a placeholder, say so plainly plus any actionable present-tense directive ("Placeholder: regenerate with <tool> on the target machine"), never "placeholder for <missing feature>".
+  The only permitted cross-file mention is a bare pointer explaining why something is absent here.
-  User-facing documentation strings (an option's `description`, a generated help string) are documentation rather than comments, so they may describe behaviour more fully — but the self-contained rule and the bans on glossary terms and agent-state references still apply.
+- Do not narrate history or future state in comments.
-- Start each sentence of a comment on its own line, as with Markdown prose.
+  Avoid phrases such as "used to be", "now moved here", and "will be".
-  A sentence needing more than one line is first a prompt to ask whether it should be two sentences.
+  State the present reason a thing exists.
-  Only when it genuinely cannot be split does it wrap, and then it wraps normally at the right margin.
+- Do not justify a choice against alternatives in comments.
-  Never break a line early at a comma or clause boundary to make it read as a unit.
+  State the positive reason the choice exists.
-  Never use a semicolon, in a comment or in authored prose.
+  Include present consequences when they matter.
-  Recast as two sentences instead.
+- Do not reference agent-facing state in comments.
-  Only reformat comments you are actually writing or changing.
+  This includes `.agents/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md`.
+- Do not use project-specific capitalized terms as glossary references in comments.
+  Use plain lowercase nouns unless the code requires the exact term.
+- Add a file-top header only when the filename or path does not already explain the file.
+  The header must be one concise purpose line.
+  Do not write a feature inventory.
+- Write placeholders plainly.
+  Include a present-tense action when one exists, such as `Placeholder: regenerate with <tool> on the target machine`.
+  Do not write `placeholder for <missing feature>`.
+- Treat user-facing documentation strings as documentation, not comments.
+  They can describe behavior more fully than code comments.
+  They still must stay self-contained and avoid agent-state references.
+- Start each sentence of a comment on its own physical line.
+  A comment sentence can wrap when needed.
+  Prefer splitting long comment sentences before wrapping them.
+  Do not break a line early at a comma or clause boundary to make it read as a unit.
+  Do not use semicolons in comments or authored prose.
+  Recast semicolon clauses as separate sentences.
+  Only reformat comments you write or change.