docs: update learn page statistics and add CI/CD workflow

[parthrohit22]

What does this PR do?

Closes out the remaining drift documented in #228. Fixes every stale count on the Learn page
(not just the five the first pass covered), fixes the four stale counts in README.md, and
extends .github/scripts/update_learn_page.py / .github/workflows/update-learn-page.yml so
both files are regenerated from the codebase on every push to dev and can no longer drift.

Type of change

• New scan rule
• Remediation playbook
• Bug fix
• Dashboard/front-end work
• API endpoint
• Documentation
• Compliance mapping

Rule details (if applicable)

Not applicable — this PR adds no scanner rule. It only reads rule metadata to produce counts.

Testing

• Tested against a real Azure free trial subscription — not applicable, no Azure API calls
• Returns correct JSON output — not applicable, no scanner or API output
• All seven CI checks pass
• No hardcoded credentials or secrets

Verification actually performed:

• ruff check . and ruff format --check . — clean repo-wide.
• python -m bandit -r .github/scripts/ — no issues.
• python -c "import yaml; yaml.safe_load(open('.github/workflows/update-learn-page.yml'))" — valid.
• Derived every number from the filesystem before writing anything: ls scanner/rules/az_*.py | wc -l → 65,
  ls playbooks/cli/*.sh | wc -l → 65, grep -l 'SEVERITY = "HIGH"' scanner/rules/az_*.py | wc -l → 38.
  Cross-checked every rule's declared PLAYBOOK field against the filename-derived path — 0 orphans
  either direction.
• Idempotency, both files: reverted docs/learn/index.html and README.md to their pre-PR
  committed content, ran the script — output was byte-identical to the version already staged
  in this PR; a second run was a true no-op (git diff empty).
• Fail-loud path, tested in isolation: reworded the hero-terminal HTML so the regex could not
  match — the script correctly named exactly that pattern and exited 1, and confirmed no file
  was written on that failure.
• Empty-input guard, tested in isolation: pointed RULES_DIR/PLAYBOOKS_DIR at an empty temp
  directory — main() returned 1 and refused to write zeroes.
• Missing-SEVERITY/CATEGORY warning path, tested in isolation with synthetic rule files —
  correctly named the offending file without failing the run.
• Ran the actual DCO checker the repo uses in CI (python scripts/check_dco.py <base> <head>)
  against this branch — sign-off verified.

Related issue

Closes #228

Checklist

• Every commit includes a DCO Signed-off-by trailer (git commit -s; see docs/dco.md)
• My code follows the rule template in CONTRIBUTING.md — no new rule; Python follows the
  repo's Ruff/PEP 8 and type-hint standards
• I added or updated the matching CLI playbook — not applicable, no new rule
• I added or updated all four compliance framework mappings — not applicable, no new rule
• I have not committed any real Azure credentials
• My branch name follows the convention — docs/update-learn-page-and-add-cicd, matching
  the docs/description form in CONTRIBUTING.md

True numbers (derived from the filesystem, verified before any edit)

Metric	Value
Rules (scanner/rules/az_*.py with RULE_ID)	66
Playbooks (playbooks/cli/*.sh)	66
Orphans (rule↔playbook)	0
HIGH / MEDIUM / LOW / CRITICAL severity	38 / 23 / 4 / 1
Categories	Identity 15, Network 15, Supply Chain 8, KeyVault 6, Kubernetes 6, Storage 5, Compute 4, Database 4, PostQuantum 3

Rebased onto dev after AZ-KV-006 merged in #235; the script picked the new rule up on its own
and moved KeyVault 5 → 6, MEDIUM 22 → 23 and both totals 65 → 66 with no hand-editing. That is
the drift-resistance this PR is for, so the numbers above will keep moving as rules land.

The 1 CRITICAL rule (AZ-SC-005) has no box in the Learn page's severity-distribution UI,
which is hardcoded to a 3-column HIGH/MEDIUM/LOW grid — documented as a known limitation, not
fixed here (see "Notes for reviewers").

Changes

File	Change
docs/learn/index.html	All previously-stale content fixed, not just the metric tiles: hero terminal 39 → 66 dynamic checks; severity boxes HIGH 22 → 38, MEDIUM 13 → 23 (LOW was already correct at 4); "Coverage by category" chart fully regenerated — previously omitted Supply Chain (8) and Kubernetes (6) entirely and undercounted Identity 4 → 15; removed a "known cleanup item" note about KeyVault vs Key Vault naming that the chart fix resolves (the chart now renders the category string the code actually declares); rewrote the "Known gaps" card's "counts are checked and updated with each release" claim to accurately describe what's CI-generated vs. hand-maintained.
README.md	Fixed 4 stale counts: Misconfiguration Scanner feature-table row (51 → 66, and added the previously-unmentioned "supply chain" category), Remediation Playbooks row (51 → 66), and both Mermaid diagram nodes (Scanner Engine, Azure CLI Playbooks).
.github/scripts/update_learn_page.py	Extended to cover the hero terminal line, all three severity boxes (previously only HIGH), and to fully regenerate the category chart's rows/counts/bar-widths from real per-category data (a new category now appears automatically instead of being silently dropped). Added render_readme() so the same script now also fixes README.md. Every substitution is tracked via re.subn; if any pattern matches zero times the script prints which one and exits non-zero instead of silently doing nothing and exiting 0. Rule files with no parseable SEVERITY/CATEGORY are now warned about by name. Still idempotent.
.github/workflows/update-learn-page.yml	Extended to diff, git add, and commit README.md alongside docs/learn/index.html. Renamed to reflect the wider scope. SHA pins and permissions: contents: write unchanged from the first pass.

Decision: README.md is now automated, not left as a manual step

The task called for deciding — and stating clearly — whether to extend the workflow to also
keep README.md current, or leave that update as a one-time manual fix. I extended it: the
whole point of this issue is closing the exact class of drift where a doc's numbers silently
fall out of sync with the codebase, and README.md's 4 stale counts are the same failure mode
in a second file. The substitution surface is small and well-bounded (2 feature-table rows, 2
Mermaid nodes), reuses the same tested apply_replacements()/fail-loud machinery already built
for the Learn page, and is the only choice consistent with the "Known gaps" card now stating
that these stats are CI-generated. README.md's "30+ scan rules" roadmap checklist item and
other prose are unrelated to this PR's scope and were left untouched.

Notes for reviewers

• Filed as a factual, no-marketing status comment on docs: update Learn page statistics and add CI/CD for auto-updates #228 before making any change, listing
  every stale location by file/line and the true numbers — see the issue thread.
• Real discrepancy, not fixed in this PR (flagging for a follow-up issue):
  scanner/engine.py::load_rules() — the code that actually executes rules at scan time —
  discovers rule modules with RULES_DIR.glob("*.py"), excluding only filenames starting with
  _. It does not require the az_*.py prefix or a RULE_ID, unlike ci.yml's
  structure-validation job and this script, which both use the narrower convention. Today all
  three agree on 65 only because scanner/rules/ happens to contain no stray file outside
  those two patterns — nothing enforces that. A leftover or misnamed .py file with a scan()
  function would be loaded and executed in production without being validated by CI or counted
  in either doc.
• Branch protection on dev, from the first review round: I don't have admin visibility
  into the repo's protection rules (only push access), so I can't fully confirm whether
  GITHUB_TOKEN can push directly to dev. GET /repos/.../rules/branches/dev (readable with
  plain read access) currently returns no effective rules, which suggests direct pushes are not
  blocked, but please verify in Settings → Branches before relying on that. If pushes are
  blocked, this workflow needs to open a PR instead of committing directly — I have not made
  that change silently.

[Vishnu2707]

CI is failing @parthrohit22 - have a look at it!

[parthrohit22]

CI is failing @parthrohit22 - have a look at it!

FIXED . THANK YOU

[Vishnu2707]

@ritiksah141 , review this PR pls, since your approved it earlier and @parthrohit22 has done some new force pushes.

[ritiksah141]

@Vishnu2707 I approved this PR as it is related to the his own learns website and doesn't affect the core of the repo and mainly his own seperate deployment

[parthrohit22]

Rebased onto dev and re-ran the generator. It's now 66 rules / 66 playbooks, 38 HIGH / 23 MEDIUM / 4 LOW.

The shift came from AZ-KV-006 landing in #235 after this branch was cut. The script picked it up on its own — KeyVault moved 5 → 6 in the category chart, MEDIUM 22 → 23, both totals 65 → 66, no hand-editing anywhere. That's the behaviour the issue was asking for, so it was a decent accidental test of it.

Everything from the earlier round is in:

• hero terminal, all three severity boxes and the category chart are generated now, not just the metric tiles
• MEDIUM and LOW are computed alongside HIGH rather than assumed
• every substitution goes through re.subn, and the script exits non-zero naming the pattern that failed — so a reworded sentence can't slip through as a green no-op
• README is covered by the same script: feature table, playbook count, and both Mermaid nodes

Updated the PR body and #228 to match the current numbers.

One thing I'd like a second opinion on before this goes in. The workflow commits straight to dev, and it's the only workflow in the repo that pushes anything. I can see dev is protected but I can't read the ruleset with my access, so I can't confirm GITHUB_TOKEN is allowed to write to it. If it isn't, this fails on every merge to dev and the fix is to have the workflow open a PR instead of committing directly.

@Vishnu2707 could you check Settings → Branches and say which you'd prefer? Happy to switch it to the PR-based flow if that's the safer default — it's a small change and I'd rather do it now than find out from a red X.

Known limitation, calling it out rather than leaving it quiet. The severity grid is a hardcoded three-column HIGH/MEDIUM/LOW layout, so the one CRITICAL rule (AZ-SC-005) has nowhere to render. At 66 rules the three boxes sum to 65, which is visible to anyone who adds them up. I'd rather not widen this PR any further — happy to add a fourth box or relabel the grid as a follow-up, whichever reads better to you.

Two things found while working on this, both filed separately rather than folded in:

• bug: Live Demo API returns 503 and is hardcoded as the frontend production fallback #243 — the Render API under Live Demo is returning 503 with a Service Suspended page. It's referenced in seven source files, including the frontend's production fallback URL in api.js and aiApi.js, so the deployed dashboard is calling a dead backend unless Vercel sets VITE_API_URL. That's wider than a README fix and needs a decision on whether the service is coming back.
• bug: scanner engine loads rule modules that CI validation and doc counts never see #244 — scanner/engine.py discovers rules with glob("*.py") while CI validation and this script both use az_*.py. All three agree on 66 by coincidence, not by enforcement. This is the follow-up I mentioned in the PR description.

[Vishnu2707]

@ritiksah141 - review this pls.

[ritiksah141]

Blocking issue — .github/workflows/update-learn-page.yml:47

actions/checkout leaves the runner in a detached HEAD state by default. As a result, the final bare git push has no current branch/upstream and will fail with fatal: You are not currently on a branch. The workflow therefore cannot publish the refreshed documentation after a push to dev.

Please either check out the branch explicitly or push the detached commit to the target branch, for example:

git push origin HEAD:${{ github.ref_name }}

Please verify the commit-and-push path in CI before merging.

[Vishnu2707]

@parthrohit22 , the conflicts and requested changes needs to be addressed to go ahead with the merge.

[parthrohit22]

Ready for review

PR #230 has been updated with the review follow-up:

• .github/scripts/update_learn_page.py now emits an explicit stderr warning when severity counts outside the HIGH/MEDIUM/LOW chart are excluded, including the excluded severity counts.
• The script was Ruff-formatted so the CI formatting check passes.

Validation completed:

• Ran the updater against docs/learn/index.html and README.md; it exited successfully, reported the expected CRITICAL: 2 exclusion, and produced no documentation diff.
• Ruff check and format check pass.
• GitHub Actions CI is fully green, including CI Summary.

Review commits: 209b725, 42ffda1.

[TFT444]

Great work @parthrohit22, the fail-loud substitution tracking and idempotent design are exactly right. One blocker:

1. Rules/playbooks mismatch: the regenerated docs now say 95 rules / 96 playbooks, but the README row still claims "Every rule ships with a matching playbook". Cause: playbooks/cli/review_enterprise_resilience.sh is an orphan no rule references. Your "0 orphans" check was true at 66/66 but dev moved. Please add a parity check to the script (fail/warn on rule count != playbook count), since this is exactly the drift class this PR exists to catch.

Two nits, same push if you like: collect_rule_stats() counts files without RULE_ID while count_rules() excludes them, so the severity boxes can disagree with the headline total; and html.escape(name) in render_category_rows() would be cheap insurance.

Fix the parity issue and this is good to go from my side.

[parthrohit22]

@TFT444 Updated:

• Parity check fixed. The root cause was count_playbooks() counting every *.sh file in playbooks/cli/, which also picked up review_enterprise_resilience.sh -- a shared helper that several fix_*.sh wrappers exec into, not a playbook any single rule owns. Replaced it with find_matching_playbooks(), which mirrors the fix_<rule filename stem>.sh convention ci.yml's playbook_check step already enforces, derives the count from actual rule-to-playbook matches, and fails loudly if a rule has no matching playbook or the two counts still disagree. Unmatched files are now a non-fatal warning instead of silently inflating the total. Regenerated docs now correctly read 95 rules / 95 playbooks, and the README's "every rule ships with a matching playbook" claim is true again.
• Both nits fixed in the same push. collect_rule_stats() now skips files with no parseable RULE_ID, matching count_rules()'s own filter, so the severity-box totals can't disagree with the headline count. render_category_rows() now HTML-escapes the category name before embedding it.

Ran the updater against the current tree -- clean exit, no further diff. Ruff check/format clean. CI is green including CI Summary.

Latest commit: 780113a.

[ritiksah141]

@parthrohit22, all good just need to be rebased once the #317 Lands with the dev and good to go

[parthrohit22]

@ritiksah141 Rebased onto the latest dev (9a84012). Ran the generator afterward - no drift, statistics are already current. Full suite and ruff still clean.

One CI note so it's not mistaken for something new: SCA (pip-audit) is currently failing on this branch because dev still has chromadb==0.4.24 (CVE-2026-45830/45833) - that's #317, not anything in this PR. It's approved and just hasn't merged yet. Once it lands I'll rebase again and this clears on its own, as you flagged.

[TFT444]

The requested fixes are addressed and the current checks pass. Approving.

[m-khan-97]

@parthrohit22, this is approved and green, but it is now two commits behind dev. Please rebase once more and rerun CI so the generated statistics are verified against the actual merge base.