Build: option to skip a broken documentation artifact with a warning instead of failing

Start in scripts/build-vite.js and trace the existing registry, extraction, validation, checker, and installation flow through scripts/fetch-apps.js, scripts/artifacts.js, src/utils/registry.js, and scripts/check-artifact.js. Read .github/workflows/build-image.yml, CLAUDE.md, and contract/DEPLOYMENT.md for the requested flag and documentation surfaces. Done means isolated failures warn and skip cleanly, skipped entries are recorded, all-skipped builds fail, and existing default behavior remains unchanged with the requested hermetic tests.

Problem

One broken documentation artifact fails the whole knowledge base build. Every registry entry is all-or-nothing: if any single repo publishes a bad kb-docs.tar.gz, the deployment cannot be rebuilt at all — including for the other, perfectly healthy docs — until that repo re-publishes or someone edits the registry.

Today the only way to skip an entry is "optional": true, and that is narrow on purpose:

• it only covers a missing prebuilt/localPath artifact (scripts/build-vite.js, the registeredApps filter);
• it is rejected outright by KB_STRICT, i.e. in every production build.

Anything else wrong with an artifact still aborts the build, e.g.:

• Release / asset download fails (scripts/fetch-apps.js: missing release, missing kb-docs.tar.gz, network/auth error)
• unsafe or corrupt archive (scripts/artifacts.js: traversal, absolute path, symlink, bad gzip)
• missing or invalid kb-docs.json (src/utils/registry.js manifest validation)
• wrong package structure (declared app directory missing, pages pointing at files that do not exist)
• an error finding from the contract checker (scripts/check-artifact.js) in a strict build
• an entry that produces no apps (strict)
• a slug that collides with another artifact's (resolveRegistry)

Proposal

Add a build parameter that turns a per-entry failure into a warning + skip instead of a build failure.

• Flag --skip-failed / env KB_SKIP_FAILED=true on scripts/build-vite.js (name open to bikeshedding), plus a matching skip-failed input on .github/workflows/build-image.yml so a deployment repo can opt in.
• Default off — current behaviour (fail fast) is unchanged unless asked for.
• When on, each registry entry is staged, extracted, validated, checked and installed inside its own try/catch. On any error:
  • log a warning naming the source (owner/repo@version) and the reason;
  • remove whatever that entry already wrote to apps/{slug}/ / public/{slug}/, so no half-installed app reaches Astro;
  • leave it out of the expansion map, so the catalog and masthead navigation never link to it;
  • continue with the next entry.
• Record skipped entries in dist/kb-build.json (e.g. skipped: [{ source, version, reason }]) and in the GitHub job summary, so a skipped doc is visible rather than silently absent.
• The build still fails if every entry is skipped (never publish an empty knowledge base), and on errors that are not attributable to one entry (registry file unreadable/invalid, astro build itself failing, stylesheet alias step).

Open questions

1. Interaction with KB_STRICT. Strict currently exists so that "a registered app that cannot be fetched is a broken deployment, not something to skip with a warning". Options:
   • KB_SKIP_FAILED is allowed together with strict, and strict keeps only its registry-level guarantees (no prebuilt/localPath/optional, non-empty registry), while per-artifact errors become skips; or
   • the two are mutually exclusive and the build refuses the combination.
     Leaning to the first: a production deployment is exactly where one team's broken release should not block everyone else's docs.
2. Should a skip ever fail the job? e.g. exit 0 but set a GitHub Actions warning annotation, or an optional max-skipped threshold.
3. Fallback to the previous good version? Out of scope here, but worth noting: instead of dropping an entry, the build could fall back to the last release that passed. Could be a follow-up.
4. Slug collisions — skip both entries, or the later one in registry order?

Acceptance criteria

• New flag/env/workflow input, off by default, documented in CLAUDE.md (Environment Variables), contract/DEPLOYMENT.md and build-image.yml input description.
• With the flag on, each failure class listed above skips only the offending entry with a warning; the rest of the knowledge base builds and deploys.
• Skipped entries appear in dist/kb-build.json and the job summary with their reason.
• No leftover files from a skipped entry in apps/, public/ or dist/; no catalog card or nav link to it.
• All entries skipped → build fails.
• With the flag off, behaviour is byte-for-byte unchanged (existing suites stay green).
• Tests: a hermetic registry with one good fixture plus one broken artifact per failure class (bad archive, missing manifest, invalid manifest, missing app dir, checker error) — build succeeds, only the good app is in dist/, kb-build.json lists the skips.