Create documentation website using Mintlify (www.panopticon-cli.com)

[eltmon]

Overview

Create a professional documentation website for Panopticon using Mintlify at www.panopticon-cli.com.

Design Requirements

Color Scheme

Light Mode:

• Primary text: #0E0E0E (dark charcoal)
• Background: #FDFDF7 (off-white/cream)
• Accent color: #D4A27F (warm tan)
• Borders: #666663 (subtle gray)

Dark Mode:

• Primary text: #E5E7EB (light gray)
• Background: #09090B (near black)
• Accent: #D4A27F (warm tan)
• Borders: rgba(212, 162, 127, .15)

Typography

• Headings: Serif display font (Georgia fallback)
• Body: Clean sans-serif with regular/medium/semibold weights
• Monospace: System defaults for code blocks
• Body text: 1rem with 1.65rem line height

Layout

• Max content width: 64rem
• Left sidebar navigation (collapsible on mobile)
• Right-side table of contents
• Responsive: 3 columns (desktop) → 2 columns (tablet) → 1 column (mobile)

UI Components

• Code blocks: Syntax highlighting with copy button, dark background
• Callouts: Info, warning, tip boxes with accent colors
• Tables: Full-width with horizontal scroll on mobile, alternating row colors
• Mermaid diagrams: Cream background with subtle grid overlay (light), dark with muted accent grid (dark)
• Buttons: Primary (warm accent), secondary (light with border), ghost variants

Site Structure

/
├── Getting Started
│   ├── Overview
│   ├── Installation
│   ├── Quick Start
│   └── Configuration
├── Core Concepts
│   ├── Multi-Agent Orchestration
│   ├── Cloister (AI Lifecycle Manager)
│   ├── Specialist Agents
│   └── Workspaces
├── Features
│   ├── Skills System
│   ├── Heartbeat Hooks
│   ├── Health Monitoring
│   ├── Context Engineering
│   └── Agent CVs
├── CLI Reference
│   ├── pan up / down
│   ├── pan work issue
│   ├── pan specialists
│   ├── pan sync
│   └── All Commands
├── Dashboard
│   ├── Overview
│   ├── Board View
│   ├── Agent Monitoring
│   └── Activity Log
├── Integrations
│   ├── Linear
│   ├── GitHub
│   ├── Claude Code
│   ├── Cursor
│   └── Other AI Tools
├── Skills Library
│   ├── Built-in Skills
│   ├── Creating Custom Skills
│   └── Dev Skills
├── Advanced
│   ├── Self-Hosted Setup
│   ├── Docker Configuration
│   ├── Traefik & HTTPS
│   └── Troubleshooting
└── Contributing
    ├── Development Setup
    ├── Architecture
    └── Publishing

Pages to Create

Priority 1 (Launch)

• Home/landing page with hero section
• Installation guide
• Quick start tutorial
• Core CLI commands reference

Priority 2 (Core Docs)

• Cloister documentation
• Specialist agents guide
• Skills system documentation
• Dashboard user guide

Priority 3 (Advanced)

• Self-hosted deployment
• Integration guides
• Contributing guide
• API reference (if applicable)

Technical Requirements

• Set up Mintlify project with custom theme
• Configure domain (www.panopticon-cli.com)
• Set up GitHub integration for auto-deploy
• Add search functionality
• Configure analytics
• Add "Edit this page" links to GitHub

Content Migration

Extract and adapt content from:

• Current README.md
• docs/PRD-CLOISTER.md
• Skills in skills/ directory
• Inline code documentation

Acceptance Criteria

• Site is live at www.panopticon-cli.com
• All priority 1 pages complete and reviewed
• Dark/light mode working correctly
• Mobile responsive
• Search functional
• Code blocks have syntax highlighting and copy buttons
• Navigation matches proposed structure

[eltmon]

Update: Mintlify Integration Approach

We're using Mintlify with the main panopticon-cli repo as the docs source (not a separate docs repo).

Setup Complete

• ✅ Added docs.json to repo root to enable Mintlify integration
• ✅ Closed PAN-5 (docs restructuring) as duplicate - Mintlify handles structure

Next Steps

1. Go to Mintlify → Settings → Git
2. Select panopticon-cli from the repository dropdown (now unlocked)
3. Branch: main, Monorepo: OFF
4. Save changes

Docs Location

Markdown files will live in /docs/ directory in the main repo. Mintlify will render them at www.panopticon-cli.com.

Structure

docs/
├── introduction.mdx      # Landing page
├── quickstart.mdx        # Getting started
├── configuration.mdx     # Config reference
├── commands/
│   ├── pan-up.mdx
│   ├── pan-work-issue.mdx
│   └── ...
├── features/
│   ├── specialists.mdx
│   ├── skills.mdx
│   └── ...
└── api-reference/        # If needed

The separate docs repo can be deleted once migration is complete.

[eltmon]

Setup Complete - Mintlify Configuration

Current Status

✅ docs.json configured - Mintlify can now recognize the repo
✅ PAN-5 closed - Merged into this issue (Mintlify handles structure)
✅ introduction.mdx created - Landing page ready

Configuration File

The docs.json at repo root is configured with:

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Panopticon",
  "theme": "maple",
  "colors": {
    "primary": "#D4A27F",
    "light": "#E5C4A8",
    "dark": "#B8886A"
  },
  "favicon": "/favicon.svg",
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction"]
          }
        ]
      }
    ]
  }
}

Key Learnings (docs.json format)

1. colors is required - Must have primary, light, dark
2. navigation is an object, not array - Use { "tabs": [...] } format
3. Pages reference .mdx files without extension (e.g., "introduction" → introduction.mdx)
4. $schema enables validation in editors

Mintlify Dashboard Setup

1. Go to Mintlify Dashboard → Settings → Git
2. Select repository: eltmon/panopticon-cli
3. Branch: main
4. Monorepo: OFF
5. Save changes

File Structure for Docs

panopticon-cli/
├── docs.json              # Mintlify config
├── introduction.mdx       # Landing page
├── quickstart.mdx         # Getting started
├── installation.mdx       # Install guide
├── cli/
│   ├── overview.mdx
│   ├── pan-up.mdx
│   └── pan-work-issue.mdx
├── specialists/
│   ├── overview.mdx
│   ├── review-agent.mdx
│   └── merge-agent.mdx
└── skills/
    ├── overview.mdx
    └── creating-skills.mdx

Next Steps

1. Complete Mintlify dashboard setup (select repo)
2. Configure domain (www.panopticon-cli.com)
3. Add favicon.svg
4. Create Priority 1 pages (quickstart, installation, CLI reference)
5. Expand navigation in docs.json as pages are added

Adding New Pages

1. Create .mdx file with frontmatter:

---
title: Page Title
description: 'Brief description'
---

# Content here

2. Add to docs.json navigation:

{
  "group": "Group Name",
  "pages": ["existing-page", "new-page"]
}

3. Commit and push - Mintlify auto-deploys

References

• Mintlify docs.json format
• Global settings