mkdocs.yml

site_name: Flow CLI Documentation
site_description: Minimalist ZSH workflow tools with smart dispatchers. Track work sessions, manage multiple projects, visualize productivity metrics with ADHD-friendly design.
site_author: DT
site_url: https://data-wise.github.io/flow-cli

# Copyright and license
copyright: Copyright © 2025-2026 DT. Released under MIT License.

repo_name: flow-cli
repo_url: https://github.com/data-wise/flow-cli
edit_uri: edit/main/docs/

theme:
  name: material
  palette:
    # Light mode - ADHD-calm warm earth tones
    - media: '(prefers-color-scheme: light)'
      scheme: default
      primary: brown
      accent: deep orange
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode - ADHD-calm warm earth tones
    - media: '(prefers-color-scheme: dark)'
      scheme: slate
      primary: brown
      accent: deep orange
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.action.edit

plugins:
  - search
  - tags
  - exclude:
      glob:
        - doc-index.md
        - '*.bak'
        - '*.tmp'
        - 'specs/**'
        - 'reports/**'
        - 'plans/**'
        - 'implementation/**'
        - 'bugs/**'
        - 'diagrams/**'
        - 'releases/**'
        - 'demos/*.md'
        - 'demos/**/*.md'
        - '.archive/**'
        - 'reference/.archive/**'
        - 'BRAINSTORM-*.md'
        - 'DECISION-*.md'
        - 'SESSION-*.md'
        - 'IMPLEMENTATION-PLAN-*.md'
        - 'SECRET-MANAGEMENT.md'
        - 'AWESOME-ZSH-PLUGINS-ENTRY.md'
        - 'FEATURE-REQUEST-QUARTO-WORKFLOW-ENHANCEMENTS.md'
        - 'internal/conventions/code/**'
        - 'internal/conventions/documentation/**'
        - 'internal/conventions/project/**'
        - 'internal/VHS-TAPE-STYLE-GUIDE.md'
        - 'assets/gifs/nvim/README.md'

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.tabbed:
      alternate_style: true
  - tables
  - attr_list
  - md_in_html
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - toc:
      permalink: true

nav:
  - Home: index.md
  # ── Getting Started (merged: Getting Started + Help) ──────────────
  - ⚡ Getting Started:
      - getting-started/index.md
      - 🎯 Choose Your Path: getting-started/choose-your-path.md
      - ⚡ Quick Start (5-min): getting-started/quick-start.md
      - 📦 Installation: getting-started/installation.md
      - 🆘 I'm Stuck: getting-started/im-stuck.md
      - Welcome: getting-started/00-welcome.md
      - ❓ FAQ: getting-started/faq.md
      - ❓ FAQ - Dependencies: getting-started/faq-dependencies.md
      - 🔄 Troubleshooting: getting-started/troubleshooting.md
      - ⚡ Quick Reference: help/QUICK-REFERENCE.md
      - 🔧 Common Workflows: help/WORKFLOWS.md
      - 🩺 General Troubleshooting: help/TROUBLESHOOTING.md
      - 🤖 Claude Code Environment: troubleshooting/CLAUDE-CODE-ENVIRONMENT.md
      - 🎉 Release Notes: RELEASES.md
      - 📜 Changelog: CHANGELOG.md
  # ── Learn (merged: Tutorials, grouped into subsections) ───────────
  - 📖 Learn:
      - Overview & Learning Path: tutorials/index.md
      - Core Workflows:
          - 1. Your First Session: tutorials/01-first-session.md
          - 2. Multiple Projects: tutorials/02-multiple-projects.md
          - 3. Status Visualizations: tutorials/03-status-visualizations.md
          - 4. Web Dashboard: tutorials/04-web-dashboard.md
          - 5. AI-Powered Commands: tutorials/05-ai-commands.md
          - 6. Dopamine Features: tutorials/06-dopamine-features.md
          - 34. Editor Workflow: tutorials/34-editor-workflow.md
      - Git & Projects:
          - 7. Sync Command: tutorials/07-sync-command.md
          - 8. Git Feature Workflow: tutorials/08-git-feature-workflow.md
          - 9. Worktrees: tutorials/09-worktrees.md
          - 22. Plugin Optimization: tutorials/22-plugin-optimization.md
          - 23. Token Automation: tutorials/23-token-automation.md
      - Dispatchers:
          - 10. CC Dispatcher: tutorials/10-cc-dispatcher.md
          - 11. TM Dispatcher: tutorials/11-tm-dispatcher.md
          - 12. Dotfiles/Secrets/Tokens: tutorials/12-dot-dispatcher.md
          - 13. Prompt Dispatcher: tutorials/13-prompt-dispatcher.md
          - 37. MCP Servers: tutorials/37-mcp-dispatcher.md
          - 38. R Packages: tutorials/38-r-dispatcher.md
          - 39. Quarto Publishing: tutorials/39-qu-dispatcher.md
          - 40. Workflow (v/vibe): tutorials/40-v-dispatcher.md
          - 41. Obsidian Vaults: tutorials/41-obs-dispatcher.md
          - 42. Git Shortcuts (g): tutorials/42-g-dispatcher.md
      - ADHD & Productivity:
          - 43. ADHD Daily Routine: tutorials/43-adhd-daily-routine.md
          - 44. Quick Capture: tutorials/44-quick-capture.md
      - Editor (Neovim):
          - 15. Nvim Quick Start: tutorials/15-nvim-quick-start.md
          - 16. Vim Motions: tutorials/16-vim-motions.md
          - 17. LazyVim Basics: tutorials/17-lazyvim-basics.md
          - 18. LazyVim Showcase: tutorials/18-lazyvim-showcase.md
  # ── Teaching (kept as-is, already well-organized) ─────────────────
  - 🎓 Teaching:
      - Overview: teaching/index.md
      - Getting Started:
          - Quick Start: tutorials/14-teach-dispatcher.md
          - Setup & Initialization: commands/teach-init.md
          - Complete v3.0 Workflow: guides/TEACHING-WORKFLOW-V3-GUIDE.md
      - Core Workflows:
          - Content Creation: guides/INTELLIGENT-CONTENT-ANALYSIS.md
          - Scholar Wrappers: guides/SCHOLAR-WRAPPERS-GUIDE.md
          - Scholar Config Sync: guides/SCHOLAR-INTEGRATION-GUIDE.md
          - Deployment: guides/TEACH-DEPLOY-GUIDE.md
          - Deploy v2 (Direct, History, Rollback): tutorials/31-teach-deploy-v2.md
          - Git Integration: tutorials/19-teaching-git-integration.md
          - Date Automation: tutorials/20-teaching-dates-automation.md
          - Visual Workflow Guide: guides/TEACHING-WORKFLOW-VISUAL.md
      - Features:
          - Content Analysis: tutorials/21-teach-analyze.md
          - AI-Powered Prompts: tutorials/28-teach-prompt.md
          - Health Check (Doctor v2): tutorials/32-teach-doctor.md
          - Lint Validation: tutorials/45-lint-quickstart.md
          - Template Management: tutorials/24-template-management.md
          - LaTeX Macros: tutorials/26-latex-macros.md
          - Lesson Plans: tutorials/27-lesson-plan-management.md
          - Lesson Plan Migration: tutorials/25-lesson-plan-migration.md
          - Backup & Safety: guides/BACKUP-SYSTEM-GUIDE.md
      - Tutorials:
          - First Exam Walkthrough: tutorials/29-first-exam-walkthrough.md
          - New Instructor Workflow: tutorials/30-new-instructor-complete-workflow.md
      - Reference:
          - Command Overview: commands/teach.md
          - Config Schema: reference/TEACH-CONFIG-SCHEMA.md
          - Quick Reference Cards:
              - All Commands: reference/REFCARD-TEACH-DISPATCHER.md
              - Lint Validation: reference/REFCARD-LINT.md
              - Content Analysis: reference/REFCARD-ANALYSIS.md
              - Date Management: reference/REFCARD-DATES.md
              - Health Check: reference/REFCARD-DOCTOR.md
              - Templates: reference/REFCARD-TEMPLATES.md
              - LaTeX Macros: reference/REFCARD-MACROS.md
              - Lesson Plans: reference/REFCARD-TEACH-PLAN.md
              - Prompts: reference/REFCARD-PROMPTS.md
              - Deploy v2: reference/REFCARD-DEPLOY-V2.md
              - Scholar Flags: reference/REFCARD-SCHOLAR-FLAGS.md
              - Scholar Wrappers: reference/REFCARD-SCHOLAR-WRAPPERS.md
          - Troubleshooting: guides/TEACHING-TROUBLESHOOTING.md
          - Help System: guides/HELP-SYSTEM-GUIDE.md
      - Advanced:
          - Scholar Integration:
              - Overview & Learning Path: tutorials/scholar-enhancement/index.md
              - Level 1 - Getting Started: tutorials/scholar-enhancement/01-getting-started.md
              - Level 2 - Intermediate: tutorials/scholar-enhancement/02-intermediate.md
              - Level 3 - Advanced: tutorials/scholar-enhancement/03-advanced.md
          - Course Planning Best Practices: guides/COURSE-PLANNING-BEST-PRACTICES.md
          - Migration from v2: guides/TEACHING-V3-MIGRATION-GUIDE.md
          - System Architecture: guides/TEACHING-SYSTEM-ARCHITECTURE.md
          - Course Examples:
              - Overview: examples/course-planning/README.md
              - STAT 545 (Graduate): examples/course-planning/intermediate-stats/README.md
      - Legacy (v2.x):
          - v2 Workflow: guides/TEACHING-WORKFLOW.md
          - Commands Deep Dive: guides/TEACHING-COMMANDS-DETAILED.md
          - Dates Guide: guides/TEACHING-DATES-GUIDE.md
          - Demo & GIFs: guides/TEACHING-DEMO-GUIDE.md
  # ── Email (himalaya integrations: CLI + Editor) ─────────────────
  - 📧 Email:
      - Himalaya Setup: guides/HIMALAYA-SETUP.md
      - CLI (em dispatcher):
          - Guide: guides/EMAIL-DISPATCHER-GUIDE.md
          - Tutorial: guides/EMAIL-TUTORIAL.md
          - 35. Email CLI: tutorials/35-em-cli-email.md
          - 36. Email Management: tutorials/36-em-delete-actions.md
          - 46. em v2.0 Features: tutorials/46-em-v2-features.md
          - Cookbook: guides/EMAIL-COOKBOOK.md
          - Quick Reference: reference/REFCARD-EMAIL-DISPATCHER.md
      - Editor (Neovim):
          - Guide: guides/HIMALAYA-NVIM-SETUP.md
          - Tutorial: tutorials/33-himalaya-email.md
          - Quick Reference: reference/REFCARD-HIMALAYA.md
  # ── Workflows & Guides (merged: Workflows + Guides) ──────────────
  - 🔧 Workflows & Guides:
      - guides/index.md
      - Start Here: guides/00-START-HERE.md
      - Quick Wins: guides/WORKFLOWS-QUICK-WINS.md
      - Git & Branching:
          - Git Dispatcher (g): reference/REFCARD-GIT-DISPATCHER.md
          - Git Feature Flow: tutorials/08-git-feature-workflow.md
          - Worktree Workflow: guides/WORKTREE-WORKFLOW.md
      - Dotfiles & Config:
          - 'Migration: dot → dots/sec/tok': guides/MIGRATION-DOT-SPLIT.md
          - Dotfile Workflow: guides/DOT-WORKFLOW.md
          - Dotfile Management: guides/DOTFILE-MANAGEMENT.md
          - 🛡️ Chezmoi Safety Features: guides/CHEZMOI-SAFETY-GUIDE.md
          - Config Management: guides/CONFIG-MANAGEMENT-WORKFLOW.md
          - Alias Management: guides/ALIAS-MANAGEMENT-WORKFLOW.md
      - Tools & Integrations:
          - 🔗 Atlas Integration: guides/ATLAS-INTEGRATION-GUIDE.md
          - 🔌 ZSH Plugin Ecosystem: guides/ZSH-PLUGIN-ECOSYSTEM-GUIDE.md
          - 🔐 Token Management: guides/TOKEN-MANAGEMENT-COMPLETE.md
          - 🩺 Doctor Token Guide: guides/DOCTOR-TOKEN-USER-GUIDE.md
          - 🚀 Quarto Workflow Phase 2: guides/QUARTO-WORKFLOW-PHASE-2-GUIDE.md
          - 🔍 Lint Validation:
              - User Guide: guides/LINT-GUIDE.md
              - Migration Guide: guides/LINT-MIGRATION-GUIDE.md
          - Lint Workflow: workflows/WORKFLOW-LINT.md
          - Quality Gates: guides/QUALITY-GATES.md
          - Mermaid Diagrams: guides/MERMAID-DIAGRAMS-QUICK-START.md
          - 🎯 Prompt Dispatcher Guide: guides/PROMPT-DISPATCHER-GUIDE.md
          - Enhanced Help: guides/ENHANCED-HELP-QUICK-START.md
          - Monorepo Commands: guides/MONOREPO-COMMANDS-TUTORIAL.md
          - Dopamine Features: guides/DOPAMINE-FEATURES-GUIDE.md
      - Advanced:
          - YOLO Mode: guides/YOLO-MODE-WORKFLOW.md
          - Plugin Management: guides/PLUGIN-MANAGEMENT-WORKFLOW.md
          - Project Scope: guides/PROJECT-SCOPE.md
          - Workflow Tutorial: guides/WORKFLOW-TUTORIAL.md
  # ── Reference (merged: Reference + Commands + Architecture) ───────
  - 📚 Reference:
      - reference/index.md
      - Tags Index: tags.md
      - API & Architecture:
          - 📚 Master API Reference: reference/MASTER-API-REFERENCE.md
          - 🎯 Master Dispatcher Guide: reference/MASTER-DISPATCHER-GUIDE.md
          - 🏗️ Master Architecture: reference/MASTER-ARCHITECTURE.md
          - 📊 Documentation Dashboard: DOC-DASHBOARD.md
      - Commands:
          - flow (main): commands/flow.md
          - work: commands/work.md
          - finish: commands/finish.md
          - hop: commands/hop.md
          - pick: commands/pick.md
          - alias: commands/alias.md
          - capture (win/yay/catch): commands/capture.md
          - timer: commands/timer.md
          - morning: commands/morning.md
          - dash: commands/dash.md
          - status: commands/status.md
          - sync: commands/sync.md
          - doctor: commands/doctor.md
          - config: commands/config.md
          - plugin: commands/plugin.md
          - ai: commands/ai.md
          - do: commands/do.md
          - install: commands/install.md
          - upgrade: commands/upgrade.md
          - at (Atlas bridge): commands/at.md
          - dashboard: commands/dashboard.md
      - Quick Reference Cards:
          - 🌳 Worktree (wt): reference/REFCARD-WORKTREE-DISPATCHER.md
          - 📁 Dotfiles (dots): reference/REFCARD-DOTFILE-DISPATCHER.md
          - 🔑 Secrets (sec): reference/REFCARD-SECRET-DISPATCHER.md
          - 🔐 Token & Secrets: reference/REFCARD-TOKEN-SECRETS.md
          - 🛡️ Chezmoi Safety: reference/REFCARD-DOT-SAFETY.md
          - 🛡️ Chezmoi Safety API: reference/API-DOT-SAFETY.md
      - Architecture Deep Dives:
          - 🛡️ Chezmoi Safety: architecture/DOT-SAFETY-ARCHITECTURE.md
          - 🔐 Doctor Token System: architecture/DOCTOR-TOKEN-ARCHITECTURE.md
          - 📅 Teaching Dates: architecture/TEACHING-DATES-ARCHITECTURE.md
          - 🎓 Scholar Enhancement: architecture/SCHOLAR-ENHANCEMENT-ARCHITECTURE.md
  # ── Contributing (merged: Development + Testing + Visuals + Planning)
  - 🛠️ Contributing:
      - contributing/index.md
      - 🛠️ Developer Guide: guides/DEVELOPER-GUIDE.md
      - Contributing: contributing/CONTRIBUTING.md
      - Branch Workflow: contributing/BRANCH-WORKFLOW.md
      - PR Workflow Guide: contributing/PR-WORKFLOW-GUIDE.md
      - Documentation Style Guide: contributing/DOCUMENTATION-STYLE-GUIDE.md
      - Documentation Templates: internal/conventions/adhd/README.md
      - GIF Creation Guide: internal/conventions/adhd/GIF-GUIDELINES.md
      - Guidelines: ZSH-DEVELOPMENT-GUIDELINES.md
      - Conventions: CONVENTIONS.md
      - Philosophy: PHILOSOPHY.md
      - Testing:
          - 🧪 Testing Guide: guides/TESTING.md
          - Safe Testing (v5.9.0): guides/SAFE-TESTING-v5.9.0.md
          - Interactive Dog Test: testing/DOG-FEEDING-TEST-README.md
          - Interactive Test Guide: testing/INTERACTIVE-TEST-GUIDE.md
      - Planning:
          - v4.3.0+ Roadmap: planning/V4.3-ROADMAP.md
          - Install Improvements: planning/INSTALL-IMPROVEMENTS.md
          - Feature Requests:
              - Config Consolidation: FEATURE-REQUEST-config-consolidation.md
              - Quarto Cache Clearing: FEATURE-REQUEST-qu-sass-cache-clearing.md
              - Scholar Config: FEATURE-REQUEST-scholar-config-consolidation.md

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/data-wise/flow-cli

extra_css:
  - stylesheets/extra.css
  - stylesheets/adhd-colors.css