From c855a1c836734fb86b7a2fa953b8747442837943 Mon Sep 17 00:00:00 2001
From: Oto Macenauer <oto.macenauer@absa.africa>
Date: Fri, 4 Sep 2026 12:45:21 +0200
Subject: [PATCH] =?UTF-8?q?docs(contract):=20define=20the=20v1=20artifact?=
 =?UTF-8?q?=20=E2=80=94=20kb-docs.tar.gz=20and=20kb-docs.json?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The artifact contract had grown two shapes and a misleading name. Packaged
sites shipped dist.tar.gz containing dist/ plus a root marketplace.json
describing one app; single-page bundles shipped dist.tar.gz containing
bundle.json plus one directory per doc, describing many. dist.tar.gz is also
indistinguishable from a repo's own distribution package, which a release
usually carries alongside.

This defines one shape for both. kb-docs.tar.gz holds kb-docs.json at its root
plus one directory per app. A documentation site is a manifest listing one app;
a set of markdown docs is a manifest listing several. Nothing downstream has to
tell them apart.

New:

  contract/ARTIFACT.md          normative: layout, manifest, archive rules,
                                versioning, size budget, registration
  contract/kb-docs.schema.json  draft-07 schema, $id at its raw GitHub URL so
                                the actions and this build validate the same
                                document
  tests/contract.spec.js        30 assertions pinning what the schema accepts
                                and rejects

Removed contract/schema.json, which described the old single-app manifest.

Two things the schema is deliberate about. kbVersion is a string, so the
contract can reach "1.1" or "2" without changing type, and unknown fields are
ignored rather than rejected so an additive change never breaks an older
knowledge base. Conversely entryPoint and pages[].path are pattern-constrained
against traversal and absolute paths: the archive is unpacked into a directory
this deployment then serves, so a manifest must not be able to point outside
the app's own tree.

The size budget is new and was previously unstated: 20 MB target, warned above
that, refused above 100 MB, which is also GitHub's per-asset limit. Every
registered artifact is downloaded on every deployment build, so it is a shared
cost rather than a private one.

validate-doc-app.yml is now a loud deprecation. It validated marketplace.json
against a schema this commit deletes, and it assumed `npm run build --headless`,
which the Python example repo cannot run. Rather than half-migrating a workflow
that #76 removes, it fails with the replacement in the message and the step
summary — a green check against a contract that no longer exists is worse than
no check.

Contract-only. No build code changes, so the build still reads the old layout
until #75 lands. The docs describing that layout move with it.

Part of #73. Closes #74.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PYtmxSeSXFg4wEXRcKCmAi
---
 .github/workflows/validate-doc-app.yml        | 220 ++++--------------
 CLAUDE.md                                     |  13 +-
 README.md                                     |  68 +++---
 .../publish-single-page-docs/src/inputs.js    |   4 +-
 contract/ARTIFACT.md                          | 181 ++++++++++++++
 contract/HEADLESS_RULES.md                    | 122 ++++++----
 contract/SINGLE_PAGE.md                       |  55 +++--
 contract/kb-docs.schema.json                  | 108 +++++++++
 contract/schema.json                          |  87 -------
 src/utils/single-page.js                      |   2 +-
 tests/contract.spec.js                        | 123 ++++++++++
 11 files changed, 604 insertions(+), 379 deletions(-)
 create mode 100644 contract/ARTIFACT.md
 create mode 100644 contract/kb-docs.schema.json
 delete mode 100644 contract/schema.json
 create mode 100644 tests/contract.spec.js

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);
+    });
+  }
+});