Add markdownlint CI job and fix broken doc links

Add a markdownlint job to CI that lints the top-level Markdown docs with
markdownlint-cli2, configured via .markdownlint-cli2.yaml. The config
disables noisy/stylistic rules (line-length, bold-as-heading,
table-pipe-spacing), sets MD024 to siblings-only for the CHANGELOG, and
globs *.{md,markdown} (non-recursive) so spec/ working notes and .github/
are excluded.

Fix the existing violations to establish a green baseline:
- README: repair the stale table of contents (drop entries with no
  in-doc target, add the real sections), demote stray H1s to H2 with
  subsections bumped one level, add languages to bare code fences.
- OPERATIONS: fix cross-reference anchors that omitted the heading's
  "(N minutes)" suffix.
- Normalize blank lines around headings, fences, and lists.

Two OPERATIONS checklist links (#capacity-monitoring, #security-audit)
point to sections that do not exist yet; they are left in place with an
inline markdownlint-disable and a TODO referencing the issue.

Fixes #95

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sir-sigurd

.github/workflows/ci.yml

@@ -19,6 +19,13 @@ jobs:
           terraform_wrapper: false
       - run: terraform fmt -check -recursive -diff
 
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      # Globs and rules come from .markdownlint-cli2.yaml in the repo root.
+      - uses: DavidAnson/markdownlint-cli2-action@v23
+
   validate:
     runs-on: ubuntu-latest
     strategy:

.markdownlint-cli2.yaml

@@ -0,0 +1,20 @@
+# markdownlint-cli2 configuration. See https://github.com/DavidAnson/markdownlint
+# for the full rule reference.
+config:
+  # Line length: prose, tables, and long links routinely exceed any fixed width.
+  MD013: false
+  # Bold-as-heading: the docs deliberately use bold text as inline labels.
+  MD036: false
+  # Table pipe spacing: cosmetic; tables render correctly either way.
+  MD060: false
+  # Duplicate headings: the CHANGELOG repeats Added/Changed/Fixed per release,
+  # which is the Keep a Changelog convention. Only flag duplicates under the
+  # same parent heading.
+  MD024:
+    siblings_only: true
+# Lint top-level docs only; spec/ holds working notes and is intentionally
+# excluded. A non-recursive glob naturally skips spec/ and .github/. This
+# matches the default globs of markdownlint-cli2-action, so local runs and CI
+# lint the same files.
+globs:
+  - "*.{md,markdown}"

CHANGELOG.md

@@ -18,6 +18,9 @@ Optional release notice.
 
 ## [Unreleased] - YYYY-MM-DD
 
+- [Added] CI job that lints top-level Markdown docs with markdownlint-cli2, configured via `.markdownlint-cli2.yaml` ([#PR](https://github.com/quiltdata/iac/pull/PR))
+- [Fixed] Broken table-of-contents and cross-reference links in README and OPERATIONS docs ([#95](https://github.com/quiltdata/iac/issues/95))
+
 ## [1.8.0] - 2026-06-09
 
 - [Added] Transit Gateway egress mode for new VPCs: set `enable_transit_gateway = true` (+ `transit_gateway_id`) to route private-subnet egress through a Transit Gateway instead of NAT gateways; IPv6 egress is opt-in via `transit_gateway_ipv6_egress`. See [Transit Gateway egress](README.md#transit-gateway-egress) ([#115](https://github.com/quiltdata/iac/pull/115))
@@ -38,6 +41,7 @@ Optional release notice.
 ## [1.6.0] - 2026-02-24
 
 If you rely on the default `search_instance_type` / `search_dedicated_master_type`:
+
 - Upgrading from a version prior to 1.5.0 will fail on `terraform apply`. Upgrade to 1.5.0 first.
 - If you have reserved m5 instances, pin the instance types explicitly to keep using them.
 

OPERATIONS.md

@@ -12,20 +12,24 @@ This document provides comprehensive operational procedures for cloud teams mana
 
 ### Daily Checklist
 
-- [ ] Health check (5 min) - [Instructions](#daily-health-checks)
+- [ ] Health check (5 min) - [Instructions](#daily-health-checks-5-minutes)
 - [ ] Monitor alerts - [Dashboard Links](#monitoring-dashboards)
 - [ ] Review logs - [Log Locations](#log-management)
 
 ### Weekly Checklist
 
-- [ ] Backup verification (10 min) - [Instructions](#backup-verification)
-- [ ] Security updates (15 min) - [Instructions](#security-updates)
+- [ ] Backup verification (10 min) - [Instructions](#backup-verification-10-minutes)
+- [ ] Security updates (15 min) - [Instructions](#security-updates-15-minutes)
+<!-- TODO: no "Capacity review" section exists yet; see https://github.com/quiltdata/iac/issues/95 -->
+<!-- markdownlint-disable-next-line MD051 -->
 - [ ] Capacity review (10 min) - [Instructions](#capacity-monitoring)
 
 ### Monthly Checklist
 
-- [ ] Capacity planning (20 min) - [Instructions](#capacity-planning)
-- [ ] Cost review (15 min) - [Instructions](#cost-optimization)
+- [ ] Capacity planning (20 min) - [Instructions](#capacity-planning-20-minutes)
+- [ ] Cost review (15 min) - [Instructions](#cost-optimization-recommendations)
+<!-- TODO: no "Security audit" section exists yet; see https://github.com/quiltdata/iac/issues/95 -->
+<!-- markdownlint-disable-next-line MD051 -->
 - [ ] Security audit (30 min) - [Instructions](#security-audit)
 
 ## Installation Procedures