update

README.md

@@ -0,0 +1,51 @@
+# 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.
+- Display the startup greeting and cached package status.
+- Display `TODO.md` and `.autonote.md` after successful directory changes.
+- Load common interactive aliases from the `profile` repository.
+
+## Boundaries
+
+This repository does not own:
+
+- Portable login environment variables or shared PATH construction. Those
+  belong in the `profile` repository.
+- Common aliases intended for more than one Bourne-family shell. Those belong
+  in `profile/aliases.sh`; genuinely Bash-specific aliases may live here.
+- 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 Bash configuration.
+- `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.