docs: generate level catalog

[jonathanperis]

Summary

• add a generated docs/wiki/level-catalog.md inventory for every levels/*.toml stage, including progression links, music, starts, configured resources, and content counts
• add tools/generate_level_catalog.py, make level-catalog, docs package scripts, and freshness checks through make docs-drift
• wire the level catalog into the Astro docs sidebar/labels and index page, and expand docs CI path filters for levels/** and the catalog generator
• extend drift checks to verify generated catalog coverage, last_star collectible counts, last_star.next_phase values, and agent context docs freshness

Validation

• RED: python3 tools/generate_level_catalog.py --check initially failed because the generator/catalog did not exist
• make level-catalog
• make docs-drift
• cd docs && mise exec node@24.13.1 -- bun run lint
• cd docs && mise exec node@24.13.1 -- bun run build
• make validate-levels
• make test CC=clang
• dummy SDL make smoke CC=clang SMOKE_FRAMES=5 SMOKE_SEED=1
• make web
• git diff --check
• independent review twice; first review caught incorrect top-level next_phase parsing and missing last_star in collectible counts, both fixed; final review caught docs workflow path filters, fixed

Notes

• The generated catalog surfaced a pre-existing content mismatch: levels/02_lugio_02.toml has screen_count = 11 while its description says "Twelve screens". I left the source level prose unchanged in this docs-generation PR.

Summary by CodeRabbit

• New Features

  • Added Level Catalog documentation page showcasing available levels, progression flow, and content metrics (screens, enemies, hazards, collectibles).

• Documentation

  • Updated build system and CI documentation with new targets and checks.
  • Enhanced level-completion control instructions with keyboard shortcuts (Esc/Back exits overlays).

• Chores

  • Added automated validation to ensure documentation consistency and catalog freshness across builds.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces an automated level catalog system that generates and maintains a living inventory of game levels from their TOML definitions. The catalog appears in the documentation, is validated for freshness alongside other drift checks, and integrates into the build system via Make and npm scripts.

Changes

Level Catalog Generation and Integration

Layer / File(s)	Summary
Catalog generation tool tools/generate_level_catalog.py	Implements the catalog generator: TOML loading, markdown formatting helpers, aggregation of level counts (enemies, hazards, collectibles, surfaces, visual layers), per-level metadata extraction (screens, player start, music, floor tiles, hearts, next phase), and a CLI supporting --check for staleness detection.
Catalog drift validation tools/check_docs_drift.py	Adds two new validation functions: check_level_catalog_doc() ensures all levels/*.toml files are documented in the catalog with correct references and next-phase links, and check_agent_context_docs() ensures AGENTS.md and CLAUDE.md reflect the current test suite count and required context tokens.
Make and npm targets Makefile, docs/package.json	Declares .PHONY level-catalog, adds level-catalog target to run the generator, updates docs-drift to verify catalog freshness before checking drift, and mirrors both targets in npm scripts.
CI workflow triggers .github/workflows/docs.yml	Extends docs workflow to trigger on changes to levels/**, tools/check_docs_drift.py, and tools/generate_level_catalog.py.
Documentation sidebar and routing docs/src/lib/docsSidebar.ts, docs/src/pages/docs/[...slug].astro, docs/wiki/index.md	Registers level-catalog section in the "Content & Assets" sidebar category, adds slug-to-label mapping, and inserts a quick-links entry in the docs homepage.
Generated catalog content docs/wiki/level-catalog.md	Contains summary totals (3 levels, 23 screens, 41 enemies, 64 hazards, 80 collectibles), level progression table, and per-level sections with source file links, metadata (screens, player start, music/volume, floor tiles, hearts), next phase references, and grouped content counts with TOML array references.
Build target documentation docs/wiki/build-system.md	Documents the new make level-catalog target and updates make docs-drift description to include the freshness verification step.
Agent and CI documentation AGENTS.md, CLAUDE.md	Updates CI gate descriptions from 11 tests to 13 tests, documents additional checks (level-catalog freshness, semantic docs drift, sanitizer smoke), and clarifies terminal overlay control (Esc/Back to exit, Enter/Space/Start to advance next_phase).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: generate level catalog' accurately describes the primary change: adding a generated level catalog documentation system with supporting tools and CI integration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/generated-level-catalog

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/wiki/index.md`:
- Line 28: Replace the relative fragment link "[Level Catalog](`#level-catalog`)"
with an absolute docs route anchor to avoid markdownlint MD051; update the link
target to the full docs path (e.g., "[Level
Catalog](/docs/wiki/#level-catalog)") while ensuring the anchor matches the
header id on the target page so navigation still works.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 291c0672-ef87-49c3-887b-e719599b6102

📥 Commits

Reviewing files that changed from the base of the PR and between f4108ea and 1f47908.

📒 Files selected for processing (12)

• .github/workflows/docs.yml
• AGENTS.md
• CLAUDE.md
• Makefile
• docs/package.json
• docs/src/lib/docsSidebar.ts
• docs/src/pages/docs/[...slug].astro
• docs/wiki/build-system.md
• docs/wiki/index.md
• docs/wiki/level-catalog.md
• tools/check_docs_drift.py
• tools/generate_level_catalog.py

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use an absolute docs anchor to avoid markdown fragment lint drift.

#level-catalog is not a fragment defined in this markdown file, so markdownlint flags it (MD051). Pointing to the docs route anchor keeps navigation intent and avoids fragment-validation noise.

Suggested diff

-| [Level Catalog](`#level-catalog`) | Generated inventory of every `levels/*.toml` stage, progression link, and content count |
+| [Level Catalog](/super-mango-editor/docs/#level-catalog) | Generated inventory of every `levels/*.toml` stage, progression link, and content count |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| [Level Catalog](#level-catalog) | Generated inventory of every `levels/*.toml` stage, progression link, and content count |
	| [Level Catalog](/super-mango-editor/docs/#level-catalog) | Generated inventory of every `levels/*.toml` stage, progression link, and content count |

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 28-28: Link fragments should be valid

(MD051, link-fragments)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/wiki/index.md` at line 28, Replace the relative fragment link "[Level
Catalog](`#level-catalog`)" with an absolute docs route anchor to avoid
markdownlint MD051; update the link target to the full docs path (e.g., "[Level
Catalog](/docs/wiki/#level-catalog)") while ensuring the anchor matches the
header id on the target page so navigation still works.