Refactored documentation to make it AI and human friendly.

.vortex/docs/CLAUDE.md

@@ -0,0 +1,60 @@
+# Documentation System Guide
+
+## Overview
+
+Docusaurus-based documentation website published to https://www.vortextemplate.com
+
+**Technology**: Docusaurus, React, MDX, Jest, cspell
+
+## Commands
+
+```bash
+cd .vortex/docs
+
+yarn install      # Install dependencies
+yarn start        # Development server
+yarn build        # Production build
+yarn test         # Run Jest tests
+yarn spellcheck   # American English validation
+yarn lint         # Code quality checks
+yarn lint-fix     # Auto-fix issues
+```
+
+## Key Directories
+
+```
+docs/
+├── content/           # MDX documentation pages
+├── src/components/    # React components
+├── tests/unit/        # Jest tests
+├── sidebars.js        # Sidebar configuration
+└── docusaurus.config.js
+```
+
+## Writing Guidelines
+
+- **American English** spelling throughout
+- **Sentence case** for headings (capitalize only first letter + proper nouns)
+- Proper nouns: Vortex, GitHub, Drupal, Docker Compose, CircleCI
+- Acronyms: CI/CD, SSH, API, BDD, PHPUnit
+
+## Sidebar Configuration
+
+Categories defined in `sidebars.js`. For subdirectories:
+- Category label from explicit definition or directory name
+- Use `sidebar_label: Overview` in README.mdx for first item
+
+## Troubleshooting
+
+```bash
+# Build failures
+yarn build --verbose
+
+# Spellcheck failures
+yarn spellcheck
+npx cspell "content/**/*.md"
+
+# Test failures
+yarn test --verbose
+yarn test --updateSnapshot
+```

.vortex/docs/content/contributing/maintenance/documentation.mdx

@@ -2,17 +2,25 @@
 
 There are 2 types of the documentation that **Vortex** provides:
 
-1. This Documentation of **Vortex** that is then deployed
-   to https://www.vortextemplate.com/docs/
-2. Consumer site documentation that is distributed when **Vortex** is
-   installed.
+1. **Vortex template documentation** (this site) - Generic information on
+   **how** to perform operations, applicable to all projects built with Vortex.
+   Deployed to https://www.vortextemplate.com/docs/
+2. **Per-project documentation** - Project-specific information on **what** the
+   project does, distributed in the `docs/` directory when Vortex is installed.
+
+The key relationship: per-project documentation describes **what** (coding
+standards, testing requirements, release configuration) while referencing the
+Vortex documentation for **how** to perform specific operations.
 
 ## www.vortextemplate.com
 
-The Documentation (this site) is written in Markdown and located in
-[`.vortex/docs`](https://github.com/drevops/vortex/blob/main/.vortex/docs) directory. This is
-removed when you install **Vortex** for a
-consumer site.
+This documentation provides generic "how-to" guides suitable for any project
+using the Vortex template. It covers workflows, tooling, and operations that
+are common across all Vortex-based projects.
+
+The source is written in Markdown and located in
+[`.vortex/docs`](https://github.com/drevops/vortex/blob/main/.vortex/docs)
+directory. This is removed when you install **Vortex** for a consumer site.
 
 ### Local build
 
@@ -59,3 +67,16 @@ An automated continuous integration build publishes this documentation.
 After **Vortex** is installed into the consumer site, these docs are
 intended to be used by the site maintainers and stay up-to-date with the
 project changes.
+
+This documentation describes the **what** for the project:
+
+- Coding standards and agreements specific to the project
+- Testing requirements and configuration
+- Release and deployment configuration
+- Project-specific workflows and decisions
+
+When describing **how** to perform an operation, per-project documentation
+should reference the relevant page on https://www.vortextemplate.com/docs/
+rather than duplicating instructions. This keeps project docs focused on
+decisions and configuration while leveraging the maintained Vortex
+documentation for operational details.

.vortex/docs/content/tools/README.mdx

@@ -36,4 +36,3 @@ Head over to the tool-specific documentation to learn more.
 | [Rector](rector.mdx)               | Instant Upgrades and Automated Refactoring                                              |
 | [Renovate](renovate.mdx)           | A bot for automated dependency updates                                                  |
 | [Twig CS Fixer](twig-cs-fixer.mdx) | Checkstyle for Twig                                                                     |
-| [Xdebug](xdebug.mdx)               | Debugger and Profiler Tool for PHP                                                      |

.vortex/docs/content/workflows/README.mdx

@@ -14,15 +14,13 @@ detailed documentation on specific workflows.
 
 ## Available workflows
 
-- [Development](development)
-- [Testing](testing)
-- [Deployment](deployment)
-- [Notifications](notifications)
-- [Releasing](releasing)
-- [Configuration Variables](variables)
-- [Updating Vortex](updating-vortex)
-
-Refer to the linked sections for detailed instructions.
+- [Development](development/) - Local development workflow, database operations, debugging
+- [Testing](testing/) - PHPUnit and Behat testing
+- [Deployment](deployment) - Deploying to remote environments
+- [Releasing](releasing/) - GitFlow workflow and versioning
+- [Notifications](notifications/) - Deployment notifications via multiple channels
+- [Configuration Variables](variables) - Environment variables reference
+- [Updating Vortex](updating-vortex) - Keeping your project up to date
 
 ## Complete code lifecycle
 

.vortex/docs/content/workflows/deployment.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Deployment