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:

{
  "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:

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

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

# 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

# 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

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

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

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

# 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 - NUC infrastructure overview
• MCP Research Guide - Finding new MCPs
• Outline API Docs: https://www.getoutline.com/developers
• MCP Server: https://github.com/Vortiago/mcp-outline