nuc/docs/outline-ai-workflow.md

# 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": "<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: <topic>",
    text="<markdown content>",
    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="<doc-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="<new content>",
    append=False  # Replace content; True to append
)
```

### 4. Export for Backup

```python
# Export single document
mcp__outline__export_document(id="<doc-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/<endpoint>' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '<json payload>'
```

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