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 <noreply@anthropic.com>

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:

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
+- Filter box to quickly find projects
-- Right-click context menu:
+- Double-click to open project dashboard
-  - Open Terminal
+- Right-click context menu (items shown based on configuration):
-  - Open in Editor
+  - Open Dashboard / Terminal / Editor
-  - View on Gitea
+  - View on Git Host / Documentation
-  - View Documentation
+  - Update / Deploy Docs
-  - 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