Restructure documentation using Diataxis framework

CLAUDE.md

@@ -1,20 +1,63 @@
 # Mintlify documentation
 
+## Diataxis Documentation Framework
+
+This documentation follows the [Diataxis framework](https://diataxis.fr/), which organizes content into four distinct types. **Do not mix content types within a single page.**
+
+### The Four Content Types
+
+| Type | Purpose | User Need | Directory |
+|------|---------|-----------|-----------|
+| **Tutorials** | Learn by doing | "Teach me" | `/tutorials/` |
+| **How-to Guides** | Solve specific problems | "Help me do X" | `/how-to/` |
+| **Reference** | Look up facts | "What are the details?" | `/packages/`, `/concepts/` |
+| **Explanation** | Understand concepts | "Help me understand why" | `/concepts/` |
+
+### Tutorials (`/tutorials/`)
+- Guide users through building a complete project
+- Focus on ONE path - don't present alternatives
+- Don't explain "why" - just teach through doing
+- Include checkpoints where users can verify success
+- Example: "Build your first WebMCP tool with React"
+
+### How-to Guides (`/how-to/`)
+- Solve specific problems or tasks
+- Assume the reader already knows the basics
+- Action-focused: minimal explanation, maximum doing
+- Can be read non-linearly
+- Example: "How to handle errors in tools"
+
+### Reference (`/packages/`, `/concepts/*.mdx`)
+- Technical descriptions and facts
+- Complete, accurate, austere
+- Structure mirrors the thing being described
+- No tutorials or explanations mixed in
+- Example: "registerTool() API parameters"
+
+### Explanation (`/concepts/why-webmcp.mdx`, `/concepts/architecture.mdx`)
+- Help users understand concepts deeply
+- Discuss "why" not "how"
+- Can include opinions and perspectives
+- Designed for reading away from keyboard
+- Example: "Why WebMCP vs browser automation"
+
+### Common Mistakes to Avoid
+- **Don't mix types**: A tutorial that stops to explain "why" breaks flow
+- **Don't add alternatives to tutorials**: Guide ONE path completely
+- **Don't explain in reference docs**: Just state the facts
+- **Don't include procedures in explanations**: Save the "how" for tutorials/guides
+
 ## Documentation structure overview
 
-The WebMCP documentation uses a flat + organized directory structure:
+The WebMCP documentation uses a Diataxis-organized directory structure:
 
-### Root-level pages
-Core documentation pages live in the repository root:
-- **Introduction & Getting Started**: `introduction.mdx`, `quickstart.mdx`, `development.mdx`
-- **Core Guides**: `best-practices.mdx`, `security.mdx`, `troubleshooting.mdx`, `advanced.mdx`
-- **Use Cases**: `building-mcp-ui-apps.mdx`, `connecting-agents.mdx`, `frontend-tools.mdx`
-- **Examples & Reference**: `examples.mdx`, `live-tool-examples.mdx`, `changelog.mdx`
+### Content type directories
+- **`/tutorials/`**: Step-by-step learning content (Diataxis: Tutorials)
+- **`/how-to/`**: Task-focused problem-solving guides (Diataxis: How-to Guides)
+- **`/concepts/`**: Explanations and reference material (Diataxis: Explanation + Reference)
+- **`/packages/`**: NPM package API reference (Diataxis: Reference)
 
-### Organized directories
-Specialized content is organized into directories:
-- **`/concepts/`**: Core concepts (architecture, tool design, schemas, security, performance, glossary)
-- **`/packages/`**: NPM package reference (react-webmcp, transports, smart-dom-reader, etc.)
+### Other directories
 - **`/calling-tools/`**: How agents call WebMCP tools (embedded agent, AI browsers, extension, devtools)
 - **`/frameworks/`**: Framework-specific integration guides (Vue, Svelte, Angular, Rails, etc.)
 - **`/extension/`**: Browser extension documentation (agents, userscripts)

best-practices.mdx

@@ -1,14 +1,145 @@
 ---
-title: Best Practices for Creating Tools
-description: Learn best practices for designing and implementing WebMCP tools on websites you control. Tool design principles, naming conventions, security, and optimal AI integration.
+title: Best Practices
+description: Learn best practices for designing and implementing WebMCP tools. Quick reference to detailed how-to guides.
 icon: list-check
 ---
 
-This guide covers the complete tool development lifecycle: from naming and schema design, through implementation and error handling, to testing and monitoring. Unlike userscripts where you work around existing structures, controlling your entire website lets you design tools from the ground up for optimal AI integration.
+This page provides a quick overview of WebMCP best practices with links to detailed how-to guides.
 
-<Info>
-These practices apply when you own the website and can integrate WebMCP tools directly into your codebase. For userscript development, see [Managing Userscripts](/extension/managing-userscripts).
-</Info>
+<Note>
+**Looking for step-by-step guidance?** See the [How-to Guides](/how-to) for detailed instructions on specific tasks.
+</Note>
+
+## Tool Design
+
+Create tools that AI agents can discover and use effectively.
+
+<CardGroup cols={2}>
+  <Card title="Design Effective Tools" icon="pen-ruler" href="/how-to/design-tools">
+    Naming conventions, descriptions, and consolidating related operations
+  </Card>
+
+  <Card title="Validate Input" icon="shield-check" href="/how-to/validate-input">
+    Use Zod and JSON Schema for robust input validation
+  </Card>
+</CardGroup>
+
+### Quick Tips
+
+- Use `domain_verb_noun` naming pattern (e.g., `cart_add_item`)
+- Write detailed descriptions - it's the only info AI has about your tool
+- Add `.describe()` to every Zod parameter
+- Consolidate related operations into one powerful tool
+
+## Error Handling
+
+Return helpful error messages that AI can use to recover or inform users.
+
+<Card title="Handle Errors" icon="triangle-exclamation" href="/how-to/handle-errors">
+  Authentication checks, authorization, network failures, and validation errors
+</Card>
+
+### Quick Tips
+
+- Always use `isError: true` for failures
+- Check authentication before protected operations
+- Provide actionable error messages
+- Use timeouts for network requests
+
+## Response Format
+
+Format responses so AI can present information clearly.
+
+<Card title="Format Responses" icon="file-lines" href="/how-to/format-responses">
+  Use markdown instead of JSON for better AI comprehension
+</Card>
+
+### Quick Tips
+
+- Return markdown strings, not JSON objects
+- Use headers, lists, and formatting
+- Include helpful context and metadata
+
+## Performance
+
+Make tools respond quickly for voice and real-time interactions.
+
+<Card title="Optimize Performance" icon="gauge-high" href="/how-to/optimize-performance">
+  Optimistic updates, caching, and avoiding blocking operations
+</Card>
+
+### Quick Tips
+
+- Update local state before returning (optimistic updates)
+- Sync to backend in background
+- Limit tool count - consolidate related operations
+- Cache expensive operations
+
+## Testing
+
+Verify tools work correctly before deploying.
+
+<Card title="Test Your Tools" icon="flask-vial" href="/how-to/test-tools">
+  Unit testing, React hook testing, and manual testing with MCP-B Extension
+</Card>
+
+### Quick Tips
+
+- Test tool registration configuration
+- Test handlers with valid and invalid inputs
+- Test error scenarios
+- Manual test with MCP-B Extension
+
+## Security
+
+Protect your application and users.
+
+<Card title="Security Guide" icon="shield" href="/security">
+  Authentication, authorization, input sanitization, and threat models
+</Card>
+
+### Quick Tips
+
+- Only expose tools users can already access via UI
+- Validate user authentication and authorization
+- Sanitize all inputs
+- Never expose sensitive data in responses
+
+## All How-to Guides
+
+<CardGroup cols={2}>
+  <Card title="Design Effective Tools" icon="pen-ruler" href="/how-to/design-tools">
+    Tool naming, descriptions, and schemas
+  </Card>
+
+  <Card title="Handle Errors" icon="triangle-exclamation" href="/how-to/handle-errors">
+    Error responses and recovery patterns
+  </Card>
+
+  <Card title="Validate Input" icon="shield-check" href="/how-to/validate-input">
+    Zod and JSON Schema validation
+  </Card>
+
+  <Card title="Format Responses" icon="file-lines" href="/how-to/format-responses">
+    Markdown formatting for AI
+  </Card>
+
+  <Card title="Optimize Performance" icon="gauge-high" href="/how-to/optimize-performance">
+    Optimistic updates and caching
+  </Card>
+
+  <Card title="Test Your Tools" icon="flask-vial" href="/how-to/test-tools">
+    Unit and integration testing
+  </Card>
+</CardGroup>
+
+---
+
+## Detailed Reference (Legacy)
+
+The sections below contain the original detailed content. For updated guidance, see the linked how-to guides above.
+
+<Accordion title="Show detailed tool design reference">
 
 ## Tool Design Principles
 
@@ -1260,3 +1391,5 @@ ${results.map(r => `- ${r.title}`).join('\n')}`
     See real-world implementations
   </Card>
 </CardGroup>
+
+</Accordion>

docs.json

@@ -76,10 +76,25 @@
             ]
           },
           {
-            "group": "Guides",
+            "group": "Tutorials",
+            "icon": "graduation-cap",
             "pages": [
-              "connecting-agents",
-              "best-practices",
+              "tutorials/index",
+              "tutorials/first-tool-vanilla",
+              "tutorials/first-tool-react"
+            ]
+          },
+          {
+            "group": "How-to Guides",
+            "icon": "wrench",
+            "pages": [
+              "how-to/index",
+              "how-to/design-tools",
+              "how-to/handle-errors",
+              "how-to/validate-input",
+              "how-to/format-responses",
+              "how-to/optimize-performance",
+              "how-to/test-tools",
               "development",
               "advanced",
               "building-mcp-ui-apps",
@@ -108,7 +123,8 @@
             ]
           },
           {
-            "group": "NPM Packages",
+            "group": "API Reference",
+            "icon": "book",
             "pages": [
               "packages/global",
               "packages/transports",
@@ -121,7 +137,7 @@
             ]
           },
           {
-            "group": "Reference",
+            "group": "Resources",
             "pages": [
               "changelog",
               "troubleshooting",