# Nexus

## What This Is

Nexus is a personal fork of Paperclip (MIT, v2026.318.0) that reframes the "companies with CEOs" corporate metaphor as "workspaces with agents." It's a project orchestration tool for a solo developer (Mikkel) managing AI agents across personal and professional projects. The fork stays mergeable with upstream by limiting changes to the display layer (UI strings, CLI output, agent templates, documentation) while leaving DB schema, API routes, code identifiers, and token formats unchanged.

## Core Value

A fresh onboard asks for ONE thing (root directory), auto-creates PM + Engineer agents, and drops you in the dashboard — no company names, missions, or corporate language anywhere.

## Requirements

### Validated

- Existing Paperclip agent orchestration engine (heartbeats, task lifecycle, adapters)
- Plugin system with worker isolation and host/worker RPC
- Multi-adapter support (Claude Code, Codex, Cursor, Gemini, OpenCode, Pi, Hermes)
- Issue/task management with sub-issues, priorities, assignments
- Project entity (groups issues, lead agent, git repo integration)
- Execution workspaces with git worktree isolation
- Cost tracking and budget enforcement
- Routine/cron scheduled task creation
- Real-time SSE updates to UI
- CLI tooling (onboard, run, doctor, configure, client commands)
- Company import/export portability
- Board authentication (local_trusted + authenticated modes)

### Active

- [ ] Onboarding redesign: root directory picker, auto-create PM + Engineer, skip to dashboard
- [ ] Terminology rename (display only): Company→Workspace, CEO→Project Manager, Board→Owner, Hire→Add, Fire→Remove, Paperclip→Nexus
- [ ] Predefined agent templates: PM and Engineer with sensible AGENTS.md, HEARTBEAT.md, SOUL.md, TOOLS.md
- [ ] Directory restructure: everything under user-chosen root, no ~/.paperclip/, human-readable agent dirs
- [ ] ~/.nexus pointer file mechanism (single file with root path)
- [ ] UI overhaul: Nexus branding, sidebar renames, dashboard cleanup, agent config page cleanup
- [ ] New Agent dialog: "Add Agent" button, predefined templates dropdown
- [ ] CLI output strings updated (paperclipai branding → nexus branding where display-only)

### Out of Scope

- DB schema renames (companies table, company_id columns) — upstream sync priority
- API route path changes (/api/companies stays) — upstream sync priority
- TypeScript identifier renames (companyService, boardAuthService etc.) — upstream sync priority
- Package name renames (@paperclipai/* stays) — upstream sync priority
- Environment variable renames (PAPERCLIP_* stays) — upstream sync priority
- Token prefix changes (pcp_board_* stays) — would invalidate issued tokens
- Plugin API contract changes (company.created events, companies.read capability) — breaks plugins
- .paperclip.yaml export format rename — breaks upstream import compatibility
- Recipe Registry plugin — separate project
- Catppuccin Mocha full theme — stretch goal, not v1
- Telegram Channels integration — future
- NPM reverse proxy — future
- Danish business integrations — future
- Multi-workspace support — works via existing multi-company feature, just renamed

## Context

**Upstream:** [paperclipai/paperclip](https://github.com/paperclipai/paperclip) — MIT licensed
**Fork repo:** /Volumes/UsbNvme/repos/nexus/ (origin: git.georgsen.dk/mikkel/nexus)
**Working directory:** /Volumes/UsbNvme/agent/

**Codebase:** TypeScript monorepo (pnpm workspaces). Server (Express), UI (React/Vite), CLI (Commander.js), packages (db/shared/adapter-utils/adapters), plugins (SDK + examples).

**Key naming collision resolved:** Paperclip already has a `Project` entity (groups issues, has lead agent, git repo). Original PRD renamed Company→Project but that collides. Decision: Company→Workspace in display layer. Existing Project entity stays unchanged.

**Rename strategy:** Display-only. All user-facing surfaces (UI strings, CLI output, agent template content, error messages, documentation) get renamed. All code-level identifiers, DB schema, API routes, env vars, token prefixes stay as upstream for merge compatibility.

**Existing "Project" in Paperclip:** Projects live under a Company (now displayed as "Workspace"). A Workspace contains Projects, which contain Issues. This maps cleanly to Nexus's mental model.

**Fork maintenance:** [nexus] commit prefix for all Nexus changes. Periodic `git rebase upstream/master` to stay current. Display-only changes minimize conflict surface.

## Constraints

- **Upstream sync**: All changes must be display-layer only to allow `git rebase upstream/master` with minimal conflicts
- **Deploy target**: Mac Mini M4 only, local_trusted mode, single user
- **No data migration**: No changes to DB tables, columns, stored enum values, or migration files
- **Forgejo**: Push to git.georgsen.dk/mikkel/nexus (SSH port 2222)

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Company → Workspace (not Project) | Paperclip already has a Project entity; naming collision | -- Pending |
| Display-only renames | Upstream sync priority; minimize merge conflicts | -- Pending |
| Keep all @paperclipai/* package names | Thousands of import statements; mechanical but huge merge conflict surface | -- Pending |
| Keep API routes (/api/companies) | UI translates on client side; server stays upstream-compatible | -- Pending |
| Keep DB schema unchanged | No migrations, no data migration, clean upstream rebase | -- Pending |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd:transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd:complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state
5. **Post-milestone upstream rebase** (see below)

## Post-Milestone Upstream Rebase (Nexus-Specific)

After every `/gsd:complete-milestone`, perform an upstream rebase before starting the next milestone. This keeps conflicts small and manageable — upstream Paperclip is active (120+ commits since fork).

**Steps:**
1. `git fetch upstream master` — fetch latest upstream
2. `git rebase upstream/master` — rebase nexus/main onto upstream
3. Resolve conflicts: merge upstream content into Nexus vocabulary (don't just delete upstream additions)
4. `pnpm dev` — verify build still works after rebase
5. `git push origin nexus/main --force-with-lease` — push to Forgejo (git.georgsen.dk)
6. Log rebase result in STATE.md: commits behind before, conflicts resolved count, build status

**Why:** Waiting too long means compound conflicts. Each milestone boundary is a natural sync point — code is tested, tagged, and stable.

**Autonomous mode:** The autonomous workflow MUST check for this section and run the rebase after `complete-milestone` returns, before starting the next milestone.

---
*Last updated: 2026-04-01 after v1.2.1 milestone*
