fix(docs): generate CLI reference for Astro Starlight

[ndimares]

Problem

The Documentation workflow (.github/workflows/documentation.yml) regenerates the CLI reference docs into the marketing-site and opens a PR. The marketing-site has migrated from Nextra to Astro (Starlight), but the doc generator still emitted Nextra-style output. Running the action against the new site would have reverted the migration and broken the Astro build:

• Missing title frontmatter — Starlight's docsSchema() requires a title on every page. The generator emitted no frontmatter for leaf pages and only asIndexPage: true for index pages, so regenerating would strip the hand-added titles → build failure.
• Duplicate H1 — the generator wrote a # <name> body heading, but Starlight renders the frontmatter title as the page H1.
• H1 inside command Long text — several commands' Long descriptions start with a # Heading, producing a second body H1. The migration had demoted these to ##.

Changes

internal/docs/docs.go:

• Emit title: "<name>" frontmatter on every page; keep asIndexPage: true on index pages.
• Drop the redundant # <name> body heading.
• Add demoteHeadings() to demote # → ## in Long/Details content, respecting fenced code blocks so # shell comments in usage examples are left intact.

cmd/docs/main.go:

• Remove the dead _meta.tsx entry from the preserve-list (a Nextra sidebar file that no longer exists in the Astro structure).

The workflow YAML already targets the correct Astro path (src/content/docs/speakeasy-reference/cli) and sets CLI_RUNTIME: docs, so no change was needed there.

Verification

Running the generator in-place over the actual committed marketing-site docs now yields a byte-for-byte match — the only diff is pull.md's --output-dir default, which is the current working directory and resolves to the identical path on the CI runner. Static hand-authored files (getting-started.mdx, mise-toolkit.mdx, docker.mdx) are preserved. go build, go vet, and gofmt are clean.

🤖 Generated with Claude Code

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}