Migrate to the knowledge-base v1 contract: kb-docs.json, kb-docs.tar.gz, publish-docs action

[oto-macenauer-absa]

Tracks this repo's side of AbsaOSS/knowledge-base#73 (the production contract), specifically AbsaOSS/knowledge-base#74 (artifact + manifest), AbsaOSS/knowledge-base#76 (the publish action) and AbsaOSS/knowledge-base#77 (the mp → kb rename). Blocked until those ship v1.

What changes

The knowledge base stops recognising dist.tar.gz + marketplace.json. This repo publishes kb-docs.tar.gz with a kb-docs.json manifest, and does so through the reusable action instead of the hand-rolled tar + softprops/action-gh-release steps in .github/workflows/pack.yml. All display metadata (name, description, icon, tags, slug, pages) lives here and only here; the registry entry in the knowledge base shrinks to { "repo": "AbsaOSS/knowledge-base-docs-example", "version": "latest" }.

Before / after

	Today	After
Manifest	marketplace.json (marketplaceVersion, one app at the top level)	kb-docs.json (kbVersion, apps: [ … ])
pages navigation	written into dist/marketplace.json by pack.sh / pack.py; never actually read by the knowledge base	written into kb-docs.json at pack time; honoured by the knowledge base
Headless marker	data-mp-headless="true" in theme/main.html	data-kb-headless="true"
Release asset	dist.tar.gz = dist/ + marketplace.json	kb-docs.tar.gz = kb-docs.json + user-guide/ (the built dist/)
Packing + upload	inline in pack.yml and in scripts/pack.sh / pack.py	uses: AbsaOSS/knowledge-base/actions/publish-docs@v1
Validation	inline Python snippet checking five keys	the action validates against the contract schema and verifies the built HTML

Scope

• marketplace.json → kb-docs.json:

  {
    "kbVersion": "1",
    "apps": [{
      "slug": "user-guide",
      "name": "Knowledge Base User Guide",
      "description": "Everything you need to create and publish your own documentation to the Knowledge Base — tools setup, template walkthrough, and registration steps.",
      "icon": "book-open",
      "tags": ["guide", "getting-started", "template"],
      "entryPoint": "index.html"
    }]
  }

• scripts/pack.sh and scripts/pack.py: keep the --headless build (mkdocs, showcase entry point, auto-generated nav) and keep generating the pages list, but write it into the apps[0].pages of a kb-docs.json placed next to dist/ instead of into dist/marketplace.json; stop producing the tarball — that is the action's job. Keep a --pack (or similar) local option that runs the same packing the action does, so a developer can inspect the artifact without a release, once the action exposes it as a CLI
• .github/workflows/pack.yml: build headless, then uses: AbsaOSS/knowledge-base/actions/publish-docs@v1 with manifest: kb-docs.json, dist: dist. Drop the inline validation, the tar step and softprops/action-gh-release. The action attaches to an existing release, so either keep creating the release first (a minimal gh release create step) or switch the trigger to release: published like the single-page workflow. Set permissions: contents: write
• Optional notify-repo / notify-token inputs wired once a deployment repo exists (Deployment: reusable build-image workflow, --strict registry mode, and the private deployment repo definition knowledge-base#78)
• theme/main.html: data-mp-headless → data-kb-headless; any mp- class names → kb-
• README.md, docs/publishing.md, docs/index.md, CLAUDE.md: new file names, the two-line registry entry, "knowledge base" instead of "marketplace" throughout
• Bump package.json version, tag v2.0.0, confirm the release carries kb-docs.tar.gz and nothing else the knowledge base would look for
• Follow-up PR in AbsaOSS/knowledge-base: trim this repo's apps.json entry and regenerate tests/fixtures/docs-example.kb-docs.tar.gz from the new release so the vendored fixture is real action output

Notes

• Hard cut: the knowledge base build does not accept the old asset or manifest after Contract v1: rename dist.tar.gz to kb-docs.tar.gz and unify marketplace.json + bundle.json into kb-docs.json knowledge-base#74. Until this lands, the sibling optional entry in the knowledge base's apps.json will be skipped with a warning.
• This repo is the template other teams copy. Whatever the final pack.yml looks like is what every packaged docs repo will look like, so keep it minimal: checkout, setup-python, build, one uses:.