coder
diff --git a/‎.github/docs/README.md
Lines changed: 31 additions & 5 deletions b/‎.github/docs/README.md
Lines changed: 31 additions & 5 deletions
diff --git a/‎.github/docs/actions/docs-core/action.yaml
Lines changed: 49 additions & 47 deletions b/‎.github/docs/actions/docs-core/action.yaml
Lines changed: 49 additions & 47 deletions
diff --git a/‎.github/workflows/docs-link-check.yaml
Lines changed: 2 additions & 15 deletions b/‎.github/workflows/docs-link-check.yaml
Lines changed: 2 additions & 15 deletions
diff --git a/‎.github/workflows/docs-preview.yaml
Lines changed: 2 additions & 10 deletions b/‎.github/workflows/docs-preview.yaml
Lines changed: 2 additions & 10 deletions
@@ -13,17 +13,43 @@ This directory contains GitHub Actions, configurations, and workflows for Coder'
 For developers working with documentation, here are the most commonly used commands:
 
 ```bash
-# Run the comprehensive docs validation
+# Run comprehensive documentation validation (markdown lint + link checking)
+make lint/docs
+
+# Run only markdown linting
 make lint/markdown
 
+# Run optional style checking with Vale (if installed)
+make lint/docs-style
+
 # Fix formatting issues
 make fmt/markdown   # Formats tables and markdown styling
+```
+
+## Local vs CI Validation
+
+The validation that runs in CI is available locally through the same Makefile targets:
+
+| GitHub Action | Local Command | Description |
+|---------------|--------------|-------------|
+| Markdown linting | `make lint/markdown` | Checks markdown formatting |
+| Link checking | `make lint/docs` | Verifies links aren't broken |
+| Vale style checking | `make lint/docs-style` (optional) | Validates documentation style with Vale |
+| Cross-reference validation | *Part of CI only* | Checks references between docs |
+
+### Optional Tool Installation
+
+While basic linting works out-of-the-box with node dependencies, additional tools can be installed for more advanced checks:
+
+```bash
+# Install Lychee for link checking (recommended)
+cargo install lychee
 
-# Run link checking locally
-lychee docs/**/*.md
+# Install Vale for style checking (optional)
+brew install vale
 
-# Check style with Vale
-vale --config=.github/docs/vale/.vale.ini docs/
+# Node dependencies for markdown formatting (required)
+pnpm install
 ```
 
 ## Workflow Architecture Overview
 
@@ -180,41 +180,41 @@ runs:
         if [ -n "${{ inputs.preset }}" ]; then
           case "${{ inputs.preset }}" in
             "pr")
-              # PR preset: Full validation with preview for PRs
-              LINT_MARKDOWN="true"
-              CHECK_FORMAT="true"
-              CHECK_LINKS="true"
-              CHECK_XREFS="true"
-              LINT_VALE="true"
-              GEN_PREVIEW="true"
-              POST_COMMENT="true"
-              CREATE_ISSUES="false"
-              FAIL_ON_ERROR="false"
+              # PR preset: Comprehensive validation with preview for PRs
+              LINT_MARKDOWN="true"  # Ensure markdown format is correct
+              CHECK_FORMAT="true"   # Check table formatting
+              CHECK_LINKS="true"    # Verify all links work
+              CHECK_XREFS="true"    # Check document cross-references
+              LINT_VALE="true"      # Run style checks
+              GEN_PREVIEW="true"    # Generate preview links
+              POST_COMMENT="true"   # Post comment with results
+              CREATE_ISSUES="false" # No auto-issue creation for PRs
+              FAIL_ON_ERROR="false" # Don't fail workflow to allow previews with warnings
               echo "::notice::Applied PR preset configuration"
               ;;
             "post-merge")
-              # Post-merge preset: Focus on link checking and issue creation
+              # Post-merge preset: Lightweight check focused on link integrity
               LINT_MARKDOWN="false"
               CHECK_FORMAT="false"
-              CHECK_LINKS="true"
-              CHECK_XREFS="true"
-              LINT_VALE="false"
+              CHECK_LINKS="true"  # Only check links after merge to main
+              CHECK_XREFS="false" # Cross-references should be checked pre-merge
+              LINT_VALE="false"   # Style should be checked pre-merge
               GEN_PREVIEW="false"
               POST_COMMENT="false"
-              CREATE_ISSUES="true"
+              CREATE_ISSUES="false"
               FAIL_ON_ERROR="false"
               echo "::notice::Applied post-merge preset configuration"
               ;;
             "weekly")
-              # Weekly check preset: Focus on links with notifications
-              LINT_MARKDOWN="false"
-              CHECK_FORMAT="false"
+              # Weekly check preset: Comprehensive validation with notifications (no style checks)
+              LINT_MARKDOWN="true"
+              CHECK_FORMAT="true"
               CHECK_LINKS="true"
               CHECK_XREFS="true"
-              LINT_VALE="false"
+              LINT_VALE="false"     # Skip Vale style checking in weekly checks
               GEN_PREVIEW="false"
               POST_COMMENT="false"
-              CREATE_ISSUES="true"
+              CREATE_ISSUES="true"  # Create issues for persistent problems
               FAIL_ON_ERROR="true"
               echo "::notice::Applied weekly check preset configuration"
               ;;
@@ -688,18 +688,18 @@ runs:
         echo "message=Link checking is enabled" >> $GITHUB_OUTPUT
         echo "::endgroup::"
         
-    # Note: Style checking is now completely handled by errata-ai/vale-action in the unified workflow
+    # Note: Vale style checking is handled in the unified workflow
     # This step exists solely to maintain compatibility with the workflow structure
     - name: Report Vale style checking status
       id: lint-vale
       if: env.lint_vale == 'true' && steps.file-detection.outputs.has_changes == 'true'
       shell: bash
       run: |
         echo "::group::Vale style checking"
-        echo "Style checking is performed via the Vale GitHub Action"
-        echo "This step is a placeholder for compatibility with the workflow structure"
+        echo "Style checking is performed inline in the unified workflow"
+        echo "This step is a placeholder for result collection"
         echo "status=success" >> $GITHUB_OUTPUT
-        echo "message=See Vale GitHub Action for style validation results" >> $GITHUB_OUTPUT
+        echo "message=See unified workflow for style validation results" >> $GITHUB_OUTPUT
         echo "::endgroup::"
         
     - name: Check for broken cross-references
@@ -921,7 +921,27 @@ runs:
         fi
         
         # === GitHub Comment Format ===
-        GH_COMMENT="# 📚 Documentation Check Results\n\n"
+        GH_COMMENT="# 📚 Documentation Preview Ready ✅\n\n"
+        
+        # Show preview link prominently first
+        if [ "${{ env.gen_preview }}" == "true" ]; then
+          GH_COMMENT+="## 🖥️ [View Documentation Preview](${{ steps.context-info.outputs.preview_url }})\n\n"
+          
+          # Add direct links to changed files if available
+          if [ -n "${{ steps.file-detection.outputs.direct_links }}" ]; then
+            GH_COMMENT+="### 📄 Changed Files\n\n"
+            
+            IFS=',' read -ra LINKS <<< "${{ steps.file-detection.outputs.direct_links }}"
+            for link in "${LINKS[@]}"; do
+              # Extract the file name for display
+              filename=$(basename "$link" | sed 's/.md$//')
+              GH_COMMENT+="- [$filename]($link)\n"
+            done
+            GH_COMMENT+="\n"
+          fi
+        fi
+        
+        # Then show validation status
         GH_COMMENT+="## 🔎 Status Overview\n\n"
         GH_COMMENT+="${{ steps.aggregate-results.outputs.badge }}\n\n"
         
@@ -940,30 +960,12 @@ runs:
           fi
         done
         
-        # Add preview section
+        # Add standard documentation links (moved from preview section)
         if [ "${{ env.gen_preview }}" == "true" ]; then
-          GH_COMMENT+="\n## 🖥️ Preview Your Changes\n\n"
-          GH_COMMENT+="**🔗 [View Documentation Preview](${{ steps.context-info.outputs.preview_url }})**\n\n"
-          
-          # Add standard documentation links
-          GH_COMMENT+="### Quick Links\n\n"
+          GH_COMMENT+="\n### Quick Links\n\n"
           GH_COMMENT+="- [Main Docs](${{ steps.context-info.outputs.preview_url }})\n"
           GH_COMMENT+="- [Installation Guide](${{ steps.context-info.outputs.install_url }})\n"
           GH_COMMENT+="- [Getting Started](${{ steps.context-info.outputs.getting_started_url }})\n\n"
-          
-          # Add direct links to changed files if available
-          if [ -n "${{ steps.file-detection.outputs.direct_links }}" ]; then
-            GH_COMMENT+="<details>\n<summary><strong>📄 Direct Links to Changed Files</strong></summary>\n\n"
-            
-            IFS=',' read -ra LINKS <<< "${{ steps.file-detection.outputs.direct_links }}"
-            for link in "${LINKS[@]}"; do
-              # Extract the file name for display
-              filename=$(basename "$link" | sed 's/.md$//')
-              GH_COMMENT+="- [$filename]($link)\n"
-            done
-            
-            GH_COMMENT+="</details>\n\n"
-          fi
         fi
         
         # Always add the documentation validation status section
@@ -1006,9 +1008,9 @@ runs:
         
         GH_COMMENT+="</details>\n\n"
         
-        # Add footer
+        # Add footer with timestamp
         GH_COMMENT+="---\n"
-        GH_COMMENT+="<sub>🤖 This comment is automatically generated and updated when documentation changes.</sub>"
+        GH_COMMENT+="<sub>🤖 This comment was last updated on $(date -u "+%Y-%m-%d %H:%M:%S UTC") when validation completed.</sub>"
         
         # Output the formatted results
         echo "summary<<EOF" >> $GITHUB_OUTPUT
 
@@ -10,9 +10,7 @@ on:
       - '.github/docs/**'
       - '.github/workflows/docs-link-check*.yaml'
       - '.github/workflows/docs-unified*.yaml'
-  # Weekly run on Monday at 9 AM
-  schedule:
-    - cron: "0 9 * * 1"
+  # Scheduled runs moved to weekly-docs.yaml
   # Allow manual triggering for testing
   workflow_dispatch:
 
@@ -32,15 +30,4 @@ jobs:
       preset: 'post-merge'
       # Configure notifications
       notification-channels: 'github-issue,slack'
-      issue-labels: 'documentation,bug,needs-triage'
-      # Post-merge checks for links, cross-references, and style
-      check-links: true
-      check-cross-references: true
-      lint-markdown: false
-      check-format: false
-      lint-vale: true
-      generate-preview: false
-      post-comment: false
-      # Don't create issues automatically to avoid flake issues
-      create-issues: false
-      fail-on-error: false
+      issue-labels: 'documentation,bug,needs-triage'
@@ -23,13 +23,5 @@ jobs:
       pull-requests: write
     with:
       preset: 'pr'  # Use the PR preset with all the right configurations
-      # Override specific parameters for faster preview
-      check-links: false # Skip link checking for faster preview
-      check-cross-references: true # Still check cross-references
-      lint-markdown: true # Quick check for formatting
-      check-format: true # Quick check for table formatting
-      lint-vale: true # Add style checking to catch typos like repeated words
-      generate-preview: true # Always generate preview
-      post-comment: true # Always post comment
-      fail-on-error: false # Never fail for preview
-      notification-channels: '' # No external notifications
+      # Skip link checking for faster preview
+      check-links: false