# 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.