diff --git a/.farhoodlabs/CLAUDE.md b/.farhoodlabs/CLAUDE.md
index f57dbc07..cb9c823f 100644
--- a/.farhoodlabs/CLAUDE.md
+++ b/.farhoodlabs/CLAUDE.md
@@ -7,16 +7,16 @@ Fork repo: https://github.com/farhoodlabs/paperclip
 
 | Branch | Purpose |
 |---|---|
-| `master` | Mirrors `upstream/master` exactly + `.farhoodlabs/` overlay directory + `assemble-local.yml` action. Never commit application code here. |
-| `local` | **Default branch.** Assembled automatically by `assemble-local.yml` on every `master` push. Contains: upstream + fork Dockerfile/workflows + all pending upstream PR cherry-picks. Builds `ghcr.io/farhoodlabs/paperclip`. |
-| `dev` | Development branch based on upstream/master. Builds `ghcr.io/farhoodlabs/paperclip-dev` on every push. |
+| `master` | Pure mirror of `upstream/master`. No fork-specific files in the tree. Sync via `git push origin upstream/master:master --force-with-lease`. |
+| `local` | **Default branch.** Assembled automatically by `assemble-local.yml` (defined on `dev`) on every `master` push. Contains: upstream + fork Dockerfile/workflows + all pending upstream PR cherry-picks. Builds `ghcr.io/farhoodlabs/paperclip`. |
+| `dev` | Development branch and canonical home of the `.farhoodlabs/` overlay and the `assemble-local.yml` action. Based on upstream/master. Builds `ghcr.io/farhoodlabs/paperclip-dev` on every push. |
 | PR branches | `skill-pat-feature`, `skill-scan-refresh`, `feat/company-portability-complete` — open PRs to upstream, never rebase onto master/local. |
 
 **Never commit directly to `local`** — it is fully regenerated by the assemble action and any direct commits will be overwritten.
 
 ## Fork Overlay (`.farhoodlabs/`)
 
-Files committed to `master` that get copied into position on `local` by the assemble action:
+Files committed to `.farhoodlabs/` on `dev` (the canonical source) that get copied into position on `local` by the assemble action:
 
 ```
 .farhoodlabs/
@@ -28,7 +28,7 @@ Files committed to `master` that get copied into position on `local` by the asse
 
 The fork's Dockerfile production stage additions over upstream: `kubectl`, `kubeseal`, `uv`/`uvx`, `forgejo-cli` (`fj`, `fj-ex`, `fgj`), `nano`, `vim`.
 
-To modify fork-specific files, edit them in `.farhoodlabs/` on `master` and push — the assemble action will apply them to `local` automatically.
+To modify fork-specific files, edit them in `.farhoodlabs/` on `dev` and push. The assemble action will apply them to `local` on the next `master` push (or trigger it manually via `workflow_dispatch`).
 
 ## Pending Upstream PRs (included in `local`)
 
@@ -50,13 +50,13 @@ git push origin upstream/master:master --force-with-lease
 ```
 
 ### Add a new pending PR to local
-Edit `.github/workflows/assemble-local.yml` on `master`:
+Edit `.github/workflows/assemble-local.yml` on `dev`:
 - Simple PR (clean commits, no merge commits): add to `PR_CHERRY_PICK`
 - Complex PR (has merge commits mixed in): add to `PR_SQUASH`
 - If the branch was rebased onto another PR branch: use `exclude:base-branch`
 
 ### Remove a PR after upstream merges it
-Delete its entry from `PR_CHERRY_PICK` or `PR_SQUASH` in `assemble-local.yml` on `master`.
+Delete its entry from `PR_CHERRY_PICK` or `PR_SQUASH` in `assemble-local.yml` on `dev`.
 
 ### Submit a new PR to upstream
 Branch from `upstream/master` (not from `local` or `master`):
@@ -66,7 +66,7 @@ git checkout -b feat/my-feature upstream/master
 ```
 
 ### Modify the fork Dockerfile
-Edit `.farhoodlabs/Dockerfile` on `master`. Only modify the production stage — keep base/deps/build stages identical to upstream so diffs are minimal and upstream changes apply cleanly.
+Edit `.farhoodlabs/Dockerfile` on `dev`. Only modify the production stage — keep base/deps/build stages identical to upstream so diffs are minimal and upstream changes apply cleanly.
 
 ## Deployment
 
@@ -75,5 +75,5 @@ Paperclip runs in Kubernetes, not locally. Use `kubectl` to access it. The produ
 ## Key Files
 
 - `.github/workflows/assemble-local.yml` — assembles `local` branch; edit this to manage pending PRs
-- `.farhoodlabs/` — fork overlay; all fork-specific files live here on `master`
+- `.farhoodlabs/` — fork overlay; all fork-specific files live here on `dev` (canonical) and are also kept in sync on `local`
 - `server/package.json` — has an adapter-utils workspace vs canary hack that needs fixing eventually