diff --git a/AGENTS.md b/AGENTS.md
index 7dc2264..110739b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -103,6 +103,11 @@ is a second implementation of the same contract and it has drifted twice
 with this suite.** CI runs it inside the `image` job, which already builds the
 image.
 
+Locally it sets `reuseExistingServer`, so a container left running from an
+earlier run answers on `:8099` and the suite passes against the **old** `dist/`.
+Before trusting a green run: `docker ps --filter "publish=8099"`, remove
+anything there, rebuild, then run it.
+
 `npm audit --omit=dev --audit-level=high` must also stay clean; it gates CI.
 
 ## Repository conventions
@@ -123,8 +128,11 @@ strong reason.
 ### Light only
 
 The marketplace has no dark mode: no theme toggle, no persisted theme, no `dark`
-class, no dark palette. `src/utils/transform.js` actively strips a sub-app's
-theme bootstrap and `dark` body class. Do not reintroduce any of it.
+class, no dark palette. A sub-app's own theme bootstrap is removed twice:
+`scripts/hoist-inline-scripts.js` deletes it while it is still inline, and
+`src/utils/transform.js` strips any that survives, along with a `dark` body
+class. Do not reintroduce any of it, and keep both halves — hoisting a bootstrap
+instead of deleting it puts it beyond the reach of the transform.
 
 ### Sub-app HTML is untrusted input
 
@@ -141,6 +149,9 @@ inline script found in a sub-app artifact into one. A change that introduces an
 inline script fails `tests/build-integrity.spec.js` before it can start breaking
 pages silently in production.
 
+The check covers `<script>` elements. Inline `on*` handlers are a known gap
+(#67): they are equally blocked by the policy but nothing strips or reports them.
+
 Inline `<style>` is still allowed (`style-src` keeps `'unsafe-inline'`); tightening
 that is a separate piece of work.
 
@@ -148,8 +159,14 @@ that is a separate piece of work.
 
 The build runs on Linux CI and on Windows developer machines. Prefer Node APIs
 (`cpSync`, `rmSync`) over shelling out to `cp`/`rm`. Where `tar` is unavoidable,
-follow the drive-letter workaround documented in
-`scripts/build-vite.js` (`stageArtifact`).
+follow the drive-letter workaround documented in `scripts/artifacts.js`
+(`stageArtifact`).
+
+The repository has no `.gitattributes`, so a Windows checkout is CRLF. Two
+consequences: `git status` reports `apps.json` and the generated fixtures as
+modified when only line endings changed — check `git diff --stat`, which will
+show nothing, before staging — and a `$`-anchored regex over file text will not
+match, because `.` does not match `\r`.
 
 ### Contract changes
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 1b9aa8c..a0abb52 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -23,11 +23,12 @@ npm run dev                          # Astro dev (needs artifacts in apps/ alrea
 npm run dev:fetch                    # fetch artifacts then start dev
 
 # Preview
-npm run preview                      # preview built output
-npm run preview:embedded             # headless preview (no compression, for web-fragments)
+npm run preview                      # serve the built dist/ (astro preview, :4321)
 
-# Test (Playwright E2E — self-contained; auto-starts both servers)
-npm test                             # headless
+# Test (Playwright E2E — self-contained; auto-starts its own servers)
+npm test                             # embedded web-fragment harness
+npx playwright test --config=playwright.config.ci.js   # standalone fragment server
+npm run test:container               # real nginx image (needs Docker)
 npm run test:ui                      # Playwright UI
 npm run test:headed                  # visible browser
 npm run test:debug                   # debug mode
@@ -51,12 +52,13 @@ apps.json (registry)
   → dist/
 ```
 
-Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`, `--path-prefix=`.
+Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`.
 
-## Two Build Configs
+## Build Config
 
-- **astro.config.mjs** — Astro SSG config, base `/knowledge-base`, used by `astro build`/`astro dev`
-- **vite.config.js** — standalone Vite config with custom `marketplacePlugin` from `plugins/marketplace.js`, base `/`, used for the non-Astro build path
+**astro.config.mjs** is the only build config — base `/knowledge-base`, used by `astro build`/`astro dev`. There is no non-Astro build path.
+
+`src/utils/config.js` holds what both the config and the pages need: `PATH_PREFIX`/`BASE_PATH` and `isHeadlessBuild()`. Import them; do not re-spell either one inline.
 
 ## Architecture
 
@@ -70,15 +72,16 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`, `--path-p
 - `src/pages/index.astro` — Landing catalog page
 - `src/utils/apps.js` — `getAppPages()` enumerates sub-app HTML (manifest-driven or filesystem crawl)
 - `src/utils/transform.js` — `transformSubAppHtml()`: URL rewriting, document splitting (head/body/title/body-class), headless transforms
-- `src/layouts/Base.astro` — The one document shell: head, fonts, marketplace CSS, theme script, `<ClientRouter />`
-- `src/components/Chrome.astro` — 56px fixed top bar (standalone mode only)
+- `src/layouts/Base.astro` — The one document shell: head, fonts, marketplace CSS, `<ClientRouter />`, shadow-DOM compat styles
 - `src/components/Masthead.astro` — Persistent Knowledge base header + Library/current-app sub-nav (all pages, both modes)
-- `src/templates/chrome.js` — Inline theme script + shadow-DOM compat styles injected by the layout
+- `src/components/AppCard.astro`, `src/components/AppIcon.astro` — Catalog card and its icon
+- `src/templates/shadow-compat.js` — Shadow-DOM design-token styles, injected into the body by the layout
+- `src/utils/config.js` — `PATH_PREFIX`/`BASE_PATH` and `isHeadlessBuild()` — the build-wide constants
 - `src/utils/single-page.js` — Bundle manifest reading/validation + registry expansion, shared by both fetch paths and by Astro
-- `scripts/build-vite.js` — Build orchestrator (3-step pipeline)
+- `scripts/build-vite.js` — Build orchestrator (4 steps: prepare, hoist, copy assets, astro build)
 - `scripts/fetch-apps.js` — GitHub Release artifact downloader
 - `scripts/artifacts.js` — Safe tarball extraction + tree copy, shared by both fetch paths. Validates archive members (no traversal, no absolute paths, no symlinks) before anything is written, and replaces the old `cp -r`/`tar` shell-outs so the build runs on Windows
-- `scripts/hoist-inline-scripts.js` — Moves inline `<script>` bodies in sub-app HTML into files before the Astro build, so the deployment can serve `script-src 'self'`. Needed because bundles published before the action stopped emitting an inline mermaid bootstrap still contain one
+- `scripts/hoist-inline-scripts.js` — Moves inline `<script>` bodies in sub-app HTML into files before the Astro build, so the deployment can serve `script-src 'self'`. Needed because bundles published before the action stopped emitting an inline mermaid bootstrap still contain one. A sub-app's dark-mode bootstrap is deleted here rather than hoisted — light only, and hoisting would put it beyond the reach of `transform.js`
 - `actions/publish-single-page-docs/` — Reusable GitHub Action that turns a repo's markdown into a single-page bundle
 
 ### Three Onboarding Types
@@ -95,15 +98,21 @@ Both modes render the same document: the masthead (`Masthead.astro`) — brandin
 
 **Non-headless** (standalone): Plain marketplace pages. Navigation is Astro's `<ClientRouter />` (view transitions).
 
-**Headless** (web-fragment): Marks `data-mp-headless="true"` and injects shadow DOM compat styles. Designed for embedding in a web-fragments gateway.
+**Headless** (web-fragment): Marks `data-mp-headless="true"` on `<html>`, for embedding in a web-fragments gateway. That attribute is the only difference in the output — the shadow-DOM compat styles are emitted in both modes.
+
+Resolution order: a per-app `"headless"` in `apps.json` wins; otherwise `isHeadlessBuild()`.
 
 ### Light Only
 
-The marketplace has no dark mode: no theme toggle, no persisted theme, no `dark` class, no dark palette. `transformSubAppHtml()` strips any sub-app theme bootstrap and `dark` body class so an embedding host's theme cannot bleed into the fragment.
+The marketplace has no dark mode: no theme toggle, no persisted theme, no `dark` class, no dark palette. A sub-app's own theme bootstrap is removed twice over — `hoist-inline-scripts.js` deletes it while it is still inline, and `transformSubAppHtml()` strips any that reaches Astro, along with a `dark` body class — so an embedding host's theme cannot bleed into the fragment.
+
+Known gap: inline `on*` handlers in sub-app HTML are not stripped (#67). They are inert under the CSP but not under `astro dev`.
 
 ### URL Rewriting
 
-`transform.js` rewrites all relative and root-relative URLs to absolute `/{prefix}/{slug}/...` paths. Runs before the document is split so nothing is double-rewritten. Removes `<base>` tags.
+`transform.js` parses the document with **parse5** and rewrites every URL-bearing attribute to an absolute `/{prefix}/{slug}/…` path: `href`/`src`/`action`/`formaction`/`poster`, `object[data]`, `srcset`/`imagesrcset`, `url()` in inline `style=` and `<style>` blocks, and URL-bearing `<meta>` content. `<base>` tags are removed. Because it walks a parsed tree, markup quoted inside prose or comments is left alone.
+
+Root-relative `url()` inside a sub-app's **copied CSS files** is a separate rewrite, in `copyAssets()` (`scripts/build-vite.js`), targeting the same absolute path.
 
 ## Contract for Doc Apps
 
@@ -118,8 +127,9 @@ Apps registered in `apps.json` must comply with:
 Self-contained Playwright E2E — `npm test` auto-starts everything (no external gateway):
 
 1. **:3000 fragment** — `scripts/setup-test-apps.mjs` writes a hermetic `apps.json` that
-   registers the local `../knowledge-base-docs-example` prebuilt `dist.tar.gz` twice
-   (slugs `user-guide` + `guide-mirror`, for cross-app nav). `build:headless` builds it;
+   registers the vendored `tests/fixtures/docs-example.dist.tar.gz` twice
+   (slugs `user-guide` + `guide-mirror`, for cross-app nav), an iframe entry pinned
+   `"headless": false`, and the generated single-page bundle fixture. `build:headless` builds it;
    `tests/fragment-server.mjs` serves `dist/` mirroring the production **nginx** rewrites
    (`/__wf/knowledge-base/*` → `/knowledge-base/*`). NB: `astro preview` is NOT used — its
    Vite `configurePreviewServer` rewrite hook does not run for static output, so the
@@ -128,14 +138,23 @@ Self-contained Playwright E2E — `npm test` auto-starts everything (no external
    application" (`FragmentGateway` + `getNodeMiddleware`) that proxies/embeds the :3000
    fragment on a single origin via `<web-fragment fragment-id="knowledge-base">`.
 
-Tests drive the host origin (`http://localhost:4201`). Suites (`tests/`):
+Tests drive the host origin (`http://localhost:4201`). Suites (`tests/`), all four
+commands listed in `AGENTS.md`:
 - `build-integrity.spec.js` — `dist/` output: both apps enumerated, absolute URL rewriting,
-  headless markup, the content-hashed marketplace stylesheet plus its stable `dist/style.css`
-  alias, and single-page bundle expansion (`tests/fixtures/single-page-bundle/` → two apps).
-- `web-fragment.spec.js` — shadow-DOM isolation (reframed `wf-html`/`wf-body`; chrome must
+  headless markup and the per-app `"headless"` override, the content-hashed marketplace
+  stylesheet plus its stable `dist/style.css` alias, no inline script anywhere, and
+  single-page bundle expansion (`tests/fixtures/single-page-bundle/` → two apps).
+- `transform.spec.js` — unit tests for `transformSubAppHtml()`: the malformed and
+  hostile documents no fixture app happens to ship.
+- `web-fragment.spec.js` — shadow-DOM isolation (reframed `wf-html`/`wf-body`; host chrome must
   not leak in), routing + smooth no-reload SPA transitions, cross-app navigation, asset
   loading (no host-origin 404s), and the documented history limitation (fragment routing is
   internal to the reframed `wf:<id>` iframe and is not mirrored to top-window history).
+- `artifact-safety.spec.js` — tarball extraction guards (traversal, absolute paths, symlinks).
+- `nginx-config.spec.js` — static assertions on `nginx.conf`/`nginx.headers.conf`, including
+  that the CSP the Express mirror serves is byte-identical to nginx's.
+- `standalone.spec.js` — the `:3000` fragment server directly (`playwright.config.ci.js`).
+- `container.spec.js` — the real nginx image (`playwright.config.docker.js`, needs Docker).
 - `support/fragment.js` — shadow-DOM traversal + reframed-body wait/query helpers.
 
 Two build-pipeline pieces support this: `apps.json` entries may carry a `prebuilt` path
@@ -153,6 +172,9 @@ in the committed `apps.json` without breaking CI, which only has this repo.
 ## Environment Variables
 
 - `GITHUB_TOKEN` — GitHub API auth for fetching Release artifacts
-- `MP_HEADLESS` — `true`/`false`, controls headless mode
-- `MP_PREFIX` — URL prefix (default: `knowledge-base`)
+- `MP_HEADLESS` — `true` produces web-fragment output; **anything else, including unset, means standalone**. `scripts/build-vite.js` always exports an explicit value, so the default only applies when `astro build`/`astro dev` runs directly. Read it through `isHeadlessBuild()`, never inline. A per-app `"headless"` in `apps.json` overrides it in either direction.
 - `AWS_REGION`, `ECR_REPOSITORY`, `ECS_CLUSTER`, `ECS_SERVICE` — deployment config
+- `KB_EXAMPLE_ARTIFACT` — overrides the packaged artifact `scripts/setup-test-apps.mjs` registers
+- `KB_CONTAINER_PORT`, `KB_SKIP_BUILD` — container-suite harness (`tests/container/serve.mjs`); CI sets `KB_SKIP_BUILD` because its image job already built the image
+
+The URL prefix is **not** an environment variable: it is the `PATH_PREFIX` constant in `src/utils/config.js`. `nginx.conf`, `tests/fragment-server.mjs` and the gateway's route patterns hard-code the same string, so changing it means changing all of them together.
diff --git a/README.md b/README.md
index f7af070..269b6c0 100644
--- a/README.md
+++ b/README.md
@@ -13,8 +13,9 @@ 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.
-2. Rewrites every page's URLs to absolute `/knowledge-base/{slug}/…` paths and,
-   in standalone mode, injects a persistent top **chrome** (nav + app switcher).
+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.
 3. Generates a **catalog landing page** listing all registered apps.
 4. Produces a single `dist/` served by **nginx** in Docker, or embedded into a
    host app as a **web fragment**.
@@ -67,11 +68,16 @@ npm test
 | `npm run build:local` | Build each app from a local checkout (`localPath`) |
 | `npm run build:local:headless` | Local + headless |
 
-`--headless` (or `MP_HEADLESS=true`) produces fragment-ready output: no chrome
-bar, `data-mp-headless="true"` on `<html>`, shadow-DOM compat styles.
+`--headless` (or `MP_HEADLESS=true`) produces fragment-ready output, marked with
+`data-mp-headless="true"` on `<html>`. Anything else — including an unset
+`MP_HEADLESS` — means standalone. An individual app can pin either mode with
+`"headless": true|false` in its `apps.json` entry, which wins over the build flag.
 
-Orchestrator: `scripts/build-vite.js` (flags: `--local`, `--headless`,
-`--path-prefix=`).
+Orchestrator: `scripts/build-vite.js` (flags: `--local`, `--headless`).
+
+The URL prefix (`/knowledge-base`) is not configurable: it is the `PATH_PREFIX`
+constant in `src/utils/config.js`, and `nginx.conf` and the fragment gateway's
+route patterns hard-code the same string.
 
 ---
 
@@ -109,7 +115,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>`
-inside the marketplace chrome and shows an **External** badge in the catalogue.
+below the marketplace masthead and shows an **External** badge in the catalogue.
 
 ```jsonc
 {
@@ -206,6 +212,7 @@ E2E tests use Playwright. Everything is hermetic — built from
 |---|---|
 | `npm test` | **Embedded** harness (`playwright.config.js`). Starts the fragment server (`:3000`) and a minimal web-fragments **host gateway** (`tests/host/server.mjs`, `:4201`) that embeds the fragment. Covers shadow-DOM isolation, smooth no-reload SPA routing, cross-app navigation, asset 404s, and the fragment-history limitation. |
 | `npx playwright test --config=playwright.config.ci.js` | **Standalone** layer. Hits the fragment server (`tests/fragment-server.mjs`, `:3000`) directly. Covers HTTP header safety (`X-Frame-Options`), the headless contract, CSS-link stability (web-fragments [#297](https://github.com/web-fragments/web-fragments/issues/297)), and asset routing. |
+| `npm run test:container` | **Container** layer (needs Docker). Runs the real production image — nginx serving `dist/` — instead of the Express mirror the other two use. Covers the shipped `nginx.conf`: rewrites, response headers, the CSP in a browser, and that the image does not run as root. |
 
 > `tests/fragment-server.mjs` serves `dist/` and mirrors the production
 > `nginx.conf` rewrites (including `/__wf/knowledge-base/* → /knowledge-base/*`).
@@ -213,7 +220,8 @@ E2E tests use Playwright. Everything is hermetic — built from
 > `configurePreviewServer` rewrite hook does not run for static output, so the
 > `/__wf` asset route would 404.
 
-Both layers run in CI (`.github/workflows/ci.yml`).
+All three layers run in CI (`.github/workflows/ci.yml`); the container layer runs
+inside the image job, which has already built the image.
 
 ---
 
@@ -269,7 +277,7 @@ Apps must comply with the marketplace contract before they can be registered:
 |---|---|
 | [`contract/schema.json`](contract/schema.json) | JSON Schema for `marketplace.json` |
 | [`contract/HEADLESS_RULES.md`](contract/HEADLESS_RULES.md) | Headless HTML, relative paths, `data-mp-headless` |
-| [`contract/STYLE_GUIDE.md`](contract/STYLE_GUIDE.md) | Design tokens (`--color-kb-*`), typography, dark mode |
+| [`contract/STYLE_GUIDE.md`](contract/STYLE_GUIDE.md) | Design tokens (`--color-kb-*`) and typography — light only; the marketplace has no dark mode |
 | [`contract/SINGLE_PAGE.md`](contract/SINGLE_PAGE.md) | `bundle.json` format + zero-config markdown onboarding |
 
 > The checklist and workflows below apply to **packaged** doc apps. Single-page
@@ -360,16 +368,20 @@ knowledge-base/
 │   ├── styles/marketplace.css ← Design tokens + Tailwind
 │   └── utils/
 │       ├── apps.js            ← loadRegistry() + getAppPages() page enumeration
+│       ├── config.js          ← PATH_PREFIX / BASE_PATH + isHeadlessBuild()
 │       ├── single-page.js     ← bundle.json parsing + registry expansion
-│       └── transform.js       ← URL rewriting + sub-app document splitting
+│       └── transform.js       ← parse5 URL rewriting + sub-app document splitting
 ├── scripts/
 │   ├── build-vite.js          ← Build orchestrator
 │   ├── fetch-apps.js          ← GitHub Release download + extract
+│   ├── artifacts.js           ← Safe tarball extraction + tree copy
+│   ├── hoist-inline-scripts.js ← Inline <script> → file, so the CSP can be strict
 │   └── setup-test-apps.mjs    ← Generates the hermetic test apps.json
 ├── tests/
 │   ├── web-fragment.spec.js   ← Embedded harness suite
 │   ├── standalone.spec.js     ← Standalone fragment-server suite
 │   ├── build-integrity.spec.js
+│   ├── transform.spec.js      ← Unit tests for the sub-app HTML transform
 │   ├── artifact-safety.spec.js ← Tarball extraction guards
 │   ├── nginx-config.spec.js   ← nginx header-inheritance guard (static)
 │   ├── container.spec.js      ← Integration suite vs. the real nginx image
@@ -379,7 +391,8 @@ knowledge-base/
 │   ├── support/fragment.js    ← Shadow-DOM test helpers
 │   └── fixtures/              ← Vendored docs-example dist.tar.gz + single-page bundle
 ├── contract/                  ← marketplace.json schema + rules + style guide
-├── .github/workflows/         ← ci.yml, validate-doc-app.yml
+├── .github/workflows/         ← ci.yml, pages.yml, pr-requirements.yml,
+│                                 validate-doc-app.yml (reusable, for doc repos)
 ├── Dockerfile
 ├── nginx.conf                 ← server block (rewrites, caching, routing)
 └── nginx.headers.conf         ← shared CORS + security headers, included by
diff --git a/apps.json b/apps.json
index 62ae9dc..e63f35c 100644
--- a/apps.json
+++ b/apps.json
@@ -31,7 +31,8 @@
     ],
     "type": "iframe",
     "url": "https://example.com/docs",
-    "temporary": true
+    "temporary": true,
+    "headless": false
   },
   {
     "type": "single-page",
diff --git a/astro.config.mjs b/astro.config.mjs
index 1525eb1..0035b61 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -1,10 +1,9 @@
 import { defineConfig } from 'astro/config';
 import tailwindcss from '@tailwindcss/vite';
-
-const PREFIX = 'knowledge-base';
+import { BASE_PATH, PATH_PREFIX } from './src/utils/config.js';
 
 export default defineConfig({
-  base: '/knowledge-base',
+  base: BASE_PATH,
   output: 'static',
 
   vite: {
@@ -16,8 +15,8 @@ export default defineConfig({
         name: 'wf-fragment-alias',
         configurePreviewServer(server) {
           server.middlewares.use((req, _res, next) => {
-            if (req.url?.startsWith(`/__wf/${PREFIX}`)) {
-              req.url = req.url.replace(`/__wf/${PREFIX}`, `/${PREFIX}`);
+            if (req.url?.startsWith(`/__wf/${PATH_PREFIX}`)) {
+              req.url = req.url.replace(`/__wf/${PATH_PREFIX}`, BASE_PATH);
             }
             next();
           });
diff --git a/scripts/build-vite.js b/scripts/build-vite.js
index 5bc0e89..ad7181b 100644
--- a/scripts/build-vite.js
+++ b/scripts/build-vite.js
@@ -7,11 +7,13 @@
  *   node scripts/build-vite.js --headless
  *
  * Pipeline:
- *   1. Fetch/build sub-app artifacts → apps/{slug}/
- *   2. Copy non-HTML sub-app assets → public/knowledge-base/{slug}/
- *      (Astro serves these as static files; HTML files are handled by the catchall page)
- *   3. Run astro build → dist/
- *      Sub-app pages are rendered by src/pages/[...path].astro via getStaticPaths.
+ *   1.  Fetch/build sub-app artifacts → apps/{slug}/
+ *   1b. Hoist inline <script> bodies → apps/{slug}/_kb-inline/*.js, and delete
+ *       any theme bootstrap (light only)
+ *   2.  Copy non-HTML sub-app assets → public/{slug}/
+ *       (Astro serves these as static files; HTML files are handled by the catchall page)
+ *   3.  Run astro build → dist/
+ *       Sub-app pages are rendered by src/pages/[...path].astro via getStaticPaths.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, copyFileSync, readdirSync, statSync } from 'node:fs';
@@ -23,6 +25,7 @@ import { copyDir, stageArtifact } from './artifacts.js';
 import { fetchApps } from './fetch-apps.js';
 import { HOIST_DIR, hoistAppInlineScripts } from './hoist-inline-scripts.js';
 import { collectHtmlFiles } from '../src/utils/apps.js';
+import { PATH_PREFIX } from '../src/utils/config.js';
 import {
   BUNDLE_MANIFEST, bundleDirName, bundleKey, expandBundle, findBundleRoot,
   isSinglePage, readBundleManifest, resolveRegistry, toRegistryEntry, writeExpansionMap,
@@ -32,10 +35,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
 const APPS_DIR = join(ROOT, 'apps');
 
-const LOCAL_MODE  = process.argv.includes('--local');
-const HEADLESS    = process.argv.includes('--headless') || process.env.MP_HEADLESS === 'true';
-const prefixArg   = process.argv.find(a => a.startsWith('--path-prefix='));
-const PATH_PREFIX = prefixArg ? prefixArg.split('=').slice(1).join('=') : 'knowledge-base';
+const LOCAL_MODE = process.argv.includes('--local');
+const HEADLESS   = process.argv.includes('--headless') || process.env.MP_HEADLESS === 'true';
 
 const log  = (msg) => console.log('\x1b[36m→\x1b[0m ' + msg);
 const ok   = (msg) => console.log('\x1b[32m✓\x1b[0m ' + msg);
@@ -169,7 +170,7 @@ async function build() {
   const packagedApps = registeredApps.filter(a => a.type !== 'iframe');
 
   // 1. Prepare apps/ directory
-  step('1/3  Preparing sub-app artifacts → apps/');
+  step('1/4  Preparing sub-app artifacts → apps/');
   mkdirSync(APPS_DIR, { recursive: true });
 
   for (const app of iframeApps) ok(app.slug + ' registered (iframe → ' + app.url + ')');
@@ -309,11 +310,9 @@ async function build() {
 
   // 3. Run Astro build
   step('3/4  Running astro build');
-  const env = {
-    ...process.env,
-    MP_PREFIX:   PATH_PREFIX,
-    MP_HEADLESS: HEADLESS ? 'true' : 'false',
-  };
+  // Always explicit: src/utils/config.js treats an unset MP_HEADLESS as
+  // standalone, and a build that says "--headless" must not depend on that.
+  const env = { ...process.env, MP_HEADLESS: HEADLESS ? 'true' : 'false' };
   execSync('npx astro build', { cwd: ROOT, stdio: 'inherit', env });
   ok('Astro build complete');
 
diff --git a/scripts/setup-test-apps.mjs b/scripts/setup-test-apps.mjs
index 7ab008f..8b91580 100644
--- a/scripts/setup-test-apps.mjs
+++ b/scripts/setup-test-apps.mjs
@@ -221,6 +221,12 @@ const apps = [
     type: 'iframe',
     url: 'https://example.com/docs',
     temporary: true,
+    // Pinned standalone so the suite covers the per-app override in the
+    // direction that used to be impossible: the harness builds headless, and
+    // this app must still come out without data-mp-headless (#52). This entry
+    // is the one with no headless assertions of its own, so it can carry the
+    // pin without weakening another test.
+    headless: false,
   },
   {
     // single-page onboarding mode (issue #35): one bundle, no per-doc metadata
diff --git a/src/layouts/Base.astro b/src/layouts/Base.astro
index 00a97b9..1cb12e6 100644
--- a/src/layouts/Base.astro
+++ b/src/layouts/Base.astro
@@ -11,9 +11,11 @@
 import '../styles/marketplace.css';
 import { ClientRouter } from 'astro:transitions';
 import { shadowCompatStyle } from '../templates/shadow-compat.js';
+import { isHeadlessBuild } from '../utils/config.js';
 
 interface Props {
   title?: string;
+  /** Per-app override. Undefined means "whatever this build is" — see config.js. */
   headless?: boolean;
   /** Extra classes for <body> — packaged sub-app pages pass their own body class. */
   bodyClass?: string;
@@ -23,13 +25,15 @@ interface Props {
 
 const {
   title = 'Knowledge base',
-  headless = false,
+  headless,
   bodyClass = '',
   flexBody = true,
 } = Astro.props;
 
-const HEADLESS = process.env.MP_HEADLESS !== 'false';
-const effectiveHeadless = headless || HEADLESS;
+// `??`, not `||`: an app pinned "headless": false in apps.json must be able to
+// opt out of a headless build. With `||` the prop could only ever turn headless
+// on, so the override was write-only in one direction (#52).
+const effectiveHeadless = headless ?? isHeadlessBuild();
 
 const bodyClasses = [
   flexBody ? 'min-h-screen flex flex-col' : '',
diff --git a/src/pages/[...path].astro b/src/pages/[...path].astro
index f17b872..408eebb 100644
--- a/src/pages/[...path].astro
+++ b/src/pages/[...path].astro
@@ -13,15 +13,13 @@
 
 import { readFileSync } from 'node:fs';
 import { getAppPages } from '../utils/apps.js';
+import { BASE_PATH, PATH_PREFIX, isHeadlessBuild } from '../utils/config.js';
 import { transformSubAppHtml } from '../utils/transform.js';
 import Base from '../layouts/Base.astro';
 import Masthead from '../components/Masthead.astro';
 
-const PREFIX = 'knowledge-base';
-
 export function getStaticPaths() {
-  const headless = process.env.MP_HEADLESS !== 'false';
-  return getAppPages(process.cwd(), headless).map(({ routePath, ...props }) => ({
+  return getAppPages(process.cwd(), isHeadlessBuild()).map(({ routePath, ...props }) => ({
     params: { path: routePath },
     props,
   }));
@@ -32,7 +30,7 @@ const { slug, appHeadless, apps, title } = props;
 
 const parts = props.iframe
   ? null
-  : transformSubAppHtml(readFileSync(props.file, 'utf-8'), slug, props.fileRelDir, PREFIX);
+  : transformSubAppHtml(readFileSync(props.file, 'utf-8'), slug, props.fileRelDir, PATH_PREFIX);
 
 const app = apps.find((a: any) => a.slug === slug);
 const pageTitle = title ?? parts?.title ?? app?.name ?? 'Knowledge base';
@@ -49,7 +47,7 @@ const atAppRoot = !props.fileRelDir;
 >
   {parts && <Fragment slot="head" set:html={parts.headHtml} />}
 
-  <Masthead apps={apps} activeSlug={slug} base={`/${PREFIX}`} appRoot={atAppRoot} />
+  <Masthead apps={apps} activeSlug={slug} base={BASE_PATH} appRoot={atAppRoot} />
 
   {props.iframe ? (
     <main style="display:flex;flex:1 1 auto;min-height:0">
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 1e3e08f..781eaa6 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -4,8 +4,7 @@ import Base from '../layouts/Base.astro';
 import Masthead from '../components/Masthead.astro';
 import AppCard from '../components/AppCard.astro';
 import { loadRegistry } from '../utils/apps.js';
-
-const HEADLESS = process.env.MP_HEADLESS !== 'false';
+import { BASE_PATH } from '../utils/config.js';
 
 // The effective registry: apps.json, with every single-page bundle replaced by
 // the docs it expanded into, so each one gets its own catalog card.
@@ -14,8 +13,8 @@ const apps = loadRegistry(process.cwd());
 const buildDate = new Date().toISOString().slice(0, 10);
 ---
 
-<Base headless={HEADLESS}>
-  <Masthead apps={apps} activeSlug="" base="/knowledge-base" />
+<Base>
+  <Masthead apps={apps} activeSlug="" base={BASE_PATH} />
 
   <div class="flex flex-col flex-1">
     <!-- App catalog -->
@@ -27,7 +26,7 @@ const buildDate = new Date().toISOString().slice(0, 10);
       </div>
       <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-5" role="list">
         {apps.map((app: any, i: number) => (
-          <AppCard app={app} delay={i < 4 ? i + 1 : 0} base="/knowledge-base" />
+          <AppCard app={app} delay={i < 4 ? i + 1 : 0} base={BASE_PATH} />
         ))}
       </div>
     </main>
diff --git a/src/utils/config.js b/src/utils/config.js
new file mode 100644
index 0000000..a2369ba
--- /dev/null
+++ b/src/utils/config.js
@@ -0,0 +1,42 @@
+// src/utils/config.js
+//
+// The two build-wide decisions — where the site is mounted, and whether this
+// build is a web fragment — in one place, because both used to be spelled out
+// independently in three or four files and the copies disagreed.
+
+/**
+ * The URL prefix everything is served under.
+ *
+ * **Not configurable, deliberately.** The build used to advertise a
+ * `--path-prefix=` flag and an `MP_PREFIX` variable that nothing in the Astro
+ * build ever read, so `--path-prefix=docs` produced a `dist/` that still said
+ * `knowledge-base` everywhere and only the closing build summary agreed with the
+ * flag (#46). Making it real means templating `nginx.conf`, the `/__wf/` rewrite
+ * and the fragment gateway's route patterns too — all of which bake this string
+ * in — so the honest fix was to delete the flag and keep one constant.
+ *
+ * Changing the prefix is a deployment change, not a build option: this constant,
+ * `nginx.conf`, `tests/fragment-server.mjs` and the gateway config must move
+ * together.
+ */
+export const PATH_PREFIX = 'knowledge-base';
+
+/** The same thing as an absolute path — Astro's `base`, and every link root. */
+export const BASE_PATH = `/${PATH_PREFIX}`;
+
+/**
+ * Whether this build produces web-fragment (headless) output.
+ *
+ * **Unset means standalone.** `scripts/build-vite.js` always exports an explicit
+ * `'true'`/`'false'`, so the default only applies when `astro build`/`astro dev`
+ * is run directly — and there, "I did not ask for a fragment" is the answer that
+ * matches the flag's name. Base.astro used to read `!== 'false'` (unset ⇒
+ * headless) while the orchestrator computed the opposite; nothing caught it
+ * because the orchestrator never leaves the variable unset (#52).
+ *
+ * A per-app `"headless"` in apps.json overrides this in either direction; the
+ * override is resolved in src/utils/apps.js and passed down as a prop.
+ */
+export function isHeadlessBuild(env = process.env) {
+  return env.MP_HEADLESS === 'true';
+}
diff --git a/tests/build-integrity.spec.js b/tests/build-integrity.spec.js
index 480359c..d9aae88 100644
--- a/tests/build-integrity.spec.js
+++ b/tests/build-integrity.spec.js
@@ -123,6 +123,15 @@ test.describe('iframe onboarding', () => {
     expect(existsSync(join(DIST, 'external-docs/docs')), 'unexpected packaged pages for iframe entry').toBe(false);
   });
 
+  test('a per-app "headless": false wins over a headless build', () => {
+    // The harness builds with --headless, and external-docs is pinned standalone
+    // in apps.json. Base.astro used to OR the prop with the global flag, so the
+    // override could only ever turn headless on (#52).
+    expect(read('external-docs/index.html')).not.toContain('data-mp-headless');
+    // …while its neighbours in the same build are still headless.
+    expect(read('user-guide/index.html')).toContain('data-mp-headless="true"');
+  });
+
   test('landing shows the iframe app card with an External badge', () => {
     const html = read('index.html');
     expect(html).toContain('External Docs');
diff --git a/vite.config.js b/vite.config.js
deleted file mode 100644
index 816ce6b..0000000
--- a/vite.config.js
+++ /dev/null
@@ -1,62 +0,0 @@
-/**
- * vite.config.js — knowledge-base Vite configuration
- *
- * Architecture:
- *  - index.html is the Vite entry (marketplace landing page template)
- *  - src/style.css is the TailwindCSS entry (processed by @tailwindcss/vite)
- *  - The marketplace Vite plugin handles sub-app HTML processing:
- *      • Dev: intercepts /knowledge-base/{slug}/ requests, transforms HTML on-the-fly
- *      • Build: post-processes apps/**\/*.html → dist/{slug}/ after Vite finishes
- */
-
-import { defineConfig } from 'vite';
-import tailwindcss from '@tailwindcss/vite';
-import { marketplacePlugin } from './plugins/marketplace.js';
-
-const PREFIX = process.env.MP_PREFIX || 'knowledge-base';
-const HEADLESS = process.env.MP_HEADLESS !== 'false'; // headless by default
-
-export default defineConfig({
-  // Never let Vite inject a <base href> — the plugin handles all URL prefixing explicitly.
-  base: '/',
-
-  plugins: [
-    tailwindcss(),
-    marketplacePlugin({ prefix: PREFIX, headless: HEADLESS, appsDir: 'apps' }),
-  ],
-
-  css: {
-    // Disable CSS modules — we use plain CSS
-    modules: false,
-  },
-
-  build: {
-    outDir: 'dist',
-    emptyOutDir: true,
-    rollupOptions: {
-      input: {
-        // Only the marketplace landing page is a Vite entry.
-        // Sub-app HTML files are processed by the marketplace plugin.
-        index: 'index.html',
-      },
-      output: {
-        // Emit style.css at the root (not assets/style-[hash].css)
-        // so sub-apps can reference /{PREFIX}/style.css reliably.
-        assetFileNames: (info) =>
-          info.name?.endsWith('.css') ? '[name][extname]' : 'assets/[name]-[hash][extname]',
-        entryFileNames: 'assets/[name]-[hash].js',
-      },
-    },
-  },
-
-  server: {
-    port: 3000,
-    strictPort: true,
-    fs: { strict: false },
-  },
-
-  preview: {
-    port: 3000,
-    strictPort: true,
-  },
-});