Update guidance files for docs restructuring (#644)

* Update guidance files to reflect docs restructuring

Update AGENTS.md/CLAUDE.md, STYLE-GUIDE.md, and skills (docs-review,
upstream-release-docs) to encode the information architecture, design
principles, and page conventions established during the Phase 1-3 docs
restructuring. This ensures future contributions follow the new
product-area-based structure.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Address review feedback: restore Diataxis, fix paths

- Restore Diataxis framework reference as the underlying authoring
  model (it still applies, just not to folder structure)
- Remove reference to transient restructuring plan document
- Add docs/toolhive/ base path to all folder references so
  contributors place files correctly

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: danbarr

.claude/skills/docs-review/SKILL.md

@@ -63,6 +63,18 @@ Watch for these telltale signs of AI-generated docs that need human intervention
 | Over-explaining | Verbose descriptions of obvious things | Trust the reader; cut aggressively |
 | Hedging language | "may," "might," "could potentially" | Be direct or remove |
 
+### Section Structure and Navigation
+
+The docs follow a product-area-based information architecture under `docs/toolhive/`. Check:
+
+- **Self-contained sections**: Product-specific content belongs in its product section (`docs/toolhive/guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`), not in a shared section.
+- **Quickstarts in product sections**: Quickstarts live inside their product section, not in a separate top-level section.
+- **Integration placement**: Third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) belong in `integrations/`, not in a product section.
+- **Next steps section**: Every how-to guide and tutorial page must end with a "Next steps" section containing 1-3 forward links. Missing "Next steps" is a primary issue.
+- **Introduction pages**: Each product section should have an Introduction as the first sidebar child. New sections must follow this pattern.
+- **Progressive disclosure**: Core workflows should appear before advanced topics. Check that advanced content isn't mixed in with beginner-facing pages.
+- **Forward navigation path**: A reader should be able to follow "Next steps" links from the quickstart through core workflows without relying on the sidebar.
+
 ### Clarity and Readability
 
 - **Passive voice**: "Backend discovery occurs" → "vMCP discovers backends"
@@ -113,6 +125,8 @@ Structure your review as:
 **Primary issues** (address before merge):
 
 - Information architecture: content in wrong document, cross-document duplication
+- Content placed in the wrong section (e.g., product-specific content in Concepts, integration content in a product section)
+- Missing "Next steps" section on how-to guides and tutorials
 - Structure problems that harm navigation
 - Missing explanations for confusing design decisions
 - Significantly buried or redundant content

.claude/skills/upstream-release-docs/SKILL.md

@@ -124,6 +124,14 @@ Apply the approved changes:
 
 2. **Create new pages** for new features that lack existing documentation. Default to documenting new features rather than skipping them:
 
+   **Page placement** — the docs are organized by product area under `docs/toolhive/`. Place new content in the correct section:
+   - **Product-specific guides** go in the relevant product section (`docs/toolhive/guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`).
+   - **Third-party integration guides** go in `docs/toolhive/integrations/`.
+   - **Cross-cutting concepts** go in `docs/toolhive/concepts/`.
+   - **Per-MCP-server usage guides** go in `docs/toolhive/guides-mcp/`.
+   - **Reference material** goes in `docs/toolhive/reference/`.
+   - Check the project's CLAUDE.md "Information architecture" section for the full placement rules.
+
    **Diataxis separation** — create separate pages per document type, not one combined page:
    - **Concept page** (explanation): What is this feature, why does it exist, when would you use it? Lead with concrete scenarios and user personas ("If you maintain a shared MCP registry and want to let teams publish reusable tool bundles..."). Explain relationships to existing features.
    - **Guide page** (how-to): Task-oriented, organized by user goals — not by API endpoint order. Include practical examples: realistic `curl` commands, sample payloads with plausible values, expected responses, and error cases. If a feature has both producer and consumer sides, document both workflows.
@@ -145,9 +153,10 @@ Apply the approved changes:
    **Naming conventions** — when the feature introduces naming rules (e.g., kebab-case identifiers, camelCase config keys), call these out explicitly with examples of valid and invalid names.
 
    **Page mechanics:**
-   - Place each page in the appropriate directory
-   - Update sidebar/navigation configuration
+   - Place each page in the appropriate product section directory (see "Page placement" above)
+   - Update sidebar/navigation configuration in `sidebars.ts`
    - Update frontmatter descriptions on all new and modified pages
+   - Add a "Next steps" section at the end of every how-to guide and tutorial page with 1-3 forward links
    - Only skip creating a page that would duplicate auto-generated reference content (e.g., don't manually list API endpoints that are already in a swagger-rendered page)
 
 3. **Add cross-references** — link new content from related existing pages and vice versa.

AGENTS.md

@@ -80,23 +80,69 @@ The documentation should be accessible to a wide range of technical users, inclu
 
 ## Information architecture
 
-This project follows the [Diataxis framework](https://diataxis.fr/) for documentation organization. Diataxis divides documentation into four types based on user needs:
-
-1. **Tutorials** (`/docs/toolhive/tutorials/`) - Learning-oriented, step-by-step lessons that guide users through completing a project or learning a concept.
-2. **How-to guides** (`/docs/toolhive/guides-*/`) - Task-oriented, practical guides that show how to solve specific problems or accomplish specific tasks.
-3. **Reference** (`/docs/toolhive/reference/`) - Information-oriented, technical descriptions of the machinery and how to operate it (API docs, CLI commands, configuration options).
-4. **Explanation/Concepts** (`/docs/toolhive/concepts/`) - Understanding-oriented, explanations that clarify and illuminate topics, provide background and context.
-
-### When to create new pages
-
-Create a new documentation page when:
-
-- The content addresses a distinct task, concept, or reference topic that doesn't fit within existing pages.
-- An existing page would become too long or cover too many disparate topics.
-- The information architecture requires it (e.g., a new MCP server guide, a new tutorial).
-- The content belongs to a different Diataxis category than existing content.
-
-Always consider where the new page fits in the Diataxis framework and place it in the appropriate directory. Update `/sidebars.ts` to include the new page in the navigation.
+This project follows the [Diataxis framework](https://diataxis.fr/) for documentation authoring - each page is a tutorial, how-to guide, reference, or explanation. The site is organized by **product area**, with each section self-contained so a reader can complete their journey without leaving it. Cross-cutting content lives in dedicated shared sections.
+
+All documentation lives under `docs/toolhive/`. Folder paths below are relative to that root.
+
+### Design principles
+
+1. **Route readers to value fast.** The home page helps a reader figure out where to go within 10 seconds.
+2. **Each section is self-contained.** A reader in the CLI section shouldn't need to leave it to complete their task. Quickstarts, guides, and relevant reference material live together.
+3. **Forward momentum on every page.** Every page ends with a "Next steps" section linking to the next logical page.
+4. **Consistent structure across sections.** Each product area follows the same pattern: Introduction, Quickstart, how-to guides.
+5. **Progressive disclosure.** Core workflows first, advanced topics grouped separately.
+
+### Top-level sections
+
+| Section | Folder | What belongs here |
+| --- | --- | --- |
+| ToolHive UI | `guides-ui/` | Desktop app guides, quickstart, and reference |
+| ToolHive CLI | `guides-cli/` | CLI guides, quickstart, command reference, API reference |
+| Kubernetes Operator | `guides-k8s/` | K8s deployment, operation, auth, telemetry, CRD reference |
+| Virtual MCP Server | `guides-vmcp/` | Gateway/aggregation guides, quickstart, optimizer |
+| Registry Server | `guides-registry/` | Registry Server deployment, config, auth, API reference |
+| Integrations | `integrations/` | Cross-cutting third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) |
+| Concepts | `concepts/` | Cross-cutting explanations (MCP primer, groups, auth framework, observability, etc.) |
+| MCP server guides | `guides-mcp/` | Per-server usage guides (auto-generated index) |
+| Reference | `reference/` | Client compatibility, CLI commands, API specs, CRD specs, registry schemas |
+| Tutorials | `tutorials/` | End-to-end tutorials that span multiple components (kept small; most tutorials moved to product sections or Integrations) |
+
+### Section skeleton
+
+Each product section follows this pattern:
+
+```text
+[Product Area]           (category label)
+├── Introduction         (what it is, who it's for, where to start)
+├── Quickstart           (hands-on in <10 minutes)
+├── [How-to guides]      (organized by journey phase)
+│   ├── Install / Deploy
+│   ├── Use
+│   ├── Secure
+│   ├── Operate
+│   └── Optimize
+└── [Reference]          (inline where relevant)
+```
+
+Not every section needs every phase. The Introduction is an explicit first sidebar child, not a hidden category-link page.
+
+### Where to place new content
+
+- **Product-specific content** goes in the relevant product section (`guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`).
+- **Quickstarts** live inside their product section, not in a separate top-level section.
+- **Third-party integration guides** (connecting ToolHive with external tools/services) go in `integrations/`.
+- **Cross-cutting concepts** (applicable to multiple product areas) go in `concepts/`.
+- **Per-MCP-server usage guides** go in `guides-mcp/`.
+- **Reference material** (specs, schemas, compatibility matrices) goes in `reference/`, with cross-links from the relevant product section.
+- Update `/sidebars.ts` to include any new page in the navigation.
+
+### Page requirements
+
+Every how-to guide and tutorial page must include:
+
+- Front matter with `title` and `description`.
+- A "Next steps" section at the end with 1-3 links to the next logical pages, following the journey phases (install, use, secure, operate, optimize).
+- Cross-links to related content in other sections where relevant.
 
 ## Review process
 

STYLE-GUIDE.md

@@ -155,6 +155,44 @@ Considerations for screenshots and other images:
 - Use the primary brand colors (`#2D684B` on light backgrounds, `#BDDFC2` on
   dark backgrounds) for annotations like callouts and highlight boxes.
 
+## Page structure
+
+Every how-to guide and tutorial page follows a consistent structure. This
+ensures readers always know what to expect and never hit dead ends.
+
+### Front matter
+
+Every page must have front matter with at least a `title` and `description`.
+
+### Next steps
+
+Every how-to guide and tutorial page ends with a `## Next steps` section
+containing 1-3 links to the next logical pages. These follow the journey phases:
+install, use, secure, operate, optimize. Example:
+
+```mdx
+## Next steps
+
+- [Run MCP servers](./run-mcp-servers.mdx) to deploy your first server.
+- [Client configuration](./client-configuration.mdx) to connect your IDE.
+```
+
+### Introduction pages
+
+Each product section (UI, CLI, K8s, vMCP, Registry Server) has an Introduction
+page as its first sidebar child. This page explains what the component is, who
+it's for, and where to start. It is an explicit child item in the sidebar - not
+a hidden category-link page.
+
+### Cross-references
+
+Link to related content in other sections where it adds value. Key patterns:
+
+- Product section auth pages link to the Concepts auth framework page.
+- Product section telemetry pages link to the Integrations OpenTelemetry guide.
+- The Registry Server introduction disambiguates from the built-in registry.
+- The UI "Access the CLI" page links to the CLI section.
+
 ## Markdown style
 
 Just like a consistent writing style is critical to clarity and messaging,