docs: refresh reference section with category badges and dynamic index pages (#69)

* docs: normalize reference page titles to Title Case

* docs: add sidebar badges for definition types

* docs: add definition header with source link and category

* docs: add CSS for definition headers

* docs: extract helpers to reduce processDirectory complexity

* docs: replace type badges with category badges for agents only

* docs: upgrade skills index to LinkCard grid

* docs: upgrade agents index to categorized LinkCard grid

* docs: upgrade commands index to categorized LinkCard grid

* docs: prefix unused definitionType param to fix lint warning

* docs: dynamically generate reference index pages from enumerated entries

Replace hardcoded index.mdx files with dynamic generation in
transform-content.ts. Index pages are now built from the same
DefinitionEntry metadata collected during processDirectory, using
Starlight CardGrid/LinkCard components.

- Add generateIndexPage() with type-aware grouping (agents by category,
  commands by workflows/utilities, skills flat)
- Remove unused definitionType param from transformFrontmatter
- Add helper functions: cleanDescription, escapeAttr, firstSentence,
  renderLinkCard, renderCardGrid
- Simplify .gitignore to ignore entire reference/ directory
- Remove index.mdx skip guard from clean step
- Update docs/AGENTS.md to reflect generated index pages

* docs: add brainstorm, plan, and solution artifacts from reference refresh

Author: marcusrbrown

.gitignore

@@ -33,6 +33,4 @@ tests/tmp/
 # Docs build artifacts
 docs/dist/
 docs/.astro/
-docs/src/content/docs/reference/**
-!docs/src/content/docs/reference/**/
-!docs/src/content/docs/reference/**/index.mdx
+docs/src/content/docs/reference/

docs/AGENTS.md

@@ -25,17 +25,17 @@ bun run docs:preview    # Preview production build
 docs/
 ├── astro.config.mjs          # Site config (sidebar, social, base path)
 ├── scripts/
-│   └── transform-content.ts  # Content generator (156 lines)
+│   └── transform-content.ts  # Content generator (~390 lines)
 ├── src/
 │   ├── styles/custom.css     # Theme overrides
 │   └── content/docs/
 │       ├── index.mdx         # Landing page
 │       ├── getting-started/  # 2 manual pages (installation, configuration)
 │       ├── guides/           # 3 manual pages (architecture, conversion, creating-skills)
 │       └── reference/        # Generated — DO NOT EDIT
-│           ├── skills/       # 8 pages + index.mdx
-│           ├── agents/       # 11 pages + index.mdx
-│           └── commands/     # 9 pages + index.mdx
+│           ├── skills/       # 11 pages + index.mdx (all generated)
+│           ├── agents/       # 24 pages + index.mdx (all generated)
+│           └── commands/     # 9 pages + index.mdx (all generated)
 └── package.json
 ```
 
@@ -45,13 +45,13 @@ docs/
 
 | Source | Pattern | Output |
 |--------|---------|--------|
-| `skills/*/SKILL.md` | `SKILL.md` files | `reference/skills/<slug>.md` |
-| `agents/**/*.md` | All `.md` files | `reference/agents/<slug>.md` |
-| `commands/**/*.md` | All `.md` files | `reference/commands/<slug>.md` |
+| `skills/*/SKILL.md` | `SKILL.md` files | `reference/skills/<slug>.md` + `index.mdx` |
+| `agents/**/*.md` | All `.md` files | `reference/agents/<slug>.md` + `index.mdx` |
+| `commands/**/*.md` | All `.md` files | `reference/commands/<slug>.md` + `index.mdx` |
 
-Pipeline: `read file → parseFrontmatter → transformFrontmatter (name→title) → generatePage → write`
+Pipeline: `read file → parseFrontmatter → transformFrontmatter (name→title, agent category→badge) → generatePage → write`
 
-Each run cleans output dirs (preserves `index.mdx`) before regenerating. Slug collisions abort with error.
+Each run cleans output dirs before regenerating. Index pages (`index.mdx`) are dynamically generated from the same enumerated entries using Starlight `CardGrid`/`LinkCard` components. Agents are grouped by category; commands are split into Workflows and Utilities. Slug collisions abort with error.
 
 ## Where to Look
 
@@ -66,8 +66,8 @@ Each run cleans output dirs (preserves `index.mdx`) before regenerating. Slug co
 
 ## Notes
 
-- Reference pages under `reference/` are gitignored — always regenerated from source
-- `index.mdx` files in reference subdirs are manual (not generated, not cleaned)
+- Reference pages under `reference/` are gitignored — always regenerated from source (including `index.mdx`)
+- Only agents get sidebar badges (category: Review, Research, Design, Workflow); skills and commands have no badge
 - Script has its own `parseFrontmatter` (duplicates `src/lib/frontmatter.ts` logic)
 - Frontmatter `name` → Starlight `title`, `description` gets HTML tags stripped
 - Sidebar: Getting Started, Guides, Reference (Skills/Agents/Commands) — all autogenerated from dirs

docs/brainstorms/2026-02-12-reference-section-refresh-brainstorm.md

@@ -0,0 +1,60 @@
+---
+date: 2026-02-12
+topic: reference-section-refresh
+---
+
+# Reference section refresh (skills, agents, commands)
+
+## What we’re building
+
+We’re improving the docs site’s **Reference** section so that generated pages for **skills**, **agents**, and **commands** feel like a coherent, scannable reference—rather than a raw copy of source Markdown.
+
+Each reference page will render a **structured definition header** that surfaces essential metadata (from frontmatter) in a consistent layout, followed by the existing source body content. The goal is to make it immediately clear:
+
+- What the definition is
+- When to use it (at least via its description; deeper “when to use” stays in body)
+- Where it comes from (source path)
+
+We will also improve readability by generating **human-friendly headings** from names/slugs (e.g., `agent-browser` → `Agent Browser`) while keeping stable URLs.
+
+## Why this approach
+
+We want the reference pages to be **content-driven** (source Markdown remains canonical) but **presentation-consistent** (shared UI across all pages). The chosen approach is:
+
+- **Generate MDX pages** that render a shared Astro/MDX component for the header
+- Keep the remaining body content as-is (minimal transforms)
+
+This gives us consistent UI without duplicating formatting logic across hundreds of generated pages.
+
+## Key decisions
+
+- **Target experience:** “Structured API ref” style pages: a consistent, compact header + clean body.
+- **Implementation approach:** **MDX + shared components** (generator outputs an MDX wrapper that calls components living in `docs/src/components/...`).
+- **Metadata policy (default): Minimal (scannability-first).**
+  - Skills: `name`, `description`
+  - Agents: `name`, `description`, `category` (where applicable)
+  - Commands: `name`, `description`
+  - Plus: `source` (path) where available
+- **Title normalization:** Display titles should be derived from the canonical name/slug (e.g., kebab-case → Title Case).
+- **Source linking:** Include a **GitHub “View source”** link in the header.
+  - Repo: `marcusrbrown/systematic`
+  - Branch: `main`
+  - URLs derived from repo-relative paths for each definition file
+
+## Success criteria
+
+- Reference pages visually communicate “what/when/source” in under 5 seconds.
+- Titles/headings are human-readable without manual editing.
+- Styling/layout is consistent across skills/agents/commands.
+- Minimal metadata avoids clutter and keeps pages readable.
+- Generator output remains deterministic and friendly to sidebar autogeneration.
+
+## Open questions
+
+- **Title casing rules:** any special handling for acronyms (e.g., MCP, JSON), “v2”, etc.?
+- **Source linking details:** do we also show the plain path alongside the GitHub link (copyable), or link-only?
+- **Index pages:** should the reference landing pages become richer (e.g., CardGrid of categories/tags) or stay simple?
+
+## Next steps
+
+→ Move to `/workflows:plan` to decide the concrete generator output format (MDX shape), component API, and any minimal style system for the reference header.