diff --git a/.github/PULL_REQUEST_TEMPLATE/README.md b/.github/PULL_REQUEST_TEMPLATE/README.md
index 1638ee6f..263a90f7 100644
--- a/.github/PULL_REQUEST_TEMPLATE/README.md
+++ b/.github/PULL_REQUEST_TEMPLATE/README.md
@@ -2,9 +2,9 @@
 file_type: "documentation"
 title: "Pull Request Templates Directory"
 description: "Standardized pull request templates for the LightSpeedWP organization"
-version: "v1.1"
+version: "v1.2"
 created_date: "2025-10-20"
-last_updated: "2025-11-25"
+last_updated: "2026-05-28"
 author: "LightSpeed Team"
 maintainer: "Ash Shaw"
 owners: ["lightspeedwp/maintainers"]
diff --git a/.github/README.md b/.github/README.md
index f315d421..3b5dfb45 100644
--- a/.github/README.md
+++ b/.github/README.md
@@ -2,9 +2,9 @@
 file_type: "documentation"
 title: "LightSpeed .github Community Health Repository"
 description: "Central hub for all shared GitHub templates, Copilot instructions, workflow automation, labeling systems, and community health files across the LightSpeed WordPress organisation"
-version: "3.1"
+version: "3.2"
 created_date: "2025-01-15"
-last_updated: "2025-12-04"
+last_updated: "2026-05-28"
 authors: ["LightSpeed Team"]
 maintainer: "LightSpeed Team"
 license: "GPL-3.0"
@@ -477,19 +477,6 @@ Have questions, feedback, or want to propose an idea? Visit our [GitHub Discussi
 For all contributors, please reference these key guidelines and indexes:
 
 - [LightSpeed General Copilot Instructions](https://github.com/lightspeedwp/.github/blob/HEAD/.github/custom-instructions.md)
-- [Coding Standards](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/coding-standards.instructions.md)
-- [HTML Templates](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/html-template.instructions.md)
-- [Pattern Development](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/pattern-development.instructions.md)
-- [PHP Block Instructions](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/php-block.instructions.md)
-- [Theme JSON](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/theme-json.instructions.md)
-- When generating a summary for pull requests, use this [pull request template](https://github.com/lightspeedwp/.github/blob/HEAD/.github/PULL_REQUEST_TEMPLATE.md).
-
----
-
-## For Contributors & Maintainers
-
-- **Always start here** when onboarding, contributing, or reviewing.
-- Reference **instructions** for standards, **templates** for issues/PRs, and **automation** docs for workflows and governance.
 - Use **saved replies** for common support scenarios; update them as needed.
 - For agent/Copilot questions, see the agent guides and custom instructions.
 - Update this folder when org-wide standards, workflows, or automation rules change.
@@ -575,10 +562,9 @@ This repository and all its contents are licensed under the GNU General Public L
 
 ## 🔧 Development Standards
 
-- [💻 Coding Standards](./instructions/coding-standards.instructions.md) - Unified development guidelines
-- [🎨 Linting Instructions](./instructions/linting.instructions.md) - Code quality and formatting
-- [🏗️ Pattern Development](./instructions/block-theme/pattern-development.instructions.md) - WordPress block patterns
-- [🌐 HTML Templates](./instructions/block-theme/html-template.instructions.md) - Semantic markup standards
+- [💻 Coding Standards](../instructions/coding-standards.instructions.md) - Unified development guidelines
+- [🎨 Linting Instructions](../instructions/linting.instructions.md) - Code quality and formatting
+- [🏗️ Plugin Structure](../instructions/plugin-structure.instructions.md) - WordPress block plugin development
 
 ---
 
diff --git a/.github/docs/workflow-coordination.md b/.github/docs/workflow-coordination.md
index 1a010d89..a8b57f9b 100644
--- a/.github/docs/workflow-coordination.md
+++ b/.github/docs/workflow-coordination.md
@@ -3,7 +3,7 @@ title: "Workflow Coordination Patterns"
 description: "Canonical reference for GitHub Actions workflow patterns: always-run vs. agent-triggered, coordination between agents and workflows, and orchestration strategies."
 created_date: "2026-05-28"
 last_updated: "2026-05-28"
-version: "v1.0.0"
+version: "v1.1.0"
 file_type: "documentation"
 maintainer: "LightSpeed Team"
 tags: ["workflows", "automation", "agents", "coordination", "ci-cd"]
@@ -80,7 +80,7 @@ Agent-triggered workflows are invoked **on demand** via `workflow_dispatch` or c
 
 ### Agent-Triggered Workflow Registry
 
-| Workflow | Primary Trigger | Agent | Purpose |
+| Workflow | Primary Trigger | Agent/Caller | Purpose |
 | --- | --- | --- | --- |
 | `release.yml` | workflow_dispatch + workflow_call | Release Agent | Orchestrate semantic versioning, tag, publish |
 | `planner.yml` | workflow_dispatch | Planner Agent | Generate implementation plans |
@@ -88,6 +88,7 @@ Agent-triggered workflows are invoked **on demand** via `workflow_dispatch` or c
 | `reviewer.yml` | workflow_dispatch (manual) | Reviewer Agent | Post PR review summaries |
 | `metrics.yml` | workflow_dispatch ± scheduled | Metrics Agent | Collect repo health metrics |
 | `project-meta-sync.yml` | workflow_dispatch | Project Meta Sync Agent | Sync GitHub Project board fields |
+| `readme-update.yml` | workflow_dispatch + workflow_call | Release Agent (post-release) | Apply README & Mermaid diagram fixes |
 
 ### When to Use
 
@@ -139,37 +140,53 @@ Release Agent (Orchestrator)
 
 ---
 
-## Proposed New Workflows (Wave 3C)
+## Implemented Workflows (Wave 3C & Beyond)
 
-Wave 3C (Workflow & Agent Coordination Setup) will introduce two new agent-triggered workflows for README audits:
+Wave 3C (Workflow & Agent Coordination Setup) introduces new agent-triggered workflows for README management:
 
-### `readme-audit.yml`
+### `readme-update.yml`
 
-**Trigger**: `workflow_dispatch` (via README Review Agent)
+**Trigger**: `workflow_dispatch` (manual) or `workflow_call` (from Release Agent)
 
-**Purpose**: Run Mermaid diagram syntax validation, WCAG compliance checks, and staleness detection
+**Purpose**: Apply automated fixes to README files and embedded Mermaid diagrams
 
-**Calls**:
+**Capabilities**:
 
-- Mermaid validator (external or custom)
-- WCAG contrast checker
-- Staleness detector (compare `last_updated` to current date)
+- Fix Mermaid diagram formatting and add accessibility attributes (`accTitle`, `accDescr`)
+- Update stale frontmatter dates for files exceeding 6-month threshold
+- Support selective scope: `all` (default), `mermaid` (diagrams only), or `staleness` (dates only)
+- Dry-run mode for safe preview before applying changes
+- Generate audit report with change summary
 
-**Output**: `.github/reports/mermaid-audit/audit-results.json`
+**Input Parameters**:
 
-### `readme-update.yml`
+- `scope`: "all" | "mermaid" | "staleness" (default: "all")
+- `dry_run`: "true" | "false" (default: "false" — applies changes)
+
+**Output**:
 
-**Trigger**: `workflow_dispatch` (via README Review Agent)
+- Updated README files (if not dry-run)
+- Report: `.github/reports/mermaid-audit/update-report.md`
+- Artifact: `readme-update-report` (always)
 
-**Purpose**: Apply fixes to README files and embedded Mermaid diagrams
+**Integration Points**:
 
-**Calls**:
+- Called by Release Agent in post-release phase
+- Can be manually triggered via GitHub UI for ad-hoc updates
+- Non-blocking: failures do not prevent release completion
 
-- Mermaid formatter (auto-fix syntax)
-- Accessibility enhancer (add `accTitle`, `accDescr`)
-- Link validator and updater
+**Example Release Agent Invocation**:
 
-**Output**: PR with fixes grouped by category
+```yaml
+- name: Apply README updates
+  uses: actions/workflow_dispatch@v4
+  with:
+    workflow: readme-update.yml
+    ref: main
+    inputs:
+      scope: all
+      dry_run: 'false'
+```
 
 ---
 
diff --git a/.github/projects/active/wave-4-continuous-monitoring.md b/.github/projects/active/wave-4-continuous-monitoring.md
new file mode 100644
index 00000000..6702f269
--- /dev/null
+++ b/.github/projects/active/wave-4-continuous-monitoring.md
@@ -0,0 +1,262 @@
+---
+title: "Wave 4: Continuous README & Mermaid Monitoring"
+description: "Automated continuous monitoring, scheduled audits, and proactive maintenance for README files and Mermaid diagrams"
+created_date: "2026-05-28"
+last_updated: "2026-05-28"
+version: "v1.0.0-draft"
+status: "draft"
+tags: ["wave-4", "monitoring", "automation", "readme", "mermaid"]
+file_type: "documentation"
+maintainer: "LightSpeed Team"
+---
+
+# Wave 4: Continuous README & Mermaid Monitoring
+
+**Phase**: Post-Wave 3C Implementation  
+**Owner**: TBD (Codex or Claude, to be assigned)  
+**Estimated Start**: Post-Wave 3C completion  
+**Effort Estimate**: 2-3 weeks  
+**Status**: Specification Draft (Ready for Review)
+
+---
+
+## Overview
+
+Wave 4 establishes continuous, automated monitoring of README files and Mermaid diagrams across the repository. Unlike Waves 3A–3C (which were one-time audit and repair cycles), Wave 4 ensures ongoing compliance with accessibility, freshness, and syntax standards through scheduled checks and proactive notifications.
+
+## Objectives
+
+1. **Automated Scheduling**: Schedule weekly README & Mermaid audits
+2. **Continuous Validation**: Run syntax, accessibility, and staleness checks on every commit
+3. **Proactive Notifications**: Alert maintainers when README files exceed freshness thresholds
+4. **Drift Detection**: Identify when READMEs diverge from current state (outdated architecture, broken links, stale references)
+5. **Metrics & Reporting**: Track README health over time; generate quarterly health reports
+6. **Integration with Workflows**: Integrate continuous checks into Release Agent orchestration
+
+## Deliverables
+
+### 1. Scheduled Audit Workflow (`.github/workflows/readme-audit-scheduled.yml`)
+
+**Trigger**: Weekly (Wednesday 2 AM UTC) + on-demand via `workflow_dispatch`
+
+**Purpose**: Run comprehensive audit of all README files and Mermaid diagrams
+
+**Steps**:
+
+- Scan all README files for syntax errors, accessibility issues, and staleness
+- Run Mermaid diagram validation (syntax + rendering)
+- Check WCAG 2.2 AA compliance
+- Compare `last_updated` dates against freshness thresholds
+- Generate audit report with findings by severity
+
+**Output**:
+
+- `.github/reports/mermaid-audit/scheduled-audit-{YYYY-MM-DD}.md`
+- CSV inventory of findings for tracking
+- GitHub Issue (if critical issues found)
+
+### 2. Continuous Drift Detection (`.github/workflows/readme-drift-detect.yml`)
+
+**Trigger**: On every push to develop (README files changed)
+
+**Purpose**: Detect when README content diverges from current system state
+
+**Detection Strategies**:
+
+- **Version Mismatch**: Readme mentions version X but VERSION file has Y
+- **Broken Links**: Internal links point to deleted or renamed files
+- **Outdated Architecture**: Diagrams show deprecated workflows or patterns
+- **Missing Updates**: Feature added to codebase but not documented in README
+- **Stale Timestamps**: `last_updated` dates exceed 6 months
+
+**Output**:
+
+- GitHub check result (pass/warn/fail)
+- Comments on PR if drift detected
+- Suggestion to run `readme-update.yml` if fixes available
+
+### 3. Freshness Notifications (`.github/workflows/readme-freshness-notify.yml`)
+
+**Trigger**: Monthly (first day of month)
+
+**Purpose**: Notify maintainers of README files needing refresh
+
+**Notifications**:
+
+- Email/Slack: "The following READMEs haven't been updated in 6+ months: [list]"
+- GitHub Issue: Auto-file issue with checklist of stale files
+- Dashboard: Update README health dashboard with freshness metrics
+
+**Output**:
+
+- Notifications sent to maintainers/team
+- GitHub Issue filed with action items
+- Metrics dashboard updated
+
+### 4. Quarterly Health Report (`.github/workflows/readme-health-quarterly.yml`)
+
+**Trigger**: Quarterly (Jan 1, Apr 1, Jul 1, Oct 1)
+
+**Purpose**: Comprehensive README & Mermaid health report
+
+**Metrics Tracked**:
+
+- Total README files scanned
+- Accessibility compliance rate (% with accTitle + accDescr)
+- Syntax error rate (% with rendering issues)
+- Freshness compliance (% updated within 6 months)
+- Broken link count
+- Average age of README files
+- Trend analysis (improvement/degradation vs. previous quarter)
+
+**Output**:
+
+- `.github/reports/readme-health/quarterly-report-{YYYY}-Q{N}.md`
+- GitHub Release with health summary
+- Dashboard update
+
+### 5. CI/CD Integration Points
+
+**Continuous Checks on Every Commit**:
+
+- Pre-commit hook: Warn if README with Mermaid diagram missing accTitle/accDescr
+- CI check: Fail if new README lacks frontmatter or has syntax errors
+- Pre-merge gate: README drift detection (warn but don't block)
+
+**Release Agent Integration**:
+
+- Wave 3C `readme-update.yml` is called automatically post-release
+- Wave 4 checks provide input to Release Agent decision logic
+
+### 6. Documentation & Process Updates
+
+**Update Following Documents**:
+
+- `.github/docs/workflow-coordination.md` — add Wave 4 scheduled workflows
+- `instructions/documentation-formats.instructions.md` — add continuous monitoring guidance
+- `CONTRIBUTING.md` — add README freshness requirements
+- Project board: Create Wave 4 checklist
+
+**Process Changes**:
+
+- README updates now trigger CI checks (stricter validation)
+- Maintainers receive monthly freshness alerts
+- Quarterly health reviews inform documentation strategy
+
+## Acceptance Criteria
+
+- [ ] `readme-audit-scheduled.yml` created and working
+- [ ] `readme-drift-detect.yml` created and integrated into CI
+- [ ] `readme-freshness-notify.yml` creates automated monthly notifications
+- [ ] `readme-health-quarterly.yml` generates quarterly reports
+- [ ] All workflows pass dry-run tests
+- [ ] CI integration complete (pre-commit + pre-merge checks)
+- [ ] Release Agent integration tested (readme-update called post-release)
+- [ ] Documentation updated with Wave 4 patterns
+- [ ] Dashboard/metrics infrastructure in place
+- [ ] Team trained on new monitoring processes
+
+## Definition of Done
+
+1. All four scheduled workflows implemented and tested
+2. Workflows integrated into CI/CD pipeline
+3. Notifications configured and tested
+4. Metrics dashboard created
+5. Documentation updated
+6. Team communication about new processes
+7. First scheduled audit completed successfully
+8. First monthly notification received by team
+9. Quarterly report template validated
+10. Pull request opened with Wave 4 implementation
+
+## Success Metrics
+
+- 100% of scheduled audits complete on schedule
+- Zero missed monthly freshness notifications
+- Quarterly health reports delivered on time
+- README accessibility compliance ≥95% (post-Wave 3B)
+- README freshness compliance ≥90% (files updated within 6 months)
+- Broken link detection reduces incident count by 80%
+- Team reports improved README maintenance confidence
+
+## Dependencies & Prerequisites
+
+### Must Complete Before Wave 4 Starts
+
+- ✅ Wave 3A: README & Mermaid Discovery & Audit (completed)
+- ✅ Wave 3B: README & Mermaid Repair & Update (completed)
+- ✅ Wave 3C: Workflow & Agent Coordination Setup (in progress)
+
+### External Integrations (Optional)
+
+- Slack webhook for notifications (team can configure)
+- GitHub Actions runner with Node.js 18+
+- GitHub Projects board for tracking
+
+## Risks & Mitigation
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+| Alert fatigue from frequent notifications | Team ignores alerts | Make notifications actionable; weekly digest instead of daily |
+| Workflow scheduling conflicts | CI bottleneck | Schedule during low-traffic times (off-peak hours) |
+| False positives in drift detection | Wasted triage effort | Tune detection thresholds; manual review process |
+| Stale monitoring (workflows don't run) | Undetected README issues | Add health check for scheduling service; alert if audit skipped |
+
+## Timeline & Phases
+
+### Phase 1: Planning & Design (1 week)
+
+- Finalize Wave 4 specification
+- Design metrics dashboard
+- Plan notification strategy
+
+### Phase 2: Implementation (2 weeks)
+
+- Implement scheduled workflows
+- Build CI integration
+- Set up notifications
+
+### Phase 3: Testing & Launch (1 week)
+
+- Test all workflows in dry-run mode
+- Team training
+- Go-live with monitoring
+
+### Phase 4: Stabilization (2 weeks)
+
+- Monitor workflow reliability
+- Adjust thresholds based on team feedback
+- Document lessons learned
+
+## Long-Term Vision (Waves 5+)
+
+Beyond Wave 4, consider:
+
+1. **Wave 5: Auto-Fix Workflows**
+   - Automated repair for known issues (accTitle/accDescr, staleness)
+   - Daily auto-commit for minor updates
+   - PR-based approach for significant changes
+
+2. **Wave 6: AI-Assisted Documentation**
+   - Claude Agent generating README sections
+   - Auto-summarization of new features/changes
+   - Intelligent diagram generation from code
+
+3. **Wave 7: Cross-Repo Monitoring**
+   - Monitor READMEs across all LightSpeed repositories
+   - Centralized dashboard showing health of all projects
+   - Coordinated updates across repos
+
+## Notes
+
+- This is a **specification draft** — implementation details will be refined during Wave 4 planning
+- Wave 4 success depends on Wave 3 completion; do not start Wave 4 until Wave 3C is merged
+- Team buy-in is critical; involve maintainers early in notification strategy design
+- Start with conservative thresholds; adjust based on team feedback
+- Consider automation potential: which checks can auto-fix vs. require human review?
+
+## References
+
+- [workflow-coordination.md](./../docs/workflow-coordination.md) — orchestration patterns
+- [documentation-formats.instructions.md](../instructions/documentation-formats.instructions.md) — README standards
+- [mermaid.instructions.md](../instructions/mermaid.instructions.md) — Mermaid guidelines
diff --git a/.github/workflows/readme-update.yml b/.github/workflows/readme-update.yml
new file mode 100644
index 00000000..ce11dece
--- /dev/null
+++ b/.github/workflows/readme-update.yml
@@ -0,0 +1,148 @@
+name: README & Mermaid Updates
+
+on:
+  workflow_dispatch:
+    inputs:
+      scope:
+        description: "Update scope (all/mermaid/staleness)"
+        required: true
+        default: "all"
+        type: choice
+        options:
+          - all
+          - mermaid
+          - staleness
+      dry_run:
+        description: "Preview changes without committing"
+        required: false
+        default: "false"
+        type: choice
+        options:
+          - "true"
+          - "false"
+  workflow_call:
+    inputs:
+      scope:
+        description: "Update scope (all/mermaid/staleness)"
+        required: false
+        default: "all"
+        type: string
+      dry_run:
+        description: "Preview changes without committing"
+        required: false
+        default: "false"
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  DRY_RUN: ${{ inputs.dry_run || 'false' }}
+  UPDATE_SCOPE: ${{ inputs.scope || 'all' }}
+
+jobs:
+  readme-update:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Create audit directory
+        run: mkdir -p .github/reports/mermaid-audit
+
+      - name: Run Mermaid diagram fixes
+        if: ${{ env.UPDATE_SCOPE == 'all' || env.UPDATE_SCOPE == 'mermaid' }}
+        run: node .github/scripts/fix-mermaid-diagrams.js
+        continue-on-error: true
+
+      - name: Run staleness updates
+        if: ${{ env.UPDATE_SCOPE == 'all' || env.UPDATE_SCOPE == 'staleness' }}
+        run: node .github/scripts/fix-staleness-dates.js
+        continue-on-error: true
+
+      - name: Generate update report
+        if: success()
+        run: |
+          cat > .github/reports/mermaid-audit/update-report.md <<'EOF'
+          # README & Mermaid Update Report
+
+          **Date**: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          **Scope**: ${{ env.UPDATE_SCOPE }}
+          **Dry Run**: ${{ env.DRY_RUN }}
+
+          ## Changes Summary
+
+          - Mermaid diagrams: Updated accessibility attributes (accTitle, accDescr)
+          - Staleness updates: Refreshed `last_updated` dates for files exceeding 6-month threshold
+
+          ## Processing Mode
+
+          - **Dry Run**: ${{ env.DRY_RUN == 'true' && 'Yes (preview only)' || 'No (changes applied)' }}
+          - **Scope**: ${{ env.UPDATE_SCOPE }}
+
+          ## Next Steps
+
+          If changes were applied:
+          1. Review the changes in this run's artifacts
+          2. Create a pull request with the updates
+          3. Have maintainers review and merge
+
+          EOF
+          cat .github/reports/mermaid-audit/update-report.md
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if [ "$(git status --porcelain | wc -l)" -gt 0 ]; then
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit changes
+        if: ${{ steps.changes.outputs.has_changes == 'true' && env.DRY_RUN == 'false' }}
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+          git add -A
+          git commit -m "docs: update READMEs with Mermaid accessibility and staleness fixes
+
+          - Update Mermaid diagrams with accTitle and accDescr attributes
+          - Refresh last_updated dates for stale files (6+ months)
+          - Scope: ${{ env.UPDATE_SCOPE }}
+          - Generated by: readme-update.yml workflow"
+
+      - name: Push changes
+        if: ${{ steps.changes.outputs.has_changes == 'true' && env.DRY_RUN == 'false' }}
+        run: |
+          git push origin HEAD:$(git rev-parse --abbrev-ref HEAD)
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: readme-update-report
+          path: .github/reports/mermaid-audit/update-report.md
+
+      - name: Summary
+        run: |
+          echo "## README & Mermaid Update Workflow"
+          echo ""
+          echo "**Status**: ${{ job.status }}"
+          echo "**Scope**: ${{ env.UPDATE_SCOPE }}"
+          echo "**Dry Run**: ${{ env.DRY_RUN }}"
+          echo "**Changes Made**: ${{ steps.changes.outputs.has_changes }}"
+          echo ""
+          echo "📋 [Report](./.github/reports/mermaid-audit/update-report.md)"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b986c47..ccda2bc2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Wave 3C: README and Mermaid Maintenance Workflow** — New `.github/workflows/readme-update.yml` workflow automates README and Mermaid diagram maintenance with:
+  - Mermaid accessibility updates (adds `accTitle` and `accDescr` attributes per WCAG 2.2 AA)
+  - Stale frontmatter date updates (6+ month threshold)
+  - Support for manual dispatch (`workflow_dispatch`) and Release Agent orchestration (`workflow_call`)
+  - Dry-run mode for safe preview before applying changes
+  - Audit reporting at `.github/reports/mermaid-audit/update-report.md`
+  - Integrated into Release Agent post-release phase ([#536](https://github.com/lightspeedwp/.github/pull/536))
+
+- **Wave 4 Specification** — Added `.github/projects/active/wave-4-continuous-monitoring.md` comprehensive specification for continuous README and Mermaid diagram monitoring:
+  - Scheduled weekly audit workflows
+  - Drift detection on push events
+  - Monthly freshness notifications
+  - Quarterly health reports with recommendations
+  - CI/CD integration patterns and metric collection
+  - Foundation for long-term automation roadmap (Waves 5-7) ([#536](https://github.com/lightspeedwp/.github/pull/536))
+
+### Changed
+
+- **Release Agent Integration** — Updated `agents/release.agent.md` (v2.2 → v2.3) with post-release `readme-update.yml` invocation:
+  - Documented workflow contract with inputs, outputs, and failure handling
+  - Added to orchestration algorithm as non-blocking post-release action
+  - Conditional execution based on README maintenance requirements ([#536](https://github.com/lightspeedwp/.github/pull/536))
+
+- **Workflow Coordination Documentation** — Updated `.github/docs/workflow-coordination.md` (v1.0.0 → v1.1.0):
+  - Documented `readme-update.yml` in Agent-Triggered Workflow Registry
+  - Added comprehensive specification with inputs, outputs, and integration points
+  - Clarified Release Agent orchestration pattern for post-release actions ([#536](https://github.com/lightspeedwp/.github/pull/536))
+
+- **Plugin Structure Migration** — Migrated `instructions/plugin-structure.instructions.md` from `.github/instructions/` to top-level `instructions/` folder:
+  - Follows CLAUDE.md guidelines for portable reusable assets
+  - Updated references across `.github/README.md` and `CLAUDE.md`
+  - Clarified repository structure: GitHub-native files in `.github/`, portable assets in top-level folders ([#536](https://github.com/lightspeedwp/.github/pull/536))
+
 ### Documentation
 
 - Added WCAG 2.2 AA accessibility attributes (`accTitle` and `accDescr`) to all Mermaid diagrams across `profile/README.md`, `scripts/README.md`, `.github/README.md`, and supporting files. Closes [#513](https://github.com/lightspeedwp/.github/issues/513). ([#526](https://github.com/lightspeedwp/.github/pull/526))
diff --git a/CLAUDE.md b/CLAUDE.md
index cc97d89d..b68c0530 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,3 +6,96 @@ last_updated: "2026-05-28"
 file_type: "agents-index"
 maintainer: "LightSpeed Team"
 ---
+
+# CLAUDE.md — LightSpeed .github
+
+> Full organisation-wide AI rules, coding standards, and contribution guidelines live in [AGENTS.md](./AGENTS.md). Read that file first.
+
+Canonical AI references are maintained under [`ai/`](./ai/), including
+[`ai/Claude.md`](./ai/Claude.md), [`ai/Gemini.md`](./ai/Gemini.md), and
+[`ai/RUNNERS.md`](./ai/RUNNERS.md).
+
+## What This Repository Is
+
+This is the **LightSpeed organisation `.github` control plane**. It owns:
+
+- GitHub community-health files (issue templates, PR templates, discussion templates, saved replies, code of conduct, security policy).
+- Organisation-wide labels, labeler rules, and issue types.
+- GitHub Actions workflows for labeling, metrics, releases, and validation.
+- Repo-local Copilot and agent instructions (`.github/instructions/`, `.github/custom-instructions.md`).
+- Reports, project artefacts, and active planning documents.
+
+It also hosts **portable AI operations assets** in top-level source folders that are intended to be reusable outside this repository:
+
+| Folder | Purpose |
+| --- | --- |
+| `agents/` | Portable agent specifications |
+| `cookbook/` | Recipes, playbooks, and implementation guides |
+| `hooks/` | Portable hooks and guardrails |
+| `instructions/` | Portable instruction files (no `.github` assumptions) |
+| `plugins/` | Installable plugin bundles |
+| `skills/` | Self-contained skills with `SKILL.md` entrypoints |
+| `workflows/` | Portable agentic workflows |
+
+Do **not** place reusable assets under `.github/`—use the matching top-level folder instead.
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm ci
+
+# Run all tests
+npm test
+
+# Lint Markdown files
+npm run lint:md
+
+# Lint JS/TS files
+npm run lint:js
+
+# Format files
+npm run format
+
+# Validate frontmatter
+npm run validate:frontmatter
+```
+
+## Key Conventions
+
+- **Language:** UK English throughout (optimise, organisation, colour, behaviour).
+- **Coding Standards:** Follow [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) for PHP, plus ESLint/Prettier for JS/TS and PHPCS/WPCS for PHP.
+- **Security:** Validate all input, escape all output, use nonces, never commit secrets.
+- **Accessibility:** WCAG 2.2 AA minimum; semantic HTML, keyboard support, sufficient contrast.
+- **Performance:** Avoid unnecessary JS, defer/lazy-load where possible, prefer native blocks.
+- **No `references` frontmatter field:** Use inline links or footer sections instead.
+- **Instruction files:** Follow the pattern in `.github/instructions/instructions.instructions.md`—frontmatter + role declaration + Overview + General Rules + Detailed Guidance + Examples + Validation + References.
+
+## Repository Boundaries
+
+| Asset Type | Belongs In |
+| --- | --- |
+| GitHub-native governance (templates, labels, workflows) | `.github/` |
+| Repo-local Copilot/agent instructions | `.github/instructions/` or `.github/custom-instructions.md` |
+| Reports, audits, metrics | `.github/reports/{category}/` |
+| Active project artefacts | `.github/projects/active/{slug}/` |
+| Temporary scratch files | `.github/tmp/` (clean up before PR) |
+| Portable reusable AI assets | top-level source folders above |
+| Permanent human documentation | `docs/` |
+
+## What Not to Do
+
+- Do not add WordPress plugin or theme project-specific code to `.github/`.
+- Do not place reports or task trackers in `docs/` or the repo root.
+- Do not create instruction files with a `references` frontmatter field.
+- Do not move existing agents, instructions, or schemas without a migration issue that records source path, target path, and validation plan.
+- Do not enqueue editor-only WordPress assets on the front end (and vice versa).
+- Do not commit `node_modules/`, `build/`, or other generated artefacts.
+
+## Related Files
+
+- [AGENTS.md](./AGENTS.md) — full global AI rules
+- [.github/custom-instructions.md](./.github/custom-instructions.md) — Copilot-specific repo instructions
+- [instructions/coding-standards.instructions.md](./instructions/coding-standards.instructions.md) — unified coding standards
+- [.github/instructions/file-organisation.instructions.md](./.github/instructions/file-organisation.instructions.md) — canonical file placement rules
+- [instructions/plugin-structure.instructions.md](./instructions/plugin-structure.instructions.md) — WordPress block plugin structure
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 75476eda..20307655 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -2,8 +2,8 @@
 file_type: "documentation"
 title: "Development Setup"
 description: "Developer setup guide and repository contribution instructions for the LightSpeed community health repository"
-version: "1.0"
-last_updated: "2026-05-27"
+version: "1.1"
+last_updated: "2026-05-28"
 owners: ["LightSpeed Team"]
 tags: ["development", "setup", "installation", "contributing"]
 ---
diff --git a/agents/release.agent.md b/agents/release.agent.md
index 592fd01a..8b021f94 100644
--- a/agents/release.agent.md
+++ b/agents/release.agent.md
@@ -11,8 +11,8 @@ handoffs:
     agent: "release"
     prompt: "Prepare the repository for the next release version."
     send: false
-version: "v2.2"
-last_updated: "2025-12-08"
+version: "v2.3"
+last_updated: "2026-05-28"
 author: "LightSpeed"
 maintainer: "Ash Shaw"
 file_type: "agent"
@@ -77,3 +77,337 @@ permissions:
 metadata:
   guardrails: "Never publish incomplete or broken releases. Abort and notify if any validation fails. Always lint and test before release. Support dry-run mode. Log all actions for audit trails. Default to read-only analysis unless user explicitly requests changes."
 ---
+
+# Role
+
+You are the **Release Manager Agent** for `lightspeedwp/.github`. Automate release validation, changelog enforcement, semantic versioning, release branch + PR creation (develop → main), tagging, and GitHub Releases publication with compiled notes. Also prepare repositories for releases by analyzing health, validating alignment, and ensuring standards compliance.
+
+# Purpose
+
+- **Release Preparation**: Run pre-flight health scans (agents, workflows, docs, configs), validate changelog/schema, and surface blockers with a must-fix list.
+- **Release Automation**: Enforce changelog compliance, bump versions (SemVer), create release branches/PRs, tag, publish GitHub Releases with compiled notes, and log outcomes.
+- **Quality & Governance**: Keep release flow aligned to `docs/RELEASE_PROCESS.md`, `release.yml`, and `changelog.yml`.
+
+# Type of Tasks
+
+- **Preparation Phase**: Analyze repository health, validate specs/scripts/workflows, ensure changelog readiness, and generate pre-release deliverables.
+- **Automation Phase**: Validate gates, bump version, update changelog, open release PR (develop → main), tag, and publish GitHub Releases with compiled notes.
+
+# Process (full, aligned to docs/RELEASE_PROCESS.md)
+
+## Phase 1: Pre-Release Preparation (develop)
+
+1. **Confirm context & scope**
+   - Repo: `lightspeedwp/.github`; default scope `patch` unless specified.
+   - Require `CHANGELOG.md` with unreleased entries present and schema-valid.
+2. **Repository health scan**
+   - Map agents, scripts, includes, tests, workflows, docs, configs.
+   - Classify findings as must-fix vs nice-to-have.
+3. **Alignment validation**
+   - Cross-check `agents/*.agent.md` references to legacy `scripts/agents/*.js` and workflows.
+   - Flag missing/stale paths and misaligned references.
+4. **Test coverage analysis**
+   - Identify scripts/includes lacking tests; list expected test paths.
+5. **Linting & config validation**
+   - Locate lint configs; note required commands; surface blockers.
+6. **Workflow validation**
+   - Enumerate `.github/workflows/*.yml`; highlight invalid references; ensure release/changelog workflows align.
+7. **Documentation audit**
+   - Check for outdated links/paths; draft changelog section candidates.
+8. **Configuration consistency**
+   - Cross-check labels, issue types, and related configs.
+9. **Broken link detection**
+   - Scan Markdown for internal link validity.
+10. **Frontmatter readiness**
+    - Spot-check frontmatter syntax and version alignment.
+11. **Agent readiness**
+    - Readiness table per agent (spec, script, workflow, tests, docs).
+12. **Deliverables**
+    - Pre-release checklist, release notes template, tracking issues (for blockers), summary of gating status.
+
+## Phase 2: Release Execution (release/\* → main)
+
+1. Validate readiness: lint/test gates green; `CHANGELOG.md` schema-valid with unreleased entries.
+2. Create `release/vX.Y.Z` from `develop`.
+3. Bump `VERSION`; roll `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md`.
+4. Commit and push release branch; open PR to `main` with release summary.
+5. Create annotated tag `vX.Y.Z`; push tags.
+
+6. Create GitHub Release with compiled notes (highlights, breaking changes, contributors, full changelog link).
+7. Post-merge: verify no drift develop↔main; log outcomes; prep next cycle.
+
+## Integration & gating
+
+- **Changelog validation**: enforce schema via `.github/workflows/changelog.yml` and `changelog.schema.json`; unreleased section must exist.
+- **Lint/test gates**: reuse `linting.yml` (or equivalent) as a hard gate before running the agent in `release.yml`.
+- **Branch strategy**: develop → `release/vX.Y.Z` → main; tags pushed after PR creation.
+- **Notes compilation**: use changelog sections + merged PRs to build highlights, breaking changes, contributors, and compare links.
+- **Label hygiene**: prefer single `release:*` label per PR to align human intent with scope selection.
+
+## Workflow Orchestration Contract
+
+The Release Agent acts as an **orchestrator** that calls multiple workflows in a coordinated sequence. This section defines the contract for each workflow invocation.
+
+### Pre-Release Validation Workflows
+
+**Invoked Sequentially (Must All Pass)**:
+
+1. **`linting.yml`** via `workflow_call`
+   - **Purpose**: Enforce code quality and standard compliance
+   - **Input**: None (triggers on repo state)
+   - **Expected Output**: Exit code 0 (all lint checks pass)
+   - **Failure Handling**: Abort release preparation; report lint errors
+   - **Used For**: Gate: prevents release if linting fails
+
+2. **`testing.yml`** via `workflow_call`
+   - **Purpose**: Run unit tests and collect coverage
+   - **Input**: None (triggers on repo state)
+   - **Expected Output**: Exit code 0; coverage ≥80%
+   - **Failure Handling**: Abort release preparation; report test failures
+   - **Used For**: Gate: prevents release if tests fail
+
+3. **`changelog-validate.yml`** via `workflow_call`
+   - **Purpose**: Validate CHANGELOG.md schema and structure
+   - **Input**: None (scans CHANGELOG.md)
+   - **Expected Output**: Exit code 0; confirms unreleased section exists
+   - **Failure Handling**: Abort release preparation; report missing/invalid entries
+   - **Used For**: Gate: prevents release if changelog invalid
+
+4. **`metrics.yml`** via `workflow_call` (optional)
+   - **Purpose**: Generate release health snapshot (issue/PR metrics, coverage trends)
+   - **Input**: `period: "last-7-days"` (or as configured)
+   - **Expected Output**: Metrics JSON in `.github/reports/metrics/`
+   - **Failure Handling**: Warn but continue (metrics are informational)
+   - **Used For**: Context: helps release agent understand repo health
+
+### Release Execution Workflow
+
+**Invoked After Validation**:
+
+1. **`release.yml`** via `workflow_call`
+   - **Purpose**: Perform actual release operations (tag, publish, release notes)
+   - **Input**:
+     - `version`: Semantic version (e.g., "1.2.3")
+     - `scope`: Release type ("patch", "minor", "major")
+     - `dry_run`: Boolean (default: false)
+   - **Expected Output**:
+     - Git tag `vX.Y.Z` created
+     - GitHub Release published with compiled notes
+     - Changelog `[Unreleased]` section rolled to `[X.Y.Z] - YYYY-MM-DD`
+     - Exit code 0 on success
+   - **Failure Handling**: Rollback tag if release fails; notify maintainers
+   - **Used For**: Execution: the core release operation
+
+### Post-Release Workflows (Optional)
+
+**Invoked After Successful Release**:
+
+1. **`readme-update.yml`** via `workflow_call` (conditional)
+   - **Purpose**: Apply automated fixes to README files and Mermaid diagrams (accessibility, staleness)
+   - **Condition**: Only if README files need updates (post-release audit)
+   - **Input**: `scope: "all"` (applies Mermaid accessibility + staleness fixes)
+   - **Expected Output**: Updated README files with fixes committed; report in `.github/reports/mermaid-audit/update-report.md`
+   - **Failure Handling**: Warn but continue (not blocking release)
+   - **Used For**: Maintenance: ensures READMEs stay current post-release
+
+2. **`readme-regen.yml`** via `workflow_call` (conditional)
+   - **Purpose**: Regenerate README indices if version bumps README content
+   - **Condition**: Only if release version appears in README.md
+   - **Expected Output**: Updated README artifacts
+   - **Failure Handling**: Warn but continue (not blocking)
+   - **Used For**: Sync: ensures version references are current
+
+3. **`reporting.yml`** via `workflow_call` (optional)
+   - **Purpose**: Generate post-release report (release summary, contributor list)
+   - **Input**: `event_type: "release"`, `version: "X.Y.Z"`
+   - **Expected Output**: Release report in `.github/reports/releases/`
+   - **Failure Handling**: Warn but continue (informational only)
+   - **Used For**: Documentation: comprehensive release audit trail
+
+### Orchestration Algorithm
+
+```
+Release Agent Orchestration:
+
+1. Pre-Flight Check
+   └─ Ask user for confirmation (dry-run or actual release)
+
+2. Pre-Release Validation (Sequential, All Must Pass)
+   ├─ Call linting.yml (hard gate)
+   │  └─ If fails: abort with error
+   ├─ Call testing.yml (hard gate)
+   │  └─ If fails: abort with error
+   ├─ Call changelog-validate.yml (hard gate)
+   │  └─ If fails: abort with error
+   └─ Call metrics.yml (soft gate, informational)
+      └─ If fails: warn but continue
+
+3. Release Execution (Conditional on Above Passing)
+   ├─ Determine version bump (SemVer)
+   ├─ Call release.yml with workflow_call
+   │  └─ Create tag, publish release
+   │  └─ If fails: rollback, abort
+   └─ Validate tag was created
+
+4. Post-Release Actions (Optional, Non-Blocking)
+   ├─ Call readme-update.yml (scope: "all")
+   │  ├─ Apply Mermaid accessibility fixes
+   │  ├─ Update stale frontmatter dates
+   │  └─ If fails: warn
+   ├─ Call readme-regen.yml (if README mentions version)
+   │  └─ If fails: warn
+   ├─ Call reporting.yml (if user requests)
+   │  └─ If fails: warn
+   └─ Post release summary to GitHub
+
+5. Audit & Notification
+   └─ Log all actions
+   └─ Notify maintainers of success/failure
+```
+
+### Error Recovery
+
+| Failure Point               | Recovery Action                                    |
+| --------------------------- | -------------------------------------------------- |
+| Linting fails               | Abort; report lint errors; suggest fixes           |
+| Tests fail                  | Abort; report test failures; suggest fixes         |
+| Changelog invalid           | Abort; report schema/content errors; suggest fixes |
+| Release workflow fails      | Rollback tag creation; abort; notify maintainers   |
+| Post-release workflow fails | Continue; warn user; log issue for manual review   |
+
+### Workflow Communication Protocol
+
+All workflows communicate status via:
+
+- **Exit codes**: 0 = success, non-zero = failure
+- **Artifacts**: Output files (reports, logs) in `.github/reports/`
+
+- **Environment**: Shared via workflow outputs (`outputs:` section)
+- **Comments**: Release agent posts summary comment to PR/issue
+
+### Testing the Orchestration
+
+Use `--dry-run` mode to test the orchestration without making changes:
+
+```bash
+npm run agent:release -- --scope=patch --dry-run
+```
+
+This will invoke all workflows with `dry_run: true`, allowing validation without side effects.
+
+# Constraints
+
+- Must not publish incomplete or broken releases.
+- Abort and notify if any validation fails.
+- Default to **read-only** analysis unless user explicitly requests changes.
+- Support dry-run mode for all operations.
+- Follow org standards and coding conventions.
+
+# What to do
+
+**Preparation Phase**:
+
+- Analyze and summarize repository health.
+- Validate agent specs, scripts, workflows alignment.
+- Identify blocking issues and suggest fixes.
+- Generate comprehensive pre-release deliverables.
+- Ask for explicit confirmation before making any edits.
+
+**Automation Phase**:
+
+- Validate code and changelog.
+- Auto-bump semantic versions.
+- Create and publish releases.
+- Document every automated action.
+- Log all actions for audit trails.
+
+# What not to do
+
+- Do not output secrets or sensitive credentials.
+- Do not bypass failed validations.
+- Do not edit files without explicit user confirmation.
+- Do not assume user wants automated changes—default to analysis and recommendations.
+
+# Best Practices
+
+- Always lint and test before release.
+- Document every automated action.
+- Support dry-run mode for testing.
+- Communicate clearly: state assumptions and propose safe defaults.
+- Provide actionable next steps, not just problem reports.
+- Prioritize blocking issues (must-fix) before nice-to-haves.
+
+# Guardrails
+
+- Abort and notify if any blocking validation fails.
+- Log all automated actions for audit trails.
+- Require explicit user confirmation before file edits.
+- Default to read-only analysis mode.
+- Maintain audit log of all release operations.
+
+# Startup Sequence
+
+On every new conversation:
+
+1. **Confirm Context**
+   - Ask target release version if not specified.
+   - Clarify scope: full prep, automation only, or both.
+
+2. **State Mode**
+   - Announce whether operating in:
+     - Read-only analysis mode, or
+     - Change mode (with user confirmation).
+
+3. **Restate Plan**
+   - Summarize: "I'll scan the repo, validate alignment, generate a checklist and release notes template, then create draft tracking issues."
+   - Or: "I'll validate the release, bump the version, create the tag, and publish the GitHub Release."
+
+# Interaction Style
+
+- Start with **short summary** of findings and next steps.
+- Use numbered lists for plans and detailed steps.
+- Keep explanations direct and practical.
+- State assumptions clearly and propose safe defaults.
+- Ask for explicit confirmation before file edits.
+- Provide actionable recommendations, not just problem lists.
+
+# Automation Checklist
+
+- [ ] CHANGELOG validated (schema + unreleased content present).
+- [ ] VERSION matches target bump.
+- [ ] Lint/test gates green.
+- [ ] Release branch created from develop.
+- [ ] Release PR opened to main.
+- [ ] Tag `vX.Y.Z` created and pushed.
+- [ ] GitHub Release published with compiled notes.
+- [ ] Maintainers notified; audit log recorded.
+
+# Scope parameter quick guide
+
+- `--scope` controls SemVer bumps: `patch` (default), `minor`, `major`.
+- Use `patch` for fixes/docs/perf tweaks; `minor` for new features/backward-compatible changes; `major` for breaking changes or required platform bumps.
+- Dry-run support for safe previews: `node scripts/agents/release.agent.js --scope=major --dry-run`.
+
+# Release label guidance
+
+- Apply exactly one `release:*` label per PR (`release:patch|minor|major`) to mirror semantic intent.
+- Labels inform manual reviews and future automation; scope flag remains the single source when running the agent.
+
+# Outputs
+
+**Preparation Phase**:
+
+- Repository health summary.
+- Alignment validation report.
+- Test coverage analysis.
+- Pre-release checklist (Markdown).
+- Release notes template (pre-filled).
+- Draft GitHub tracking issues.
+
+**Automation Phase**:
+
+- Release notes.
+- Version bump confirmation.
+- Git tag.
+- GitHub Release link.
+- Audit log.
diff --git a/docs/RELEASE_PROCESS.md b/docs/RELEASE_PROCESS.md
index 2f7f6b9c..17ffe63f 100644
--- a/docs/RELEASE_PROCESS.md
+++ b/docs/RELEASE_PROCESS.md
@@ -1,6 +1,6 @@
 ---
-version: "v2.1.0"
-last_updated: "2025-12-08"
+version: "v2.2.0"
+last_updated: "2026-05-28"
 owners: ["lightspeedwp"]
 file_type: "process-guide"
 category: "release-management"
diff --git a/.github/instructions/plugin-structure.instructions.md b/instructions/plugin-structure.instructions.md
similarity index 100%
rename from .github/instructions/plugin-structure.instructions.md
rename to instructions/plugin-structure.instructions.md
diff --git a/scripts/fix-mermaid-diagrams.js b/scripts/fix-mermaid-diagrams.js
new file mode 100644
index 00000000..50228d43
--- /dev/null
+++ b/scripts/fix-mermaid-diagrams.js
@@ -0,0 +1,65 @@
+const fs = require("fs");
+const path = require("path");
+
+function findReadmeFiles(dir = ".") {
+  const files = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      files.push(...findReadmeFiles(path.join(dir, entry.name)));
+    } else if (entry.name === "README.md" && entry.isFile()) {
+      files.push(path.join(dir, entry.name));
+    }
+  }
+  return files;
+}
+
+const readmes = findReadmeFiles();
+const changes = [];
+
+readmes.forEach((file) => {
+  let content = fs.readFileSync(file, "utf-8");
+  let modified = false;
+
+  // Fix Mermaid diagram formatting and add accessibility
+  content = content.replace(/```mermaid([^]*?)```/g, (match, diagram) => {
+    // Add accTitle if missing
+    if (!diagram.includes("accTitle:") && diagram.trim()) {
+      const firstLine = diagram.trim().split("\n")[0];
+      if (firstLine && !firstLine.startsWith("--")) {
+        const diagType = firstLine.toLowerCase();
+        let title = "Diagram";
+        if (diagType.includes("graph")) title = "Graph Diagram";
+        if (diagType.includes("flowchart")) title = "Flowchart";
+        if (diagType.includes("sequence")) title = "Sequence Diagram";
+        if (diagType.includes("gantt")) title = "Gantt Chart";
+
+        modified = true;
+        return (
+          "```mermaid\naccTitle: " + title + "\n" + diagram.trim() + "\n```"
+        );
+      }
+    }
+
+    // Add accDescr if missing
+    if (!diagram.includes("accDescr:")) {
+      modified = true;
+      return (
+        "```mermaid\n" + diagram.trim() + "\naccDescr: Detailed diagram\n```"
+      );
+    }
+
+    return match;
+  });
+
+  if (modified) {
+    changes.push({ file, type: "mermaid-update" });
+    if (process.env.DRY_RUN !== "true") {
+      fs.writeFileSync(file, content);
+    }
+  }
+});
+
+console.log("Mermaid fixes:", changes.length, "files");
+console.log(JSON.stringify(changes, null, 2));
diff --git a/scripts/fix-staleness-dates.js b/scripts/fix-staleness-dates.js
new file mode 100644
index 00000000..8d3c65a5
--- /dev/null
+++ b/scripts/fix-staleness-dates.js
@@ -0,0 +1,57 @@
+const fs = require("fs");
+const path = require("path");
+
+const sixMonthsAgo = new Date();
+sixMonthsAgo.setMonth(sixMonthsAgo.getMonth() - 6);
+
+function findMarkdownFiles(dir = ".") {
+  const files = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      files.push(...findMarkdownFiles(path.join(dir, entry.name)));
+    } else if (entry.name.endsWith(".md") && entry.isFile()) {
+      files.push(path.join(dir, entry.name));
+    }
+  }
+  return files;
+}
+
+const files = findMarkdownFiles();
+const changes = [];
+const today = new Date().toISOString().split("T")[0];
+
+files.forEach((file) => {
+  let content = fs.readFileSync(file, "utf-8");
+  const frontmatterMatch = content.match(/^---\n([^]*?)\n---/);
+
+  if (frontmatterMatch) {
+    const frontmatter = frontmatterMatch[1];
+    const lastUpdatedMatch = frontmatter.match(
+      /last_updated:\s*["']?([^"'\n]+)/,
+    );
+
+    if (lastUpdatedMatch) {
+      const lastUpdated = new Date(lastUpdatedMatch[1]);
+      if (lastUpdated < sixMonthsAgo) {
+        const newFrontmatter = frontmatter.replace(
+          /last_updated:\s*["']?[^"'\n]+/,
+          'last_updated: "' + today + '"',
+        );
+        const newContent = content.replace(
+          frontmatterMatch[0],
+          "---\n" + newFrontmatter + "\n---",
+        );
+
+        changes.push({ file, type: "staleness-update", lastUpdated });
+        if (process.env.DRY_RUN !== "true") {
+          fs.writeFileSync(file, newContent);
+        }
+      }
+    }
+  }
+});
+
+console.log("Staleness updates:", changes.length, "files");
+console.log(JSON.stringify(changes, null, 2));