feat: add Starship prompt across all 3 platforms

CHANGELOG.md

@@ -6,6 +6,37 @@ Versions increment by one patch step (0.0.1) per release.
 
 ---
 
+## [1.0.7] - 2026-06-05
+
+### Added
+
+- Starship prompt across all three platforms: `mac/topics/59-starship.zsh`,
+  `linux/topics/59-starship.sh`, `windows/topics/59-starship.ps1` — each
+  contains the single platform-specific init line.
+- `shared/starship.toml`: one config file for all three platforms covering git,
+  all languages in the 59 topic files (Python, Node, Go, Rust, Java/Kotlin/Scala,
+  PHP, Ruby, .NET, Docker, Lua, Zig, Swift, Elixir), and command duration.
+  Cloud modules (AWS, GCloud, Azure) disabled for startup performance.
+- `journal/009-starship-prompt.md`: reasoning behind adding Starship, module
+  choices, the shared/ approach, and how to disable it.
+
+### Changed
+
+- `shared/README.md`: updated to list `starship.toml` and explain the shared
+  config pattern.
+- `NOTICE`: updated to mention `shared/starship.toml` and the symlink step.
+- `guides/mac.md`, `guides/linux.md`, `guides/windows.md`: topic count updated
+  from 58 to 59; Starship topic file and symlink noted in loader section.
+- `guides/new-device.md`: Starship setup steps added for all three platforms
+  (install + symlink); added to Contents; dedicated section before Mirror setup.
+- `documentation.md`: architecture updated to 59 topic files; Starship section
+  added with full module table and disable instructions; "next available number"
+  note updated from 59 to 60.
+- `will-do/new-device-setup.md`: Starship step expanded with platform-specific
+  install and symlink commands.
+
+---
+
 ## [1.0.6] - 2026-06-05
 
 ### Added

NOTICE

@@ -9,11 +9,12 @@ matches your machine - do not mix files across platforms.
   linux/     Linux only  (bash, apt/pacman, Linux-specific paths and tools)
   windows/   Windows only  (PowerShell, winget/choco, Windows-specific paths)
 
-The shared/ folder contains files used by all three platforms.
+The shared/ folder contains files used by all three platforms, including
+starship.toml — the Starship prompt config. Symlink it to ~/.config/starship.toml
+on each device (see the Starship section in will-do/new-device-setup.md).
 The scripts/ folder contains utility scripts that run from any platform.
 The hooks/ folder contains git hooks that can be installed manually.
 
-
 What you must change before using these dotfiles
 -------------------------------------------------
 
@@ -46,6 +47,11 @@ What you must change before using these dotfiles
    to match the version on your machine, or remove it and rely on the dynamic
    finder function.
 
+7. Starship prompt in 59-starship
+   The 59-starship topic file is already written for all three platforms.
+   After cloning, symlink shared/starship.toml to ~/.config/starship.toml and
+   install Starship for your platform. See will-do/new-device-setup.md for the
+   exact commands per platform.
 
 API tokens and secrets - never commit these
 -------------------------------------------
@@ -65,7 +71,6 @@ The recommended approach is to keep all tokens in a file at ~/.mirror_tokens
 (chmod 600) and source it from your profile. That file is listed in .gitignore
 and must never be committed.
 
-
 Platform-specific tools mentioned in these files
 -------------------------------------------------
 
@@ -83,10 +88,12 @@ Some tools appear only on one platform because they have no equivalent elsewhere
                   /opt/resolve/bin/resolve for DaVinci Resolve (55-media.sh)
                   /dev/ttyUSB* and /dev/ttyACM* for serial devices (49-eda.sh)
 
+  All platforms:  shared/starship.toml covers all languages and tools across
+                  the 59 topic files. One symlink per device is all that is needed.
+
 If a command listed in cmds() does not exist on your platform, it will simply
 not be defined - the loader will source the file without error.
 
-
 Licence
 -------
 

documentation.md

@@ -70,7 +70,7 @@ Detailed technical reference for this dotfiles repo. This covers how the loader
 
 ## Architecture
 
-The profile is split across 58 numbered topic files rather than kept in a single monolithic profile. I did this because a single file past a few hundred lines becomes hard to navigate, and topic files make it easy to find, add or remove a section without touching anything else.
+The profile is split across 59 numbered topic files rather than kept in a single monolithic profile. I did this because a single file past a few hundred lines becomes hard to navigate, and topic files make it easy to find, add or remove a section without touching anything else.
 
 ```
 dotfiles/
@@ -79,10 +79,12 @@ dotfiles/
 - mac/topics/02-colours.zsh second topic file
 - ...
 - mac/topics/58-productivity.zsh
+- mac/topics/59-starship.zsh   Starship prompt init
 - linux/bashrc              loader for Linux and WSL2 (bash)
-- linux/topics/*.sh         same 58 topics, bash syntax
+- linux/topics/*.sh         same 59 topics, bash syntax
 - windows/Microsoft.PowerShell_profile.ps1   loader for Windows (PowerShell)
-- windows/topics/*.ps1      same 58 topics, PowerShell syntax
+- windows/topics/*.ps1      same 59 topics, PowerShell syntax
+- shared/starship.toml      Starship prompt config — one file for all three platforms
 ```
 
 ---
@@ -1359,11 +1361,50 @@ Defined in `58-productivity` on all platforms.
 
 ---
 
+## Starship prompt
+
+Defined in `59-starship` on all platforms. Config in `shared/starship.toml`.
+
+Starship replaces the shell's default prompt line (`%` / `$`) with a dynamic one that
+re-evaluates on every Enter press. Only modules relevant to the current directory appear —
+git info only shows inside git repos, language versions only inside matching projects.
+
+| What you see | When it appears |
+| --- | --- |
+| Directory (bold blue, 3 segments) | Always |
+| Branch + git status | Inside any git repo |
+| Python version | `.py` file, `pyproject.toml`, `requirements.txt`, or `.python-version` present |
+| Node version | `package.json` present |
+| Go version | `go.mod` or `.go` files present |
+| Rust version | `Cargo.toml` or `.rs` files present |
+| Java/Kotlin/Scala | `.java`, `.kt`, `.kts`, or `.scala` files present |
+| PHP version | `.php` files present |
+| Ruby version | `.rb` files or `Gemfile` present |
+| .NET version | `.cs`, `.csproj`, or `.fsproj` files present |
+| Docker context | `Dockerfile` or `docker-compose.yml` present |
+| Lua version | `.lua` files present |
+| Zig version | `.zig` files present |
+| Swift version | `.swift` files present |
+| Elixir version | `.ex`, `.exs`, or `mix.exs` present |
+| Haskell version | `stack.yaml`, `.cabal`, or `.hs` files present |
+| Deno version | `deno.json`, `deno.jsonc`, or `deno.lock` present |
+| Bun version | `bun.lockb` present |
+| Dart/Flutter version | `pubspec.yaml` present |
+| C/C++ | `.c`, `.cpp`, `.h`, or `.hpp` files present |
+| Command duration | Any command that took longer than 2 seconds |
+
+To disable Starship entirely: comment out the `eval` line in `59-starship.zsh` (or `.sh` / `.ps1`) and reload.
+To hide a specific module: add `disabled = true` under its section in `shared/starship.toml`.
+
+The `starship.toml` is shared — editing it once updates the prompt on all three platforms on the next shell open.
+
+---
+
 ## Extending the profile
 
 To add a new group of aliases:
 
-1. Create a new file in the relevant `topics/` folder with the next available number, e.g. `59-mytopic.zsh` (macOS), `59-mytopic.sh` (Linux) or `59-mytopic.ps1` (Windows).
+1. Create a new file in the relevant `topics/` folder with the next available number, e.g. `60-mytopic.zsh` (macOS), `60-mytopic.sh` (Linux) or `60-mytopic.ps1` (Windows). (`59` is taken by Starship.)
 2. Add your aliases and functions to the file.
 3. Reload the profile: `reload-profile`.
 4. Run `cmds` to verify the new commands appear. If you want them listed there too, add a section to `06-functions` under `cmds()`.

guides/linux.md

@@ -80,7 +80,9 @@ for f in "$DOTFILES/linux/topics"/[0-9]*.sh; do
 done
 ```
 
-Files load from `01-path.sh` to `58-productivity.sh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [linux/topics/README.md](../linux/topics/README.md) for the full listing.
+Files load from `01-path.sh` to `59-starship.sh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [linux/topics/README.md](../linux/topics/README.md) for the full listing.
+
+`59-starship.sh` initialises the Starship prompt. The config lives in [shared/starship.toml](../shared/starship.toml) — one file shared across all three platforms. Symlink it to `~/.config/starship.toml` on each device.
 
 ---
 

guides/mac.md

@@ -69,9 +69,11 @@ for f in "$DOTFILES/mac/topics"/[0-9]*.zsh; do
 done
 ```
 
-Files are loaded from `01-path.zsh` to `58-productivity.zsh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [mac/topics/README.md](../mac/topics/README.md) for the full listing of all topic files.
+Files are loaded from `01-path.zsh` to `59-starship.zsh`. A higher-numbered file overrides an alias from a lower-numbered one if they share a name. See [mac/topics/README.md](../mac/topics/README.md) for the full listing of all topic files.
 
-To add a new group of aliases, create a new file (e.g. `59-mytopic.zsh`) in `mac/topics/`. It is picked up automatically at the next `reload-profile`. No changes to `zshrc` needed.
+`59-starship.zsh` initialises the Starship prompt. The config lives in [shared/starship.toml](../shared/starship.toml) — one file shared across all three platforms. Symlink it to `~/.config/starship.toml` on each device.
+
+To add a new group of aliases, create a new file (e.g. `60-mytopic.zsh`) in `mac/topics/`. It is picked up automatically at the next `reload-profile`. No changes to `zshrc` needed.
 
 ---
 

guides/new-device.md

@@ -10,6 +10,7 @@ Step-by-step walkthrough for setting up these dotfiles on a brand new machine. F
 - [Linux (Ubuntu / Debian)](#linux-ubuntu--debian)
 - [WSL2 on Windows](#wsl2-on-windows)
 - [Windows (native PowerShell)](#windows-native-powershell)
+- [Starship prompt (all platforms)](#starship-prompt-all-platforms)
 - [Mirror setup (all platforms)](#mirror-setup-all-platforms)
 
 ---
@@ -67,7 +68,19 @@ Download from [code.visualstudio.com](https://code.visualstudio.com). After inst
 
 Press `Cmd+Shift+P` in VS Code, type "Shell Command: Install 'code' command in PATH" and run it.
 
-### 7 - Install language runtimes
+### 7 - Set up the Starship prompt
+
+`59-starship.zsh` is already in the profile and will be sourced automatically. You just need to install Starship and symlink the shared config:
+
+```bash
+brew install starship
+mkdir -p ~/.config
+ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml
+```
+
+Open a new terminal tab. The prompt will show your current directory, git branch, and language versions automatically.
+
+### 8 - Install language runtimes
 
 Install whichever runtimes you need:
 
@@ -129,7 +142,19 @@ sudo snap install --classic code
 
 Or download the `.deb` package from [code.visualstudio.com](https://code.visualstudio.com).
 
-### 6 - Install language runtimes
+### 6 - Set up the Starship prompt
+
+`59-starship.sh` is already in the profile and will be sourced automatically. You just need to install Starship and symlink the shared config:
+
+```bash
+curl -sS https://starship.rs/install.sh | sh
+mkdir -p ~/.config
+ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml
+```
+
+Open a new terminal tab. The prompt will show your current directory, git branch, and language versions automatically.
+
+### 7 - Install language runtimes
 
 ```bash
 sudo apt install -y python3 python3-pip golang nodejs npm
@@ -210,14 +235,67 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 > [!NOTE]
 > The profile uses `C:\dev` as a convention for the base dev folder. Review [windows/topics/03-navigation.ps1](../windows/topics/03-navigation.ps1) and adjust the directory shortcuts to match your own folder layout before applying.
 
-### 5 - Install language runtimes
+### 5 - Set up the Starship prompt
+
+`59-starship.ps1` is already in the profile and will be sourced automatically. You just need to install Starship and symlink the shared config:
+
+```powershell
+winget install Starship.Starship
+New-Item -ItemType Directory -Force -Path "$HOME\.config"
+New-Item -ItemType SymbolicLink -Path "$HOME\.config\starship.toml" -Target "C:\path\to\your\projects\dotfiles\shared\starship.toml"
+```
+
+> [!NOTE]
+> Creating a symlink on Windows requires either running PowerShell as Administrator or enabling Developer Mode in Settings → System → For developers.
+
+Open a new terminal tab. The prompt will show your current directory, git branch, and language versions automatically.
+
+### 6 - Install language runtimes
 
 ```powershell
 winget install OpenJS.NodeJS Python.Python.3 GoLang.Go Rustlang.Rustup
 ```
 
 ---
 
+## Starship prompt (all platforms)
+
+The `59-starship` topic file is already written for all three platforms and sourced automatically
+when the profile loads. All that is needed on a new device is to install Starship and symlink the
+shared config. The config lives in `shared/starship.toml` — one file, identical across all devices.
+Never create platform-specific versions; edit the shared file and it updates everywhere.
+
+### macOS
+
+```bash
+brew install starship
+mkdir -p ~/.config
+ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml
+```
+
+### Linux / WSL2
+
+```bash
+curl -sS https://starship.rs/install.sh | sh
+mkdir -p ~/.config
+ln -sf /path/to/your/projects/dotfiles/shared/starship.toml ~/.config/starship.toml
+```
+
+### Windows (native PowerShell)
+
+```powershell
+winget install Starship.Starship
+New-Item -ItemType Directory -Force -Path "$HOME\.config"
+New-Item -ItemType SymbolicLink -Path "$HOME\.config\starship.toml" -Target "C:\path\to\your\projects\dotfiles\shared\starship.toml"
+```
+
+> [!NOTE]
+> Creating a symlink on Windows requires either running PowerShell as Administrator or enabling Developer Mode in Settings → System → For developers.
+
+Open a new terminal tab — the prompt updates immediately. See [shared/starship.toml](../shared/starship.toml) to add or disable modules.
+
+---
+
 ## Mirror setup (all platforms)
 
 ### 1 - Create the token file

guides/windows.md

@@ -87,7 +87,9 @@ Get-ChildItem "$PSScriptRoot\topics\[0-9]*.ps1" | Sort-Object Name | ForEach-Obj
 }
 ```
 
-Files load from `01-path.ps1` to `58-productivity.ps1`. A later-numbered file overrides a function from an earlier one if they share a name. See [windows/topics/README.md](../windows/topics/README.md) for the full listing.
+Files load from `01-path.ps1` to `59-starship.ps1`. A later-numbered file overrides a function from an earlier one if they share a name. See [windows/topics/README.md](../windows/topics/README.md) for the full listing.
+
+`59-starship.ps1` initialises the Starship prompt. The config lives in [shared/starship.toml](../shared/starship.toml) — one file shared across all three platforms. Symlink it to `~/.config/starship.toml` on each device.
 
 ---