diff --git a/CLAUDE.md b/CLAUDE.md
index a0ec676..2ee7a19 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -64,7 +64,7 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`.
 
 ### Core Data Flow
 
-`apps.json` → `scripts/fetch-apps.js` downloads `kb-docs.tar.gz` per app → `apps/{slug}/` → Astro's `src/pages/[...path].astro` catchall uses `getStaticPaths()` from `src/utils/apps.js` to enumerate every HTML file → `src/utils/transform.js` rewrites URLs and splits the document → `Base.astro` re-hosts the parts → static output in `dist/`.
+`apps.json` (a source per entry) → `scripts/build-vite.js` stages each artifact (downloading via `scripts/fetch-apps.js` for a `repo`) → reads its `kb-docs.json` → copies one directory per declared app into `apps/{slug}/` → Astro's `src/pages/[...path].astro` catchall uses `getStaticPaths()` from `src/utils/apps.js` to enumerate every HTML file → `src/utils/transform.js` rewrites URLs and splits the document → `Base.astro` re-hosts the parts → static output in `dist/`.
 
 ### Key Source Files
 
@@ -76,21 +76,23 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`.
 - `src/components/Masthead.astro` — Persistent Knowledge base header + Library/current-app sub-nav (all pages, both modes)
 - `src/components/AppCard.astro`, `src/components/AppIcon.astro` — Catalog card and its icon
 - `src/templates/shadow-compat.js` — Shadow-DOM design-token styles, injected into the body by the layout
-- `src/utils/config.js` — `PATH_PREFIX`/`BASE_PATH` and `isHeadlessBuild()` — the build-wide constants
-- `src/utils/single-page.js` — Bundle manifest reading/validation + registry expansion, shared by both fetch paths and by Astro
+- `src/utils/config.js` — `PATH_PREFIX`/`BASE_PATH`, `isHeadlessBuild()` and `REGISTRY_FILE` — the build-wide constants
+- `src/utils/registry.js` — Registry validation, manifest reading/validation, expansion map. Shared by the build and by Astro so both resolve the same registry
 - `scripts/build-vite.js` — Build orchestrator (4 steps: prepare, hoist, copy assets, astro build)
-- `scripts/fetch-apps.js` — GitHub Release artifact downloader
+- `scripts/fetch-apps.js` — GitHub Release artifact downloader. Only *obtains* an artifact; installing it is one shared path in `build-vite.js`
 - `scripts/artifacts.js` — Safe tarball extraction + tree copy, shared by both fetch paths. Validates archive members (no traversal, no absolute paths, no symlinks) before anything is written, and replaces the old `cp -r`/`tar` shell-outs so the build runs on Windows
 - `scripts/hoist-inline-scripts.js` — Moves inline `<script>` bodies in sub-app HTML into files before the Astro build, so the deployment can serve `script-src 'self'`. Needed because bundles published before the action stopped emitting an inline mermaid bootstrap still contain one. A sub-app's dark-mode bootstrap is deleted here rather than hoisted — light only, and hoisting would put it beyond the reach of `transform.js`
 - `actions/publish-single-page-docs/` — Reusable GitHub Action that turns a repo's markdown into a single-page bundle
 
-### Three Onboarding Types
+### Onboarding Types
 
-An `apps.json` entry is one of:
+A registry entry names a **source** (`repo` + optional `version`, `prebuilt`, or `localPath`) and nothing else — no slug, name, description, icon or tags. Those come from the artifact's `kb-docs.json`, and the build rejects an entry that carries them. The one exception is an `iframe` entry, which has no artifact to read them from.
+
+The registry file is `apps.json` by default; `KB_REGISTRY` points the build at another one, which is how a deployment repo owns its own list.
 
 - **default (packaged)** — a repo publishes a headless static site as `kb-docs.tar.gz` carrying a `kb-docs.json` manifest. Every HTML file becomes a route unless the manifest lists `pages`.
 - **`type: "iframe"`** — no artifact; a single route renders a full-viewport `<iframe>` for an external URL. Explicit stopgap (issue #10).
-- **`type: "single-page"`** — one release artifact holding *many* docs, published by `actions/publish-single-page-docs` from plain markdown. The entry carries **no per-doc metadata** (`{ "repo": …, "type": "single-page", "version": "latest" }`); the build reads the artifact's `kb-docs.json` and **expands** the entry into one app per doc, extracting each into `apps/{slug}/`. The expansion is recorded in `apps/.single-page.json` and spliced back into the registry by `loadRegistry()` so Astro sees the same registry the build did. Slugs must be globally unique — `resolveRegistry()` fails the build otherwise. Rendering: masthead, no sidebar, content in a centred `main.kb-single-page` reading column. See issue #35 and `contract/SINGLE_PAGE.md`.
+- **markdown bundles** — an artifact published by `actions/publish-single-page-docs` from plain markdown, holding one doc per app. Structurally identical to a packaged site: same asset name, same manifest, same install path. Rendering differs only where the artifact does — an app whose directory holds exactly one HTML file and declares no `pages` is rendered in a centred `main.kb-single-page` reading column with no sidebar. See issue #35 and `contract/SINGLE_PAGE.md`.
 
 ### Two Modes
 
@@ -128,7 +130,7 @@ Apps registered in `apps.json` must comply with:
 Self-contained Playwright E2E — `npm test` auto-starts everything (no external gateway):
 
 1. **:3000 fragment** — `scripts/setup-test-apps.mjs` writes a hermetic `apps.json` that
-   registers the vendored `tests/fixtures/docs-example.dist.tar.gz` twice
+   registers the vendored `tests/fixtures/docs-example.kb-docs.tar.gz` (two apps)
    (slugs `user-guide` + `guide-mirror`, for cross-app nav), an iframe entry pinned
    `"headless": false`, and the generated single-page bundle fixture. `build:headless` builds it;
    `tests/fragment-server.mjs` serves `dist/` mirroring the production **nginx** rewrites
@@ -159,7 +161,7 @@ commands listed in `AGENTS.md`:
 - `support/fragment.js` — shadow-DOM traversal + reframed-body wait/query helpers.
 
 Two build-pipeline pieces support this: `apps.json` entries may carry a `prebuilt` path
-(tarball or dist dir) consumed by `scripts/build-vite.js` (`preparePrebuilt`) for hermetic
+(tarball or unpacked directory) consumed by `scripts/build-vite.js` (`stageEntry`) for hermetic
 offline builds; and the build copies the knowledge base stylesheet — identified as the local
 stylesheet the landing page loads — to a stable `dist/style.css` alias. Pages themselves
 reference the content-hashed bundle Astro injects, so nothing depends on that filename.
@@ -173,6 +175,7 @@ in the committed `apps.json` without breaking CI, which only has this repo.
 ## Environment Variables
 
 - `GITHUB_TOKEN` — GitHub API auth for fetching Release artifacts
+- `KB_REGISTRY` — registry file to build from, relative to the project root. Default `apps.json`. Read through `REGISTRY_FILE` in `src/utils/config.js`, never inline.
 - `KB_HEADLESS` — `true` produces web-fragment output; **anything else, including unset, means standalone**. `scripts/build-vite.js` always exports an explicit value, so the default only applies when `astro build`/`astro dev` runs directly. Read it through `isHeadlessBuild()`, never inline. A per-app `"headless"` in `apps.json` overrides it in either direction.
 - `AWS_REGION`, `ECR_REPOSITORY`, `ECS_CLUSTER`, `ECS_SERVICE` — deployment config
 - `KB_EXAMPLE_ARTIFACT` — overrides the packaged artifact `scripts/setup-test-apps.mjs` registers
diff --git a/README.md b/README.md
index 6d5dbcb..6b6d7a1 100644
--- a/README.md
+++ b/README.md
@@ -87,26 +87,30 @@ route patterns hard-code the same string.
 
 ## The registry: `apps.json`
 
-Each entry registers one doc app. A `slug` is required; the source is one of
-`repo` (+ optional `version`), `localPath`, `prebuilt`, or an `iframe` URL:
+Each entry says **where an artifact comes from, and nothing else**. The slug,
+name, description, icon, tags and page list all come from the artifact's own
+`kb-docs.json` (see [`contract/ARTIFACT.md`](contract/ARTIFACT.md)), so one entry
+may register several apps and onboarding a new doc never edits this repository
+again. The build rejects an entry that carries display fields.
 
 ```jsonc
 [
-  {
-    "slug": "my-app",
-    "name": "My App Documentation",
-    "description": "What this app documents.",
-    "icon": "book-open",
-    "tags": ["guide"],
-
-    // pick ONE source:
-    "repo": "AbsaOSS/my-docs", "version": "latest", // GitHub Release artifact
-    // "localPath": "../my-docs",                    // build from local checkout
-    // "prebuilt": "tests/fixtures/my-docs.kb-docs.tar.gz" // prebuilt tarball or dist dir
-  }
+  // pick ONE source per entry:
+  { "repo": "AbsaOSS/my-docs", "version": "latest" },      // GitHub Release artifact
+  { "localPath": "../my-docs" },                            // pack from a local checkout
+  { "prebuilt": "tests/fixtures/my-docs.kb-docs.tar.gz" }   // tarball or unpacked directory
 ]
 ```
 
+`version` accepts `latest` (the default) or a pinned tag. `localPath` runs the
+checkout's pack command — `npm run pack:kb` unless the entry sets `"pack"` — and
+then reads the `kb-docs.tar.gz` it leaves behind; `"pack": false` skips that when
+the artifact is already built. An entry may also set `"headless"` to pin one app
+against the build flag.
+
+`KB_REGISTRY` points the build at a different registry file, which is how a
+deployment repository owns its own list without forking this one.
+
 Add `"optional": true` to a `prebuilt`/`localPath` entry whose artifact lives
 outside this repo — a sibling checkout, say. The build then **skips it with a
 warning** when the artifact is absent instead of failing, so CI and fresh clones
@@ -170,7 +174,7 @@ to headless HTML — GFM tables, task lists, footnotes, highlighted code and
 vendored-mermaid diagrams — packs every doc into one `kb-docs.tar.gz` with a
 `kb-docs.json` manifest, and attaches it to the repo's latest release.
 
-The registry entry then carries **no per-doc metadata at all**:
+The registry entry is the same two lines every artifact gets:
 
 ```jsonc
 {
@@ -209,7 +213,7 @@ own apps for a real deployment.
 ## Testing
 
 E2E tests use Playwright. Everything is hermetic — built from
-`tests/fixtures/docs-example.dist.tar.gz` (no network, token, or sibling repo).
+`tests/fixtures/docs-example.kb-docs.tar.gz` (no network, token, or sibling repo).
 
 | Command | Layer |
 |---|---|
@@ -371,7 +375,7 @@ knowledge-base/
 │   └── utils/
 │       ├── apps.js            ← loadRegistry() + getAppPages() page enumeration
 │       ├── config.js          ← PATH_PREFIX / BASE_PATH + isHeadlessBuild()
-│       ├── single-page.js     ← manifest parsing + registry expansion
+│       ├── registry.js         ← registry rules + manifest parsing + expansion
 │       └── transform.js       ← parse5 URL rewriting + sub-app document splitting
 ├── scripts/
 │   ├── build-vite.js          ← Build orchestrator
diff --git a/apps.json b/apps.json
index e63f35c..2892665 100644
--- a/apps.json
+++ b/apps.json
@@ -1,25 +1,6 @@
 [
   {
-    "slug": "user-guide",
-    "name": "User Guide",
-    "description": "Primary docs app — the vendored docs-example fixture used as the integration guinea pig.",
-    "icon": "book-open",
-    "tags": [
-      "guide",
-      "getting-started"
-    ],
-    "prebuilt": "tests/fixtures/docs-example.dist.tar.gz"
-  },
-  {
-    "slug": "guide-mirror",
-    "name": "Guide Mirror",
-    "description": "Second registered app (same artifact, different slug) for cross-app navigation tests.",
-    "icon": "book-open",
-    "tags": [
-      "mirror",
-      "cross-app"
-    ],
-    "prebuilt": "tests/fixtures/docs-example.dist.tar.gz"
+    "prebuilt": "tests/fixtures/docs-example.kb-docs.tar.gz"
   },
   {
     "slug": "external-docs",
@@ -35,12 +16,10 @@
     "headless": false
   },
   {
-    "type": "single-page",
     "prebuilt": "tests/fixtures/single-page-bundle"
   },
   {
-    "type": "single-page",
-    "prebuilt": "../knowledge-base-example-single-page/dist.tar.gz",
+    "prebuilt": "../knowledge-base-example-single-page/kb-docs.tar.gz",
     "optional": true
   }
 ]
diff --git a/scripts/artifacts.js b/scripts/artifacts.js
index 18d28d1..1833cd3 100644
--- a/scripts/artifacts.js
+++ b/scripts/artifacts.js
@@ -1,7 +1,7 @@
 /**
  * artifacts.js — safe extraction and copying of sub-app artifacts.
  *
- * Every artifact this build consumes is a `dist.tar.gz` produced by *another*
+ * Every artifact this build consumes is a `kb-docs.tar.gz` produced by *another*
  * repository's release pipeline, so its contents are untrusted input: a
  * compromised (or merely careless) doc repo must not be able to write outside
  * the staging directory, and must not be able to smuggle a symlink into the
diff --git a/scripts/build-vite.js b/scripts/build-vite.js
index 234ef44..e17ece9 100644
--- a/scripts/build-vite.js
+++ b/scripts/build-vite.js
@@ -16,20 +16,21 @@
  *       Sub-app pages are rendered by src/pages/[...path].astro via getStaticPaths.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, copyFileSync, linkSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, copyFileSync, linkSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
-import { copyDir, stageArtifact } from './artifacts.js';
-import { fetchApps } from './fetch-apps.js';
+import { copyDir, extractTarball, stageArtifact } from './artifacts.js';
+import { downloadArtifact } from './fetch-apps.js';
 import { HOIST_DIR, hoistAppInlineScripts } from './hoist-inline-scripts.js';
 import { collectHtmlFiles } from '../src/utils/apps.js';
-import { PATH_PREFIX } from '../src/utils/config.js';
+import { PATH_PREFIX, REGISTRY_FILE } from '../src/utils/config.js';
 import {
-  BUNDLE_MANIFEST, bundleDirName, bundleKey, expandBundle, findBundleRoot,
-  isSinglePage, readBundleManifest, resolveRegistry, toRegistryEntry, writeExpansionMap,
-} from '../src/utils/single-page.js';
+  ARTIFACT_NAME, MANIFEST, expandManifest, findManifestRoot, isIframe,
+  readManifest, resolveRegistry, sourceKey, stagingName, toRegistryEntry,
+  validateEntry, writeExpansionMap,
+} from '../src/utils/registry.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
@@ -43,7 +44,10 @@ const ok   = (msg) => console.log('\x1b[32m✓\x1b[0m ' + msg);
 const warn = (msg) => console.warn('\x1b[33m⚠\x1b[0m  ' + msg);
 const step = (msg) => console.log('\n\x1b[1m' + msg + '\x1b[0m');
 
-/** Where `prebuilt` tarballs are unpacked before being copied into apps/. */
+/** Default command a `localPath` entry runs to produce its artifact. */
+const DEFAULT_PACK = 'npm run pack:kb';
+
+/** Where artifacts are unpacked before their apps are copied into apps/. */
 const STAGE_ROOT = join(ROOT, 'tmp', 'prebuilt');
 
 /** Expands a registry path (`~` and repo-relative forms allowed) to an absolute one. */
@@ -55,72 +59,146 @@ function artifactPath(raw) {
 /** As artifactPath, but fails the build when the artifact is not there. */
 function resolveArtifactPath(app, raw, label) {
   const srcPath = artifactPath(raw);
-  if (!existsSync(srcPath)) fail((app.slug ?? bundleKey(app)) + ': ' + label + ' path not found: ' + srcPath);
+  if (!existsSync(srcPath)) fail(sourceKey(app) + ': ' + label + ' path not found: ' + srcPath);
   return srcPath;
 }
 
 /**
- * Prepares a sub-app from a prebuilt artifact instead of fetching from GitHub
- * or building from source.
+ * Puts an entry's artifact on disk as a directory, whatever its source.
  *
- * Used for hermetic E2E tests (no network, no per-app toolchain) and for any
- * registry entry that ships a `prebuilt` path. Mirrors fetch-apps.js: the dist
- * contents land in apps/{slug}/ with marketplace.json copied alongside. For a
- * `single-page` entry the artifact is a bundle instead, so it is expanded — see
- * installBundle.
+ * This is the only place the three sources differ. Everything after it —
+ * reading the manifest, validating it, copying apps into apps/{slug}/ — is
+ * installArtifact, run identically for all of them. The GitHub path and the
+ * prebuilt path used to be separate implementations of the same idea and drifted
+ * apart repeatedly; there is now nothing left to drift.
  *
- * @returns {Array|null} expanded app entries for a single-page bundle, else null
+ * @returns {Promise<{stageDir: string, label: string, releaseTag?: string}>}
  */
-function preparePrebuilt(app) {
-  const label    = app.slug ?? bundleKey(app);
-  const srcPath  = resolveArtifactPath(app, app.prebuilt, 'prebuilt');
-  const stageDir = stageArtifact(srcPath, bundleDirName(label), STAGE_ROOT, label);
-
-  if (isSinglePage(app)) return installBundle(app, stageDir, 'prebuilt');
+async function stageEntry(app) {
+  const key = sourceKey(app);
 
-  const destDir = join(APPS_DIR, app.slug);
-  if (existsSync(destDir)) rmSync(destDir, { recursive: true });
+  if (app.prebuilt) {
+    const srcPath = resolveArtifactPath(app, app.prebuilt, 'prebuilt');
+    return { stageDir: stageArtifact(srcPath, stagingName(key), STAGE_ROOT, key), label: 'prebuilt' };
+  }
 
-  // The built output is dist/ when present, otherwise the staging dir itself.
-  const distDir = existsSync(join(stageDir, 'dist')) ? join(stageDir, 'dist') : stageDir;
-  copyDir(distDir, destDir);
+  if (app.localPath) {
+    const checkout = resolveArtifactPath(app, app.localPath, 'localPath');
+
+    // A local checkout is source, not output. Run whatever the repo uses to
+    // produce its artifact and then treat the result exactly like a prebuilt
+    // one. The command is per-entry because doc repos are not all Node: the
+    // example repo is Python and mkdocs, and the old hard-coded
+    // `npm run build:headless` simply could not run there.
+    if (app.pack !== false) {
+      const command = typeof app.pack === 'string' ? app.pack : DEFAULT_PACK;
+      log(`Packing ${key} with \`${command}\`…`);
+      execSync(command, { cwd: checkout, stdio: 'inherit' });
+    }
 
-  // Copy marketplace.json (tarball root preferred, then dist/) so manifest-driven
-  // routing/metadata works the same as the GitHub fetch path.
-  for (const cand of [join(stageDir, 'marketplace.json'), join(distDir, 'marketplace.json')]) {
-    if (existsSync(cand)) { copyFileSync(cand, join(destDir, 'marketplace.json')); break; }
+    const artifact = join(checkout, ARTIFACT_NAME);
+    if (!existsSync(artifact)) {
+      fail(
+        `${key}: no ${ARTIFACT_NAME} in the checkout after packing.\n` +
+        `     A "localPath" entry runs its pack command (\`${app.pack ?? DEFAULT_PACK}\`) and then reads\n` +
+        `     ${ARTIFACT_NAME} from the checkout root, the same file the repo publishes to a release.\n` +
+        `     Set "pack" to the right command, or "pack": false if the artifact is already built.`,
+      );
+    }
+    return { stageDir: stageArtifact(artifact, stagingName(key), STAGE_ROOT, key), label: 'local' };
   }
-  ok(app.slug + ' ready (prebuilt)');
-  return null;
+
+  const { tarPath, releaseTag } = await downloadArtifact(app);
+  const stageDir = join(STAGE_ROOT, stagingName(key));
+  if (existsSync(stageDir)) rmSync(stageDir, { recursive: true });
+  mkdirSync(stageDir, { recursive: true });
+  extractTarball(tarPath, stageDir, `${key}@${releaseTag}`);
+  return { stageDir, label: releaseTag, releaseTag };
 }
 
 /**
- * Expands a locally staged single-page bundle into one sub-app per doc.
- *
- * The GitHub path (scripts/fetch-apps.js → fetchBundle) does the same thing after
- * downloading the release asset; both share the manifest reading/validation in
- * src/utils/single-page.js so the two can't drift.
+ * Installs every app an artifact declares into apps/{slug}/.
  *
  * @returns {Array} expanded app entries, ready for the expansion map
  */
-function installBundle(app, stageDir, sourceLabel) {
-  const key = bundleKey(app);
-  const bundleRoot = findBundleRoot(stageDir);
-  if (!bundleRoot) {
+function installArtifact(app, stageDir, label) {
+  const key  = sourceKey(app);
+  const root = findManifestRoot(stageDir);
+  if (!root) {
     fail(
-      key + ': single-page artifact has no ' + BUNDLE_MANIFEST + ' at its root. ' +
-      'Publish it with AbsaOSS/knowledge-base/actions/publish-single-page-docs — see contract/SINGLE_PAGE.md.',
+      `${key}: the artifact has no ${MANIFEST} at its root.\n` +
+      `     A release must carry ${ARTIFACT_NAME} packed by an AbsaOSS/knowledge-base publishing\n` +
+      `     action — see contract/ARTIFACT.md.`,
     );
   }
 
-  const docs = expandBundle(app, readBundleManifest(bundleRoot, key), bundleRoot);
-  for (const doc of docs) {
-    const destDir = join(APPS_DIR, doc.slug);
+  const manifest = readManifest(root, key);
+  const apps     = expandManifest(app, manifest, root);
+
+  // Anything in the archive that no app claims is not served. Saying so is the
+  // difference between a doc that is missing and a doc nobody realises was
+  // never registered.
+  warnOnUnclaimedMembers(root, apps, key);
+
+  for (const entry of apps) {
+    const destDir = join(APPS_DIR, entry.slug);
     if (existsSync(destDir)) rmSync(destDir, { recursive: true });
-    copyDir(doc.docDir, destDir);
-    ok(doc.slug + ' ready (single-page doc, ' + sourceLabel + ')');
+    copyDir(entry.appDir, destDir);
+
+    const html = readFileSync(join(destDir, entry.entryPoint), 'utf8');
+    checkHeadlessMarker(html, `${entry.slug}: ${entry.entryPoint}`);
+
+    ok(`${entry.slug} ready (${label})`);
+  }
+  return apps.map(toRegistryEntry);
+}
+
+/** The marker a headless artifact must carry on `<html>`. */
+const HEADLESS_MARKER = 'data-kb-headless="true"';
+/** Its pre-rename spelling — see issue #77. */
+const LEGACY_HEADLESS_MARKER = 'data-mp-headless';
+
+/**
+ * Warns when an artifact's entry point is not marked headless.
+ *
+ * A bundle published before the rename carries `data-mp-headless`, which is
+ * indistinguishable from "not headless at all" to every downstream consumer.
+ * Saying so explicitly is the difference between a publisher re-reading the
+ * contract and a publisher re-reading their build script.
+ *
+ * This used to run only on the GitHub fetch path, so the sources CI actually
+ * uses were never checked.
+ */
+function checkHeadlessMarker(html, label) {
+  if (html.includes(HEADLESS_MARKER)) return;
+  if (html.includes(LEGACY_HEADLESS_MARKER)) {
+    warn(
+      `${label} carries ${LEGACY_HEADLESS_MARKER}, which this knowledge base no longer reads. ` +
+      `The artifact was produced against the pre-rename contract — republish it with a current ` +
+      `AbsaOSS/knowledge-base action so it emits ${HEADLESS_MARKER}.`,
+    );
+    return;
+  }
+  warn(`${label} is missing ${HEADLESS_MARKER} on <html> — see contract/HEADLESS_RULES.md.`);
+}
+
+/**
+ * Reports archive members that belong to no declared app.
+ *
+ * contract/ARTIFACT.md allows only the manifest and the declared `<slug>/`
+ * directories. A stray top-level file is not served, and a stray *directory*
+ * usually means a doc was dropped from the manifest but not from the build.
+ */
+function warnOnUnclaimedMembers(root, apps, key) {
+  const claimed = new Set(apps.map((a) => a.slug));
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.name === MANIFEST) continue;
+    if (entry.isDirectory() && claimed.has(entry.name)) continue;
+    warn(
+      `${key}: ${entry.isDirectory() ? 'directory' : 'file'} "${entry.name}" is in the artifact but ` +
+      `no app in ${MANIFEST} claims it — it will not be served.`,
+    );
   }
-  return docs.map(toRegistryEntry);
 }
 
 function fail(msg) { throw new Error(msg); }
@@ -148,7 +226,26 @@ async function build() {
   const modeLabel = [LOCAL_MODE && 'local', HEADLESS && 'headless'].filter(Boolean).join(', ');
   console.log('\n\x1b[1m\x1b[35m▶ knowledge-base build' + (modeLabel ? ' (' + modeLabel + ')' : '') + '\x1b[0m\n');
 
-  const allEntries = JSON.parse(readFileSync(join(ROOT, 'apps.json'), 'utf8'));
+  const registryPath = join(ROOT, REGISTRY_FILE);
+  if (!existsSync(registryPath)) fail(`registry not found: ${registryPath} (set KB_REGISTRY to point elsewhere)`);
+  const allEntries = JSON.parse(readFileSync(registryPath, 'utf8'));
+  if (!Array.isArray(allEntries)) fail(`${REGISTRY_FILE}: expected an array of entries.`);
+
+  // Validate every entry before touching the network or the filesystem, so a
+  // malformed registry fails on the registry rather than halfway through a
+  // download. See src/utils/registry.js for the rules.
+  allEntries.forEach(validateEntry);
+
+  const seenSources = new Set();
+  for (const app of allEntries) {
+    if (isIframe(app)) {
+      if (app.temporary) warn(`${app.slug}: temporary iframe entry — migrate to a packaged artifact when ready`);
+      continue;
+    }
+    const key = sourceKey(app);
+    if (seenSources.has(key)) fail(`${REGISTRY_FILE}: two entries both point at ${key}.`);
+    seenSources.add(key);
+  }
 
   // Entries flagged `"optional": true` are local-development conveniences whose
   // artifact lives outside this repo — the sibling example repo, say. When it is
@@ -158,34 +255,14 @@ async function build() {
   const registeredApps = allEntries.filter(app => {
     const artifact = app.prebuilt ?? app.localPath;
     if (!app.optional || !artifact || existsSync(artifactPath(artifact))) return true;
-    warn((app.slug ?? artifact) + ': optional entry skipped — artifact not found at ' + artifactPath(artifact));
+    warn(`${sourceKey(app)}: optional entry skipped — artifact not found at ${artifactPath(artifact)}`);
     return false;
   });
 
-  // Validate registry entries up front (fail fast with a clear message).
-  const bundleKeys = new Set();
-  for (const app of registeredApps) {
-    if (isSinglePage(app)) {
-      // A single-page entry carries no slug or per-doc metadata — the docs (and
-      // their slugs) are discovered from the artifact's bundle.json.
-      const key = bundleKey(app);
-      if (bundleKeys.has(key)) fail('apps.json: two "single-page" entries both point at ' + key);
-      bundleKeys.add(key);
-      continue;
-    }
-    if (!app.slug) fail('apps.json: an entry is missing "slug"');
-    if (app.type === 'iframe') {
-      if (!app.url) fail(app.slug + ': iframe entry requires a "url"');
-      if (app.temporary) warn(app.slug + ': temporary iframe entry — migrate to a headless package when ready');
-    } else if (!app.prebuilt && !app.localPath && !app.repo) {
-      fail(app.slug + ': packaged entry needs one of "repo", "localPath", or "prebuilt"');
-    }
-  }
-
-  // iframe entries have no artifact to fetch/build — they render a single route
-  // (see src/pages/[...path].astro). Only packaged apps go through the pipeline.
-  const iframeApps   = registeredApps.filter(a => a.type === 'iframe');
-  const packagedApps = registeredApps.filter(a => a.type !== 'iframe');
+  // iframe entries have no artifact to fetch or build — they render a single
+  // route (see src/pages/[...path].astro).
+  const iframeApps   = registeredApps.filter(isIframe);
+  const artifactApps = registeredApps.filter(a => !isIframe(a));
 
   // 1. Prepare apps/ directory
   step('1/4  Preparing sub-app artifacts → apps/');
@@ -193,62 +270,32 @@ async function build() {
 
   for (const app of iframeApps) ok(app.slug + ' registered (iframe → ' + app.url + ')');
 
-  // What each single-page bundle expanded into, keyed by bundleKey. Written to
-  // apps/.single-page.json so Astro resolves the same registry the build did.
+  // What each artifact expanded into, keyed by its source. Written to
+  // apps/.registry.json so Astro resolves the same registry the build did.
   const expansions = {};
-  const record = (key, docs) => { (expansions[key] ??= []).push(...docs); };
 
-  // Apps shipping a `prebuilt` artifact are prepared locally regardless of mode
-  // (hermetic — no network, no per-app build). The rest go through fetch/local.
-  const prebuiltApps  = packagedApps.filter(a => a.prebuilt);
-  const remainingApps = packagedApps.filter(a => !a.prebuilt);
+  for (const app of artifactApps) {
+    const key = sourceKey(app);
 
-  for (const app of prebuiltApps) {
-    const docs = preparePrebuilt(app);
-    if (docs) record(bundleKey(app), docs);
-  }
-
-  if (remainingApps.length > 0) {
-    if (LOCAL_MODE) {
-      for (const app of remainingApps) {
-        if (!app.localPath) { warn((app.slug ?? bundleKey(app)) + ': no localPath, skipping'); continue; }
-        const srcDir = app.localPath.replace(/^~/, homedir());
-
-        // A local single-page bundle is already built output — expand it in place
-        // rather than running a per-app build script it does not have.
-        if (isSinglePage(app)) {
-          record(bundleKey(app), installBundle(app, resolveArtifactPath(app, app.localPath, 'localPath'), 'local'));
-          continue;
-        }
-
-        const buildScript = HEADLESS ? 'build:headless' : 'build';
-        log('Building ' + app.slug + ' from ' + app.localPath + '…');
-        execSync('npm run ' + buildScript, { cwd: srcDir, stdio: 'inherit' });
-
-        const srcDist = join(srcDir, 'dist');
-        const destDir = join(APPS_DIR, app.slug);
-        if (existsSync(destDir)) rmSync(destDir, { recursive: true });
-        copyDir(srcDist, destDir);
-        const manifest = join(srcDir, 'marketplace.json');
-        if (existsSync(manifest)) copyFileSync(manifest, join(destDir, 'marketplace.json'));
-        ok(app.slug + ' ready (local)');
-      }
-    } else {
-      for (const entry of await fetchApps(remainingApps)) {
-        // Only single-page entries carry a bundleKey; packaged apps are already
-        // fully described by their apps.json entry.
-        const { bundleKey: key, ...rest } = entry;
-        if (key) record(key, [toRegistryEntry(rest)]);
-      }
+    // `prebuilt` artifacts are staged locally regardless of mode — that is what
+    // makes CI hermetic. `--local` only changes what a `repo` entry means: build
+    // it from the checkout beside this one rather than downloading a release.
+    if (LOCAL_MODE && app.repo && !app.localPath) {
+      warn(`${key}: --local was requested but the entry names no localPath — skipping.`);
+      continue;
     }
+
+    console.log('\n\x1b[1m[' + key + ']\x1b[0m');
+    const { stageDir, label } = await stageEntry(app);
+    expansions[key] = installArtifact(app, stageDir, label);
   }
 
   // Persist the expansion and resolve the registry the rest of the build works
-  // from. resolveRegistry also enforces globally unique slugs, so a doc bundle
+  // from. resolveRegistry also enforces globally unique slugs, so one artifact
   // can never quietly take over another app's URL prefix.
   writeExpansionMap(ROOT, expansions);
   const resolvedApps = resolveRegistry(registeredApps, expansions, warn);
-  const packagedResolved = resolvedApps.filter(a => a.type !== 'iframe');
+  const packagedResolved = resolvedApps.filter(a => !isIframe(a));
 
   // 1b. Hoist inline <script> bodies out of sub-app HTML into files.
   //     The knowledge base serves script-src 'self'; an inline script anywhere would
@@ -258,7 +305,7 @@ async function build() {
   step('1b/4  Hoisting inline scripts → files');
   let hoisted = 0;
   let droppedBootstraps = 0;
-  for (const app of resolvedApps.filter(a => a.type !== 'iframe')) {
+  for (const app of resolvedApps.filter(a => !isIframe(a))) {
     const appDir = join(APPS_DIR, app.slug);
     if (!existsSync(appDir)) continue;
     const { hoisted: count, dropped } = hoistAppInlineScripts(appDir, collectHtmlFiles(appDir));
diff --git a/scripts/fetch-apps.js b/scripts/fetch-apps.js
index 1335b8d..4b85e20 100644
--- a/scripts/fetch-apps.js
+++ b/scripts/fetch-apps.js
@@ -1,33 +1,30 @@
 /**
  * fetch-apps.js
  *
- * Downloads the latest (or pinned) GitHub Release artifact for each app in apps.json.
- * Requires either:
+ * Downloads the kb-docs.tar.gz release asset for a registry entry that names a
+ * `repo`. Requires either:
  *   - GITHUB_TOKEN env variable, OR
- *   - `gh` CLI authenticated (used as fallback)
+ *   - `gh` CLI authenticated (used as fallback for the API, not for downloads)
  *
- * Artifacts are extracted to apps/{slug}/ (the Vite source directory for sub-apps).
- * Legacy: also keeps tmp/apps/{slug}/ populated for non-Vite paths.
+ * This module only *obtains* an artifact. Reading its manifest, validating it
+ * and installing its apps into apps/{slug}/ is the same code for every source
+ * and lives in scripts/build-vite.js — see contract/ARTIFACT.md. Keeping the two
+ * apart is what stopped the GitHub path and the prebuilt path from drifting the
+ * way they used to.
  */
 
 import { spawnSync } from 'node:child_process';
-import { createWriteStream, mkdirSync, rmSync, existsSync, copyFileSync, readFileSync } from 'node:fs';
+import { createWriteStream, mkdirSync, rmSync, existsSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
-import { copyDir, extractTarball } from './artifacts.js';
-import {
-  BUNDLE_MANIFEST, bundleDirName, bundleKey, expandBundle,
-  findBundleRoot, isSinglePage, readBundleManifest, toRegistryEntry,
-} from '../src/utils/single-page.js';
+import { ARTIFACT_NAME, SIZE_LIMIT, SIZE_WARN } from '../src/utils/registry.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT      = join(__dirname, '..');
-// Primary output: apps/{slug}/ — consumed by the Vite build and dev server
-const APPS_DIR  = join(ROOT, 'apps');
-// Legacy output kept for compatibility with old build.js path
-const TMP_DIR   = join(ROOT, 'tmp', 'apps');
+/** Where downloaded artifacts land before they are staged. */
+const DOWNLOAD_DIR = join(ROOT, 'tmp', 'downloads');
 
 const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
 const API_BASE     = 'https://api.github.com';
@@ -36,7 +33,6 @@ const API_BASE     = 'https://api.github.com';
 
 function log(msg)  { process.stdout.write(`  \x1b[36m→\x1b[0m ${msg}\n`); }
 function warn(msg) { process.stderr.write(`  \x1b[33m⚠\x1b[0m  ${msg}\n`); }
-function ok(msg)   { process.stdout.write(`  \x1b[32m✓\x1b[0m ${msg}\n`); }
 function fail(msg) { throw new Error(`\x1b[31m✗\x1b[0m ${msg}`); }
 
 /** `owner/name`, the only shape a registry `repo` may take. */
@@ -44,32 +40,6 @@ const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 /** Git tag characters we are willing to put in a URL path. */
 const VERSION_RE = /^[A-Za-z0-9._/-]+$/;
 
-/** The marker a headless artifact must carry on `<html>`. */
-const HEADLESS_MARKER = 'data-kb-headless="true"';
-/** Its pre-rename spelling — see issue #77. */
-const LEGACY_HEADLESS_MARKER = 'data-mp-headless';
-
-/**
- * Warns when an artifact's entry point is not marked headless.
- *
- * A bundle published before the rename carries `data-mp-headless` instead, which
- * is indistinguishable from "not headless at all" to every downstream consumer.
- * Saying so explicitly is the difference between a publisher re-reading the
- * contract and a publisher re-reading their build script.
- */
-function checkHeadlessMarker(html, label, hint) {
-  if (html.includes(HEADLESS_MARKER)) return;
-  if (html.includes(LEGACY_HEADLESS_MARKER)) {
-    warn(
-      `${label} carries ${LEGACY_HEADLESS_MARKER}, which this knowledge base no longer reads.\n` +
-      `     The artifact was produced against the pre-rename contract — republish it with a\n` +
-      `     current AbsaOSS/knowledge-base action so it emits ${HEADLESS_MARKER}.`
-    );
-    return;
-  }
-  warn(`${label} is missing ${HEADLESS_MARKER} on <html>.\n     ${hint}`);
-}
-
 /**
  * Rejects registry values that must never reach a URL or a subprocess argument.
  *
@@ -140,7 +110,7 @@ async function downloadAsset(repo, assetId, assetName, destPath) {
 }
 
 /**
- * Fetches the release info for an app.
+ * Fetches the release info for an entry.
  * - version "latest": fetches the latest release
  * - version "v1.2.3": fetches that specific tag
  */
@@ -151,208 +121,84 @@ async function fetchRelease(repo, version) {
   return ghApi(path);
 }
 
-/**
- * Finds the dist.tar.gz asset in a release.
- */
-function findDistAsset(release, repo) {
-  const asset = release.assets?.find(a => a.name === 'dist.tar.gz');
+/** Finds the kb-docs.tar.gz asset in a release. */
+function findArtifactAsset(release, repo) {
+  const asset = release.assets?.find((a) => a.name === ARTIFACT_NAME);
   if (!asset) {
+    const available = release.assets?.map((a) => a.name).join(', ') || 'none';
+    const legacy = release.assets?.some((a) => a.name === 'dist.tar.gz');
     fail(
-      `No 'dist.tar.gz' asset found in release '${release.tag_name}' of ${repo}.\n` +
-      `Available assets: ${release.assets?.map(a => a.name).join(', ') || 'none'}\n` +
-      `See contract/HEADLESS_RULES.md for how to publish release artifacts.`
+      `No '${ARTIFACT_NAME}' asset in release '${release.tag_name}' of ${repo}.\n` +
+      `     Available assets: ${available}\n` +
+      (legacy
+        ? `     This release carries 'dist.tar.gz', the pre-v1 asset name. Republish it with a\n` +
+          `     current AbsaOSS/knowledge-base publishing action.\n`
+        : '') +
+      `     See contract/ARTIFACT.md for what a release must carry.`,
     );
   }
   return asset;
 }
 
-// ── Single-page bundles ───────────────────────────────────────────────────────
-
 /**
- * Downloads a single-page bundle and expands it into one app per doc.
+ * Enforces the artifact size budget from contract/ARTIFACT.md.
  *
- * Same release/asset logic as a packaged app — the difference is what the
- * tarball contains: a bundle.json manifest plus one directory per doc, each of
- * which is mirrored into apps/{slug}/ exactly like a packaged app's dist.
- * See contract/SINGLE_PAGE.md.
- *
- * @returns {Promise<Array>} expanded app entries, each tagged with its bundleKey
+ * Every registered artifact is downloaded on every deployment build, so an
+ * oversized one is a cost the whole knowledge base pays rather than a private
+ * matter for the publishing repo.
  */
-async function fetchBundle(app) {
-  const { repo, version = 'latest' } = app;
-  const key = bundleKey(app);
-  assertSafeTarget(repo, version, key);
-
-  console.log(`\n\x1b[1m[${key}]\x1b[0m Fetching single-page bundle from ${repo}@${version}`);
-
-  const workDir = join(TMP_DIR, '_bundles', bundleDirName(key));
-  if (existsSync(workDir)) rmSync(workDir, { recursive: true });
-  mkdirSync(workDir, { recursive: true });
-
-  log(`Fetching release info (${version})…`);
-  let release;
-  try {
-    release = await fetchRelease(repo, version);
-  } catch (err) {
-    fail(`Could not fetch release for ${repo}@${version}: ${err.message}`);
-  }
-  log(`Found release: ${release.tag_name} (${release.published_at?.slice(0, 10)})`);
-
-  const asset   = findDistAsset(release, repo);
-  const tarPath = join(workDir, 'dist.tar.gz');
-  log(`Downloading ${asset.name} (${(asset.size / 1024).toFixed(1)} KB)…`);
-  await downloadAsset(repo, asset.id, asset.name, tarPath);
-
-  log('Extracting…');
-  extractTarball(tarPath, workDir, `${key}@${release.tag_name}`);
-
-  const bundleRoot = findBundleRoot(workDir);
-  if (!bundleRoot) {
+export function checkArtifactSize(bytes, label) {
+  if (bytes > SIZE_LIMIT) {
     fail(
-      `${key}: the release artifact has no ${BUNDLE_MANIFEST} at its root.\n` +
-      `     A "single-page" entry expects a bundle published by ` +
-      `AbsaOSS/knowledge-base/actions/publish-single-page-docs — see contract/SINGLE_PAGE.md.`,
+      `${label}: the artifact is ${mb(bytes)} MB, over the ${mb(SIZE_LIMIT)} MB limit.\n` +
+      `     See contract/ARTIFACT.md — the usual cause is uncompressed images or a vendored\n` +
+      `     toolchain the built site does not need at runtime.`,
     );
   }
-
-  const docs = expandBundle(app, readBundleManifest(bundleRoot, key), bundleRoot);
-
-  for (const doc of docs) {
-    const appsSlugDir = join(APPS_DIR, doc.slug);
-    if (existsSync(appsSlugDir)) rmSync(appsSlugDir, { recursive: true });
-    copyDir(doc.docDir, appsSlugDir);
-
-    const html = readFileSync(join(appsSlugDir, doc.entryPoint), 'utf8');
-    checkHeadlessMarker(
-      html,
-      `${doc.slug}: ${doc.entryPoint}`,
-      'See contract/HEADLESS_RULES.md.',
+  if (bytes > SIZE_WARN) {
+    warn(
+      `${label}: the artifact is ${mb(bytes)} MB, over the ${mb(SIZE_WARN)} MB target. ` +
+      `Every deployment build downloads it — see contract/ARTIFACT.md.`,
     );
-    ok(`${doc.slug} ready (single-page doc, ${release.tag_name})`);
   }
-
-  return docs.map(doc => ({
-    ...toRegistryEntry(doc),
-    bundleKey:  key,
-    releaseTag: release.tag_name,
-    releasedAt: release.published_at,
-  }));
 }
 
+const mb = (bytes) => (bytes / 1024 / 1024).toFixed(1);
+
 // ── Main export ───────────────────────────────────────────────────────────────
 
 /**
- * Downloads and extracts all app artifacts.
- * Returns enriched app metadata array (apps.json entries + release info).
+ * Downloads one entry's release artifact.
  *
- * @param {Array} apps - Contents of apps.json
- * @returns {Promise<Array>} - Enriched app list with { ...app, distDir, releaseTag, releasedAt }
+ * @param {object} app - an apps.json entry naming a `repo`
+ * @returns {Promise<{tarPath: string, releaseTag: string, releasedAt: string}>}
  */
-export async function fetchApps(apps) {
-  mkdirSync(TMP_DIR, { recursive: true });
-  mkdirSync(APPS_DIR, { recursive: true });
-
-  const enriched = [];
-
-  for (const app of apps) {
-    // A single-page entry is one artifact holding many docs — it expands into
-    // several enriched entries rather than one.
-    if (isSinglePage(app)) {
-      enriched.push(...await fetchBundle(app));
-      continue;
-    }
-
-    const { repo, slug, version = 'latest' } = app;
-    assertSafeTarget(repo, version, slug);
-
-    console.log(`\n\x1b[1m[${slug}]\x1b[0m Fetching from ${repo}@${version}`);
-
-    const appDir = join(TMP_DIR, slug);
-    if (existsSync(appDir)) {
-      rmSync(appDir, { recursive: true });
-    }
-    mkdirSync(appDir, { recursive: true });
-
-    // 1. Fetch release metadata
-    log(`Fetching release info (${version})…`);
-    let release;
-    try {
-      release = await fetchRelease(repo, version);
-    } catch (err) {
-      fail(`Could not fetch release for ${repo}@${version}: ${err.message}`);
-    }
-    log(`Found release: ${release.tag_name} (${release.published_at?.slice(0, 10)})`);
-
-    // 2. Find the dist.tar.gz asset
-    const asset = findDistAsset(release, repo);
-    const tarPath = join(appDir, 'dist.tar.gz');
-
-    // 3. Download artifact
-    log(`Downloading ${asset.name} (${(asset.size / 1024).toFixed(1)} KB)…`);
-    await downloadAsset(repo, asset.id, asset.name, tarPath);
-
-    // 4. Extract — validated against traversal and symlink members first.
-    log('Extracting…');
-    extractTarball(tarPath, appDir, `${slug}@${release.tag_name}`);
-
-    // Determine extracted dist location (may be dist/ or root-level files)
-    const distDir = existsSync(join(appDir, 'dist'))
-      ? join(appDir, 'dist')
-      : appDir;
-
-    // 4b. Mirror into apps/{slug}/ for the Vite dev server and build pipeline
-    const appsSlugDir = join(APPS_DIR, slug);
-    if (existsSync(appsSlugDir)) rmSync(appsSlugDir, { recursive: true });
-    copyDir(distDir, appsSlugDir);
-    // 5. Validate marketplace.json exists (in the tarball root, not dist/)
-    const manifestInTar  = join(appDir, 'marketplace.json');
+export async function downloadArtifact(app) {
+  const { repo, version = 'latest' } = app;
+  assertSafeTarget(repo, version, repo ?? '(unnamed entry)');
 
-    // Also copy marketplace.json if present alongside the dist dir
-    if (existsSync(manifestInTar)) {
-      copyFileSync(manifestInTar, join(appsSlugDir, 'marketplace.json'));
-    }
-    log(`Synced to apps/${slug}/`);
-    const manifestInDist = join(distDir, 'marketplace.json');
-    let manifest = null;
+  const workDir = join(DOWNLOAD_DIR, repo.replace('/', '__'));
+  if (existsSync(workDir)) rmSync(workDir, { recursive: true });
+  mkdirSync(workDir, { recursive: true });
 
-    if (existsSync(manifestInTar)) {
-      manifest = JSON.parse(readFileSync(manifestInTar, 'utf8'));
-    } else if (existsSync(manifestInDist)) {
-      manifest = JSON.parse(readFileSync(manifestInDist, 'utf8'));
-    } else {
-      warn(`No marketplace.json found in artifact for ${slug}. Using apps.json metadata.`);
-    }
+  log(`Fetching release info for ${repo}@${version}…`);
+  let release;
+  try {
+    release = await fetchRelease(repo, version);
+  } catch (err) {
+    fail(`Could not fetch release for ${repo}@${version}: ${err.message}`);
+  }
+  log(`Found release: ${release.tag_name} (${release.published_at?.slice(0, 10)})`);
 
-    // 6. Validate headless HTML (spot-check index.html)
-    const indexHtml = join(distDir, app.entryPoint || 'index.html');
-    if (existsSync(indexHtml)) {
-      const html = readFileSync(indexHtml, 'utf8');
-      checkHeadlessMarker(
-        html,
-        `${slug}/index.html`,
-        'See contract/HEADLESS_RULES.md — ensure the app is built with --headless.',
-      );
-    } else {
-      warn(`${slug}: entryPoint '${app.entryPoint || 'index.html'}' not found in artifact.`);
-    }
+  const asset   = findArtifactAsset(release, repo);
+  const tarPath = join(workDir, ARTIFACT_NAME);
 
-    ok(`${slug} ready (${release.tag_name})`);
+  checkArtifactSize(asset.size, `${repo}@${release.tag_name}`);
+  log(`Downloading ${asset.name} (${mb(asset.size)} MB)…`);
+  await downloadAsset(repo, asset.id, asset.name, tarPath);
 
-    enriched.push({
-      ...app,
-      // Merge manifest fields if present (manifest wins over apps.json for display fields)
-      name:        manifest?.name        ?? app.name,
-      description: manifest?.description ?? app.description,
-      icon:        manifest?.icon        ?? app.icon,
-      tags:        manifest?.tags        ?? app.tags ?? [],
-      entryPoint:  manifest?.entryPoint  ?? app.entryPoint ?? 'index.html',
-      pages:       manifest?.pages       ?? null,
-      // Build metadata
-      distDir,
-      releaseTag:  release.tag_name,
-      releasedAt:  release.published_at,
-    });
-  }
+  // The API reports a size; trust the bytes on disk over the metadata.
+  checkArtifactSize(statSync(tarPath).size, `${repo}@${release.tag_name}`);
 
-  return enriched;
+  return { tarPath, releaseTag: release.tag_name, releasedAt: release.published_at };
 }
diff --git a/scripts/setup-test-apps.mjs b/scripts/setup-test-apps.mjs
index 88f30a5..ec09727 100644
--- a/scripts/setup-test-apps.mjs
+++ b/scripts/setup-test-apps.mjs
@@ -6,17 +6,23 @@
  *
  * The committed apps.json is this script's output; the Playwright webServer runs
  * it before every build so the registry stays in sync. It registers:
- *   • the vendored docs-example fixture twice (two slugs) so the suite can
- *     exercise both the landing catalog and cross-app navigation,
+ *   • the vendored docs-example fixture, whose manifest declares two apps —
+ *     `user-guide` (crawled) and `guide-mirror` (a `pages` manifest) — so the
+ *     suite can exercise the landing catalog, cross-app navigation and both
+ *     routing paths from one artifact,
  *   • an iframe entry (issue #10),
- *   • a single-page bundle holding two docs (issue #35).
+ *   • a markdown bundle holding two docs (issue #35).
  * No network, no GITHUB_TOKEN, no sibling repo or per-app build toolchain.
  *
- * The `prebuilt` field is consumed by scripts/build-vite.js (preparePrebuilt).
+ * Note what the entries do *not* carry: no slug, name, description, icon or
+ * tags. Those live in each artifact's kb-docs.json — the registry only records
+ * where an artifact comes from. See contract/ARTIFACT.md.
+ *
+ * The `prebuilt` field is consumed by scripts/build-vite.js (stageEntry).
  *
  * Override the packaged artifact with KB_EXAMPLE_ARTIFACT (absolute path or path
  * relative to the repo root) — e.g. to point at a different doc app's
- * dist.tar.gz / dist.
+ * kb-docs.tar.gz / an unpacked artifact directory.
  */
 
 import { mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
@@ -30,15 +36,15 @@ const ROOT = join(__dirname, '..');
 
 // Vendored fixture (committed under tests/fixtures/) keeps the build + tests fully
 // hermetic — no sibling repo, no network, no GITHUB_TOKEN.
-const DEFAULT_ARTIFACT = 'tests/fixtures/docs-example.dist.tar.gz';
+const DEFAULT_ARTIFACT = 'tests/fixtures/docs-example.kb-docs.tar.gz';
 const artifact = process.env.KB_EXAMPLE_ARTIFACT || DEFAULT_ARTIFACT;
 const artifactAbs = isAbsolute(artifact) ? artifact : resolve(ROOT, artifact);
 
 if (!existsSync(artifactAbs)) {
   console.error(
     `\x1b[31m✗ Example artifact not found:\x1b[0m ${artifactAbs}\n` +
-    `  Expected the vendored fixture at tests/fixtures/docs-example.dist.tar.gz\n` +
-    `  or set KB_EXAMPLE_ARTIFACT to a dist.tar.gz / dist directory.`,
+    `  Expected the vendored fixture at tests/fixtures/docs-example.kb-docs.tar.gz\n` +
+    `  or set KB_EXAMPLE_ARTIFACT to a kb-docs.tar.gz or an unpacked artifact directory.`,
   );
   process.exit(1);
 }
@@ -95,7 +101,7 @@ const RELEASE_PROCESS_BODY = `<h1 id="release-process" tabindex="-1">Release Pro
 <ol>
 <li>Tag the commit.</li>
 <li>Publish the GitHub Release.</li>
-<li>The publish-single-page-docs action attaches <code>dist.tar.gz</code>.</li>
+<li>The publish-single-page-docs action attaches <code>kb-docs.tar.gz</code>.</li>
 </ol>`;
 
 /**
@@ -177,11 +183,10 @@ function writeSinglePageBundle() {
     }
   }
 
-  writeFileSync(join(root, 'bundle.json'), JSON.stringify({
-    marketplaceVersion: '1',
-    type: 'single-page',
-    docs: bundleDocs.map(({ slug, title, description, icon, tags }) => ({
-      slug, title, description, icon, tags, entryPoint: 'index.html',
+  writeFileSync(join(root, 'kb-docs.json'), JSON.stringify({
+    kbVersion: '1',
+    apps: bundleDocs.map(({ slug, title, description, icon, tags }) => ({
+      slug, name: title, description, icon, tags, entryPoint: 'index.html',
     })),
   }, null, 2) + '\n');
 
@@ -196,19 +201,10 @@ const bundleRoot = writeSinglePageBundle();
 // navigation (clicking from one app's card to another) is testable.
 const apps = [
   {
-    slug: 'user-guide',
-    name: 'User Guide',
-    description: 'Primary docs app — the vendored docs-example fixture used as the integration guinea pig.',
-    icon: 'book-open',
-    tags: ['guide', 'getting-started'],
-    prebuilt: artifact,
-  },
-  {
-    slug: 'guide-mirror',
-    name: 'Guide Mirror',
-    description: 'Second registered app (same artifact, different slug) for cross-app navigation tests.',
-    icon: 'book-open',
-    tags: ['mirror', 'cross-app'],
+    // One artifact, two apps: `user-guide` (crawled) and `guide-mirror` (which
+    // carries a `pages` manifest). Their names, descriptions and slugs live in
+    // the artifact's kb-docs.json, not here — the registry only says where the
+    // artifact comes from.
     prebuilt: artifact,
   },
   {
@@ -229,23 +225,22 @@ const apps = [
     headless: false,
   },
   {
-    // single-page onboarding mode (issue #35): one bundle, no per-doc metadata
-    // here — the build expands it into one app per doc from bundle.json.
-    type: 'single-page',
+    // A markdown bundle: one artifact, one app per doc, all of it described by
+    // the artifact's own kb-docs.json. Structurally identical to the packaged
+    // entry above — that sameness is the point.
     prebuilt: BUNDLE_DIR,
   },
   {
     // The sibling example repo (knowledge-base-example-single-page), for looking
     // at real action output in a browser: `npm run build:local && npm run preview`.
-    // Its dist.tar.gz is produced by the real action, so it is the closest thing
-    // to a published bundle without a network round-trip.
+    // Its artifact is produced by the real action, so it is the closest thing to
+    // a published bundle without a network round-trip.
     //
     // `optional` because that repo is not part of this one: when it is not
     // checked out next door — CI, a fresh clone — the build skips this entry with
     // a warning instead of failing. Keep it last so the hermetic fixture above
-    // stays the first single-page entry the suites look at.
-    type: 'single-page',
-    prebuilt: '../knowledge-base-example-single-page/dist.tar.gz',
+    // stays the first bundle the suites look at.
+    prebuilt: '../knowledge-base-example-single-page/kb-docs.tar.gz',
     optional: true,
   },
 ];
diff --git a/src/utils/apps.js b/src/utils/apps.js
index a98d487..48527ce 100644
--- a/src/utils/apps.js
+++ b/src/utils/apps.js
@@ -4,7 +4,8 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, dirname } from 'node:path';
-import { isSinglePage, readExpansionMap, resolveRegistry } from './single-page.js';
+import { EXPANSION_FILE, isIframe, readExpansionMap, resolveRegistry } from './registry.js';
+import { REGISTRY_FILE } from './config.js';
 
 /**
  * Cached result of loadRegistry, keyed by cwd and invalidated by mtime.
@@ -20,15 +21,15 @@ let registryCache = null;
 /** Modification stamp of the two files the registry is built from. */
 function registryStamp(cwd) {
   const mtime = (p) => (existsSync(p) ? statSync(p).mtimeMs : 0);
-  return `${mtime(join(cwd, 'apps.json'))}:${mtime(join(cwd, 'apps', '.single-page.json'))}`;
+  return `${mtime(join(cwd, REGISTRY_FILE))}:${mtime(join(cwd, EXPANSION_FILE))}`;
 }
 
 /**
  * Reads the effective app registry.
  *
- * apps.json is the source of truth, except for `type: "single-page"` entries:
- * those point at a bundle whose docs are only known after the build fetched it,
- * so each one is replaced by the apps it expanded into (see single-page.js).
+ * The registry says where each artifact comes from; the artifact's own manifest
+ * says what it contains. Every non-iframe entry is therefore replaced by the
+ * apps it expanded into during the build (see registry.js).
  *
  * @param {string} cwd - project root (process.cwd())
  */
@@ -38,9 +39,9 @@ export function loadRegistry(cwd) {
     return registryCache.apps;
   }
 
-  const appsJson = join(cwd, 'apps.json');
-  const registry = existsSync(appsJson)
-    ? JSON.parse(readFileSync(appsJson, 'utf-8'))
+  const registryPath = join(cwd, REGISTRY_FILE);
+  const registry = existsSync(registryPath)
+    ? JSON.parse(readFileSync(registryPath, 'utf-8'))
     : [];
 
   const apps = resolveRegistry(registry, readExpansionMap(cwd), (msg) => {
@@ -94,7 +95,7 @@ export function getAppPages(cwd, headless) {
     /** The only registry data a sub-app page needs. */
     const card        = { slug: app.slug, name: app.name ?? app.slug, icon: app.icon };
 
-    if (app.type === 'iframe') {
+    if (isIframe(app)) {
       // iFrame onboarding mode: no artifact on disk — emit a single route that
       // renders a full-viewport <iframe> for the external URL. See issue #10.
       pages.push({
@@ -112,10 +113,14 @@ export function getAppPages(cwd, headless) {
       continue;
     }
 
-    if (isSinglePage(app)) {
-      // Single-page onboarding (issue #35): the artifact holds exactly one
-      // document per app, so there is nothing to crawl — emit its single route
-      // and let the catchall render it in the centred reading column.
+    const crawled = collectHtmlFiles(appDir);
+
+    // A whole app in one document reads better as a centred column than as a
+    // docs site with an empty sidebar — that is what the single-page onboarding
+    // type produced, and it is now inferred from the artifact rather than
+    // declared in the registry. A manifest that supplies `pages` has opted into
+    // site navigation and is never treated this way, even at one page.
+    if (!app.pages && crawled.length === 1) {
       pages.push({
         routePath:   app.slug,
         file:        join(appDir, app.entryPoint ?? 'index.html'),
@@ -131,7 +136,9 @@ export function getAppPages(cwd, headless) {
     }
 
     if (Array.isArray(app.pages) && app.pages.length > 0) {
-      // Manifest-driven routing: use the pages array from marketplace.json
+      // Manifest-driven routing: the artifact's `pages` list is authoritative,
+      // so the directory is not crawled and nothing it happens to contain
+      // becomes a route the publisher did not ask for.
       for (const page of app.pages) {
         const file        = join(appDir, page.path);
         const fileRelDir  = dirname(page.path).replace(/\\/g, '/').replace(/^\.$/, '');
@@ -150,8 +157,8 @@ export function getAppPages(cwd, headless) {
         });
       }
     } else {
-      // Fallback: crawl the filesystem for all HTML files
-      for (const file of collectHtmlFiles(appDir)) {
+      // Fallback: every HTML file in the artifact becomes a route.
+      for (const file of crawled) {
         const fileRelDir = relative(appDir, dirname(file)).replace(/\\/g, '/');
         const routeParts = [app.slug];
         if (fileRelDir) routeParts.push(fileRelDir);
diff --git a/src/utils/config.js b/src/utils/config.js
index d8c089c..4ff1c42 100644
--- a/src/utils/config.js
+++ b/src/utils/config.js
@@ -40,3 +40,17 @@ export const BASE_PATH = `/${PATH_PREFIX}`;
 export function isHeadlessBuild(env = process.env) {
   return env.KB_HEADLESS === 'true';
 }
+
+/**
+ * The registry file this build reads, relative to the project root.
+ *
+ * `apps.json` here is the CI and preview registry: the vendored fixture plus the
+ * optional sibling example. A real deployment owns its own registry in its own
+ * repository and points this at it, so that this repo is a build tool rather
+ * than a list of somebody's documentation.
+ *
+ * Read at module load: both the orchestrator and Astro's getStaticPaths need the
+ * same answer within one build, and an environment variable that changed
+ * halfway would silently produce a dist/ assembled from two registries.
+ */
+export const REGISTRY_FILE = process.env.KB_REGISTRY?.trim() || 'apps.json';
diff --git a/src/utils/registry.js b/src/utils/registry.js
new file mode 100644
index 0000000..6e0ca75
--- /dev/null
+++ b/src/utils/registry.js
@@ -0,0 +1,366 @@
+// src/utils/registry.js
+//
+// The registry and the artifact manifest, in one place.
+//
+// apps.json says *where* an artifact comes from. kb-docs.json, inside the
+// artifact, says *what* it is. Those two sentences are the whole design:
+//
+//   apps.json     [{ "repo": "org/repo", "version": "latest" }]
+//   kb-docs.json  { "kbVersion": "1", "apps": [ { slug, name, description, … } ] }
+//
+// Every source — a GitHub release, a prebuilt tarball, a local checkout — yields
+// the same thing: a directory holding kb-docs.json plus one subdirectory per
+// app. So there is one reader, one validator and one install path, and adding,
+// renaming or removing a doc never touches this repository.
+//
+// Imported by scripts/build-vite.js (which installs), scripts/fetch-apps.js
+// (which downloads) and src/utils/apps.js (so Astro resolves the same registry
+// the build did).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** Manifest at the root of a kb-docs.tar.gz artifact. See contract/ARTIFACT.md. */
+export const MANIFEST = 'kb-docs.json';
+/** The release asset a docs repo publishes. */
+export const ARTIFACT_NAME = 'kb-docs.tar.gz';
+/** The contract version this knowledge base understands. */
+export const KB_VERSION = '1';
+/** Where the build records what each artifact expanded into, for Astro to read. */
+export const EXPANSION_FILE = join('apps', '.registry.json');
+
+/** Icon set — kept in sync with contract/kb-docs.schema.json. */
+const ICONS = [
+  'book-open', 'cube', 'chip', 'chart-bar', 'shield',
+  'cog', 'terminal', 'globe', 'layers', 'lightning-bolt',
+  'document', 'collection', 'puzzle', 'database',
+];
+const DEFAULT_ICON = 'book-open';
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Artifact size budget from contract/ARTIFACT.md, in bytes. */
+export const SIZE_WARN  = 20 * 1024 * 1024;
+export const SIZE_LIMIT = 100 * 1024 * 1024;
+
+// ── Registry entries ──────────────────────────────────────────────────────────
+
+/** The three ways an entry can name an artifact, in precedence order. */
+const SOURCES = ['repo', 'prebuilt', 'localPath'];
+
+/**
+ * Display fields that used to be duplicated into apps.json and are now read
+ * from the artifact. Rejected rather than ignored: an onboarding PR that sets
+ * one of these has a mistaken idea of where metadata lives, and silently
+ * dropping it would leave the author waiting for a catalog card that never
+ * changes.
+ */
+const ARTIFACT_OWNED = ['slug', 'name', 'description', 'icon', 'tags', 'entryPoint', 'pages'];
+
+export function isIframe(app) {
+  return app?.type === 'iframe';
+}
+
+/**
+ * Stable identity of an artifact entry — its source.
+ *
+ * Keys the expansion map, so Astro can splice each artifact's apps back into the
+ * registry at the position its entry occupies.
+ */
+export function sourceKey(app) {
+  for (const field of SOURCES) if (app?.[field]) return app[field];
+  throw new Error(`apps.json: an entry names no artifact — it needs one of ${SOURCES.join(', ')}`);
+}
+
+/** Filesystem-safe form of a source key, for staging directory names. */
+export function stagingName(key) {
+  return key.replace(/[^a-z0-9._-]+/gi, '__');
+}
+
+/**
+ * Validates one registry entry against the v2 rules.
+ *
+ * @param {object} app
+ * @param {number} index - position in apps.json, for the error message
+ */
+export function validateEntry(app, index) {
+  const where = `apps.json[${index}]`;
+  if (!app || typeof app !== 'object' || Array.isArray(app)) {
+    throw new Error(`${where}: expected an object.`);
+  }
+
+  // An iframe entry has no artifact to read metadata from, so it is the one
+  // place display fields still belong. See issue #10 — it is a stopgap.
+  if (isIframe(app)) {
+    if (!app.slug) throw new Error(`${where}: an iframe entry needs a "slug".`);
+    if (!SLUG_RE.test(app.slug)) {
+      throw new Error(`${where}: slug ${JSON.stringify(app.slug)} must be lowercase kebab-case.`);
+    }
+    if (!app.url) throw new Error(`${app.slug}: an iframe entry needs a "url".`);
+    for (const field of SOURCES) {
+      if (app[field]) throw new Error(`${app.slug}: an iframe entry must not also set "${field}".`);
+    }
+    return;
+  }
+
+  const named = SOURCES.filter((field) => app[field]);
+  if (named.length === 0) {
+    throw new Error(
+      `${where}: needs exactly one of "repo", "prebuilt" or "localPath" — see contract/ARTIFACT.md.`,
+    );
+  }
+  if (named.length > 1) {
+    throw new Error(`${where}: names more than one source (${named.join(', ')}); pick one.`);
+  }
+
+  const present = ARTIFACT_OWNED.filter((field) => app[field] !== undefined);
+  if (present.length > 0) {
+    throw new Error(
+      `${where} (${sourceKey(app)}): sets ${present.map((f) => `"${f}"`).join(', ')}, which the artifact owns.\n` +
+      `     Move it to ${MANIFEST} in the publishing repo — the registry records where an artifact\n` +
+      `     comes from and nothing else. See contract/ARTIFACT.md.`,
+    );
+  }
+
+  if (app.type !== undefined) {
+    throw new Error(
+      `${where} (${sourceKey(app)}): "type" is only for iframe entries. A packaged site and a set of\n` +
+      `     single-page docs are both just apps in a ${MANIFEST} manifest now.`,
+    );
+  }
+  if (app.version !== undefined && !app.repo) {
+    throw new Error(`${where} (${sourceKey(app)}): "version" pins a release, so it needs "repo".`);
+  }
+  if (app.pack !== undefined && !app.localPath) {
+    throw new Error(`${where} (${sourceKey(app)}): "pack" is the local build command, so it needs "localPath".`);
+  }
+  if (app.optional && app.repo) {
+    throw new Error(
+      `${where} (${app.repo}): "optional" is for artifacts that live outside this repo and may be absent.\n` +
+      `     A "repo" entry is fetched, so a missing release is a real failure.`,
+    );
+  }
+}
+
+// ── Manifest ──────────────────────────────────────────────────────────────────
+
+/**
+ * Locates the manifest inside a staged artifact.
+ *
+ * Artifacts are packed with the manifest at the archive root, but a repo may
+ * also wrap one in dist/ — accept both rather than fail on a detail of the
+ * packing step that the publishing repo did not choose deliberately.
+ */
+export function findManifestRoot(stageDir) {
+  for (const candidate of [stageDir, join(stageDir, 'dist')]) {
+    if (existsSync(join(candidate, MANIFEST))) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Reads and validates a manifest's envelope.
+ *
+ * Per-app validation happens in expandManifest, which can also check the
+ * directories on disk.
+ *
+ * @param {string} root   - directory containing kb-docs.json
+ * @param {string} source - human-readable origin, used in error messages
+ */
+export function readManifest(root, source) {
+  const file = join(root, MANIFEST);
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new Error(`${source}: ${MANIFEST} is not valid JSON — ${err.message}`);
+  }
+
+  if (manifest.kbVersion !== KB_VERSION) {
+    throw new Error(
+      `${source}: ${MANIFEST} declares kbVersion ${JSON.stringify(manifest.kbVersion)}; ` +
+      `this knowledge base understands ${JSON.stringify(KB_VERSION)}.`,
+    );
+  }
+  if (!Array.isArray(manifest.apps) || manifest.apps.length === 0) {
+    throw new Error(`${source}: ${MANIFEST} lists no apps.`);
+  }
+  return manifest;
+}
+
+/**
+ * Turns a manifest into app entries — one per app in the artifact.
+ *
+ * Each returned entry looks like a resolved registry app, so every downstream
+ * consumer (catalog cards, masthead, routing) needs no knowledge of artifacts.
+ * `appDir` is the source directory to copy into apps/{slug}/ and is stripped
+ * before the entry is persisted — see toRegistryEntry.
+ *
+ * @param {object} entry    - the apps.json entry the artifact came from
+ * @param {object} manifest - output of readManifest
+ * @param {string} root     - directory the manifest was read from
+ */
+export function expandManifest(entry, manifest, root) {
+  const source = sourceKey(entry);
+  const seen = new Set();
+  const apps = [];
+
+  for (const [i, app] of manifest.apps.entries()) {
+    const where = `${source}: ${MANIFEST} apps[${i}]`;
+
+    if (typeof app?.slug !== 'string' || !SLUG_RE.test(app.slug)) {
+      throw new Error(`${where} has an invalid slug ${JSON.stringify(app?.slug)} — expected lowercase kebab-case.`);
+    }
+    if (seen.has(app.slug)) {
+      throw new Error(`${where} repeats slug "${app.slug}" — slugs must be unique within an artifact.`);
+    }
+    seen.add(app.slug);
+
+    for (const field of ['name', 'description']) {
+      if (typeof app[field] !== 'string' || app[field].trim() === '') {
+        throw new Error(`${where} ("${app.slug}") is missing a ${field}.`);
+      }
+    }
+
+    const entryPoint = app.entryPoint ?? 'index.html';
+    const appDir = join(root, app.slug);
+    if (!existsSync(join(appDir, entryPoint))) {
+      throw new Error(
+        `${where} ("${app.slug}") declares entryPoint "${entryPoint}" but ` +
+        `${app.slug}/${entryPoint} is not in the artifact.`,
+      );
+    }
+
+    apps.push({
+      slug:        app.slug,
+      name:        app.name.trim(),
+      description: app.description.trim(),
+      icon:        ICONS.includes(app.icon) ? app.icon : DEFAULT_ICON,
+      tags:        Array.isArray(app.tags) ? app.tags.slice(0, 5) : [],
+      entryPoint,
+      // The navigation manifest, when the publisher supplied one. Absent means
+      // the build crawls the directory instead.
+      pages:       normalisePages(app.pages, appDir, where),
+      // Carried through from the registry entry: the only two things apps.json
+      // still gets to say about an app it did not describe.
+      ...(entry.headless === undefined ? {} : { headless: entry.headless }),
+      appDir,
+    });
+  }
+
+  return apps;
+}
+
+/**
+ * Validates and sorts a `pages` navigation manifest.
+ *
+ * A page whose file is missing is dropped with the entry named, not silently:
+ * the manifest is authoritative when present, so a stale path would otherwise
+ * produce a route that 404s at runtime rather than at build time.
+ */
+function normalisePages(pages, appDir, where) {
+  if (!Array.isArray(pages) || pages.length === 0) return null;
+
+  const kept = [];
+  for (const [i, page] of pages.entries()) {
+    if (typeof page?.title !== 'string' || typeof page?.path !== 'string') {
+      throw new Error(`${where} pages[${i}] needs a "title" and a "path".`);
+    }
+    if (!Number.isInteger(page.order)) {
+      throw new Error(`${where} pages[${i}] ("${page.title}") needs an integer "order".`);
+    }
+    if (!existsSync(join(appDir, page.path))) {
+      throw new Error(
+        `${where} pages[${i}] ("${page.title}") points at "${page.path}", which is not in the artifact.`,
+      );
+    }
+    kept.push({ title: page.title, path: page.path, order: page.order, section: page.section ?? null });
+  }
+  return kept.sort((a, b) => a.order - b.order);
+}
+
+/** Drops build-only fields so the expansion map stays a plain registry fragment. */
+export function toRegistryEntry({ appDir, ...entry }) {
+  return entry;
+}
+
+// ── Expansion map ─────────────────────────────────────────────────────────────
+// The committed apps.json cannot list the apps (they are discovered from the
+// artifact), and rewriting the registry in place would make a build mutate a
+// checked-in file. Instead the build drops a map next to the artifacts and Astro
+// splices it back in at read time.
+
+export function readExpansionMap(cwd) {
+  const file = join(cwd, EXPANSION_FILE);
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeExpansionMap(cwd, map) {
+  const file = join(cwd, EXPANSION_FILE);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(map, null, 2) + '\n');
+}
+
+/**
+ * Replaces every artifact entry with the apps it expanded into.
+ *
+ * iframe entries pass through untouched and always come straight from apps.json,
+ * so editing the registry never goes stale against the map.
+ *
+ * @param {Array}  registry - raw apps.json contents
+ * @param {object} map      - output of readExpansionMap
+ * @param {(msg: string) => void} [warn]
+ */
+export function resolveRegistry(registry, map, warn = () => {}) {
+  const resolved = [];
+
+  for (const app of registry) {
+    if (isIframe(app)) { resolved.push(app); continue; }
+
+    const key = sourceKey(app);
+    const apps = map[key];
+    if (!apps || apps.length === 0) {
+      // `optional` entries are expected to be missing whenever their artifact is
+      // not checked out (see build-vite.js) — that is not worth a warning.
+      if (!app.optional) {
+        warn(`${key}: artifact has not been prepared yet — run a build to populate ${EXPANSION_FILE}`);
+      }
+      continue;
+    }
+    resolved.push(...apps);
+  }
+
+  assertUniqueSlugs(resolved);
+  return resolved;
+}
+
+/**
+ * Guards against two apps claiming the same URL prefix.
+ *
+ * A repo chooses its own slugs without seeing the rest of the registry, so a
+ * collision with an existing app would otherwise silently overwrite apps/{slug}/.
+ */
+export function assertUniqueSlugs(apps) {
+  const seen = new Map();
+  for (const app of apps) {
+    if (!app.slug) continue;
+    if (seen.has(app.slug)) {
+      throw new Error(
+        `Duplicate app slug "${app.slug}": claimed by both ${describe(seen.get(app.slug))} and ` +
+        `${describe(app)}. Slugs are URL prefixes and must be unique across the whole registry — ` +
+        `rename one of them in the publishing repo's ${MANIFEST} and republish.`,
+      );
+    }
+    seen.set(app.slug, app);
+  }
+  return apps;
+}
+
+function describe(app) {
+  if (isIframe(app)) return `iframe entry "${app.name ?? app.slug}"`;
+  return `app "${app.name ?? app.slug}"`;
+}
diff --git a/src/utils/single-page.js b/src/utils/single-page.js
deleted file mode 100644
index 80fa10c..0000000
--- a/src/utils/single-page.js
+++ /dev/null
@@ -1,254 +0,0 @@
-// src/utils/single-page.js
-//
-// Shared helpers for the "single-page" onboarding type (issue #35).
-//
-// A single-page entry in apps.json points at ONE release artifact that contains
-// MANY docs — the repo publishes them with actions/publish-single-page-docs. The registry
-// entry therefore carries no per-doc metadata:
-//
-//   { "repo": "org/repo", "type": "single-page", "version": "latest" }
-//
-// Everything the catalog needs lives in the artifact's bundle.json manifest, so
-// onboarding a new doc never touches this repository. The build "expands" one
-// registry entry into N knowledge base apps, one per doc.
-//
-// Imported by both scripts/fetch-apps.js (GitHub path) and scripts/build-vite.js
-// (prebuilt/local path) so the two never drift, and by src/utils/apps.js so Astro
-// sees the expanded registry.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-
-export const SINGLE_PAGE_TYPE = 'single-page';
-/** Manifest at the root of a single-page artifact. */
-export const BUNDLE_MANIFEST = 'bundle.json';
-/** Where the build records what each bundle expanded into, for Astro to read. */
-export const EXPANSION_FILE = join('apps', '.single-page.json');
-
-/** Icon set — kept in sync with contract/kb-docs.schema.json. */
-const ICONS = [
-  'book-open', 'cube', 'chip', 'chart-bar', 'shield',
-  'cog', 'terminal', 'globe', 'layers', 'lightning-bolt',
-  'document', 'collection', 'puzzle', 'database',
-];
-const DEFAULT_ICON = 'book-open';
-const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-
-export function isSinglePage(app) {
-  return app?.type === SINGLE_PAGE_TYPE;
-}
-
-/**
- * Stable identity of a single-page registry entry.
- *
- * Used to key the expansion map, so Astro can splice each bundle's docs back
- * into the registry at exactly the position its entry occupies.
- */
-export function bundleKey(app) {
-  const key = app.repo ?? app.prebuilt ?? app.localPath;
-  if (!key) {
-    throw new Error(
-      `apps.json: a "${SINGLE_PAGE_TYPE}" entry needs one of "repo", "prebuilt" or "localPath"`,
-    );
-  }
-  return key;
-}
-
-/** Filesystem-safe form of a bundle key, for staging directory names. */
-export function bundleDirName(key) {
-  return key.replace(/[^a-z0-9._-]+/gi, '__');
-}
-
-/**
- * Locates the bundle root inside an extracted artifact.
- *
- * Bundles are packed with bundle.json at the archive root, but a repo may also
- * publish one wrapped in dist/ — accept both rather than fail on a detail the
- * onboarding repo cannot see.
- */
-export function findBundleRoot(stageDir) {
-  for (const candidate of [stageDir, join(stageDir, 'dist')]) {
-    if (existsSync(join(candidate, BUNDLE_MANIFEST))) return candidate;
-  }
-  return null;
-}
-
-/**
- * Reads and validates a bundle manifest.
- *
- * @param {string} bundleRoot - directory containing bundle.json
- * @param {string} source     - human-readable origin, used in error messages
- */
-export function readBundleManifest(bundleRoot, source) {
-  const file = join(bundleRoot, BUNDLE_MANIFEST);
-  let manifest;
-  try {
-    manifest = JSON.parse(readFileSync(file, 'utf8'));
-  } catch (err) {
-    throw new Error(`${source}: ${BUNDLE_MANIFEST} is not valid JSON — ${err.message}`);
-  }
-
-  if (manifest.marketplaceVersion !== '1') {
-    throw new Error(
-      `${source}: ${BUNDLE_MANIFEST} has marketplaceVersion ` +
-      `${JSON.stringify(manifest.marketplaceVersion)} — this knowledge base understands "1".`,
-    );
-  }
-  if (manifest.type !== SINGLE_PAGE_TYPE) {
-    throw new Error(
-      `${source}: ${BUNDLE_MANIFEST} declares type ${JSON.stringify(manifest.type)}, ` +
-      `expected "${SINGLE_PAGE_TYPE}".`,
-    );
-  }
-  if (!Array.isArray(manifest.docs) || manifest.docs.length === 0) {
-    throw new Error(`${source}: ${BUNDLE_MANIFEST} lists no docs.`);
-  }
-  return manifest;
-}
-
-/**
- * Turns a bundle manifest into knowledge base app entries — one per doc.
- *
- * Each returned entry looks like a normal apps.json app (slug/name/description/
- * icon/tags) so every downstream consumer — catalog cards, masthead, routing —
- * needs no knowledge of bundles. `docDir` is the source directory to copy into
- * apps/{slug}/ and is stripped before the entry is persisted.
- *
- * @param {object} app        - the apps.json entry the bundle came from
- * @param {object} manifest   - output of readBundleManifest
- * @param {string} bundleRoot - directory the manifest was read from
- */
-export function expandBundle(app, manifest, bundleRoot) {
-  const source = bundleKey(app);
-  const seen = new Set();
-  const docs = [];
-
-  for (const [i, doc] of manifest.docs.entries()) {
-    const where = `${source}: ${BUNDLE_MANIFEST} docs[${i}]`;
-
-    if (typeof doc?.slug !== 'string' || !SLUG_RE.test(doc.slug)) {
-      throw new Error(`${where} has an invalid slug ${JSON.stringify(doc?.slug)} — expected lowercase kebab-case.`);
-    }
-    if (seen.has(doc.slug)) {
-      throw new Error(`${where} repeats slug "${doc.slug}" — slugs must be unique within a bundle.`);
-    }
-    seen.add(doc.slug);
-
-    if (typeof doc.title !== 'string' || doc.title.trim() === '') {
-      throw new Error(`${where} ("${doc.slug}") is missing a title.`);
-    }
-    if (typeof doc.description !== 'string' || doc.description.trim() === '') {
-      throw new Error(`${where} ("${doc.slug}") is missing a description.`);
-    }
-
-    const entryPoint = doc.entryPoint ?? 'index.html';
-    const docDir = join(bundleRoot, doc.slug);
-    if (!existsSync(join(docDir, entryPoint))) {
-      throw new Error(
-        `${where} ("${doc.slug}") declares entryPoint "${entryPoint}" but ` +
-        `${doc.slug}/${entryPoint} is not in the artifact.`,
-      );
-    }
-
-    docs.push({
-      slug:        doc.slug,
-      name:        doc.title.trim(),
-      description: doc.description.trim(),
-      icon:        ICONS.includes(doc.icon) ? doc.icon : DEFAULT_ICON,
-      tags:        Array.isArray(doc.tags) ? doc.tags.slice(0, 5) : [],
-      type:        SINGLE_PAGE_TYPE,
-      entryPoint,
-      docDir,
-    });
-  }
-
-  return docs;
-}
-
-/** Drops build-only fields so the expansion map stays a plain registry fragment. */
-export function toRegistryEntry({ docDir, ...entry }) {
-  return entry;
-}
-
-// ── Expansion map ─────────────────────────────────────────────────────────────
-// The committed apps.json cannot list the expanded docs (they are discovered from
-// the artifact), and rewriting the registry in place would make a build mutate a
-// checked-in file. Instead the build drops a map next to the artifacts and Astro
-// splices it back in at read time.
-
-export function readExpansionMap(cwd) {
-  const file = join(cwd, EXPANSION_FILE);
-  if (!existsSync(file)) return {};
-  try {
-    return JSON.parse(readFileSync(file, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-export function writeExpansionMap(cwd, map) {
-  const file = join(cwd, EXPANSION_FILE);
-  mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, JSON.stringify(map, null, 2) + '\n');
-}
-
-/**
- * Replaces every single-page registry entry with the docs it expanded into.
- *
- * Non-single-page entries pass through untouched and always come straight from
- * apps.json, so editing the registry never goes stale against the map.
- *
- * @param {Array}  registry - raw apps.json contents
- * @param {object} map      - output of readExpansionMap
- * @param {(msg: string) => void} [warn]
- */
-export function resolveRegistry(registry, map, warn = () => {}) {
-  const resolved = [];
-
-  for (const app of registry) {
-    if (!isSinglePage(app)) { resolved.push(app); continue; }
-
-    const key = bundleKey(app);
-    const docs = map[key];
-    if (!docs || docs.length === 0) {
-      // `optional` entries are expected to be missing whenever their artifact is
-      // not checked out (see build-vite.js) — that is not worth a warning.
-      if (!app.optional) {
-        warn(`${key}: single-page bundle has not been prepared yet — run a build to populate ${EXPANSION_FILE}`);
-      }
-      continue;
-    }
-    resolved.push(...docs);
-  }
-
-  assertUniqueSlugs(resolved);
-  return resolved;
-}
-
-/**
- * Guards against two apps claiming the same URL prefix.
- *
- * Single-page bundles are the reason this has to be enforced globally: a repo
- * chooses its own slugs without seeing the rest of the registry, so a collision
- * with an existing app would otherwise silently overwrite apps/{slug}/.
- */
-export function assertUniqueSlugs(apps) {
-  const seen = new Map();
-  for (const app of apps) {
-    if (!app.slug) continue;
-    if (seen.has(app.slug)) {
-      throw new Error(
-        `Duplicate app slug "${app.slug}": claimed by both ${describe(seen.get(app.slug))} and ` +
-        `${describe(app)}. Slugs are URL prefixes and must be unique across the whole registry — ` +
-        `rename one of them (for a single-page bundle, change the slug in the publishing repo).`,
-      );
-    }
-    seen.set(app.slug, app);
-  }
-  return apps;
-}
-
-function describe(app) {
-  if (isSinglePage(app)) return `single-page doc "${app.name ?? app.slug}"`;
-  return `apps.json entry "${app.name ?? app.slug}"`;
-}
diff --git a/tests/artifact-safety.spec.js b/tests/artifact-safety.spec.js
index 3f9516f..78b4b06 100644
--- a/tests/artifact-safety.spec.js
+++ b/tests/artifact-safety.spec.js
@@ -90,16 +90,16 @@ test.afterEach(() => {
 
 test.describe('extractTarball', () => {
   test('extracts a well-formed bundle', () => {
-    const tar = join(workDir, 'dist.tar.gz');
+    const tar = join(workDir, 'kb-docs.tar.gz');
     writeTarball(tar, [
-      { name: 'bundle.json', content: '{"marketplaceVersion":"1"}' },
+      { name: 'kb-docs.json', content: '{"kbVersion":"1"}' },
       { name: 'my-doc/index.html', content: '<html data-kb-headless="true"></html>' },
     ]);
 
     const dest = join(workDir, 'out');
     extractTarball(tar, dest, 'good-bundle');
 
-    expect(readFileSync(join(dest, 'bundle.json'), 'utf8')).toContain('marketplaceVersion');
+    expect(readFileSync(join(dest, 'kb-docs.json'), 'utf8')).toContain('kbVersion');
     expect(readFileSync(join(dest, 'my-doc', 'index.html'), 'utf8')).toContain('data-kb-headless');
   });
 
diff --git a/tests/build-integrity.spec.js b/tests/build-integrity.spec.js
index b7cd733..c582358 100644
--- a/tests/build-integrity.spec.js
+++ b/tests/build-integrity.spec.js
@@ -154,9 +154,62 @@ test.describe('iframe onboarding', () => {
   });
 });
 
+// ── the pages navigation manifest ────────────────────────────────────────────
+//
+// Both apps come out of the same artifact and hold the same directory tree.
+// `user-guide` declares no `pages`, so every HTML file becomes a route.
+// `guide-mirror` declares four, deliberately omitting docs/some-new-page — which
+// is present on disk. That asymmetry is the test: the manifest is authoritative
+// when supplied, and the crawl is what happens only in its absence.
+//
+// This path had never run. fetch-apps.js merged the manifest over the registry
+// entry, build-vite.js discarded the result for packaged apps, and Astro read
+// apps.json alone — so `pages` never reached getAppPages and every app was
+// crawled regardless of what its manifest said.
+test.describe('pages navigation manifest', () => {
+  test('an app with no pages manifest has every HTML file crawled into a route', () => {
+    for (const p of [
+      'user-guide/index.html',
+      'user-guide/docs/index.html',
+      'user-guide/docs/adding-pages/index.html',
+      'user-guide/docs/customising/index.html',
+      'user-guide/docs/some-new-page/index.html',
+      'user-guide/admin/index.html',
+    ]) {
+      expect(existsSync(join(DIST, p)), `expected crawled page ${p}`).toBe(true);
+    }
+  });
+
+  test('an app with a pages manifest gets exactly those routes and no others', () => {
+    for (const p of [
+      'guide-mirror/index.html',
+      'guide-mirror/docs/index.html',
+      'guide-mirror/docs/adding-pages/index.html',
+      'guide-mirror/docs/customising/index.html',
+    ]) {
+      expect(existsSync(join(DIST, p)), `expected manifest page ${p}`).toBe(true);
+    }
+
+    // Present in the artifact, absent from the manifest, so not a route — while
+    // the very same file is a route under the crawled app.
+    expect(
+      existsSync(join(DIST, 'guide-mirror/docs/some-new-page/index.html')),
+      'a page the manifest omits must not be served',
+    ).toBe(false);
+    expect(existsSync(join(DIST, 'user-guide/docs/some-new-page/index.html'))).toBe(true);
+  });
+
+  test('titles come from the manifest, not from the document', () => {
+    // "Adding Pages" is the manifest title for a page whose own <title> differs;
+    // the masthead sub-nav is what surfaces it.
+    const html = read('guide-mirror/docs/adding-pages/index.html');
+    expect(html).toContain('Adding Pages');
+  });
+});
+
 // ── single-page onboarding (issue #35) ──────────────────────────────────────
 //
-// One registry entry (`type: "single-page"`, no per-doc metadata) points at a
+// One registry entry (a source and nothing else) points at a
 // bundle holding two docs; the build must expand it into two independent apps.
 test.describe('single-page onboarding', () => {
   test('one bundle entry expands into one app per doc', () => {
@@ -167,19 +220,34 @@ test.describe('single-page onboarding', () => {
     expect(existsSync(join(DIST, 'platform-overview/docs')), 'single-page app must emit exactly one route').toBe(false);
   });
 
-  test('apps.json carries no per-doc metadata — the bundle manifest supplies it', () => {
+  test('the registry carries no metadata at all — every manifest supplies its own', () => {
     const registry = JSON.parse(readFileSync(join(ROOT, 'apps.json'), 'utf8'));
-    const entry = registry.find((a) => a.type === 'single-page');
-    expect(entry, 'no single-page entry in apps.json').toBeTruthy();
-    expect(entry.slug, 'a single-page entry must not name a slug').toBeUndefined();
-    expect(entry.name).toBeUndefined();
+    const artifactEntries = registry.filter((a) => a.type !== 'iframe');
+    expect(artifactEntries.length, 'expected artifact entries in the registry').toBeGreaterThan(0);
+
+    // The whole point of the source-only registry: an entry names a source and
+    // nothing else, so onboarding a doc never edits this repository again.
+    for (const entry of artifactEntries) {
+      for (const field of ['slug', 'name', 'description', 'icon', 'tags', 'entryPoint', 'pages', 'type']) {
+        expect(entry[field], `registry entry must not carry "${field}"`).toBeUndefined();
+      }
+      expect(
+        Boolean(entry.repo) || Boolean(entry.prebuilt) || Boolean(entry.localPath),
+        'every artifact entry names exactly one source',
+      ).toBe(true);
+    }
 
-    // …yet the catalog knows both docs, which can only come from bundle.json.
+    // …yet the catalog knows every app, which can only come from the manifests.
     const html = read('index.html');
-    expect(html).toContain('Platform Overview');
-    expect(html).toContain('Release Process');
-    expect(html).toContain('href="/knowledge-base/platform-overview/"');
-    expect(html).toContain('href="/knowledge-base/release-process/"');
+    for (const [name, slug] of [
+      ['Platform Overview', 'platform-overview'],
+      ['Release Process',   'release-process'],
+      ['User Guide',        'user-guide'],
+      ['Guide Mirror',      'guide-mirror'],
+    ]) {
+      expect(html).toContain(name);
+      expect(html).toContain(`href="/knowledge-base/${slug}/"`);
+    }
   });
 
   test('renders in the centred reading column, with no sidebar', () => {
diff --git a/tests/fixtures/docs-example.dist.tar.gz b/tests/fixtures/docs-example.dist.tar.gz
deleted file mode 100644
index 6cfa198..0000000
Binary files a/tests/fixtures/docs-example.dist.tar.gz and /dev/null differ
diff --git a/tests/fixtures/docs-example.kb-docs.tar.gz b/tests/fixtures/docs-example.kb-docs.tar.gz
new file mode 100644
index 0000000..39fd1c8
Binary files /dev/null and b/tests/fixtures/docs-example.kb-docs.tar.gz differ
diff --git a/tests/fixtures/single-page-bundle/bundle.json b/tests/fixtures/single-page-bundle/kb-docs.json
similarity index 78%
rename from tests/fixtures/single-page-bundle/bundle.json
rename to tests/fixtures/single-page-bundle/kb-docs.json
index 5b49be8..3d284ca 100644
--- a/tests/fixtures/single-page-bundle/bundle.json
+++ b/tests/fixtures/single-page-bundle/kb-docs.json
@@ -1,10 +1,9 @@
 {
-  "marketplaceVersion": "1",
-  "type": "single-page",
-  "docs": [
+  "kbVersion": "1",
+  "apps": [
     {
       "slug": "platform-overview",
-      "title": "Platform Overview",
+      "name": "Platform Overview",
       "description": "How the platform is wired together, endpoint by endpoint.",
       "icon": "layers",
       "tags": [
@@ -15,7 +14,7 @@
     },
     {
       "slug": "release-process",
-      "title": "Release Process",
+      "name": "Release Process",
       "description": "How a release is cut and how the docs bundle gets attached.",
       "icon": "cog",
       "tags": [
diff --git a/tests/fixtures/single-page-bundle/release-process/index.html b/tests/fixtures/single-page-bundle/release-process/index.html
index 7cd6cc6..b96ff70 100644
--- a/tests/fixtures/single-page-bundle/release-process/index.html
+++ b/tests/fixtures/single-page-bundle/release-process/index.html
@@ -18,7 +18,7 @@ <h2 id="steps" tabindex="-1">Steps <a class="kb-anchor" href="#steps">#</a></h2>
 <ol>
 <li>Tag the commit.</li>
 <li>Publish the GitHub Release.</li>
-<li>The publish-single-page-docs action attaches <code>dist.tar.gz</code>.</li>
+<li>The publish-single-page-docs action attaches <code>kb-docs.tar.gz</code>.</li>
 </ol>
 </article>
 </body>