Add markdownlint CI job and fix broken doc links (#123)

* 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>

* Fill in CHANGELOG PR number

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

* Use rule-name aliases in markdownlint config

Reference rules by their readable names (line-length, no-emphasis-as-heading,
table-column-style, no-duplicate-heading) instead of MD0xx IDs.

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

* Drop CHANGELOG entry

A CI/docs-tooling change does not warrant a release note.

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

* Use rule-name alias in inline disable directives

Reference link-fragments instead of MD051 in the markdownlint-disable
comments, matching the config style.

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

* Add blank line before list in CHANGELOG

Pre-existing MD032 violation surfaced by the new markdownlint baseline.

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

* Correct MD060 description in config comment

table-column-style (MD060) governs table cell padding consistency; the
previous comment described it as "table pipe spacing," which is MD055.

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

* Defer README TOC fix to a separate PR

Restore the original table-of-contents entries verbatim and suppress the
broken in-doc anchors with a markdownlint-disable block plus a TODO
referencing #95, rather than deciding the TOC restructure here. The
navigation/content decision (which sections belong, cross-doc links)
belongs in a focused PR; this one stays scoped to the lint baseline.

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

* Lint all Markdown recursively

With spec/ removed (#122), there's no working-notes directory left to
avoid, so widen the glob from top-level *.{md,markdown} to recursive
**/*.{md,markdown} in both the config and the CI action (the action's
default glob is non-recursive and overrides the config, so it's set
explicitly). This auto-covers future nested docs like module READMEs.

The only newly-linted file, .github/pull_request_template.md, opens with
a section heading rather than an H1; skip first-line-heading inline since
it's a template fragment, not a standalone document.

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

* Use disable-file for the template's first-line-heading exemption

MD041 is about the file's first line, so the exemption belongs to the
whole file, not one line. disable-line was positional and would silently
stop working if the template gained a line above the heading.

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

* Lint Markdown via pinned npx instead of the action

Replace DavidAnson/markdownlint-cli2-action@v23 with a pinned
`npx markdownlint-cli2@0.22.1` run.

A moving major action tag auto-adopts new releases that can add or
tighten rules and break CI with no repo change; a pinned npm version is
content-immutable, so the linter is reproducible. It also matches the
local invocation, and lets the config's globs drive file selection
without duplicating them in the workflow.

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

* Tighten TOC link suppressions and fix two retargetable entries

- Retarget Troubleshooting and Terraform Commands Reference to the real
  sections; only the five entries needing cross-doc decisions (#95) stay.
- Switch the README disable block to per-line disables so a TOC entry
  added later still gets dead-anchor checking.
- Reword the TODO: #95 tracks the broken links themselves, not a
  restructure.
- Indent the suppression comments under the preceding list item so the
  TOC and checklists render as single lists (an unindented HTML comment
  between bullets splits the list).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Freeze the linter via lockfile and ignore vendored trees

- Move the markdownlint-cli2 pin into package.json + package-lock.json
  and run `npm ci` in CI: a bare `npx <pkg>@<version>` still resolves
  deep transitive deps fresh on every run, while the lockfile freezes
  the whole tree and makes the pin visible to update tooling.
- Add `ignores` for .terraform/ and node_modules/: markdownlint-cli2
  has no default exclusions, and `terraform init` vendors registry
  modules whose READMEs would fail local runs.
- Ignore node_modules in .gitignore.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Trim package.json to the essentials

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

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

Author: sir-sigurd

.github/pull_request_template.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable-file first-line-heading -->
 ## Description
 
 ## TODO

.github/workflows/ci.yml

@@ -19,6 +19,17 @@ 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. npm ci installs the
+      # exact tree from package-lock.json, so no markdownlint (or transitive)
+      # release can change rules or break CI without a repo change; bump the
+      # version deliberately via package.json.
+      - run: npm ci
+      - run: npx --no-install markdownlint-cli2
+
   validate:
     runs-on: ubuntu-latest
     strategy:

.gitignore

@@ -2,3 +2,4 @@
 .terraform
 .terraform.lock.hcl
 tfplan
+node_modules

.markdownlint-cli2.yaml

@@ -0,0 +1,26 @@
+# 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.
+  line-length: false
+  # Bold-as-heading: the docs deliberately use bold text as inline labels.
+  no-emphasis-as-heading: false
+  # Table column style: enforces consistent cell padding across tables;
+  # cosmetic, tables render correctly either way.
+  table-column-style: 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.
+  no-duplicate-heading:
+    siblings_only: true
+# Lint every Markdown file in the repo. Both local runs and CI invoke
+# markdownlint-cli2 with no glob arguments, so this is the single source of
+# truth for which files are linted.
+globs:
+  - "**/*.{md,markdown}"
+# markdownlint-cli2 has no default exclusions, so vendored trees must be
+# ignored explicitly: `terraform init` vendors registry modules (and their
+# READMEs) under .terraform/, and npm installs under node_modules/.
+ignores:
+  - "**/.terraform/**"
+  - "**/node_modules/**"

CHANGELOG.md

@@ -38,6 +38,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 link-fragments -->
 - [ ] 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 link-fragments -->
 - [ ] Security audit (30 min) - [Instructions](#security-audit)
 
 ## Installation Procedures