# 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.