feat(backstage): catalog-info + TechDocs + GitHub→Backstage docs sync

[olafkfreund]

What

Annotates skill_pool for Backstage and publishes the existing GitHub docs as TechDocs, plus automation to keep the two in sync.

Software Catalog — catalog-info.yaml

A skill-pool System (domain public, owner group:default/olafkfreund — same pattern as the ravn OSS project) with:

Entity	Kind	Relations
skill-pool-server	Component service	provides skill-pool-api; depends on db + object-store + cache
skill-pool-web	Component website	consumes skill-pool-api
skill-pool-cli	Component library	consumes skill-pool-api
skill-pool-api	API openapi	definition → openapi.yaml
skill-pool-db / -object-store / -cache	Resource	database / object-storage / cache

All four entity kinds were validated against the live Backstage instance before commit.

TechDocs

• openapi.yaml — faithful OpenAPI 3.0 spec built from docs/api.md (renders in the Backstage API explorer).
• mkdocs.yml — techdocs-core build, full nav mirroring docs/ + docs/wiki/.
• docs/backstage.md — catalog model + sync design.
• Local mkdocs build: 70 pages, no errors.

Docs sync automation

• scripts/sync-techdocs.py — regenerates docs/index.md from README.md (single source of truth) with TechDocs-aware link rewriting (docs/... stripped, code links → GitHub URLs). --check mode is the CI gate.
• .github/workflows/techdocs.yml — on every PR + main: verify README↔index sync and run a real mkdocs build. Optional publish job ships a pre-built site to a TechDocs S3 bucket when vars.TECHDOCS_PUBLISH=true; otherwise Backstage's local builder serves dir:. from main automatically.

How sync works end-to-end

1. catalog-info.yaml registered as a Location → Backstage re-reads on schedule.
2. techdocs-ref: dir:. → local builder rebuilds from mkdocs.yml on main.
3. CI gate guarantees main always has buildable, in-sync docs.

Notes

• The mkdocs build emits non-fatal warnings for pre-existing cross-references in source docs that link to code outside docs/ (e.g. ../../server/src/...); CI intentionally does not use --strict.
• pages.yml (the marketing showcase site) is untouched — separate concern from the docs corpus.

🤖 Generated with Claude Code