[nexus] docs(01-02): create zone taxonomy, rebase runbook, and hook installer

- Add .planning/ZONE-TAXONOMY.md classifying all rename targets (DISPLAY/CODE/STORED)
- Add .planning/REBASE-RUNBOOK.md documenting range-diff rebase verification workflow
- Add scripts/install-hooks.sh for post-clone hook reinstallation

.planning/REBASE-RUNBOOK.md

@@ -0,0 +1,83 @@
+# Nexus Rebase Runbook
+
+Step-by-step workflow for rebasing Nexus fork commits onto new upstream Paperclip releases.
+
+## Prerequisites
+
+- `git rerere` enabled: `git config rerere.enabled true`
+- `git range-diff` available (git 2.19+, confirmed 2.39.5 on this machine)
+- Upstream remote configured: `git remote add upstream https://github.com/paperclipai/paperclip.git` (if not already)
+
+## Pre-Rebase Checklist
+
+1. Ensure working tree is clean: `git status`
+2. Fetch upstream: `git fetch upstream`
+3. Record current tip: `git log --oneline -1` (save this SHA as OLD_TIP)
+4. Verify all tests pass before rebase: `pnpm test:run`
+
+## Rebase Procedure
+
+```bash
+# 1. Fetch latest upstream
+git fetch upstream
+
+# 2. Rebase nexus commits onto upstream/master
+git rebase upstream/master
+
+# 3. If conflicts arise:
+#    - git rerere will auto-apply previously recorded resolutions
+#    - For new conflicts: resolve manually, then `git add` + `git rebase --continue`
+#    - rerere automatically records new resolutions for future use
+
+# 4. Verify rebase integrity with range-diff
+#    ORIG_HEAD is the pre-rebase tip (set automatically by git)
+git range-diff upstream/master ORIG_HEAD HEAD
+```
+
+## Post-Rebase Verification
+
+1. **range-diff check:** `git range-diff upstream/master ORIG_HEAD HEAD`
+   - Every nexus commit should show as "equivalent" (minor offset changes only)
+   - Flag any commit showing significant diff changes for manual review
+2. **Test suite:** `pnpm test:run` — all tests must pass
+3. **Type check:** `pnpm typecheck` (if available) or `pnpm -r run typecheck`
+4. **Branding spot check:** `pnpm vitest run --project packages/branding`
+
+## Handling Common Scenarios
+
+### Upstream changed a file we also changed (DISPLAY zone)
+- Most common: string changes in UI components
+- rerere should handle if previously resolved
+- If new: resolve keeping Nexus display string, `git add`, continue
+
+### Upstream added new constants to packages/shared/src/constants.ts
+- Our changes are in `packages/branding/` (separate file) — no conflict expected
+- If AGENT_ROLE_LABELS format changes upstream, update the DISPLAY zone mapping
+
+### Upstream restructured a file entirely
+- range-diff will show the affected nexus commit as "changed"
+- Manually verify the nexus change still applies correctly
+- Update zone taxonomy if file paths changed
+
+## rerere Cache Notes
+
+- Cache lives in `.git/rr-cache/` (not tracked by git)
+- Cache is machine-local — lost on re-clone
+- After a fresh clone, first rebase may require manual resolution
+- Subsequent rebases at the same conflict points will auto-resolve
+
+## Hook Re-installation
+
+After a fresh clone, the commit-msg hook must be reinstalled:
+
+```bash
+# From repo root:
+cp scripts/nexus-commit-msg-hook.sh .git/hooks/commit-msg
+chmod +x .git/hooks/commit-msg
+```
+
+Or using the install script:
+
+```bash
+bash scripts/install-hooks.sh
+```

.planning/ZONE-TAXONOMY.md

@@ -0,0 +1,77 @@
+# Nexus Zone Taxonomy
+
+Classifies every Paperclip-to-Nexus rename target by zone.
+Zones determine which occurrences are safe to change and which must stay unchanged for upstream sync.
+
+**Zones:**
+- **DISPLAY** — User-facing strings safe to rename (UI text, banners, tooltips, help text, button labels)
+- **CODE** — TypeScript identifiers, import paths, route segments, env vars — do NOT touch
+- **STORED** — DB column/table names, stored enum values — do NOT touch
+
+---
+
+## DISPLAY Zone (safe to change in Phases 2-4)
+
+| Target | Location | Current Value | Nexus Value | Phase |
+|--------|----------|---------------|-------------|-------|
+| Company display string in JSX | ~16 UI files in `ui/src/` | "Company" | "Workspace" | 3 |
+| Companies plural in JSX | UI files | "Companies" | "Workspaces" | 3 |
+| CEO display string in JSX | `ui/src/components/agent-config-primitives.tsx`, `AgentProperties.tsx`, etc. | "CEO" | "Project Manager" | 3 |
+| Board display string in JSX | Various UI files | "Board" | "Owner" | 3 |
+| Hire button text | UI dialogs | "Hire" | "Add" | 3 |
+| Fire button text | UI dialogs | "Fire" | "Remove" | 3 |
+| `AGENT_ROLE_LABELS.ceo` value | `packages/shared/src/constants.ts` | `"CEO"` | `"Project Manager"` | 2 |
+| PAPERCLIP ASCII banner | `server/src/startup-banner.ts` | "PAPERCLIP" | "NEXUS" | 2 |
+| PAPERCLIP ASCII banner (CLI) | `cli/src/utils/banner.ts` | "PAPERCLIP" | "NEXUS" | 2 |
+| App title in browser tab | `ui/index.html` or layout | "Paperclip" | "Nexus" | 3 |
+| Top-left logo text | UI layout component | "Paperclip" | "Nexus" | 3 |
+| CLI help text brand name | `cli/src/` command descriptions | "Paperclip" | "Nexus" | 3 |
+| paperclip.ing URL references | `ui/src/pages/CompanyExport.tsx` | "paperclip.ing" | Nexus URL | 3 |
+| Favicon and logo assets | `ui/public/` or assets dir | Paperclip branding | Nexus branding | 3 |
+
+---
+
+## CODE Zone (do NOT touch — upstream sync priority)
+
+| Target | Location | Rationale |
+|--------|----------|-----------|
+| `companyService`, `companyId`, `selectedCompanyId` | Throughout server/ui/cli | TypeScript identifiers — hundreds of import references |
+| `companies` table name | `packages/db/src/schema/` | DB table — migration required to rename |
+| `company_id` FK columns | `packages/db/src/schema/` | DB columns — migration required |
+| `/api/companies` route segment | `server/src/routes/companies.ts` | API contract — client/server must match |
+| `COMPANY_STATUSES` / `CompanyStatus` type | `packages/shared/src/constants.ts` | Upstream shared type — plugin API contract |
+| `@paperclipai/*` package names | All `package.json` files | Import paths throughout monorepo |
+| `PAPERCLIP_*` env vars | Server/CLI config | Breaks existing deployments |
+| `board_api_keys` table / `board` actor type | DB schema, auth code | Auth token format, DB schema |
+| `pcp_board_*` token prefixes | Auth code | Would invalidate issued tokens |
+| `.paperclip.yaml` export format | Import/export code | Upstream compatibility |
+
+---
+
+## STORED Zone (do NOT touch — DB integrity)
+
+| Target | Location | Stored Where | Rationale |
+|--------|----------|-------------|-----------|
+| `"ceo"` in `AGENT_ROLES` | `packages/shared/src/constants.ts` | `agent_role` DB column | Existing rows contain this value |
+| `"hire_agent"` approval type | `packages/shared/src/constants.ts` APPROVAL_TYPES | `approval_type` DB column | Existing approvals reference this |
+| `"approve_ceo_strategy"` | `packages/shared/src/constants.ts` APPROVAL_TYPES | `approval_type` DB column | Existing approvals reference this |
+| `"bootstrap_ceo"` invite type | `packages/shared/src/constants.ts` | `invite_type` DB column | Existing invites reference this |
+| `company_id` FK values | All FK columns | PostgreSQL foreign keys | Data integrity constraint |
+
+---
+
+## Zone Summary
+
+| Zone | Count | Rule |
+|------|-------|------|
+| DISPLAY | ~40 surface points | Safe to rename in Phases 2-4 |
+| CODE | Many hundreds | Never rename — upstream sync priority |
+| STORED | ~8 enum/column values | Never rename — DB integrity |
+
+---
+
+## Decision Rule
+
+When the same term appears in multiple zones (e.g., "ceo" is both STORED as `AGENT_ROLES[0]` and DISPLAY as `AGENT_ROLE_LABELS.ceo` value), classify each occurrence independently. The key stays, only the display value changes.
+
+**Example:** `AGENT_ROLES` contains `"ceo"` (STORED — do not touch). `AGENT_ROLE_LABELS.ceo` has value `"CEO"` (DISPLAY — safe to change to `"Project Manager"`). Both live in the same file (`packages/shared/src/constants.ts`), but the treatment differs per occurrence.

scripts/install-hooks.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Install Nexus git hooks
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cp "$REPO_ROOT/scripts/nexus-commit-msg-hook.sh" "$REPO_ROOT/.git/hooks/commit-msg"
+chmod +x "$REPO_ROOT/.git/hooks/commit-msg"
+echo "Nexus commit-msg hook installed."