diff --git a/docs/outline-ai-workflow.md b/docs/outline-ai-workflow.md new file mode 100644 index 0000000..4edf8cc --- /dev/null +++ b/docs/outline-ai-workflow.md @@ -0,0 +1,259 @@ +# Outline AI Workflow Guide + +**Date:** 2026-02-01 +**Purpose:** Document how AI agents can interact with Outline wiki for knowledge management + +--- + +## Overview + +Outline is the NUC's wiki/documentation system. AI agents can interact with it via: +1. **MCP Server** (preferred) - `mcp-outline` for full CRUD operations +2. **REST API** - Direct API calls when MCP not available +3. **Browser Automation** - Playwriter fallback for UI-only features + +--- + +## MCP Server Setup + +### Installation + +Added to `~/.claude/settings.json`: + +```json +{ + "mcpServers": { + "outline": { + "command": "uvx", + "args": ["mcp-outline"], + "env": { + "OUTLINE_API_KEY": "", + "OUTLINE_API_URL": "http://192.168.1.3:3080/api" + } + } + } +} +``` + +### Available MCP Tools + +| Tool | Purpose | +|------|---------| +| **Search & Discovery** | | +| `search_documents` | Search by keywords with pagination | +| `list_collections` | List all collections | +| `get_collection_structure` | Get document hierarchy | +| `get_document_id_from_title` | Find doc ID by title | +| **Document Operations** | | +| `read_document` | Get document content | +| `create_document` | Create new document | +| `update_document` | Update document (append mode available) | +| `move_document` | Move to different collection/parent | +| `export_document` | Export as markdown | +| **Lifecycle** | | +| `archive_document` | Archive a document | +| `delete_document` | Delete or move to trash | +| `restore_document` | Restore from trash | +| **Batch Operations** | | +| `batch_create_documents` | Create multiple docs | +| `batch_update_documents` | Update multiple docs | +| `batch_move_documents` | Move multiple docs | +| **AI Features** | | +| `ask_ai_about_documents` | Natural language queries | + +--- + +## Collections + +| Collection | ID | Purpose | +|------------|-----|---------| +| **NUC Docs** | `2a42945b-1a4f-4c92-add5-dfa147ef3f56` | Server documentation | +| **Welcome** | (default) | Getting started guides | + +--- + +## Common Workflows + +### 1. Save Session Findings to Wiki + +When Claude discovers important information during a session: + +```python +# Using MCP (preferred) +mcp__outline__create_document( + title="Session Finding: ", + text="", + collectionId="2a42945b-1a4f-4c92-add5-dfa147ef3f56", # NUC Docs + publish=True +) +``` + +### 2. Search Existing Documentation + +Before solving a problem, check if solution exists: + +```python +# Search for relevant docs +mcp__outline__search_documents(query="tailscale funnel setup") + +# Read specific document +mcp__outline__read_document(id="") +``` + +### 3. Update Existing Documentation + +When information changes: + +```python +# Find document +doc_id = mcp__outline__get_document_id_from_title(title="Architecture") + +# Update with new content +mcp__outline__update_document( + id=doc_id, + text="", + append=False # Replace content; True to append +) +``` + +### 4. Export for Backup + +```python +# Export single document +mcp__outline__export_document(id="") + +# Export entire collection +mcp__outline__export_collection(id="2a42945b-1a4f-4c92-add5-dfa147ef3f56") +``` + +--- + +## REST API Fallback + +When MCP is not available, use direct API calls: + +### Authentication + +```bash +API_KEY="ol_api_..." +curl -X POST 'http://192.168.1.3:3080/api/' \ + -H "Authorization: Bearer $API_KEY" \ + -H 'Content-Type: application/json' \ + -d '' +``` + +### Create Document + +```bash +curl -X POST 'http://192.168.1.3:3080/api/documents.create' \ + -H "Authorization: Bearer $API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{ + "title": "Document Title", + "text": "Markdown content...", + "collectionId": "2a42945b-1a4f-4c92-add5-dfa147ef3f56", + "publish": true + }' +``` + +### Search Documents + +```bash +curl -X POST 'http://192.168.1.3:3080/api/documents.search' \ + -H "Authorization: Bearer $API_KEY" \ + -H 'Content-Type: application/json' \ + -d '{"query": "search term"}' +``` + +--- + +## API Key Management + +### Generate New API Key + +1. Navigate to: http://192.168.1.3:3080/settings/api-and-apps +2. Click "New API key..." +3. Set name and scopes: + - `documents.create` - Create documents + - `documents.update` - Update documents + - `documents.read` - Read documents + - `collections.read` - List collections + - `collections.create` - Create collections +4. Copy key immediately (shown only once) + +### Current API Key + +- **Name:** Docs Import 2 +- **Scopes:** documents.create, documents.update, collections.create, collections.read +- **Expires:** Mar 03, 2026 + +--- + +## When to Use Outline + +**DO save to Outline:** +- Infrastructure documentation +- Configuration guides +- Troubleshooting procedures +- Architecture decisions +- Setup instructions +- Persistent reference material + +**DON'T save to Outline:** +- Temporary session notes (use `.artifacts/`) +- Sensitive credentials (use Vaultwarden) +- One-time command outputs +- Transient debugging info + +--- + +## Integration with Other Systems + +### From Gitea + +NUC docs are also in Gitea at `http://192.168.1.3:3030/alezmad/nuc-docs` +- Git repo is source of truth for docs +- Outline provides searchable wiki interface +- Sync manually when significant changes occur + +### From n8n + +Can automate Outline updates: +- Webhook triggers on events +- Scheduled documentation reviews +- Auto-archive stale documents + +--- + +## Troubleshooting + +### MCP Connection Issues + +```bash +# Test API connectivity +curl -s http://192.168.1.3:3080/api/auth.info \ + -H "Authorization: Bearer $API_KEY" | jq .ok +``` + +### File Upload Limits + +Outline file size limits (configured in Coolify env vars): +- `FILE_STORAGE_UPLOAD_MAX_SIZE`: 100MB +- `FILE_STORAGE_IMPORT_MAX_SIZE`: 100MB +- `FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE`: 100MB + +### API Key Scope Errors + +If "API key does not have access": +1. Check key scopes in Settings > API & Apps +2. Generate new key with required scopes +3. Update `~/.claude/settings.json` with new key + +--- + +## Related + +- [Architecture](./architecture.md) - NUC infrastructure overview +- [MCP Research Guide](./mcp-research-guide.md) - Finding new MCPs +- Outline API Docs: https://www.getoutline.com/developers +- MCP Server: https://github.com/Vortiago/mcp-outline