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

v1.3 added a full chat interface with streaming, brainstormer workflow, file system, search/branching, and PWA support. v1.4 made Hermes the default local provider with Ollama integration. v1.5 adds smart onboarding with hardware detection, tiered AI providers, and a Personal AI Assistant mode. v1.6 adds a transport-agnostic voice pipeline (Whisper STT + Piper TTS) and a minimal Telegram bridge for phone access.

## 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)
- ✓ Chat Foundation (conversations, messages, rendering, theme) — v1.3
- ✓ Agent Streaming (SSE, agent identity, edit/retry/stop) — v1.3
- ✓ Brainstormer Flow (spec approval, task creation from chat) — v1.3
- ✓ Search, History & Branching (full-text search, bookmarks, branching, export) — v1.3
- ✓ File System (upload/preview/download, git versioning, voice input) — v1.3
- ✓ PWA & Performance (installable, offline, mobile responsive, push notifications) — v1.3
- ✓ Hermes adapter integration (spawn, heartbeat, session, skill sync, cost tracking) — v1.4
- ✓ Ollama detection, model listing, RAM/VRAM recommendations — v1.4
- ✓ Default provider logic (fallback to Hermes when no cloud provider) — v1.4
- ✓ Agent templates working with Hermes runtime — v1.4
- ✓ Dashboard Hermes-specific info (model, VRAM, native skills) — v1.4
- ✓ Mode selection (Personal AI Assistant / Project Builder / Both) — v1.5
- ✓ Hardware detection with pre-built model database (GPU, Apple Silicon, CPU-only) — v1.5
- ✓ Local AI setup via Ollama with RAM-aware model recommendations — v1.5
- ✓ Zero-config cloud via Puter.js (no API keys, no sign-up) — v1.5
- ✓ Multi-step onboarding wizard with skip buttons and summary screen — v1.5
- ✓ Personal AI Assistant with persistent memory, voice, project handoff — v1.5
- ✓ `npx buildthis` CLI entry point with hardware detection — v1.5

### Active

- [ ] Whisper STT pipeline (local, transport-agnostic, language auto-detection, CPU fallback)
- [ ] Piper TTS pipeline (local, multiple voices, <3s response, CPU-only)
- [ ] Voice mode flag on messages (text mode vs voice mode response formatting)
- [ ] Dual output pattern (voice-optimized response + full text with code blocks)
- [ ] Web chat mic button (record, silence detection, waveform UI, auto-send)
- [ ] Web chat audio playback (inline player, auto-play toggle)
- [ ] Voice mode toggle setting (text only / voice input / full voice)
- [ ] Telegram bridge — single bot, text + voice relay, agent prefixing
- [ ] Onboarding STT/TTS hardware detection and voice enable step

### 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
- Per-agent Telegram bots — replaced by Command Center agent visualization
- GSD question formatting for Telegram — replaced by Command Center rich elements
- Deep Telegram ↔ web chat sync — replaced by Postgres bus
- Telegram threads/topics/inline keyboards — thin bridge only
- Voice call / real-time audio streaming — future consideration
- Wake word detection ("Hey Nexus") — 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). ~1054 TS/TSX files.

**v1.3 additions:** Full chat system (ChatPanel, ChatMessage, ChatInput, ChatConversationList), agent streaming (SSE, useStreamingChat), brainstormer workflow (spec cards, handoff, status updates), file system (upload, preview, git versioning, voice input), PWA (service worker, offline queue, install prompt, push notifications, mobile responsive layout).

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

**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 |
| ChatPanel as hub component | Central orchestrator for all chat features (streaming, files, offline, mobile) | ✓ Good |
| Cache-first SW strategy | Faster cached loads; API calls stay network-only | ✓ Good |
| IndexedDB offline queue (not SW) | Simpler than SW↔main message passing; idb library handles it | ✓ Good |
| React.lazy for all pages | 37 pages lazy-loaded; main bundle stays manageable | ✓ Good |
| MobileChatView as separate component | Full-screen mobile experience; responsive breakpoint at 768px | ✓ Good |

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

## Current Milestone: v1.6 Voice Pipeline + Minimal Message Bridge

**Goal:** Transport-agnostic voice pipeline (Whisper STT + Piper TTS) integrated into web chat, plus a minimal Telegram bridge for phone access. Voice infrastructure designed to survive v2.2 Command Center migration.

**Target features:**
- Whisper STT pipeline (local, transport-agnostic, language auto-detection, CPU fallback)
- Piper TTS pipeline (local, multiple voices, <3s response, CPU-only)
- Voice mode flag + dual output pattern (voice-optimized + full text)
- Web chat mic button with recording, silence detection, waveform UI
- Web chat audio playback (inline player, auto-play toggle)
- Voice mode toggle (text only / voice input / full voice)
- Minimal Telegram bridge — single bot, text + voice relay, agent prefixing
- Onboarding STT/TTS hardware detection

---
*Last updated: 2026-04-03 after v1.6 milestone start*
