feat(showcase): build the static gallery generator

[Muyideen-js]

Closes #256

Description

Build a static gallery generator that consumes the example catalog metadata and produces a browsable HTML showcase: an index page with category/maturity filtering and one detail page per example, each pulling its description from the example's own README.md.

Part of #256

Implementation approach

Decision: standalone Rust static-site generator (not an mdBook preprocessor).

The generator lives at tools/cougr-showcase/ as a workspace member. This approach was chosen because:

1. No mdBook setup exists yet — building a preprocessor would require standing up an entire mdBook config and book structure before the generator could be tested
2. A standalone Rust binary keeps the toolchain uniform with the existing Rust workspace (no Node, no additional CI tooling)
3. It can be easily wired into an mdBook build later (via a pre-build script that dumps generated pages into the book's source directory) once the docs site infrastructure exists in its own repository per the repository strategy

What it does

Step	Description
Parse catalog	Reads examples/README.md, extracting both the Canonical and Transitional example tables (name, category, focus)
Read descriptions	For each example, reads its local README.md — extracts the first substantive paragraph as the description
Extract APIs	Parses the "Cougr APIs used" section from each example's README to build a structured cougr_features list
Generate index	Produces index.html — dark-themed gallery with search bar, category filter buttons, and maturity filter buttons (Stable/Beta/Experimental) with client-side JavaScript filtering
Generate detail pages	Produces {example}.html — one page per example showing name, category, maturity badge, description, cougr_features list, GitHub source link, and related examples

Gallery index features

• Responsive grid layout using CSS Grid (auto-fill, minmax(320px, 1fr))
• Client-side filtering by category and maturity (togglable buttons, combinable with search)
• Search box filters by example name and description
• Maturity badges color-coded: green (Stable), amber (Beta), red (Experimental)
• Hover states on cards: elevation, accent border, reveals "View on GitHub" link

Detail page features

• Breadcrumb navigation back to gallery index
• Maturity badge, category tag, focus description
• Full description paragraph (no manual duplication — sourced from README.md)
• "Cougr APIs Used" section rendered as styled tags
• "View Source on GitHub" button linking to the example's directory
• "Related examples" grid showing up to 6 other examples

CI wiring

A new GitHub Actions workflow (.github/workflows/showcase.yml) triggers on pushes and PRs touching examples/, tools/cougr-showcase/, or related config. It:

1. Runs cargo clippy -p cougr-showcase -- -D warnings
2. Builds the generator: cargo build -p cougr-showcase
3. Runs the generator: cargo run -p cougr-showcase -- --output-dir site/showcase
4. Verifies output: checks that index.html and at least one detail page exist

Changes

• tools/cougr-showcase/Cargo.toml — New workspace tool crate (no dependencies, publish = false)
• tools/cougr-showcase/src/main.rs — Full generator implementation (~550 lines)
• tools/cougr-showcase/README.md — Usage documentation
• .github/workflows/showcase.yml — CI workflow for building and running the generator
• Cargo.toml — Added "tools/cougr-showcase" to workspace members
• .gitignore — Added site/showcase/ for generated output

Verification

cargo build -p cougr-showcase
cargo clippy -p cougr-showcase -- -D warnings
cargo run -p cougr-showcase -- --output-dir /tmp/showcase-test
ls /tmp/showcase-test/index.html      # should exist
ls /tmp/showcase-test/spawn_and_move.html  # should exist

Out of scope

• Preview/screenshot images (sibling sub-issue provides source images; generator gracefully omits them where missing)
• "Cougr Verified" badge logic (sibling sub-issue; generator renders whatever verification status the catalog data provides)
• Design tokens package (consumes, does not generate)

[drips-wave]

@Muyideen-js Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[salazarsebas]

Points 1-3 of #256 (index with category/maturity filters, client-side search, detail pages pulling cougr_features/README description) look solid. Point 4 isn't met: the issue asks for the generator to run as part of the docs site's existing CI build, not as a separate manual step — this PR adds its own standalone showcase.yml instead. Could you fold the generator into the docs-site build pipeline once that exists (see the related #274/#284 thread — we're bringing the cougr-site mdBook scaffold into this monorepo), rather than keeping it as an independent workflow? Also, right now CI only checks that files exist — could you add a couple of real tests for the generator logic itself?

[salazarsebas]

This looks well-structured and doesn't conflict with anything else on main. Just ask that you rebase onto the latest main before we merge, to make sure nothing has drifted.