KB class-hierarchy metadata degrades silently on cloud deployments: the image never builds the artifact and nothing fetches it

Context

Observed in a live cloud deployment's kb-server logs, as the only application-level line in the tail:

[ApiSource] Class hierarchy file not found at /app/docs/output/class-hierarchy.json.
'extends' metadata will be incomplete.

The server reports status: "healthy" and "All features are operational" alongside it.

The Problem

docs/output/class-hierarchy.json is a generated artifact — produced by buildScripts/docs/generateDocsJson.mjs — and the Knowledge Base treats it as a first-class input: it is a config leaf (hierarchyPath in ai/mcp/server/knowledge-base/configBase.mjs:266) and is listed among the files PrimaryRepoSyncService keeps in sync.

On a cloud deployment neither producer runs:

1. The deploy image build has no docs-generation step, so the artifact is absent from the image.
2. Primary-dev-sync — which would fetch it — is disabled in the cloud profile (NEO_ORCHESTRATOR_PRIMARY_DEV_SYNC_ENABLED=false), correctly, since a client deployment should not sync our dev repo.

So there is no path by which the file can exist on such a deployment, and get_class_hierarchy plus every extends-bearing answer is quietly incomplete. Health stays green, because a missing optional input degrades rather than fails.

Not a regression — no cloud deployment has ever had this artifact.

The Architectural Reality

Degrading rather than crashing on a missing enrichment input is the right call; a KB that refuses to start because extends metadata is unavailable would be worse. The gap is that the degradation is reported only as a log line, in a component whose logs an operator has no reason to read while healthcheck says healthy — so the deployment is permanently and invisibly less capable than intended.

This is the same shape as two siblings filed today: the system knows something the operator cannot see. Here it is even quieter, because nothing failed.

Two candidate fixes, and the choice is a real decision rather than an implementation detail:

• Build it into the image — the artifact is derived from source already present at build time, so this is the self-contained option and needs no runtime fetch.
• Declare it optional and surface the degradation — if cloud deployments are not expected to carry it, healthcheck should say so instead of claiming all features operational.

These are not exclusive; the first makes the capability whole, the second makes any future absence visible. My read is that both belong, with the build step as the primary.

Acceptance Criteria

• Decide and record whether cloud deployments are expected to carry class-hierarchy metadata. Everything else follows from that; the ticket should not proceed on an assumed answer.
• If expected: the deploy image generates docs/output/class-hierarchy.json at build time, verified by asserting the file exists in a built image.
• Either way: healthcheck reports the degradation instead of "All features are operational" while an input it depends on is absent — a green health check must not coexist with a known-incomplete capability.
• get_class_hierarchy states that its answer is incomplete when the artifact is missing, rather than returning a partial result indistinguishable from a complete one.
• A fixture pins the degraded path, so the honest-reporting behaviour cannot regress once the file is present in CI.

Out of Scope

• Changing what ApiSource extracts, or the hierarchy format.
• Re-enabling primary-dev-sync on client deployments — correctly disabled.

Related

• #16056 · #16060 — same class: the system knows something the operator cannot see
• #16057 — the other KB-corpus gap from the same probe