From 891ba27000c373f5fef640d3d9cdda016cab9c9f Mon Sep 17 00:00:00 2001
From: Christian Colglazier <christian@cacolglazier.com>
Date: Sun, 11 Oct 2026 12:55:19 -0400
Subject: [PATCH] feat(dotfiles): document macos setup and secure secrets

---
 README.md                                  | 59 +++++++++++++++++++++-
 home/.chezmoiignore                        |  3 ++
 home/bin/frc-photo-checklist.py            |  3 +-
 home/dot_Brewfile                          | 21 ++++++++
 home/dot_config/private_settings.conf.tmpl |  5 ++
 home/dot_config/settings.conf.tmpl         |  4 --
 6 files changed, 88 insertions(+), 7 deletions(-)
 create mode 100644 home/dot_Brewfile
 create mode 100644 home/dot_config/private_settings.conf.tmpl
 delete mode 100644 home/dot_config/settings.conf.tmpl

diff --git a/README.md b/README.md
index 87ffd98..dc2f60b 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,65 @@
 # Dotfiles
 
-A collection of config files and scripts for Fedora GNU/Linux.
+A collection of config files and scripts for Fedora GNU/Linux and macOS.
 
-## Installation
+## Linux installation
 
 ```bash
 chezmoi init --apply git@github.com:AquaMorph/dotfiles.git
 ```
 
+## macOS installation
+
+1. Install the Xcode Command Line Tools with `xcode-select --install`, then
+   install [Homebrew](https://brew.sh/) and follow its `brew shellenv`
+   instructions. Its default prefix is `/opt/homebrew` on Apple Silicon and
+   `/usr/local` on Intel Macs.
+
+2. Download the dotfiles without applying them, then install dependencies:
+
+   ```bash
+   brew install chezmoi
+   chezmoi init git@github.com:AquaMorph/dotfiles.git
+    brew bundle --file="$(chezmoi source-path ~/.brewfile)"
+   ```
+
+    The Brewfile includes chezmoi, Git, Emacs, Python, jq, pass, GnuPG, Brave Browser,
+    Alacritty, and Inconsolata. FFmpeg and Ollama are optional; install them separately
+    if needed.
+
+3. Restore your password store to `~/.password-store` and import its GPG private
+   key from a secure backup before applying the dotfiles:
+
+   ```bash
+   gpg --import /path/to/private-key-backup.asc
+   ```
+
+   If the store is kept in Git, clone it to `~/.password-store` using your
+   password-store repository URL. Verify that all required secrets can be
+   decrypted without printing their values:
+
+   ```bash
+   pass show self-host/token/audible-activation-bytes >/dev/null
+   pass show self-host/token/aquaai >/dev/null
+   pass show self-host/token/todoist >/dev/null
+   ```
+
+   `settings.conf` is rendered using `pass`, so applying it requires these
+   entries and the matching private key. Never commit keys or plaintext tokens.
+
+4. Review and apply the dotfiles, then open a new terminal:
+
+   ```bash
+   chezmoi diff
+   chezmoi apply
+   ```
+
+   The generated `~/.config/settings.conf` is private (mode `0600`) and its
+   values are shell-quoted. Linux-only configuration and scripts are ignored on
+   macOS; shared shell, Git, and terminal configuration remains managed.
+
+To install newly added macOS dependencies later:
+
+```bash
+brew bundle --file="$(chezmoi source-path ~/.brewfile)"
+```
diff --git a/home/.chezmoiignore b/home/.chezmoiignore
index 7fe4aad..bcf6b74 100644
--- a/home/.chezmoiignore
+++ b/home/.chezmoiignore
@@ -46,4 +46,7 @@ bin/audio/synth-power-prompt.sh
 
 # Wine-based Adobe DNG conversion with GNU date
 bin/video/cr3todng.sh
+{{ else -}}
+# Homebrew dependencies are only managed on macOS.
+.brewfile
 {{ end -}}
diff --git a/home/bin/frc-photo-checklist.py b/home/bin/frc-photo-checklist.py
index c27d681..4d55a4a 100644
--- a/home/bin/frc-photo-checklist.py
+++ b/home/bin/frc-photo-checklist.py
@@ -7,6 +7,7 @@ import datetime as dt
 import re
 import operator
 import os
+import shlex
 import sys
 import tbapy
 from todoist_api_python.api import TodoistAPI
@@ -105,7 +106,7 @@ configParser.read_string(configString)
 
 # Load needed credentials
 tbaKey = configParser.get('Settings', 'TBAKey')
-todoistToken = configParser.get('Settings', 'TodoistToken')
+todoistToken = shlex.split(configParser.get('Settings', 'TodoistToken'))[0]
 
 # Setup Todoist
 api = TodoistAPI(todoistToken)
diff --git a/home/dot_Brewfile b/home/dot_Brewfile
new file mode 100644
index 0000000..1046843
--- /dev/null
+++ b/home/dot_Brewfile
@@ -0,0 +1,21 @@
+# Shared command-line tools
+brew "chezmoi"
+brew "git"
+brew "emacs"
+brew "python"
+brew "jq"
+
+# Password-store secrets used by chezmoi templates
+brew "pass"
+brew "gnupg"
+
+# Web browser
+cask "brave-browser"
+
+# Terminal and font used by the shared Alacritty configuration
+cask "alacritty"
+cask "font-inconsolata"
+
+# Optional tools for audio conversion and local AI
+# brew "ffmpeg"
+# brew "ollama"
diff --git a/home/dot_config/private_settings.conf.tmpl b/home/dot_config/private_settings.conf.tmpl
new file mode 100644
index 0000000..a38a764
--- /dev/null
+++ b/home/dot_config/private_settings.conf.tmpl
@@ -0,0 +1,5 @@
+# Single-quote values and escape embedded single quotes without changing backslashes.
+computer='{{ .chezmoi.hostname | replace "'" "'\\''" }}'
+activation_bytes='{{ pass "self-host/token/audible-activation-bytes" | replace "'" "'\\''" }}'
+AQUAAI_KEY='{{ pass "self-host/token/aquaai" | replace "'" "'\\''" }}'
+TodoistToken='{{ pass "self-host/token/todoist" | replace "'" "'\\''" }}'
diff --git a/home/dot_config/settings.conf.tmpl b/home/dot_config/settings.conf.tmpl
deleted file mode 100644
index 06affeb..0000000
--- a/home/dot_config/settings.conf.tmpl
+++ /dev/null
@@ -1,4 +0,0 @@
-computer={{ .chezmoi.hostname }}
-activation_bytes={{ pass "self-host/token/audible-activation-bytes" }}
-AQUAAI_KEY={{ pass "self-host/token/aquaai" }}
-TodoistToken={{ pass "self-host/token/todoist" }}
\ No newline at end of file