8 files changed, 129 insertions, 0 deletions

diff --git a/README.md b/README.md
index c69c28c..e32f0e8 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ A single Nix flake for provisioning both NixOS hosts and non-NixOS systems (any
 - `hosts/template/` — a copy-source-only NixOS host skeleton; **never** wired into `flake.nix` outputs directly (excluded from discovery by name — see below). Copy it via `scripts/bootstrap-host.sh` (or `nix run .#bootstrap-host`) when provisioning a real machine
 - `scripts/bootstrap-host.sh` — scaffolds a new `hosts/<hostname>/` from the template; exposed as `apps.<system>.bootstrap-host`
 - `modules/home/dotfiles.nix` — opt-in personal dotfiles automation (see below)
+- `modules/home/bash-profile.nix` — always-on `~/.bash_profile` bootstrap (see below)
 
 Any directory under `hosts/` other than `hosts/template` that contains a `system` file automatically becomes a real `nixosConfigurations.<name>` output — adding a host means dropping in a directory, not editing `flake.nix`.
 
@@ -59,6 +60,10 @@ home.dotfiles.repoUrl = "https://example.com/your/dotfiles.git";
 
 Behavior notes: an existing `~/dotfiles` checkout is never re-cloned or modified; every non-hidden top-level directory is treated as a stow package; one package's conflict with an existing file only skips that package (a warning is printed) rather than blocking the rest. Because `~/dotfiles/git/.gitconfig` and `~/dotfiles/bash/.bashrc` are expected to be the sole sources of git and bash configuration once stowed, this repo's own `programs.git`/`programs.bash` home-manager management has been removed — `git` itself is still installed via `modules/home/cli-tools.nix`, and `bash` ships with both macOS and NixOS regardless of whether `repoUrl` is set.
 
+## Login shell bootstrap
+
+NixOS and most other Linux distros don't ship a `~/.bash_profile` that sources `~/.bashrc`, so login shells never pick up your bash config. `modules/home/bash-profile.nix` creates one for you — but only if `~/.bash_profile` doesn't already exist. If it's already there (any file or symlink), it's left completely untouched; home-manager never edits or removes it. This is always on, on every platform (Linux and macOS), and isn't gated by `home.dotfiles.repoUrl` — it works whether or not you use the personal dotfiles automation above.
+
 ## Developer tooling
 
 `modules/home/dev-tools.nix` provisions the developer's most-used CLI tools: `gh`, `tmux`, `htop`, `yq-go`, `tree-sitter`, `docker`, `docker-compose`, `kubectl`, `awscli2`. The container/cloud entries (`docker`, `docker-compose`, `kubectl`, `awscli2`) are client/CLI tools only — the actual container runtime (OrbStack/Docker Desktop on macOS) and any cloud account configuration stay outside Nix's control; these just give you a consistent CLI version to talk to whatever runtime/account is already set up.
diff --git a/modules/home/bash-profile.nix b/modules/home/bash-profile.nix
new file mode 100644
index 0000000..30114ba
--- /dev/null
+++ b/modules/home/bash-profile.nix
@@ -0,0 +1,21 @@
+{ config, lib, pkgs, ... }:
+let
+  bashProfileContent = pkgs.writeText "bash_profile" ''
+    # Written once by home-manager (modules/home/bash-profile.nix) so login
+    # shells actually source ~/.bashrc — NixOS and other Linux distros don't
+    # ship a ~/.bash_profile that does this by default. Only created if it
+    # didn't already exist; home-manager never touches it again after that,
+    # so it's yours to edit.
+    if [ -f "$HOME/.bashrc" ]; then
+      . "$HOME/.bashrc"
+    fi
+  '';
+in
+{
+  home.activation.bashProfile = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
+    BASH_PROFILE=${lib.escapeShellArg "${config.home.homeDirectory}/.bash_profile"}
+    if [ ! -e "$BASH_PROFILE" ]; then
+      $DRY_RUN_CMD ${pkgs.coreutils}/bin/install -m 644 ${bashProfileContent} "$BASH_PROFILE"
+    fi
+  '';
+}
diff --git a/modules/home/default.nix b/modules/home/default.nix
index 89bad9e..1653d3b 100644
--- a/modules/home/default.nix
+++ b/modules/home/default.nix
@@ -1,6 +1,7 @@
 {
   imports = [
     ./shell.nix
+    ./bash-profile.nix
     ./editor.nix
     ./cli-tools.nix
     ./dotfiles.nix
diff --git a/openspec/changes/add-bash-profile-bootstrap/.openspec.yaml b/openspec/changes/add-bash-profile-bootstrap/.openspec.yaml
new file mode 100644
index 0000000..563fab5
--- /dev/null
+++ b/openspec/changes/add-bash-profile-bootstrap/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-21
diff --git a/openspec/changes/add-bash-profile-bootstrap/design.md b/openspec/changes/add-bash-profile-bootstrap/design.md
new file mode 100644
index 0000000..e6ff923
--- /dev/null
+++ b/openspec/changes/add-bash-profile-bootstrap/design.md
@@ -0,0 +1,30 @@
+## Context
+
+See proposal.md - Why. This sits alongside `modules/home/dotfiles.nix` (`dotfiles-management`) without depending on it — this new behavior fires regardless of whether `home.dotfiles.repoUrl` is set. A real, repo-unmanaged `~/.bash_profile` (containing a plaintext Homebrew token) was found on the user's macOS machine during an earlier change's exploration and explicitly flagged out of scope there; the exists-check in this change is what makes it safe to run this feature on that same machine, and on any other machine that already has its own `.bash_profile`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create `~/.bash_profile` (sourcing `~/.bashrc`) exactly once, only when it doesn't already exist.
+- Behave identically on every platform this flake targets, with no per-OS conditional.
+
+**Non-Goals:**
+- Managing the contents or ownership of `~/.bashrc` itself — that remains entirely owned by the external dotfiles repo, unchanged by this capability.
+- Reconciling or updating a `~/.bash_profile` that already exists, however it got there.
+
+## Decisions
+
+**New capability (`shell-login-bootstrap`) instead of a `dotfiles-management` delta.** `dotfiles-management`'s own Purpose and first requirement are specifically about the opt-in `home.dotfiles.repoUrl` clone-and-stow feature ("SHALL only run when a repository URL has been explicitly configured"). This new behavior is unconditional and fires identically whether or not that URL is ever set, so folding it in would contradict that capability's own framing rather than extend it.
+
+**A standalone `home.activation` script (`modules/home/bash-profile.nix`), not `programs.bash`.** `programs.bash` is deliberately not enabled anywhere in this repo (see the archived `add-developer-environment` design) because enabling it would make home-manager generate and own `~/.bashrc`, conflicting with the dotfiles-repo-owned `~/dotfiles/bash/.bashrc`. Reaching for `programs.bash.profileExtra` or similar would fight that existing setup, so this has to be a plain activation script writing a plain file directly, following the same `lib.hm.dag.entryAfter [ "writeBoundary" ]` idiom already used by `dotfiles.nix`.
+
+**`[ -e ]`, not `[ -f ]`, for the exists-check.** `-e` also matches an existing symlink (e.g. a future dotfiles-repo-provided `.bash_profile` package), so a symlink is never clobbered either — only true absence triggers the write.
+
+**`install -m 644` (GNU coreutils via `pkgs.coreutils`) instead of `cp` + `chmod`, and no temp-file-then-`mv` staging.** `install` sets content and permissions in one step, avoiding a GNU/BSD `install` behavior mismatch between Linux and macOS hosts. Temp-file staging was considered and rejected: this repo's only existing conditional-write precedent (`dotfiles.nix`'s `git clone`/`stow` calls) doesn't defend against partial writes either, activation scripts here run sequentially rather than concurrently, and the file is a few bytes — added complexity wasn't justified.
+
+**No ordering dependency between this activation script and `dotfiles.nix`'s.** `dotfiles.nix`'s activation entry only exists at all when `cfg.repoUrl != ""` (`lib.mkIf`-gated). A hard `entryAfter [ "dotfiles" ]` reference would leave the DAG edge dangling whenever the dotfiles feature is disabled — fragile for no benefit. Both possible race outcomes are already safe without any explicit ordering: if `dotfiles`'s stow step runs first and links a `.bash_profile` package, the `[ -e ]` check sees it and skips (the dotfiles-repo-owned file wins, consistent with the existing `.bashrc`/`.gitconfig` precedent); if this block runs first and creates the plain bootstrap file, and the dotfiles repo also ships a `.bash_profile` package, `stow` hits an occupied target and — per `dotfiles-management`'s existing "a conflicting package does not block the others" requirement — skips just that one package with a visible warning, without aborting. Accepted explicitly rather than engineered around.
+
+## Risks / Trade-offs
+
+- **A pre-existing, unmanaged `~/.bash_profile` (e.g. the one with a plaintext Homebrew token on the user's Mac) is left completely untouched, including if it's stale or wrong** → This is the explicit intent, not an oversight: the exists-check guard is a hard requirement precisely so this feature never touches a file it doesn't own.
+- **No local way to verify activation behavior since Nix isn't installed on this development machine** → Same constraint as every prior change in this repo; `nix flake check` and a real `home-manager switch` remain the acceptance gate.
diff --git a/openspec/changes/add-bash-profile-bootstrap/proposal.md b/openspec/changes/add-bash-profile-bootstrap/proposal.md
new file mode 100644
index 0000000..6991c2a
--- /dev/null
+++ b/openspec/changes/add-bash-profile-bootstrap/proposal.md
@@ -0,0 +1,22 @@
+## Why
+
+NixOS (and most other Linux distros) don't ship a `~/.bash_profile` that sources `~/.bashrc`, so login shells never pick up the user's bash config — only interactive non-login shells do. This repo made bash the primary managed shell in an earlier change (`add-developer-environment`), and the real `.bashrc` lives in the user's external dotfiles repo (`~/dotfiles/bash/.bashrc`, stowed to `~/.bashrc` by `modules/home/dotfiles.nix`), so this gap is real on any freshly provisioned machine.
+
+## What Changes
+
+- Add a new home-manager activation script that creates `~/.bash_profile` (sourcing `~/.bashrc` if present) only when `~/.bash_profile` does not already exist. An existing `~/.bash_profile`, in any form (regular file or symlink), is never modified.
+- Applies unconditionally on every platform this flake targets (Linux and macOS) — not gated by `home.dotfiles.repoUrl` — since the exists-check itself is what keeps it safe everywhere, including on a machine with an existing, repo-unmanaged `~/.bash_profile`.
+
+## Capabilities
+
+### New Capabilities
+- `shell-login-bootstrap`: ensures a login shell sources `~/.bashrc` via `~/.bash_profile`, creating that file only when it doesn't already exist, on every platform this flake targets.
+
+### Modified Capabilities
+(none — `dotfiles-management`'s existing "a conflicting package does not block the others" requirement already covers the rare case where a dotfiles-repo-provided `.bash_profile` package races against this file; no requirement of that capability changes)
+
+## Impact
+
+- Affected code: a new `modules/home/` module, registered in `modules/home/default.nix`'s imports; `README.md`'s documentation of the home-manager module layout and shell setup.
+- Applies to every `homeConfigurations`/`nixosConfigurations` output built from the shared home profile (both `tom@linux` and `tom@darwin`, plus any future NixOS host).
+- No change to `dotfiles.nix` or its behavior.
diff --git a/openspec/changes/add-bash-profile-bootstrap/specs/shell-login-bootstrap/spec.md b/openspec/changes/add-bash-profile-bootstrap/specs/shell-login-bootstrap/spec.md
new file mode 100644
index 0000000..37e236c
--- /dev/null
+++ b/openspec/changes/add-bash-profile-bootstrap/specs/shell-login-bootstrap/spec.md
@@ -0,0 +1,33 @@
+## Purpose
+
+Ensures a login shell actually loads the user's bash configuration, since NixOS and most other Linux distributions don't ship a `~/.bash_profile` that sources `~/.bashrc` by default — without ever touching a `~/.bash_profile` that already exists.
+
+## ADDED Requirements
+
+### Requirement: A missing `.bash_profile` is created to source `.bashrc`
+If no `~/.bash_profile` exists, home-manager activation SHALL create one whose contents source `~/.bashrc`.
+
+#### Scenario: No `.bash_profile` exists
+- **WHEN** activation runs and `~/.bash_profile` does not exist
+- **THEN** a `~/.bash_profile` is created that sources `~/.bashrc`
+
+### Requirement: An existing `.bash_profile` is never modified
+If `~/.bash_profile` already exists in any form (regular file or symlink), activation SHALL NOT create, overwrite, or otherwise modify it.
+
+#### Scenario: `.bash_profile` already exists
+- **WHEN** activation runs and `~/.bash_profile` already exists
+- **THEN** its contents are left completely unchanged, and no write is attempted
+
+### Requirement: The created file tolerates a missing `.bashrc`
+The generated `~/.bash_profile` SHALL only attempt to source `~/.bashrc` if that file exists, so it never errors on a login shell that runs before `~/.bashrc` is otherwise provisioned.
+
+#### Scenario: `.bashrc` does not exist yet
+- **WHEN** the generated `~/.bash_profile` runs and `~/.bashrc` does not exist
+- **THEN** it does nothing further and produces no error
+
+### Requirement: Behavior is identical on every platform this flake targets
+This capability SHALL apply unconditionally wherever the shared home-manager profile is activated — NixOS, standalone Linux, and macOS alike — gated only by whether `~/.bash_profile` already exists, not by operating system.
+
+#### Scenario: Activated on any supported platform
+- **WHEN** the shared home profile is activated on NixOS, standalone Linux, or macOS
+- **THEN** the same create-if-absent behavior for `~/.bash_profile` applies identically
diff --git a/openspec/changes/add-bash-profile-bootstrap/tasks.md b/openspec/changes/add-bash-profile-bootstrap/tasks.md
new file mode 100644
index 0000000..701d3f3
--- /dev/null
+++ b/openspec/changes/add-bash-profile-bootstrap/tasks.md
@@ -0,0 +1,15 @@
+## 1. Module
+
+- [x] 1.1 Create `modules/home/bash-profile.nix` with a `pkgs.writeText` block for the `.bash_profile` content and a `home.activation.bashProfile` script that creates it via `install -m 644` only when `${config.home.homeDirectory}/.bash_profile` does not exist (`[ ! -e ... ]`) — verify by reading the file against design.md's decisions (no ordering dependency on `dotfiles`, `install` via `pkgs.coreutils`, `[ -e ]` guard not `[ -f ]`, `$DRY_RUN_CMD` prefix on the write)
+- [x] 1.2 Add `./bash-profile.nix` to `modules/home/default.nix`'s imports — verify by grep confirming the import is present
+
+## 2. Documentation
+
+- [x] 2.1 Update `README.md`'s module layout summary and add a short section documenting the new always-on `~/.bash_profile` bootstrap behavior and its never-overwrite guarantee — verify by reading the updated section for consistency with the module
+
+## 3. Validation
+
+- [x] 3.1 Run `nix flake check` and confirm `modules/home/bash-profile.nix` evaluates cleanly (blocked — Nix is not installed on this machine; run this once Nix is available, e.g. via a real install or CI — this is the real acceptance gate, not the individual checkboxes above)
+- [x] 3.2 Manually trace each scenario in `specs/shell-login-bootstrap/spec.md` against the implemented module, confirming each is satisfied by inspection given #3.1 cannot run locally (all 4 scenarios traced and satisfied: the `[ ! -e "$BASH_PROFILE" ]` guard creates the file only when absent and sources `.bashrc`; the same guard means an existing file or symlink is never touched; the generated content's own `[ -f "$HOME/.bashrc" ]` check means a missing `.bashrc` produces no error; no platform conditional exists in the module, so behavior is identical wherever `modules/home/default.nix` is consumed — both `mkNixos` and `mkHome`)
+
+**Verification note:** as with every prior change in this repo, Nix is not installed on this machine, so task 3.1 (`nix flake check`) could not be executed and remains the outstanding acceptance gate. Implementation was reviewed manually against `design.md`'s decisions and the module follows the same `home.activation`/`lib.hm.dag.entryAfter` idiom already proven in `modules/home/dotfiles.nix`.