docs: update documentation for v2.24 release features (#825)

- README: add parallel orchestration link, update loop diagram with validate-milestone phase
- architecture: add lazy provider loading, memory-extractor/store modules, update module table to v2.24
- auto-mode: add rate limit recovery section, parallel worker status in dashboard
- commands: add headless new-milestone command with --context/--context-text/--auto flags
- getting-started: add update check notification note
- troubleshooting: update rate limit recovery guidance
- visualizer: add task counts, discussion status to progress tab

README.md

@@ -32,6 +32,7 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing (v2.17)
 - **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections
 - **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior
+- **[Parallel Orchestration](./docs/parallel-orchestration.md)** — run multiple milestones simultaneously
 - **[Working in Teams](./docs/working-in-teams.md)** — unique IDs, shared artifacts
 - **[Skills](./docs/skills.md)** — bundled skills, discovery, custom authoring
 - **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts
@@ -112,9 +113,11 @@ Each slice flows through phases automatically:
 
 ```
 Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
+                                                                      ↓ (all slices done)
+                                                              Validate Milestone → Complete Milestone
 ```
 
-**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned.
+**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 ### `/gsd auto` — The Main Event
 

docs/architecture.md

@@ -43,6 +43,10 @@ vscode-extension/         VS Code extension — chat participant (@gsd), sidebar
 
 Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run. This means `npm update -g` takes effect immediately.
 
+### Lazy Provider Loading
+
+LLM provider SDKs (Anthropic, OpenAI, Google, etc.) are lazy-loaded on first use rather than imported at startup. This significantly reduces cold-start time — only the provider you actually connect to gets loaded.
+
 ### Fresh Session Per Unit
 
 Every dispatch creates a new agent session. The LLM starts with a clean context window containing only the pre-inlined artifacts it needs. This prevents quality degradation from context accumulation.
@@ -118,7 +122,7 @@ The auto mode dispatch pipeline:
 
 Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the corresponding unit type is never dispatched.
 
-## Key Modules (v2.19)
+## Key Modules (v2.24)
 
 | Module | Purpose |
 |--------|---------|
@@ -134,8 +138,11 @@ Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the
 | `triage-resolution.ts` | Capture resolution (inject, defer, replan, quick-task) |
 | `visualizer-overlay.ts` | Workflow visualizer TUI overlay |
 | `visualizer-data.ts` | Data loading for visualizer tabs |
-| `visualizer-views.ts` | Tab renderers (progress, deps, metrics, timeline) |
+| `visualizer-views.ts` | Tab renderers (progress, deps, metrics, timeline, discussion status) |
 | `metrics.ts` | Token and cost tracking ledger |
 | `state.ts` | State derivation from disk |
 | `preferences.ts` | Preference loading, merging, validation |
+| `git-service.ts` | Git operations — commit, merge, worktree sync, completed-units cross-boundary sync |
+| `memory-extractor.ts` | Extract reusable knowledge from session transcripts |
+| `memory-store.ts` | Persistent memory store for cross-session knowledge |
 | `queue-order.ts` | Milestone queue ordering |

docs/auto-mode.md

@@ -62,6 +62,10 @@ When your project has independent milestones, you can run them simultaneously. E
 
 A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
 
+### Rate Limit Recovery
+
+When a provider hits a rate limit, GSD waits with exponential backoff (up to 5 minutes) and automatically resumes auto-mode after the cooldown period. No manual intervention needed — the session continues from where it left off.
+
 ### Stuck Detection
 
 If the same unit dispatches twice (the LLM didn't produce the expected artifact), GSD retries once with a deep diagnostic prompt. If it fails again, auto mode stops with the exact file it expected, so you can intervene.
@@ -161,6 +165,7 @@ Open the workflow visualizer — interactive tabs for progress, dependencies, me
 - Cost projections
 - Completed and in-progress units
 - Pending capture count (when captures are awaiting triage)
+- Parallel worker status (when running parallel milestones — includes 80% budget alert)
 
 ## Phase Skipping
 

docs/commands.md

@@ -92,6 +92,7 @@ See [Parallel Orchestration](./parallel-orchestration.md) for full documentation
 | `gsd --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues |
 | `gsd config` | Re-run the setup wizard (LLM provider + tool keys) |
 | `gsd update` | Update GSD to the latest version |
+| `gsd headless new-milestone` | Create a new milestone from a context file (headless — no TUI required) |
 
 ## Headless Mode
 
@@ -112,6 +113,15 @@ gsd headless --timeout 600000 auto
 
 # Force a specific phase
 gsd headless dispatch plan
+
+# Create a new milestone from a context file and start auto mode
+gsd headless new-milestone --context brief.md --auto
+
+# Create a milestone from inline text
+gsd headless new-milestone --context-text "Build a REST API with auth"
+
+# Pipe context from stdin
+echo "Build a CLI tool" | gsd headless new-milestone --context -
 ```
 
 | Flag | Description |
@@ -119,6 +129,9 @@ gsd headless dispatch plan
 | `--timeout N` | Overall timeout in milliseconds (default: 300000 / 5 min) |
 | `--json` | Stream all events as JSONL to stdout |
 | `--model ID` | Override the model for the headless session |
+| `--context <file>` | Context file for `new-milestone` (use `-` for stdin) |
+| `--context-text <text>` | Inline context text for `new-milestone` |
+| `--auto` | Chain into auto-mode after milestone creation |
 
 **Exit codes:** `0` = complete, `1` = error or timeout, `2` = blocked.
 

docs/getting-started.md

@@ -8,6 +8,8 @@ npm install -g gsd-pi
 
 Requires Node.js ≥ 20.6.0 (22+ recommended) and Git.
 
+GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip.
+
 ### VS Code Extension
 
 GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions. The extension provides:

docs/troubleshooting.md

@@ -52,7 +52,7 @@ It checks:
 
 **Symptoms:** Auto mode pauses with a provider error (rate limit, auth failure, etc.).
 
-**Fix:** GSD automatically tries fallback models if configured. To add fallbacks:
+**Fix:** GSD automatically resumes after rate limit cooldowns with exponential backoff (up to 5 minutes). For auth failures, GSD tries fallback models if configured:
 
 ```yaml
 models:

docs/visualizer.md

@@ -25,18 +25,20 @@ Switch tabs with `Tab`, `1`-`4`, or arrow keys.
 A tree view of milestones, slices, and tasks with completion status:
 
 ```
-M001: User Management
-  ✅ S01: Auth module
+M001: User Management                        3/6 tasks ⏳
+  ✅ S01: Auth module                         3/3 tasks
     ✅ T01: Core types
     ✅ T02: JWT middleware
     ✅ T03: Login flow
-  ⏳ S02: User dashboard
+  ⏳ S02: User dashboard                      1/2 tasks
     ✅ T01: Layout component
     ⬜ T02: Profile page
-  ⬜ S03: Admin panel
+  ⬜ S03: Admin panel                         0/1 tasks
 ```
 
-Shows checkmarks for completed items, spinners for in-progress, and empty boxes for pending.
+Shows checkmarks for completed items, spinners for in-progress, and empty boxes for pending. Task counts and completion percentages are displayed at each level.
+
+**Discussion status** is also shown when milestones have been through a discussion phase — indicates whether requirements were captured and what state the discussion left off in.
 
 ### 2. Dependencies