feat(config): worktree-setup helper + skill notes for worktree gotchas

tooling/worktree-setup <branch>: one command to create a usable worktree —
adds it under the gitignored .worktrees/, symlinks .venv (so make/python
tooling resolves .venv/bin/python), relies on the post-checkout hook for the
pql --vault rebuild, and prints the in-worktree reminders. Tested end-to-end
(venv linked, pql.db populated on create).

whats-next §3c now calls the helper and documents the three in-worktree
gotchas (pql --vault, tea-from-main, read-only content agents); tea-cli.md
notes tea must run from the main checkout.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tooling/worktree-setup

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# worktree-setup — create a git worktree that's immediately usable.
+#
+# Collapses the /whats-next §3c ritual into one command. A bare
+# `git worktree add` leaves two things broken that bit the Layer-5 batch:
+#   1. no `.venv` in the worktree, so `make test-tooling` / `make regen-db` /
+#      any python tooling can't find `.venv/bin/python`;
+#   2. (fixed separately in .config/hooks/post-checkout) pql resolving the
+#      worktree's `.git` *file* to the MAIN checkout — the post-checkout hook
+#      now passes `--vault`, so this script relies on it for the pql rebuild.
+#
+# This script adds the worktree under the repo's gitignored `.worktrees/`
+# (never the parent dir — outside the permission sandbox), symlinks the venv,
+# and prints the worktree path + the in-worktree reminders.
+#
+# Usage:  tooling/worktree-setup <branch-name> [<start-point>]
+#         (run from the MAIN checkout, not a linked worktree)
+set -euo pipefail
+
+branch="${1:?usage: tooling/worktree-setup <branch-name> [<start-point>]}"
+start="${2:-HEAD}"
+
+repo_root="$(git rev-parse --show-toplevel)"
+if [ -f "$repo_root/.git" ]; then
+    echo "worktree-setup: run this from the MAIN checkout, not a worktree" >&2
+    exit 1
+fi
+
+wt_dir="$repo_root/.worktrees/$branch"
+if [ -e "$wt_dir" ]; then
+    echo "worktree-setup: $wt_dir already exists — reuse it or 'git worktree remove' it first" >&2
+    exit 1
+fi
+
+# The post-checkout hook (.config/hooks/post-checkout) fires here and rebuilds
+# the new worktree's pql.db via `pql --vault <worktree>`.
+git worktree add "$wt_dir" -b "$branch" "$start"
+
+# Symlink the venv — worktrees don't copy it and a fresh per-worktree venv is
+# wasteful (the main one is identical). Makes `.venv/bin/python` resolve so the
+# Makefile's VENV_PY and every python tool work inside the worktree.
+if [ -d "$repo_root/.venv" ] && [ ! -e "$wt_dir/.venv" ]; then
+    ln -s "$repo_root/.venv" "$wt_dir/.venv"
+    echo "  linked .venv -> $repo_root/.venv"
+fi
+
+echo "worktree ready: $wt_dir"
+echo "  reminders: pql in this worktree needs --vault \"$wt_dir\" (FR-4);"
+echo "             tea commands run from the main checkout (go-git can't read a linked worktree)."