# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Development Hub** is the central orchestration project for Rob's multi-project development ecosystem. It provides:

1. **GUI Application** - PyQt6-based workspace with project list, splittable terminal panes, and session persistence
2. **CLI Tools** - Scripts to create and manage projects following consistent patterns

## GUI Application

### Running the App

```bash
cd ~/PycharmProjects/development-hub
source .venv/bin/activate
python -m development_hub
```

### Architecture

```
src/development_hub/
├── __init__.py
├── __main__.py             # Entry point
├── app.py                  # QApplication subclass
├── main_window.py          # Main window with menus
├── project_list.py         # Left panel - project list with filter
├── workspace_manager.py    # Splittable pane layout management
├── pane_widget.py          # Tab container with action menu
├── draggable_tab_widget.py # Cross-pane tab dragging support
├── terminal_widget.py      # PTY terminal with search bar
├── terminal_display.py     # Terminal rendering with scrollback
├── pty_manager.py          # PTY process management
├── project_discovery.py    # Auto-discover projects from paths
├── dialogs.py              # New Project, Settings, Setup Wizard dialogs
├── settings.py             # JSON persistence for settings & session
├── paths.py                # Centralized path resolution from settings
├── styles.py               # Dark theme stylesheet
├── models/                 # Data models (Goal, Todo, Milestone)
├── views/dashboard/        # Dashboard views and components
│   ├── project_dashboard.py
│   ├── data_store.py       # Data loading/saving with file watching
│   └── undo_manager.py     # Undo/redo support
├── parsers/                # Markdown file parsers
├── services/               # Business logic (git, health, progress)
└── widgets/                # Reusable UI components
```

### Key Classes

| Class | File | Purpose |
|-------|------|---------|
| `MainWindow` | main_window.py | QMainWindow with menus, splitter layout |
| `ProjectListWidget` | project_list.py | Project list with filter and context menu |
| `WorkspaceManager` | workspace_manager.py | Manages splittable pane layout |
| `PaneWidget` | pane_widget.py | Tab container with action menu |
| `DraggableTabWidget` | draggable_tab_widget.py | Tab widget supporting cross-pane drag |
| `TerminalWidget` | terminal_widget.py | PTY terminal with search and auto-accept |
| `TerminalDisplay` | terminal_display.py | Terminal rendering with scrollback buffer |
| `AutoAcceptToast` | terminal_widget.py | Countdown toast for auto-accept prompts |
| `AutoAcceptDialog` | dialogs.py | Duration selection for auto-accept |
| `ImportPlanDialog` | dialogs.py | Import implementation plans to milestones |
| `SetupWizardDialog` | dialogs.py | Multi-page first-run wizard |
| `SettingsDialog` | dialogs.py | Application settings with docs mode |
| `PathResolver` | paths.py | Centralized path resolution singleton |
| `DashboardDataStore` | views/dashboard/data_store.py | Data persistence with file watching |
| `UndoManager` | views/dashboard/undo_manager.py | Undo/redo action management |

### Features

- **Project List**: Discovers projects from configurable search paths
- **Project Filtering**: Filter box to quickly find projects by name or key
- **Context Menu**: Open terminal, editor, git host, docs, deploy (items hidden when not configured)
- **Splittable Panes**: Horizontal/vertical splits, each pane has own tab bar
- **Cross-Pane Tab Dragging**: Drag tabs between panes to reorganize workspace
- **Terminal**: Full PTY with pyte for TUI support (vim, htop work)
- **Terminal Scrollback**: 10,000 line history with Shift+PageUp/Down navigation
- **Terminal Search**: Ctrl+Shift+F to search output with match highlighting
- **Terminal Error Recovery**: Graceful shell crash handling, Enter to restart
- **Drag & Drop**: Drop files/folders into terminal to inject paths
- **Session Persistence**: Remembers pane layout and open terminals
- **External File Watching**: Dashboard auto-reloads when files modified externally
- **New Project Dialog**: Integrates with Ramble for voice input
- **Progress Reports**: Export weekly progress summaries from daily standups
- **Auto-accept Prompts**: Automatically accept Y/yes prompts in terminals for CLI tools (Claude, Codex, etc.)
- **Plan Import**: Import implementation plans into milestones via right-click context menu
- **Phase Grouping**: Todos can be grouped by phase within milestones using `[Phase N]` prefix
- **Milestone Discussions**: Start discussions directly from milestones for implementation planning
- **Workspace Files**: Export/import configuration via YAML for sharing setups
- **First-Run Wizard**: Multi-page setup wizard with Simple/Documentation/Import modes
- **Documentation Modes**: Standalone (local storage) or Project-Docs (Docusaurus integration)
- **Graceful Degradation**: Features hide when dependencies unavailable (CmdForge, git, docs)

### Keyboard Shortcuts

#### Global Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+T` | New terminal tab |
| `Ctrl+Shift+W` | Close current tab |
| `Ctrl+Shift+D` | Split pane horizontal |
| `Ctrl+Shift+E` | Split pane vertical |
| `Ctrl+Shift+P` | Close active pane |
| `Ctrl+Alt+Left/Right` | Switch panes |
| `Ctrl+B` | Toggle project panel |
| `Ctrl+G` | Global Dashboard |
| `Ctrl+N` | New project dialog |
| `Ctrl+D` | New discussion |
| `Ctrl+R` | Weekly progress report |
| `Ctrl+Z` | Undo (in dashboard) |
| `Ctrl+Shift+Z` | Redo (in dashboard) |
| `F5` | Refresh project list |

#### Terminal Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+F` | Open search bar |
| `Ctrl+Shift+V` | Paste from clipboard |
| `Shift+PageUp/Down` | Scroll through history |
| `Enter` (in search) | Next match |
| `Shift+Enter` (in search) | Previous match |
| `F3` / `Shift+F3` | Next/previous match |
| `Escape` | Close search bar |

### Auto-accept Prompts

The terminal includes an auto-accept feature for handling Y/yes confirmation prompts from CLI tools like Claude Code, Codex, etc. This is useful when running long-running AI tasks that may ask many permission questions.

**How to use:**
1. Click ☰ (action menu) → "Auto-accept prompts..."
2. Select a duration (5 min, 15 min, 30 min, 1 hour, or custom)
3. When a Y/yes prompt is detected, a toast appears with a 5-second countdown
4. Click "Skip" to ignore, "Accept" to confirm immediately, or wait for countdown
5. Tab badge shows remaining time (e.g., `⏱4:32`)
6. Click ☰ → "Stop auto-accept" to disable early

**Supported patterns:**
- Standard `[Y/n]`, `[y/N]`, `(y/n)` prompts
- Claude Code permission dialogs with `❯ 1. Yes` menu selection

#### Dashboard Shortcuts (when dashboard tab is active)

| Shortcut | Action |
|----------|--------|
| `/` | Focus add todo input |
| `Ctrl+1` | Switch to priority view |
| `Ctrl+2` | Switch to milestone view |
| `Ctrl+3` | Switch to show all view |
| `Ctrl+]` | Expand all sections |
| `Ctrl+[` | Collapse all sections |

### Dashboard Data Sync

The dashboard automatically syncs data between documentation files:

- **Deliverables → TODOs**: When loading a project dashboard, deliverables from `milestones.md` tables are synced to `todos.md`. If a deliverable doesn't exist as a todo (matched by text + milestone ID), it's added with the appropriate `@M#` tag and priority.
- **TODOs → Milestone Progress**: The milestone progress bar is calculated from linked todos (items tagged with `@M#`), not from the deliverables table.

This means you can define major work items in milestone deliverable tables, and they'll automatically appear in your todo list for tracking.

### Todo Notes

Todos can have optional notes that provide additional context. Notes are displayed as tooltips when hovering over todo items and are persisted as indented blockquote lines in `todos.md`:

```markdown
- [ ] [Phase 1] Add settings module @M4
  > File: settings.py - Add DEFAULTS and properties
- [ ] Task without notes @M4
```

Notes are automatically extracted when importing plans via the Import Plan dialog and preserved through save/reload cycles.

### Workspace Files

Development Hub supports exporting and importing configuration via YAML workspace files. This allows sharing setups between machines or users.

**Export/Import via menu:** File → Export Workspace... / Import Workspace...

**Workspace file format:**
```yaml
# ~/.devhub-workspace.yaml
name: "My Development Environment"
version: 1

paths:
  projects_root: ~/PycharmProjects
  docs_root: ~/PycharmProjects/project-docs/docs  # Optional

documentation:
  enabled: true
  mode: project-docs  # "standalone" | "project-docs"
  docusaurus_path: ~/PycharmProjects/project-docs
  auto_start_server: true

git_hosting:
  type: gitea  # "gitea" | "github" | "gitlab"
  url: https://gitea.example.com
  owner: username
  pages_url: https://pages.example.com  # Optional

features:
  cmdforge_integration: true
  progress_tracking: true
```

### Documentation Modes

Development Hub supports two documentation modes:

1. **Standalone Mode**: Data stored locally in `~/.local/share/development-hub/`. No Docusaurus integration. Good for simple use cases.

2. **Project-Docs Mode**: Full Docusaurus integration with centralized documentation. Supports auto-start docs server, deploy scripts, and pages hosting.

The mode is configured during first-run setup or in Settings → Documentation.

### First-Run Wizard

On first launch (when no `settings.json` exists), the setup wizard appears with three options:

1. **Simple Mode**: Quick setup with just a projects directory. Documentation features disabled.
2. **Documentation Mode**: Full setup with Docusaurus path, git hosting, and pages configuration.
3. **Import Workspace**: Load settings from a `.devhub-workspace.yaml` file.

Existing users are unaffected - the wizard only appears when `setup_completed` is false.

## CLI Scripts

### `bin/new-project`

Creates a new project in the ecosystem with all the standard setup:

```bash
# Full usage
new-project myproject --title "My Project" --tagline "Short description"

# Interactive mode (prompts for title/tagline)
new-project myproject

# Options
--title "..."     Display title for the project
--tagline "..."   Short description
--dry-run         Show what would happen without making changes
--skip-gitea      Skip Gitea repository creation (for offline use)
```

**What it does:**
1. Creates Gitea repository via API
2. Creates local project directory with git
3. Generates project files from templates (CLAUDE.md, README.md, .gitignore, pyproject.toml)
4. Sets up documentation symlink to project-docs
5. Updates build-public-docs.sh to include the new project
6. Creates initial commit and pushes

## Project Structure

```
development-hub/
├── src/development_hub/      # GUI application (see Architecture above)
├── bin/
│   └── new-project           # CLI scaffolding script
├── templates/
│   ├── gitignore.template    # Python .gitignore with docs exclusion
│   ├── CLAUDE.md.template    # AI context file
│   ├── README.md.template    # Basic README
│   ├── pyproject.toml.template
│   ├── overview.md.template  # Docs overview
│   └── updating-documentation.md.template
├── docs/                     # Symlink to project-docs
├── pyproject.toml            # Python packaging with PyQt6 dep
├── CLAUDE.md                 # This file
├── README.md
└── .gitignore
```

## Template Placeholders

Templates use these placeholders (replaced by sed):

- `{{PROJECT_NAME}}` - lowercase project name (e.g., "my-tool")
- `{{PROJECT_TITLE}}` - display title (e.g., "My Tool")
- `{{PROJECT_TAGLINE}}` - short description
- `{{YEAR}}` - current year
- `{{DATE}}` - creation date
- `{{GITEA_URL}}` - https://gitea.brrd.tech
- `{{GITEA_OWNER}}` - rob

## Configuration

### Settings File

Settings are stored in `~/.config/development-hub/settings.json`. Key settings:

| Setting | Default | Description |
|---------|---------|-------------|
| `docs_mode` | `"auto"` | `"auto"`, `"standalone"`, or `"project-docs"` |
| `docs_root` | `""` | Override docs root path (empty = derive from mode) |
| `docusaurus_path` | `""` | Path to project-docs directory |
| `pages_url` | `""` | URL for documentation pages hosting |
| `cmdforge_path` | `""` | Override CmdForge installation path |
| `progress_dir` | `""` | Override progress log directory |
| `auto_start_docs_server` | `true` | Start Docusaurus dev server on launch |
| `git_host_type` | `""` | `"gitea"`, `"github"`, or `"gitlab"` |
| `git_host_url` | `""` | Git hosting URL |
| `git_host_owner` | `""` | Username or organization |
| `git_host_token` | `""` | API token for repo creation |

### Path Resolution

The `PathResolver` class (`paths.py`) centralizes all path lookups:

```python
from development_hub.paths import paths

paths.projects_root      # Primary projects directory
paths.docs_root          # Documentation root
paths.project_docs_dir   # Docusaurus project directory
paths.progress_dir       # Progress log directory
paths.build_script       # build-public-docs.sh path
paths.cmdforge_executable  # CmdForge binary path

paths.project_docs_path("myproject")  # Docs for specific project
paths.git_url("owner", "repo")        # Git repository URL
paths.pages_url("owner", "repo")      # Pages URL for project
```

### Gitea API Token

The script needs a Gitea API token to create repositories:

1. **Environment variable**: `GITEA_TOKEN`
2. **Config file**: `~/.config/development-hub/gitea-token`

To create a token:
1. Go to https://gitea.brrd.tech/user/settings/applications
2. Generate a new token with 'repo' scope
3. The script will prompt and save it automatically

## Documentation

Documentation lives in the centralized docs system:

- **Source**: `~/PycharmProjects/project-docs/docs/projects/development-hub/`
- **Public URL**: `https://pages.brrd.tech/rob/development-hub/`

When updating documentation:
1. Edit files in `docs/` (the symlink)
2. Use `public: true` frontmatter for public-facing docs
3. Run `~/PycharmProjects/project-docs/scripts/build-public-docs.sh development-hub --deploy` to publish

## Related Projects

This project manages and creates projects in the ecosystem:

- **CmdForge** - AI-powered CLI tool builder
- **CascadingDev** - Cascading Development Framework
- **Orchestrated Discussions** - AI Discussion Framework
- **Artifact Editor** - Code Artifact Editor
- **Ramble** - Voice Note Transcription

All projects follow the same documentation pattern and can be created using `new-project`.