Tom Boucher 9b6ff01471 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

4.1 KiB

Raw Blame History

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	Installation, first run, and basic usage
Auto Mode	How autonomous execution works — the state machine, crash recovery, and steering
Commands Reference	All commands, keyboard shortcuts, and CLI flags
Remote Questions	Discord and Slack integration for headless auto-mode
Configuration	Preferences, model selection, git settings, and token profiles
Provider Setup	Step-by-step setup for OpenRouter, Ollama, LM Studio, vLLM, and all supported providers
Custom Models	Advanced model configuration — models.json schema, compat flags, overrides
Token Optimization	Token profiles, context compression, complexity routing, and adaptive learning (v2.17)
Dynamic Model Routing	Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19)
Captures & Triage	Fire-and-forget thought capture during auto-mode with automated triage (v2.19)
Workflow Visualizer	Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19)
Cost Management	Budget ceilings, cost tracking, projections, and enforcement modes
Git Strategy	Worktree isolation, branching model, and merge behavior
Parallel Orchestration	Run multiple milestones simultaneously with worker isolation and coordination
Working in Teams	Unique milestone IDs, `.gitignore` setup, and shared planning artifacts
Skills	Bundled skills, skill discovery, and custom skill authoring
Migration from v1	Migrating `.planning` directories from the original GSD
Troubleshooting	Common issues, `/gsd doctor` (real-time visibility v2.40), `/gsd forensics` (full debugger v2.40), and recovery procedures
Web Interface	Browser-based project management with `gsd --web` (v2.41)
VS Code Extension	Chat participant, sidebar dashboard, and RPC integration for VS Code

Architecture & Internals

Guide	Description
Architecture Overview	System design, extension model, state-on-disk, and dispatch pipeline
Native Engine	Rust N-API modules for performance-critical operations
ADR-001: Branchless Worktree Architecture	Decision record for the v2.14 git architecture
ADR-003: Pipeline Simplification	Research merged into planning, mechanical completion (v2.30)
ADR-004: Capability-Aware Model Routing	Extend routing from tier/cost selection to task-capability matching

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	Core concepts — modes, agent loop, sessions, tools, providers
Extending Pi	Building extensions — tools, commands, UI, events, state
Context & Hooks	Context pipeline, hook reference, inter-extension communication
Pi UI / TUI	Terminal UI components, theming, keyboard input, rendering

Research

Guide	Description
Building Coding Agents	Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs

4.1 KiB Raw Blame History