moving

docs/guides/capabilities.md

@@ -0,0 +1,211 @@
+# Capabilities
+
+Capabilities are the extensions that make Waggle powerful: skills, plugins, MCP servers, workflow templates, hooks, and commands. This guide covers how to discover, install, and manage them.
+
+## Capability Types
+
+| Type | What It Is | Storage |
+|------|-----------|---------|
+| **Skill** | Markdown file that extends the agent's system prompt with domain knowledge and instructions | `~/.waggle/skills/*.md` |
+| **Plugin** | Structured package with a manifest that adds tools and behaviors | `~/.waggle/plugins/` |
+| **MCP Server** | Model Context Protocol server that provides external tools | Configured in settings |
+| **Workflow Template** | Multi-step agent orchestration (e.g., research-team, review-pair, plan-execute) | Built into `@waggle/agent` |
+| **Hook** | Event-driven callback (before/after tool calls, session start/end, etc.) | Registered in agent state |
+| **Command** | Slash command (`/research`, `/draft`, etc.) | Built into `@waggle/agent` |
+
+## Built-in Capability Packs
+
+Waggle ships with 5 curated packs. Each pack bundles several skills that work together.
+
+### Research Workflow
+
+Skills for investigation and synthesis. Includes `research-synthesis`, `explain-concept`, and the `research-team` multi-agent workflow.
+
+### Writing Suite
+
+Skills for document creation and editing. Includes `draft-memo`, `compare-docs`, and `extract-actions`.
+
+### Planning Master
+
+Skills for task decomposition and execution. Includes `daily-plan`, `task-breakdown`, and the `plan-execute` workflow.
+
+### Team Collaboration
+
+Skills for coordination and communication. Includes `catch-up`, `status-update`, and `meeting-prep`.
+
+### Decision Framework
+
+Skills for structured decision-making. Includes `decision-matrix`, `risk-assessment`, and `retrospective`.
+
+## Installing Packs
+
+### From the UI
+
+1. Navigate to **Capabilities** in the sidebar (or click the grid icon)
+2. Click **Browse Packs**
+3. Each pack shows its skills, install state (available / incomplete / complete), and description
+4. Click **Install** to install all skills in the pack at once
+5. Already-installed skills are skipped
+
+### From the API
+
+```bash
+# Install the Research Workflow pack
+curl -X POST http://localhost:3333/api/skills/capability-packs/research-workflow
+
+# Install a single skill from the starter pack
+curl -X POST http://localhost:3333/api/skills/starter-pack/draft-memo
+```
+
+## Installing Individual Skills
+
+### From the Starter Catalog
+
+1. Go to **Capabilities** > **Skills**
+2. Browse by family: Writing & Docs, Research & Analysis, Decision Support, Planning & Organization, Communication, Code & Engineering, Creative & Ideation
+3. Click **Install** on any skill
+4. The skill is copied to `~/.waggle/skills/` and loaded immediately
+
+### Creating Custom Skills
+
+Skills are markdown files. Create a file in `~/.waggle/skills/`:
+
+```markdown
+# My Custom Skill
+
+Instructions for the agent when this skill is active.
+
+## When to Use
+- Trigger conditions
+
+## How to Respond
+- Response format guidelines
+- Quality standards
+```
+
+Or use the API:
+
+```bash
+curl -X POST http://localhost:3333/api/skills \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-skill", "content": "# My Skill\n\nInstructions here."}'
+```
+
+## Marketplace
+
+The marketplace catalog contains 120+ packages across skills, plugins, and MCP servers from curated sources.
+
+### Searching
+
+```bash
+# Search by keyword
+curl "http://localhost:3333/api/marketplace/search?query=research&limit=10"
+
+# Filter by type
+curl "http://localhost:3333/api/marketplace/search?type=skill&category=analysis"
+```
+
+Or use the `/marketplace search <query>` slash command in any workspace.
+
+### Installing from Marketplace
+
+```bash
+# Install by package ID
+curl -X POST http://localhost:3333/api/marketplace/install \
+  -H "Content-Type: application/json" \
+  -d '{"packageId": 42}'
+```
+
+Or use `/marketplace install <name>`.
+
+### Security Scanning
+
+Every marketplace install goes through the **SecurityGate** scanner. Results determine whether the install proceeds:
+
+| Severity | Action |
+|----------|--------|
+| CLEAN | Install proceeds immediately |
+| LOW | Install proceeds, logged to audit trail |
+| MEDIUM | Install proceeds with warnings in response |
+| HIGH | Blocked unless `force=true` (override logged to audit) |
+| CRITICAL | Always blocked, cannot override |
+
+### Syncing the Catalog
+
+```bash
+# Sync from all configured sources
+curl -X POST http://localhost:3333/api/marketplace/sync
+```
+
+Or use `/marketplace sync`.
+
+## Trust Model
+
+Waggle uses a multi-layer trust model:
+
+1. **Source trust** -- starter-pack skills are trusted by default; marketplace and user-created skills get assessed
+2. **Content analysis** -- heuristic scan for dangerous patterns (credential access, network calls, file system mutations)
+3. **Risk level** -- low, medium, high, critical based on what the capability does
+4. **Approval class** -- standard (auto-approve), review (log), force-override (user acknowledged risk), blocked
+5. **Content hash** -- SHA-256 hash of each skill file, checked at startup to detect unauthorized modifications
+
+### Audit Trail
+
+Every install, uninstall, and security decision is recorded in the audit store. View it:
+
+- **UI**: Capabilities > Cockpit > Trust Audit section
+- **API**: `GET /api/audit/installs`
+
+### Hash Verification
+
+At startup, Waggle checks each installed skill's content hash against the stored hash. If a skill file was modified outside of Waggle, it is flagged in the hash status:
+
+```bash
+curl http://localhost:3333/api/skills/hash-status
+```
+
+## Plugins
+
+Plugins are structured packages with manifests that can add tools and extend agent behavior.
+
+### Installing a Plugin
+
+```bash
+curl -X POST http://localhost:3333/api/plugins/install \
+  -H "Content-Type: application/json" \
+  -d '{"sourceDir": "/path/to/my-plugin"}'
+```
+
+### Enabling / Disabling
+
+```bash
+# Enable
+curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/enable
+
+# Disable
+curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/disable
+```
+
+### Uninstalling
+
+```bash
+curl -X DELETE http://localhost:3333/api/plugins/my-plugin
+```
+
+## Viewing Capability Status
+
+The **Cockpit** (accessible from the sidebar) shows a live dashboard of all capabilities:
+
+- **Plugins**: name, state, tool count, skill count
+- **MCP Servers**: name, state, healthy status, tool count
+- **Skills**: name, content length
+- **Tools**: total count (native + plugin + MCP)
+- **Commands**: all registered slash commands
+- **Hooks**: registered count, recent activity log
+- **Workflows**: available templates with step counts
+
+API equivalent:
+
+```bash
+curl http://localhost:3333/api/capabilities/status
+```