Production contract: kb-docs artifact, unified manifest, source-only registry, publish action, deployment repo

[oto-macenauer-absa]

The last contract changes before the knowledge base goes to production. After these land, a docs repo interacts with the knowledge base through one release asset, one manifest, one action, and one registry line — and the private deployment repo has a defined shape.

Goals

1. Rename the artifact. dist.tar.gz → kb-docs.tar.gz, so a docs release asset cannot be mistaken for the repo's own distribution package.
2. One manifest, owned by the docs repo. marketplace.json (packaged) and bundle.json (single-page) → a single kb-docs.json that always lists apps[]. A packaged site is a list of one.
3. No duplication. apps.json in the knowledge base says where an artifact comes from (repo + version, prebuilt, localPath) and nothing else. Name, description, icon, tags, slug and pages come from the artifact. The build rejects display fields in the registry.
4. Publishing is an action, not a copied workflow. Packaged repos consume actions/publish-docs the way single-page repos consume actions/publish-single-page-docs; both share one validate/pack/upload/notify library and one @v1 tag. Contract changes ship as action changes.
5. Drop the old name. data-mp-headless, .mp-*, MP_HEADLESS, marketplace.css, marketplaceVersion → kb. Hard cut, no shim.
6. Define the deployment repo. A reusable build-image.yml workflow here, a documented private-repo layout, a GitHub App for reading docs repos' releases, and repository_dispatch from the publish action so a docs release rebuilds the deployment.

Issues

#	Issue	Depends on
#74	Contract v1: kb-docs.tar.gz + unified kb-docs.json	—
#75	apps.json becomes source-only; the manifest is the source of truth	#74
#76	actions/publish-docs for packaged sites, shared action library, v1 tag	#74
#77	Rename marketplace / mp identifiers to kb (hard cut)	— (sequence, do not parallelise)
#78	Reusable build-image workflow + deployment repo definition	#75, #76

Suggested order: #77 (mechanical, first) → #74 → #75 and #76 in parallel → #78 → migrate AbsaOSS/knowledge-base-docs-example and cut v1.0.0.

Decisions already taken

• Unified manifest over two renamed ones: one install path in the build, one code path to test, the registry entry looks the same for every type.
• Hard cut over a compatibility window: nothing is in production, and every producer republishes through the action.
• GitHub App installation token over a PAT for the deployment build: scoped to contents: read, short-lived, adding a repo is an app install.
• repository_dispatch from the action plus a nightly schedule: publishes rebuild promptly, the schedule catches anything that did not notify.
• kbVersion is a string in the manifest and the actions carry a floating major tag, so the contract can evolve additively without breaking older consumers, and breaking changes have an obvious home ("2" / @v2).

Done when

• AbsaOSS/knowledge-base-docs-example publishes kb-docs.tar.gz through actions/publish-docs@v1 and its registry entry in this repo is { "repo": …, "version": "latest" }.
• git grep -i marketplace in this repo finds nothing.
• A private deployment repo can be created from examples/deployment-repo/ and contract/DEPLOYMENT.md without reading this repo's source.