From 5742b7088b9e0c8ed81bf838070e670cc78dd5b0 Mon Sep 17 00:00:00 2001 From: rob Date: Sun, 25 Jan 2026 05:48:47 -0400 Subject: [PATCH] Update documentation for workspace files feature - Update CLAUDE.md with new architecture, classes, features - Add workspace files and configuration sections - Update README.md with first-run setup and workspace files Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++- README.md | 29 +++++++++---- 2 files changed, 139 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c5458b4..39b3cb6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,8 +35,9 @@ src/development_hub/ ├── 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, Preview dialogs +├── 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 @@ -61,6 +62,10 @@ src/development_hub/ | `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 | @@ -68,7 +73,7 @@ src/development_hub/ - **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, Gitea, docs, deploy +- **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) @@ -81,6 +86,13 @@ src/development_hub/ - **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 @@ -95,6 +107,7 @@ src/development_hub/ | `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 | @@ -150,6 +163,71 @@ The dashboard automatically syncs data between documentation files: 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` @@ -213,6 +291,43 @@ Templates use these placeholders (replaced by sed): ## 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: diff --git a/README.md b/README.md index 1aecc13..4c5978c 100644 --- a/README.md +++ b/README.md @@ -90,13 +90,12 @@ To create manually: ### Project List (Left Panel) - Auto-discovers projects from build configuration -- Double-click to open terminal at project root -- Right-click context menu: - - Open Terminal - - Open in Editor - - View on Gitea - - View Documentation - - Deploy Docs +- Filter box to quickly find projects +- Double-click to open project dashboard +- Right-click context menu (items shown based on configuration): + - Open Dashboard / Terminal / Editor + - View on Git Host / Documentation + - Update / Deploy Docs ### Workspace (Right Panel) - Splittable panes (horizontal/vertical) @@ -104,6 +103,20 @@ To create manually: - Full PTY terminals with TUI support (vim, htop, etc.) - Drag & drop files/folders to inject paths - Session persistence - remembers layout on restart +- Auto-accept prompts for AI CLI tools + +### First-Run Setup + +On first launch, a setup wizard helps configure: +- **Simple Mode**: Just a projects directory, local data storage +- **Documentation Mode**: Full Docusaurus integration with git hosting +- **Import Workspace**: Load settings from a YAML file + +### Workspace Files + +Export your configuration to share with others: +- File → Export Workspace... (creates `.devhub-workspace.yaml`) +- File → Import Workspace... (loads settings from file) ### Keyboard Shortcuts @@ -116,6 +129,8 @@ To create manually: | `Ctrl+Alt+Left/Right` | Switch panes | | `Ctrl+B` | Toggle project panel | | `Ctrl+N` | New project dialog | +| `Ctrl+G` | Global Dashboard | +| `Ctrl+R` | Weekly progress report | ## Full Documentation