feat(copilot): canonical copilot-instructions.md + sync script (#115)

## Summary

Ships the canonical \`.github/copilot-instructions.md\` that GitHub
Copilot reads for code review, Chat, and inline generation. Applies to
macbook-dev-setup's own reviews immediately; sibling repos
(mojwang.tech, ihw) sync via the new script and ship separate follow-up
PRs.

## Why canonical + sync (not symlink)

GitHub reads \`.github/copilot-instructions.md\` from each repo's own
blob server-side — symlinks outside the repo don't resolve. Pattern
mirrors existing \`sync-agentic.sh\` (canonical in macbook-dev-setup,
discovery from \`\$SECOND_BRAIN_HOME/repos/personal\`) but copies
instead of symlinking.

## Canonical scope — universal discipline only

After a mid-draft design review, the file deliberately stays out of
project-specific voice. Each repo owns its own tone via its own
\`CLAUDE.md\`. This canonical covers:

- **Review focus:** silent cached failure modes, cache-key consistency,
doc/code drift, defense-in-depth on user-facing paths, duplication and
magic numbers, security + payment-hook adjacency.
- **Universal discipline:** Conventional Commits, <200 LOC/commit, no
\`Co-Authored-By Claude\` tags, PR title/body conventions.
- **Explicit skip list:** AI Gateway migration (Tier 2.1 deferred),
generic "consider adding tests," style-only nits, taste renames.
- **Explicitly out of scope:** project voice — reviewed against each
repo's own stated conventions.

## Sync script

\`scripts/sync-copilot-instructions.sh\`:
- \`set -euo pipefail\`, shellcheck clean
- Auto-discovers sibling repos under
\`\$SECOND_BRAIN_HOME/repos/personal\` that have a \`.github/\`
directory; skips macbook-dev-setup itself
- \`--repo <path>\` arg to target a specific repo
- Idempotent (unchanged-file detection via \`cmp\`)
- Copies, not symlinks — target repos commit their own file

## Pair with a branch ruleset for full auto-assignment

Per the current GitHub docs, auto-requesting Copilot review on every PR
requires a branch ruleset (Settings → Rules → Rulesets → New branch
ruleset → \"Automatically request Copilot code review\"). That's a
GitHub UI step I can't do via PR — enable it alongside merging this.
Together: ruleset = auto-assigned reviewer, this file = house rules
loaded into the review.

## Follow-up PRs (not in this one)

- mojwang.tech — run \`sync-copilot-instructions.sh\`, commit the
resulting \`.github/copilot-instructions.md\`
- ihw — same

Dry-run verified: the script finds both sibling repos and copies
cleanly.

Author: mojwang

.github/copilot-instructions.md

@@ -0,0 +1,81 @@
+# Copilot instructions
+
+Canonical `.github/copilot-instructions.md` — applies to Copilot code review, Chat, and inline generation in this repo. Synced to sibling repos via `scripts/sync-copilot-instructions.sh`. Single source of truth; edit here, re-sync downstream.
+
+## Project context
+
+For repo-specific context (stack, conventions, architectural decisions, voice), read the repo's own `CLAUDE.md`, `README.md`, or equivalent. Review guidance below applies universally — review each PR against the *repo's* stated conventions, not patterns from other sibling repos.
+
+## Canonical source
+
+This file is synced from `macbook-dev-setup/.github/copilot-instructions.md` via `macbook-dev-setup/scripts/sync-copilot-instructions.sh`. Edit the canonical; re-sync downstream. Don't edit the copy in a sibling repo without also editing the canonical, or the next sync overwrites the local change.
+
+## Review focus
+
+When reviewing a PR, prioritize these concerns in roughly this order.
+
+### Silent or cached failure modes
+- A `catch` that returns an empty / default value inside anything wrapped in `unstable_cache`, React `cache()`, or similar memoization. Once cached, the empty state persists until explicit invalidation. Flag it — suggest a cache-boundary split (throw on error from the cached layer; handle fallback uncached).
+- Swallowed errors without logging, or logging without enough context to distinguish sources.
+- `try/catch` around code that probably shouldn't fail — often papers over a real bug.
+
+### Cache correctness
+- Two cache layers keyed on different normalizations of the same input (e.g. React cache on raw string, `unstable_cache` on sliced string). Both layers must key on the same normalized value.
+- Heavy fields (embeddings, large blobs) in a cached projection when consumers don't read them. Flag as cache-payload bloat; suggest explicit column selection.
+- Tags referenced in `revalidateTag(...)` with no queries that actually set the tag — dead code.
+
+### Docs ↔ code drift
+- Comments / docstrings / PR descriptions that misdescribe actual behavior. Call out specific divergences: "doc says X, code does Y — pick one."
+- Stale references to functions, files, or line numbers that have moved. Cite the current location.
+- Claims of "deduped," "normalized," "validated," etc. that aren't actually enforced in code.
+
+### Defense-in-depth on user-facing paths
+- `useSearchParams().get()` already returns decoded values; calling `decodeURIComponent` again is redundant AND throws `URIError` on malformed percent-encoding.
+- Bash scripts without `set -euo pipefail` or equivalent.
+- Bash flag parsing that references `$2` without guarding against end-of-args (crashes with `set -u`).
+- Shell command construction where user input flows into `eval`, `path.resolve`, or subshell args without validation.
+
+### Duplication and magic numbers
+- Literal numbers that appear in multiple files (`3600`, `2000`, etc.) — usually belong in a named constant.
+- Patterns copy-pasted across files with identical bodies — usually belong in a shared helper.
+- Config scattered across files when one module could own it (e.g., cache timings).
+- **Hotfix discipline:** when a PR fixes a bug in file A, check whether the same pattern exists in neighbor files B and C. Flag the scope.
+
+### Security + safety
+- Secrets or API keys in client-bundled code, committed `.env` files, or agent frontmatter.
+- `Bash` commands that touch paid services (Stripe, x402, Browserbase, parallel.ai, tempo) without the `CLAUDE_ALLOW_PAYMENTS=1` escape valve — the payment-safety hook exists for a reason.
+- Admin DB creds (`DATABASE_URL_ADMIN`) in `.env.local` — they belong in `.env.sync-vault.local`.
+
+## Universal discipline (applies to every repo this file is synced to)
+
+- **Commit format:** Conventional Commits — `type(scope): description`. Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
+- **Small commits:** aim for <200 LOC per diff. Larger is sometimes right, but call out the reason in the commit body.
+- **No `Co-Authored-By` Claude tags** in commits or PRs. No "Generated with Claude Code" footers.
+- **PR titles** are the TL;DR; detail goes in the body.
+- **PR bodies** include a Test plan with specific, runnable checks — not "verified locally" without saying what was verified.
+
+## Project-specific voice and style
+
+This file does not prescribe voice. Each repo owns its own tone:
+- Writing / comments / PR bodies should match the repo's existing CLAUDE.md or equivalent style guide.
+- If a repo's style is silent on a point, follow the surrounding code's idiom, not a preference from another repo.
+- Don't suggest style edits purely on voice grounds when the surrounding code is consistent with itself.
+
+## Skip (don't suggest these)
+
+- **AI Gateway migration** (Tier 2.1). Direct `openai` imports in `src/db/queries/related.ts`, `scripts/sync-vault.ts` are known and deferred — stop flagging them as a recommendation.
+- **Generic "consider adding tests"** without naming the specific behavior gap the new test would close.
+- **Style-only nits** in files the PR didn't change.
+- **Renaming for taste** unless it prevents a future conflict or bug.
+- **Introducing new runtime dependencies** to replace a small amount of custom code.
+- **Vercel-specific "migrate to X" advice** unless X is a current, non-deprecated product.
+
+## What good feedback looks like
+
+Concrete, cites file + line, suggests a specific fix, explains the failure mode it prevents. Example: *"`getNoteBySlugCached` uses `.select()` (all columns) including the 1536-dim embedding vector — ~12KB per cached row. Consider selecting only the 8 fields `/mind/[slug]/page.tsx` reads, because the embedding is never consumed by callers."*
+
+Not: *"Consider narrowing the column selection."*
+
+## When in doubt
+
+If you can't decide whether to flag something, err toward naming the specific concrete risk and letting the author judge. Vague concerns ("this could be clearer") create review noise; specific ones ("line 47 swallows a network error that was previously surfaced") earn their place.

scripts/sync-copilot-instructions.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# sync-copilot-instructions.sh — Copy the canonical copilot-instructions.md
+# to a target repo's .github/ directory.
+#
+# Unlike sync-agentic.sh (which symlinks), this script COPIES because
+# GitHub reads .github/copilot-instructions.md server-side from each
+# repo's own blob — symlinks outside the repo don't resolve. Each target
+# repo commits its own copy.
+#
+# Usage:
+#   sync-copilot-instructions.sh                   # auto-discover siblings
+#   sync-copilot-instructions.sh /path/to/repo     # single target
+#
+# Auto-discovery walks $SECOND_BRAIN_HOME/repos/personal/*/ and copies
+# the canonical into any repo that has a .github/ directory. Skips
+# macbook-dev-setup itself (it IS the canonical).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MACBOOK_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CANONICAL="$MACBOOK_ROOT/.github/copilot-instructions.md"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+if [[ ! -f "$CANONICAL" ]]; then
+    echo -e "${RED}Canonical not found: $CANONICAL${NC}" >&2
+    exit 1
+fi
+
+# Allow override of the sibling-discovery root. Defaults match the same
+# env var sync-agentic.sh uses, so both scripts share one config point.
+# shellcheck disable=SC1091
+source "$MACBOOK_ROOT/.personal/config.sh" 2>/dev/null || true
+ROOT="${SECOND_BRAIN_HOME:-$HOME/ai/workspace/claude}/repos/personal"
+
+copy_to() {
+    local target_repo="$1"
+    local target_dir="$target_repo/.github"
+    local target_file="$target_dir/copilot-instructions.md"
+
+    if [[ ! -d "$target_repo" ]]; then
+        echo -e "${RED}✗ $target_repo — not a directory${NC}" >&2
+        return 1
+    fi
+
+    if [[ "$(cd "$target_repo" && pwd)" = "$MACBOOK_ROOT" ]]; then
+        # Canonical lives here; nothing to copy.
+        return 0
+    fi
+
+    mkdir -p "$target_dir"
+
+    if [[ -f "$target_file" ]] && cmp -s "$CANONICAL" "$target_file"; then
+        echo -e "${GREEN}✓${NC} $target_repo (unchanged)"
+        return 0
+    fi
+
+    cp "$CANONICAL" "$target_file"
+    echo -e "${GREEN}✓${NC} $target_repo (copied)"
+}
+
+if [[ $# -gt 0 ]]; then
+    # Explicit target(s): copy to each and exit.
+    rc=0
+    for target in "$@"; do
+        copy_to "$target" || rc=$?
+    done
+    exit "$rc"
+fi
+
+# Auto-discover: any repo with .github/ directory under personal/
+if [[ ! -d "$ROOT" ]]; then
+    echo -e "${YELLOW}Discovery root not found: $ROOT${NC}" >&2
+    echo "Set SECOND_BRAIN_HOME or pass an explicit target." >&2
+    exit 1
+fi
+
+echo "Syncing copilot-instructions.md from: $CANONICAL"
+echo "Discovery root: $ROOT"
+echo
+
+rc=0
+for repo in "$ROOT"/*/; do
+    repo="${repo%/}"
+    if [[ -d "$repo/.github" ]]; then
+        copy_to "$repo" || rc=$?
+    fi
+done
+
+if [[ $rc -ne 0 ]]; then
+    echo -e "${RED}Some copies failed.${NC}" >&2
+fi
+exit "$rc"