Add worktree bootstrap for local configuration

AGENTS.md

@@ -12,6 +12,23 @@ before live use.
 Files marked `FOUNDATION` require explicit human guidance before editing and
 stricter review. Escalate needed changes rather than editing without authorization.
 
+## Worktree creation
+
+Before creating a worktree, run `git worktree list` and choose the existing
+checkout whose local development configuration should be inherited. Immediately
+after `git worktree add`, run this from the new worktree:
+
+```sh
+scripts/bootstrap-worktree.sh /absolute/path/to/source/checkout
+```
+
+Do not start development before bootstrap completes. The script copies the
+git-ignored `.env.local` without overwriting an existing target, then uses that
+worktree's Hermit proxy to run `bin/pnpm install --frozen-lockfile`. Do not copy
+other ignored paths: Keychain credentials and pnpm's package cache are
+machine-shared, while dependencies and build output are regenerated. Follow the
+per-worktree hook setup in `docs/contributing.md` before committing or pushing.
+
 ## Engineering standard
 
 Before editing, state the intended outcome and non-goals. Read the owning code,

docs/contributing.md

@@ -71,6 +71,21 @@ Both run the development broker with your identity when the public
 `BUZZ_DEV_VIEWER` pin is configured in `.env.local`, and start without live
 identity otherwise; see [the setup and Keychain requirements](../README.md#relay-channels).
 
+After creating a worktree, bootstrap it from the checkout whose local development
+configuration it should inherit:
+
+```sh
+scripts/bootstrap-worktree.sh /absolute/path/to/source/checkout
+```
+
+The idempotent script copies the source checkout's git-ignored `.env.local`
+without overwriting an existing target, then uses the new worktree's Hermit proxy
+to run `bin/pnpm install --frozen-lockfile`. It rejects checkouts from another
+repository. Keychain credentials and pnpm's package cache remain machine-shared;
+do not copy private keys, `node_modules`, build output, `.npmrc`, or other ignored
+files. Install hooks separately as described below so existing custom hooks are
+never silently replaced.
+
 ## Interactive product iteration
 
 While shaping the first version, default to **edit → human tries the running app

scripts/bootstrap-worktree.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+
+set -eu
+
+if [ "$#" -ne 1 ]; then
+  echo "Usage: scripts/bootstrap-worktree.sh /absolute/path/to/source/checkout" >&2
+  exit 2
+fi
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+target=$(git -C "$script_dir" rev-parse --show-toplevel)
+source=$(git -C "$1" rev-parse --show-toplevel)
+target_git=$(git -C "$target" rev-parse --path-format=absolute --git-common-dir)
+source_git=$(git -C "$source" rev-parse --path-format=absolute --git-common-dir)
+
+if [ "$source_git" != "$target_git" ]; then
+  echo "Source must be another worktree of this repository: $source" >&2
+  exit 2
+fi
+
+if [ "$source" != "$target" ] && [ -f "$source/.env.local" ]; then
+  if [ -e "$target/.env.local" ]; then
+    echo "Keeping existing .env.local"
+  else
+    cp -p "$source/.env.local" "$target/.env.local"
+    echo "Copied .env.local from $source"
+  fi
+else
+  echo "No .env.local to copy from $source"
+fi
+
+"$target/bin/pnpm" install --dir "$target" --frozen-lockfile