refactor: make apps.json a source-only registry with one install path

[oto-macenauer-absa]

Closes #75. Part of #73.

Stacked on #80 (chore/kb-docs-contract), which is stacked on #79. Review in that order; this PR's base is #80's branch, so the diff here is only the registry work.

The duplication was worse than "duplicated"

apps.json restated everything the docs repo already declared. But the resolution never worked as documented: fetch-apps.js merged the manifest over the registry entry ("manifest wins"), build-vite.js discarded that result for packaged apps, and Astro's loadRegistry read apps.json alone.

Two consequences, both live on master:

• A catalog card showed whatever the onboarding PR typed, not what the repo published.
• pages never reached getAppPages. The Array.isArray(app.pages) branch in apps.js was dead code, and every packaged app was filesystem-crawled no matter what its manifest said.

A registry entry now names a source and nothing else

[
  { "repo": "AbsaOSS/my-docs", "version": "latest" },
  { "localPath": "../my-docs" },
  { "prebuilt": "tests/fixtures/my-docs.kb-docs.tar.gz" }
]

Display fields are rejected, not ignored. An onboarding PR that sets one has a mistaken idea of where metadata lives, and silently dropping it would leave the author waiting for a card that never changes.

One install path replaces two

stageEntry puts an artifact on disk — download, copy, or pack a local checkout — and is the only place the three sources differ. installArtifact then reads the manifest, validates it, copies one directory per declared app into apps/{slug}/, and checks the headless marker, identically for all of them. fetch-apps.js is now purely a downloader, and src/utils/single-page.js becomes src/utils/registry.js, generalised from bundles to every artifact.

Things that follow from having one path:

pages works	And is authoritative when present: the directory is not crawled, so nothing it happens to contain becomes a route the publisher did not ask for
The marker check runs everywhere	It used to run only on the GitHub path, so the prebuilt fixtures CI actually uses were never checked
No single-page registry type	A markdown bundle and a docs site are both artifacts with a manifest. The reading-column layout is inferred from the artifact (one HTML file, no pages) rather than declared in the registry
localPath can pack non-Node repos	Per-entry pack command, default npm run pack:kb, replacing a hard-coded npm run build:headless that could not run in the Python example repo at all
KB_REGISTRY	Selects the registry file, so a deployment repo owns its own list without forking this one (#78 needs this)
Size budget enforced	The numbers agreed in #74 are now checked on download
Unclaimed members reported	An archive directory no app declares is named in a warning rather than silently ignored

The fixture now tests the feature

The vendored artifact is one kb-docs.tar.gz whose manifest declares two apps from one tree:

• user-guide — no pages, so crawled. Six routes, including the admin page the inline-script hoisting tests need.
• guide-mirror — a pages list of four, deliberately omitting docs/some-new-page/index.html, which is present on disk.

That asymmetry is the test: the same file is a route under one app and not under the other. It also drops the artifact from 6.5 MB to 4.2 MB, by not duplicating the 4.8 MB vendored CMS bundle into the mirror.

Its HTML is now stamped with data-kb-headless="true". The old fixture had no marker anywhere — a gap nothing could catch, because nothing checked prebuilt artifacts. A fixture that does not meet the contract cannot verify the contract.

Verification

Suite	Result
npm test (embedded)	118 passed
playwright.config.ci.js (standalone)	22 passed
npm run build:headless	5 apps, 14 pages

The route list is the readable proof: guide-mirror emits exactly its four manifest pages, user-guide emits all six crawled ones.

Not run locally: test:container (needs Docker) — CI's image job covers it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PYtmxSeSXFg4wEXRcKCmAi