# Bash configuration

This repository owns configuration that is specific to interactive Bash and
the Bash login sequence.

## Responsibilities

- Install `~/.bash_profile` and `~/.bashrc` as symlinks into this repository.
- Make login Bash load the shared `~/.profile` environment before `.bashrc`.
- Configure Bash history, prompt rendering, completion and command-not-found
  behaviour.
- Initialize Bash integrations such as NVM, Pyenv, z.lua and gitstatus.
- Own interactive aliases, functions and their curated command catalogue.
- Isolate Arch-specific interactive commands from general Bash configuration.
- Display the startup greeting and cached package status.
- Display `TODO.md` and `.autonote.md` after successful directory changes.

## Boundaries

This repository does not own:

- Portable login environment variables or shared PATH construction. Those
  belong in the `profile` repository.
- User services, timers or background refresh logic. Those belong in the
  `systemd` repository. Bash may consume their cached output or request a
  non-blocking service start.
- Secrets, machine credentials or project-specific environment settings.

## Startup flow

A login Bash reads:

```text
~/.bash_profile -> ~/.profile -> ~/.bashrc
```

A non-login interactive Bash reads only `~/.bashrc` and inherits the login
environment from its parent process. `.bashrc` returns immediately when the
shell is not interactive.

## Files

- `bash_profile`: connects Bash login startup to the shared profile and Bash RC.
- `bashrc`: interactive guard and ordered module loader.
- `bashrc.d/`: numbered interactive Bash modules; lower numbers load first.
- `interactive.sh`: loads interactive aliases, functions and reminders.
- `aliases.sh`: general interactive aliases and functions, written portably.
- `aliases.bash`: aliases requiring Bash-specific naming or behaviour.
- `commands.sh`: command-catalogue display and validation functions.
- `commands.tsv`: curated command descriptions and reminder visibility.
- `commands.README.md`: format and maintenance instructions for the catalogue.
- `hosts.sh`: SSH destination listing function.
- `memory.tsv`: curated daily shell-memory questions and answers.
- `memory.README.md`: memory-bank format and selection behaviour.
- `platform/arch.sh`: Arch-specific applications and system integration.
- `gitstatus-custom.sh`: prompt integration for gitstatus.
- `cheat.bash`: completion for `cheat`.
- `install.sh`: installs the home-directory symlinks and gitstatus dependency.

Run `install.sh` when initially installing the repository. It preserves an
existing destination before creating each symlink.

## Bash RC modules

The loader sources every readable `bashrc.d/*.bash` file in lexical order:

- `00-core.bash`: colors, history, terminal and Readline settings.
- `10-prompt.bash`: prompt, gitstatus and per-command history flushing.
- `20-greeting.bash`: calendar-day greeting and adjective selection.
- `30-integrations.bash`: interactive commands, NVM and z.lua.
- `40-status.bash`: command reminders, memory and cached package status.
- `50-completions.bash`: command-specific completion setup.
- `60-directory-notes.bash`: `TODO.md` and `.autonote.md` display after `cd`.
- `70-development.bash`: OpenCode and Pyenv initialization.
- `90-memory-question.bash`: persisted shuffled question deck, `answerpls` and
  on-demand `refreshpls` rotation.

Keep cross-module dependencies explicit through this numbering. New modules
should own one coherent area rather than becoming another general-purpose RC.

## Package-status integration

`40-status.bash` is a read-only consumer of the package cache at
`~/.cache/package-status/status`. It never runs Pacman or synchronizes package
databases during shell startup. When the cache is missing, stale or predates a
local package transaction, Bash requests a non-blocking start of
`package-status-refresh.service`, subject to a five-minute retry backoff.

The refresh service and 30-minute timer are owned and documented by the
`systemd` repository. The Arch `update` wrapper in this repository also
requests a refresh after a successful upgrade.