diff --git a/README.md b/README.md
index dbda8ed..1802110 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,10 @@ Bitwarden note:
 - `bw` is installed via Homebrew as `bitwarden-cli`
 - `bws` is not currently managed in this repo because I did not find a
   supported nixpkgs or Homebrew package for it on macOS during verification
+- daily shell secrets are synced from Bitwarden into `~/.config/secrets/shell.zsh`
+  via `just secrets-sync`
+- vault items are currently the source of truth for imported machine secrets and
+  SSH material
 
 ## Commands
 
@@ -94,7 +98,8 @@ just secrets-sync
 
 ## What Still Needs Manual Handling
 
-- Secrets and tokens under `~/.secrets`, `~/.npmrc`, `~/.config/gcloud`, `~/.config/gh`, and similar paths
+- Promoting vault-backed secrets into Bitwarden Secrets Manager machine-account
+  flows, if you want fully non-interactive sandbox secret injection later
 - App state under `~/Library/Application Support`
 - Anything that depends on local credentials, keychains, or encrypted stores
 - Manual cleanup of old non-Nix installs that are no longer wanted
diff --git a/docs/secrets.md b/docs/secrets.md
new file mode 100644
index 0000000..5e3341a
--- /dev/null
+++ b/docs/secrets.md
@@ -0,0 +1,78 @@
+# Secrets
+
+## Current Model
+
+This repo does not store secret values in Nix.
+
+Instead:
+
+- Bitwarden vault items are the current source of truth for imported machine
+  secrets
+- Nix/Home Manager owns the integration points
+- generated runtime files live outside the repo under `~/.config/secrets`
+
+That boundary matters because the Nix store is not the right place for real
+secret values.
+
+## What Is Already Wired
+
+- [home/zsh.nix](/Users/rathi/Documents/GitHub/nix/home/zsh.nix) sources
+  `~/.config/secrets/shell.zsh` when present
+- [scripts/render-bw-shell-secrets.sh](/Users/rathi/Documents/GitHub/nix/scripts/render-bw-shell-secrets.sh)
+  renders that file from Bitwarden vault items
+- [justfile](/Users/rathi/Documents/GitHub/nix/justfile) exposes this as
+  `just secrets-sync`
+
+## Daily Shell Flow
+
+```bash
+export BW_SESSION="$(bw unlock --raw)"
+just secrets-sync
+exec zsh -l
+```
+
+That flow currently materializes:
+
+- `OPENAI_API_KEY`
+- `GREPTILE_API_KEY`
+- `CONTEXT7_API_KEY`
+- `MISTRAL_API_KEY`
+
+## Machine Secret Coverage
+
+The Bitwarden vault now holds:
+
+- API keys and CLI tokens
+- AWS default credentials
+- GCloud ADC
+- Stripe CLI config
+- Codex auth
+- Vercel auth
+- SSH configs
+- SSH private keys
+
+The vault is currently the backup/recovery source of truth for those values.
+
+## Sandbox Strategy
+
+For a fresh sandbox or new machine, the clean bootstrap is:
+
+1. `darwin-rebuild switch` or Home Manager activation
+2. authenticate `bw`
+3. `just secrets-sync`
+4. restore any file-based credentials you actually need from Bitwarden
+
+That gives you a usable dev shell quickly without committing any secret values
+into the repo.
+
+## Future Upgrade
+
+If you want fully non-interactive sandbox secret injection, the next step is to
+move the env-style secrets from normal Bitwarden vault items into Bitwarden
+Secrets Manager (`bws`) and keep file-based credentials and SSH material in the
+normal vault.
+
+That would give you:
+
+- `bws` for machine/app secrets
+- `bw` for human-managed vault items, SSH material, and recovery data
diff --git a/home/zsh.nix b/home/zsh.nix
index 7ee364c..887c888 100644
--- a/home/zsh.nix
+++ b/home/zsh.nix
@@ -42,7 +42,9 @@
     };
 
     envExtra = ''
-      . "$HOME/.cargo/env"
+      if [[ -f "$HOME/.cargo/env" ]]; then
+        . "$HOME/.cargo/env"
+      fi
 
       # Ghostty shell integration expects a resource directory; the Nix app
       # bundle lives in the store instead of /Applications.