docs: add pipeline extension recipe (kie.ai content:null workaround)

[lennney]

Description

Documents the headroom.pipeline_extension entry-point system that was previously only discoverable by reading source code. Adds a recipe-style guide covering available pipeline stages, entry-point registration, and a real-world example (normalizing content: null → content: "" for kie.ai Gemini endpoints).

Closes #1697

Type of Change

• Documentation update

Changes Made

• New docs/content/docs/pipeline-extensions.mdx — 147 lines covering:
  • When to use a pipeline extension
  • All pipeline stages table with use cases
  • Complete recipe for kie.ai content: null workaround
  • Entry-point registration (pyproject.toml)
  • --proxy-extension CLI flag + x-headroom-base-url routing
  • Extension contract + troubleshooting
• docs/content/docs/meta.json — register new page under Proxy Server section (+1 line)

Testing

• No code changes — docs-only PR
• Markdown renders correctly (verified locally)
• meta.json JSON is valid
• PR diff is scoped to 2 doc files only

Test Output

$ git diff --stat upstream/main...HEAD
 docs/content/docs/meta.json               | 1 +
 docs/content/docs/pipeline-extensions.mdx | 147 ++++++++++++++++++++++++++++++
 2 files changed, 148 insertions(+)

Real Behavior Proof

• Environment: headroom docs framework (Nextra, MDX)
• Exact command / steps: git diff upstream/main...HEAD -- docs/
• Observed result: 2 files changed, 148 insertions, 0 deletions. Only docs/ touched.
• Not tested: Full docs site npm run build (requires Node.js build environment)

Review Readiness

• I have performed a self-review
• This PR is ready for human review

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.

[JerrettDavis]

Thanks for writing this up. I think this should not merge in its current form because it conflates two different extension systems.

headroom.pipeline_extension is loaded by PipelineExtensionManager through discover_pipeline_extensions; the --proxy-extension flag and HEADROOM_PROXY_EXTENSIONS environment variable enable entries from the separate headroom.proxy_extension group, whose install call receives the FastAPI app/config. Documenting --proxy-extension kie-ai-compat for a headroom.pipeline_extension entry point will leave users with an extension that never runs.

A newer docs PR, #1712, covers the same issue without mixing those extension mechanisms and also documents x-headroom-base-url. My recommendation is to close this PR in favor of #1712, or revise it to clearly separate pipeline extensions from proxy extensions before it is considered again.

[lennney]

Closing per maintainer recommendation — superseded by #1712 which covers the same issue without mixing pipeline/proxy extension mechanisms.