Clean up docs

Author: dcramer

biome.json

@@ -4,7 +4,11 @@
     "enabled": true
   },
   "files": {
-    "ignore": ["worker-configuration.d.ts", "tsconfig*.json"]
+    "ignore": [
+      "worker-configuration.d.ts",
+      "tsconfig*.json",
+      "packages/mcp-server-mocks/src/fixtures/trace.json"
+    ]
   },
   "vcs": {
     "enabled": true,

docs/README.md

@@ -15,22 +15,21 @@ This directory serves a dual purpose:
 ## Contents
 
 ### Core Guidelines
-- `coding-guidelines.mdc` - Coding standards, patterns, and best practices
-- `coding-practices.mdc` - General coding practices and conventions
-- `package-management.mdc` - Package and dependency management
+- @docs/coding-guidelines.mdc - Coding standards, patterns, and best practices
+- @docs/common-patterns.mdc - Reusable patterns and conventions
+- @docs/quality-checks.mdc - Required checks before changes
 
 ### API and Tools
-- `adding-new-tools.mdc` - How to add new MCP tools
-- `adding-prompts.mdc` - Guidelines for adding new prompts
-- `adding-new-resources.mdc` - How to add new MCP resources
-- `api-client-patterns.mdc` - Working with the Sentry API client
-- `search-events-api-patterns.md` - Comprehensive guide to search_events API patterns
-- `using-api-mocks.mdc` - Testing with API mocks
+- @docs/adding-tools.mdc - How to add new MCP tools
+- @docs/adding-prompts.mdc - Guidelines for adding new prompts
+- @docs/adding-resources.mdc - How to add new MCP resources
+- @docs/api-patterns.mdc - Working with the Sentry API client
+- @docs/search-events-api-patterns.md - search_events API patterns
 
 ### Infrastructure and Operations
-- `deployment-and-infrastructure.mdc` - Deployment processes and infrastructure
-- `observability-and-monitoring.mdc` - Monitoring and telemetry practices
-- `security-and-authentication.mdc` - Security best practices
+- @docs/deployment.mdc - Deployment processes (Cloudflare)
+- @docs/monitoring.mdc - Monitoring and telemetry practices
+- @docs/security.mdc - Security and authentication patterns
 
 ## For LLMs
 
@@ -51,9 +50,9 @@ These `.mdc` files are designed to be easily consumed by various AI development
 ## LLM-Specific Guidelines
 
 The `llms/` subdirectory contains meta-documentation for LLMs:
-- `documentation-style-guide.mdc` - How to write effective LLM documentation
-- `document-scopes.mdc` - Purpose and content for each doc
-- `documentation-todos.mdc` - Tasks for documentation improvement
+- @docs/llms/documentation-style-guide.mdc - How to write effective LLM documentation
+- @docs/llms/document-scopes.mdc - Purpose and content for each doc
+  
 
 ## Maintenance
 
@@ -65,4 +64,4 @@ These documents should be updated when:
 
 ## Note
 
-This documentation supplements but does not replace the root-level CLAUDE.md file, which remains the primary instruction set for Claude Code when working with this repository. The CLAUDE.md file will be refactored into multiple focused documents within this directory.
+This documentation supplements but does not replace the root-level @AGENTS.md file, which remains the primary instruction set for agents when working with this repository. The @AGENTS.md file is kept concise and points to focused documents within this directory.

docs/adding-tools.mdc

@@ -303,7 +303,7 @@ try {
 
 ### Implementation Guidelines
 
-1. **Create a CLAUDE.md file** in the tool directory documenting:
+1. **Create an AGENTS.md file** in the tool directory documenting:
    - The embedded agent's prompt and behavior
    - Common translation patterns
    - Known limitations

docs/architecture.mdc

@@ -56,7 +56,7 @@ A separate web chat application that uses the MCP server.
 
 **Note**: This is NOT part of the MCP server itself - it's a demonstration of how to build a chat interface that consumes MCP.
 
-See [Cloudflare Web App Documentation](./cloudflare/overview.md) for details.
+See "Overview" in @docs/cloudflare/overview.md for details.
 
 ### packages/mcp-server-evals
 

docs/cloudflare/architecture.md

@@ -183,7 +183,7 @@ SENTRY_CLIENT_SECRET = "..." # OAuth app secret
 
 ## Related Documentation
 
-- [Authentication Flow](./authentication.md)
-- [Chat Interface Features](./chat-interface.md)
-- [Deployment Guide](./deployment.md)
-- [Core MCP Server](../architecture.mdc)
+- See "OAuth Architecture" in @docs/cloudflare/oauth-architecture.md
+- See "Chat Interface" in @docs/cloudflare/architecture.md
+- See "Deployment" in @docs/cloudflare/deployment.md
+- See "Architecture" in @docs/architecture.mdc

docs/cloudflare/mcpagent-architecture.md

@@ -308,12 +308,12 @@ OAuth Provider                          McpAgent
 ## Implementation Reference
 
 The actual implementation can be found in:
-- **Main class**: `packages/mcp-cloudflare/src/server/lib/mcp-agent.ts`
-- **Constraint utilities**: `packages/mcp-cloudflare/src/server/lib/constraint-utils.ts`
-- **Type definitions**: `packages/mcp-cloudflare/src/server/types.ts`
+- Main class: @packages/mcp-cloudflare/src/server/lib/mcp-agent.ts
+- Constraint utilities: @packages/mcp-cloudflare/src/server/lib/constraint-utils.ts
+- Type definitions: @packages/mcp-cloudflare/src/server/types.ts
 
 ## Related Documentation
 
-- [OAuth Architecture](./oauth-architecture.md) - How OAuth provider integrates
-- [MCP Transport Implementation](../lib/mcp-transport.ts) - Our implementation
-- [Constraint DO Analysis](./constraint-do-analysis.md) - Alternative architectures considered
+- OAuth Architecture: @docs/cloudflare/oauth-architecture.md — How OAuth provider integrates
+- MCP Transport (stdio) Implementation: @packages/mcp-server/src/transports/stdio.ts — Core server transport
+- Constraint DO Analysis: @docs/cloudflare/constraint-do-analysis.md — Alternative architectures considered

docs/cloudflare/overview.md

@@ -35,14 +35,14 @@ Think of it as:
 
 ## Documentation Structure
 
-- [Architecture](./architecture.md) - Technical architecture of the web application
-- [Authentication](./authentication.md) - OAuth flow and token management  
-- [Chat Interface](./chat-interface.md) - UI components and features
-- [Prompts Integration](./prompts-integration.md) - How the chat app uses MCP prompts
-- [Deployment](./deployment.md) - Deploying to Cloudflare Workers
+- Architecture: @docs/cloudflare/architecture.md — Technical architecture of the web application
+- OAuth Architecture: @docs/cloudflare/oauth-architecture.md — OAuth flow and token management
+- Chat Interface: @docs/cloudflare/architecture.md — See "Chat Interface" section
+- Prompts Integration: @docs/cloudflare/prompts-integration.md — How the chat app uses MCP prompts
+- Deployment: @docs/cloudflare/deployment.md — Deploying to Cloudflare Workers
 
 ## Quick Links
 
 - Live deployment: https://mcp.sentry.dev
 - Package location: `packages/mcp-cloudflare`
-- **For MCP Server docs**: [Core MCP Server Architecture](../architecture.mdc)
+- **For MCP Server docs**: See "Architecture" in @docs/architecture.mdc

docs/cursor.mdc

@@ -36,16 +36,16 @@ Sentry MCP is a Model Context Protocol server that provides access to Sentry's f
 - **Changing architecture**: Update `docs/architecture.mdc`
 
 ### Critical Sync Requirements
-- **CLAUDE.md ↔ cursor.mdc**: These files MUST stay synchronized
-- **When updating CLAUDE.md**: Also update `cursor.mdc` with equivalent guidance
-- **When updating cursor.mdc**: Also update `CLAUDE.md` with equivalent guidance
+- **AGENTS.md ↔ cursor.mdc**: These files MUST stay synchronized
+- **When updating AGENTS.md**: Also update `cursor.mdc` with equivalent guidance
+- **When updating cursor.mdc**: Also update `AGENTS.md` with equivalent guidance
 - Both files serve the same purpose for different tools (Claude Code vs Cursor IDE)
 
 ### Documentation Update Process
 1. **Identify affected docs** while implementing changes
 2. **Update documentation in the same session** as code changes
 3. **Verify cross-references** remain accurate
-4. **Ensure CLAUDE.md ↔ cursor.mdc sync** is maintained
+4. **Ensure AGENTS.md ↔ cursor.mdc sync** is maintained
 5. **Add examples** for new patterns introduced
 
 **Documentation updates are not optional - they are part of completing any task.**
@@ -75,7 +75,7 @@ You should ALWAYS update docs when they are inaccurate or you have learned new r
 
 ## Documentation Maintenance
 
-- **Keep CLAUDE.md and cursor.mdc concise**: These files are navigation aids, not comprehensive docs
+- **Keep AGENTS.md and cursor.mdc concise**: These files are navigation aids, not comprehensive docs
 - **Reference, don't duplicate**: Point to `docs/` files instead of repeating content
 - **Update referenced docs first**: When making changes, update the actual documentation before updating references
 - **Avoid redundancy**: Check existing docs before creating new ones (see `docs/llms/documentation-style-guide.mdc`)

docs/llms/document-scopes.mdc

@@ -2,6 +2,12 @@
 
 Defines the specific purpose and content for each documentation file.
 
+## Reference Style (MANDATORY)
+
+- Use @path for all local file references, repo-root relative (e.g., `@packages/mcp-server/src/server.ts`).
+- Refer to sections by name: `See "Error Handling" in @docs/common-patterns.mdc`.
+- Keep Markdown links only for external sites.
+
 ## Core Documents
 
 ### architecture.mdc
@@ -201,14 +207,14 @@ Defines the specific purpose and content for each documentation file.
 - General coding guidelines
 - Project overview
 
-### CLAUDE.md
-**Purpose**: Claude Code entry point
+### AGENTS.md
+**Purpose**: Agent entry point (Claude Code, Cursor, etc.)
 
 **Must Include**:
 - Brief project description
 - Documentation directory reference
 - Critical quality checks
-- Claude Code-specific notes
+- Agent-specific notes (tools, transports, auth defaults)
 
 **Must Exclude**:
 - Detailed architecture (link to architecture.mdc)
@@ -226,4 +232,4 @@ Key improvements needed:
 - **deployment.mdc** (574 lines): Too much CloudFlare docs → focus on config
 - **monitoring.mdc** (559 lines): Verbose explanations → code examples
 
-The goal: Each document should be focused enough to be useful in a single context window while remaining comprehensive for its topic.
+The goal: Each document should be focused enough to be useful in a single context window while remaining comprehensive for its topic.

docs/llms/documentation-style-guide.mdc

@@ -17,7 +17,7 @@ This guide defines how to write effective documentation for LLMs working with th
 
 ### 3. Show, Don't Tell
 - Include minimal, focused code examples
-- Reference actual implementations: `See packages/mcp-server/src/tools.ts:45`
+- Reference actual implementations: `See @packages/mcp-server/src/server.ts:45`
 - Use real patterns from the codebase
 
 ## MDC Header Format
@@ -61,12 +61,12 @@ Project-specific rules that must be followed.
 
 ## Common Patterns
 
-Link to reusable patterns: See `common-patterns.mdc#error-handling`
+Link to reusable patterns: See "Error Handling" in @docs/common-patterns.mdc
 
 ## References
 
-- Implementation: `packages/mcp-server/src/[file].ts`
-- Tests: `packages/mcp-server/src/[file].test.ts`
+- Implementation: `@packages/mcp-server/src/[file].ts`
+- Tests: `@packages/mcp-server/src/[file].test.ts`
 - Examples in codebase: [specific function/tool names]
 ```
 
@@ -115,15 +115,24 @@ export const ParamOrganizationSlug = z
 
 ## Cross-References
 
-### Internal Links:
-- Use relative references: `See common-patterns.mdc#error-handling`
-- Link to specific sections with anchors
-- Avoid duplicating content - link instead
+### File References (MANDATORY):
+- Use @path syntax for local files: `@docs/common-patterns.mdc`
+- Always reference from repo root: `@packages/mcp-server/src/server.ts`
+- Do NOT use Markdown links for local files (avoid markdown `[text](./...)` patterns)
+- Prefer path-only mentions to help agents parse
+
+### Section References:
+- Refer to sections by name, not anchors: `See "Error Handling" in @docs/common-patterns.mdc`
+- If multiple sections share a name, include a short hint: `("Zod Patterns" in @docs/common-patterns.mdc)`
 
 ### Code References:
-- Use specific file paths: `packages/mcp-server/src/tools.ts`
-- Include line numbers for specific examples: `tools.ts:45-52`
-- Reference actual implementations over creating examples
+- Use concrete paths and identifiers: `@packages/mcp-server/src/tools/search-events/index.ts:buildQuery`
+- Optional line hints for humans: `server.ts:45-52` (agents may ignore)
+- Prefer real implementations over fabricated examples
+
+### External Links:
+- Keep standard Markdown links for external sites
+- Use concise link text; avoid link-only bullets
 
 ## Language and Tone
 
@@ -191,7 +200,15 @@ pnpm install
 cp .env.example .env  # Add your API keys
 ```
 
-See `CLAUDE.md#development-setup` for environment variables.
+See "Development Setup" in @AGENTS.md for environment variables.
 ```
 
-This style guide ensures documentation remains focused, valuable, and maintainable for LLM consumption.
+## Agent Readability Checklist
+
+- Uses @path for all local file references
+- Short, focused sections with concrete examples
+- Minimal prose; prefers code and commands
+- Clear preconditions and environment notes
+- Error handling and validation rules are explicit
+
+This style guide ensures documentation remains focused, valuable, and maintainable for LLM consumption.