diff --git a/.github/workflows/validate-doc-app.yml b/.github/workflows/validate-doc-app.yml
index ecca0a1..906ef8a 100644
--- a/.github/workflows/validate-doc-app.yml
+++ b/.github/workflows/validate-doc-app.yml
@@ -1,190 +1,70 @@
-# Reusable workflow — validate a doc app against the knowledge-base contract.
+# Reusable workflow — DEPRECATED.
 #
-# Called by doc-app repos in their own CI to verify the app meets the knowledge base
-# contract before raising a PR or publishing a release.
+# This workflow validated a doc app against the pre-v1 contract: a
+# `marketplace.json` in the repo root, a `dist/` produced by
+# `npm run build -- --headless`, and a schema fetched from
+# `contract/schema.json`.
 #
-# Usage in a doc repo (.github/workflows/validate.yml):
+# None of those exist any more. The v1 contract is one release asset,
+# `kb-docs.tar.gz`, carrying a `kb-docs.json` manifest — see
+# `contract/ARTIFACT.md`. Validation is no longer a separate workflow a doc repo
+# has to remember to call: the publishing action validates the manifest and the
+# built HTML before it packs anything, so a repo that publishes is a repo that
+# was checked.
 #
-#   jobs:
-#     validate:
-#       uses: AbsaOSS/knowledge-base/.github/workflows/validate-doc-app.yml@master
+# Replace a call to this workflow with the publishing step itself:
 #
-# The calling repo must have:
-#   - marketplace.json in the repo root
-#   - `npm run build -- --headless` producing dist/
+#   - uses: actions/checkout@v4
+#   - run: <your headless build>
+#   - uses: AbsaOSS/knowledge-base/actions/publish-docs@v1
+#     with:
+#       manifest: kb-docs.json
+#       dist: dist
 #
-name: Validate Doc App
+# It fails loudly rather than silently passing, because a green check against a
+# contract that no longer exists is worse than no check.
+#
+# Removed once the migration is done — see issue #76.
+name: Validate Doc App (deprecated)
 
 on:
   workflow_call:
     inputs:
       node-version:
-        description: 'Node.js version to use'
+        description: 'Unused. Kept so an existing caller fails on the message below rather than on an unexpected-input error.'
         type: string
+        required: false
         default: '24'
 
 permissions:
   contents: read
 
 jobs:
-  validate:
-    name: Validate knowledge base contract
+  deprecated:
+    name: Deprecated — use actions/publish-docs
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Setup Node.js
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: ${{ inputs.node-version }}
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      # ── Validate marketplace.json ──────────────────────────────────────────
-      - name: Validate marketplace.json exists
+      - name: Explain the replacement
         run: |
-          if [ ! -f marketplace.json ]; then
-            echo "::error file=marketplace.json::marketplace.json not found in repo root."
-            echo "See https://github.com/AbsaOSS/knowledge-base/blob/master/contract/HEADLESS_RULES.md"
-            exit 1
-          fi
-          echo "✓ marketplace.json found"
-
-      - name: Validate marketplace.json schema
-        run: |
-          # ajv may not be a dependency of the doc repo — install it transiently.
-          npm install --no-save ajv@^8
-          node --input-type=module <<'EOF'
-          import { readFileSync } from 'node:fs';
-          import Ajv from 'ajv';
-
-          const manifest = JSON.parse(readFileSync('marketplace.json', 'utf8'));
-          const schemaUrl =
-            'https://raw.githubusercontent.com/AbsaOSS/knowledge-base/master/contract/schema.json';
-
-          const res = await fetch(schemaUrl);
-          if (!res.ok) {
-            console.warn('⚠ Could not fetch remote schema — skipping schema validation');
-            process.exit(0);
-          }
-          const schema = await res.json();
-          const validate = new Ajv({ allErrors: true }).compile(schema);
-
-          if (!validate(manifest)) {
-            console.error('✗ marketplace.json validation errors:');
-            for (const err of validate.errors) {
-              console.error(`  ${err.instancePath || '/'}: ${err.message}`);
-            }
-            process.exit(1);
-          }
-          console.log('✓ marketplace.json is valid');
-          EOF
-
-      # ── Build headless ─────────────────────────────────────────────────────
-      - name: Build headless
-        run: npm run build -- --headless
-
-      # ── Check dist/ output ─────────────────────────────────────────────────
-      - name: Check dist/ exists
-        run: |
-          if [ ! -d dist ]; then
-            echo "::error::dist/ directory not found after build. Check your build script."
-            exit 1
-          fi
-          echo "✓ dist/ exists"
-
-      - name: Check entryPoint exists
-        run: |
-          ENTRY=$(node -e "const m=require('./marketplace.json'); console.log(m.entryPoint || 'index.html')")
-          if [ ! -f "dist/${ENTRY}" ]; then
-            echo "::error::dist/${ENTRY} (entryPoint) not found after headless build."
-            exit 1
-          fi
-          echo "✓ dist/${ENTRY} found"
-
-      # ── Validate headless HTML structure ───────────────────────────────────
-      - name: Check data-kb-headless attribute
-        run: |
-          ENTRY=$(node -e "const m=require('./marketplace.json'); console.log(m.entryPoint || 'index.html')")
-          if ! grep -q 'data-kb-headless="true"' "dist/${ENTRY}"; then
-            echo "::error file=dist/${ENTRY}::Missing data-kb-headless=\"true\" on <html> element."
-            echo "Add data-kb-headless=\"true\" to the <html> tag when building with --headless."
-            exit 1
-          fi
-          echo "✓ data-kb-headless=\"true\" found"
-
-      - name: Check no fixed site header in headless output
-        run: |
-          VIOLATIONS=$(grep -rl 'class="[^"]*fixed[^"]*top-0[^"]*inset-x-0' dist/ || true)
-          if [ -n "$VIOLATIONS" ]; then
-            echo "::warning::Found potential fixed top-bar elements in headless output:"
-            echo "$VIOLATIONS"
-            echo "Ensure the site header is omitted when building with --headless."
-          else
-            echo "✓ No fixed site headers detected in headless output"
-          fi
-
-      - name: Check all asset paths are relative
-        run: |
-          node --input-type=module <<'EOF'
-          import { readdirSync, statSync, readFileSync } from 'node:fs';
-          import { join, extname } from 'node:path';
-
-          function collectHtml(dir) {
-            const files = [];
-            for (const e of readdirSync(dir)) {
-              const p = join(dir, e);
-              if (statSync(p).isDirectory()) files.push(...collectHtml(p));
-              else if (extname(e) === '.html') files.push(p);
-            }
-            return files;
-          }
-
-          let violations = 0;
-          for (const file of collectHtml('dist')) {
-            const html = readFileSync(file, 'utf8');
-            const matches = [...html.matchAll(/(?:href|src|action)="(\/[^/"'][^"]*?)"/g)];
-            for (const [, path] of matches) {
-              if (!path.startsWith('//') && !path.startsWith('/favicon')) {
-                console.error(`::warning file=${file}::Absolute path found: ${path}`);
-                violations++;
-              }
-            }
-          }
-          if (violations > 0) {
-            console.error(
-              `\n${violations} absolute path(s) found. The knowledge-base mounts each app under ` +
-              `/knowledge-base/{slug}/ and rewrites relative paths — absolute paths will 404.`,
-            );
-            process.exit(1);
-          }
-          console.log('✓ All asset paths are relative');
-          EOF
-
-      # ── Design tokens (soft check) ─────────────────────────────────────────
-      - name: Check knowledge-base design tokens in CSS
-        run: |
-          CSS_FILES=$(find dist/ -name "*.css" | head -5)
-          if [ -z "$CSS_FILES" ]; then
-            echo "::warning::No CSS files found in dist/"
-          else
-            FOUND=false
-            for f in $CSS_FILES; do
-              if grep -q -- '--color-kb-500\|#af144b' "$f"; then
-                FOUND=true
-                break
-              fi
-            done
-            if [ "$FOUND" = "false" ]; then
-              echo "::warning::knowledge-base brand token (--color-kb-500 / #af144b) not found in dist CSS."
-              echo "See contract/STYLE_GUIDE.md for the design-token contract."
-            else
-              echo "✓ knowledge-base design tokens detected in CSS"
-            fi
-          fi
-
-      - name: Validation summary
-        run: echo "✓ All contract checks passed for $(node -e "console.log(require('./marketplace.json').slug)")"
+          {
+            echo "### This workflow is deprecated"
+            echo
+            echo "It validated the pre-v1 contract (\`marketplace.json\` + \`dist/\`), which no longer exists."
+            echo
+            echo "The v1 contract is a single \`kb-docs.tar.gz\` release asset carrying a \`kb-docs.json\` manifest."
+            echo "Validation now happens inside the publishing action, so replace your call to this workflow with:"
+            echo
+            echo '```yaml'
+            echo "- uses: actions/checkout@v4"
+            echo "- run: <your headless build>"
+            echo "- uses: AbsaOSS/knowledge-base/actions/publish-docs@v1"
+            echo "  with:"
+            echo "    manifest: kb-docs.json"
+            echo "    dist: dist"
+            echo '```'
+            echo
+            echo "See https://github.com/AbsaOSS/knowledge-base/blob/master/contract/ARTIFACT.md"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          echo "::error::validate-doc-app.yml is deprecated. The pre-v1 contract it checked (marketplace.json + dist/) no longer exists. Use AbsaOSS/knowledge-base/actions/publish-docs@v1 instead — see contract/ARTIFACT.md."
+          exit 1
diff --git a/CLAUDE.md b/CLAUDE.md
index 5bdcc77..a0ec676 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 `dist.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` → `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/`.
 
 ### Key Source Files
 
@@ -88,9 +88,9 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`.
 
 An `apps.json` entry is one of:
 
-- **default (packaged)** — a repo publishes a headless static site as `dist.tar.gz` plus `marketplace.json`. Every HTML file becomes a route.
+- **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 `bundle.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`.
+- **`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`.
 
 ### Two Modes
 
@@ -117,10 +117,11 @@ Root-relative `url()` inside a sub-app's **copied CSS files** is a separate rewr
 ## Contract for Doc Apps
 
 Apps registered in `apps.json` must comply with:
-- `contract/schema.json` — JSON Schema for `marketplace.json` manifest (packaged apps)
+- `contract/ARTIFACT.md` — Normative: the `kb-docs.tar.gz` layout, the `kb-docs.json` manifest, archive and size rules
+- `contract/kb-docs.schema.json` — JSON Schema for `kb-docs.json`
 - `contract/HEADLESS_RULES.md` — Structural requirements (headless HTML, relative paths, `data-kb-headless` attribute)
 - `contract/STYLE_GUIDE.md` — Design tokens and typography (light only — the knowledge base has no dark mode)
-- `contract/SINGLE_PAGE.md` — `bundle.json` format + the copy-paste onboarding workflow for single-page docs
+- `contract/SINGLE_PAGE.md` — The copy-paste onboarding workflow for single-page docs
 
 ## Testing
 
@@ -165,7 +166,7 @@ reference the content-hashed bundle Astro injects, so nothing depends on that fi
 
 An entry may also carry `"optional": true`: the build then skips it with a warning when its
 `prebuilt`/`localPath` artifact is missing, instead of failing. That is how the sibling
-`knowledge-base-example-single-page` repo (a mock docs repo whose `dist.tar.gz` comes from
+`knowledge-base-example-single-page` repo (a mock docs repo whose `kb-docs.tar.gz` comes from
 the real action — `npm run build:local && npm run preview` to view it) can stay registered
 in the committed `apps.json` without breaking CI, which only has this repo.
 
diff --git a/README.md b/README.md
index c101978..6d5dbcb 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
 build time it:
 
 1. Obtains each registered app's built output (`dist/`) — from a **GitHub Release
-   artifact** (`dist.tar.gz`), a **local repo**, or a **prebuilt** tarball/dir.
+   artifact** (`kb-docs.tar.gz`), a **local repo**, or a **prebuilt** tarball/dir.
 2. Rewrites every page's URLs to absolute `/knowledge-base/{slug}/…` paths and
    re-hosts each document under a persistent **masthead** (branding + Library /
    current-app navigation), the same in both modes.
@@ -102,7 +102,7 @@ Each entry registers one doc app. A `slug` is required; the source is one of
     // pick ONE source:
     "repo": "AbsaOSS/my-docs", "version": "latest", // GitHub Release artifact
     // "localPath": "../my-docs",                    // build from local checkout
-    // "prebuilt": "tests/fixtures/my-docs.dist.tar.gz" // prebuilt tarball or dist dir
+    // "prebuilt": "tests/fixtures/my-docs.kb-docs.tar.gz" // prebuilt tarball or dist dir
   }
 ]
 ```
@@ -118,7 +118,7 @@ never quietly produce an empty deployment.
 
 Teams that already host their docs elsewhere and can't yet produce a headless
 package can be listed immediately with an **iframe** entry — no `repo`,
-`marketplace.json`, or artifact needed. It renders as a full-viewport `<iframe>`
+manifest, or artifact needed. It renders as a full-viewport `<iframe>`
 below the knowledge base masthead and shows an **External** badge in the catalogue.
 
 ```jsonc
@@ -167,20 +167,19 @@ jobs:
 
 The action ([`actions/publish-single-page-docs/`](actions/publish-single-page-docs)) renders the markdown
 to headless HTML — GFM tables, task lists, footnotes, highlighted code and
-vendored-mermaid diagrams — packs every doc into one `dist.tar.gz` with a
-`bundle.json` manifest, and attaches it to the repo's latest release.
+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**:
 
 ```jsonc
 {
   "repo": "AbsaOSS/my-service",
-  "type": "single-page",
   "version": "latest"
 }
 ```
 
-The build reads `bundle.json` and expands that one entry into one app per doc —
+The build reads `kb-docs.json` and expands that one entry into one app per doc —
 each with its own catalogue card and URL — so adding or renaming a doc later
 never touches this repository again. Pages render with the masthead and a centred
 reading column, no sidebar. See [`contract/SINGLE_PAGE.md`](contract/SINGLE_PAGE.md)
@@ -189,7 +188,7 @@ and issue #35.
 #### Seeing it for real
 
 `knowledge-base-example-single-page` is a mock docs repo — three markdown files
-and the workflow above, nothing else — whose `dist.tar.gz` is produced by the
+and the workflow above, nothing else — whose `kb-docs.tar.gz` is produced by the
 real action. Check it out next to this repo and:
 
 ```bash
@@ -279,58 +278,57 @@ Apps must comply with the knowledge base contract before they can be registered:
 
 | Document | Description |
 |---|---|
-| [`contract/schema.json`](contract/schema.json) | JSON Schema for `marketplace.json` |
+| [`contract/ARTIFACT.md`](contract/ARTIFACT.md) | Normative: artifact layout, manifest, archive and size rules |
+| [`contract/kb-docs.schema.json`](contract/kb-docs.schema.json) | JSON Schema for `kb-docs.json` |
 | [`contract/HEADLESS_RULES.md`](contract/HEADLESS_RULES.md) | Headless HTML, relative paths, `data-kb-headless` |
 | [`contract/STYLE_GUIDE.md`](contract/STYLE_GUIDE.md) | Design tokens (`--color-kb-*`) and typography — light only; the knowledge base has no dark mode |
-| [`contract/SINGLE_PAGE.md`](contract/SINGLE_PAGE.md) | `bundle.json` format + zero-config markdown onboarding |
+| [`contract/SINGLE_PAGE.md`](contract/SINGLE_PAGE.md) | Zero-config markdown onboarding |
 
 > The checklist and workflows below apply to **packaged** doc apps. Single-page
 > docs skip all of it — the action produces a compliant artifact for you.
 
 ### Checklist
-- [ ] `marketplace.json` in repo root, valid against `contract/schema.json`
+- [ ] `kb-docs.json` in repo root, valid against `contract/kb-docs.schema.json`
 - [ ] `npm run build -- --headless` produces a headless `dist/`
 - [ ] `data-kb-headless="true"` on `<html>` in headless output
 - [ ] No fixed site-level header in headless output
 - [ ] All asset paths relative (no leading `/`)
-- [ ] GitHub Release tagged `v*` with a `dist.tar.gz` asset
+- [ ] GitHub Release with a `kb-docs.tar.gz` asset
 
 ### Reusable validation workflow
 
-Doc repos can enforce the contract in their own CI:
-
-```yaml
-# .github/workflows/validate.yml (in your doc repo)
-on: [push, pull_request]
-jobs:
-  validate:
-    uses: AbsaOSS/knowledge-base/.github/workflows/validate-doc-app.yml@master
-```
+Doc repos do not need a separate validation workflow: the publishing action
+validates the manifest and the built HTML before it packs anything, so a repo
+that publishes successfully is a repo that met the contract.
 
 ### Release workflow for doc repos
 
+Build the site, then hand the output to the publishing action. It validates the
+manifest, checks the HTML against the contract, packs `kb-docs.tar.gz` and
+uploads it to the release — the repo does not assemble the archive itself.
+
 ```yaml
-# .github/workflows/release.yml (in your doc repo)
+# .github/workflows/publish-docs.yml (in your doc repo)
 on:
-  push:
-    tags: ['v*']
+  release:
+    types: [published]
 permissions:
   contents: write
 jobs:
-  release:
+  publish:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with: { node-version: '24', cache: npm }
-      - run: npm ci
-      - run: npm run build -- --headless
-      - run: tar -czf dist.tar.gz dist/ marketplace.json
-      - uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2.6.2
+      - run: npm ci && npm run build -- --headless
+      - uses: AbsaOSS/knowledge-base/actions/publish-docs@v1
         with:
-          files: dist.tar.gz
+          manifest: kb-docs.json
+          dist: dist
 ```
 
+The archive layout and the manifest are specified in
+[`contract/ARTIFACT.md`](contract/ARTIFACT.md).
+
 ---
 
 ## Deployment
@@ -373,7 +371,7 @@ knowledge-base/
 │   └── utils/
 │       ├── apps.js            ← loadRegistry() + getAppPages() page enumeration
 │       ├── config.js          ← PATH_PREFIX / BASE_PATH + isHeadlessBuild()
-│       ├── single-page.js     ← bundle.json parsing + registry expansion
+│       ├── single-page.js     ← manifest parsing + registry expansion
 │       └── transform.js       ← parse5 URL rewriting + sub-app document splitting
 ├── scripts/
 │   ├── build-vite.js          ← Build orchestrator
@@ -393,8 +391,8 @@ knowledge-base/
 │   ├── host/server.mjs        ← Reference web-fragments host (gateway)
 │   ├── fragment-server.mjs    ← nginx-mirroring static server
 │   ├── support/fragment.js    ← Shadow-DOM test helpers
-│   └── fixtures/              ← Vendored docs-example dist.tar.gz + single-page bundle
-├── contract/                  ← marketplace.json schema + rules + style guide
+│   └── fixtures/              ← Vendored docs-example tarball + single-page bundle
+├── contract/                  ← Artifact contract: schema, rules, style guide
 ├── .github/workflows/         ← ci.yml, pages.yml, pr-requirements.yml,
 │                                 validate-doc-app.yml (reusable, for doc repos)
 ├── Dockerfile
diff --git a/actions/publish-single-page-docs/src/inputs.js b/actions/publish-single-page-docs/src/inputs.js
index 6ff6caf..173c668 100644
--- a/actions/publish-single-page-docs/src/inputs.js
+++ b/actions/publish-single-page-docs/src/inputs.js
@@ -11,7 +11,7 @@ import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, join, normalize, relative, sep } from 'node:path';
 import YAML from 'yaml';
 
-/** Icon set — kept in sync with contract/schema.json. */
+/** Icon set — kept in sync with contract/kb-docs.schema.json. */
 export const ICONS = [
   'book-open', 'cube', 'chip', 'chart-bar', 'shield',
   'cog', 'terminal', 'globe', 'layers', 'lightning-bolt',
@@ -20,7 +20,7 @@ export const ICONS = [
 
 export const DEFAULT_ICON = 'book-open';
 
-/** Same rule as contract/schema.json, minus leading/trailing/double hyphens. */
+/** Same rule as contract/kb-docs.schema.json, minus leading/trailing/double hyphens. */
 const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 const MIN_DESCRIPTION = 10;
diff --git a/contract/ARTIFACT.md b/contract/ARTIFACT.md
new file mode 100644
index 0000000..5dd2da7
--- /dev/null
+++ b/contract/ARTIFACT.md
@@ -0,0 +1,181 @@
+# The knowledge base artifact
+
+This is the normative description of what a docs repo publishes and what the
+knowledge base consumes. [`HEADLESS_RULES.md`](./HEADLESS_RULES.md) and
+[`SINGLE_PAGE.md`](./SINGLE_PAGE.md) describe two ways of *producing* one; both
+produce exactly what is described here.
+
+---
+
+## One asset, one manifest
+
+A docs repo attaches a single asset to its GitHub Release:
+
+```
+kb-docs.tar.gz
+├─ kb-docs.json
+├─ <slug-a>/
+│  ├─ index.html          ← entryPoint
+│  └─ assets/…
+└─ <slug-b>/              ← only a bundle publishing several apps has more than one
+   └─ …
+```
+
+The name is `kb-docs.tar.gz`, not `dist.tar.gz`: a docs bundle is not the repo's
+own distribution package, and a release usually carries both.
+
+**Every app the knowledge base serves is a directory in this archive plus an
+entry in `kb-docs.json`.** A repo publishing one documentation site is a manifest
+listing one app. A repo publishing a set of standalone markdown docs is a
+manifest listing several. Nothing downstream distinguishes the two cases.
+
+---
+
+## `kb-docs.json`
+
+At the archive root. UTF-8, no BOM.
+
+```jsonc
+{
+  "kbVersion": "1",
+  "apps": [
+    {
+      "slug": "user-guide",
+      "name": "Knowledge Base User Guide",
+      "description": "Everything you need to publish your own documentation.",
+      "icon": "book-open",
+      "tags": ["guide", "getting-started"],
+      "entryPoint": "index.html",
+      "pages": [
+        { "title": "Overview",   "path": "index.html",                 "order": 1 },
+        { "title": "Publishing", "path": "docs/publishing/index.html", "order": 2, "section": "Guide" }
+      ]
+    }
+  ]
+}
+```
+
+### Top level
+
+| Field | Required | Rules |
+|---|---|---|
+| `kbVersion` | ✅ | Contract version, as a **string**. `"1"` today. A knowledge base that does not understand the value fails the build and says so. |
+| `apps` | ✅ | Non-empty array. One entry per app. |
+
+### Each app
+
+| Field | Required | Rules |
+|---|---|---|
+| `slug` | ✅ | `^[a-z0-9]+(-[a-z0-9]+)*$`, 2–32 characters. Names the directory in the archive **and** the public URL `/knowledge-base/{slug}/`. Must be unique across the entire knowledge base, not just within your bundle — prefix it with your service name. |
+| `name` | ✅ | 2–64 characters. Shown on the catalog card and in the masthead. |
+| `description` | ✅ | 10–280 characters. One sentence, shown on the catalog card. |
+| `entryPoint` | ☐ | Path to the landing page, relative to `<slug>/`. Default `index.html`. |
+| `icon` | ☐ | One of the [icon set](#icon-set). Default `book-open`. |
+| `tags` | ☐ | Up to 5 strings, ≤ 32 characters each. Shown as pills on the card. |
+| `pages` | ☐ | Navigation manifest — see below. Absent means the knowledge base crawls `<slug>/` for HTML. |
+
+### `pages`
+
+When present, this is the **authoritative** route list for the app: the knowledge
+base serves exactly these and does not crawl. Use it to control titles and
+ordering; omit it and every HTML file under `<slug>/` becomes a route with a
+title derived from the document.
+
+| Field | Required | Rules |
+|---|---|---|
+| `title` | ✅ | 1–128 characters. Shown in navigation. |
+| `path` | ✅ | Path to the HTML file, relative to `<slug>/`. Must exist in the archive. |
+| `order` | ✅ | Integer ≥ 0. Lower sorts higher. |
+| `section` | ☐ | ≤ 64 characters. Group heading to display above this page. |
+
+### Icon set
+
+`book-open`, `cube`, `chip`, `chart-bar`, `shield`, `cog`, `terminal`, `globe`,
+`layers`, `lightning-bolt`, `document`, `collection`, `puzzle`, `database`.
+
+An unrecognised icon falls back to `book-open` rather than failing the build —
+an icon is not worth breaking a deployment over.
+
+### Versioning
+
+`kbVersion` is a string so it can become `"1.1"` or `"2"` without changing type.
+
+- **Additive changes** — a new optional field — do not change `kbVersion`. A
+  knowledge base ignores manifest fields it does not recognise, so a newer
+  publisher never breaks an older knowledge base.
+- **Breaking changes** bump the major and ship as a new major tag of the
+  publishing actions. The two move together.
+
+Because unknown fields are ignored rather than rejected, do not rely on the
+knowledge base to catch a typo in an optional field name. Validate against
+[`kb-docs.schema.json`](./kb-docs.schema.json); the publishing actions do this
+for you.
+
+---
+
+## Archive rules
+
+The archive is untrusted input: it comes from another repository and is unpacked
+into a directory this deployment then serves. Extraction is refused outright if
+any member:
+
+- is an absolute path, or carries a drive letter;
+- contains a `..` segment;
+- is a symbolic or hard link;
+- is anything other than `kb-docs.json` or a path under a `<slug>/` directory
+  named in the manifest.
+
+The last rule is what keeps a stray file from becoming a route. A member under a
+directory that the manifest does not declare is ignored with a warning, not
+served.
+
+`kb-docs.json` may also sit under a single `dist/` wrapper; the knowledge base
+accepts that, because it is a detail of the packing step rather than something
+the publishing repo chooses deliberately. Nothing else is unwrapped.
+
+### Size
+
+Every registered artifact is downloaded on every deployment build, so size is a
+shared cost rather than a private one.
+
+| | |
+|---|---|
+| Target | ≤ 20 MB per artifact |
+| Warned | > 20 MB — the build logs the size and names the app |
+| Refused | > 100 MB, which is also GitHub's per-asset release limit |
+
+The usual cause of a large artifact is uncompressed images or a vendored
+toolchain that the built site does not need at runtime. A docs bundle should
+carry rendered HTML, CSS, fonts and images, and nothing else.
+
+---
+
+## What the HTML must look like
+
+Identical for both producers, and specified in
+[`HEADLESS_RULES.md`](./HEADLESS_RULES.md):
+
+- `data-kb-headless="true"` on `<html>`
+- no `<base>` element; every asset path relative
+- no site-level fixed header, no theme toggle, light only
+- the design tokens in [`STYLE_GUIDE.md`](./STYLE_GUIDE.md)
+
+Inline `<script>` is permitted but discouraged: the deployment serves
+`script-src 'self'`, so the knowledge base hoists inline bodies into files at
+build time. A doc that needs inline scripting to render will not render.
+
+---
+
+## Registering
+
+Once your release carries `kb-docs.tar.gz`, open a PR against
+`AbsaOSS/knowledge-base` adding one entry to `apps.json`:
+
+```json
+{ "repo": "AbsaOSS/my-service", "version": "latest" }
+```
+
+That is the whole entry. No slug, no name, no description, no icon, no tags:
+all of it is read from your manifest, so adding, renaming or removing a doc
+later never touches the knowledge base repository again. `version` accepts
+`latest` (the default) or a pinned tag such as `v1.4.0`.
diff --git a/contract/HEADLESS_RULES.md b/contract/HEADLESS_RULES.md
index 0a2ac04..0de56d0 100644
--- a/contract/HEADLESS_RULES.md
+++ b/contract/HEADLESS_RULES.md
@@ -2,17 +2,18 @@
 
 Doc apps included in the knowledge base must produce **headless HTML output** — pages that
 contain content (sidebar + prose) but **do not** include a site-level top navigation bar.
-The knowledge base injects its own persistent 56 px chrome at the top of every page.
+The knowledge base re-hosts every page under its own persistent masthead, which carries the
+branding and the Library / current-app navigation.
 
 > **Simpler alternative — single-page docs.** If what you have is a markdown file or
 > two rather than a documentation *site*, none of this applies to you. Add the
 > `publish-single-page-docs` action to your repo and it produces a compliant artifact
-> for you — no headless build, no `marketplace.json`, no config. See
+> for you — no headless build, no manifest to write, no config. See
 > [`SINGLE_PAGE.md`](./SINGLE_PAGE.md).
 
 > **Temporary alternative — iframe onboarding.** Teams that already host their docs
 > elsewhere and cannot yet produce a headless package can be listed immediately with an
-> `apps.json` entry of `"type": "iframe"` + a `"url"` (no `marketplace.json`, no release
+> `apps.json` entry of `"type": "iframe"` + a `"url"` (no manifest, no release
 > artifact, no headless build). The page is rendered as a full-viewport `<iframe>` inside
 > the knowledge base chrome. This is an **explicit stopgap** — such entries should carry
 > `"temporary": true` and be migrated to a proper headless package when possible. The
@@ -41,51 +42,52 @@ When `--headless` is active:
 | **Sidebar offset** | Set sidebar's `top` to `0`. The knowledge base no longer injects a fixed bar, so nothing is reserved above your content. |
 | **`data-kb-headless` attribute** | Add `data-kb-headless="true"` to the `<html>` element so the knowledge base can identify and verify headless pages. |
 | **Theme toggle** | Omit the theme toggle button from the site header. The knowledge base is light only and strips any theme bootstrap your page ships. |
-| **Relative asset paths** | All `href`, `src`, `action` attribute values must be **relative** (no leading `/`). The knowledge base mounts apps at `/apps/{slug}/`, so absolute paths will 404. |
+| **Relative asset paths** | All `href`, `src`, `action` attribute values must be **relative** (no leading `/`). The knowledge base mounts apps at `/knowledge-base/{slug}/`, so absolute paths will 404. |
 
 ---
 
-## Required: `marketplace.json` manifest
+## Required: `kb-docs.json` manifest
 
-Place a `marketplace.json` file in the **root of your repository** (not in `dist/`).  
-It must validate against the [JSON Schema](./schema.json).
+Place a `kb-docs.json` file in the **root of your repository**. It must validate
+against the [JSON Schema](./kb-docs.schema.json); the publishing action does that
+for you before it packs anything.
 
 ```json
 {
-  "marketplaceVersion": "1",
-  "name": "My App Documentation",
-  "slug": "my-app",
-  "description": "A clear, one-paragraph description of what this documentation covers.",
-  "icon": "book-open",
-  "tags": ["example", "guide"],
-  "entryPoint": "index.html",
-  "pages": [
-    { "title": "Overview",        "path": "index.html",                 "order": 1 },
-    { "title": "Getting Started", "path": "getting-started/index.html", "order": 2 },
-    { "title": "Configuration",   "path": "configuration/index.html",   "order": 3, "section": "Reference" }
+  "kbVersion": "1",
+  "apps": [
+    {
+      "slug": "my-app",
+      "name": "My App Documentation",
+      "description": "A clear, one-sentence description of what this documentation covers.",
+      "icon": "book-open",
+      "tags": ["example", "guide"],
+      "entryPoint": "index.html",
+      "pages": [
+        { "title": "Overview",        "path": "index.html",                 "order": 1 },
+        { "title": "Getting Started", "path": "getting-started/index.html", "order": 2 },
+        { "title": "Configuration",   "path": "configuration/index.html",   "order": 3, "section": "Reference" }
+      ]
+    }
   ]
 }
 ```
 
-### Recommended: `pages` navigation manifest
+A documentation site is one entry in `apps`. The list exists because a single
+repo may publish several independent docs from one release — see
+[`SINGLE_PAGE.md`](./SINGLE_PAGE.md) — and the knowledge base reads both through
+the same manifest.
 
-The optional `pages` array tells the knowledge base the **exact set of routes** your app exposes, along with human-readable titles and ordering. When present it replaces the default filesystem crawl used to discover HTML files.
+Every field is specified in [`ARTIFACT.md`](./ARTIFACT.md), which is normative.
+The two worth reading before you start:
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `title` | ✅ | Page title shown in sidebar navigation |
-| `path` | ✅ | Path to the HTML file relative to `dist/` |
-| `order` | ✅ | Integer sort position (lower = higher up) |
-| `section` | ☐ | Optional sidebar section/group heading |
-
-> **Note:** `pages` should be written into `dist/marketplace.json` (not the root `marketplace.json`) by your build script at build time. See the example app for a reference implementation that generates this from MkDocs navigation config.
->
-> If `pages` is absent the knowledge base falls back to crawling all `.html` files in `dist/` — existing apps require no changes.
-
-### Slug rules
-- Lowercase letters, numbers, and hyphens only: `^[a-z0-9-]+$`
-- Must be unique across all apps in `apps.json`
-- Becomes the URL prefix: `/apps/{slug}/`
+- **`slug`** becomes your public URL (`/knowledge-base/{slug}/`) and the name of
+  your app's directory inside the archive. It must be unique across the *whole*
+  knowledge base, so prefix it with your service name.
+- **`pages`** is optional but recommended. When present it is the authoritative
+  route list, with your titles and your ordering. Absent, the knowledge base
+  crawls your output for HTML and derives titles from the documents. Generate it
+  from whatever your site generator already knows about its navigation.
 
 ---
 
@@ -95,7 +97,7 @@ The `<body>` of each doc page must follow this structure:
 
 ```html
 <body>
-  <!-- ✅ Sidebar — knowledge base repositions top offset -->
+  <!-- ✅ Sidebar — yours, kept as-is -->
   <nav id="sidebar" class="fixed top-0 ...">
     ...
   </nav>
@@ -142,36 +144,56 @@ There is deliberately no `.dark` set — the knowledge base is light-only.
 
 ## Required: GitHub Release artifact
 
-Your repo must publish a **GitHub Release** containing `dist.tar.gz` whenever docs are updated.  
-The archive must unpack to a `dist/` directory containing the headless HTML output.
+Your repo must attach **`kb-docs.tar.gz`** to a GitHub Release whenever the docs
+change. Its layout — the manifest at the root, one directory per app — is
+specified in [`ARTIFACT.md`](./ARTIFACT.md).
 
-Use the reusable release workflow — see [`.github/workflows/validate-doc-app.yml`](../.github/workflows/validate-doc-app.yml).
+You do not assemble it by hand. Build your site, then hand the output to the
+publishing action, which validates the manifest, checks the HTML against the
+rules on this page, packs the archive and uploads it:
 
 ```yaml
-# .github/workflows/release.yml in your doc repo
-name: Release
+# .github/workflows/publish-docs.yml in your doc repo
+name: Publish docs
 
 on:
-  push:
-    tags: ['v*']
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write        # required — the action uploads a release asset
 
 jobs:
-  release:
-    uses: AbsaOSS/knowledge-base/.github/workflows/validate-doc-app.yml@main
-    secrets: inherit
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Whatever your site generator is. The action does not build for you.
+      - run: npm ci && npm run build -- --headless
+
+      - uses: AbsaOSS/knowledge-base/actions/publish-docs@v1
+        with:
+          manifest: kb-docs.json
+          dist: dist
 ```
 
+Pin the action to a major tag (`@v1`), not to a branch. A breaking contract
+change ships as `@v2`, so a pinned major keeps publishing until you choose to
+move.
+
 ---
 
 ## Checklist
 
 Before opening a PR to add your app to `apps.json`:
 
-- [ ] `marketplace.json` is in the repo root and validates against `contract/schema.json`
-- [ ] `npm run build -- --headless` succeeds and produces `dist/`
-- [ ] `dist/` contains `index.html` (or your configured `entryPoint`)
+- [ ] `kb-docs.json` is in the repo root and validates against [`contract/kb-docs.schema.json`](./kb-docs.schema.json)
+- [ ] Your headless build succeeds and produces the output directory named in the workflow
+- [ ] That directory contains `index.html` (or your configured `entryPoint`)
 - [ ] No `<header class="fixed top-0...">` present in any headless HTML page
 - [ ] `data-kb-headless="true"` is on the `<html>` element
 - [ ] All asset paths are relative (no leading `/`)
 - [ ] Design tokens are defined in your CSS
-- [ ] A GitHub Release with `dist.tar.gz` exists on your repo
+- [ ] A GitHub Release with `kb-docs.tar.gz` exists on your repo
diff --git a/contract/SINGLE_PAGE.md b/contract/SINGLE_PAGE.md
index 4f5ad22..3c933a8 100644
--- a/contract/SINGLE_PAGE.md
+++ b/contract/SINGLE_PAGE.md
@@ -2,10 +2,11 @@
 
 The zero-config way into the knowledge base. Your repo has one or more markdown
 files; you add **one workflow file and nothing else**. No mkdocs, no theme, no
-`marketplace.json`, no build script, no headless flag.
+manifest to write, no build script, no headless flag — the action derives the
+manifest from the workflow inputs below.
 
 The reusable action renders your markdown into headless HTML, packs it as
-`dist.tar.gz`, and attaches it to your latest GitHub Release. The knowledge base
+`kb-docs.tar.gz`, and attaches it to your latest GitHub Release. The knowledge base
 picks it up on its next build and gives every doc its own catalog card and URL.
 
 > Choosing between the three onboarding types:
@@ -13,7 +14,7 @@ picks it up on its next build and gives every doc its own catalog card and URL.
 > | Type | Use when | Cost to your repo |
 > |---|---|---|
 > | **single-page** | You have markdown files, not a docs *site* | one workflow file |
-> | *default* (packaged) | You have a real static docs site (mkdocs, Starlight…) | headless build + `marketplace.json` + release workflow — see [HEADLESS_RULES.md](./HEADLESS_RULES.md) |
+> | *default* (packaged) | You have a real static docs site (mkdocs, Starlight…) | headless build + `kb-docs.json` + release workflow — see [HEADLESS_RULES.md](./HEADLESS_RULES.md) |
 > | *iframe* | Your docs are already hosted elsewhere and can't be packaged yet | an `apps.json` entry — explicit stopgap, see [HEADLESS_RULES.md](./HEADLESS_RULES.md) |
 
 ---
@@ -67,7 +68,7 @@ That is the entire onboarding on your side. Multiple docs go in the same list:
 | Input | Required | Default | Description |
 |---|---|---|---|
 | `docs` | ✅ | — | YAML (or JSON) **list** of doc definitions — see below |
-| `release-tag` | ☐ | the triggering release, else the repo's latest | Release to attach `dist.tar.gz` to |
+| `release-tag` | ☐ | the triggering release, else the repo's latest | Release to attach `kb-docs.tar.gz` to |
 | `github-token` | ☐ | `${{ github.token }}` | Needs `contents: write` |
 
 ### Each doc definition
@@ -90,7 +91,7 @@ naming the entry and the fix.
 |---|---|
 | `slugs` | Comma-separated list of published slugs |
 | `count` | Number of docs in the bundle |
-| `artifact` | Absolute path of the packed `dist.tar.gz` |
+| `artifact` | Absolute path of the packed `kb-docs.tar.gz` |
 | `release-tag` | Tag the bundle was uploaded to |
 
 ### Prerequisite: a release must exist
@@ -108,15 +109,15 @@ Open a PR against `AbsaOSS/knowledge-base` adding **one** entry to `apps.json`:
 ```json
 {
   "repo": "AbsaOSS/my-service",
-  "type": "single-page",
   "version": "latest"
 }
 ```
 
-Note what is *not* there: no slug, no name, no description, no icon, no tags. All
-of it is discovered from the bundle, so adding, renaming or removing a doc later
-never touches the knowledge base repo again — publish a new release and the next
-knowledge-base build picks it up.
+Note what is *not* there: no slug, no name, no description, no icon, no tags, and
+no type. All of it is read from your manifest, so adding, renaming or removing a
+doc later never touches the knowledge base repo again — publish a new release and
+the next knowledge-base build picks it up. It is also the same entry a packaged
+docs site gets: the registry records where an artifact comes from, nothing more.
 
 `version` accepts `latest` (default) or a pinned tag such as `v1.4.0`.
 
@@ -176,10 +177,10 @@ single-page doc; package it as a full static site instead
 
 ### Artifact layout
 
-`dist.tar.gz` unpacks to a `bundle.json` manifest plus one directory per doc:
+`kb-docs.tar.gz` unpacks to a `kb-docs.json` manifest plus one directory per doc:
 
 ```
-bundle.json
+kb-docs.json
 my-service/
   index.html
   assets/doc.css
@@ -191,16 +192,15 @@ my-service-releases/
   assets/doc.css
 ```
 
-### `bundle.json`
+### `kb-docs.json`
 
 ```json
 {
-  "marketplaceVersion": "1",
-  "type": "single-page",
-  "docs": [
+  "kbVersion": "1",
+  "apps": [
     {
       "slug": "my-service",
-      "title": "Service Overview",
+      "name": "Service Overview",
       "description": "What the service does and how to use it.",
       "icon": "cube",
       "tags": ["platform", "api"],
@@ -210,15 +210,14 @@ my-service-releases/
 }
 ```
 
-| Field | Required | Description |
-|---|---|---|
-| `marketplaceVersion` | ✅ | Contract version. Must be `"1"`. |
-| `type` | ✅ | Must be `"single-page"`. |
-| `docs` | ✅ | Non-empty list. Each doc needs `slug`, `title` and `description`; `icon`, `tags` and `entryPoint` (default `index.html`) are optional. |
+Your `title` becomes the app's `name`; everything else carries over as you wrote
+it. One entry per doc.
 
-`bundle.json` is the single-page counterpart of `marketplace.json` — one manifest
-describing a *set* of apps rather than one app. Packaged doc sites keep using
-`marketplace.json` and [`schema.json`](./schema.json) unchanged.
+This is the same manifest a packaged documentation site publishes, specified in
+[`ARTIFACT.md`](./ARTIFACT.md) and validated against
+[`kb-docs.schema.json`](./kb-docs.schema.json). There is no separate single-page
+format: a set of markdown docs is a manifest listing several apps, a docs site is
+a manifest listing one, and the knowledge base reads both the same way.
 
 ### Generated HTML
 
@@ -261,7 +260,7 @@ only navigation; there is no sidebar and no in-app chrome.
 | `md "…" does not exist in the repository` | Wrong path, or `actions/checkout` is missing from the job. |
 | `slug "…" is invalid` | Slugs are lowercase kebab-case only — no underscores, capitals or spaces. |
 | `Duplicate app slug "…"` (knowledge-base build) | Another registered app already owns that URL prefix. Rename yours and republish. |
-| `the release artifact has no bundle.json at its root` | The release's `dist.tar.gz` was not produced by this action. |
+| `the release artifact has no kb-docs.json at its root` | The release's `kb-docs.tar.gz` was not produced by this action. |
 
 ---
 
@@ -270,5 +269,5 @@ only navigation; there is no sidebar and no in-app chrome.
 - [ ] `.github/workflows/publish-docs.yml` added, with `permissions: contents: write`
 - [ ] Every `slug` is lowercase kebab-case and prefixed with your service name
 - [ ] Each `description` is 10–280 characters
-- [ ] The workflow ran and `dist.tar.gz` is attached to the release
-- [ ] A PR adds the `{ "repo": …, "type": "single-page" }` entry to `apps.json`
+- [ ] The workflow ran and `kb-docs.tar.gz` is attached to the release
+- [ ] A PR adds the `{ "repo": … }` entry to `apps.json`
diff --git a/contract/kb-docs.schema.json b/contract/kb-docs.schema.json
new file mode 100644
index 0000000..996efcd
--- /dev/null
+++ b/contract/kb-docs.schema.json
@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/AbsaOSS/knowledge-base/master/contract/kb-docs.schema.json",
+  "title": "kb-docs.json",
+  "description": "Manifest at the root of a kb-docs.tar.gz release artifact. Describes every app the archive publishes. See contract/ARTIFACT.md.",
+  "type": "object",
+  "required": ["kbVersion", "apps"],
+  "additionalProperties": false,
+  "properties": {
+    "kbVersion": {
+      "type": "string",
+      "enum": ["1"],
+      "description": "Contract version. Must be '1'."
+    },
+    "apps": {
+      "type": "array",
+      "minItems": 1,
+      "description": "One entry per app in the archive. A packaged documentation site is a list of one.",
+      "items": { "$ref": "#/definitions/app" }
+    }
+  },
+  "definitions": {
+    "app": {
+      "type": "object",
+      "required": ["slug", "name", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+          "minLength": 2,
+          "maxLength": 32,
+          "description": "Names the app's directory in the archive and its public URL prefix /knowledge-base/{slug}/. Must be unique across the whole knowledge base — prefix it with your service name."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 64,
+          "description": "Human-readable app name, shown on the catalog card and in the masthead."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 280,
+          "description": "One sentence, shown on the catalog card."
+        },
+        "entryPoint": {
+          "type": "string",
+          "default": "index.html",
+          "description": "Landing page, relative to the app's directory in the archive.",
+          "$comment": "Relative, forward-slashed, no traversal — enforced by the pattern below rather than by prose.",
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
+        },
+        "icon": {
+          "type": "string",
+          "default": "book-open",
+          "description": "Icon name from the supported set. An unrecognised value falls back to book-open rather than failing the build.",
+          "enum": [
+            "book-open", "cube", "chip", "chart-bar", "shield",
+            "cog", "terminal", "globe", "layers", "lightning-bolt",
+            "document", "collection", "puzzle", "database"
+          ]
+        },
+        "tags": {
+          "type": "array",
+          "maxItems": 5,
+          "description": "Taxonomy tags shown as pills on the catalog card.",
+          "items": { "type": "string", "minLength": 1, "maxLength": 32 }
+        },
+        "pages": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Navigation manifest. When present it is the authoritative route list for the app and the knowledge base does not crawl the directory.",
+          "items": { "$ref": "#/definitions/page" }
+        }
+      }
+    },
+    "page": {
+      "type": "object",
+      "required": ["title", "path", "order"],
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "Human-readable page title used in navigation."
+        },
+        "path": {
+          "type": "string",
+          "description": "Path to the HTML file, relative to the app's directory in the archive.",
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
+        },
+        "order": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sort position within the app's navigation (lower sorts higher)."
+        },
+        "section": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Optional group heading to display above this page."
+        }
+      }
+    }
+  }
+}
diff --git a/contract/schema.json b/contract/schema.json
deleted file mode 100644
index 1b7bb1f..0000000
--- a/contract/schema.json
+++ /dev/null
@@ -1,87 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "contract/schema.json",
-  "title": "marketplace.json",
-  "description": "Metadata manifest required in every doc app repo to be included in the docs knowledge base.",
-  "type": "object",
-  "required": ["marketplaceVersion", "name", "slug", "description", "entryPoint"],
-  "additionalProperties": false,
-  "properties": {
-    "marketplaceVersion": {
-      "type": "string",
-      "enum": ["1"],
-      "description": "Contract version. Must be '1'."
-    },
-    "name": {
-      "type": "string",
-      "minLength": 2,
-      "maxLength": 64,
-      "description": "Human-readable app name shown in the knowledge base."
-    },
-    "slug": {
-      "type": "string",
-      "pattern": "^[a-z0-9-]+$",
-      "minLength": 2,
-      "maxLength": 32,
-      "description": "URL-safe identifier used as the path prefix: /apps/{slug}/. Must be lowercase alphanumeric with hyphens."
-    },
-    "description": {
-      "type": "string",
-      "minLength": 10,
-      "maxLength": 280,
-      "description": "Short description shown on the knowledge base catalog card."
-    },
-    "icon": {
-      "type": "string",
-      "description": "Icon name from the supported set. See HEADLESS_RULES.md for the full list.",
-      "default": "book-open",
-      "enum": [
-        "book-open", "cube", "chip", "chart-bar", "shield",
-        "cog", "terminal", "globe", "layers", "lightning-bolt",
-        "document", "collection", "puzzle", "database"
-      ]
-    },
-    "tags": {
-      "type": "array",
-      "items": { "type": "string", "maxLength": 32 },
-      "maxItems": 5,
-      "description": "Taxonomy tags shown as pills on the catalog card."
-    },
-    "entryPoint": {
-      "type": "string",
-      "description": "Relative path to the landing page within the built output directory.",
-      "default": "index.html"
-    },
-    "pages": {
-      "type": "array",
-      "description": "Optional navigation manifest. When present, the knowledge base uses this list as the authoritative source of static routes instead of crawling the dist/ filesystem.",
-      "items": {
-        "type": "object",
-        "required": ["title", "path", "order"],
-        "additionalProperties": false,
-        "properties": {
-          "title": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 128,
-            "description": "Human-readable page title used in sidebar navigation."
-          },
-          "path": {
-            "type": "string",
-            "description": "Relative path to the HTML file within the built dist/ directory."
-          },
-          "order": {
-            "type": "integer",
-            "minimum": 0,
-            "description": "Integer sort order within the app's navigation (lower = higher up)."
-          },
-          "section": {
-            "type": "string",
-            "maxLength": 64,
-            "description": "Optional section/group heading to display above this page in the sidebar."
-          }
-        }
-      }
-    }
-  }
-}
diff --git a/src/utils/single-page.js b/src/utils/single-page.js
index 7c0d945..80fa10c 100644
--- a/src/utils/single-page.js
+++ b/src/utils/single-page.js
@@ -25,7 +25,7 @@ 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/schema.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',
diff --git a/tests/contract.spec.js b/tests/contract.spec.js
new file mode 100644
index 0000000..bcfa337
--- /dev/null
+++ b/tests/contract.spec.js
@@ -0,0 +1,123 @@
+// contract.spec.js — the artifact contract, checked against its own schema.
+//
+// contract/kb-docs.schema.json is the one document both publishing actions and
+// this repo's build validate against, and it reaches consuming repos through a
+// raw GitHub URL. A schema that does not compile, or that quietly accepts a
+// manifest the build will later reject, is worse than no schema at all: the
+// onboarding repo goes green and the deployment fails.
+//
+// These are pure assertions on the schema — no browser, no build. They live in
+// the Playwright suite so `npm test` stays the single command.
+
+import { test, expect } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv from 'ajv';
+
+const SCHEMA_PATH = join(process.cwd(), 'contract', 'kb-docs.schema.json');
+const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+
+/** A fresh validator per call: Ajv caches by $id, and reuse hides compile errors. */
+function validator() {
+  return new Ajv({ allErrors: true, strict: false }).compile(schema);
+}
+
+/** The smallest manifest the contract calls valid. */
+const minimal = () => ({
+  kbVersion: '1',
+  apps: [{ slug: 'my-service', name: 'My Service', description: 'What the service does.' }],
+});
+
+/** One app, every optional field populated. */
+const full = () => ({
+  kbVersion: '1',
+  apps: [{
+    slug: 'my-service',
+    name: 'My Service',
+    description: 'What the service does and how to use it.',
+    icon: 'cube',
+    tags: ['platform', 'api'],
+    entryPoint: 'index.html',
+    pages: [
+      { title: 'Overview', path: 'index.html', order: 0 },
+      { title: 'Releases', path: 'docs/releasing/index.html', order: 1, section: 'Reference' },
+    ],
+  }],
+});
+
+/** Applies `mutate` to the first app of a full manifest. */
+function withApp(mutate) {
+  const m = full();
+  mutate(m.apps[0]);
+  return m;
+}
+
+test.describe('kb-docs.schema.json', () => {
+  test('compiles', () => {
+    expect(() => validator()).not.toThrow();
+  });
+
+  test('is published at the URL consuming repos fetch it from', () => {
+    // The $id is how an onboarding repo's CI finds the schema; a stale one sends
+    // it to a 404 and the validation step silently degrades to a warning.
+    expect(schema.$id).toBe(
+      'https://raw.githubusercontent.com/AbsaOSS/knowledge-base/master/contract/kb-docs.schema.json',
+    );
+  });
+
+  test('accepts the minimal and the fully populated manifest', () => {
+    const validate = validator();
+    expect(validate(minimal()), JSON.stringify(validate.errors)).toBe(true);
+    expect(validate(full()), JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  test('accepts several apps in one bundle', () => {
+    const m = minimal();
+    m.apps.push({ slug: 'my-service-ops', name: 'Operations', description: 'Running it in production.' });
+    expect(validator()(m)).toBe(true);
+  });
+});
+
+test.describe('kb-docs.schema.json rejects', () => {
+  const cases = [
+    ['a numeric kbVersion', { ...minimal(), kbVersion: 1 }],
+    ['an unknown kbVersion', { ...minimal(), kbVersion: '2' }],
+    ['a missing kbVersion', { apps: minimal().apps }],
+    ['an empty apps list', { kbVersion: '1', apps: [] }],
+    ['a missing apps list', { kbVersion: '1' }],
+    ['an unknown top-level field', { ...minimal(), type: 'single-page' }],
+
+    ['an upper-case slug', withApp(a => { a.slug = 'My-Service'; })],
+    ['an underscored slug', withApp(a => { a.slug = 'my_service'; })],
+    ['a slug with a leading hyphen', withApp(a => { a.slug = '-my-service'; })],
+    ['a one-character slug', withApp(a => { a.slug = 'x'; })],
+    ['a missing slug', withApp(a => { delete a.slug; })],
+
+    ['a missing name', withApp(a => { delete a.name; })],
+    ['a missing description', withApp(a => { delete a.description; })],
+    ['a description under 10 characters', withApp(a => { a.description = 'too short'; })],
+    ['a description over 280 characters', withApp(a => { a.description = 'x'.repeat(281); })],
+
+    ['an unknown icon', withApp(a => { a.icon = 'rocket'; })],
+    ['more than five tags', withApp(a => { a.tags = ['a', 'b', 'c', 'd', 'e', 'f']; })],
+    ['an unknown app field', withApp(a => { a.headless = true; })],
+
+    // The archive is unpacked into a directory this deployment serves, so a
+    // manifest must not be able to point at a file outside the app's own tree.
+    ['an entryPoint that escapes the app directory', withApp(a => { a.entryPoint = '../other/index.html'; })],
+    ['an absolute entryPoint', withApp(a => { a.entryPoint = '/index.html'; })],
+    ['a page path that escapes the app directory', withApp(a => { a.pages[0].path = '../../etc/passwd'; })],
+    ['an absolute page path', withApp(a => { a.pages[0].path = '/index.html'; })],
+
+    ['a page with no order', withApp(a => { delete a.pages[0].order; })],
+    ['a negative page order', withApp(a => { a.pages[0].order = -1; })],
+    ['a non-integer page order', withApp(a => { a.pages[0].order = 1.5; })],
+    ['an unknown page field', withApp(a => { a.pages[0].icon = 'cube'; })],
+  ];
+
+  for (const [label, manifest] of cases) {
+    test(label, () => {
+      expect(validator()(manifest)).toBe(false);
+    });
+  }
+});