ci(docs): add markdownlint foundation (prek + CI)

[pfe-nazaries]

Context

The repo had no consistent markdown lint enforcement. Style drifted between docs and was caught only during review, with the same fixes repeated PR after PR. This change wires markdownlint into both prek (local pre-commit) and CI so violations are caught up front, and cleans up the pre-existing violations the repo-wide scope surfaces so CI stays green from day one.

Description

Wires a shared markdown lint pipeline (prek + CI) and applies a one-shot, formatting-only cleanup of the violations the repo-wide scope exposes.

What's wired

• .markdownlint.json (rule config) and .markdownlintignore (path scope).
• markdownlint-cli@0.45.0 in .pre-commit-config.yaml (prek hook — runs locally on touched *.md).
• .github/workflows/markdown-lint.yml (Docs: Markdown Lint): triggers on PRs/pushes to master / v5.* and lints the whole tree with the same pin. No tj-actions/changed-files gate — the lint itself is ~5s, so the gate doesn't pay for itself the way it does in Python toolchains, and skipping the third-party action removes a small supply-chain surface. Node sourced from ui/.nvmrc. Invocation uses pnpm dlx --ignore-scripts to mitigate postinstall risk on transitive deps.

Rule overview

The config extends markdownlint/style/prettier (which already disables anything Prettier would reformat — line length, list indent, fence/blank spacing, etc.). On top of that:

Rule	State	Why
MD024 no-duplicate-heading	siblings_only: true	Allows the same heading text under different parents (e.g. repeated ### Args blocks).
MD033 no-inline-html	off	We rely on raw HTML for GitHub <details>, callouts, badges, etc.
MD034 no-bare-urls	off	Bare URLs are common and idiomatic in our docs/READMEs.
MD041 first-line-h1	off	Some files start with frontmatter or admonitions, not an H1.
All other defaults	on	Standard markdownlint defaults remain active.

The high-impact rules left enabled (the ones that actually fired across the repo and drove the cleanup commit):

• MD040 fenced-code-language — fenced code blocks must declare a language.
• MD036 no-emphasis-as-heading — **Section title** on its own line must be a real heading.
• MD001 heading-increment — heading levels increment by one (no ## → ####).
• MD025 single-h1 — one top-level # H1 per document.
• MD024 no-duplicate-heading (siblings-only).

Path scope

**/*.md repo-wide, minus node_modules, .git, .venv, dist, build, htmlcov, .next, ui/out, contrib/, and **/CHANGELOG.md (keepachangelog format legitimately repeats ### Added/Changed/Fixed and would trip MD024).

Cleanups

• Files this branch touched on its first pass (CONTRIBUTING.md, README.md, AGENTS.md, ui/tests/*.md, the touched skills/*.md) — formatting only.
• One follow-up commit clearing the rest of the repo backlog the lint-all surface exposed (38 files): MD040 across skills/** and project READMEs; MD036 in tdd/SKILL.md, docs/AGENTS.md, mcp_server/README.md; MD025 cascade in api/README.md; MD001 in *AGENTS.md; MD024 dup in skill-creator/SKILL.md. Formatting and outline only — no copy, no code samples, no links changed.

Steps to review

Please review the rules and their scope more than how the cleaned-up files look now. The diff is mechanical; the config is the part we'll live with. If a rule feels wrong, a path should be (un)excluded, or you want to loosen/tighten something for files you maintain — say so here. Config is easy to change; baking in the wrong defaults is not.

1. Rule overview above + .markdownlint.json — anything you want disabled, tightened, or scoped differently?
2. .markdownlintignore — same question for path scope (vendored/build trees, CHANGELOGs, anything else you'd add).
3. Workflow + prek hook — .github/workflows/markdown-lint.yml and the markdownlint-cli entry in .pre-commit-config.yaml. Versions are pinned and kept in sync between the two.
4. If you own files under skills/**, */AGENTS.md, or */README.md — skim the diff for your file as a sanity check on the mechanical edits (code-fence languages, promoted headings, re-leveling). No copy, code, or links were changed.
5. Verify green locally: pnpm dlx --ignore-scripts markdownlint-cli@0.45.0 '**/*.md' — should exit 0.

Checklist

Community Checklist

• This feature/issue is listed in here or roadmap.prowler.com
• Is it assigned to me, if not, request it via the issue/feature in here or Prowler Community Slack

• Review if the code is being covered by tests. — The CI workflow itself is the test surface; it now runs on every PR touching *.md.
• Review if code is being documented following this specification https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings — N/A, no Python code changes.
• Review if backport is needed.
• Review if is needed to change the Readme.md — only formatting cleanup; no content change.
• Ensure new entries are added to CHANGELOG.md, if applicable. — CI/tooling only, no user-visible product change.

SDK/CLI

• Are there new checks included in this PR? No.

UI

• All issue/task requirements work as expected on the UI — no UI runtime change; only markdown docs reformatted.
• Screenshots/Video of the functionality flow (if applicable) - Mobile (X < 640px) — N/A.
• Screenshots/Video of the functionality flow (if applicable) - Table (640px > X < 1024px) — N/A.
• Screenshots/Video of the functionality flow (if applicable) - Desktop (X > 1024px) — N/A.
• Ensure new entries are added to CHANGELOG.md, if applicable. — N/A.

API

• All issue/task requirements work as expected on the API — no API runtime change.
• Endpoint response output (if applicable) — N/A.
• EXPLAIN ANALYZE output for new/modified queries or indexes (if applicable) — N/A.
• Performance test results (if applicable) — N/A.
• Any other relevant evidence of the implementation (if applicable) — N/A.
• Verify if API specs need to be regenerated. — N/A.
• Check if version updates are required (e.g., specs, Poetry, etc.). — N/A.
• Ensure new entries are added to CHANGELOG.md, if applicable. — N/A.

License

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[github-actions]

⚠️ Changes detected in the following folders without a corresponding update to the CHANGELOG.md:

• api
• ui
• prowler
• mcp_server

Please add an entry to the corresponding CHANGELOG.md file to maintain a clear history of changes.

[github-actions]

✅ Conflict Markers Resolved

All conflict markers have been successfully resolved in this pull request.

[github-actions]

🔒 Container Security Scan

Image: prowler-mcp:eabfc0c
Last scan: 2026-05-26 10:03:48 UTC

📊 Vulnerability Summary

Severity	Count
🔴 Critical	2
Total	2

2 package(s) affected

⚠️ Action Required

Critical severity vulnerabilities detected. These should be addressed before merging:

• Review the detailed scan results
• Update affected packages to patched versions
• Consider using a different base image if updates are unavailable

---

📋 Resources:

• Download full report (see artifacts)
• View in Security tab
• Scanned with Trivy

[github-actions]

🔒 Container Security Scan

Image: prowler-ui:eabfc0c
Last scan: 2026-05-26 10:05:30 UTC

📊 Vulnerability Summary

Severity	Count
🔴 Critical	2
Total	2

2 package(s) affected

⚠️ Action Required

Critical severity vulnerabilities detected. These should be addressed before merging:

• Review the detailed scan results
• Update affected packages to patched versions
• Consider using a different base image if updates are unavailable

---

📋 Resources:

• Download full report (see artifacts)
• View in Security tab
• Scanned with Trivy

[github-actions]

🔒 Container Security Scan

Image: prowler:eabfc0c
Last scan: 2026-05-26 10:07:55 UTC

📊 Vulnerability Summary

Severity	Count
🔴 Critical	5
Total	5

4 package(s) affected

⚠️ Action Required

Critical severity vulnerabilities detected. These should be addressed before merging:

• Review the detailed scan results
• Update affected packages to patched versions
• Consider using a different base image if updates are unavailable

---

📋 Resources:

• Download full report (see artifacts)
• View in Security tab
• Scanned with Trivy