Updates to add an AI section to the docs, including new pages and links, and to fix enhanced link search indexing by rendering titles as headings.

docs/.vitepress/config.mjs

@@ -1,6 +1,40 @@
 import { defineConfig } from 'vitepress'
 import { linkMetadataPlugin } from './plugins/linkMetadataPlugin'
 
+/**
+ * Inject EnhancedLink title props as plain text into the markdown source
+ * before rendering, so VitePress local search can index link card titles.
+ *
+ * VitePress's local search _render hook receives the raw markdown source.
+ * <EnhancedLink> is a Vue component — markdown-it passes it through as a
+ * raw HTML block, so the title prop value never appears as a text node in
+ * the indexed content.
+ *
+ * This function rewrites each <EnhancedLink title="..."> tag to also emit
+ * the title as a plain markdown text token immediately after the tag, so
+ * the search indexer associates the title with the correct page section.
+ *
+ * @param {string} src - Raw markdown source of the page
+ * @param {object} env - VitePress page environment
+ * @param {object} md - markdown-it instance
+ * @returns {string} Rendered HTML with EnhancedLink titles as indexed text
+ */
+function renderWithEnhancedLinkTitles(src, env, md) {
+  // Replace each <EnhancedLink ... title="Foo" ... /> with a level-4 heading
+  // containing the title text, followed by the original tag.
+  //
+  // Using a heading (####) rather than a paragraph means:
+  // 1. The title appears as the matched section in search results (better UX)
+  // 2. The term is indexed in the `titles` field (higher relevance weight)
+  // 3. Clicking the result navigates to the correct section anchor
+  const patched = src.replace(
+    /(<EnhancedLink\b[^>]*\btitle="([^"]+)"[^>]*\/>)/g,
+    (match, tag, title) => `\n\n#### ${title}\n\n${tag}\n\n`
+  )
+
+  return md.render(patched, env)
+}
+
 export default defineConfig({
   vite: {
     plugins: [linkMetadataPlugin()]
@@ -15,6 +49,7 @@ export default defineConfig({
     search: {
       provider: 'local',
       options: {
+        _render: renderWithEnhancedLinkTitles,
         translations: {
           button: {
             buttonText: 'Search',
@@ -50,6 +85,13 @@ export default defineConfig({
           { text: 'GitHub Actions', link: '/github-actions' }
         ]
       },
+      { text: 'AI',
+        items: [
+          { text: 'AI Writing', link: '/ai/writing' },
+          { text: 'AI Review', link: '/ai/review' },
+          { text: 'MCP Servers', link: '/ai/mcp-servers' }
+        ]
+      },
       { text: 'Guide', link: '/guide' },
       { text: 'Contributing', link: '/contributing/' }
     ],
@@ -83,6 +125,15 @@ export default defineConfig({
           { text: 'Additional Tools', link: '/tools' }
         ]
       },
+      {
+        text: 'AI',
+        items: [
+          { text: 'Overview', link: '/ai/' },
+          { text: 'Writing', link: '/ai/writing' },
+          { text: 'Review', link: '/ai/review' },
+          { text: 'MCP Servers', link: '/ai/mcp-servers' }
+        ]
+      },
       {
         text: 'Contributing',
         items: [

docs/ai/index.md

@@ -0,0 +1,21 @@
+# AI for Documentation
+
+AI tools, agent skills, and MCP servers for technical writers and documentation teams.
+
+This section covers three areas where AI is changing documentation workflows:
+
+## 🖊️ [AI Writing](./writing)
+
+AI-powered writing assistants and agent skills for technical writing — from grammar and style tools to prompt templates that help you draft, structure, and refine documentation faster.
+
+## 🔍 [AI Review](./review)
+
+AI-powered review tools and agent skills for documentation review — tools that help catch issues, enforce style, and provide structured feedback on your docs before they ship.
+
+## 🔌 [MCP Servers](./mcp-servers)
+
+Model Context Protocol (MCP) servers relevant to documentation workflows — connecting AI agents directly to documentation tools like Vale, enabling richer, context-aware assistance.
+
+---
+
+*Looking for non-AI writing tools? See [Writing Tools](../writing). For quality assurance and linting, see [Quality Assurance](../quality).*

docs/ai/mcp-servers.md

@@ -0,0 +1,36 @@
+# MCP Servers
+
+Model Context Protocol (MCP) servers relevant to documentation workflows.
+
+## What is MCP?
+
+[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that allows AI assistants (such as Claude, Cursor, and other MCP-compatible clients) to connect to external tools and data sources. An MCP server exposes capabilities — like running a linter, querying a knowledge base, or fetching content — that an AI agent can invoke directly within a conversation.
+
+For documentation teams, MCP servers mean your AI assistant can actively use your documentation toolchain, not just talk about it.
+
+## Documentation MCP Servers
+
+### Vale MCP Server
+
+- **Repository**: [errata-ai/vale-mcp](https://github.com/errata-ai/vale-mcp)
+- **Description**: An MCP server that exposes [Vale](https://vale.sh/) prose linting capabilities to AI assistants. Allows an AI agent to run Vale checks on text directly within a conversation, returning style and grammar issues according to your configured Vale rules.
+- **Use cases**:
+  - Ask your AI assistant to lint a draft document against your style guide before publishing
+  - Integrate Vale feedback into AI-assisted writing and review workflows
+  - Run Vale checks without leaving your AI chat interface
+
+## Contributing
+
+Know of another MCP server useful for documentation workflows? This list is just getting started.
+
+MCP servers relevant to documentation might include servers for:
+- Documentation platforms (Confluence, Notion, GitBook)
+- Link checking and validation
+- Terminology and glossary management
+- Translation and localization
+
+*[Contribute to this project](../contributing/) and help grow this list.*
+
+---
+
+*For AI writing tools, see [AI Writing](./writing). For AI review tools and Vale integration patterns, see [AI Review](./review).*

docs/ai/review.md

@@ -0,0 +1,64 @@
+# AI Review
+
+AI-powered review tools, agent skills, and prompt resources for documentation review workflows.
+
+## AI Review Tools
+
+Tools that use AI to review, critique, and improve documentation quality.
+
+### Style & Prose Review
+
+- [Vale](https://vale.sh/) - Syntax-aware prose linter; integrates with AI workflows via the [Vale MCP Server](./mcp-servers)
+- [Harper](https://writewithharper.com/) - Grammar checker built for developers, runs locally with no data sent to the cloud
+- [Alex](https://github.com/get-alex/alex) - Catches insensitive and inconsiderate writing; pairs well with AI review workflows
+
+### AI-Assisted Review Platforms
+
+- [Grammarly Business](https://www.grammarly.com/business) - Team-level AI writing and review with style guide enforcement
+- [Writer](https://writer.com/) - AI writing platform with built-in style guide, terminology management, and review workflows for teams
+- [Acrolinx](https://www.acrolinx.com/) - Enterprise AI content governance platform for large documentation teams
+
+### Code Review with Docs Context
+
+- [GitHub Copilot Code Review](https://github.com/features/copilot) - AI-assisted pull request review that can flag missing or outdated documentation
+- [Reviewdog](https://github.com/reviewdog/reviewdog) - Automated code review tool that integrates linters (including Vale) into PR workflows
+
+## Agent Skills & Prompts
+
+Prompt templates, system prompts, and agent skill patterns for documentation review workflows.
+
+### Review Prompt Patterns
+
+Effective prompt patterns for AI-assisted documentation review:
+
+- **Completeness check** — Ask the AI to identify missing sections, undefined terms, or steps that assume unstated prerequisites
+- **Audience alignment** — Provide the target audience profile and ask the AI to flag content that is too advanced, too basic, or uses unexplained jargon
+- **Consistency audit** — Paste multiple pages and ask the AI to identify inconsistent terminology, formatting, or tone across them
+- **Accuracy review** — Provide the relevant code or API spec alongside the docs and ask the AI to flag discrepancies
+- **Readability pass** — Ask the AI to score readability and suggest specific rewrites for sentences above a target complexity level
+
+### Structured Review Checklists as Prompts
+
+Convert your documentation review checklist into a prompt template:
+
+```
+Review the following documentation against these criteria:
+1. Is every term defined on first use?
+2. Are all code examples syntactically correct?
+3. Does the content match the stated audience level?
+4. Are there any broken or missing cross-references?
+5. Is the tone consistent with [your style guide]?
+
+Flag each issue with: [ISSUE TYPE] - [location] - [description]
+```
+
+### Vale + AI Integration
+
+Vale's rule-based linting and AI review are complementary:
+- Use Vale for deterministic, rule-based checks (style guide enforcement, terminology)
+- Use AI for subjective review (clarity, completeness, audience fit)
+- The [Vale MCP Server](./mcp-servers) enables AI agents to run Vale checks directly within a conversation
+
+---
+
+*For non-AI quality assurance tools, see [Quality Assurance](../quality). For AI writing assistance, see [AI Writing](./writing).*

docs/ai/writing.md

@@ -0,0 +1,54 @@
+# AI Writing
+
+AI-powered writing assistants, agent skills, and prompt resources for technical writing workflows.
+
+## AI Writing Assistants
+
+Tools that use AI to help you write, edit, and improve documentation.
+
+### General Purpose
+
+- [Grammarly](https://www.grammarly.com/) - AI-powered writing assistant with grammar, style, and tone suggestions
+- [LanguageTool](https://languagetool.org/) - Open-source grammar and style checker with AI-enhanced suggestions
+- [QuillBot](https://quillbot.com/) - AI paraphrasing and rewriting tool useful for simplifying complex technical content
+
+### Technical Writing Focused
+
+- [GitHub Copilot](https://github.com/features/copilot) - AI pair programmer that also assists with writing documentation, README files, and inline code comments
+- [Mintlify Writer](https://writer.mintlify.com/) - AI-powered documentation writer that generates docs from code
+- [Swimm](https://swimm.io/) - AI-assisted documentation platform that keeps docs synchronized with code
+
+### AI Editors & Integrations
+
+- [Cursor](https://www.cursor.com/) - AI-first code editor with strong support for editing Markdown and documentation files
+- [Zed](https://zed.dev/) - High-performance editor with AI assistant integration for writing tasks
+
+## Agent Skills & Prompts
+
+Prompt templates, system prompts, and agent skill patterns for technical writing workflows.
+
+### Prompt Libraries
+
+- [Awesome ChatGPT Prompts](https://github.com/f/awesome-chatgpt-prompts) - Community-curated prompt collection including technical writing prompts
+- [Fabric](https://github.com/danielmiessler/fabric) - Open-source framework for augmenting humans with AI, includes patterns for writing and summarization
+
+### Technical Writing Prompt Patterns
+
+Effective prompt patterns for common technical writing tasks:
+
+- **Draft from outline** — Provide a structured outline and ask the AI to expand each section with appropriate technical depth
+- **Simplify for audience** — Paste complex content and specify the target audience (e.g., "rewrite this for a developer unfamiliar with Kubernetes")
+- **Generate examples** — Ask the AI to produce code examples or step-by-step walkthroughs for a concept you've described
+- **Review for clarity** — Ask the AI to identify sentences that are ambiguous, overly passive, or unnecessarily complex
+- **Terminology consistency** — Provide a glossary and ask the AI to flag inconsistent term usage in a document
+
+### AI Writing with Roo/Claude Skills
+
+If you use AI coding assistants with skill/tool support, technical writing skills can be defined to:
+- Enforce house style rules during drafting
+- Generate structured documentation from code or API specs
+- Produce first drafts of changelogs, release notes, or how-to guides
+
+---
+
+*For non-AI writing tools, see [Writing Tools](../writing). For AI-powered review and linting, see [AI Review](./review).*

docs/index.md

@@ -26,6 +26,11 @@ A **curated list** of awesome documentation tools, guides and best practices for
 ### 🌐 Publishing & Hosting
 - [GitHub Actions](./github-actions) - Automation for documentation workflows
 
+### 🤖 AI
+- [AI Writing](./ai/writing) - AI writing assistants and agent skills for technical writing
+- [AI Review](./ai/review) - AI review tools and agent skills for documentation review
+- [MCP Servers](./ai/mcp-servers) - Model Context Protocol servers for documentation workflows
+
 ### 📚 Learning Resources
 - [Style Guides](./style-guides) - Documentation and writing style guides
 - [Reading List](./reading) - Articles and resources about documentation

docs/quality.md

@@ -77,4 +77,8 @@ Most quality assurance tools can be integrated into:
 - Regular audits of documentation quality
 - Track metrics over time
 - User feedback analysis
-- Tool effectiveness evaluation
+- Tool effectiveness evaluation
+
+## AI-Powered Review
+
+For AI-powered review tools, agent skills, and prompt templates for documentation review, see our [AI Review](/ai/review) section.

docs/style-guides.md

@@ -6,16 +6,18 @@ Comprehensive collection of documentation style guides and writing standards fro
 
 ### Government & Standards
 
-- [18F](https://content-guide.18f.gov/) - U.S. Digital Service content guide
-- [Federal (US) plain language guidelines](https://plainlanguage.gov/guidelines/) - Government plain language standards
-- [United Nations](https://www.un.org/dgacm/content/editorial-manual) - UN editorial manual
+<ResourceGrid>
+<EnhancedLink url="https://github.com/18F/guides" title="18F Guides" />
+<EnhancedLink url="https://plainlanguage.gov/guidelines" title="Plain Language Guide Series" />
+<EnhancedLink url="https://www.un.org/dgacm/content/editorial-manual" title="United Nations Editorial Manual" />
+</ResourceGrid>
 
 ### Web Standards & Accessibility
 
 <ResourceGrid>
-<EnhancedLink url="https://developer.mozilla.org/en-US/docs/Web/Accessibility" />
-<EnhancedLink url="https://www.w3.org/TR/WCAG21/" />
-<EnhancedLink url="https://www.accessible-social.com/quick-guide" />
+<EnhancedLink url="https://developer.mozilla.org/en-US/docs/Web/Accessibility" title="Accessibility | MDN" />
+<EnhancedLink url="https://www.w3.org/TR/WCAG21/" title="Web Content Accessibility Guidelines (WCAG) 2.1" />
+<EnhancedLink url="https://www.accessible-social.com/quick-guide" title="Accessible Social Quick Guide" />
 </ResourceGrid>
 
 ## Technology Companies
@@ -25,19 +27,19 @@ Comprehensive collection of documentation style guides and writing standards fro
 <ResourceGrid>
 <EnhancedLink url="https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide" title="GitHub Docs Style Guide" />
 <EnhancedLink url="https://docs.gitlab.com/ee/development/documentation/styleguide/" title="GitLab Style Guide" />
-<EnhancedLink url="https://developers.google.com/style/" />
-<EnhancedLink url="https://docs.microsoft.com/en-us/style-guide/welcome/" />
-<EnhancedLink url="https://redhat-documentation.github.io/" />
-<EnhancedLink url="https://stylepedia.net/" />
+<EnhancedLink url="https://developers.google.com/style/" title="Google Developer Documentation Style Guide" />
+<EnhancedLink url="https://docs.microsoft.com/en-us/style-guide/welcome/" title="Microsoft Writing Style Guide" />
+<EnhancedLink url="https://redhat-documentation.github.io/" title="Guidelines for Red Hat Documentation" />
+<EnhancedLink url="https://stylepedia.net/" title="Red Hat Style Guide" />
 </ResourceGrid>
 
 ### Cloud & Infrastructure
 
 <ResourceGrid>
-<EnhancedLink url="https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines" />
-<EnhancedLink url="https://www.linode.com/docs/linode-writers-formatting-guide/" />
-<EnhancedLink url="https://github.com/rackerlabs/docs-style-guide/tree/master/style-guide" />
-<EnhancedLink url="https://developer.salesforce.com/docs/atlas.en-us.salesforce_pubs_style_guide.meta/salesforce_pubs_style_guide/overview.htm" />
+<EnhancedLink url="https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines" title="DigitalOcean's Technical Writing Guidelines" />
+<EnhancedLink url="https://www.linode.com/docs/linode-writers-formatting-guide/" title="Linode Writer's Formatting Guide" />
+<EnhancedLink url="https://github.com/rackerlabs/docs-style-guide/tree/master/style-guide" title="Rackspace Style Guide for Technical Content" />
+<EnhancedLink url="https://developer.salesforce.com/docs/atlas.en-us.salesforce_pubs_style_guide.meta/salesforce_pubs_style_guide/overview.htm" title="Salesforce Style Guide" />
 </ResourceGrid>
 
 ### Database & Analytics
@@ -55,9 +57,9 @@ Comprehensive collection of documentation style guides and writing standards fro
 ### Technical Writing
 
 <ResourceGrid>
-<EnhancedLink url="https://clig.dev/" />
-<EnhancedLink url="https://github.com/lornajane/developer-style-guide" />
-<EnhancedLink url="https://www.markdownguide.org/" />
+<EnhancedLink url="https://clig.dev/" title="Command Line Interface Guidelines" />
+<EnhancedLink url="https://github.com/lornajane/developer-style-guide" title="Developer Style Guide" />
+<EnhancedLink url="https://www.markdownguide.org/" title="Markdown Guide" />
 </ResourceGrid>
 
 ### Content & Marketing

docs/tools.md

@@ -14,10 +14,10 @@ Specialized tools and resources that support documentation workflows across vari
 ### Browser Testing Tools
 
 <ResourceGrid>
-<EnhancedLink url="https://nightwatchjs.org/" />
-<EnhancedLink url="https://playwright.dev/" />
-<EnhancedLink url="https://github.com/GoogleChrome/puppeteer" />
-<EnhancedLink url="https://www.selenium.dev/" />
+<EnhancedLink url="https://nightwatchjs.org/" title="Nightwatch" />
+<EnhancedLink url="https://playwright.dev/" title="Playwright" />
+<EnhancedLink url="https://github.com/GoogleChrome/puppeteer" title="Puppeteer" />
+<EnhancedLink url="https://www.selenium.dev/" title="Selenium" />
 </ResourceGrid>
 
 ### Spelling & Language Tools
@@ -27,22 +27,22 @@ Specialized tools and resources that support documentation workflows across vari
 ## Accessibility Tools
 
 <ResourceGrid>
-<EnhancedLink url="https://github.com/dequelabs/axe-cli" />
-<EnhancedLink url="https://webaim.org/resources/contrastchecker/" />
-<EnhancedLink url="https://support.siteimprove.com/hc/en-gb/articles/115000013031-Accessibility-Image-Alt-text-best-practices" />
-<EnhancedLink url="https://github.com/JakePartusch/lumberjack" />
-<EnhancedLink url="https://pa11y.org/" />
+<EnhancedLink url="https://github.com/dequelabs/axe-cli" title="axe-cli" />
+<EnhancedLink url="https://webaim.org/resources/contrastchecker/" title="WebAIM Contrast Checker" />
+<EnhancedLink url="https://support.siteimprove.com/hc/en-gb/articles/115000013031-Accessibility-Image-Alt-text-best-practices" title="Accessibility: Image Alt Text Best Practices" />
+<EnhancedLink url="https://github.com/JakePartusch/lumberjack" title="Lumberjack" />
+<EnhancedLink url="https://pa11y.org/" title="Pa11y" />
 </ResourceGrid>
 
 ## Hosting & Deployment
 
 <ResourceGrid>
-<EnhancedLink url="https://www.doctave.com/" />
+<EnhancedLink url="https://www.doctave.com/" title="Doctave" />
 <EnhancedLink url="https://hashnode.com/" title="Docs by Hashnode" description="Documentation hosting platform by Hashnode" />
-<EnhancedLink url="https://www.gitbook.com/" />
-<EnhancedLink url="https://www.mintlify.com/" />
-<EnhancedLink url="https://www.netlify.com/" />
-<EnhancedLink url="https://readthedocs.org/" />
+<EnhancedLink url="https://www.gitbook.com/" title="GitBook" />
+<EnhancedLink url="https://www.mintlify.com/" title="Mintlify" />
+<EnhancedLink url="https://www.netlify.com/" title="Netlify" />
+<EnhancedLink url="https://readthedocs.org/" title="Read the Docs" />
 </ResourceGrid>
 
 ## Utility Tools

docs/writing.md

@@ -65,4 +65,7 @@ Tools and resources for improving technical writing, grammar, and content creati
 For accessibility-focused writing tools, see our [Quality Assurance](/quality) section.
 
 ### Content Validation
-For spell checking and content validation tools, see our [Quality Assurance](/quality) section.
+For spell checking and content validation tools, see our [Quality Assurance](/quality) section.
+
+### AI Writing Tools
+For AI-powered writing assistants, agent skills, and prompt templates for technical writing, see our [AI Writing](/ai/writing) section.

openspec/changes/add-ai-section/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-14

openspec/changes/add-ai-section/design.md

@@ -0,0 +1,67 @@
+## Context
+
+The Awesome Docs site is a VitePress-based curated list. Navigation and sidebar are defined in [`docs/.vitepress/config.mjs`](docs/.vitepress/config.mjs). Content pages are Markdown files under `docs/`. The site already uses `EnhancedLink` and `ResourceGrid` Vue components for rich link cards.
+
+Currently there is no AI-specific section. The only AI-related content is a single Grammarly entry in [`docs/writing.md`](docs/writing.md). MCP (Model Context Protocol) servers have no presence at all.
+
+The change adds four new Markdown pages under `docs/ai/`, updates the VitePress config, and adds cross-references from two existing pages.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create `docs/ai/` subdirectory with `index.md`, `writing.md`, `review.md`, and `mcp-servers.md`
+- Add a top-level **AI** nav item in `config.mjs` with three sub-items
+- Add an **AI** sidebar group in `config.mjs`
+- Add cross-reference links from `docs/writing.md` and `docs/quality.md` to the new AI pages
+- Update `docs/index.md` Categories Overview to list the new AI section
+- Populate each page with curated, relevant content following existing page conventions
+
+**Non-Goals:**
+- Moving or removing the Grammarly entry from `docs/writing.md` (cross-link only)
+- Adding MCP servers beyond the Vale MCP server in the initial implementation
+- Creating a new VitePress theme component or plugin
+- Automated link validation for the new pages (handled by existing CI)
+
+## Decisions
+
+### Decision 1: `docs/ai/` subdirectory over a single `docs/ai.md`
+
+**Chosen**: Subdirectory with four files (`index.md`, `writing.md`, `review.md`, `mcp-servers.md`)
+
+**Rationale**: Each topic (writing, review, MCP servers) is a distinct category that will grow independently. A subdirectory allows each to have its own nav entry, sidebar link, and URL. A single flat file would become unwieldy as content grows.
+
+**Alternative considered**: Single `docs/ai.md` — simpler to start but harder to split later without breaking URLs.
+
+### Decision 2: Cross-link from existing pages, not move content
+
+**Chosen**: Add a "See also" cross-reference in `docs/writing.md` and `docs/quality.md` pointing to the new AI pages.
+
+**Rationale**: Moving Grammarly would break the logical flow of `writing.md` (it's a browser extension, not exclusively an AI tool). Cross-linking preserves existing structure while connecting readers to the new section.
+
+**Alternative considered**: Move all AI-adjacent tools to `docs/ai/` — cleaner taxonomy but risks breaking reader expectations and existing bookmarks.
+
+### Decision 3: Top-level nav item for AI
+
+**Chosen**: Add `AI` as a new top-level nav item alongside `Tools` and `Resources`.
+
+**Rationale**: AI tooling is a first-class concern, not a subcategory of existing tools. A top-level item signals its importance and makes it discoverable.
+
+**Alternative considered**: Add AI as a sub-item under `Tools` — less visible, undersells the category.
+
+### Decision 4: Use plain Markdown lists for initial content (not `EnhancedLink`)
+
+**Chosen**: Plain Markdown links for the initial content entries.
+
+**Rationale**: `EnhancedLink` requires metadata fetching at build time. For a new section with potentially unstable URLs (especially MCP server repos), plain links are safer and faster to author. `EnhancedLink` can be adopted incrementally per the existing contributing guide.
+
+**Alternative considered**: Use `EnhancedLink` throughout — richer UX but adds build-time risk for new/unstable URLs.
+
+## Risks / Trade-offs
+
+- **MCP ecosystem immaturity** → The Vale MCP server and MCP in general are early-stage. Links may go stale quickly. Mitigation: note the experimental nature in the page intro; rely on community PRs to keep current.
+- **Content staleness for AI tools** → AI tooling moves fast. Mitigation: keep entries minimal (name + one-line description + link); avoid version-specific details.
+- **Nav crowding** → Adding a top-level AI item makes the nav bar wider. Mitigation: acceptable at current nav item count; revisit if more top-level items are added.
+
+## Open Questions
+
+- Should `docs/ai/index.md` be a full landing page with summaries of each sub-page, or a minimal redirect-style page? (Recommendation: full landing page, consistent with how other index pages work in the contributing section.)

openspec/changes/add-ai-section/proposal.md

@@ -0,0 +1,37 @@
+## Why
+
+AI tooling for technical writing and documentation review is evolving rapidly, and readers of Awesome Docs need a dedicated, structured place to discover AI writing assistants, agent skills/prompt templates, and MCP servers relevant to documentation workflows. The Vale MCP server in particular represents a new paradigm — connecting AI agents directly to prose linting — that has no home in the current docs.
+
+## What Changes
+
+- Add a new `docs/ai/` subdirectory with four pages: `index.md`, `writing.md`, `review.md`, and `mcp-servers.md`
+- Add an **AI** top-level nav group in the VitePress config with links to all three sub-pages
+- Add an **AI** sidebar group in the VitePress config
+- Add a cross-reference from `docs/writing.md` pointing to the new AI writing page
+- Add a cross-reference from `docs/quality.md` pointing to the new AI review page
+- Populate `docs/ai/writing.md` with AI writing assistants and agent skills/prompt resources for technical writing
+- Populate `docs/ai/review.md` with AI review tools and agent skills/prompt resources for documentation review
+- Populate `docs/ai/mcp-servers.md` with the Vale MCP server entry and a brief MCP introduction
+- Update `docs/index.md` Categories Overview to include the new AI section
+
+## Capabilities
+
+### New Capabilities
+
+- `ai-writing-page`: A curated page of AI writing assistants and agent skills/prompts for technical writing workflows
+- `ai-review-page`: A curated page of AI review tools and agent skills/prompts for documentation review workflows
+- `ai-mcp-servers-page`: A curated page of MCP servers relevant to documentation, starting with the Vale MCP server
+- `ai-section-nav`: VitePress navigation and sidebar entries for the new AI section
+
+### Modified Capabilities
+
+<!-- No existing spec-level capabilities are changing -->
+
+## Impact
+
+- `docs/.vitepress/config.mjs` — nav and sidebar updated
+- `docs/index.md` — Categories Overview section updated
+- `docs/writing.md` — cross-reference added
+- `docs/quality.md` — cross-reference added
+- New files: `docs/ai/index.md`, `docs/ai/writing.md`, `docs/ai/review.md`, `docs/ai/mcp-servers.md`
+- No breaking changes; all existing pages and URLs remain unchanged

openspec/changes/add-ai-section/specs/ai-mcp-servers-page/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: AI MCP servers page exists at /ai/mcp-servers
+The system SHALL provide a page at `docs/ai/mcp-servers.md` that is accessible via the URL `/ai/mcp-servers` in the VitePress site.
+
+#### Scenario: Page is accessible
+- **WHEN** a user navigates to `/ai/mcp-servers`
+- **THEN** the page renders without error and displays the MCP servers content
+
+### Requirement: MCP servers page includes a brief MCP introduction
+The page SHALL include a short introductory paragraph explaining what MCP (Model Context Protocol) is and why it is relevant to documentation workflows.
+
+#### Scenario: MCP introduction is present
+- **WHEN** a user views the MCP servers page
+- **THEN** they see an introductory section explaining MCP before any server listings
+
+### Requirement: MCP servers page lists the Vale MCP server
+The page SHALL include an entry for the Vale MCP server with a name, link to its repository or documentation, and a one-line description of what it enables.
+
+#### Scenario: Vale MCP server entry is present
+- **WHEN** a user views the MCP servers page
+- **THEN** they see an entry for the Vale MCP server with a working link and description
+
+### Requirement: MCP servers page signals openness for contributions
+The page SHALL include a note inviting contributors to add additional documentation-relevant MCP servers.
+
+#### Scenario: Contribution invitation is present
+- **WHEN** a user views the MCP servers page
+- **THEN** they see a note or call-to-action encouraging them to contribute additional MCP server entries

openspec/changes/add-ai-section/specs/ai-review-page/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: AI review page exists at /ai/review
+The system SHALL provide a page at `docs/ai/review.md` that is accessible via the URL `/ai/review` in the VitePress site.
+
+#### Scenario: Page is accessible
+- **WHEN** a user navigates to `/ai/review`
+- **THEN** the page renders without error and displays the AI review content
+
+### Requirement: AI review page contains AI review tools section
+The page SHALL include a section listing AI-powered tools for reviewing documentation, with each entry containing a name, link, and one-line description.
+
+#### Scenario: Review tools section is present
+- **WHEN** a user views the AI review page
+- **THEN** they see a section titled "AI Review Tools" with at least one tool entry
+
+### Requirement: AI review page contains agent skills and prompts section for review
+The page SHALL include a section covering agent skills, system prompts, and prompt templates for documentation review workflows.
+
+#### Scenario: Agent skills for review section is present
+- **WHEN** a user views the AI review page
+- **THEN** they see a section covering AI agent skills or prompt resources for documentation review
+
+### Requirement: AI review page cross-references quality assurance tools
+The page SHALL include a note or link directing readers to the Quality Assurance page for non-AI review and linting tools.
+
+#### Scenario: Cross-reference to quality assurance is present
+- **WHEN** a user views the AI review page
+- **THEN** they see a reference or link to `/quality` for broader quality assurance tool coverage

openspec/changes/add-ai-section/specs/ai-section-nav/spec.md

@@ -0,0 +1,36 @@
+## ADDED Requirements
+
+### Requirement: AI top-level nav item exists in VitePress config
+The VitePress config SHALL include a top-level nav item labelled "AI" with sub-items linking to `/ai/writing`, `/ai/review`, and `/ai/mcp-servers`.
+
+#### Scenario: AI nav item is present with sub-items
+- **WHEN** a user views any page on the site
+- **THEN** the top navigation bar contains an "AI" item that expands to show "AI Writing", "AI Review", and "MCP Servers" links
+
+### Requirement: AI sidebar group exists in VitePress config
+The VitePress config SHALL include a sidebar group labelled "AI" containing links to `/ai/`, `/ai/writing`, `/ai/review`, and `/ai/mcp-servers`.
+
+#### Scenario: AI sidebar group is present
+- **WHEN** a user views any page on the site
+- **THEN** the sidebar contains an "AI" group with four entries: Overview, Writing, Review, and MCP Servers
+
+### Requirement: docs/index.md Categories Overview includes AI section
+The `docs/index.md` Categories Overview section SHALL include a reference to the new AI section with a link to `/ai/`.
+
+#### Scenario: AI section appears in index categories
+- **WHEN** a user views the home page
+- **THEN** the Categories Overview section lists the AI section with a link
+
+### Requirement: docs/writing.md cross-references AI writing page
+The `docs/writing.md` page SHALL include a "See also" or equivalent cross-reference linking to `/ai/writing` for AI-specific writing tools.
+
+#### Scenario: Cross-reference to AI writing is present in writing.md
+- **WHEN** a user views the Writing Tools page
+- **THEN** they see a reference directing them to the AI Writing page for AI-specific tools
+
+### Requirement: docs/quality.md cross-references AI review page
+The `docs/quality.md` page SHALL include a "See also" or equivalent cross-reference linking to `/ai/review` for AI-specific review tools.
+
+#### Scenario: Cross-reference to AI review is present in quality.md
+- **WHEN** a user views the Quality Assurance page
+- **THEN** they see a reference directing them to the AI Review page for AI-specific review tools

openspec/changes/add-ai-section/specs/ai-writing-page/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: AI writing page exists at /ai/writing
+The system SHALL provide a page at `docs/ai/writing.md` that is accessible via the URL `/ai/writing` in the VitePress site.
+
+#### Scenario: Page is accessible
+- **WHEN** a user navigates to `/ai/writing`
+- **THEN** the page renders without error and displays the AI writing content
+
+### Requirement: AI writing page contains AI writing assistants section
+The page SHALL include a section listing AI-powered writing assistant tools relevant to technical writing, with each entry containing a name, link, and one-line description.
+
+#### Scenario: Writing assistants section is present
+- **WHEN** a user views the AI writing page
+- **THEN** they see a section titled "AI Writing Assistants" with at least one tool entry
+
+### Requirement: AI writing page contains agent skills and prompts section
+The page SHALL include a section covering agent skills, system prompts, and prompt templates for technical writing workflows.
+
+#### Scenario: Agent skills section is present
+- **WHEN** a user views the AI writing page
+- **THEN** they see a section covering AI agent skills or prompt resources for technical writing
+
+### Requirement: AI writing page cross-references existing writing tools
+The page SHALL include a note or link directing readers to the main Writing Tools page for non-AI writing tools.
+
+#### Scenario: Cross-reference to writing tools is present
+- **WHEN** a user views the AI writing page
+- **THEN** they see a reference or link to `/writing` for broader writing tool coverage

openspec/changes/add-ai-section/tasks.md

@@ -0,0 +1,24 @@
+## 1. VitePress Config Updates
+
+- [x] 1.1 Add "AI" top-level nav item to `docs/.vitepress/config.mjs` with sub-items: AI Writing (`/ai/writing`), AI Review (`/ai/review`), MCP Servers (`/ai/mcp-servers`)
+- [x] 1.2 Add "AI" sidebar group to `docs/.vitepress/config.mjs` with entries: Overview (`/ai/`), Writing (`/ai/writing`), Review (`/ai/review`), MCP Servers (`/ai/mcp-servers`)
+
+## 2. AI Section Pages
+
+- [x] 2.1 Create `docs/ai/index.md` — landing page with overview of all three sub-pages and brief descriptions of each area
+- [x] 2.2 Create `docs/ai/writing.md` — AI writing assistants section and agent skills/prompts section for technical writing
+- [x] 2.3 Create `docs/ai/review.md` — AI review tools section and agent skills/prompts section for documentation review
+- [x] 2.4 Create `docs/ai/mcp-servers.md` — MCP introduction, Vale MCP server entry, and contribution invitation
+
+## 3. Cross-References in Existing Pages
+
+- [x] 3.1 Add cross-reference in `docs/writing.md` pointing to `/ai/writing` for AI-specific writing tools
+- [x] 3.2 Add cross-reference in `docs/quality.md` pointing to `/ai/review` for AI-specific review tools
+- [x] 3.3 Add AI section entry to the Categories Overview in `docs/index.md`
+
+## 4. Verification
+
+- [x] 4.1 Run `pnpm docs:dev` and verify all four AI pages render correctly
+- [x] 4.2 Verify the AI nav item and sidebar group appear and all links resolve
+- [x] 4.3 Verify cross-references in `docs/writing.md` and `docs/quality.md` link correctly
+- [x] 4.4 Verify `docs/index.md` Categories Overview includes the AI section link

openspec/changes/fix-enhanced-link-search-indexing/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-14

openspec/changes/fix-enhanced-link-search-indexing/design.md

@@ -0,0 +1,54 @@
+## Context
+
+VitePress's built-in local search works by indexing the **static markdown source** of each page at build time. It does not execute Vue components or fetch runtime data.
+
+`<EnhancedLink>` components that omit the `title` prop display their link title by fetching metadata from `/cache/link-metadata.json` in the browser at runtime. Because the search indexer never sees this fetched title, those links are invisible to search — searching for "GitLab Style Guide", "Google Developer Documentation Style Guide", etc. returns no results even though those pages exist.
+
+The metadata cache (`docs/.vitepress/cache/link-metadata.json`) already contains the correct titles for all URLs — it is populated at build time by the `linkMetadataPlugin`. The titles are available; they just aren't written into the markdown source.
+
+**Affected files (EnhancedLink usages without `title`):**
+- `docs/style-guides.md` — multiple `<ResourceGrid>` blocks
+- `docs/tools.md` — multiple `<ResourceGrid>` blocks
+- `docs/contributing/enhanced-links.md` — example usages (documentation page)
+
+## Goals / Non-Goals
+
+**Goals:**
+- Every `<EnhancedLink>` in the docs has an explicit `title` prop so VitePress search can index it.
+- Titles are sourced from the existing metadata cache — no new network requests.
+- The fix is purely in markdown content files; no component or plugin code changes.
+
+**Non-Goals:**
+- Changing the `EnhancedLink` component's runtime behaviour.
+- Modifying the metadata fetch/cache pipeline.
+- Adding search indexing for `description` or other metadata fields (out of scope).
+- Fixing the example usages in `docs/contributing/enhanced-links.md` — those are intentional illustrations of the component API and should remain as-is.
+
+## Decisions
+
+### Decision 1: Add `title` props to markdown source (not a build-time transform)
+
+**Chosen:** Manually add `title="..."` to each `<EnhancedLink>` in the markdown files, using the metadata cache as the source of truth.
+
+**Alternatives considered:**
+- *VitePress search `_render` hook*: Could transform component markup into indexable text at search-index build time. More complex, requires ongoing maintenance, and is fragile against VitePress upgrades.
+- *Markdown-it plugin to inject titles*: Would auto-populate titles from the cache during the markdown parse phase. Adds build complexity and makes the markdown source less readable/auditable.
+- *Always require `title` prop (lint rule)*: Good long-term hygiene but doesn't fix existing content.
+
+**Rationale:** Explicit `title` props in the markdown source are the simplest, most transparent, and most maintainable solution. The markdown becomes self-documenting, the search index is correct, and no tooling changes are needed.
+
+### Decision 2: Source titles from the metadata cache
+
+**Chosen:** Read `docs/.vitepress/cache/link-metadata.json` to get the canonical title for each URL.
+
+**Rationale:** The cache is already populated and authoritative. Using it avoids any new network requests and ensures consistency between what the card displays at runtime and what the search index contains.
+
+### Decision 3: Use the page `<title>` metadata value, trimmed if needed
+
+Some cached titles are verbose (e.g., `"Fast and reliable end-to-end testing for modern web apps | Playwright"`). For the `title` prop, use a human-readable short form (the part before ` | ` or ` - ` where appropriate) to keep the markdown readable and the search results clean.
+
+## Risks / Trade-offs
+
+- **Cache staleness** → If a linked site changes its page title, the `title` prop in markdown will drift from the fetched metadata. Mitigation: the `title` prop is the authoritative display value; the cache is only used as the initial source. Periodic audits can catch drift.
+- **Manual effort** → There are ~30 `<EnhancedLink>` usages to update across 2-3 files. Low risk of error given the small scope.
+- **Contributing docs examples** → The `docs/contributing/enhanced-links.md` page intentionally shows `<EnhancedLink>` without `title` as a usage example. These should NOT be changed, as they demonstrate the component's auto-fetch capability.

openspec/changes/fix-enhanced-link-search-indexing/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+`<EnhancedLink>` components that omit the `title` prop display their link title by fetching metadata at runtime in the browser. VitePress's built-in local search indexes only the static markdown source, so those links have no searchable text — searching for "GitLab Style Guide" (or any other title that comes from fetched metadata) returns zero results. Adding explicit `title` props to every `<EnhancedLink>` in the docs gives the search indexer the text it needs.
+
+## What Changes
+
+- Add a `title` prop to every `<EnhancedLink>` usage that currently omits it across all markdown pages.
+- Titles are sourced from the already-populated metadata cache (`docs/.vitepress/cache/link-metadata.json`) so no new network requests are needed.
+- No changes to the `EnhancedLink` component, the metadata plugin, or the VitePress config.
+
+## Capabilities
+
+### New Capabilities
+
+- `enhanced-link-title-audit`: Audit all markdown files for `<EnhancedLink>` usages missing a `title` prop and populate them from the metadata cache.
+
+### Modified Capabilities
+
+<!-- No existing spec-level requirements are changing. -->
+
+## Impact
+
+- All markdown files under `docs/` that use `<EnhancedLink>` without a `title` prop.
+- The metadata cache (`docs/.vitepress/cache/link-metadata.json`) is read-only for this change (used as the source of truth for titles).
+- No runtime or build-pipeline code changes required.

openspec/changes/fix-enhanced-link-search-indexing/specs/enhanced-link-title-audit/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: All EnhancedLink usages in content pages have an explicit title prop
+Every `<EnhancedLink>` component used in documentation content pages (i.e., pages under `docs/` that are not the contributing/enhanced-links.md documentation page) SHALL include a `title` prop with a human-readable name for the linked resource.
+
+#### Scenario: EnhancedLink with title is indexed by search
+- **WHEN** a user searches for the title of a linked resource (e.g., "GitLab Style Guide")
+- **THEN** the search results SHALL include the page containing the `<EnhancedLink>` for that resource
+
+#### Scenario: EnhancedLink without title is not present in content pages
+- **WHEN** a content page under `docs/` (excluding `docs/contributing/enhanced-links.md`) contains a `<EnhancedLink>` component
+- **THEN** the component SHALL have a non-empty `title` prop
+
+### Requirement: Titles are sourced from the metadata cache
+When populating missing `title` props, the title value SHALL be derived from the `title` field in `docs/.vitepress/cache/link-metadata.json` for the corresponding URL.
+
+#### Scenario: Title matches cached metadata
+- **WHEN** a `title` prop is added to an `<EnhancedLink>` for a URL that exists in the metadata cache
+- **THEN** the title SHALL match the cached `metadata.title` value (or a human-readable shortened form of it, e.g., stripping ` | Site Name` suffixes)
+
+#### Scenario: URL not in cache falls back to hostname
+- **WHEN** a `title` prop is added to an `<EnhancedLink>` for a URL that does NOT exist in the metadata cache
+- **THEN** the title SHALL use the URL's hostname as a fallback (e.g., `"stylepedia.net"`)
+
+### Requirement: Contributing documentation examples are exempt
+The `<EnhancedLink>` usages in `docs/contributing/enhanced-links.md` are intentional API examples and SHALL NOT be required to have a `title` prop.
+
+#### Scenario: Contributing page examples remain unchanged
+- **WHEN** reviewing `docs/contributing/enhanced-links.md`
+- **THEN** `<EnhancedLink>` usages without `title` props SHALL be left as-is to preserve their illustrative purpose

openspec/changes/fix-enhanced-link-search-indexing/tasks.md

@@ -0,0 +1,49 @@
+## 1. Audit EnhancedLink usages
+
+- [x] 1.1 Identify all `<EnhancedLink>` usages without a `title` prop in `docs/style-guides.md`
+- [x] 1.2 Identify all `<EnhancedLink>` usages without a `title` prop in `docs/tools.md`
+- [x] 1.3 Cross-reference each URL against `docs/.vitepress/cache/link-metadata.json` to get the canonical title
+
+## 2. Update docs/style-guides.md
+
+- [x] 2.1 Add `title` prop to `<EnhancedLink url="https://github.com/18F/guides" />` (Government & Standards section)
+- [x] 2.2 Add `title` prop to `<EnhancedLink url="https://plainlanguage.gov/guidelines" />` (Government & Standards section)
+- [x] 2.3 Add `title` prop to `<EnhancedLink url="https://www.un.org/dgacm/content/editorial-manual" />` (Government & Standards section)
+- [x] 2.4 Add `title` prop to `<EnhancedLink url="https://developer.mozilla.org/en-US/docs/Web/Accessibility" />` (Web Standards & Accessibility section)
+- [x] 2.5 Add `title` prop to `<EnhancedLink url="https://www.w3.org/TR/WCAG21/" />` (Web Standards & Accessibility section)
+- [x] 2.6 Add `title` prop to `<EnhancedLink url="https://www.accessible-social.com/quick-guide" />` (Web Standards & Accessibility section)
+- [x] 2.7 Add `title` prop to `<EnhancedLink url="https://developers.google.com/style/" />` (Developer-Focused section)
+- [x] 2.8 Add `title` prop to `<EnhancedLink url="https://docs.microsoft.com/en-us/style-guide/welcome/" />` (Developer-Focused section)
+- [x] 2.9 Add `title` prop to `<EnhancedLink url="https://redhat-documentation.github.io/" />` (Developer-Focused section)
+- [x] 2.10 Add `title` prop to `<EnhancedLink url="https://stylepedia.net/" />` (Developer-Focused section)
+- [x] 2.11 Add `title` prop to `<EnhancedLink url="https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines" />` (Cloud & Infrastructure section)
+- [x] 2.12 Add `title` prop to `<EnhancedLink url="https://www.linode.com/docs/linode-writers-formatting-guide/" />` (Cloud & Infrastructure section)
+- [x] 2.13 Add `title` prop to `<EnhancedLink url="https://github.com/rackerlabs/docs-style-guide/tree/master/style-guide" />` (Cloud & Infrastructure section)
+- [x] 2.14 Add `title` prop to `<EnhancedLink url="https://developer.salesforce.com/docs/atlas.en-us.salesforce_pubs_style_guide.meta/salesforce_pubs_style_guide/overview.htm" />` (Cloud & Infrastructure section)
+- [x] 2.15 Add `title` prop to `<EnhancedLink url="https://clig.dev/" />` (Technical Writing section)
+- [x] 2.16 Add `title` prop to `<EnhancedLink url="https://github.com/lornajane/developer-style-guide" />` (Technical Writing section)
+- [x] 2.17 Add `title` prop to `<EnhancedLink url="https://www.markdownguide.org/" />` (Technical Writing section)
+
+## 3. Update docs/tools.md
+
+- [x] 3.1 Add `title` prop to `<EnhancedLink url="https://nightwatchjs.org/" />` (Testing section)
+- [x] 3.2 Add `title` prop to `<EnhancedLink url="https://playwright.dev/" />` (Testing section)
+- [x] 3.3 Add `title` prop to `<EnhancedLink url="https://github.com/GoogleChrome/puppeteer" />` (Testing section)
+- [x] 3.4 Add `title` prop to `<EnhancedLink url="https://www.selenium.dev/" />` (Testing section)
+- [x] 3.5 Add `title` prop to `<EnhancedLink url="https://github.com/dequelabs/axe-cli" />` (Accessibility section)
+- [x] 3.6 Add `title` prop to `<EnhancedLink url="https://webaim.org/resources/contrastchecker/" />` (Accessibility section)
+- [x] 3.7 Add `title` prop to `<EnhancedLink url="https://support.siteimprove.com/hc/en-gb/articles/115000013031-Accessibility-Image-Alt-text-best-practices" />` (Accessibility section)
+- [x] 3.8 Add `title` prop to `<EnhancedLink url="https://github.com/JakePartusch/lumberjack" />` (Accessibility section)
+- [x] 3.9 Add `title` prop to `<EnhancedLink url="https://pa11y.org/" />` (Accessibility section)
+- [x] 3.10 Add `title` prop to `<EnhancedLink url="https://www.doctave.com/" />` (Hosting section)
+- [x] 3.11 Add `title` prop to `<EnhancedLink url="https://www.gitbook.com/" />` (Hosting section)
+- [x] 3.12 Add `title` prop to `<EnhancedLink url="https://www.mintlify.com/" />` (Hosting section)
+- [x] 3.13 Add `title` prop to `<EnhancedLink url="https://www.netlify.com/" />` (Hosting section)
+- [x] 3.14 Add `title` prop to `<EnhancedLink url="https://readthedocs.org/" />` (Hosting section)
+
+## 4. Verify
+
+- [x] 4.1 Confirm no `<EnhancedLink>` without `title` remains in `docs/style-guides.md` (excluding contributing docs)
+- [x] 4.2 Confirm no `<EnhancedLink>` without `title` remains in `docs/tools.md`
+- [x] 4.3 Run a local VitePress build (`npm run docs:build`) and verify search returns results for "GitLab Style Guide", "Google Developer Documentation Style Guide", and "Playwright"
+- [x] 4.4 Confirm `docs/contributing/enhanced-links.md` examples are unchanged