2026-03-25 22:38:55 -06:00
# GSD Documentation
Welcome to the GSD documentation. This covers everything from getting started to advanced configuration, auto-mode internals, and extending GSD with the Pi SDK.
## User Documentation
| Guide | Description |
|-------|-------------|
| [Getting Started ](./getting-started.md ) | Installation, first run, and basic usage |
| [Auto Mode ](./auto-mode.md ) | How autonomous execution works — the state machine, crash recovery, and steering |
| [Commands Reference ](./commands.md ) | All commands, keyboard shortcuts, and CLI flags |
| [Remote Questions ](./remote-questions.md ) | Discord and Slack integration for headless auto-mode |
| [Configuration ](./configuration.md ) | Preferences, model selection, git settings, and token profiles |
docs: add provider setup guide for third-party LLM providers (#3294)
* docs: add provider setup guide and improve onboarding hints
Fixes #2161
Add docs/providers.md with step-by-step setup instructions for every
supported LLM provider: OpenRouter, Ollama, LM Studio, vLLM, SGLang,
and all built-in providers. Includes env var names, example configs,
common pitfalls, and verification steps.
Improve onboarding wizard:
- Add URL hints to provider selection list
- Show common local endpoints when choosing Custom (OpenAI-compatible)
- Add post-setup guidance for OpenRouter and custom endpoints
- Reference docs/providers.md for compat troubleshooting
Update cross-references in getting-started.md, troubleshooting.md,
docs/README.md, and help-text.ts to link to the new guide.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: verify config help mentions OpenRouter, Ollama, and docs/providers.md
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: trek-e <trek-e@users.noreply.github.com>
2026-04-05 00:48:19 -04:00
| [Provider Setup ](./providers.md ) | Step-by-step setup for OpenRouter, Ollama, LM Studio, vLLM, and all supported providers |
| [Custom Models ](./custom-models.md ) | Advanced model configuration — models.json schema, compat flags, overrides |
2026-03-25 22:38:55 -06:00
| [Token Optimization ](./token-optimization.md ) | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) |
| [Dynamic Model Routing ](./dynamic-model-routing.md ) | Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19) |
| [Captures & Triage ](./captures-triage.md ) | Fire-and-forget thought capture during auto-mode with automated triage (v2.19) |
| [Workflow Visualizer ](./visualizer.md ) | Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19) |
| [Cost Management ](./cost-management.md ) | Budget ceilings, cost tracking, projections, and enforcement modes |
| [Git Strategy ](./git-strategy.md ) | Worktree isolation, branching model, and merge behavior |
| [Parallel Orchestration ](./parallel-orchestration.md ) | Run multiple milestones simultaneously with worker isolation and coordination |
| [Working in Teams ](./working-in-teams.md ) | Unique milestone IDs, `.gitignore` setup, and shared planning artifacts |
| [Skills ](./skills.md ) | Bundled skills, skill discovery, and custom skill authoring |
| [Migration from v1 ](./migration.md ) | Migrating `.planning` directories from the original GSD |
| [Troubleshooting ](./troubleshooting.md ) | Common issues, `/gsd doctor` (real-time visibility v2.40), `/gsd forensics` (full debugger v2.40), and recovery procedures |
2026-03-26 10:13:41 -05:00
| [Web Interface ](./web-interface.md ) | Browser-based project management with `gsd --web` (v2.41) |
2026-03-25 22:38:55 -06:00
| [VS Code Extension ](../vscode-extension/README.md ) | Chat participant, sidebar dashboard, and RPC integration for VS Code |
## Architecture & Internals
| Guide | Description |
|-------|-------------|
| [Architecture Overview ](./architecture.md ) | System design, extension model, state-on-disk, and dispatch pipeline |
| [Native Engine ](../native/README.md ) | Rust N-API modules for performance-critical operations |
| [ADR-001: Branchless Worktree Architecture ](./ADR-001-branchless-worktree-architecture.md ) | Decision record for the v2.14 git architecture |
| [ADR-003: Pipeline Simplification ](./ADR-003-pipeline-simplification.md ) | Research merged into planning, mechanical completion (v2.30) |
2026-03-26 10:13:41 -05:00
| [ADR-004: Capability-Aware Model Routing ](./ADR-004-capability-aware-model-routing.md ) | Extend routing from tier/cost selection to task-capability matching |
2026-04-05 07:37:31 -05:00
| [ADR-007: Model Catalog Split ](./ADR-007-model-catalog-split.md ) | Separate model metadata from routing logic for extensibility |
| [Context Optimization Opportunities ](./pi-context-optimization-opportunities.md ) | Analysis of context window usage and optimization strategies |
2026-03-25 22:38:55 -06:00
## Pi SDK Documentation
These guides cover the underlying Pi SDK that GSD is built on. Useful if you want to extend GSD or build your own agent application.
| Guide | Description |
|-------|-------------|
| [What is Pi ](./what-is-pi/README.md ) | Core concepts — modes, agent loop, sessions, tools, providers |
| [Extending Pi ](./extending-pi/README.md ) | Building extensions — tools, commands, UI, events, state |
| [Context & Hooks ](./context-and-hooks/README.md ) | Context pipeline, hook reference, inter-extension communication |
| [Pi UI / TUI ](./pi-ui-tui/README.md ) | Terminal UI components, theming, keyboard input, rendering |
## Research
| Guide | Description |
|-------|-------------|
| [Building Coding Agents ](./building-coding-agents/README.md ) | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs |
