update

AGENTS.md

@@ -0,0 +1,39 @@
+# Repository guidance
+
+Read `README.md` before changing startup flow, file ownership or repository
+boundaries.
+
+## Scope
+
+- This repository owns the Bash login sequence and the complete interactive
+  Bash experience: prompt, history, completion, aliases, functions, reminders
+  and interactive integrations.
+- The `profile` repository owns only the portable login environment.
+- The `systemd` repository owns user services, timers and background work.
+- Keep Arch-specific interactive behavior in `platform/arch.sh`.
+
+## Change rules
+
+- Preserve the ordered, single-purpose modules under `bashrc.d/`.
+- Keep shell startup responsive. Do not add synchronous network access, package
+  database synchronization or other slow background checks to startup.
+- Preserve the cached package-status interface documented in `README.md` unless
+  all producers, consumers and documentation are deliberately updated together.
+- Keep `commands.tsv` and `memory.tsv` tab-separated, headerless and free of
+  comments; follow their corresponding README files.
+- Do not edit the vendored `gitstatus/` tree as part of ordinary configuration
+  work.
+- Update `README.md` when startup behavior, ownership or module responsibilities
+  change.
+- Do not install packages, run system upgrades or change live systemd unit state
+  unless the user explicitly requests it.
+
+## Validation
+
+- Run `bash -n` on Bash entrypoints and `bashrc.d/*.bash`.
+- Run `sh -n` on files intentionally kept in portable shell syntax.
+- Run ShellCheck where available and distinguish actionable findings from
+  expected dynamic-source warnings.
+- For startup changes, use an isolated interactive Bash subprocess and confirm
+  the relevant aliases and functions load without modifying the current shell.
+- Run `git diff --check` before finishing.