diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 7d5d88f..8058772 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,69 +1,60 @@
 # GitHub Copilot Repository Instructions
 
-These instructions help GitHub Copilot and Copilot Chat provide better code suggestions and answers for the Mapbox MCP DevKit Server. For more details, see the [Copilot repository instructions guide](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions).
+Instructions for GitHub Copilot working on the Mapbox MCP DevKit Server. See [Copilot repository instructions guide](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions).
 
 ---
 
-## Project Overview
+## 1. Review Code Before Suggesting Changes
 
-- Model Context Protocol (MCP) server for Mapbox developer APIs
-- Written in TypeScript (strict mode)
-- Provides tools for Mapbox style management, token management, GeoJSON processing, and more
+- **Read existing patterns** before proposing solutions
+- Check `src/tools/` for tool implementation patterns
+- Reference `CLAUDE.md` for architecture decisions
+- Verify token scope requirements in `README.md`
 
-## Code Style
+## 2. Security & Token Management
 
-- Use TypeScript strict mode
-- Prefer ES module syntax (`import`/`export`)
-- Destructure imports when possible
-- Tool names must be `snake_case_tool`
-- Tool schemas live in `*.schema.ts` files
-- Use Zod for schema validation
-- Run Prettier and ESLint before committing
+- **Never hardcode tokens or credentials**
+- All Mapbox API calls require `MAPBOX_ACCESS_TOKEN` with specific scopes
+- Token scope mismatches are the primary failure mode
+- Use `VERBOSE_ERRORS=true` for debugging auth issues
+- Reference token scope requirements in `README.md` before implementing
 
-## Development & Build
+## 3. Code Quality & Style
 
-- Requires Node.js 22+
-- Install dependencies: `npm install`
-- Build: `npm run build`
-- Run tests: `npm test`
-- Lint: `npm run lint`
-- Format: `npm run format`
-- Create new tool: `npx plop create-tool`
-- Create DXT package: `npx @anthropic-ai/dxt pack`
-- Build Docker image: `docker build -t mapbox-mcp-devkit .`
+- **TypeScript strict mode** - No implicit any, proper typing required
+- **Tool naming** - Tool names (MCP identifiers) must be `snake_case_tool` (e.g., `list_styles_tool`). TypeScript class names follow `PascalCaseTool` convention (e.g., `ListStylesTool`)
+- **Schema separation** - Schema in `*.schema.ts`, implementation in `*.tool.ts`
+- **Use plop generator** - `npx plop create-tool` for new tools
+- **Zod validation** - All tool inputs validated with Zod schemas
+- ESLint and Prettier handle formatting - run `npm run lint:fix && npm run format:fix`
 
-## Testing
+## 4. Testing Requirements
 
-- Run all tests: `npm test`
-- Update tool snapshot tests after adding/removing tools:
-  - `npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot`
-- Run a single test file: `npm test -- path/to/testfile.ts`
-- Only update snapshots when changes are intentional
+- **Run tests before committing** - `npm test`
+- **Update snapshots deliberately** - After adding/removing/modifying tools: `npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot`
+- Never update snapshots without understanding what changed
+- Snapshot tests capture tool metadata (TypeScript class names in `PascalCaseTool` format, MCP tool names in `snake_case_tool` format, descriptions)
 
-## PR & Branching
+## 5. Collaboration Standards
 
-- Always run `npm run lint` and `npm test` before committing
-- Keep PRs focused and well-described
+- **Focused commits** - One logical change per commit
+- **Build before testing** - Always `npm run build` before running
+- **Check CI** - Tests must pass before merge
+- Reference issues/PRs in commit messages
 
-## Tool Configuration
+## 6. When to Avoid Copilot Suggestions
 
-- Tools can be enabled/disabled at startup (see `TOOL_CONFIGURATION.md`)
-- Example: `node dist/esm/index.js --enable-tools list_styles_tool,create_style_tool`
-
-## Security & Tokens
-
-- Each tool requires specific Mapbox token scopes (see `README.md`)
-- Using insufficient scopes will result in errors
-- Use `VERBOSE_ERRORS=true` for detailed error output
-
-## Additional Resources
-
-- [README.md](../README.md)
-- [AGENTS.md](../AGENTS.md)
-- [CLAUDE.md](../CLAUDE.md)
-- [TOOL_CONFIGURATION.md](../TOOL_CONFIGURATION.md)
-- [docs/claude-code-integration.md](../docs/claude-code-integration.md)
+- **Don't auto-accept** tool name changes without verifying snake_case_tool convention
+- **Don't merge** schema definitions into tool implementation files
+- **Don't skip** snapshot updates after adding/removing tools
+- **Don't commit** without running linter and tests
 
 ---
 
-_Edit this file to keep Copilot up to date on project standards, commands, and best practices._
+**Key files:**
+
+- `docs/engineering_standards.md` — Comprehensive contributor guidelines
+- `CLAUDE.md` — Architecture and technical patterns
+- `AGENTS.md` — AI agent development guide
+- `README.md` — Complete tool reference
+- `TOOL_CONFIGURATION.md` — Tool configuration
diff --git a/AGENTS.md b/AGENTS.md
index ecbba86..5cd6b85 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,79 +1,72 @@
 # AGENTS.md — Mapbox MCP DevKit Server
 
-This file provides coding agents with the context, commands, and conventions needed to work effectively with the Mapbox MCP DevKit Server. For human-focused docs, see `README.md`.
+Instructions for AI agents working with the Mapbox MCP DevKit Server. For project overview and user documentation, see `README.md` and `CLAUDE.md`.
 
 ---
 
-## Project Overview
+## Critical Patterns
 
-- Model Context Protocol (MCP) server for Mapbox developer APIs
-- Exposes tools for style management, token management, GeoJSON processing, and more
-- Written in TypeScript, strict mode enabled
+**Tool Architecture:**
 
-## Setup Commands
+- **Tool naming:** Tool names (MCP identifiers) must be `snake_case_tool` (e.g., `list_styles_tool`). TypeScript class names follow `PascalCaseTool` convention (e.g., `ListStylesTool`)
+- Schema files: Always separate `*.schema.ts` from `*.tool.ts`
+- Schema validation: Use Zod, export both schema and inferred type
+- Tool location: `src/tools/tool-name-tool/` with all three files (schema, implementation, tests)
 
-- Install dependencies: `npm install`
-- Build the project: `npm run build`
-- Run tests: `npm test`
-- Lint code: `npm run lint`
-- Format code: `npm run format`
-- Create a new tool: `npx plop create-tool`
-- Create DXT package: `npx @anthropic-ai/dxt pack`
-- Build Docker image: `docker build -t mapbox-mcp-devkit .`
+**Testing:**
 
-## Environment
+- After adding/removing tools: `npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot`
+- Never update snapshots without verifying changes
+- Tool snapshots capture class names (TypeScript `PascalCaseTool`), tool names (MCP `snake_case_tool`), and descriptions
 
-- Requires Node.js 22+
-- Set `MAPBOX_ACCESS_TOKEN` in your environment (see `manifest.json`)
-- For Claude Code integration, see `docs/claude-code-integration.md`
+**Token Management:**
 
-## Code Style
+- All Mapbox API tools require `MAPBOX_ACCESS_TOKEN` with specific scopes
+- Token scope errors are the #1 issue - check `README.md` for required scopes
+- Use `VERBOSE_ERRORS=true` for debugging authentication failures
 
-- TypeScript strict mode
-- Use ES module syntax (`import`/`export`)
-- Destructure imports when possible
-- Tool names must be `snake_case_tool`
-- Tool schemas live in `*.schema.ts` files
-- Use Zod for schema validation
-- Run Prettier and ESLint before committing
+## Factual Errors to Watch For
 
-## Testing Instructions
+**Incorrect Tool Naming:**
 
-- Run all tests: `npm test`
-- Update tool snapshot tests after adding/removing tools:
-  - `npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot`
-- Run a single test file: `npm test -- path/to/testfile.ts`
-- Only update snapshots when changes are intentional
+- ❌ `list_styles` → ✅ `list_styles_tool`
+- ❌ `ListStyles` → ✅ `ListStylesTool`
 
-## Tool Configuration
+**Incorrect File Structure:**
 
-- Enable/disable tools at startup (see `TOOL_CONFIGURATION.md`)
-- Example: `node dist/esm/index.js --enable-tools list_styles_tool,create_style_tool`
+- ❌ Schema defined in `*.tool.ts` → ✅ Schema in separate `*.schema.ts`
+- ❌ Tool in `src/tools/ListStylesTool.ts` → ✅ Tool in `src/tools/list-styles-tool/ListStylesTool.ts`
 
-## PR Instructions
+**Incorrect Class References:**
 
-- Branch naming: use `feature/`, `fix/`, or `chore/` prefixes
-- PR title format: `[mcp-devkit-server] <Title>`
-- Always run `npm run lint` and `npm test` before committing
-- Keep PRs focused and well-described
+- ❌ `ToolRegistry.registerTool()` → ✅ Tools auto-registered via `src/tools/index.ts` exports
+- ❌ Manual tool instantiation → ✅ Use plop generator: `npx plop create-tool`
 
-## Security & Tokens
+**Incorrect Token Scope Usage:**
 
-- Each tool requires specific Mapbox token scopes (see `README.md`)
-- Using insufficient scopes will result in errors
-- Use `VERBOSE_ERRORS=true` for detailed error output
+- ❌ Using default token for all operations → ✅ Check required scopes per tool in `README.md`
+- ❌ `styles:read` for creating styles → ✅ `styles:write` required
 
-## Agent Tips
+## Essential Commands
 
-- Mention files/folders explicitly for agents to read or edit
-- Use `/clear` to reset context between tasks (Claude Code)
-- Use checklists in Markdown for large refactors or multi-step tasks
-- Prefer running single tests for performance
+```bash
+npm run build                    # Always build before running
+npm test                         # Run all tests
+npx plop create-tool             # Generate new tool scaffold
+npm run lint:fix && npm run format:fix  # Fix code style
+```
 
-## Large Monorepo?
+## Development Workflow
 
-- Place additional AGENTS.md files in subprojects if needed; the closest file to the code being edited takes precedence
+1. **Adding a tool:** `npx plop create-tool` → Implement schema/logic → Update snapshots
+2. **Modifying a tool:** Edit → Build → Test → Update snapshots if metadata changed
+3. **Testing:** Use MCP Inspector: `npx @modelcontextprotocol/inspector node dist/esm/index.js`
 
 ---
 
-_Edit this file to keep coding agents up to date on project standards, commands, and best practices._
+**See also:**
+
+- `docs/engineering_standards.md` — Comprehensive contributor guidelines
+- `CLAUDE.md` — Architecture and technical patterns
+- `README.md` — Complete tool reference and token scopes
+- `TOOL_CONFIGURATION.md` — Tool enable/disable configuration
diff --git a/CLAUDE.md b/CLAUDE.md
index 8887f5f..67db9d1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,183 +1,66 @@
 # CLAUDE.md — Mapbox MCP DevKit Server
 
-This file provides Claude and developers with essential context, commands, and standards for working with the Mapbox MCP DevKit Server. It follows [Anthropic's CLAUDE.md best practices](https://www.anthropic.com/engineering/claude-code-best-practices).
+## Overview
 
----
+This is an MCP (Model Context Protocol) server providing "geospatial intelligence capabilities through Mapbox APIs" for AI agents, enabling map styling, GeoJSON visualization, token management, and geocoding.
 
-## Common Bash Commands
+## Tech Stack
 
-- `npm run build` — Build the project
-- `npm test` — Run all tests
-- `npm run lint` — Run ESLint
-- `npm run lint:fix` — Auto-fix lint issues
-- `npm run format` — Check formatting with Prettier
-- `npm run format:fix` — Auto-format code
-- `npx plop create-tool` — Generate a new tool scaffold
-- `npx @modelcontextprotocol/inspector node dist/esm/index.js` — Inspect the MCP server
-- `npm run sync-manifest` — Sync version from package.json to manifest.json
-- `docker build -t mapbox-mcp-devkit .` — Build Docker image
-- `docker run mapbox/mcp-devkit-server ...` — Run server in Docker
-- `npm run tracing:jaeger:start` — Start Jaeger tracing backend (requires Docker)
-- `npm run tracing:jaeger:stop` — Stop Jaeger tracing backend
-- `npm run tracing:verify` — Show instructions for verifying tracing setup
+- **Runtime:** Node.js 22+ LTS
+- **Language:** TypeScript (strict mode)
+- **Testing:** Vitest
+- **Package Manager:** npm
 
-## Observability & Tracing
+## Project Structure
 
-This server includes OpenTelemetry (OTEL) instrumentation for distributed tracing. Tracing is **opt-in** and disabled by default.
+The codebase organizes into:
 
-### Quick Start with Jaeger
+- `src/index.ts` - Main entry point with .env loading and server initialization
+- `src/config/toolConfig.ts` - Configuration parser for tool filtering and MCP-UI toggles
+- `src/tools/` - MCP tool implementations with `BaseTool` abstract class and registry
+- `src/resources/` - Static reference data (style specs, token scopes, Streets v8 fields)
+- `src/utils/` - HTTP pipeline, JWT parsing, tracing, and version utilities
 
-1. Start Jaeger backend (requires Docker):
+## Key Architectural Patterns
 
-   ```bash
-   npm run tracing:jaeger:start
-   ```
+**Tool Architecture:** All tools extend `BaseTool<InputSchema, OutputSchema>`. Tools auto-validate inputs using Zod schemas. Each tool lives in `src/tools/tool-name-tool/` with separate `*.schema.ts` and `*.tool.ts` files.
 
-2. Configure environment variables in `.env`:
+**HTTP Pipeline System:** "Never patch global.fetch—use HttpPipeline with dependency injection instead." The `HttpPipeline` class applies policies (User-Agent, retry logic) via a chain-of-responsibility pattern. See `src/utils/httpPipeline.ts:20`.
 
-   ```bash
-   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-   OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
-   ```
+**Resource System:** Static reference data exposed as MCP resources using URI pattern `resource://mapbox-*`, including style layer specs, Streets v8 field definitions, and token scope documentation.
 
-3. Run the server:
+**Token Management:** Tools receive `MAPBOX_ACCESS_TOKEN` via `extra.authInfo.token` or environment variable. Token scope validation is critical—most tool failures stem from insufficient scopes (see `README.md` for per-tool requirements).
 
-   ```bash
-   npm run inspect:build
-   ```
+**Tool Registry:** Tools are auto-discovered via `src/tools/index.ts` exports. No manual registration required—just export from index.
 
-4. View traces at http://localhost:16686
+## Essential Workflows
 
-5. Stop Jaeger when done:
-   ```bash
-   npm run tracing:jaeger:stop
-   ```
+**Development commands:**
 
-### Environment Variables
+```bash
+npm install
+npm test
+npm run build
+npm run inspect:build  # Interactive MCP inspector
+npx plop create-tool   # Generate tool scaffold
+```
 
-- `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint URL (e.g., `http://localhost:4318`). If not set, tracing is disabled.
-- `OTEL_TRACING_ENABLED` — Set to `false` to explicitly disable tracing even if endpoint is configured
-- `OTEL_SERVICE_NAME` — Override service name (default: `mapbox-mcp-devkit-server`)
-- `OTEL_EXPORTER_OTLP_HEADERS` — JSON string of additional headers for OTLP exporter
-- `OTEL_LOG_LEVEL` — OTEL diagnostic log level: `NONE` (default), `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`. Defaults to `NONE` to prevent diagnostic logs from corrupting stdio transport.
+**New tool creation:** Run `npx plop create-tool` for interactive scaffolding (provide name without "Tool" suffix). Generates three files: `*.schema.ts`, `*.tool.ts`, and `*.test.ts`.
 
-### What Gets Traced
+**Testing workflow:**
 
-- Tool execution spans with timing and status
-- HTTP requests to Mapbox APIs (automatic instrumentation)
-- Configuration loading and initialization
-- Error details and stack traces
+- After adding/removing tools: `npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot`
+- Never update snapshots without verifying changes
+- Tool snapshots capture class names, tool names, and descriptions
 
-### Trace Attributes
+## Important Constraints
 
-Each tool execution span includes:
+- **Tool naming:** Tool names (MCP identifiers) must be `snake_case_tool` (e.g., `list_styles_tool`). TypeScript class names follow `PascalCaseTool` convention (e.g., `ListStylesTool`)
+- Schema files must be separate from implementation files (`*.schema.ts` vs `*.tool.ts`)
+- Avoid `any` types; add comments explaining unavoidable usage
+- Never execute real network calls in tests—mock `HttpPipeline` instead
+- All Mapbox API tools require valid token with specific scopes (most common failure mode)
 
-- `tool.name` — Tool identifier
-- `tool.input.size` — Input payload size
-- `operation.type` — Type of operation (e.g., `tool_execution`)
-- `session.id`, `user.id`, `account.id` — Context from MCP extra fields (if provided)
+## Documentation
 
-### Production Considerations
-
-- Tracing has minimal overhead when enabled
-- Recommended for debugging complex tool chains and performance issues
-- Can be used with any OTLP-compatible backend (Jaeger, Honeycomb, DataDog, etc.)
-- For hosted endpoints, configure appropriate sampling rates
-
-## Core Files & Structure
-
-- `src/tools/` — All tool implementations (see subfolders for each tool)
-- `src/resources/` — Resource classes and registries
-- `src/config/` — Tool and server configuration
-- `test/` — Unit and snapshot tests
-- `manifest.json` — DXT/extension manifest
-- `TOOL_CONFIGURATION.md` — Tool enable/disable and configuration guide
-- `README.md` — Main project documentation
-
-## Code Style Guidelines
-
-- Use TypeScript (strict mode enabled)
-- Prefer ES module syntax (`import`/`export`)
-- Destructure imports when possible
-- Follow snake_case for tool names (e.g., `list_styles_tool`)
-- Tool input schemas live in `*.schema.ts` files, separate from implementation
-- Use Zod for schema validation
-- Run Prettier and ESLint before committing
-
-## Testing Instructions
-
-- Run all tests: `npm test`
-- Update tool snapshot tests after adding/removing tools:
-  - `npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot`
-- Run a single test file: `npm test -- path/to/testfile.ts`
-- Only update snapshots when changes are intentional
-
-## Repository Etiquette
-
-- Prefer squash merges for PRs
-- Keep PRs focused and well-described
-- Update `CLAUDE.md` and `README.md` when adding new tools or workflows
-
-## Developer Environment Setup
-
-- Requires Node.js 22+
-- Install dependencies: `npm install`
-- Set `MAPBOX_ACCESS_TOKEN` in your environment (see `manifest.json` and `README.md`)
-- For Claude Code integration, see `docs/claude-code-integration.md`
-
-## Tool Configuration
-
-- Tools can be enabled/disabled at startup (see `TOOL_CONFIGURATION.md`)
-- Example: `node dist/esm/index.js --enable-tools list_styles_tool,create_style_tool`
-
-### MCP-UI Support (Enabled by Default)
-
-MCP-UI allows tools that return URLs to also provide interactive iframe resources. **Enabled by default** and fully backwards compatible.
-
-**Supported tools:**
-
-- `preview_style_tool` - Embeds style previews
-- `geojson_preview_tool` - Embeds GeoJSON visualizations
-- `style_comparison_tool` - Embeds style comparisons
-
-**How it works:**
-
-- Tools return both text URL and UIResource
-- Clients without MCP-UI support (e.g., Claude Desktop) ignore UIResource
-- Clients with MCP-UI support (e.g., Goose) render iframes
-
-**Disable if needed:**
-
-- Environment variable: `ENABLE_MCP_UI=false`
-- Command-line flag: `--disable-mcp-ui`
-
-**Note:** You rarely need to disable this. See [mcpui.dev](https://mcpui.dev) for compatible clients.
-
-## Mapbox Token Scopes
-
-- Each tool requires specific Mapbox token scopes (see `README.md` for details)
-- Using insufficient scopes will result in errors
-
-## Known Issues & Warnings
-
-- Large GeoJSON files may cause slow performance in preview tools
-- Always check token scopes if a tool fails with authentication errors
-- Use `VERBOSE_ERRORS=true` for detailed error output
-
-## Claude Code Usage Tips
-
-- Mention files/folders explicitly for Claude to read or edit
-- Use `/clear` to reset context between tasks
-- Use checklists in Markdown for large refactors or multi-step tasks
-- Prefer running single tests for performance
-- Use `claude mcp add ...` to add this server to Claude Code
-
-## Additional Resources
-
-- [TOOL_CONFIGURATION.md](./TOOL_CONFIGURATION.md) — Tool config and usage
-- [docs/claude-code-integration.md](./docs/claude-code-integration.md) — Claude Code integration
-- [README.md](./README.md) — Project overview and tool documentation
-
----
-
-_Edit this file to keep Claude and your team up to date on project standards, commands, and best practices._
+Additional guidance available in `docs/engineering_standards.md` (comprehensive contributor guidelines), `README.md` (complete tool reference and token scopes), `TOOL_CONFIGURATION.md` (enable/disable tools), `AGENTS.md` (AI agent patterns), and integration guides for Claude Desktop, VS Code, Cursor, and Claude Code.
diff --git a/README.md b/README.md
index b542c8a..3d4a81b 100644
--- a/README.md
+++ b/README.md
@@ -559,8 +559,8 @@ The project includes snapshot tests to ensure tool integrity and prevent acciden
 
 **What the snapshot test covers:**
 
-- Tool class names
-- Tool names (must follow `snake_case_tool` naming convention)
+- Tool class names (TypeScript classes follow `PascalCaseTool` convention, e.g., `ListStylesTool`)
+- Tool names (MCP identifiers must follow `snake_case_tool` convention, e.g., `list_styles_tool`)
 - Tool descriptions
 
 **When to update snapshots:**
@@ -719,8 +719,9 @@ node dist/esm/index.js --disable-mcp-ui
 
 ## Contributing
 
-We welcome contributions to the Mapbox Development MCP Server! Please review our standards and guidelines before contributing:
+We welcome contributions to the Mapbox Development MCP Server! Please review our documentation:
 
-- **[Engineering Standards (CLAUDE.md)](./CLAUDE.md)** - Code quality, testing, documentation, and collaboration standards for all contributors
-- **[AI Agent Instructions (AGENTS.md)](./AGENTS.md)** - Comprehensive guide for AI agents working with this codebase
-- **[GitHub Copilot Guidelines](./.github/copilot-instructions.md)** - Best practices for using GitHub Copilot responsibly in this project
+- **[Engineering Standards (docs/engineering_standards.md)](./docs/engineering_standards.md)** - Comprehensive guidelines for all contributors
+- **[CLAUDE.md](./CLAUDE.md)** - Architecture and technical patterns
+- **[AGENTS.md](./AGENTS.md)** - Critical patterns and common errors for AI agents
+- **[GitHub Copilot Guidelines](./.github/copilot-instructions.md)** - Copilot-specific development practices
diff --git a/docs/engineering_standards.md b/docs/engineering_standards.md
new file mode 100644
index 0000000..70531b3
--- /dev/null
+++ b/docs/engineering_standards.md
@@ -0,0 +1,179 @@
+# Mapbox MCP DevKit Server Engineering Standards
+
+This document establishes comprehensive guidelines for contributors to the Mapbox MCP DevKit server project.
+
+## Core Principles
+
+**Code Quality Requirements:**
+
+All code must be written in TypeScript. No JavaScript files in `src/` or `test/`. Contributors must ensure their work passes both ESLint and Prettier checks before committing:
+
+```bash
+npm run lint:fix
+npm run format:fix
+```
+
+Key requirements:
+
+- Maintain strict typing conventions (`strict: true` in tsconfig.json)
+- Avoid `any` types; add explanatory comments if unavoidable
+- Never patch global objects (e.g., `global.fetch`)
+- Follow tool naming conventions: Tool names (MCP identifiers) must be `snake_case_tool` (e.g., `list_styles_tool`). TypeScript class names follow `PascalCaseTool` convention (e.g., `ListStylesTool`)
+- Separate schema definitions (`*.schema.ts`) from implementation (`*.tool.ts`)
+
+**Testing Expectations:**
+
+New features require unit tests with coverage goals targeting critical logic paths. The project uses Vitest as its testing framework, with tests colocated alongside source files in tool directories.
+
+Critical testing rules:
+
+- Mock external services and APIs; do not make real network calls in tests
+- After adding/removing tools, update snapshots: `npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot`
+- Never update snapshots without understanding what changed
+- Test files follow the pattern: `*.test.ts` alongside `*.tool.ts` and `*.schema.ts`
+
+**Documentation Standards:**
+
+All public interfaces require JSDoc comments. User-facing modifications must be documented:
+
+- Update `README.md` for new tools or setup changes
+- Update `TOOL_CONFIGURATION.md` for configuration changes
+- Reference `CLAUDE.md` for architectural decisions
+- Maintain changelog entries for significant changes
+
+## Technical Implementation
+
+**Tool Architecture:**
+
+All tools must extend `BaseTool<InputSchema, OutputSchema>` from `src/tools/BaseTool.ts`. Tools auto-validate inputs using Zod schemas.
+
+Tool creation workflow:
+
+1. Run `npx plop create-tool` (provide name without "Tool" suffix)
+2. Implement Zod schema in `*.schema.ts`
+3. Implement tool logic in `*.tool.ts`
+4. Add unit tests in `*.test.ts`
+5. Export from `src/tools/index.ts` for auto-registration
+
+**HTTP Request Handling:**
+
+Use the `HttpPipeline` abstraction for all HTTP operations. Never patch `global.fetch`. Apply policies (User-Agent, Retry) through the pipeline:
+
+```typescript
+import { HttpPipeline } from '../utils/httpPipeline.js';
+
+const pipeline = new HttpPipeline();
+const response = await pipeline.execute(url, options);
+```
+
+This approach supports dependency injection and maintains testability. See `src/utils/httpPipeline.ts:20` for implementation details.
+
+**Token Management:**
+
+All Mapbox API tools require `MAPBOX_ACCESS_TOKEN` with specific scopes:
+
+- Tools receive tokens via `extra.authInfo.token` or `process.env.MAPBOX_ACCESS_TOKEN`
+- Document required scopes in `README.md` for each tool
+- Token scope mismatches are the primary failure mode
+- Use `VERBOSE_ERRORS=true` for debugging authentication issues
+
+**Resource System:**
+
+Static reference data should be exposed as MCP resources using URI pattern `resource://mapbox-*`. Resources provide:
+
+- Style layer specifications
+- Streets v8 field definitions
+- Token scope documentation
+- Layer type mappings
+
+See `src/resources/` for examples.
+
+**Collaboration Workflow:**
+
+Changes flow through pull requests requiring approval from core maintainers:
+
+- Keep PRs focused on a single logical change
+- Reference issues in PR descriptions
+- Run tests and linting before pushing: `npm test && npm run lint`
+- Build must succeed: `npm run build`
+
+## Security and DevOps
+
+**Environment Variables:**
+
+Keep secrets out of repositories. Use environment variables for sensitive data:
+
+- `MAPBOX_ACCESS_TOKEN` - Required for all Mapbox API operations
+- `VERBOSE_ERRORS` - Set to `true` for detailed error messages
+- `ENABLE_MCP_UI` - Controls MCP-UI support (default: `true`)
+- `OTEL_EXPORTER_OTLP_ENDPOINT` - OpenTelemetry endpoint (optional)
+- `OTEL_SERVICE_NAME` - Override service name for tracing (optional)
+
+**OpenTelemetry Configuration:**
+
+Observability is opt-in via OpenTelemetry. Enable only when debugging:
+
+- Tracing is disabled by default
+- Set `OTEL_EXPORTER_OTLP_ENDPOINT` to enable
+- Use Jaeger for local development: `npm run tracing:jaeger:start`
+- See `docs/tracing.md` for detailed configuration
+
+**Docker:**
+
+The project includes Docker support for containerized deployment:
+
+```bash
+docker build -t mapbox-mcp-devkit .
+docker run -e MAPBOX_ACCESS_TOKEN="..." mapbox-mcp-devkit
+```
+
+## Quick Start Commands
+
+Setup and development workflow:
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build project
+npm run build
+
+# Lint and format
+npm run lint:fix
+npm run format:fix
+
+# Generate new tool
+npx plop create-tool
+
+# Interactive testing
+npm run inspect:build
+
+# Create DXT package
+npx @anthropic-ai/dxt pack
+```
+
+## Common Pitfalls
+
+**Avoid these mistakes:**
+
+1. ❌ Using `any` type without comments
+2. ❌ Patching `global.fetch` instead of using `HttpPipeline`
+3. ❌ Making real network calls in tests
+4. ❌ Forgetting to update snapshots after tool changes
+5. ❌ Tool names not following `snake_case_tool` convention (e.g., using `listStyles` instead of `list_styles_tool`)
+6. ❌ Schema and implementation in same file
+7. ❌ Hardcoding tokens or credentials
+8. ❌ Missing required token scopes in documentation
+9. ❌ Committing without running linter and tests
+10. ❌ Auto-updating snapshots without reviewing changes
+
+## References
+
+- `CLAUDE.md` - Architecture and technical patterns
+- `AGENTS.md` - AI agent development guide
+- `README.md` - Complete tool reference and token scopes
+- `TOOL_CONFIGURATION.md` - Tool enable/disable configuration
+- `docs/tracing.md` - OpenTelemetry setup and configuration