docs/setup/01-dev-debian-vm-setup.md

@@ -169,7 +169,7 @@ What each script does:
 | [`50-docker.sh`](scripts/50-docker.sh)               | Install Docker CE + compose plugin from the Docker apt repo. Add the current user to the `docker` group. Enable `docker.service`.                                                                                                                                               | ✅          |
 | [`60-tuning.sh`](scripts/60-tuning.sh)               | `fs.inotify.max_user_watches=524288` (Vite / Nx watch). Prompt for hostname (only if generic). Add a 4 GB swapfile if none.                                                                                                                                                     | ✅          |
 | [`70-hardening.sh`](scripts/70-hardening.sh)         | Best-effort UFW (allow SSH only, prompts before enabling), `unattended-upgrades` on security channel, `fail2ban` (opt-in — prompts before installing), sshd hardening (no root, no password — prompts before applying). **Probes before applying** — skips what's already done. | ✅          |
-| [`80-dotfiles.sh`](scripts/80-dotfiles.sh)           | Symlink `notes/aliases.zsh` → `~/.oh-my-zsh/custom/aliases.zsh`. Generate `~/.gitconfig` from `notes/gitconfig.txt`, prompt for identity (name + email).                                                                                                                        | ✅          |
+| [`80-dotfiles.sh`](scripts/80-dotfiles.sh)           | Symlink `docs/setup/dotfiles/aliases.zsh` → `~/.oh-my-zsh/custom/aliases.zsh`. Generate `~/.gitconfig` from `docs/setup/dotfiles/gitconfig.txt`, prompt for identity (name + email).                                                                                            | ✅          |
 
 After bootstrap, reload your shell to pick up the new PATH + zsh:
 
@@ -345,7 +345,7 @@ git clone git@git.unespace.com:apf/dotfiles.git ~/.dotfiles
 ~/.dotfiles/install.sh
 ```
 
-The dotfiles repo is **out of scope** for this PR but the `80-dotfiles.sh` script is already structured to fall back to either (a) the in-repo files (`notes/aliases.zsh`, `notes/gitconfig.txt`) or (b) a `~/.dotfiles/` checkout if one exists. A subsequent PR creates the dotfiles repo and reuses these inputs as the seed.
+The dotfiles repo is **out of scope** for this PR but the `80-dotfiles.sh` script reads the project-wide templates from `docs/setup/dotfiles/` (`aliases.zsh`, `gitconfig.txt`). A subsequent PR creates the per-dev `~/.dotfiles/` repo and reuses those templates as its seed.
 
 ### 8.5 — GPG agent forwarding (optional, for signed commits)
 

docs/setup/README.md

@@ -24,7 +24,16 @@ Modular setup scripts called from the doc above. Each is idempotent, each can be
 | [`50-docker.sh`](scripts/50-docker.sh)               | Docker CE + compose plugin from docker.com apt repo + user added to `docker` group + service enabled at boot.                                                                    |
 | [`60-tuning.sh`](scripts/60-tuning.sh)               | inotify watches → 524288, optional 4 GB swapfile, optional hostname rename (only prompts if generic).                                                                            |
 | [`70-hardening.sh`](scripts/70-hardening.sh)         | Best-effort UFW + unattended-upgrades + fail2ban (opt-in) + sshd hardening drop-in. Probes before applying — skips done items, prompts before each install.                      |
-| [`80-dotfiles.sh`](scripts/80-dotfiles.sh)           | Symlinks `notes/aliases.zsh` → `~/.oh-my-zsh/custom/aliases.zsh`. Copies `notes/gitconfig.txt` to `~/.gitconfig` with prompted identity.                                         |
+| [`80-dotfiles.sh`](scripts/80-dotfiles.sh)           | Symlinks `docs/setup/dotfiles/aliases.zsh` → `~/.oh-my-zsh/custom/aliases.zsh`. Copies `docs/setup/dotfiles/gitconfig.txt` to `~/.gitconfig` with prompted identity.             |
+
+## `dotfiles/`
+
+Project-wide dotfile templates installed by [`80-dotfiles.sh`](scripts/80-dotfiles.sh). Versioned so a fresh clone has everything it needs — `notes/` is gitignored and was the wrong home for these.
+
+| File                                      | Purpose                                                                                                                                                                      |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`aliases.zsh`](dotfiles/aliases.zsh)     | Project-wide zsh aliases, symlinked into `~/.oh-my-zsh/custom/aliases.zsh`. Edit here, all devs pick it up on restart.                                                       |
+| [`gitconfig.txt`](dotfiles/gitconfig.txt) | Base `~/.gitconfig` template (aliases, colour, default branch, editor). Identity (`user.name` / `user.email`) is prompted at install and overlaid via `git config --global`. |
 
 ## `systemd/`
 

docs/setup/dotfiles/aliases.zsh

@@ -0,0 +1,36 @@
+# Project-wide zsh aliases for apf-portal. Installed by 80-dotfiles.sh as
+# a symlink at ~/.oh-my-zsh/custom/aliases.zsh, so any change here ripples
+# to every dev's shell on their next zsh restart.
+#
+# Per-dev customizations belong elsewhere (private dotfiles repo or
+# additional files under ~/.oh-my-zsh/custom/).
+
+# Navigation
+alias ls="eza --icons"
+alias la="eza -alF --icons"
+alias ll="eza -lA --icons"
+alias lh="eza -lAh --icons --git"
+alias lr="eza -lAhR --icons --git"
+alias lt="ls -lAhtr"
+alias ltr="eza --tree --icons"
+alias l="ls -CF"
+alias cdworks="cd ~/Works/apf_portal"
+
+# Files
+alias bat="batcat"
+
+# Search
+alias find="fd"
+
+# Git
+alias gitstat='git status'
+alias gitcount='git status | wc -l'
+alias gitgb='git log --oneline --graph --decorate'
+alias gitgraph='git log --oneline --graph --decorate --branches'
+alias gitfullstat='git log --graph --decorate --branches --stat'
+alias gitprune='git remote update origin --prune'
+alias gitfp='git fetch --all --prune'
+
+# Dev
+alias ng="pnpm exec ng"
+alias nx="pnpm exec nx"

docs/setup/dotfiles/gitconfig.txt

@@ -0,0 +1,41 @@
+[user]
+        name = your name
+        email = your.email@example.com
+[init]
+        defaultBranch = master
+[core]
+        editor = nano
+[alias]
+        lg = log --oneline --graph --decorate --all
+        br = for-each-ref --format='%(refname:short)' refs/heads refs/remotes
+        brl = for-each-ref --format='%(refname:short)' refs/heads
+        brr = for-each-ref --format='%(refname:short)' refs/remotes
+        c = commit
+        co = checkout
+        cob = checkout -b
+        fp = fetch --all --prune
+        gb = log --oneline --graph --decorate
+        gr = log --oneline --graph --decorate --branches
+        gs = log --graph --decorate --branches --stat
+        s = stash
+        sp = stash pop
+        st = status
+        pm = !git switch main && git pull --ff-only origin main
+[color]
+        branch = auto
+        diff = auto
+        status = auto
+        interactive = auto
+[color "branch"]
+        current = yellow reverse
+        local = yellow
+        remote = green
+[color "diff"]
+        meta = yellow bold
+        frag = magenta bold
+        old = red bold
+        new = green bold
+[color "status"]
+        added = green
+        changed = yellow
+        untracked = cyan

docs/setup/scripts/80-dotfiles.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# Wire up the project-specific dotfiles:
+# Wire up the project-wide dotfiles:
-#   - symlink notes/aliases.zsh → ~/.oh-my-zsh/custom/aliases.zsh
+#   - symlink docs/setup/dotfiles/aliases.zsh → ~/.oh-my-zsh/custom/aliases.zsh
-#   - copy notes/gitconfig.txt to ~/.gitconfig and overlay your identity
+#   - copy docs/setup/dotfiles/gitconfig.txt to ~/.gitconfig and overlay your identity
 set -euo pipefail
 # shellcheck source=./lib.sh
 source "$(cd "$(dirname "$0")" && pwd)/lib.sh"
@@ -14,8 +14,10 @@ if [[ -z "$REPO_ROOT" ]]; then
   exit 1
 fi
 
+DOTFILES_DIR="$REPO_ROOT/docs/setup/dotfiles"
+
 # ─── 1. Aliases ───────────────────────────────────────────────────────
-SOURCE_ALIASES="$REPO_ROOT/notes/aliases.zsh"
+SOURCE_ALIASES="$DOTFILES_DIR/aliases.zsh"
 if [[ ! -f "$SOURCE_ALIASES" ]]; then
   err "$SOURCE_ALIASES not found."
   exit 1
@@ -42,7 +44,7 @@ else
 fi
 
 # ─── 2. gitconfig — copy + identity overlay ───────────────────────────
-SOURCE_GITCONFIG="$REPO_ROOT/notes/gitconfig.txt"
+SOURCE_GITCONFIG="$DOTFILES_DIR/gitconfig.txt"
 if [[ ! -f "$SOURCE_GITCONFIG" ]]; then
   err "$SOURCE_GITCONFIG not found."
   exit 1