docs: comprehensive documentation updates and improvements

.codewhisperer/settings.json

@@ -0,0 +1,9 @@
+{
+    "customizations": [
+        {
+            "name": "CouchCMS Documentation Standards",
+            "description": "Documentation writing standards for CouchCMS",
+            "instructions": "# CouchCMS Documentation Standards\n# Auto-generated from DOCS-STANDARDS.md\n\n**Critical: Always follow these documentation standards.**\n\n## Project Context\n\n- **Project**: CouchCMS Documentation\n- **Type**: Technical Documentation\n- **Platform**: Astro + Starlight\n- **Content Format**: MDX (Markdown + JSX)\n- **Standards**: English-only, 4-space indentation, WCAG 2.1 AA\n\n## Core Principles\n\n1. **Single Source of Truth**: STYLEGUIDE.md is authoritative\n2. **Consistency First**: All documentation follows identical patterns\n3. **Accessibility**: WCAG 2.1 AA compliance mandatory\n4. **English Only**: All content, code, and comments in English\n5. **Semantic Structure**: Proper heading hierarchy and HTML5\n\n## Essential Formatting Rules\n\n### Frontmatter (Required)\nEvery MDX file must start with:\n```yaml\n---\ntitle: [50-60 chars, include keyword]\ndescription: \"[150-160 chars]\"\nkeywords: [keyword1, keyword2, keyword3]\ncategory: [category]\nauthor: [Author Name]\nlastUpdated: YYYY-MM-DD\nsidebar:\n  order: [number]\n---\n```\n\n### Text Formatting\n\n**Product Names:**\n- Regular: \"Couch\"\n- Formal: \"CouchCMS\"\n- Never bold (except headers)\n\n**Technical Terms (backticks):**\n- Files: `config.php`, `.htaccess`\n- Variables: `my_variable`\n- Code: `echo $value`\n- Booleans: `true`, `false`\n\n**UI Elements (bold):**\n- Pages: **About Us**\n- Buttons: **Save Changes**\n- Use Title Case\n\n**Tag References:**\n```markdown\n[**editable**](../../tags-reference/core/editable/)\n```\n\n**Documentation Links:**\n```markdown\n[**Working with Templates**](../../concepts/templates/)\n```\n\n### Code Blocks\n\nAlways include descriptive titles:\n````markdown\n```php title=\"config.php\"\n<?php\n// Code here\n?>\n```\n````\n\n### Components\n\n**Steps:**\n```markdown\nimport { Steps } from \"@astrojs/starlight/components\";\n\n<Steps>\n\n1. First step\n2. Second step\n\n</Steps>\n```\n\n**Card:**\n```markdown\n<Card icon=\"info\" title=\"Title\">\n\nContent\n\n</Card>\n```\n\n**FileTree (NO backticks!):**\n```markdown\n<FileTree>\n- src/\n  - content/\n</FileTree>\n```\n\n### Links\n\n- Internal links: ALWAYS use trailing slashes\n- Meaningful text (no \"click here\")\n- Relative paths for internal content\n\n### Admonitions\n\n```markdown\n:::note[Context]\nInformation\n:::\n\n:::tip[Best Practice]\nRecommendation\n:::\n\n:::caution[Important]\nLimitation\n:::\n\n:::danger[Warning]\nCritical warning\n:::\n```\n\n## Quality Checklist\n\nBefore finalizing documentation:\n- ✅ Valid frontmatter with SEO metadata\n- ✅ Proper heading hierarchy (no skipping)\n- ✅ Technical terms in backticks\n- ✅ UI elements in bold\n- ✅ Links with trailing slashes\n- ✅ Code blocks with titles\n- ✅ Complete examples\n- ✅ Image alt text\n- ✅ WCAG 2.1 AA compliance\n\n## AI Tools Available\n\n### Automated (Auto-Applied)\n- `.cursor/rules/markdown.mdc` - Formatting rules\n- `.cursor/rules/content-structure.mdc` - Content organization\n- `.cursor/rules/component-architecture.mdc` - Components\n\n### Manual (Explicit Use)\n- `@.cursor/prompts/convert-to-markdown.md` - Convert content\n- `@.cursor/prompts/markdown-quick-reference.md` - Quick syntax\n\n### Reference Documentation\n- **AI-TOOLKIT.md** - Complete toolkit guide\n- **STYLEGUIDE.md** - Full formatting rules\n- **.cursor/README.md** - Detailed documentation\n\n## Common Patterns\n\n### Introducing CMS Tags\n```markdown\nThe [**editable**](../../tags-reference/core/editable/) tag creates regions.\n\n## Basic Usage\n\n```php title=\"example.php\"\n<cms:editable name='content' type='text' />\n```\n\n:::tip[Best Practice]\nUse descriptive names.\n:::\n```\n\n### Cross-References\n```markdown\nSee [**Working with Templates**](../../concepts/templates/).\n```\n\n### Version Info\n```markdown\n:::version[v2.0+]\nRequires CouchCMS v2.0 or higher.\n:::\n```\n\n## Error Prevention\n\n**Never:**\n- ❌ Use non-English language\n- ❌ Skip frontmatter\n- ❌ Incorrect heading hierarchy\n- ❌ Omit code block titles\n- ❌ Forget trailing slashes\n\n**Always:**\n- ✅ Complete frontmatter\n- ✅ Proper heading hierarchy\n- ✅ Descriptive code titles\n- ✅ Trailing slashes in links\n- ✅ Correct tag formatting\n\n---\n\n**For complete rules, see STYLEGUIDE.md**\n**For conversion help, use @.cursor/prompts/convert-to-markdown.md**\n**Generated from DOCS-STANDARDS.md - Last updated: 2025-11-26**\n"
+        }
+    ]
+}

.cursor/AI-CONFIG-INDEX.md

@@ -0,0 +1,42 @@
+# AI Configuration Index
+# Auto-generated from DOCS-STANDARDS.md
+
+All AI editor configurations are automatically generated from **DOCS-STANDARDS.md**.
+
+## Generated Files
+
+### AI Assistants
+- ✅ `.cursorrules` - Cursor AI configuration
+- ✅ `CLAUDE.md` - Claude AI instructions
+- ✅ `.windsurfrules` - Windsurf AI configuration
+- ✅ `.github/copilot-instructions.md` - GitHub Copilot
+- ✅ `.tabnine/settings.json` - Tabnine configuration
+- ✅ `.codewhisperer/settings.json` - Amazon CodeWhisperer
+
+### Editors
+- ✅ `.vscode/settings.json` - VS Code settings
+- ✅ `.editorconfig` - Universal editor config
+
+## Single Source of Truth
+
+**DOCS-STANDARDS.md** → All configurations above
+
+To update all AI configurations:
+```bash
+bun run sync
+```
+
+## Manual Tools
+
+These files are maintained manually:
+- `.cursor/rules/*.mdc` - Auto-applied formatting rules
+- `.cursor/prompts/*.md` - AI assistance prompts
+- `STYLEGUIDE.md` - Complete style guide
+
+## Last Sync
+
+Generated: 2025-11-26T17:19:28.784Z
+
+---
+
+**Never edit generated files directly. Edit DOCS-STANDARDS.md and run `bun run sync`.**

.cursor/INDEX.md

@@ -0,0 +1,264 @@
+# CouchCMS Documentation - AI Toolkit Index
+
+Complete overview of all AI assistance tools for documentation development.
+
+## 🎯 Quick Access
+
+| Need | File | Use |
+|------|------|-----|
+| **Start Here** | [QUICKSTART.md](.cursor/QUICKSTART.md) | 30-second guide |
+| **Complete Guide** | [README.md](.cursor/README.md) | Full toolkit documentation |
+| **Convert Content** | [convert-to-markdown.md](.cursor/prompts/convert-to-markdown.md) | Content conversion |
+| **Format Reference** | [markdown-quick-reference.md](.cursor/prompts/markdown-quick-reference.md) | Syntax lookup |
+| **Style Rules** | [STYLEGUIDE.md](../STYLEGUIDE.md) | Complete formatting guide |
+
+## 📂 Directory Structure
+
+```
+.cursor/
+├── README.md                    # Complete AI toolkit guide
+├── QUICKSTART.md               # 30-second start guide
+├── INDEX.md                    # This file - complete overview
+│
+├── rules/                      # Auto-applied formatting rules
+│   ├── markdown.mdc           # Complete formatting rules (auto-applied)
+│   ├── content-structure.mdc  # Content organization patterns
+│   └── component-architecture.mdc  # Component usage rules
+│
+└── prompts/                    # AI assistance prompts
+    ├── README.md              # Prompt usage guide
+    ├── convert-to-markdown.md # Content conversion prompt
+    └── markdown-quick-reference.md  # Quick formatting reference
+```
+
+## 🤖 Automated Rules (Auto-Applied)
+
+These rules automatically apply when you edit markdown files:
+
+### 1. markdown.mdc
+**Auto-applies to:** All `.md` and `.mdx` files
+**Coverage:** Complete formatting rules from STYLEGUIDE.md
+**Purpose:** Ensures consistent documentation quality
+
+### 2. content-structure.mdc
+**Auto-applies to:** Content collections and layouts
+**Coverage:** Documentation hierarchy and navigation
+**Purpose:** Maintains logical content organization
+
+### 3. component-architecture.mdc
+**Auto-applies to:** Component files and MDX
+**Coverage:** Astro/Starlight component patterns
+**Purpose:** Consistent component usage
+
+## 🛠️ AI Prompts (Manual Use)
+
+Use these prompts explicitly when needed:
+
+### 1. convert-to-markdown.md
+**Use for:**
+- Converting any content to CouchCMS markdown format
+- Creating new documentation pages from scratch
+- Ensuring style guide compliance
+
+**How to use:**
+```markdown
+@.cursor/prompts/convert-to-markdown.md
+
+Convert this content about [topic]:
+[Your content]
+```
+
+### 2. markdown-quick-reference.md
+**Use for:**
+- Quick syntax lookups
+- Format pattern reference
+- Validation examples
+
+**How to use:**
+```markdown
+@.cursor/prompts/markdown-quick-reference.md
+
+How do I format [element]?
+```
+
+## 📖 Reference Documentation
+
+### 1. STYLEGUIDE.md (Root)
+**Location:** `../STYLEGUIDE.md`
+**Purpose:** Authoritative source for all formatting rules
+**Coverage:**
+- Document organization
+- Content guidelines
+- Technical standards
+- Quality requirements
+- Common patterns
+
+### 2. Prompts README
+**Location:** `.cursor/prompts/README.md`
+**Purpose:** Detailed guide for using AI prompts
+**Coverage:**
+- Workflow recommendations
+- Use case examples
+- Best practices
+- Quality assurance
+
+## 🎯 Common Workflows
+
+### Workflow 1: Converting Existing Content
+
+1. **Gather** source content (HTML, text, notes)
+2. **Use** convert-to-markdown.md prompt
+3. **Review** generated markdown
+4. **Refine** if needed (auto-rules maintain consistency)
+
+### Workflow 2: Creating New Documentation
+
+1. **Plan** structure and sections
+2. **Use** convert-to-markdown.md to scaffold
+3. **Write** content (auto-rules enforce formatting)
+4. **Verify** quality checklist
+
+### Workflow 3: Quick Formatting Check
+
+1. **Reference** markdown-quick-reference.md
+2. **Find** relevant pattern
+3. **Apply** to your content
+
+### Workflow 4: Style Guide Consultation
+
+1. **Search** STYLEGUIDE.md for specific rule
+2. **Apply** to complex formatting decisions
+3. **Trust** auto-rules for standard patterns
+
+## 📊 File Relationships
+
+```
+STYLEGUIDE.md (Root)
+    ↓ (authoritative source)
+.cursor/rules/markdown.mdc (Auto-applied rules)
+    ↓ (enforces automatically)
+[Your .md/.mdx files]
+    ↓ (guides manually)
+.cursor/prompts/convert-to-markdown.md (Conversion prompt)
+    ↓ (quick reference)
+.cursor/prompts/markdown-quick-reference.md (Syntax lookup)
+```
+
+## 🚦 Decision Tree
+
+```
+Need to work on documentation?
+│
+├─ Creating/Converting content?
+│  └─ Use: convert-to-markdown.md
+│
+├─ Quick syntax question?
+│  └─ Use: markdown-quick-reference.md
+│
+├─ Complex formatting decision?
+│  └─ Consult: STYLEGUIDE.md
+│
+└─ Just editing?
+   └─ Auto-rules handle it!
+```
+
+## 💡 Pro Tips
+
+### For Maximum Efficiency
+
+1. **Let automation work**
+   - Auto-rules in `.cursor/rules/` handle most formatting
+   - Focus on content quality
+   - Trust the system
+
+2. **Use prompts strategically**
+   - convert-to-markdown.md for scaffolding
+   - markdown-quick-reference.md for lookups
+   - Don't reinvent patterns
+
+3. **Reference the style guide**
+   - For edge cases
+   - For comprehensive rules
+   - For team alignment
+
+### For Best Results
+
+1. **Be specific with prompts**
+   - Include context and requirements
+   - Provide complete source content
+   - Describe desired structure
+
+2. **Review AI output**
+   - Check frontmatter completeness
+   - Verify code examples
+   - Test links
+
+3. **Trust but verify**
+   - Auto-rules are reliable
+   - Double-check critical content
+   - Use quality checklist
+
+## 📈 Success Metrics
+
+Your documentation should achieve:
+
+- ✅ 100% valid frontmatter
+- ✅ Consistent formatting throughout
+- ✅ Zero broken links
+- ✅ Complete code examples
+- ✅ Proper component usage
+- ✅ WCAG 2.1 AA compliance
+
+## 🔄 Maintenance
+
+### When to Update
+
+- **Style guide evolves** → Update STYLEGUIDE.md, then sync to rules/prompts
+- **New patterns emerge** → Add to markdown-quick-reference.md
+- **Prompts improve** → Refine based on usage experience
+- **Team feedback** → Incorporate into standards
+
+### Update Process
+
+1. Update authoritative source (STYLEGUIDE.md)
+2. Sync changes to automated rules (markdown.mdc)
+3. Update prompts to reflect new patterns
+4. Update quick reference with new examples
+5. Test with sample conversions
+
+## 🆘 Troubleshooting
+
+### Formatting Issues
+→ Check STYLEGUIDE.md for specific rules
+→ Verify auto-rules are applying (`.cursor/rules/`)
+→ Use markdown-quick-reference.md for patterns
+
+### Conversion Problems
+→ Review convert-to-markdown.md prompt
+→ Ensure source content is complete
+→ Check quality checklist after conversion
+
+### Component Issues
+→ Consult component-architecture.mdc
+→ Reference Starlight documentation
+→ Check existing usage in codebase
+
+## 🔗 External Resources
+
+- **CouchCMS Docs:** https://docs.couchcms.com/
+- **Astro Docs:** https://docs.astro.build/
+- **Starlight Docs:** https://starlight.astro.build/
+- **MDX Docs:** https://mdxjs.com/
+
+## 📞 Getting Help
+
+1. **Check this index** for quick navigation
+2. **Consult QUICKSTART.md** for common tasks
+3. **Review README.md** for comprehensive guide
+4. **Reference STYLEGUIDE.md** for definitive rules
+5. **Use prompts** for AI assistance
+
+---
+
+**Everything you need for consistent, high-quality CouchCMS documentation.**
+