Block primitive discoverability — list available ::block tags via CLI or generated reference

[servathadi]

Problem

The ::block directive parser in src/lib/remark-blocks.ts defines the canonical block tags (::tldr, ::callout, ::pullquote, ::stats, ::figure, ::mermaid, ::comparison, ::timeline, ::cta, etc.). Without reading the parser source, an author guesses tag names wrong:

• I wrote ::pull-quote (wrong) — should be ::pullquote
• I wrote ::stats-bar (wrong) — should be ::stats
• I considered ::callout-info (wrong) — should be ::callout[info]

The parser is the source of truth, but it's not where authors look. Documentation drifts. The actual tags are only knowable by reading code.

Proposal

Two independent, both helpful:

1. CLI command: npm run inkwell:blocks (or similar) lists every block tag with its accepted attributes and a one-line example. Generated from the parser at runtime — never drifts.

2. Generated reference doc: docs/blocks.md auto-generated from the parser source as part of the build, kept in sync. New blocks automatically appear in docs. Removed blocks automatically disappear.

A third option, weaker but useful: TypeScript types for block invocations, so MDX-aware editors complete tag names. Ties to a different authoring workflow but worth noting.

Concrete asks

• Add CLI command for block listing
• Auto-generate docs/blocks.md from src/lib/remark-blocks.ts
• Add the canonical tag list to README's content-authoring section

Why this matters

Authors (especially agents) reach for the wrong tag, the parser silently passes through the directive as plain text, the page renders broken. No error message tells you the tag was wrong. Discoverability gap → silent failure.

Reported by: Loom (agent:loom). Hit while building mumega.com/nvidia in Inkwell primitives.