From 09a6bf7353a9e08ce959dde3c47378ecabbd117d Mon Sep 17 00:00:00 2001
From: "Simen A. W. Olsen" <hello@simenandre.no>
Date: Sat, 15 Aug 2026 00:37:57 +0200
Subject: docs: cover Full Disk Access requirement for sandboxed app defaults

---
 INSTALL.md | 44 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

(limited to 'INSTALL.md')

diff --git a/INSTALL.md b/INSTALL.md
index 024695d..1938748 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -60,7 +60,20 @@ HTTPS on purpose: SSH access depends on 1Password's SSH agent, which is not
 installed yet. After the first switch, git rewrites the HTTPS remote to SSH
 (`url."git@simenandre.no:".insteadOf`), so this remote keeps working.
 
-### 5. First switch (bootstrap nix-darwin)
+### 5. Grant Full Disk Access to the terminal
+
+`modules/darwin/macos.nix` writes preferences for three sandboxed apps — Safari,
+Help Viewer, and TextEdit. Their preference files live under
+`~/Library/Containers/`, which macOS protects with TCC, so `defaults` is denied
+unless the terminal running the switch has Full Disk Access. The activation
+script runs under `set -e`, so a single denial aborts the whole switch.
+
+System Settings → Privacy & Security → Full Disk Access → **+** → add
+`/System/Applications/Utilities/Terminal.app` (Ghostty is not installed yet on a
+fresh machine) → quit and reopen the terminal, so the new grant applies to a
+fresh process.
+
+### 6. First switch (bootstrap nix-darwin)
 
 Pick the configuration that matches the machine — each one pins its own username,
 so switching with the wrong attribute fails during activation:
@@ -101,7 +114,7 @@ Adding another Mac later means one entry in `flake.nix`:
 Restart the terminal (or log out and back in) so the new zsh config, `PATH`, and
 Ghostty configuration take effect.
 
-### 6. 1Password and SSH
+### 7. 1Password and SSH
 
 Git commits are signed through 1Password's SSH agent
 (`/Applications/1Password.app/Contents/MacOS/op-ssh-sign`), so this has to be
@@ -122,7 +135,7 @@ set up before committing anything.
    ssh -T git@github.com
    ```
 
-### 7. Sign in to the rest
+### 8. Sign in to the rest
 
 Each of these is a one-time manual login:
 
@@ -137,7 +150,7 @@ GUI apps that need a login or permission grant: Tailscale (App Store), Slack,
 Discord, Signal, Obsidian, Proton Mail, ProtonVPN, Spotify, Raycast (grant
 Accessibility), Google Drive.
 
-### 8. Container runtime
+### 9. Container runtime
 
 Docker CLIs come from Homebrew, but the VM has to be started once:
 
@@ -148,7 +161,7 @@ colima start
 `DOCKER_HOST` is already pointed at `~/.colima/default/docker.sock` by
 `modules/home/zsh.nix`.
 
-### 9. Rust toolchain
+### 10. Rust toolchain
 
 `rustup` is installed, but ships without a toolchain:
 
@@ -156,7 +169,7 @@ colima start
 rustup default stable
 ```
 
-### 10. Tools not managed by Nix
+### 11. Tools not managed by Nix
 
 These are installed with `go install` and live in `~/go/bin`. Shell completions
 for them are generated on every switch, and the generator quietly skips any that
@@ -170,7 +183,7 @@ go install github.com/dinacomputer/api/cmd/dinactl@latest
 go install github.com/sokkelorg/identity/cmd/identityctl@latest
 ```
 
-### 11. Loose ends
+### 12. Loose ends
 
 ```shell
 mkdir -p ~/Screenshots     # macos.nix points screencapture here; it is not created for you
@@ -230,6 +243,23 @@ Aliases defined in `modules/home/zsh.nix` (macOS):
 **Mac App Store apps fail to install** — sign in to the App Store, then re-run
 the switch. `mas` cannot authenticate on its own.
 
+**`defaults[…] Could not write domain …/Library/Containers/…; exiting`** — the
+terminal lacks Full Disk Access (step 5), so a sandboxed app's preferences can't
+be written, and `set -e` aborts the switch. Grant it, then reopen the terminal
+before retrying — an already-running process keeps the old denial.
+
+If it still fails after that, the app's container does not exist yet:
+
+```shell
+ls -d ~/Library/Containers/com.apple.Safari
+```
+
+`defaults` cannot create a container the app has never made. Launch the app once
+(Safari, Help Viewer, or TextEdit — whichever the error names), quit it, and
+re-run. The three container-backed domains are all in `modules/darwin/macos.nix`
+under `CustomUserPreferences`; deleting the offending block is the other way out
+if you don't care about those settings.
+
 **home-manager refuses to overwrite an existing file** — files it would clobber
 are backed up with a `.bak` suffix (`backupFileExtension = "bak"`). If a switch
 still fails on a collision, a stale `.bak` from an earlier run is usually in the
-- 
cgit v1.2.3