feat(docs): invoke docs({ plugins })

[captjt]

What

@eqtylab/docs 0.4.0 declares a plugins option and exports the DocsPlugin / DocsPluginContext types, but nothing ever calls a plugin's setup. A consumer that passes plugins: [...] gets a build that silently registers nothing. This wires the hook up.

Why

We hit this while moving the Guardian docs (eqtylab/governance-platform-docs) onto the framework. Its API reference is written as a DocsPlugin, and the only way to run it today is a small adapter that calls setup from an ordinary Astro integration. That works, but an option that is accepted and ignored is a trap for the next consumer, and the extension point is the right home for generated sections that the framework does not ship itself (changelogs, CLI references, and so on).

This is independent of the native OpenAPI work in #158 → #160, which takes the content-collection route rather than the plugin hook; the two merge cleanly (checked with git merge-tree against feat/mic-73-openapi-pages). Once that chain lands, Guardian will drop its own plugin in favour of the built-in pages, and this hook remains for everything else.

Changes

• src/internal/run-plugins.ts (new): validates plugins entries, runs each setup in order inside astro:config:setup with the raw hook params as ctx.astro, and collects contributions. Runs after the framework has planned its own routes and before the runtime payload is sealed.
• addNavGroup groups are appended to sidebar.extra, so they reach the runtime through the existing config virtual module.
• addMdxComponents now takes module specifiers (Record<string, string>), served through a new virtual:eqty-docs/plugin-components module that mdx-components.ts spreads in last. A component object cannot cross into the runtime, which loads from node_modules, so passing one fails with a message naming the plugin and the component. This narrows the previously unknown-typed map; nothing could have used it before.
• Types injected for the new virtual module; README gains a "Plugins" section; CHANGELOG has an Unreleased entry.

Verification

• 5 new tests in tests/plugins.test.ts (ordering, replacement, error paths, virtual-module source); pnpm --filter @eqtylab/docs test passes all 108 docs tests. Lint, format check and pnpm --filter @eqtylab/docs build pass.
• End to end: packed this branch, installed it into the Guardian docs checkout, and built that site with docs({ plugins: [openApiPlugin(...)] }) instead of the adapter. The plugin logged as registered through the hook and the build emitted the same 241 pages, including all 143 operation pages with correct sidebar state.

🤖 Generated with Claude Code

[matthewmr-eqty]

Looks great, glad the plugins actually run now. I haven't run my OpenAPI pages against the Guardian specs yet, so looking forward to comparing the two.