diff --git a/docs/README.md b/docs/README.md index f4b2d398b..e74a67039 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,54 +4,67 @@ Welcome to the GSD documentation. This covers everything from getting started to ## User Documentation +Guides for installing, configuring, and using GSD day-to-day. Located in [`user-docs/`](./user-docs/). + | 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 | -| [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 | -| [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 | -| [Web Interface](./web-interface.md) | Browser-based project management with `gsd --web` (v2.41) | +| [Getting Started](./user-docs/getting-started.md) | Installation, first run, and basic usage | +| [Auto Mode](./user-docs/auto-mode.md) | How autonomous execution works — the state machine, crash recovery, and steering | +| [Commands Reference](./user-docs/commands.md) | All commands, keyboard shortcuts, and CLI flags | +| [Remote Questions](./user-docs/remote-questions.md) | Discord and Slack integration for headless auto-mode | +| [Configuration](./user-docs/configuration.md) | Preferences, model selection, git settings, and token profiles | +| [Provider Setup](./user-docs/providers.md) | Step-by-step setup for OpenRouter, Ollama, LM Studio, vLLM, and all supported providers | +| [Custom Models](./user-docs/custom-models.md) | Advanced model configuration — models.json schema, compat flags, overrides | +| [Token Optimization](./user-docs/token-optimization.md) | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) | +| [Dynamic Model Routing](./user-docs/dynamic-model-routing.md) | Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19) | +| [Captures & Triage](./user-docs/captures-triage.md) | Fire-and-forget thought capture during auto-mode with automated triage (v2.19) | +| [Workflow Visualizer](./user-docs/visualizer.md) | Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19) | +| [Cost Management](./user-docs/cost-management.md) | Budget ceilings, cost tracking, projections, and enforcement modes | +| [Git Strategy](./user-docs/git-strategy.md) | Worktree isolation, branching model, and merge behavior | +| [Parallel Orchestration](./user-docs/parallel-orchestration.md) | Run multiple milestones simultaneously with worker isolation and coordination | +| [Working in Teams](./user-docs/working-in-teams.md) | Unique milestone IDs, `.gitignore` setup, and shared planning artifacts | +| [Skills](./user-docs/skills.md) | Bundled skills, skill discovery, and custom skill authoring | +| [Migration from v1](./user-docs/migration.md) | Migrating `.planning` directories from the original GSD | +| [Troubleshooting](./user-docs/troubleshooting.md) | Common issues, `/gsd doctor` (real-time visibility v2.40), `/gsd forensics` (full debugger v2.40), and recovery procedures | +| [Web Interface](./user-docs/web-interface.md) | Browser-based project management with `gsd --web` (v2.41) | | [VS Code Extension](../vscode-extension/README.md) | Chat participant, sidebar dashboard, and RPC integration for VS Code | ## Architecture & Internals +Design documents, ADRs, and internal references. Located in [`dev/`](./dev/). + | Guide | Description | |-------|-------------| -| [Architecture Overview](./architecture.md) | System design, extension model, state-on-disk, and dispatch pipeline | +| [Architecture Overview](./dev/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) | -| [ADR-004: Capability-Aware Model Routing](./ADR-004-capability-aware-model-routing.md) | Extend routing from tier/cost selection to task-capability matching | -| [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 | +| [ADR-001: Branchless Worktree Architecture](./dev/ADR-001-branchless-worktree-architecture.md) | Decision record for the v2.14 git architecture | +| [ADR-003: Pipeline Simplification](./dev/ADR-003-pipeline-simplification.md) | Research merged into planning, mechanical completion (v2.30) | +| [ADR-004: Capability-Aware Model Routing](./dev/ADR-004-capability-aware-model-routing.md) | Extend routing from tier/cost selection to task-capability matching | +| [ADR-007: Model Catalog Split](./dev/ADR-007-model-catalog-split.md) | Separate model metadata from routing logic for extensibility | +| [ADR-008: GSD Tools over MCP](./dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md) | Native tools over MCP for provider parity | +| [ADR-008: Implementation Plan](./dev/ADR-008-IMPLEMENTATION-PLAN.md) | Implementation plan for ADR-008 | +| [Context Optimization Opportunities](./dev/pi-context-optimization-opportunities.md) | Analysis of context window usage and optimization strategies | +| [File System Map](./dev/FILE-SYSTEM-MAP.md) | Complete file system reference | +| [CI/CD Pipeline](./dev/ci-cd-pipeline.md) | Continuous integration and deployment pipeline | +| [Frontier Techniques](./dev/FRONTIER-TECHNIQUES.md) | Advanced techniques and research | +| [PRD: Branchless Worktree](./dev/PRD-branchless-worktree-architecture.md) | Product requirements for branchless worktree architecture | +| [Agent Knowledge Index](./dev/agent-knowledge-index.md) | Index of agent knowledge resources | ## 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. +Guides for the underlying Pi SDK that GSD is built on. Located in [`dev/`](./dev/). | 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 | +| [What is Pi](./dev/what-is-pi/README.md) | Core concepts — modes, agent loop, sessions, tools, providers | +| [Extending Pi](./dev/extending-pi/README.md) | Building extensions — tools, commands, UI, events, state | +| [Context & Hooks](./dev/context-and-hooks/README.md) | Context pipeline, hook reference, inter-extension communication | +| [Pi UI / TUI](./dev/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 | +| [Building Coding Agents](./dev/building-coding-agents/README.md) | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs | +| [Proposals](./dev/proposals/) | Feature proposals and workflow definitions | +| [Superpowers](./dev/superpowers/) | Plans and specs for superpower features | diff --git a/docs/ADR-001-branchless-worktree-architecture.md b/docs/dev/ADR-001-branchless-worktree-architecture.md similarity index 100% rename from docs/ADR-001-branchless-worktree-architecture.md rename to docs/dev/ADR-001-branchless-worktree-architecture.md diff --git a/docs/ADR-003-pipeline-simplification.md b/docs/dev/ADR-003-pipeline-simplification.md similarity index 100% rename from docs/ADR-003-pipeline-simplification.md rename to docs/dev/ADR-003-pipeline-simplification.md diff --git a/docs/ADR-004-capability-aware-model-routing.md b/docs/dev/ADR-004-capability-aware-model-routing.md similarity index 100% rename from docs/ADR-004-capability-aware-model-routing.md rename to docs/dev/ADR-004-capability-aware-model-routing.md diff --git a/docs/ADR-007-model-catalog-split.md b/docs/dev/ADR-007-model-catalog-split.md similarity index 100% rename from docs/ADR-007-model-catalog-split.md rename to docs/dev/ADR-007-model-catalog-split.md diff --git a/docs/ADR-008-IMPLEMENTATION-PLAN.md b/docs/dev/ADR-008-IMPLEMENTATION-PLAN.md similarity index 100% rename from docs/ADR-008-IMPLEMENTATION-PLAN.md rename to docs/dev/ADR-008-IMPLEMENTATION-PLAN.md diff --git a/docs/ADR-008-gsd-tools-over-mcp-for-provider-parity.md b/docs/dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md similarity index 100% rename from docs/ADR-008-gsd-tools-over-mcp-for-provider-parity.md rename to docs/dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md diff --git a/docs/FILE-SYSTEM-MAP.md b/docs/dev/FILE-SYSTEM-MAP.md similarity index 100% rename from docs/FILE-SYSTEM-MAP.md rename to docs/dev/FILE-SYSTEM-MAP.md diff --git a/docs/FRONTIER-TECHNIQUES.md b/docs/dev/FRONTIER-TECHNIQUES.md similarity index 100% rename from docs/FRONTIER-TECHNIQUES.md rename to docs/dev/FRONTIER-TECHNIQUES.md diff --git a/docs/PRD-branchless-worktree-architecture.md b/docs/dev/PRD-branchless-worktree-architecture.md similarity index 100% rename from docs/PRD-branchless-worktree-architecture.md rename to docs/dev/PRD-branchless-worktree-architecture.md diff --git a/docs/agent-knowledge-index.md b/docs/dev/agent-knowledge-index.md similarity index 100% rename from docs/agent-knowledge-index.md rename to docs/dev/agent-knowledge-index.md diff --git a/docs/architecture.md b/docs/dev/architecture.md similarity index 100% rename from docs/architecture.md rename to docs/dev/architecture.md diff --git a/docs/building-coding-agents/01-work-decomposition.md b/docs/dev/building-coding-agents/01-work-decomposition.md similarity index 100% rename from docs/building-coding-agents/01-work-decomposition.md rename to docs/dev/building-coding-agents/01-work-decomposition.md diff --git a/docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md b/docs/dev/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md similarity index 100% rename from docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md rename to docs/dev/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md diff --git a/docs/building-coding-agents/03-state-machine-context-management.md b/docs/dev/building-coding-agents/03-state-machine-context-management.md similarity index 100% rename from docs/building-coding-agents/03-state-machine-context-management.md rename to docs/dev/building-coding-agents/03-state-machine-context-management.md diff --git a/docs/building-coding-agents/04-optimal-storage-for-project-context.md b/docs/dev/building-coding-agents/04-optimal-storage-for-project-context.md similarity index 100% rename from docs/building-coding-agents/04-optimal-storage-for-project-context.md rename to docs/dev/building-coding-agents/04-optimal-storage-for-project-context.md diff --git a/docs/building-coding-agents/05-parallelization-strategy.md b/docs/dev/building-coding-agents/05-parallelization-strategy.md similarity index 100% rename from docs/building-coding-agents/05-parallelization-strategy.md rename to docs/dev/building-coding-agents/05-parallelization-strategy.md diff --git a/docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md b/docs/dev/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md similarity index 100% rename from docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md rename to docs/dev/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md diff --git a/docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md b/docs/dev/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md similarity index 100% rename from docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md rename to docs/dev/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md diff --git a/docs/building-coding-agents/08-speed-optimization.md b/docs/dev/building-coding-agents/08-speed-optimization.md similarity index 100% rename from docs/building-coding-agents/08-speed-optimization.md rename to docs/dev/building-coding-agents/08-speed-optimization.md diff --git a/docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md b/docs/dev/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md similarity index 100% rename from docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md rename to docs/dev/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md diff --git a/docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md b/docs/dev/building-coding-agents/10-top-10-pitfalls-to-avoid.md similarity index 100% rename from docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md rename to docs/dev/building-coding-agents/10-top-10-pitfalls-to-avoid.md diff --git a/docs/building-coding-agents/11-god-tier-context-engineering.md b/docs/dev/building-coding-agents/11-god-tier-context-engineering.md similarity index 100% rename from docs/building-coding-agents/11-god-tier-context-engineering.md rename to docs/dev/building-coding-agents/11-god-tier-context-engineering.md diff --git a/docs/building-coding-agents/12-handling-ambiguity-contradiction.md b/docs/dev/building-coding-agents/12-handling-ambiguity-contradiction.md similarity index 100% rename from docs/building-coding-agents/12-handling-ambiguity-contradiction.md rename to docs/dev/building-coding-agents/12-handling-ambiguity-contradiction.md diff --git a/docs/building-coding-agents/13-long-running-memory-fidelity.md b/docs/dev/building-coding-agents/13-long-running-memory-fidelity.md similarity index 100% rename from docs/building-coding-agents/13-long-running-memory-fidelity.md rename to docs/dev/building-coding-agents/13-long-running-memory-fidelity.md diff --git a/docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md b/docs/dev/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md similarity index 100% rename from docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md rename to docs/dev/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md diff --git a/docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md b/docs/dev/building-coding-agents/15-legacy-code-brownfield-onboarding.md similarity index 100% rename from docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md rename to docs/dev/building-coding-agents/15-legacy-code-brownfield-onboarding.md diff --git a/docs/building-coding-agents/16-encoding-taste-aesthetics.md b/docs/dev/building-coding-agents/16-encoding-taste-aesthetics.md similarity index 100% rename from docs/building-coding-agents/16-encoding-taste-aesthetics.md rename to docs/dev/building-coding-agents/16-encoding-taste-aesthetics.md diff --git a/docs/building-coding-agents/17-irreversible-operations-safety-architecture.md b/docs/dev/building-coding-agents/17-irreversible-operations-safety-architecture.md similarity index 100% rename from docs/building-coding-agents/17-irreversible-operations-safety-architecture.md rename to docs/dev/building-coding-agents/17-irreversible-operations-safety-architecture.md diff --git a/docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md b/docs/dev/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md similarity index 100% rename from docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md rename to docs/dev/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md diff --git a/docs/building-coding-agents/19-when-to-scrap-and-start-over.md b/docs/dev/building-coding-agents/19-when-to-scrap-and-start-over.md similarity index 100% rename from docs/building-coding-agents/19-when-to-scrap-and-start-over.md rename to docs/dev/building-coding-agents/19-when-to-scrap-and-start-over.md diff --git a/docs/building-coding-agents/20-error-taxonomy-routing.md b/docs/dev/building-coding-agents/20-error-taxonomy-routing.md similarity index 100% rename from docs/building-coding-agents/20-error-taxonomy-routing.md rename to docs/dev/building-coding-agents/20-error-taxonomy-routing.md diff --git a/docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md b/docs/dev/building-coding-agents/21-cost-quality-tradeoff-model-routing.md similarity index 100% rename from docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md rename to docs/dev/building-coding-agents/21-cost-quality-tradeoff-model-routing.md diff --git a/docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md b/docs/dev/building-coding-agents/22-cross-project-learning-reusable-intelligence.md similarity index 100% rename from docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md rename to docs/dev/building-coding-agents/22-cross-project-learning-reusable-intelligence.md diff --git a/docs/building-coding-agents/23-evolution-across-project-scale.md b/docs/dev/building-coding-agents/23-evolution-across-project-scale.md similarity index 100% rename from docs/building-coding-agents/23-evolution-across-project-scale.md rename to docs/dev/building-coding-agents/23-evolution-across-project-scale.md diff --git a/docs/building-coding-agents/24-security-trust-boundaries.md b/docs/dev/building-coding-agents/24-security-trust-boundaries.md similarity index 100% rename from docs/building-coding-agents/24-security-trust-boundaries.md rename to docs/dev/building-coding-agents/24-security-trust-boundaries.md diff --git a/docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md b/docs/dev/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md similarity index 100% rename from docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md rename to docs/dev/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md diff --git a/docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md b/docs/dev/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md similarity index 100% rename from docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md rename to docs/dev/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md diff --git a/docs/building-coding-agents/README.md b/docs/dev/building-coding-agents/README.md similarity index 100% rename from docs/building-coding-agents/README.md rename to docs/dev/building-coding-agents/README.md diff --git a/docs/ci-cd-pipeline.md b/docs/dev/ci-cd-pipeline.md similarity index 100% rename from docs/ci-cd-pipeline.md rename to docs/dev/ci-cd-pipeline.md diff --git a/docs/context-and-hooks/01-the-context-pipeline.md b/docs/dev/context-and-hooks/01-the-context-pipeline.md similarity index 100% rename from docs/context-and-hooks/01-the-context-pipeline.md rename to docs/dev/context-and-hooks/01-the-context-pipeline.md diff --git a/docs/context-and-hooks/02-hook-reference.md b/docs/dev/context-and-hooks/02-hook-reference.md similarity index 100% rename from docs/context-and-hooks/02-hook-reference.md rename to docs/dev/context-and-hooks/02-hook-reference.md diff --git a/docs/context-and-hooks/03-context-injection-patterns.md b/docs/dev/context-and-hooks/03-context-injection-patterns.md similarity index 100% rename from docs/context-and-hooks/03-context-injection-patterns.md rename to docs/dev/context-and-hooks/03-context-injection-patterns.md diff --git a/docs/context-and-hooks/04-message-types-and-llm-visibility.md b/docs/dev/context-and-hooks/04-message-types-and-llm-visibility.md similarity index 100% rename from docs/context-and-hooks/04-message-types-and-llm-visibility.md rename to docs/dev/context-and-hooks/04-message-types-and-llm-visibility.md diff --git a/docs/context-and-hooks/05-inter-extension-communication.md b/docs/dev/context-and-hooks/05-inter-extension-communication.md similarity index 100% rename from docs/context-and-hooks/05-inter-extension-communication.md rename to docs/dev/context-and-hooks/05-inter-extension-communication.md diff --git a/docs/context-and-hooks/06-advanced-patterns-from-source.md b/docs/dev/context-and-hooks/06-advanced-patterns-from-source.md similarity index 100% rename from docs/context-and-hooks/06-advanced-patterns-from-source.md rename to docs/dev/context-and-hooks/06-advanced-patterns-from-source.md diff --git a/docs/context-and-hooks/07-the-system-prompt-anatomy.md b/docs/dev/context-and-hooks/07-the-system-prompt-anatomy.md similarity index 100% rename from docs/context-and-hooks/07-the-system-prompt-anatomy.md rename to docs/dev/context-and-hooks/07-the-system-prompt-anatomy.md diff --git a/docs/context-and-hooks/README.md b/docs/dev/context-and-hooks/README.md similarity index 100% rename from docs/context-and-hooks/README.md rename to docs/dev/context-and-hooks/README.md diff --git a/docs/extending-pi/01-what-are-extensions.md b/docs/dev/extending-pi/01-what-are-extensions.md similarity index 100% rename from docs/extending-pi/01-what-are-extensions.md rename to docs/dev/extending-pi/01-what-are-extensions.md diff --git a/docs/extending-pi/02-architecture-mental-model.md b/docs/dev/extending-pi/02-architecture-mental-model.md similarity index 100% rename from docs/extending-pi/02-architecture-mental-model.md rename to docs/dev/extending-pi/02-architecture-mental-model.md diff --git a/docs/extending-pi/03-getting-started.md b/docs/dev/extending-pi/03-getting-started.md similarity index 100% rename from docs/extending-pi/03-getting-started.md rename to docs/dev/extending-pi/03-getting-started.md diff --git a/docs/extending-pi/04-extension-locations-discovery.md b/docs/dev/extending-pi/04-extension-locations-discovery.md similarity index 100% rename from docs/extending-pi/04-extension-locations-discovery.md rename to docs/dev/extending-pi/04-extension-locations-discovery.md diff --git a/docs/extending-pi/05-extension-structure-styles.md b/docs/dev/extending-pi/05-extension-structure-styles.md similarity index 100% rename from docs/extending-pi/05-extension-structure-styles.md rename to docs/dev/extending-pi/05-extension-structure-styles.md diff --git a/docs/extending-pi/06-the-extension-lifecycle.md b/docs/dev/extending-pi/06-the-extension-lifecycle.md similarity index 100% rename from docs/extending-pi/06-the-extension-lifecycle.md rename to docs/dev/extending-pi/06-the-extension-lifecycle.md diff --git a/docs/extending-pi/07-events-the-nervous-system.md b/docs/dev/extending-pi/07-events-the-nervous-system.md similarity index 100% rename from docs/extending-pi/07-events-the-nervous-system.md rename to docs/dev/extending-pi/07-events-the-nervous-system.md diff --git a/docs/extending-pi/08-extensioncontext-what-you-can-access.md b/docs/dev/extending-pi/08-extensioncontext-what-you-can-access.md similarity index 100% rename from docs/extending-pi/08-extensioncontext-what-you-can-access.md rename to docs/dev/extending-pi/08-extensioncontext-what-you-can-access.md diff --git a/docs/extending-pi/09-extensionapi-what-you-can-do.md b/docs/dev/extending-pi/09-extensionapi-what-you-can-do.md similarity index 100% rename from docs/extending-pi/09-extensionapi-what-you-can-do.md rename to docs/dev/extending-pi/09-extensionapi-what-you-can-do.md diff --git a/docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md b/docs/dev/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md similarity index 100% rename from docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md rename to docs/dev/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md diff --git a/docs/extending-pi/11-custom-commands-user-facing-actions.md b/docs/dev/extending-pi/11-custom-commands-user-facing-actions.md similarity index 100% rename from docs/extending-pi/11-custom-commands-user-facing-actions.md rename to docs/dev/extending-pi/11-custom-commands-user-facing-actions.md diff --git a/docs/extending-pi/12-custom-ui-visual-components.md b/docs/dev/extending-pi/12-custom-ui-visual-components.md similarity index 100% rename from docs/extending-pi/12-custom-ui-visual-components.md rename to docs/dev/extending-pi/12-custom-ui-visual-components.md diff --git a/docs/extending-pi/13-state-management-persistence.md b/docs/dev/extending-pi/13-state-management-persistence.md similarity index 100% rename from docs/extending-pi/13-state-management-persistence.md rename to docs/dev/extending-pi/13-state-management-persistence.md diff --git a/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md b/docs/dev/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md similarity index 100% rename from docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md rename to docs/dev/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md diff --git a/docs/extending-pi/15-system-prompt-modification.md b/docs/dev/extending-pi/15-system-prompt-modification.md similarity index 100% rename from docs/extending-pi/15-system-prompt-modification.md rename to docs/dev/extending-pi/15-system-prompt-modification.md diff --git a/docs/extending-pi/16-compaction-session-control.md b/docs/dev/extending-pi/16-compaction-session-control.md similarity index 100% rename from docs/extending-pi/16-compaction-session-control.md rename to docs/dev/extending-pi/16-compaction-session-control.md diff --git a/docs/extending-pi/17-model-provider-management.md b/docs/dev/extending-pi/17-model-provider-management.md similarity index 100% rename from docs/extending-pi/17-model-provider-management.md rename to docs/dev/extending-pi/17-model-provider-management.md diff --git a/docs/extending-pi/18-remote-execution-tool-overrides.md b/docs/dev/extending-pi/18-remote-execution-tool-overrides.md similarity index 100% rename from docs/extending-pi/18-remote-execution-tool-overrides.md rename to docs/dev/extending-pi/18-remote-execution-tool-overrides.md diff --git a/docs/extending-pi/19-packaging-distribution.md b/docs/dev/extending-pi/19-packaging-distribution.md similarity index 100% rename from docs/extending-pi/19-packaging-distribution.md rename to docs/dev/extending-pi/19-packaging-distribution.md diff --git a/docs/extending-pi/20-mode-behavior.md b/docs/dev/extending-pi/20-mode-behavior.md similarity index 100% rename from docs/extending-pi/20-mode-behavior.md rename to docs/dev/extending-pi/20-mode-behavior.md diff --git a/docs/extending-pi/21-error-handling.md b/docs/dev/extending-pi/21-error-handling.md similarity index 100% rename from docs/extending-pi/21-error-handling.md rename to docs/dev/extending-pi/21-error-handling.md diff --git a/docs/extending-pi/22-key-rules-gotchas.md b/docs/dev/extending-pi/22-key-rules-gotchas.md similarity index 100% rename from docs/extending-pi/22-key-rules-gotchas.md rename to docs/dev/extending-pi/22-key-rules-gotchas.md diff --git a/docs/extending-pi/23-file-reference-documentation.md b/docs/dev/extending-pi/23-file-reference-documentation.md similarity index 100% rename from docs/extending-pi/23-file-reference-documentation.md rename to docs/dev/extending-pi/23-file-reference-documentation.md diff --git a/docs/extending-pi/24-file-reference-example-extensions.md b/docs/dev/extending-pi/24-file-reference-example-extensions.md similarity index 100% rename from docs/extending-pi/24-file-reference-example-extensions.md rename to docs/dev/extending-pi/24-file-reference-example-extensions.md diff --git a/docs/extending-pi/25-slash-command-subcommand-patterns.md b/docs/dev/extending-pi/25-slash-command-subcommand-patterns.md similarity index 100% rename from docs/extending-pi/25-slash-command-subcommand-patterns.md rename to docs/dev/extending-pi/25-slash-command-subcommand-patterns.md diff --git a/docs/extending-pi/README.md b/docs/dev/extending-pi/README.md similarity index 100% rename from docs/extending-pi/README.md rename to docs/dev/extending-pi/README.md diff --git a/docs/pi-context-optimization-opportunities.md b/docs/dev/pi-context-optimization-opportunities.md similarity index 100% rename from docs/pi-context-optimization-opportunities.md rename to docs/dev/pi-context-optimization-opportunities.md diff --git a/docs/pi-ui-tui/01-the-ui-architecture.md b/docs/dev/pi-ui-tui/01-the-ui-architecture.md similarity index 100% rename from docs/pi-ui-tui/01-the-ui-architecture.md rename to docs/dev/pi-ui-tui/01-the-ui-architecture.md diff --git a/docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md b/docs/dev/pi-ui-tui/02-the-component-interface-foundation-of-everything.md similarity index 100% rename from docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md rename to docs/dev/pi-ui-tui/02-the-component-interface-foundation-of-everything.md diff --git a/docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md b/docs/dev/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md similarity index 100% rename from docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md rename to docs/dev/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md diff --git a/docs/pi-ui-tui/04-built-in-dialog-methods.md b/docs/dev/pi-ui-tui/04-built-in-dialog-methods.md similarity index 100% rename from docs/pi-ui-tui/04-built-in-dialog-methods.md rename to docs/dev/pi-ui-tui/04-built-in-dialog-methods.md diff --git a/docs/pi-ui-tui/05-persistent-ui-elements.md b/docs/dev/pi-ui-tui/05-persistent-ui-elements.md similarity index 100% rename from docs/pi-ui-tui/05-persistent-ui-elements.md rename to docs/dev/pi-ui-tui/05-persistent-ui-elements.md diff --git a/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md b/docs/dev/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md similarity index 100% rename from docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md rename to docs/dev/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md diff --git a/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md b/docs/dev/pi-ui-tui/07-built-in-components-the-building-blocks.md similarity index 100% rename from docs/pi-ui-tui/07-built-in-components-the-building-blocks.md rename to docs/dev/pi-ui-tui/07-built-in-components-the-building-blocks.md diff --git a/docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md b/docs/dev/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md similarity index 100% rename from docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md rename to docs/dev/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md diff --git a/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md b/docs/dev/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md similarity index 100% rename from docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md rename to docs/dev/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md diff --git a/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md b/docs/dev/pi-ui-tui/10-line-width-the-cardinal-rule.md similarity index 100% rename from docs/pi-ui-tui/10-line-width-the-cardinal-rule.md rename to docs/dev/pi-ui-tui/10-line-width-the-cardinal-rule.md diff --git a/docs/pi-ui-tui/11-theming-colors-and-styles.md b/docs/dev/pi-ui-tui/11-theming-colors-and-styles.md similarity index 100% rename from docs/pi-ui-tui/11-theming-colors-and-styles.md rename to docs/dev/pi-ui-tui/11-theming-colors-and-styles.md diff --git a/docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md b/docs/dev/pi-ui-tui/12-overlays-floating-modals-and-panels.md similarity index 100% rename from docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md rename to docs/dev/pi-ui-tui/12-overlays-floating-modals-and-panels.md diff --git a/docs/pi-ui-tui/13-custom-editors-replacing-the-input.md b/docs/dev/pi-ui-tui/13-custom-editors-replacing-the-input.md similarity index 100% rename from docs/pi-ui-tui/13-custom-editors-replacing-the-input.md rename to docs/dev/pi-ui-tui/13-custom-editors-replacing-the-input.md diff --git a/docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md b/docs/dev/pi-ui-tui/14-tool-rendering-custom-tool-display.md similarity index 100% rename from docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md rename to docs/dev/pi-ui-tui/14-tool-rendering-custom-tool-display.md diff --git a/docs/pi-ui-tui/15-message-rendering-custom-message-display.md b/docs/dev/pi-ui-tui/15-message-rendering-custom-message-display.md similarity index 100% rename from docs/pi-ui-tui/15-message-rendering-custom-message-display.md rename to docs/dev/pi-ui-tui/15-message-rendering-custom-message-display.md diff --git a/docs/pi-ui-tui/16-performance-caching-and-invalidation.md b/docs/dev/pi-ui-tui/16-performance-caching-and-invalidation.md similarity index 100% rename from docs/pi-ui-tui/16-performance-caching-and-invalidation.md rename to docs/dev/pi-ui-tui/16-performance-caching-and-invalidation.md diff --git a/docs/pi-ui-tui/17-theme-changes-and-invalidation.md b/docs/dev/pi-ui-tui/17-theme-changes-and-invalidation.md similarity index 100% rename from docs/pi-ui-tui/17-theme-changes-and-invalidation.md rename to docs/dev/pi-ui-tui/17-theme-changes-and-invalidation.md diff --git a/docs/pi-ui-tui/18-ime-support-the-focusable-interface.md b/docs/dev/pi-ui-tui/18-ime-support-the-focusable-interface.md similarity index 100% rename from docs/pi-ui-tui/18-ime-support-the-focusable-interface.md rename to docs/dev/pi-ui-tui/18-ime-support-the-focusable-interface.md diff --git a/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md b/docs/dev/pi-ui-tui/19-building-a-complete-component-step-by-step.md similarity index 100% rename from docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md rename to docs/dev/pi-ui-tui/19-building-a-complete-component-step-by-step.md diff --git a/docs/pi-ui-tui/20-real-world-patterns-from-examples.md b/docs/dev/pi-ui-tui/20-real-world-patterns-from-examples.md similarity index 100% rename from docs/pi-ui-tui/20-real-world-patterns-from-examples.md rename to docs/dev/pi-ui-tui/20-real-world-patterns-from-examples.md diff --git a/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md b/docs/dev/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md similarity index 100% rename from docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md rename to docs/dev/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md diff --git a/docs/pi-ui-tui/22-quick-reference-all-ui-apis.md b/docs/dev/pi-ui-tui/22-quick-reference-all-ui-apis.md similarity index 100% rename from docs/pi-ui-tui/22-quick-reference-all-ui-apis.md rename to docs/dev/pi-ui-tui/22-quick-reference-all-ui-apis.md diff --git a/docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md b/docs/dev/pi-ui-tui/23-file-reference-example-extensions-with-ui.md similarity index 100% rename from docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md rename to docs/dev/pi-ui-tui/23-file-reference-example-extensions-with-ui.md diff --git a/docs/pi-ui-tui/README.md b/docs/dev/pi-ui-tui/README.md similarity index 100% rename from docs/pi-ui-tui/README.md rename to docs/dev/pi-ui-tui/README.md diff --git a/docs/proposals/698-browser-tools-feature-additions.md b/docs/dev/proposals/698-browser-tools-feature-additions.md similarity index 100% rename from docs/proposals/698-browser-tools-feature-additions.md rename to docs/dev/proposals/698-browser-tools-feature-additions.md diff --git a/docs/proposals/rfc-gitops-branching-strategy.md b/docs/dev/proposals/rfc-gitops-branching-strategy.md similarity index 100% rename from docs/proposals/rfc-gitops-branching-strategy.md rename to docs/dev/proposals/rfc-gitops-branching-strategy.md diff --git a/docs/proposals/workflows/README.md b/docs/dev/proposals/workflows/README.md similarity index 100% rename from docs/proposals/workflows/README.md rename to docs/dev/proposals/workflows/README.md diff --git a/docs/proposals/workflows/backmerge.yml b/docs/dev/proposals/workflows/backmerge.yml similarity index 100% rename from docs/proposals/workflows/backmerge.yml rename to docs/dev/proposals/workflows/backmerge.yml diff --git a/docs/proposals/workflows/create-release.yml b/docs/dev/proposals/workflows/create-release.yml similarity index 100% rename from docs/proposals/workflows/create-release.yml rename to docs/dev/proposals/workflows/create-release.yml diff --git a/docs/proposals/workflows/sync-next.yml b/docs/dev/proposals/workflows/sync-next.yml similarity index 100% rename from docs/proposals/workflows/sync-next.yml rename to docs/dev/proposals/workflows/sync-next.yml diff --git a/docs/superpowers/plans/2026-03-17-cicd-pipeline.md b/docs/dev/superpowers/plans/2026-03-17-cicd-pipeline.md similarity index 100% rename from docs/superpowers/plans/2026-03-17-cicd-pipeline.md rename to docs/dev/superpowers/plans/2026-03-17-cicd-pipeline.md diff --git a/docs/superpowers/specs/2026-03-17-cicd-pipeline-design.md b/docs/dev/superpowers/specs/2026-03-17-cicd-pipeline-design.md similarity index 100% rename from docs/superpowers/specs/2026-03-17-cicd-pipeline-design.md rename to docs/dev/superpowers/specs/2026-03-17-cicd-pipeline-design.md diff --git a/docs/what-is-pi/01-what-pi-is.md b/docs/dev/what-is-pi/01-what-pi-is.md similarity index 100% rename from docs/what-is-pi/01-what-pi-is.md rename to docs/dev/what-is-pi/01-what-pi-is.md diff --git a/docs/what-is-pi/02-design-philosophy.md b/docs/dev/what-is-pi/02-design-philosophy.md similarity index 100% rename from docs/what-is-pi/02-design-philosophy.md rename to docs/dev/what-is-pi/02-design-philosophy.md diff --git a/docs/what-is-pi/03-the-four-modes-of-operation.md b/docs/dev/what-is-pi/03-the-four-modes-of-operation.md similarity index 100% rename from docs/what-is-pi/03-the-four-modes-of-operation.md rename to docs/dev/what-is-pi/03-the-four-modes-of-operation.md diff --git a/docs/what-is-pi/04-the-architecture-how-everything-fits-together.md b/docs/dev/what-is-pi/04-the-architecture-how-everything-fits-together.md similarity index 100% rename from docs/what-is-pi/04-the-architecture-how-everything-fits-together.md rename to docs/dev/what-is-pi/04-the-architecture-how-everything-fits-together.md diff --git a/docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md b/docs/dev/what-is-pi/05-the-agent-loop-how-pi-thinks.md similarity index 100% rename from docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md rename to docs/dev/what-is-pi/05-the-agent-loop-how-pi-thinks.md diff --git a/docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md b/docs/dev/what-is-pi/06-tools-how-pi-acts-on-the-world.md similarity index 100% rename from docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md rename to docs/dev/what-is-pi/06-tools-how-pi-acts-on-the-world.md diff --git a/docs/what-is-pi/07-sessions-memory-that-branches.md b/docs/dev/what-is-pi/07-sessions-memory-that-branches.md similarity index 100% rename from docs/what-is-pi/07-sessions-memory-that-branches.md rename to docs/dev/what-is-pi/07-sessions-memory-that-branches.md diff --git a/docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md b/docs/dev/what-is-pi/08-compaction-how-pi-manages-context-limits.md similarity index 100% rename from docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md rename to docs/dev/what-is-pi/08-compaction-how-pi-manages-context-limits.md diff --git a/docs/what-is-pi/09-the-customization-stack.md b/docs/dev/what-is-pi/09-the-customization-stack.md similarity index 100% rename from docs/what-is-pi/09-the-customization-stack.md rename to docs/dev/what-is-pi/09-the-customization-stack.md diff --git a/docs/what-is-pi/10-providers-models-multi-model-by-default.md b/docs/dev/what-is-pi/10-providers-models-multi-model-by-default.md similarity index 100% rename from docs/what-is-pi/10-providers-models-multi-model-by-default.md rename to docs/dev/what-is-pi/10-providers-models-multi-model-by-default.md diff --git a/docs/what-is-pi/11-the-interactive-tui.md b/docs/dev/what-is-pi/11-the-interactive-tui.md similarity index 100% rename from docs/what-is-pi/11-the-interactive-tui.md rename to docs/dev/what-is-pi/11-the-interactive-tui.md diff --git a/docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md b/docs/dev/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md similarity index 100% rename from docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md rename to docs/dev/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md diff --git a/docs/what-is-pi/13-context-files-project-instructions.md b/docs/dev/what-is-pi/13-context-files-project-instructions.md similarity index 100% rename from docs/what-is-pi/13-context-files-project-instructions.md rename to docs/dev/what-is-pi/13-context-files-project-instructions.md diff --git a/docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md b/docs/dev/what-is-pi/14-the-sdk-rpc-embedding-pi.md similarity index 100% rename from docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md rename to docs/dev/what-is-pi/14-the-sdk-rpc-embedding-pi.md diff --git a/docs/what-is-pi/15-pi-packages-the-ecosystem.md b/docs/dev/what-is-pi/15-pi-packages-the-ecosystem.md similarity index 100% rename from docs/what-is-pi/15-pi-packages-the-ecosystem.md rename to docs/dev/what-is-pi/15-pi-packages-the-ecosystem.md diff --git a/docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md b/docs/dev/what-is-pi/16-why-pi-matters-what-makes-it-different.md similarity index 100% rename from docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md rename to docs/dev/what-is-pi/16-why-pi-matters-what-makes-it-different.md diff --git a/docs/what-is-pi/17-file-reference-all-documentation.md b/docs/dev/what-is-pi/17-file-reference-all-documentation.md similarity index 100% rename from docs/what-is-pi/17-file-reference-all-documentation.md rename to docs/dev/what-is-pi/17-file-reference-all-documentation.md diff --git a/docs/what-is-pi/18-quick-reference-commands-shortcuts.md b/docs/dev/what-is-pi/18-quick-reference-commands-shortcuts.md similarity index 100% rename from docs/what-is-pi/18-quick-reference-commands-shortcuts.md rename to docs/dev/what-is-pi/18-quick-reference-commands-shortcuts.md diff --git a/docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md b/docs/dev/what-is-pi/19-building-branded-apps-on-top-of-pi.md similarity index 100% rename from docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md rename to docs/dev/what-is-pi/19-building-branded-apps-on-top-of-pi.md diff --git a/docs/what-is-pi/README.md b/docs/dev/what-is-pi/README.md similarity index 100% rename from docs/what-is-pi/README.md rename to docs/dev/what-is-pi/README.md diff --git a/docs/auto-mode.md b/docs/user-docs/auto-mode.md similarity index 100% rename from docs/auto-mode.md rename to docs/user-docs/auto-mode.md diff --git a/docs/captures-triage.md b/docs/user-docs/captures-triage.md similarity index 100% rename from docs/captures-triage.md rename to docs/user-docs/captures-triage.md diff --git a/docs/user-docs/claude-code-auth-compliance.md b/docs/user-docs/claude-code-auth-compliance.md new file mode 100644 index 000000000..f930afd46 --- /dev/null +++ b/docs/user-docs/claude-code-auth-compliance.md @@ -0,0 +1,180 @@ +# Claude Code Auth Compliance Research + +Date: 2026-04-10 + +## Executive Summary + +Anthropic's current public guidance draws a hard line: + +- Native Anthropic apps, including Claude Code, may use Claude subscription authentication. +- Third-party tools should prefer API key authentication through Claude Console or a supported cloud provider. +- Apps that misrepresent their identity, route third-party traffic against subscription limits, or otherwise violate Anthropic terms are explicitly prohibited. + +For GSD2, the safe path is: + +1. Treat local Claude Code as an external authenticated runtime. +2. Never ask GSD users to sign into Claude subscriptions through GSD-managed Anthropic OAuth. +3. Never exchange Claude.ai subscription OAuth into a bearer token and call Anthropic APIs as if GSD were Claude Code. +4. If GSD needs direct Anthropic API access, require a Claude Console API key, Bedrock, Vertex, or another explicitly supported provider path. + +## What Anthropic Explicitly Allows + +### 1. Claude Code itself can use Claude subscription auth + +Anthropic's help center says Claude Pro/Max users should install Claude Code, run `claude`, and "log in with the same credentials you use for Claude." It also says this connects the subscription directly to Claude Code, and that `/login` is the way to switch account types. The Team/Enterprise article gives the same flow for org accounts. + +Implication for GSD2: + +- Letting users authenticate inside the real `claude` CLI is aligned with Anthropic's documented flow. +- Detecting `claude auth status` and routing work through the local CLI or official Claude Code SDK is the lowest-risk pattern. + +### 2. Claude Code supports both subscription OAuth and API credentials + +Anthropic's Claude Code docs say supported auth types include Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth. The docs also define auth precedence: + +1. cloud provider credentials +2. `ANTHROPIC_AUTH_TOKEN` +3. `ANTHROPIC_API_KEY` +4. `apiKeyHelper` +5. subscription OAuth from `/login` + +Implication for GSD2: + +- If GSD2 shells out to or embeds Claude Code, it should respect Claude Code's own credential selection instead of inventing a parallel Anthropic OAuth flow. +- `apiKeyHelper` is the clean enterprise escape hatch when an org wants dynamic short-lived keys without handing raw API keys to the tool. + +### 3. Anthropic commercial usage is available through API keys and supported cloud providers + +Anthropic's commercial terms govern API keys and related Anthropic services for customer-built products, including products made available to end users. The authentication docs for teams recommend Claude for Teams/Enterprise, Claude Console, Bedrock, Vertex, or Microsoft Foundry. + +Implication for GSD2: + +- If GSD2 is acting as a product for users, direct Anthropic access should be through commercial auth paths, not subscription-token reuse. + +## What Anthropic Explicitly Warns Against + +Anthropic's current "Logging in to your Claude account" article is the clearest statement: + +- Subscription plans are for ordinary use of native Anthropic apps, including Claude web, desktop, mobile, and Claude Code. +- "The preferred way" for third-party tools, including open-source projects, is API key auth through Claude Console or a supported cloud provider. +- If you're building a product, application, or tool for others, use API key auth through Claude Console or a supported cloud provider. +- Tools that misrepresent identity, route third-party traffic against subscription limits, or otherwise violate terms are prohibited. + +Anthropic's consumer terms add two more constraints: + +- Users may not share account login info, API keys, or account credentials with anyone else. +- Except when accessing services via an Anthropic API key or where Anthropic explicitly permits it, users may not access the services through automated or non-human means. + +Implication for GSD2: + +- A GSD-managed Anthropic OAuth flow for subscription accounts is high risk. +- Reusing user Claude subscription credentials inside GSD's own API client is high risk. +- Any flow that makes Anthropic believe requests come from Claude Code when they actually come from GSD infrastructure is out of bounds. + +## Current GSD2 Findings + +### Low-risk / aligned pieces + +- `src/resources/extensions/claude-code-cli/index.ts` + Registers `claude-code` as an `externalCli` provider and routes through Anthropic's official `@anthropic-ai/claude-agent-sdk`. +- `src/resources/extensions/claude-code-cli/readiness.ts` + Only checks local CLI presence and auth state via `claude --version` and `claude auth status`. +- `src/onboarding.ts` + TUI onboarding already removed Anthropic browser OAuth and labels local Claude Code routing as the TOS-compliant path. +- `src/cli.ts` + Migrates users from `anthropic` to `claude-code` when the local CLI is available. + +These are directionally correct because GSD is using the user's own local Claude Code installation as the authenticated Anthropic surface. + +### Medium/high-risk pieces + +- `packages/pi-ai/src/utils/oauth/anthropic.ts` + Still implements a first-party-looking Anthropic OAuth flow for GSD itself using `claude.ai/oauth/authorize` and `platform.claude.com/v1/oauth/token`. +- `packages/pi-ai/src/utils/oauth/index.ts` + Still registers `anthropicOAuthProvider` as a built-in OAuth provider. +- `src/web/onboarding-service.ts` + Still advertises Anthropic as `supportsOAuth: true`, which keeps the web onboarding surface inconsistent with the TUI stance. +- `packages/daemon/src/orchestrator.ts` + Reads Anthropic OAuth credentials from `~/.gsd/agent/auth.json`, refreshes them, and then uses the access token for Anthropic API calls. + +The key risk is not just stale UI. The repo still contains code paths where GSD can behave as a third-party Anthropic OAuth client and then convert that credential into direct API access. + +## Recommended Policy For GSD2 + +Adopt this as the repo rule: + +- Claude subscription auth is allowed only inside Anthropic-owned surfaces: + - the `claude` CLI + - Claude Code SDK when it is backed by the local authenticated Claude Code install + - other Anthropic-documented native flows +- GSD2 must not implement its own Anthropic subscription OAuth flow for end users. +- GSD2 must not persist Anthropic subscription OAuth tokens for later API use. +- GSD2 must not send Anthropic API traffic using subscription OAuth tokens obtained by GSD. +- GSD2 may support Anthropic direct access only via: + - `ANTHROPIC_API_KEY` + - Claude Console API keys stored in auth storage + - `apiKeyHelper` + - Bedrock / Vertex / Foundry + - the local Claude Code provider + +## Recommended Implementation Plan + +### Option A: Safe minimal compliance cleanup + +1. Remove Anthropic from the built-in OAuth provider registry. +2. Change web onboarding so Anthropic is API-key only. +3. Keep `claude-code` as the recommended path when `claude auth status` succeeds. +4. Add explicit UI copy: + - "Claude subscription users: sign into the local Claude Code app/CLI, not GSD." +5. Block migrations or code paths that convert Anthropic OAuth credentials into API auth for GSD-managed requests. + +This is the fastest path to align the repo with Anthropic's published guidance. + +### Option B: Enterprise-safe Anthropic support + +Support three distinct Anthropic modes: + +- `claude-code` + Uses the local authenticated `claude` runtime only. +- `anthropic-api` + Uses Console API keys or `apiKeyHelper`. +- `anthropic-cloud` + Uses Bedrock, Vertex, or Foundry. + +Then remove any ambiguous `anthropic` browser-login path entirely. + +This is the best long-term UX because it separates: + +- subscription-native usage +- API-billed usage +- cloud-routed usage + +## Concrete Repo Follow-ups + +1. Delete or disable `packages/pi-ai/src/utils/oauth/anthropic.ts`. +2. Remove `anthropicOAuthProvider` from `packages/pi-ai/src/utils/oauth/index.ts`. +3. Change `src/web/onboarding-service.ts` so Anthropic does not claim OAuth support. +4. Audit `packages/daemon/src/orchestrator.ts` and any other callers that treat Anthropic OAuth access tokens as API credentials. +5. Update docs/UI labels to prefer `anthropic-api` for direct API usage and `claude-code` for subscription usage. +6. Add tests that fail if Anthropic subscription OAuth is reintroduced through the onboarding/provider registry. + +## Decision Rule + +If a proposed GSD2 feature needs Anthropic access, ask one question: + +"Is GSD calling Anthropic as GSD, or is GSD delegating to the user's already-authenticated local Claude Code runtime?" + +- If GSD is calling Anthropic as GSD: require API key or supported cloud auth. +- If GSD is delegating to local Claude Code: acceptable, as long as GSD does not intercept, mint, or replay subscription credentials itself. + +## Sources Reviewed + +- Anthropic Help Center: "Logging in to your Claude account" +- Anthropic Help Center: "Using Claude Code with your Pro or Max plan" +- Anthropic Help Center: "Use Claude Code with your Team or Enterprise plan" +- Anthropic Help Center: "Managing API key environment variables in Claude Code" +- Anthropic Help Center: "API Key Best Practices: Keeping Your Keys Safe and Secure" +- Claude Code Docs: getting started / authentication / team / settings / IAM +- Anthropic Commercial Terms of Service +- Anthropic Consumer Terms of Service +- Anthropic Usage Policy diff --git a/docs/commands.md b/docs/user-docs/commands.md similarity index 100% rename from docs/commands.md rename to docs/user-docs/commands.md diff --git a/docs/configuration.md b/docs/user-docs/configuration.md similarity index 100% rename from docs/configuration.md rename to docs/user-docs/configuration.md diff --git a/docs/cost-management.md b/docs/user-docs/cost-management.md similarity index 100% rename from docs/cost-management.md rename to docs/user-docs/cost-management.md diff --git a/docs/custom-models.md b/docs/user-docs/custom-models.md similarity index 100% rename from docs/custom-models.md rename to docs/user-docs/custom-models.md diff --git a/docs/dynamic-model-routing.md b/docs/user-docs/dynamic-model-routing.md similarity index 100% rename from docs/dynamic-model-routing.md rename to docs/user-docs/dynamic-model-routing.md diff --git a/docs/getting-started.md b/docs/user-docs/getting-started.md similarity index 100% rename from docs/getting-started.md rename to docs/user-docs/getting-started.md diff --git a/docs/git-strategy.md b/docs/user-docs/git-strategy.md similarity index 100% rename from docs/git-strategy.md rename to docs/user-docs/git-strategy.md diff --git a/docs/migration.md b/docs/user-docs/migration.md similarity index 100% rename from docs/migration.md rename to docs/user-docs/migration.md diff --git a/docs/node-lts-macos.md b/docs/user-docs/node-lts-macos.md similarity index 100% rename from docs/node-lts-macos.md rename to docs/user-docs/node-lts-macos.md diff --git a/docs/parallel-orchestration.md b/docs/user-docs/parallel-orchestration.md similarity index 100% rename from docs/parallel-orchestration.md rename to docs/user-docs/parallel-orchestration.md diff --git a/docs/providers.md b/docs/user-docs/providers.md similarity index 100% rename from docs/providers.md rename to docs/user-docs/providers.md diff --git a/docs/remote-questions.md b/docs/user-docs/remote-questions.md similarity index 100% rename from docs/remote-questions.md rename to docs/user-docs/remote-questions.md diff --git a/docs/skills.md b/docs/user-docs/skills.md similarity index 100% rename from docs/skills.md rename to docs/user-docs/skills.md diff --git a/docs/token-optimization.md b/docs/user-docs/token-optimization.md similarity index 100% rename from docs/token-optimization.md rename to docs/user-docs/token-optimization.md diff --git a/docs/troubleshooting.md b/docs/user-docs/troubleshooting.md similarity index 100% rename from docs/troubleshooting.md rename to docs/user-docs/troubleshooting.md diff --git a/docs/visualizer.md b/docs/user-docs/visualizer.md similarity index 100% rename from docs/visualizer.md rename to docs/user-docs/visualizer.md diff --git a/docs/web-interface.md b/docs/user-docs/web-interface.md similarity index 100% rename from docs/web-interface.md rename to docs/user-docs/web-interface.md diff --git a/docs/working-in-teams.md b/docs/user-docs/working-in-teams.md similarity index 100% rename from docs/working-in-teams.md rename to docs/user-docs/working-in-teams.md