development-hub/CLAUDE.md

# 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 discovery & context menu
├── workspace.py          # Right panel - splittable panes with tabs
├── terminal_widget.py    # PTY terminal with pyte emulation
├── project_discovery.py  # Parse projects from build-public-docs.sh
├── dialogs.py            # New Project (with Ramble), Settings dialogs
├── settings.py           # JSON persistence for settings & session
└── styles.py             # Dark theme stylesheet
```

### Key Classes

| Class | File | Purpose |
|-------|------|---------|
| `MainWindow` | main_window.py | QMainWindow with menus, splitter layout |
| `ProjectListWidget` | project_list.py | Project list with context menu actions |
| `WorkspaceManager` | workspace.py | Manages splittable pane layout |
| `PaneWidget` | workspace.py | Tab container within a pane |
| `TerminalWidget` | terminal_widget.py | PTY-based terminal with pyte screen emulation |

### Features

- **Project List**: Discovers projects from `build-public-docs.sh` config
- **Context Menu**: Open terminal, editor, Gitea, docs, deploy
- **Splittable Panes**: Horizontal/vertical splits, each pane has own tab bar
- **Terminal**: Full PTY with pyte for TUI support (vim, htop work)
- **Drag & Drop**: Drop files/folders into terminal to inject paths
- **Session Persistence**: Remembers pane layout and open terminals
- **New Project Dialog**: Integrates with Ramble for voice input

### Keyboard 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+N` | New project dialog |
| `F5` | Refresh project list |

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

### 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`.