AGENTS/skills/outline/references/outline-workflows.md

Outline Workflows

This reference provides detailed examples and patterns for Outline wiki integration with Obsidian.

Table of Contents

1. Export Decision to Wiki
2. Project Documentation Sync
3. Knowledge Discovery
4. Batch Export
5. Wiki Migration

---

Export Decision to Wiki

Scenario

After a meeting, you made an important decision about API authentication. You want to preserve it in the company wiki.

Workflow

User: "Export decision: Use OAuth2 for all external APIs"

Outline skill:
1. Create document:
   - Title: "API Authentication Decision"
   - Collection: Engineering/Security
   - Content:
     ---
     title: "API Authentication Decision"
     date: 2026-01-28
     decision_made_by: "[Team Name]"
     tags: [decision, api, security]
     ---

     # Decision
     Use OAuth2 for all external API integrations.

     # Reasoning
     - OAuth2 provides better security (no shared secrets)
     - Token rotation reduces risk exposure
     - Industry standard for API auth
     - Existing libraries available

     # Implementation
     - Use RFC 6749 OAuth2 framework
     - Implement refresh token flow
     - Set 30-day token expiry
     - Document API endpoints in collection

     # Alternatives Considered
     - API Keys: Rejected (security risk)
     - JWT: Rejected (overkill for external APIs)
     - Custom Auth: Rejected (maintenance burden)

     # Related Documents
     - [[OAuth2 Setup Guide]]
     - [[Token Management Policy]]
     - [[API Security Best Practices]]

2. Confirm: "Created API Authentication Decision in Engineering/Security"
3. Offer: "Link to project?"

Obsidian Integration

After creating in Outline, create cross-reference in Obsidian:

~/CODEX/01-projects/work/[project]/decisions/api-auth-decision.md
---
title: "API Authentication Decision"
date: 2026-01-28
source: outline
outline_doc_id: [ID]
tags: [work, decision, api]
---

## Decision
Use OAuth2 for all external API integrations.

## Outline Link
📄 [API Authentication Decision](outline://document/abc123)

## Context
- Made during API integration project
- Discussed in [Security Review Meeting]
- Approved by: [Stakeholder names]

## Project Notes
- Update authentication service by Q2
- Train team on OAuth2 flow

---

Project Documentation Sync

Scenario

You're starting a new project. You want to link project docs with the wiki for context.

Workflow

User: "Start project: Customer Portal Redesign"

outline skill:
1. Search for related docs:
   - "Search Outline for Customer Portal"
   - "Search Outline for UI/UX guidelines"
   - "Search Outline for architecture decisions"

2. Present findings:
   📄 Customer Portal Architecture (Engineering)
   📄 UI Design System (Product/Design)
   📄 Accessibility Guidelines (Engineering/Docs)

3. Create project folder in Obsidian with wiki links

Project MOC with Wiki Links

~/CODEX/01-projects/work/customer-portal-redesign/_index.md
---
title: "Customer Portal Redesign"
status: active
deadline: 2026-06-30
priority: high
tags: [work, project]
---

## Overview
Redesign of customer portal with improved UX, performance, and accessibility.

## Wiki Resources

### Architecture
📄 [[Customer Portal Architecture]](outline://document/abc123)
- Backend architecture decisions
- Database schema
- API endpoints

### Design System
📄 [[UI Design System]](outline://document/def456)
- Component library
- Color palette
- Typography

### Guidelines
📄 [[Accessibility Guidelines]](outline://document/ghi789)
- WCAG 2.1 AA compliance
- Testing checklist
- Common patterns

## Notes
<!-- Your project notes here -->

## Tasks
<!-- Tasks linked from Basecamp -->

---

Knowledge Discovery

Scenario

You need to implement a feature but don't remember the authentication pattern used in the codebase.

Workflow

User: "Ask Outline: How do we handle API authentication?"

outline skill:
1. ask_ai_about_documents(
     question: "How do we handle API authentication?"
     collection_id: "engineering"
   )

2. Present AI answer with sources:
   🤖 **Answer**:
   Based on 12 documents, here's the authentication pattern:

   **Standard Pattern**:
   - OAuth2 with refresh tokens
   - 30-day token expiry
   - Automatic refresh before expiry

   **Implementation**:
   1. Use `/auth/oauth2/token` endpoint
   2. Store refresh token securely
   3. Implement token rotation
   4. Handle 401 Unauthorized with retry

   **Exceptions**:
   - Internal services use API keys (documented separately)
   - Admin portals use session-based auth

   **Key Sources**:
   1. [[OAuth2 Setup Guide]](outline://document/abc123)
   2. [[Token Management Policy]](outline://document/def456)
   3. [[API Security Best Practices]](outline://document/ghi789)

3. Offer:
   - "Read OAuth2 Setup Guide?"
   - "Export to current project?"

---

Batch Export

Scenario

You're preparing for a job transition or need offline access to critical documentation.

Workflow

User: "Export all Engineering docs to Obsidian"

outline skill:
1. export_collection(collection_id: "engineering_id")
2. Create Obsidian structure:
   ~/CODEX/03-resources/work/wiki-mirror/engineering/
   ├── api-docs/
   │   ├── oauth2-setup-guide.md
   │   ├── token-management.md
   │   └── api-security.md
   ├── architecture/
   │   ├── system-design.md
   │   └── data-flow.md
   └── decisions/
       ├── auth-decision.md
       └── database-choice.md

3. Update wiki index:
   Update ~/CODEX/03-resources/work/wiki-mirror/_wiki-index.md
   with new export metadata

4. Confirm: "Exported 15 Engineering docs to wiki-mirror/engineering/"

---

Wiki Migration

Scenario

You're switching from a different wiki system to Outline and want to migrate content.

Workflow (No n8n - Manual Process)

Step 1: Export from Old Wiki
- Export all pages as Markdown
- Preserve structure/folders
- Keep metadata (created dates, authors)

Step 2: Batch Import to Outline
outline skill:
1. batch_create_documents(documents):
   [
     {
       "title": "API Documentation",
       "collection_id": "engineering_id",
       "text": "# API Documentation\n\n...",
       "publish": true
     },
     {
       "title": "System Design",
       "collection_id": "engineering_id",
       "text": "# System Design\n\n...",
       "publish": true
     }
   ]
2. Confirm: "Imported 50 documents to Outline"

Step 3: Verify Migration
- Check Outline web UI
- Verify document counts
- Test search functionality
- Fix any formatting issues

Step 4: Archive Old Wiki
- Mark old wiki as read-only
- Add deprecation notice
- Link to new Outline location

---

Cross-Tool Patterns

Outline ↔ Obsidian

When	Action	Location
Important decision	Create in Outline + link in Obsidian	Outline: Primary, Obsidian: Reference
Project docs	Link wiki docs from project MOC	Obsidian: Primary, Outline: Source
Meeting outcome	Export key decisions to Outline	Outline: Persistent, Obsidian: Session context
Research	Export findings to Outline	Outline: Knowledge base, Obsidian: Working notes

Search Workflow

1. First: Search Obsidian vault (personal knowledge)
2. Then: Search Outline wiki (team knowledge)
3. Finally: Search both with context

User: "Find info about OAuth2"

Obsidian search:
- Check ~/CODEX/03-resources/work/wiki-mirror/
- Check project notes
- Return local copies

Outline search:
- search_documents("OAuth2")
- Return live wiki content
- Export if needed for offline access

---

Advanced Workflows

Decision Audit

Periodically review all decisions to check:

• Relevance (still applicable?)
• Implementation status (actually done?)
• Outdated decisions (need update?)

# List all decision docs
search_documents("decision")

# For each:
read_document(document_id)
# Check frontmatter:
# - implemented: true/false
# - reviewed_at: date
# - status: active/archived

Knowledge Gap Analysis

Identify missing documentation:

1. List all project areas
2. Search Outline for each area
3. Identify gaps:
   • "No results found for X"
   • "Documentation is outdated"
   • "Information is scattered"

Create follow-up tasks:

## Documentation Tasks
- [ ] Write API rate limiting guide (missing)
- [ ] Update OAuth2 examples (outdated)
- [ ] Create testing best practices (scattered)

---

Troubleshooting

Export Failed

Problem: Document exported to wrong location or failed to export

Solution:

1. Verify collection hierarchy
2. Check Obsidian vault path
3. Ensure directory exists: mkdir -p 03-resources/work/wiki-mirror/[collection]/
4. Check file permissions

Search No Results

Problem: search_documents returns empty results

Solution:

1. Try broader query (fewer keywords)
2. Remove collection_id to search everywhere
3. Check if document exists in Outline web UI
4. Use ask_ai_about_documents for semantic search

Wiki Link Broken

Problem: (outline://document/abc123) link doesn't work

Solution:

1. Verify document_id is correct
2. Check Outline MCP is running
3. Test with read_document(document_id)
4. Fallback: Use Outline web UI URL

---

Best Practices Summary

1. Export Early, Export Often: Don't wait until job transition
2. Link Immediately: Create Obsidian links when exporting
3. Index Everything: Maintain wiki index for easy navigation
4. AI as Helper: Use ask_ai_about_documents but verify sources
5. Preserve Hierarchy: Maintain collection structure in exports
6. Tag Generously: Add tags for discoverability
7. Cross-Reference: Link related documents in Outline
8. Decisions Matter: Export all decisions, not just docs

---

Automation (Future n8n Workflows)

These will be implemented later with n8n automation:

1. Daily Wiki Sync: Export updated Outline docs each night
2. Decision Auto-Export: Hook meeting-notes → Outline create
3. Search Integration: Combine Obsidian + Outline search
4. Backup Workflow: Weekly export_all_collections