diff --git a/README.md b/README.md
index d37f45d..c33b3aa 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,5 @@
 # InstaArchive Viewer
 
-> [!CAUTION]
-> ## This branch must not be published to GitHub
->
-> You are on **`tooling`**. It is the only branch that still contains the
-> archive-fetching scripts and their docs, and those name things `main` was
-> rewritten to remove:
->
-> - the fetch host's **public IP** (`docs/gallery-dl.md`)
-> - the browser profile the session cookie is read from
-> - the NAS archive path
-> - the **list of Instagram accounts being archived**
->
-> On 2026-08-20 `main`'s entire history was rewritten with `git filter-repo`,
-> the GitHub repo was deleted and recreated, and 22 container images were
-> pruned from ghcr — all to remove exactly this material from public view.
-> **One push of this branch to GitHub undoes all of it**, and the second
-> cleanup would be harder than the first: force-push residue stayed reachable
-> by SHA until the repo itself was deleted.
->
-> Guards in place, neither of them foolproof:
->
-> - `.git/hooks/pre-push` rejects any ref but `main`/tags to the GitHub remote.
->   It is **local and unversioned** — a fresh clone does not have it.
-> - `git config remote.github.push refs/heads/main:refs/heads/main`.
->
-> Recreate both after cloning. `origin` is gitea and is the right default for
-> everything; GitHub only ever needs `main` and the current release tag.
->
-> *This block exists only on `tooling`. If a merge from `main` ever conflicts
-> here, keep both sides — the warning is not something `main` deleted.*
-
-
 A high-performance React PWA for browsing archived Instagram data with a native-feeling interface. Supports both official Instagram exports and Instaloader archives.
 
 ## Features
diff --git a/TOOLING.md b/TOOLING.md
new file mode 100644
index 0000000..a1a1dd0
--- /dev/null
+++ b/TOOLING.md
@@ -0,0 +1,94 @@
+# Tooling branch
+
+> [!CAUTION]
+> ## This branch must not be pushed to GitHub
+>
+> `tooling` is the only branch that still contains the archive-fetching
+> scripts and their docs, and those name things `main` was rewritten to
+> remove:
+>
+> - the fetch host's **public IP** (`docs/gallery-dl.md`)
+> - the browser profile the session cookie is read from
+> - the NAS archive path
+> - the **list of Instagram accounts being archived**
+>
+> On 2026-08-20 `main`'s entire history was rewritten with `git filter-repo`,
+> the GitHub repo was deleted and recreated, and 22 container images were
+> pruned from ghcr — all to get exactly this material out of public view.
+> **One push of this branch to GitHub undoes all of it.**
+>
+> A second cleanup would be harder than the first: after a force-push the old
+> commits stayed reachable by raw SHA, and only deleting the repository
+> outright removed them.
+
+## Remotes
+
+| remote | what goes there |
+|---|---|
+| `origin` → gitea | everything: `main`, `tooling`, tags, backups |
+| `github` | **`main` and the current release tag only** — it exists to run the CI/CD image build |
+
+The other 22 release tags stay on gitea. Pushing them all to GitHub triggers
+one container build per tag, because each tag carries its own workflow file.
+
+## Guards — recreate these after a fresh clone
+
+Neither guard is versioned, so a new clone has **no protection at all**:
+
+```sh
+git config remote.github.push refs/heads/main:refs/heads/main
+
+cat > .git/hooks/pre-push <<'HOOK'
+#!/bin/sh
+remote_url="$2"
+case "$remote_url" in *github.com*) ;; *) exit 0 ;; esac
+while read -r _ _ remote_ref _; do
+  [ -z "$remote_ref" ] && continue
+  case "$remote_ref" in
+    refs/heads/main|refs/tags/*) ;;
+    *) echo "pre-push: refusing to push '$remote_ref' to GitHub." >&2; exit 1 ;;
+  esac
+done
+exit 0
+HOOK
+chmod +x .git/hooks/pre-push
+```
+
+Decide on the **remote** ref, not the local one: a delete push sends
+`(delete)` as the local ref, and an earlier version of this hook rejected
+every deletion because of it.
+
+## What lives here
+
+| path | what it is |
+|---|---|
+| `scripts/gdl-sync.py` | the gallery-dl fetcher; replaced JD2 for the ARTMS profiles |
+| `scripts/test_gdl_sync.py` | its tests |
+| `scripts/jd2-sync.ts` | JDownloader `.crawljob` generator, still used elsewhere |
+| `docs/gallery-dl.md` | the measurements behind every option in the fetcher — **read before changing pacing** |
+| `docs/jdownloader.md` | the older JD2 flow |
+| `docs/artms-instagram-accounts.txt` | the profile list passed to `--urls-file` |
+
+## Commands
+
+```sh
+# fetch: always --dry-run first; it prints the plan and the publish step
+./scripts/gdl-sync.py --index https://instaarchive.ergosteur.com \
+    --staging <dir> --publish <user>@<nas>:<archives> \
+    --archive-db <db> --urls-file artms_account_links.txt --abort 50 --dry-run
+
+# crawljobs (no npm script — package.json is kept identical to main)
+npx tsx scripts/jd2-sync.ts --archives <dir> --dry-run
+```
+
+Run the fetcher from the host whose public IP matches the browser the cookie
+came from. `--abort 50` is the routine setting; omit it for a full sweep that
+also catches edited carousels.
+
+## Why there is no CLAUDE.md entry for any of this
+
+`CLAUDE.md`, `README.md` and `package.json` are kept **byte-identical** to
+`main` so that merging `main` into `tooling` never conflicts. The earlier
+attempt put tooling notes in `CLAUDE.md` and a `jd2` script in `package.json`;
+because `main` had *deleted* those lines, every merge re-applied the deletion.
+Keep branch-specific documentation in this file, which `main` does not have.