Make root docs the shared Toolkit home (#1438)

## Summary
Make root `docs/` the shared entry point for Sentry CLI, Sentry MCP, and
contributor guidance. Link to the published CLI docs and their existing
Astro source without moving the release-built site. Update root guidance
and CI-selection wording; root docs remain quality-checked without
selecting product jobs.

Closes #1363

## Validation
- `pnpm run tsc`
- `pnpm run lint`
- `pnpm run test`
- `pnpm run check:generated`
- `pnpm run docs:check`
- `pnpm run test:ci-projects`
- `pnpm exec oxfmt --check` on changed files
- `node scripts/pre-commit-generated.mjs`

Co-authored-by: GPT-6 Sol <agent@openai.com>

Author: BYK

AGENTS.md

@@ -1,5 +1,6 @@
 # AGENTS.md
-Sentry MCP is a Model Context Protocol server that exposes Sentry's error tracking and performance monitoring to AI assistants through 19 tools.
+
+Toolkit contains the Sentry CLI, the Sentry MCP server, and shared code. Product-specific instructions live in their packages; start with the shared [documentation index](docs/README.md).
 
 ## Principles
 
@@ -9,90 +10,104 @@ Sentry MCP is a Model Context Protocol server that exposes Sentry's error tracki
 
 ## Constraints
 
-- **Tool count**: Target ≤20, hard limit 25 (AI agents have limited tool slots).
+- **MCP tool count**: Target ≤20, hard limit 25 (AI agents have limited tool slots).
 - **Quality gate**: `pnpm run tsc && pnpm run lint && pnpm run test` must pass before committing.
 
 ## Repository Structure
 
 ```
-sentry-mcp/
+toolkit/
+├── apps/
+│   └── cli-docs/            # CLI documentation site and generated command pages
 ├── packages/
+│   ├── cli/                 # Sentry CLI (see packages/cli/AGENTS.md)
+│   ├── toolkit-core/        # Shared CLI/MCP primitives
 │   ├── mcp-core/            # Core MCP implementation (private)
-│   │   └── src/
-│   │       ├── tools/       # 19 tool modules
-│   │       ├── server.ts    # buildServer()
-│   │       ├── api-client/  # Sentry API
-│   │       └── internal/    # Shared utils
 │   ├── mcp-server/          # stdio transport (@sentry/mcp-server on npm)
 │   ├── mcp-cloudflare/      # Web app + OAuth
 │   ├── mcp-server-evals/    # AI evaluation tests
 │   ├── mcp-server-mocks/    # MSW mocks
 │   └── mcp-test-client/     # CLI test client
-└── docs/                    # All documentation
+└── docs/                    # Toolkit contributor docs for CLI and MCP
 ```
 
 ## Documentation Map
 
-- docs/README.md — Full documentation index
+- docs/README.md — Toolkit documentation index
+- docs/cli/README.md — CLI guides and the published CLI site
+- docs/mcp/README.md — MCP guides across its packages
+- packages/cli/AGENTS.md — CLI-specific rules
+
+**Read before MCP tool changes:**
 
-**Read before tool changes:**
 - docs/contributing/adding-tools.md — Tool implementation guide
 - docs/contributing/tool-responses.md — Tool output policy and QA review checklist
 - docs/testing/overview.md — Testing requirements and snapshot policy
 - docs/contributing/common-patterns.md — Error handling, Zod schemas, shared formatting patterns
 - docs/contributing/error-handling.md — Error types and propagation
 
-**Contributing:**
-- docs/contributing/api-patterns.md — Sentry API client usage
+**Shared contributing:**
+
 - docs/contributing/coding-guidelines.md — TypeScript and code style guidance
 - docs/contributing/documentation-style-guide.md — Documentation style guide
 - docs/contributing/pr-management.md — Commit and PR guidelines
 - docs/contributing/quality-checks.md — Pre-commit checklist
+
+**MCP contributing:**
+
+- docs/contributing/api-patterns.md — Sentry API client usage
 - docs/contributing/search-events-api-patterns.md — Search Events API patterns
 
-**Testing:**
+**MCP testing:**
+
 - docs/testing/overview.md — Unit, snapshot, eval, and agent CLI testing
 - docs/testing/stdio.md — Stdio transport testing
 - docs/testing/remote.md — Remote server and OAuth testing
 
-**Architecture and Operations:**
-- docs/architecture/overview.md — System design
+**MCP architecture and operations:**
+
+- docs/architecture/overview.md — MCP system design
 - docs/operations/security.md — Authentication and security patterns
 - docs/operations/stdio-auth.md — Device code flow, token caching, client ID architecture
 - docs/operations/oauth-signout-playbook.md — Remote OAuth diagnostic runbook
 - docs/operations/embedded-agents.md — LLM provider configuration for AI-powered tools
-- docs/operations/github-actions.md — GitHub Actions guidance
+- docs/operations/github-actions.md — MCP deployment workflows
 - docs/operations/logging.md — Logging guidance
 - docs/operations/monitoring.md — Monitoring guidance
 - docs/operations/token-cost-tracking.md — Tool definition token cost tracking
 
-**Cloudflare:**
+**MCP Cloudflare:**
+
 - docs/cloudflare/overview.md — Cloudflare package overview
 - docs/cloudflare/architecture.md — Cloudflare architecture
 - docs/cloudflare/oauth-architecture.md — Cloudflare OAuth architecture
 
-**Integrations:**
+**MCP integrations:**
+
 - docs/integrations/claude-code-plugin.md — Plugin structure and agent prompts
 - docs/integrations/ide-instructions-refactor.md — IDE instruction refactor notes
 
-**Specs:**
+**MCP specs:**
+
 - docs/specs/README.md — Specs index
 - docs/specs/embedded-agent-openai-routing.md — Embedded agent OpenAI routing spec
 - docs/specs/search-events.md — Search Events spec
 - docs/specs/subpath-constraints.md — Subpath constraints spec
 
-**Releases:**
+**MCP releases:**
+
 - docs/releases/stdio.md — npm package release
 - docs/releases/cloudflare.md — Cloudflare deployment
 
 ## Commands
 
 ```bash
 # Development
-pnpm run dev                              # Start dev server
-pnpm run build                            # Build all packages
+pnpm run dev                              # Start MCP dev server
+pnpm run build                            # Build non-CLI workspace packages
+pnpm --filter sentry run cli help         # Run CLI help from repository root
 
-# Testing
+# MCP testing
 pnpm -w run cli --transport stdio "q"      # Test MCP tools
 pnpm -w run cli --transport stdio --access-token=TOKEN "q"
 
@@ -121,12 +136,14 @@ Use `/dex` skill to coordinate complex work. Create tasks with full context, bre
 1. Check neighboring files for existing patterns before writing new code.
 2. When adding or modifying Sentry API endpoint usage, ALWAYS validate the endpoint behavior against the Sentry source code in `~/src/sentry` instead of assuming docs or client parameters are authoritative.
 3. Update relevant docs when changing functionality.
-4. Follow docs/contributing/error-handling.md for error types.
+4. Follow docs/contributing/error-handling.md for MCP error types and
+   packages/cli/src/lib/errors.ts for CLI error classes.
 5. Follow docs/contributing/pr-management.md for commits and PRs.
 
 ## Commit Attribution
 
 AI commits MUST include:
+
 ```
 Co-Authored-By: (the agent model's name and attribution byline)
 ```

README.md

@@ -1,4 +1,11 @@
-# sentry-mcp
+# Sentry Toolkit
+
+This repository contains the Sentry CLI, the Sentry MCP server, and shared
+packages. For the CLI, see the [CLI guide](docs/cli/README.md) and the published
+documentation at <https://cli.sentry.dev/>. The [documentation index](docs/README.md)
+covers both products and shared contributor guidance.
+
+## Sentry MCP
 
 Sentry's MCP service is primarily designed for human-in-the-loop coding agents. Our tool selection and priorities are focused on developer workflows and debugging use cases, rather than providing a general-purpose MCP server for all Sentry functionality.
 
@@ -267,6 +274,7 @@ pnpm -w run cli --access-token=TOKEN "query"
 Note: The CLI defaults to `http://localhost:5173`. Override with `--mcp-host` or set `MCP_URL` environment variable.
 
 **Comprehensive testing playbooks:**
+
 - **Stdio testing:** See `docs/testing/stdio.md` for complete guide on building, running, and testing the stdio implementation (IDEs, MCP Inspector)
 - **Remote testing:** See `docs/testing/remote.md` for complete guide on testing the remote server (OAuth, web UI, CLI client)
 
@@ -287,4 +295,6 @@ When addressing automated feedback, focus on the underlying concerns rather than
 
 ### Contributor Documentation
 
-Looking to contribute or explore the full documentation map? See `CLAUDE.md` (also available as `AGENTS.md`) for contributor workflows and the complete docs index. The `docs/` folder contains the per-topic guides and tool-integrated `.md` files.
+Looking to contribute? Start at the [Toolkit documentation index](docs/README.md)
+for CLI, MCP, and shared guides. See `AGENTS.md` for repository rules and
+`packages/cli/AGENTS.md` for CLI-specific rules.

docs/README.md

@@ -1,78 +1,39 @@
-# Contributor Docs
-
-This directory contains contributor documentation used by humans and LLMs. The
-canonical workflow and required docs live in [../AGENTS.md](../AGENTS.md)
-(`CLAUDE.md` is a symlink to the same file).
-
-## Start Here
-
-- Tool implementation: [contributing/adding-tools.md](contributing/adding-tools.md)
-- Tool output policy: [contributing/tool-responses.md](contributing/tool-responses.md)
-- Testing: [testing/overview.md](testing/overview.md)
-- Shared implementation patterns: [contributing/common-patterns.md](contributing/common-patterns.md)
-
-## Topic Map
-
-### Contributing
-
-- [contributing/adding-tools.md](contributing/adding-tools.md) - Tool structure, visibility, implementation, and registration
-- [contributing/api-patterns.md](contributing/api-patterns.md) - Sentry API client and MSW patterns
-- [contributing/coding-guidelines.md](contributing/coding-guidelines.md) - TypeScript and code style guidance
-- [contributing/common-patterns.md](contributing/common-patterns.md) - Shared Zod, validation, and formatting patterns
-- [contributing/documentation-style-guide.md](contributing/documentation-style-guide.md) - Documentation style guide
-- [contributing/error-handling.md](contributing/error-handling.md) - Error hierarchy and propagation
-- [contributing/pr-management.md](contributing/pr-management.md) - Commit and PR guidelines
-- [contributing/quality-checks.md](contributing/quality-checks.md) - Quality gates and pre-commit checks
-- [contributing/search-events-api-patterns.md](contributing/search-events-api-patterns.md) - Search Events API guidance
-- [contributing/tool-responses.md](contributing/tool-responses.md) - User-facing tool output policy, snapshot review, and QA expectations
-
-### Testing
-
-- [testing/overview.md](testing/overview.md) - Unit, snapshot, eval, and agent CLI testing
-- [testing/stdio.md](testing/stdio.md) - Stdio transport testing
-- [testing/remote.md](testing/remote.md) - Remote server and OAuth testing
-
-### Architecture And Operations
-
-- [architecture/overview.md](architecture/overview.md) - System design
-- [operations/embedded-agents.md](operations/embedded-agents.md) - Embedded LLM provider configuration
-- [operations/github-actions.md](operations/github-actions.md) - GitHub Actions guidance
-- [operations/logging.md](operations/logging.md) - Logging guidance
-- [operations/monitoring.md](operations/monitoring.md) - Monitoring guidance
-- [operations/oauth-signout-playbook.md](operations/oauth-signout-playbook.md) - Remote OAuth diagnostic runbook
-- [operations/security.md](operations/security.md) - Authentication and security patterns
-- [operations/stdio-auth.md](operations/stdio-auth.md) - Device code auth and token caching
-- [operations/token-cost-tracking.md](operations/token-cost-tracking.md) - Tool definition token cost tracking
-
-### Cloudflare
-
-- [cloudflare/overview.md](cloudflare/overview.md) - Cloudflare package overview
-- [cloudflare/architecture.md](cloudflare/architecture.md) - Cloudflare architecture
-- [cloudflare/oauth-architecture.md](cloudflare/oauth-architecture.md) - Cloudflare OAuth architecture
-
-### Integrations
-
-- [integrations/claude-code-plugin.md](integrations/claude-code-plugin.md) - Plugin structure and agent prompts
-- [integrations/ide-instructions-refactor.md](integrations/ide-instructions-refactor.md) - IDE instruction refactor notes
-
-### Specs
-
-- [specs/README.md](specs/README.md) - Specs index
-- [specs/alert-rules.md](specs/alert-rules.md) - Alert inspection, editing, options, and connected sources
-- [specs/embedded-agent-openai-routing.md](specs/embedded-agent-openai-routing.md) - Embedded agent OpenAI routing spec
-- [specs/project-management.md](specs/project-management.md) - Project management tools spec
-- [specs/remembered-oauth-skills.md](specs/remembered-oauth-skills.md) - Remembered OAuth skill defaults spec
-- [specs/search-events.md](specs/search-events.md) - Search Events spec
-- [specs/sentry-bearer-cloudflare-auth.md](specs/sentry-bearer-cloudflare-auth.md) - Direct Sentry token auth for the Cloudflare transport
-- [specs/subpath-constraints.md](specs/subpath-constraints.md) - Subpath constraints spec
-
-### Releases
-
-- [releases/stdio.md](releases/stdio.md) - npm package release
-- [releases/cloudflare.md](releases/cloudflare.md) - Cloudflare deployment
-
-## Maintenance
-
-Update docs when patterns change, new tools are added, or common issues arise.
-Prefer cross-links over duplicated guidance: topic docs should link to the
-canonical policy or pattern that owns the detail.
+# Toolkit Documentation
+
+This directory is the documentation home for the Toolkit repository. It covers
+the Sentry CLI, the MCP server, and the code they share. Start with the product
+you are working on:
+
+- [Sentry CLI](cli/README.md) — commands, contributor guides, generated docs,
+  and the published CLI documentation site.
+- [Sentry MCP](mcp/README.md) — tools, transports, Cloudflare, operations, and
+  MCP-specific tests and specs.
+
+The published CLI site lives in `apps/cli-docs/` because CLI releases build
+and package it from that workspace. The contributor index here links to its
+source and to <https://cli.sentry.dev/>. MCP documentation lives in the topic
+directories below; the MCP index explains which guides apply to that product.
+
+## Shared Contributor Guides
+
+- [Coding guidelines](contributing/coding-guidelines.md) — repository-wide style
+  and the separate CLI and MCP patterns.
+- [Documentation style](contributing/documentation-style-guide.md) — how to
+  write and link Toolkit docs.
+- [Pull requests](contributing/pr-management.md) — contribution and review
+  workflow.
+- [Quality checks](contributing/quality-checks.md) — repository checks before
+  a change is proposed.
+
+For package-specific rules, see the root [AGENTS.md](../AGENTS.md) and the
+[CLI AGENTS.md](../packages/cli/AGENTS.md). `packages/toolkit-core/` contains
+shared primitives used by both products.
+
+## Ownership
+
+Keep repository-wide contributor guidance in `docs/contributing/`. Put product
+guides under the relevant product index, and link to existing material rather
+than copying it. CLI website pages and generated command documentation remain
+in `apps/cli-docs/`; changes there follow the CLI documentation build and
+release. Root `docs/` changes run the repository documentation checks; they do
+not deploy a website or select a product build on their own.

docs/cli/README.md

@@ -0,0 +1,33 @@
+# Sentry CLI Documentation
+
+The CLI lives in `packages/cli/`. Its published user guide and command reference
+are at <https://cli.sentry.dev/>. The site source lives in `apps/cli-docs/`, and
+CLI releases build it from that workspace. Start here for repository guides:
+
+- [Getting started](../../apps/cli-docs/src/content/docs/getting-started.mdx),
+  [features](../../apps/cli-docs/src/content/docs/features.md), and
+  [self-hosted use](../../apps/cli-docs/src/content/docs/self-hosted.md) —
+  hand-written user guides.
+- [Contributing to the CLI](../../apps/cli-docs/src/content/docs/contributing.md)
+  — setup, generated project layout, testing, and builds.
+- [CLI development notes](../../packages/cli/DEVELOPMENT.md) and
+  [command conventions](../../packages/cli/CONTRIBUTING.md) — implementation
+  details and command design.
+- [CLI build workflow](../../.github/workflows/cli-build.yml) and
+  [release configuration](../../.craft.yml) — binaries, npm packaging, and
+  release-gated website artifacts.
+- [CLI AGENTS.md](../../packages/cli/AGENTS.md) — package-specific coding and
+  testing rules.
+- [CLI docs fragments](../../apps/cli-docs/src/fragments/commands/index.md)
+  — hand-written additions to generated command pages. Command metadata and
+  examples belong to the commands; the generated pages are not checked in.
+- [CLI overview](../../packages/cli/README.md) — installation, supported
+  platforms, and library use.
+
+Run CLI commands from `packages/cli/` or use `pnpm --filter sentry run <script>`
+at the repository root. Check `packages/cli/package.json` for current scripts
+before running them. The CLI docs workspace uses `pnpm --filter sentry-cli-docs`
+and depends on generated CLI documentation. The root
+[coding guidelines](../contributing/coding-guidelines.md) and
+[quality checks](../contributing/quality-checks.md) apply alongside the CLI's
+own rules.

docs/contributing/coding-guidelines.md

@@ -1,6 +1,8 @@
 # Coding Guidelines
 
-Essential patterns and standards for Sentry MCP development.
+Repository-wide TypeScript and style guidance for Toolkit. See the
+[CLI guide](../cli/README.md) and [MCP guide](../mcp/README.md) for
+product-specific implementation patterns.
 
 ## TypeScript Configuration
 
@@ -51,7 +53,7 @@ import { mockData } from "@sentry-mcp/mocks";
 import { UserInputError } from "./errors.js";
 ```
 
-## Tool Implementation
+## MCP Tool Implementation
 
 ```typescript
 export const toolName = {