groove-dev 0.17.8 → 0.18.2

package/docs/GUI_DESIGN_SPEC.md

@@ -1,402 +0,0 @@
-# Groove AI — GUI Design Specification
-### Terminal-Native Visual Control Plane
-
-> The GUI should feel like a terminal that happens to have graphics in it — not a website pretending to be a terminal.
-
----
-
-## Philosophy
-
-This is a TUI-meets-browser hybrid. It runs at `localhost:3141` and is designed to sit inside a terminal multiplexer pane (cmux) alongside real terminal sessions. It should look like it belongs there. No rounded corners on containers, no card shadows, no hover animations, no gradient backgrounds. Think: htop with a React Flow node graph in the center.
-
----
-
-## Color Palette
-
-Based on One Dark Pro. Every color has a purpose.
-
-### Backgrounds
-| Token | Hex | Usage |
-|---|---|---|
-| `--bg-base` | `#24282f` | Main content area / node graph background |
-| `--bg-chrome` | `#282c34` | Sidebar, header bar, panels |
-| `--bg-surface` | `#2c313a` | Buttons, input fields, card surfaces |
-| `--bg-hover` | `#333842` | Button/row hover state |
-| `--bg-active` | `#3a3f4b` | Active/selected button or tab |
-
-### Text
-| Token | Hex | Usage |
-|---|---|---|
-| `--text-primary` | `#abb2bf` | Default body text, labels |
-| `--text-bright` | `#e6e6e6` | Headings, active items, emphasis |
-| `--text-dim` | `#5c6370` | Secondary info, timestamps, hints |
-| `--text-muted` | `#3e4451` | Disabled text, decorative borders |
-
-### Accent / Status
-| Token | Hex | Usage |
-|---|---|---|
-| `--accent` | `#33afbc` | Brand accent — active nav item, selected node border, primary action |
-| `--green` | `#98c379` | Agent active, success states, healthy status |
-| `--amber` | `#e5c07b` | Agent idle, warning, pending approval |
-| `--red` | `#e06c75` | Agent blocked/error, kill actions, conflicts |
-| `--purple` | `#c678dd` | Journalist activity, context rotation events |
-| `--blue` | `#61afef` | Info badges, links, secondary accent |
-
----
-
-## Typography
-
-One font. Everywhere. No exceptions.
-
-```
-font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace;
-```
-
-| Element | Size | Weight | Color |
-|---|---|---|---|
-| Header bar title | 13px | 600 | `--text-bright` |
-| Nav buttons | 12px | 500 | `--text-primary` (inactive), `--text-bright` (active) |
-| Node labels | 12px | 600 | `--text-bright` |
-| Node metadata | 11px | 400 | `--text-dim` |
-| Panel headings | 11px | 600 | `--text-dim`, uppercase, letter-spacing 1.5px |
-| Panel body text | 12px | 400 | `--text-primary` |
-| Timestamps | 10px | 400 | `--text-dim` |
-| Status badges | 10px | 600 | Status color, uppercase |
-
----
-
-## Layout
-
-```
-┌──────────────────────────────────────────────────────┐
-│  HEADER BAR (--bg-chrome, 40px height)              │
-│  [logo]  [Agents] [Tokens] [Teams] [Permissions]    │
-├────────────────────────────────────┬─────────────────┤
-│                                    │                 │
-│         NODE GRAPH                 │   DETAIL PANEL  │
-│         (--bg-base)                │   (--bg-chrome) │
-│                                    │                 │
-│    React Flow canvas with          │   Context for   │
-│    agent nodes and edges           │   selected node │
-│                                    │                 │
-│                                    │                 │
-└────────────────────────────────────┴─────────────────┘
-```
-
-### Header Bar
-- Height: 40px
-- Background: `--bg-chrome`
-- Bottom border: 1px `--text-muted`
-- Logo: Groove infinity icon (16px), left side
-- Nav buttons: right-aligned, evenly spaced
-
-### Node Graph Area
-- Background: `--bg-base`
-- Takes remaining viewport width/height
-- Subtle dot grid pattern: `--text-muted` dots, 20px spacing, 1px size
-- No border, no padding — edge to edge
-
-### Detail Panel (right sidebar)
-- Width: 320px, collapsible
-- Background: `--bg-chrome`
-- Left border: 1px `--text-muted`
-- Shows detail for whatever is selected in the graph
-
----
-
-## Components
-
-### Nav Buttons (Header)
-
-The four main views: **Agents**, **Tokens**, **Teams**, **Permissions**
-
-```
-Inactive:
-  background: transparent
-  color: --text-primary
-  padding: 6px 14px
-  border: none
-
-Hover:
-  background: --bg-hover
-  color: --text-bright
-
-Active:
-  background: --bg-active
-  color: --text-bright
-  border-bottom: 2px --accent (or underline indicator)
-```
-
-No border-radius. These are terminal tabs, not web buttons.
-
-### Agent Nodes (React Flow)
-
-Each node represents one running agent.
-
-```
-┌─────────────────────────┐
-│ ● backend-1             │  ← status dot + agent name
-│ src/api/**              │  ← file scope
-│ claude-code · 45%       │  ← provider + context usage
-└─────────────────────────┘
-```
-
-| Property | Value |
-|---|---|
-| Background | `--bg-surface` |
-| Border | 1px `--text-muted` |
-| Border (selected) | 1px `--accent` |
-| Border-radius | 2px (barely rounded — terminal feel) |
-| Padding | 10px 12px |
-| Width | 200px |
-| Font | 12px for name, 11px for metadata |
-
-**Status dot** (6px circle, left of agent name):
-- `--green` = active
-- `--amber` = idle / waiting
-- `--red` = blocked / error
-- `--purple` = rotating context
-
-**Context usage bar** (optional, bottom of node):
-- Height: 2px
-- Background: `--text-muted`
-- Fill: `--green` (0-60%), `--amber` (60-80%), `--red` (80-100%)
-
-### Edges (connections between nodes)
-
-- Stroke: `--text-muted`
-- Stroke width: 1px
-- Style: straight or step (not bezier — too soft)
-- Animated dash when data is flowing (introduction events, journalist updates)
-
-### QC Supervisor Node (special)
-
-Same structure as agent node but:
-- Border: 1px `--purple`
-- Label prefix: `[QC]`
-- Always positioned at root/top of the tree
-
-### Status Badges
-
-Small inline badges for agent states.
-
-```
-background: rgba(color, 0.12)
-color: status color
-padding: 2px 6px
-font-size: 10px
-font-weight: 600
-text-transform: uppercase
-letter-spacing: 0.5px
-border-radius: 2px
-```
-
-Examples:
-- `ACTIVE` — green bg tint, green text
-- `IDLE` — amber bg tint, amber text
-- `BLOCKED` — red bg tint, red text
-- `ROTATING` — purple bg tint, purple text
-
-### Token Usage View
-
-Replaces the node graph when "Tokens" tab is active.
-
-```
-┌──────────────────────────────────┐
-│ TOKEN USAGE           this session│
-│                                  │
-│ Total          1,247,893         │
-│ Saved (routing)  412,500  (33%) │
-│ Saved (rotation) 289,100  (23%) │
-│                                  │
-│ AGENT BREAKDOWN                  │
-│ ─────────────────────────────── │
-│ backend-1      482,100   38.6%  │
-│ ████████████████░░░░░░          │
-│ frontend-1     391,200   31.3%  │
-│ ██████████████░░░░░░░░          │
-│ database-1     374,593   30.0%  │
-│ █████████████░░░░░░░░░          │
-└──────────────────────────────────┘
-```
-
-Bar charts use block characters or thin divs:
-- Fill: `--accent`
-- Track: `--text-muted`
-- Height: 3px
-
-Numbers right-aligned, monospace tabular. This should look like a terminal stats output, not a web dashboard.
-
-### Teams View
-
-List of saved team configurations.
-
-```
-┌──────────────────────────────────┐
-│ SAVED TEAMS                      │
-│                                  │
-│ > fullstack          4 agents    │
-│   backend, frontend, db, qc     │
-│   saved 2026-04-05               │
-│                                  │
-│ > api-only           2 agents    │
-│   backend, database              │
-│   saved 2026-04-04               │
-└──────────────────────────────────┘
-```
-
-- `>` prefix for each team (terminal-style list marker)
-- Selected team: `--text-bright` text, `--bg-hover` background
-- Load button: inline, right side, `--accent` text
-
-### Permissions / Approvals View
-
-Pending agent actions requiring human approval.
-
-```
-┌──────────────────────────────────┐
-│ PENDING APPROVALS        2       │
-│                                  │
-│ backend-1 wants to:              │
-│ Edit src/middleware/auth.js      │
-│ "Refactoring auth to use JWT"    │
-│ [APPROVE]  [REJECT]    2m ago   │
-│                                  │
-│ frontend-1 wants to:             │
-│ Create src/components/Modal.jsx  │
-│ "Adding confirmation dialog"     │
-│ [APPROVE]  [REJECT]    45s ago  │
-└──────────────────────────────────┘
-```
-
-Action buttons:
-```
-[APPROVE]:
-  background: rgba(--green, 0.12)
-  color: --green
-  border: 1px rgba(--green, 0.2)
-  padding: 4px 10px
-  font-size: 11px
-
-[REJECT]:
-  background: rgba(--red, 0.12)
-  color: --red
-  border: 1px rgba(--red, 0.2)
-  padding: 4px 10px
-  font-size: 11px
-```
-
----
-
-## Detail Panel (Right Sidebar)
-
-Shows context for selected agent node.
-
-```
-┌─────────────────────┐
-│ AGENT DETAIL        │
-│                     │
-│ backend-1           │
-│ Status: ACTIVE      │
-│ Provider: claude    │
-│ Context: 45%        │
-│ ████████░░░░░░░░░░ │
-│ Tokens: 482,100     │
-│ Scope:              │
-│   src/api/**        │
-│   src/middleware/**  │
-│ Spawned: 14:20      │
-│ Peers: frontend-1,  │
-│   database-1        │
-│                     │
-│ RECENT ACTIVITY     │
-│ ─────────────────  │
-│ 14:32 editing       │
-│   auth.js           │
-│ 14:28 introduced to │
-│   frontend-1        │
-│ 14:20 spawned       │
-└─────────────────────┘
-```
-
-- Section headers: `--text-dim`, 11px, uppercase, 1.5px letter-spacing
-- Dividers: single line of `─` chars or 1px `--text-muted` border
-- Key labels: `--text-dim`
-- Values: `--text-primary`
-- Agent name: `--text-bright`, 14px, 600 weight
-
----
-
-## Interaction States
-
-| State | Treatment |
-|---|---|
-| Default | `--bg-surface` background, `--text-primary` text |
-| Hover | `--bg-hover` background, `--text-bright` text |
-| Active/Selected | `--bg-active` background, `--text-bright` text |
-| Focused | 1px `--accent` outline (no glow, no shadow) |
-| Disabled | `--text-muted` text, no hover change |
-
-No transitions longer than 100ms. No easing curves. Instant or near-instant state changes — like a terminal.
-
----
-
-## What NOT To Do
-
-- No border-radius > 2px anywhere
-- No box-shadow anywhere
-- No gradients anywhere
-- No opacity transitions on hover
-- No font-size larger than 14px (exception: token counter numbers)
-- No sans-serif fonts
-- No rounded buttons
-- No icons — use text labels and ASCII where possible (`●`, `>`, `─`, `█`, `░`)
-- No loading spinners — use text like `loading...` or `syncing...`
-- No toast notifications — use inline status text
-- No modals — use the detail panel or inline expansion
-
----
-
-## CSS Variables (copy-paste ready)
-
-```css
-:root {
-  /* Backgrounds */
-  --bg-base: #24282f;
-  --bg-chrome: #282c34;
-  --bg-surface: #2c313a;
-  --bg-hover: #333842;
-  --bg-active: #3a3f4b;
-
-  /* Text */
-  --text-primary: #abb2bf;
-  --text-bright: #e6e6e6;
-  --text-dim: #5c6370;
-  --text-muted: #3e4451;
-
-  /* Status */
-  --accent: #33afbc;
-  --green: #98c379;
-  --amber: #e5c07b;
-  --red: #e06c75;
-  --purple: #c678dd;
-  --blue: #61afef;
-
-  /* Typography */
-  --font: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace;
-}
-```
-
----
-
-## File Reference
-
-- Logo (full): `/groove-logo.png` (800x254, cyan on transparent)
-- Logo (icon): `/favicon.png` (500x500, infinity symbol)
-- Brand accent: `#33afbc`
-- Site: https://grooveai.dev
-- Docs: https://docs.grooveai.dev
-
----
-
-*This spec is the single source of truth for GUI visual design. If it's not in here, don't add it. If it contradicts a mockup, this document wins.*

package/docs/SKILLS-API-SPEC.md

@@ -1,277 +0,0 @@
-# Skills Marketplace API — Build Spec
-
-> Instructions for building the server-side Skills API that powers the GROOVE Skills Store.
-> This API is hosted on the docs/retail site (docs.groovedev.ai).
-
-## Context
-
-GROOVE is an agent orchestration tool. Its GUI has a Skills Store (app-store style) that currently reads from a static `registry.json` file. We need a real API so users can **submit, edit, and sell** their own skills. The GROOVE daemon will fetch from this API instead of the static file.
-
-### What exists today (static files):
-- `https://docs.groovedev.ai/skills/registry.json` — JSON array of all skill metadata
-- `https://docs.groovedev.ai/skills/content/<id>.md` — individual SKILL.md files
-
-### What we're building:
-A REST API that replaces the static files and adds CRUD + author management.
-
----
-
-## Data Model
-
-### Skill
-
-```json
-{
-  "id": "frontend-design",
-  "name": "Frontend Design",
-  "description": "Create distinctive, production-grade frontend interfaces...",
-  "author": "Anthropic",
-  "authorId": "user_abc123",
-  "authorProfile": {
-    "avatar": "https://...",
-    "website": "https://anthropic.com",
-    "github": "anthropics",
-    "twitter": "AnthropicAI",
-    "bio": "Building reliable AI systems"
-  },
-  "category": "design",
-  "tags": ["frontend", "ui", "css", "react"],
-  "roles": ["frontend", "fullstack"],
-  "source": "claude-official",
-  "icon": "P",
-  "contentUrl": "https://docs.groovedev.ai/skills/content/frontend-design.md",
-  "content": "--- (full SKILL.md content) ---",
-  "downloads": 1840,
-  "rating": 4.8,
-  "ratingCount": 124,
-  "price": 0,
-  "featured": false,
-  "status": "published",
-  "version": "1.0.0",
-  "createdAt": "2026-04-01T00:00:00Z",
-  "updatedAt": "2026-04-06T00:00:00Z"
-}
-```
-
-**Categories** (enum): `design`, `quality`, `devtools`, `workflow`, `security`, `specialized`
-
-**Status** (enum): `draft`, `review`, `published`, `rejected`, `unlisted`
-
-**Source**: `claude-official` for Anthropic skills, `community` for user-submitted
-
-### Author / User
-
-```json
-{
-  "id": "user_abc123",
-  "githubId": "12345",
-  "username": "johndoe",
-  "displayName": "John Doe",
-  "avatar": "https://avatars.githubusercontent.com/u/12345",
-  "bio": "Senior UI designer, 10 years experience",
-  "website": "https://johndoe.dev",
-  "github": "johndoe",
-  "twitter": "johndoe",
-  "portfolio": "https://dribbble.com/johndoe",
-  "createdAt": "2026-04-01T00:00:00Z",
-  "skillCount": 3,
-  "totalDownloads": 5200
-}
-```
-
----
-
-## API Endpoints
-
-Base URL: `https://docs.groovedev.ai/api/v1`
-
-### Public (no auth)
-
-#### `GET /skills`
-Returns the full skill registry. This is what the GROOVE daemon fetches on startup.
-
-Query params:
-- `search` — text search on name, description, tags
-- `category` — filter by category
-- `sort` — `popular` (default), `rating`, `newest`, `name`
-- `status` — defaults to `published` only
-- `author` — filter by authorId
-- `limit` — pagination (default 50)
-- `offset` — pagination offset
-
-Response:
-```json
-{
-  "skills": [ ... ],
-  "total": 21,
-  "categories": [
-    { "id": "devtools", "count": 9 },
-    { "id": "quality", "count": 3 }
-  ]
-}
-```
-
-**Important:** The response shape must match what the GROOVE daemon expects. The `skills` array uses the same schema as `registry.json` today. The `content` field should NOT be included in list responses (it's large). Only metadata.
-
-#### `GET /skills/:id`
-Returns a single skill with full metadata.
-
-Response: single skill object (without `content` field)
-
-#### `GET /skills/:id/content`
-Returns the full SKILL.md content for a skill.
-
-Response:
-```json
-{
-  "id": "frontend-design",
-  "content": "---\nname: Frontend Design\n---\n\n..."
-}
-```
-
-#### `GET /skills/registry.json`
-**Backwards compatibility.** Returns the same format as the current static file so older GROOVE versions still work. Just the skills array, no wrapper object.
-
-#### `GET /authors/:id`
-Public author profile.
-
-Response: author object + their published skills
-
----
-
-### Authenticated (requires GitHub OAuth token)
-
-#### Auth Flow
-- GitHub OAuth (standard web flow)
-- User authorizes, we get GitHub profile
-- Create or update user record
-- Return JWT for subsequent API calls
-- GROOVE daemon does NOT handle auth — this is for the web portal / submission flow
-
-#### `POST /skills`
-Submit a new skill.
-
-Body:
-```json
-{
-  "name": "My Awesome Skill",
-  "description": "Does amazing things...",
-  "category": "design",
-  "tags": ["ui", "css"],
-  "roles": ["frontend"],
-  "icon": "A",
-  "content": "---\nname: My Awesome Skill\n---\n\nFull SKILL.md content here...",
-  "price": 0,
-  "version": "1.0.0"
-}
-```
-
-- `id` is auto-generated from slugified `name`
-- `author`, `authorId`, `authorProfile` populated from authenticated user
-- `source` set to `community`
-- `status` set to `draft` initially
-- `downloads`, `rating`, `ratingCount` initialized to 0
-
-Response: created skill object
-
-#### `PUT /skills/:id`
-Edit an existing skill. Author-only.
-
-Body: partial skill object (only changed fields)
-
-Restrictions:
-- Can only edit your own skills
-- Cannot change `id`, `authorId`, `source`, `downloads`, `rating`, `ratingCount`
-- Changing `content` bumps `updatedAt`
-
-#### `DELETE /skills/:id`
-Remove a skill. Author-only. Sets status to `unlisted` (soft delete).
-
-#### `POST /skills/:id/publish`
-Submit a skill for review / publish it.
-- If `price === 0`: auto-publish (set status to `published`)
-- If `price > 0`: set status to `review` (manual review before listing)
-
-#### `PUT /authors/me`
-Update your own author profile.
-
-Body:
-```json
-{
-  "displayName": "John Doe",
-  "bio": "Senior UI designer",
-  "website": "https://...",
-  "twitter": "johndoe",
-  "portfolio": "https://..."
-}
-```
-
----
-
-### Future (Payments — don't build yet, but design schema for it)
-
-- `POST /skills/:id/purchase` — record a purchase
-- `GET /authors/me/earnings` — seller dashboard
-- Stripe Connect for payouts
-- 80/20 revenue share (creator/platform)
-- Price field already in the skill model, just not enforced yet
-
----
-
-## Key Design Decisions
-
-1. **Backwards compatible** — `/skills/registry.json` must keep working as a plain JSON array. The GROOVE daemon currently fetches this on startup. Newer daemon versions will switch to `/api/v1/skills`.
-
-2. **Content separate from metadata** — The `content` (full SKILL.md) is large. Never include it in list/registry responses. Only serve it via `/skills/:id/content`.
-
-3. **Soft deletes** — Never hard-delete skills. Set status to `unlisted`.
-
-4. **Download counting** — Increment on install. The GROOVE daemon will POST to `/skills/:id/install` to record an install (new endpoint, unauthenticated, rate-limited by IP).
-
-5. **Rating** — Not building the rating/review system yet, but the fields are in the schema. We'll add `POST /skills/:id/rate` later.
-
-6. **The 21 Anthropic skills** — Seed the database with these. They have `source: "claude-official"` and `author: "Anthropic"`. They should not be editable via the API.
-
-7. **Validation:**
-   - `name`: 3-100 chars
-   - `description`: 10-500 chars
-   - `content`: must be valid markdown, max 50KB
-   - `category`: must be one of the enum values
-   - `tags`: max 10, each 2-30 chars
-   - `icon`: single character
-   - `price`: >= 0, max 99.99
-
----
-
-## Tech Recommendations
-
-- Whatever fits the existing docs site stack
-- If starting fresh: Node.js + Express or Hono, SQLite or Postgres
-- GitHub OAuth for auth
-- JWT for session tokens
-- Rate limiting on public endpoints (60/min per IP)
-- CORS: allow `localhost:*` (for GROOVE daemon) + `groovedev.ai` origins
-
----
-
-## Install Tracking Endpoint
-
-Add this for download counting (the GROOVE daemon calls this when a user installs a skill):
-
-#### `POST /skills/:id/install`
-Unauthenticated. Rate-limited (1 per skill per IP per hour).
-
-Increments the `downloads` counter.
-
-Response: `{ "downloads": 1841 }`
-
-This replaces the current flow where the daemon downloads from `contentUrl` directly. New flow:
-1. Daemon calls `POST /api/v1/skills/:id/install` to record the install
-2. Daemon calls `GET /api/v1/skills/:id/content` to get the SKILL.md
-3. Daemon saves locally
-
----
-
-## Seed Data
-
-The current `skills-registry.json` in the GROOVE repo has all 21 Anthropic skills with full metadata including downloads, ratings, prices, author profiles, and featured flags. Use this to seed the database.