# Project Research Summary

**Project:** Nexus (fork of Paperclip)
**Domain:** Display-layer fork of a TypeScript AI agent orchestration monorepo
**Researched:** 2026-03-30
**Confidence:** HIGH

## Executive Summary

Nexus is a personal-use fork of Paperclip, an open-source AI agent orchestration platform. The project scope is strictly display-layer: rename corporate metaphors (Company, CEO, Board) to solo-developer vocabulary (Workspace, Project Manager, Owner), replace the onboarding wizard with a zero-friction root-directory-picker flow, and ship predefined PM and Engineer agent templates. No engine changes, no schema changes, no route changes. Every functional capability is inherited from upstream — the work is entirely in what the product communicates to its operator.

The recommended approach is rebase-over-upstream with a `[nexus]` commit prefix convention, all fork-specific strings isolated in a new `packages/branding/` package and `ui/src/lib/nexus-labels.ts` file, and a Vite alias to redirect the `OnboardingWizard` import to a fully Nexus-owned replacement component. This architecture concentrates the entire mutable surface in new files that upstream will never create, minimising rebase conflict exposure to a small number of well-understood lines in five upstream files.

The principal risk is accidental scope creep into Zone B (code identifiers) or Zone C (dual-purpose stored DB values) during rename work. A single naive find-replace that touches `companyService`, `"ceo"` in `AGENT_ROLES`, or `/api/companies` routes would shatter rebasability and require a recovery that undoes the entire rename. The mitigation is a strict three-zone taxonomy applied file-by-file from the first commit, combined with a pre-commit hook enforcing the `[nexus]` prefix and a weekly rebase cadence.

---

## Key Findings

### Recommended Stack

Paperclip's existing stack is retained without alteration. The fork adds one new workspace package (`@paperclipai/branding`) and two new UI files (`nexus-labels.ts`, `branding.css`) — all additions, no modifications to `package.json` names, tsconfig paths, or Tailwind config structure.

The only tooling additions are: `git rerere` enabled in the repo config to auto-replay recurring conflict resolutions, and a `vite.config.ts` `define` block for build-time product name injection into static HTML. Both are zero-dependency changes.

**Core tools:**
- `git rebase upstream/master` + `[nexus]` prefix convention: fork sync strategy — standard practice used by git-for-windows, VSCodium, microsoft/git
- `git range-diff` + `git rerere`: rebase verification and auto-resolution — official Git tooling, no third-party risk
- `packages/branding/` (`@paperclipai/branding`): single string mutation surface — new package in existing namespace, zero import-path disruption
- `ui/src/lib/nexus-labels.ts`: UI-layer label registry — new file, zero upstream conflict risk
- `ui/src/branding.css`: Tailwind v4 CSS custom property overrides — new file, zero upstream conflict risk
- Vite `resolve.alias` for `OnboardingWizard`: build-time component swap — existing vite.config.ts already uses alias syntax

### Expected Features

**Must have (table stakes) — all already exist in upstream, display rename only:**
- Dashboard with live agent status (SSE-backed, Company → Workspace rename)
- Real-time run logs and heartbeat transcript
- Cost visibility per agent (`cost_events` table already tracked)
- Task/issue list with status and sub-task hierarchy
- Agent status indicators (idle/running/paused)
- One-command startup (`nexus run` replacing `paperclipai run`)
- Human approval workflow (approvals table and routes intact)
- Agent configuration page with config revision history
- Scheduled task creation (routines with cron)
- CLI help text using Nexus vocabulary throughout

**Should have (differentiators):**
- Zero-question onboarding — root directory picker, auto-create PM + Engineer agents, no "company name" or "CEO" prompts (highest-impact UX change)
- Predefined agent templates (PM + Engineer) — SOUL.md, AGENTS.md, HEARTBEAT.md, TOOLS.md for each role
- Workspace-first mental model — systematic string audit across all UI and CLI surfaces
- Nexus branding — logo, `<title>`, CLI binary name (`nexus`), favicon
- "Add Agent" dialog with template dropdown replacing the "hire agent" flow
- Human-readable agent directories under user root (`~/RaglanWork/agents/engineer/`)

**Defer (v2+):**
- Full Catppuccin Mocha theme (high visual risk for v1, CSS custom properties make it addable later as a single-file change)
- Telegram Channels integration (separate project scope)
- Recipe Registry plugin (separate project scope)
- Plugin API event renames (`company.created` etc.) — would break existing plugins silently
- MCP connector layer abstraction (upstream adapter system already handles this)

**Critical path for differentiators:** D2 (Agent Templates) → D1 (Zero-Question Onboarding) → D4 (Human-Readable Directories). D3 (Workspace Mental Model), D5 (Branding), and D6 (Add Agent Dialog) can ship in any order alongside or after.

### Architecture Approach

The architecture goal is to confine all fork-specific content to new files that upstream will never create. Two strategies cover every change type: (1) add-only new files for net-new content (zero conflict risk), and (2) minimal inline edits with `// [nexus]` markers on lines that must touch existing upstream files (string changes only, never identifier renames). For the one component requiring substantial structural rewriting (OnboardingWizard), a Vite alias redirects the import to a fully Nexus-owned file, leaving the upstream file untouched and allowing upstream to evolve it freely.

**Major components:**
1. `packages/branding/` (NEW) — canonical vocabulary constants (`VOCAB`, `DISPLAY_ROLE_LABELS`); the only place Nexus display strings are defined
2. `ui/src/lib/nexus-labels.ts` (NEW) — UI-layer label registry imported by components instead of hardcoded strings
3. `ui/src/nexus/OnboardingWizard.tsx` (NEW) — full Nexus onboarding replacement; upstream `OnboardingWizard.tsx` left untouched
4. `server/src/onboarding-assets/pm/` and `engineer/` (NEW) — predefined agent template directories; zero conflict risk as net-new paths
5. `ui/src/branding.css` (NEW) — Tailwind v4 CSS custom property overrides for brand colors
6. `packages/shared/src/constants.ts` (MODIFIED, 1 line) — `ceo: "Project Manager"` in `AGENT_ROLE_LABELS`; the only upstream constants file touched
7. `server/src/home-paths.ts` (MODIFIED, 1 line) — default home dir `".nexus"`
8. `ui/vite.config.ts` (MODIFIED, 1 line) — alias entry redirecting `OnboardingWizard` import

### Critical Pitfalls

1. **Renaming a code identifier that is also a stored DB value** — `"ceo"`, `"hire_agent"`, `"bootstrap_ceo"`, `"board"`, `"company"` are stored in DB rows, not just TypeScript constants. Renaming the constant value silently breaks existing installations (old rows no longer match). Mitigation: rename only the label map value (`ceo: "Project Manager"`), never the key (`ceo`). Grep for any target string in `packages/db/src/schema/` before renaming.

2. **Bulk find-replace contaminating Zone B (code identifiers)** — a naive global replace of "company" touches `companyService`, import paths, and DB schema values alongside JSX strings. Result: hundreds of rebase conflicts in files that should never have been modified. Mitigation: three-zone taxonomy enforced file-by-file; no global find-replace ever.

3. **Upstream rebase cadence drift** — fork conflicts accumulate non-linearly. A two-week gap becomes a four-hour archaeology session. Mitigation: weekly rebase on a fixed schedule, `[nexus]` prefix from the first commit, CI rebase check on a test branch.

4. **Renaming `~/.paperclip` config path without a migration** — existing installations lose all agents, projects, and API keys on next startup if the config path is renamed without a read-both-paths fallback. Mitigation: check `~/.nexus` first, fall back to `~/.paperclip`; implement the pointer-file mechanism before shipping the home dir change.

5. **Partial rename — missing occurrences across 12+ files** — "CEO" appears in at least 12 distinct files. Without an i18n layer there is no compile-time verification that a rename is complete. Mitigation: run `grep -ri "CEO\|company\|board\|hire\|paperclip" ui/src cli/src server/src` after each phase and verify every remaining occurrence is intentional (Zone B/C).

---

## Implications for Roadmap

Based on research, suggested phase structure:

### Phase 1: Foundation and String Infrastructure
**Rationale:** Establishes all new files with zero upstream file touches. Creates the containment structure before any existing file is modified. Safe to rebase at any point. Pre-commit hook and zone taxonomy documented here — if these are not in place before Phase 2, all subsequent work is at risk.
**Delivers:** `packages/branding/`, `ui/src/lib/nexus-labels.ts`, `ui/src/nexus/` directory, `server/src/onboarding-assets/pm/` and `engineer/` skeleton directories, `[nexus]` pre-commit hook, zone taxonomy document in `.planning/`.
**Addresses:** D2 partial (template directories created), D5 partial (branding package scaffold)
**Avoids:** Pitfall 8 (no-prefix commits), Pitfall 2 (Zone B contamination from lack of taxonomy)

### Phase 2: Constants, Labels, and Home Directory
**Rationale:** Touches three upstream files with one-line changes each. These are the lowest-risk upstream file modifications: rarely-changed lines, isolated diffs, immediately verifiable. Completing this phase makes every downstream component able to import correct labels before any component is touched.
**Delivers:** `AGENT_ROLE_LABELS.ceo = "Project Manager"` live, home dir default changed to `.nexus` with read-both-paths fallback, `DISPLAY_ROLE_LABELS` exported from branding package.
**Addresses:** D3 (core vocabulary change), D4 partial (home dir pointer)
**Avoids:** Pitfall 1 (dual-purpose stored values — keys unchanged), Pitfall 4 (config migration — fallback implemented here)

### Phase 3: UI and CLI String Renames
**Rationale:** Surface-area is larger (multiple upstream files) but each change is string-only with `// [nexus]` markers. Individual commits per file keep each rebase conflict isolated and mechanically resolvable. The branding infrastructure from Phases 1–2 must exist before this phase to avoid scattering string definitions.
**Delivers:** All "Company/CEO/Board" display strings replaced with "Workspace/Project Manager/Owner" across `Companies.tsx`, `CompanyRail.tsx`, `CompanySettings.tsx`, `InstanceSidebar.tsx`, `cli/onboard.ts`, `startup-banner.ts`. CLI binary renamed to `nexus` atomically with all instructional copy updated.
**Addresses:** D3 (complete), D5 (complete), D6 partial (dialog strings updated)
**Avoids:** Pitfall 6 (atomic CLI rename), Pitfall 7 (post-phase grep audit), Pitfall 10 (test assertions updated in same commits)

### Phase 4: Onboarding Redesign
**Rationale:** Most complex change goes last. Vite alias approach means upstream `OnboardingWizard.tsx` is never touched and can evolve independently. PM and Engineer template content (written in Phase 1) is wired up here. Onboarding API shape mismatch (workspace name derived from directory basename) must be explicitly resolved.
**Delivers:** `ui/src/nexus/OnboardingWizard.tsx` full replacement (root dir picker, auto-create PM + Engineer agents, one-step flow), Vite alias in `vite.config.ts`, `ceo/` onboarding asset content replaced with PM framing, PM and Engineer template files populated, "Add Agent" dialog updated with template dropdown.
**Addresses:** D1 (complete), D2 (complete), D4 (complete), D6 (complete)
**Avoids:** Pitfall 3 (ceo/ directory name kept, only content replaced), Pitfall 9 (API shape documented and workspace name derived before implementation)

### Phase Ordering Rationale

- New files before upstream file modifications — zero conflict risk for the majority of work
- Constants before components — components can import correct labels from day one
- String renames before onboarding redesign — the vocabulary must be stable before the most complex component is written against it
- Onboarding last — its Vite alias approach is the most architectural change; having it isolated keeps every earlier phase simple and independently rebaseable
- Each phase produces a rebasing-clean state — can sync upstream between any two phases without compound conflicts

### Research Flags

Phases with well-documented patterns (skip `/gsd:research-phase`):
- **Phase 1:** Standard TypeScript monorepo package creation and git hook setup — no research needed
- **Phase 2:** Single-line constant and config path changes — no research needed
- **Phase 3:** Mechanical string replacement with documented taxonomy — no research needed

Phases likely benefiting from deeper research during planning:
- **Phase 4:** The onboarding API shape mismatch (Pitfall 9) needs the `POST /api/companies` contract documented before writing the new wizard. A brief codebase read of `server/src/routes/companies.ts` and the API client should resolve this. Not complex — 30 minutes of reading, not a full research session.

---

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | HIGH | Based on direct codebase inspection of live repo + official Git, Vite, Tailwind v4 documentation |
| Features | HIGH (table stakes), MEDIUM (differentiators) | Table stakes verified from codebase; differentiator prioritization informed by Paperclip product notes and UX research but not validated against actual users |
| Architecture | HIGH | Patterns derived from direct codebase inspection; Vite alias pattern verified against official docs and existing vite.config.ts in the repo |
| Pitfalls | HIGH | Primarily from direct audit of CONCERNS.md and codebase; supplemented by fork maintenance community research |

**Overall confidence:** HIGH

### Gaps to Address

- **OnboardingWizard API contract:** The `POST /api/companies` required fields are not fully documented in research. Before Phase 4 implementation, read `server/src/routes/companies.ts` to determine exactly what fields are required and derive a rule for the workspace name field (likely `basename(rootDir)`).
- **Test suite audit scope:** The pre-rename test audit (Pitfall 10) requires running the grep against the actual test files. The exact count of test files asserting on "CEO" / "company" display strings is not known — this should be done as the first step of Phase 3 execution, not planning.
- **`localStorage` key migration:** Whether to keep `"paperclip.selectedCompanyId"` or migrate it is unresolved. Given it is internal and users never see it, keeping it unchanged is the lowest-risk path and should be the default decision unless there is a specific reason to change it.
- **Catppuccin Mocha theme scope boundary:** The `branding.css` scaffold is included in Phase 1 but full theme is deferred. The exact CSS custom property overrides needed for even minimal brand differentiation (Nexus blue-purple vs Paperclip defaults) should be defined during Phase 3 execution.

---

## Sources

### Primary (HIGH confidence)
- `/Volumes/UsbNvme/agent/.planning/codebase/ARCHITECTURE.md` — direct codebase analysis
- `/Volumes/UsbNvme/agent/.planning/codebase/CONCERNS.md` — direct audit of dual-purpose stored values
- `/Volumes/UsbNvme/agent/.planning/PROJECT.md` — project constraints and scope
- `/Volumes/UsbNvme/repos/nexus/` — live codebase inspection
- [Git range-diff documentation](https://git-scm.com/docs/git-range-diff)
- [Git rerere — Pro Git book](https://git-scm.com/book/en/v2/Git-Tools-Rerere)
- [Vite resolve.alias + define documentation](https://vite.dev/config/shared-options)

### Secondary (MEDIUM confidence)
- [GitHub: Strategies for friendly fork management](https://github.blog/developer-skills/github/friend-zone-strategies-friendly-fork-management/)
- [History-preserving fork maintenance with git](https://amboar.github.io/notes/2021/09/16/history-preserving-fork-maintenance-with-git.html)
- [VSCodium Build System — DeepWiki](https://deepwiki.com/VSCodium/vscodium/2-build-system)
- [Stop Forking Around — Fork Drift in Open Source](https://preset.io/blog/stop-forking-around-the-hidden-dangers-of-fork-drift-in-open-source-adoption/)
- [Designing For Agentic AI: Practical UX Patterns (Smashing Magazine, 2026)](https://www.smashingmagazine.com/2026/02/designing-agentic-ai-practical-ux-patterns/)
- [Tailwind CSS v4 + Vite — CSS custom properties theming](https://medium.com/render-beyond/build-a-flawless-multi-theme-ui-using-new-tailwind-css-v4-react-dca2b3c95510)

### Tertiary (LOW confidence)
- UX claims regarding cognitive load from vocabulary mismatch — reasonable inference, not validated against actual users

---
*Research completed: 2026-03-30*
*Ready for roadmap: yes*
