coder
diff --git a/‎.github/docs/README.md
Lines changed: 37 additions & 189 deletions b/‎.github/docs/README.md
Lines changed: 37 additions & 189 deletions
@@ -22,9 +22,9 @@ The validation system will automatically detect and check only files that have c
 
 ## Directory Structure
 
-- `actions/docs-core`: Primary composite action with the phase-based architecture
+- `config`: Configuration files for markdown tools (markdownlint, markdown-link-check)
 - `vale`: Configuration and style rules for Vale documentation linting
-- `.lycheeignore`: Configuration patterns for lychee link checking
+- `testing`: Test scripts and utilities for workflow validation
 
 ## Quick Start
 
@@ -74,7 +74,7 @@ pnpm install
 
 ## Workflow Architecture
 
-The documentation workflow system has a clear separation of concerns with multiple layers:
+The documentation workflow system uses MegaLinter and standardized GitHub Actions to provide a comprehensive validation pipeline:
 
 ```
 ┌─ Workflow Entry Points ───────────────────────────────────────────────────────┐
@@ -108,33 +108,11 @@ The documentation workflow system has a clear separation of concerns with multip
 │  └───────────────────────────────────────────────────────────────────────────┘  │
 │                                                                                 │
 │  ┌───────────────────────────────────────────────────────────────────────────┐  │
-│  │ Conditional Setup                                                          │  │
-│  │ • Tool installation (Node.js, PNPM, Vale)                                  │  │
-│  │ • Comment posting system                                                   │  │
-│  │ • Notification handling                                                    │  │
-│  └───────────────────────────────────────────────────────────────────────────┘  │
-│                                                                                 │
-└──────────────────────────────────────┬──────────────────────────────────────────┘
-                                       │
-                                       ▼
-┌─ Core Implementation (docs-core/action.yaml) ───────────────────────────────────┐
-│                                                                                 │
-│  ┌─── Phase 1: Setup & Detection ───┐  ┌─── Phase 3: Validation ─────────────┐  │
-│  │                                  │  │                                      │  │
-│  │ • Configuration processing       │  │ • Markdown linting                   │  │
-│  │ • Environment validation         │  │ • Table format checking              │  │
-│  │ • Changed file detection         │  │ • Link validation                    │  │
-│  │ • Advanced fallback mechanisms   │  │ • Vale style checking (parallel)     │  │
-│  │ • File relevance prioritization  │  │ • Enhanced cross-reference checks    │  │
-│  └──────────────────────────────────┘  └──────────────────────────────────────┘  │
-│                                                                                 │
-│  ┌─── Phase 4: Results & Reporting ──────────────────────────────────────────┐  │
-│  │                                                                           │  │
-│  │ • Results aggregation and normalization                                   │  │
-│  │ • JSON-based validation tracking                                          │  │
-│  │ • Two-stage PR comment system                                             │  │
-│  │ • Issue reporting                                                         │  │
-│  │ • Statistics calculation                                                  │  │
+│  │ Validation Pipeline                                                        │  │
+│  │ ┌────────────────┐  ┌────────────────┐  ┌────────────────┐                │  │
+│  │ │ MegaLinter     │  │ Cross-reference│  │ Result Reporting│                │  │
+│  │ │ Documentation  │  │ Validation     │  │ and Comments    │                │  │
+│  │ └────────────────┘  └────────────────┘  └────────────────┘                │  │
 │  └───────────────────────────────────────────────────────────────────────────┘  │
 │                                                                                 │
 └─────────────────────────────────────────────────────────────────────────────────┘
@@ -147,13 +125,6 @@ The documentation workflow system has a clear separation of concerns with multip
 │  │ make lint/docs│ │make fmt/markdown│ │make lint/markdown│ │make lint/docs-style│     │
 │  └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘     │
 │                                                                               │
-│  Features:                                                                    │
-│  • Automatically detects changed files (git diff)                             │
-│  • Supports both changed-only (default) and all-files (--all) modes           │
-│  • Uses same validation tools as GitHub Actions                               │
-│  • Provides clear error messages and fix instructions                         │
-│                                                                               │
-└───────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ## Documentation Workflow Components
@@ -195,91 +166,53 @@ All entry points use the central `docs-unified.yaml` workflow with different pre
 | `weekly` | Scheduled health check | markdown, formatting, links, cross-references | Weekly cron job (comprehensive check) |
 | `ci` | Fast CI validation | markdown, formatting | PR checks (fast feedback) |
 
-These presets ensure consistent validation based on context without duplicating logic.
+## Key Tools and Integrations
 
-#### Preset Configuration Details
+### MegaLinter Documentation Flavor
 
-Each preset automatically configures the following settings:
+The workflow leverages MegaLinter's documentation flavor to provide comprehensive validation:
 
-**PR Preset:**
-```yaml
-lint-markdown: true   # Format validation
-check-format: true    # Table format checks
-check-links: true     # Link validation
-check-xrefs: true     # Cross-reference validation
-lint-vale: true       # Style rule checking
-gen-preview: true     # Generate preview URLs
-post-comment: true    # Post PR comment with results
-create-issues: false  # Don't auto-create issues
-fail-on-error: false  # Allow preview generation even with errors
-```
+- **markdownlint**: Validates markdown syntax and formatting
+- **Vale**: Checks documentation style and terminology
+- **markdown-link-check**: Verifies links are valid and accessible
 
-**Post-Merge Preset:**
-```yaml
-lint-markdown: false  # Skip format validation (already checked in PR)
-check-format: false   # Skip table checks (already checked in PR) 
-check-links: true     # Focus on link validation after content changes
-check-xrefs: false    # Cross-refs already checked in PR
-lint-vale: false      # Style already checked in PR
-gen-preview: false    # No preview needed after merge
-post-comment: false   # No PR to comment on
-create-issues: false  # Manual issue review after merge
-fail-on-error: false  # Record but don't block on errors
-```
+Configuration files are stored in standardized locations:
+- `.github/docs/config/.markdownlint.yml`: Markdown linting rules
+- `.github/docs/vale/.vale.ini`: Vale style configuration
+- `.github/docs/config/markdown-link-check.json`: Link checking settings
 
-**Weekly Preset:**
-```yaml
-lint-markdown: true   # Comprehensive checks
-check-format: true    # Comprehensive checks
-check-links: true     # Comprehensive checks
-check-xrefs: true     # Comprehensive checks
-lint-vale: false      # Style not critical for weekly checks
-gen-preview: false    # No preview needed
-post-comment: false   # No PR to comment on
-create-issues: false  # Issue creation feature is planned but not implemented yet
-fail-on-error: true   # Strict validation
-```
+### Changed Files Detection
+
+The workflow uses tj-actions/changed-files to efficiently detect changed files:
 
-**CI Preset:**
 ```yaml
-lint-markdown: true   # Focus on basic validation
-check-format: true    # Focus on basic validation
-check-links: false    # Skip slower checks in CI
-check-xrefs: false    # Skip slower checks in CI
-lint-vale: true       # Include style checks
-gen-preview: false    # No preview in CI
-post-comment: false   # No comments in CI
-create-issues: false  # No issues from CI
-fail-on-error: true   # Fail fast in CI
+# Get changed files
+- name: Get changed files
+  id: changed-files
+  uses: tj-actions/changed-files@v41
+  with:
+    files: |
+      docs/**/*.md
+      **/*.md
 ```
 
-## Validation Features
-
-### Two-Stage PR Comment System
+### Cross-Reference Validation
 
-The PR workflow implements a two-stage comment system:
+Custom cross-reference validation checks for broken internal links:
 
-1. **Initial Comment (Immediate)**
-   - Posted immediately after checkout and setup
-   - Provides preview links while validation runs
-   - Displays a "Validation in progress" status
-   - Allows reviewers to immediately start reviewing documentation
+- References to deleted files
+- Broken internal markdown links
+- Missing image references
 
-2. **Updated Comment (After Validation)**
-   - Updates the same comment with validation results
-   - Shows comprehensive validation status
-   - Includes direct links to changed files
-   - Provides validation statistics and duration information
-
-### Vale Style Checking
+## Vale Style Checking
 
 The workflow includes Vale style checking that:
 - Only examines changed files to improve performance
 - Validates documentation against Coder style guidelines
-- Runs inline in the workflow (not as a separate action)
+- Uses the errata-ai/vale-action GitHub Action
 - Is configured in `.github/docs/vale/` with custom rules
 
-#### Vale Style Rules
+### Vale Style Rules
 
 The following style rules are configured:
 
@@ -299,30 +232,6 @@ This is a very long sentence that would normally trigger the sentence length rul
 <!-- vale Coder.SentenceLength = YES -->
 ```
 
-To exempt an entire file, add this at the top:
-
-```markdown
----
-vale: false
----
-```
-
-### Link and Cross-Reference Verification
-
-Link checking features:
-- External link validation with lychee
-- Internal cross-reference verification
-- Configurable settings and ignore patterns in `.lycheeignore`
-- Special handling for manifest.json navigation changes
-
-### Markdown Validation
-
-The workflow validates markdown:
-- Structural issues (headings, lists, blockquotes)
-- Table formatting and alignment
-- Basic stylistic conventions
-- Document structure and organization
-
 ## Workflow Configuration Options
 
 Each workflow entry point can be customized with these key parameters:
@@ -340,67 +249,6 @@ Each workflow entry point can be customized with these key parameters:
 | `create-issues` | Create GitHub issues for failures | (from preset) |
 | `fail-on-error` | Fail workflow on validation errors | (from preset) |
 
-## Future Improvements
-
-While the current documentation workflow system is robust and efficient, there are several areas for potential future enhancements:
-
-1. **Incremental Validation**
-   - Implement only checking files that have changed since the last validation
-   - Create a dependency graph of documentation files to optimize cross-reference checking
-
-2. **Advanced Link Checking**
-   - Add specialized handling for API endpoint references
-   - Implement schema validation for URLs in documentation
-   - Add validation for image references
-
-3. **Better Local Integration**
-   - Create a pre-commit hook that runs the same validation locally
-   - Develop a VSCode extension for real-time documentation validation
-
-4. **Enhanced Reporting**
-   - Implement trending analysis of documentation issues
-   - Add visualization of common problem areas
-   - Create a documentation quality dashboard
-
-5. **Automated Fixes**
-   - Implement auto-correction for common documentation issues
-   - Add AI-assisted suggestions for improvement
-
-6. **Integration with External Systems**
-   - Sync validation results with project management tools
-   - Implement notification integrations beyond GitHub and Slack
-
-By continuously improving the documentation workflow, we can maintain high-quality documentation while making the validation process more efficient for contributors.
-
-## Troubleshooting
-
-### Common Issues and Solutions
-
-#### File Detection Problems
-If changed files aren't being detected correctly:
-- The workflow includes fallback mechanisms to ensure validation occurs
-- Check workflow logs for fallback notices
-- Verify you have changes in the docs/ directory
-
-#### Link Checking Errors
-If you see link checking errors:
-- Run link checking locally: `lychee docs/**/*.md`
-- Add exceptions to `.github/docs/.lycheeignore` if needed
-- For internal cross-references, ensure anchors match headers exactly
-
-#### Style Validation Issues
-If you encounter Vale style warnings:
-- Check specific rules in the output
-- Use inline comments to disable specific rules when appropriate:
-  `<!-- vale StyleName.RuleName = NO -->`
-- Consider updating the Vale style rules if the issue occurs frequently
-
-#### Preview URL Issues
-The preview URL system converts branch names to URL-friendly format:
-- Branch names with slashes are converted to dashes
-- Default links are provided even when no files change
-- The format is: `https://coder.com/docs/@<branch-name>`
-
 ## Using Documentation Validation in Custom Workflows
 
 To use documentation validation in your own workflows: