Jeremy McSpadden f8c6ab0c54 chore: consolidate docs, remove stale artifacts, and repo hygiene (#2665 )

* fix(vscode): add extensionKind and error handler for Remote SSH support

* fix(vscode): reject failed RPC startup

* docs: consolidate docs, remove stale artifacts, and repo hygiene

- Remove docs-internal/ (duplicate of docs/); update pr-risk-check.mjs path
- Sync 9 diverged files to latest content (commands, config, troubleshooting, etc.)
- Fix pi --web → gsd --web naming in docs/README.md
- Copy FRONTIER-TECHNIQUES.md and ADR-004 to docs/ before removal
- Delete orphaned PR screenshot folders (pr-876/, pr-1530/) — unreferenced
- Remove committed pnpm-lock.yaml files (project uses npm)
- Move PLAN.md → .plans/doctor-cleanup-consolidation.md
- Move web/left-native-tui-main-session-plan.md → .plans/
- Delete .DS_Store and vscode-extension/dist/ from disk

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-26 09:13:41 -06:00

4 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
Custom Models	Add custom providers (Ollama, vLLM, LM Studio, proxies) via models.json
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 KiB Raw Blame History