moving

2026-09-02 10:10:29 +02:00
commit 0c3e2ead3b
3841 changed files with 970576 additions and 0 deletions
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -0,0 +1,242 @@
+# API Reference
+
+The Waggle local server runs on `http://localhost:3333`. All endpoints accept and return JSON unless otherwise noted.
+
+## Chat
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/chat` | Send a message and receive an SSE stream of agent responses. Body: `{ message, workspaceId, sessionId, model? }` |
+| GET | `/api/history` | Get conversation history. Query: `?session=ID&workspace=ID` |
+
+The chat endpoint streams responses via Server-Sent Events (SSE). Events include `message`, `tool_call`, `tool_result`, `approval_request`, `done`, and `error`.
+
+## Workspaces
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/workspaces` | List all workspaces |
+| POST | `/api/workspaces` | Create a workspace. Body: `{ name, group, icon?, model?, personaId?, directory?, teamId? }` |
+| GET | `/api/workspaces/:id` | Get workspace by ID |
+| PUT | `/api/workspaces/:id` | Update workspace. Body: `{ name?, group?, icon?, model?, personaId? }` |
+| DELETE | `/api/workspaces/:id` | Delete workspace |
+| GET | `/api/workspaces/:id/context` | Workspace catch-up context: summary, threads, decisions, suggestions, stats |
+| GET | `/api/workspaces/:id/files` | List ingested files for a workspace |
+
+## Sessions
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/workspaces/:wid/sessions` | List sessions for a workspace, sorted by last active |
+| POST | `/api/workspaces/:wid/sessions` | Create a new session. Body: `{ title? }` |
+| GET | `/api/workspaces/:wid/sessions/search` | Search across sessions. Query: `?q=query&limit=20` |
+| GET | `/api/workspaces/:wid/sessions/:sid/export` | Export session as Markdown. Returns `text/markdown` |
+| PATCH | `/api/sessions/:id` | Rename a session. Body: `{ title }`. Query: `?workspace=ID` |
+| DELETE | `/api/sessions/:id` | Delete a session. Query: `?workspace=ID` |
+
+## Memory
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/memory/search` | Search memory. Query: `?q=query&scope=all|personal|workspace&limit=20&workspace=ID` |
+| GET | `/api/memory/frames` | Recent frames without search. Query: `?workspace=ID&limit=50` |
+| GET | `/api/memory/graph` | Knowledge graph entities and relations. Query: `?workspace=ID` |
+
+## Agent
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/agent/status` | Agent status: model, tokens used, estimated cost, turn count |
+| GET | `/api/agent/cost` | Detailed cost breakdown with formatted summary |
+| POST | `/api/agent/cost/reset` | Reset cost tracking (takes effect on server restart) |
+| GET | `/api/agent/model` | Current model name |
+| PUT | `/api/agent/model` | Switch model. Body: `{ model }` |
+| GET | `/api/agents/active` | Active sub-agent orchestrator state |
+
+## Approval Gates
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/approval/pending` | List pending approval requests |
+| POST | `/api/approval/:requestId` | Approve or deny. Body: `{ approved: boolean, reason? }` |
+
+## Settings
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/settings` | Read config: default model, providers (masked keys), paths |
+| PUT | `/api/settings` | Update config. Body: `{ defaultModel?, providers? }` |
+| POST | `/api/settings/test-key` | Validate API key format. Body: `{ provider, apiKey }` |
+| POST | `/api/settings/probe-provider` | Live-probe a STORED provider key by id. Body: `{ provider }` → `{ configured, valid, verified, error? }` |
+| GET | `/api/settings/permissions` | Read permission settings (YOLO mode, external gates) |
+| PUT | `/api/settings/permissions` | Update permissions. Body: `{ yoloMode?, externalGates?, workspaceOverrides? }` |
+
+## Vault
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/vault` | List all secrets (names and types only, no values) |
+| POST | `/api/vault` | Add or update a secret. Body: `{ name, value, type? }` |
+| DELETE | `/api/vault/:name` | Delete a secret |
+| POST | `/api/vault/:name/reveal` | Decrypt and return the full value |
+
+## Skills
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/skills` | List all installed skills |
+| GET | `/api/skills/:name` | Get full skill content |
+| POST | `/api/skills` | Create a new skill. Body: `{ name, content }` |
+| PUT | `/api/skills/:name` | Update skill content. Body: `{ content }` |
+| DELETE | `/api/skills/:name` | Remove a skill |
+| GET | `/api/skills/suggestions` | Contextual skill recommendations. Query: `?context=text&topN=3` |
+| GET | `/api/skills/hash-status` | Check which skills have changed on disk |
+| POST | `/api/skills/starter-pack` | Install all starter skills |
+| GET | `/api/skills/starter-pack/catalog` | Browse starter skills with install state and family grouping |
+| POST | `/api/skills/starter-pack/:id` | Install a single starter skill |
+| GET | `/api/skills/capability-packs/catalog` | List all packs with skill states |
+| POST | `/api/skills/capability-packs/:id` | Install all skills in a pack |
+
+## Plugins
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/plugins` | List all installed plugins |
+| POST | `/api/plugins/install` | Install a plugin. Body: `{ sourceDir }` |
+| DELETE | `/api/plugins/:name` | Uninstall a plugin |
+
+## Capabilities
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/capabilities/status` | Aggregated capability dashboard: plugins, MCP, skills, tools, commands, hooks, workflows |
+| POST | `/api/capabilities/plugins/:name/enable` | Enable a plugin |
+| POST | `/api/capabilities/plugins/:name/disable` | Disable a plugin |
+
+## Marketplace
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/marketplace/search` | Search catalog. Query: `?query=text&type=skill&category=cat&limit=20&offset=0` |
+| GET | `/api/marketplace/packs` | List all capability packs |
+| GET | `/api/marketplace/packs/:slug` | Pack detail with packages |
+| GET | `/api/marketplace/enterprise-packs` | Enterprise packs (requires KVARK) |
+| POST | `/api/marketplace/install` | Install package. Body: `{ packageId, installPath?, settings?, force? }` |
+| POST | `/api/marketplace/uninstall` | Uninstall package. Body: `{ packageId }` |
+| GET | `/api/marketplace/installed` | List installed packages |
+| POST | `/api/marketplace/security-check` | Security scan without install. Body: `{ packageId }` |
+| GET | `/api/marketplace/sources` | List marketplace sources |
+| POST | `/api/marketplace/sync` | Sync from sources. Body: `{ sources?: string[] }` |
+
+## Connectors
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/connectors` | List all connectors with status |
+| GET | `/api/connectors/:id/health` | Check connector health |
+| POST | `/api/connectors/:id/connect` | Store credentials. Body: `{ token?, apiKey?, refreshToken?, expiresAt?, scopes?, email? }` |
+| POST | `/api/connectors/:id/disconnect` | Remove credentials from vault |
+
+## Personas
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/personas` | List all available personas (ID, name, description, icon, affinity, commands) |
+
+## Cron (Scheduling)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/cron` | Create schedule. Body: `{ name, cronExpr, jobType, jobConfig?, workspaceId?, enabled? }` |
+| GET | `/api/cron` | List all schedules |
+| GET | `/api/cron/:id` | Get one schedule |
+| PATCH | `/api/cron/:id` | Update schedule. Body: `{ name?, cronExpr?, jobConfig?, workspaceId?, enabled? }` |
+| DELETE | `/api/cron/:id` | Delete schedule |
+| POST | `/api/cron/:id/trigger` | Manually trigger a schedule |
+
+## Tasks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/workspaces/:id/tasks` | List tasks. Query: `?status=open|in_progress|done` |
+| POST | `/api/workspaces/:id/tasks` | Create task. Body: `{ title, assigneeName?, assigneeId? }` |
+| PATCH | `/api/workspaces/:id/tasks/:taskId` | Update task (status, assignment) |
+| DELETE | `/api/workspaces/:id/tasks/:taskId` | Delete task |
+
+## Fleet (Mission Control)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/fleet` | List active workspace sessions with status and duration |
+| POST | `/api/fleet/:workspaceId/pause` | Pause a workspace session |
+| POST | `/api/fleet/:workspaceId/resume` | Resume a paused session |
+| POST | `/api/fleet/:workspaceId/kill` | Abort and close a session |
+
+## File Ingestion
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/ingest` | Ingest files. Body: `{ files: [{ name, content (base64) }], workspaceId? }`. Max 15MB. |
+
+Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX), spreadsheets (XLSX, CSV), text/code (50+ extensions), archives (ZIP).
+
+## Import
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/import/preview` | Preview import from ChatGPT or Claude export. Body: `{ data, source: "chatgpt"|"claude" }` |
+| POST | `/api/import/commit` | Import and save to personal memory. Body: `{ data, source }` |
+
+## Feedback
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/feedback` | Record feedback. Body: `{ sessionId, messageIndex, rating: "up"|"down", reason?, detail? }` |
+| GET | `/api/feedback/stats` | Improvement stats: positive rate, top issues, corrections, trend |
+
+## Notifications
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/notifications/stream` | SSE stream of notifications (cron, approval, task, message, agent events) |
+
+## Audit
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/audit/installs` | Recent install audit trail. Query: `?limit=20` |
+
+## Team
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/team/connect` | Connect to team server. Body: `{ serverUrl, token }` |
+| POST | `/api/team/disconnect` | Disconnect from team server |
+| GET | `/api/team/status` | Current team connection status |
+
+## Anthropic Proxy
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/chat/completions` | OpenAI-compatible endpoint that translates to Anthropic API. Used by internal agent loop. |
+
+## Commands
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/commands/execute` | Execute a slash command. Body: `{ command, workspaceId, sessionId }` |
+
+## SSE Streaming
+
+The `/api/chat` endpoint uses Server-Sent Events for real-time streaming. Event types:
+
+| Event | Description |
+|-------|-------------|
+| `message` | Agent text chunk |
+| `tool_call` | Agent is calling a tool (shows tool name and input) |
+| `tool_result` | Tool execution result |
+| `approval_request` | Agent needs approval before proceeding |
+| `approval_resolved` | Approval was granted or denied |
+| `memory_saved` | A memory frame was auto-saved |
+| `done` | Agent turn complete |
+| `error` | Error occurred |
--- a/docs/reference/commands.md
+++ b/docs/reference/commands.md
@@ -0,0 +1,138 @@
+# Commands Reference
+
+Waggle provides 14 slash commands for quick actions. Type `/` in any workspace to see autocomplete suggestions.
+
+## Command List
+
+| Command | Aliases | Args | Description |
+|---------|---------|------|-------------|
+| `/catchup` | `/catch-up`, `/recap` | -- | Workspace restart summary. Shows recent activity, memories, and state so you can get up to speed instantly. |
+| `/now` | `/current`, `/where` | -- | Current workspace state. What is happening right now -- active threads, recent changes, open items. |
+| `/research` | `/investigate` | `<topic>` | Launch multi-agent research. Spawns the `research-team` workflow with multiple agents investigating the topic in parallel. |
+| `/draft` | `/write` | `<type> [topic]` | Start a drafting workflow. Supports any document type: blog, report, email, proposal, memo. Uses the `review-pair` workflow for drafts with review. |
+| `/decide` | `/decision`, `/weigh` | `<question>` | Create a structured decision matrix with options, pros/cons, risk, and effort columns. Provides an evaluation framework for systematic decision-making. |
+| `/review` | `/critique`, `/check` | -- | Review the last output with a critic agent. Spawns the `review-pair` workflow to analyze the most recent response for accuracy and completeness. |
+| `/spawn` | `/agent`, `/summon` | `<role> [task]` | Spawn a specialist sub-agent. Available roles: `researcher`, `writer`, `coder`, `analyst`, `reviewer`, `planner`. |
+| `/skills` | `/abilities`, `/tools` | -- | Show active skills in this workspace. Lists all loaded skill files with their names. |
+| `/status` | `/report`, `/progress` | -- | Project status summary. Shows workspace state including tasks, progress, blockers, and recent activity. |
+| `/memory` | `/remember`, `/recall` | `[query]` | Search workspace memory. Without arguments, shows usage help. With a query, searches both personal and workspace minds. |
+| `/plan` | `/decompose`, `/break-down` | `<goal>` | Break a goal into actionable tasks. Uses the `plan-execute` workflow to create a structured task list with dependencies. |
+| `/focus` | `/narrow`, `/scope` | `<topic>` | Narrow agent focus to a specific topic. Subsequent responses prioritize this context. Use again to change focus. |
+| `/marketplace` | `/mp`, `/market` | `<subcommand> [args]` | Marketplace operations. Sub-commands: `search`, `install`, `packs`, `installed`, `sync`. See details below. |
+| `/help` | `/commands`, `/?` | -- | List all available commands with descriptions. |
+
+## Detailed Examples
+
+### /catchup
+
+```
+/catchup
+```
+
+Output: A structured briefing with what this workspace is about, recent sessions, decisions, memory count, and suggested next steps. Use this every time you return to a workspace after a break.
+
+### /research
+
+```
+/research quantum computing applications in drug discovery
+```
+
+Spawns the `research-team` multi-agent workflow:
+1. A researcher agent investigates the topic
+2. Findings are synthesized and cross-referenced
+3. Results are presented with citations and confidence levels
+
+### /draft
+
+```
+/draft blog post about AI safety best practices
+/draft report quarterly metrics for Q1 2026
+/draft email to client about project timeline changes
+```
+
+The agent determines the document type from the first word and adapts its formatting accordingly. If the `review-pair` workflow is available, the draft goes through a review cycle.
+
+### /decide
+
+```
+/decide Should we use PostgreSQL or MongoDB for the new project?
+```
+
+Produces a decision matrix template:
+
+| Option | Pros | Cons | Risk | Effort |
+|--------|------|------|------|--------|
+| PostgreSQL | | | | |
+| MongoDB | | | | |
+
+Ask the agent to fill it in: "Please analyze this decision for me."
+
+### /spawn
+
+```
+/spawn researcher Find recent papers on transformer architectures
+/spawn coder Implement a rate limiter middleware
+/spawn analyst Compare our metrics against industry benchmarks
+```
+
+The sub-agent runs with the specified role and task, then returns its results to the main conversation.
+
+### /memory
+
+```
+/memory architecture decisions
+/memory last meeting notes
+/memory project goals
+```
+
+Searches both personal and workspace memory using FTS5 full-text search. Results include content, importance level, and dates.
+
+### /plan
+
+```
+/plan Build a user dashboard with analytics
+/plan Migrate the database to PostgreSQL
+```
+
+Creates a structured plan with ordered steps, dependencies, and success criteria. The agent can then execute steps sequentially.
+
+### /marketplace
+
+```
+/marketplace search research
+/marketplace install deep-research
+/marketplace packs
+/marketplace installed
+/marketplace sync
+```
+
+| Sub-command | Description |
+|-------------|-------------|
+| `search <query>` | Search the marketplace catalog by keyword. Returns up to 10 results with name, type, category, and description. |
+| `install <name>` | Install a package by name. Searches for the best match, runs SecurityGate scan, and installs. |
+| `packs` | List all capability packs grouped by priority tier. |
+| `installed` | Show all currently installed packages with status and install date. |
+| `sync` | Trigger a manual sync from all configured marketplace sources. Reports added/updated counts. |
+
+## Command Parsing
+
+Commands follow the format `/commandName arg1 arg2 ...`. The parser:
+
+1. Strips the leading `/`
+2. Splits on the first space to get the command name and arguments
+3. Resolves aliases (e.g., `/mp` resolves to `/marketplace`)
+4. Executes the handler with the argument string and workspace context
+
+Partial matching is supported for autocomplete but not for execution. You must type the full command name or alias.
+
+## Adding Custom Commands
+
+Commands are registered in the `CommandRegistry`. To add a custom command, create a `CommandDefinition` with:
+
+- `name` -- the primary command name (lowercase)
+- `aliases` -- alternative names
+- `description` -- shown in `/help` output
+- `usage` -- usage string with argument placeholders
+- `handler` -- async function receiving `(args: string, context: CommandContext)`
+
+See `packages/agent/src/commands/` for implementation examples.