diff --git a/.gitignore b/.gitignore
index 44ddc10..cbad2d2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,6 +37,7 @@ fixtures/mcp-multi-server/public/index.md
 fixtures/discovery/public/index.md
 fixtures/middleware/public/index.md
 fixtures/*/public/auth.md
+fixtures/*/public/404.md
 
 # The serving-manifest data module a fixture's `prebuild: ax manifest` regenerates every build —
 # build output there (real projects may commit theirs; a fixture must rebuild it from scratch).
diff --git a/README.md b/README.md
index 0bea1ea..4dfb250 100644
--- a/README.md
+++ b/README.md
@@ -37,9 +37,11 @@ ax detects gated MCP and OpenAPI surfaces, lets you declare the real auth flow w
 see one, and publishes both in a generated `auth.md`. Your 401/403 responses stay honest — ax never
 touches your route handlers.
 
-**Steer lost agents back — agent-aware 404 + wayfinding middleware**
-An opt-in `not-found.tsx` lists your real routes and discovery artifacts for agents that hit a dead
-end; the runtime middleware gives the same wayfinding response to any URL that matches nothing.
+**Steer lost agents back — `/404.md` wayfinding guide + middleware**
+Every build generates `/404.md` — your real routes and discovery artifacts, for agents that hit a
+dead end. Your 404 page stays yours: ax only asks it to carry one invisible
+`<link rel="alternate" type="text/markdown" href="/404.md">` tag. The runtime middleware serves the
+same wayfinding response directly for any URL that matches nothing.
 
 **Tell agents who you are and gain their trust — JSON-LD scaffolding**
 An opt-in `Organization` JSON-LD component is scaffolded from your `package.json`. ax prints the
@@ -136,13 +138,12 @@ const config: AxConfig = {
   emit: 'static',
   // Scaffold a starter llms.txt filled with your real routes and artifacts. Opt-in.
   scaffoldLlmsTxt: true,
-  // Scaffold an agent-aware app/not-found.tsx plus a regenerated route-manifest module. Opt-in.
-  scaffoldAgent404: true,
   // Add Sitemap:/Agentmap: discovery lines to robots.txt (or write one if you have none). Opt-in.
   scaffoldRobots: true,
   // Scaffold an Organization JSON-LD component. Opt-in; ax never wires it into your layout.
   scaffoldJsonLd: true,
-  // Generate markdown twins of your pages, plus /auth.md when surfaces are gated. Default on.
+  // Generate markdown twins of your pages, /auth.md when surfaces are gated, and the /404.md
+  // wayfinding guide lost agents continue from. Default on.
   markdownTwins: true,
   // Write .ora/report.json, the machine-readable build report. Opt-in.
   report: true,
diff --git a/docs-internal/PLAN.md b/docs-internal/PLAN.md
index 6f69114..17e1bd7 100644
--- a/docs-internal/PLAN.md
+++ b/docs-internal/PLAN.md
@@ -859,6 +859,16 @@ Two additions shipped alongside Phase 4, both following existing conventions:
       sync, the agreed pattern is a composing higher-order middleware that wraps the user's
       existing middleware instead of owning the file, which removes the invasiveness objection.
       See the Vercel strategy sync section.
+      **Update (2026-08-28): redesigned — the scaffold, data module, and `scaffoldAgent404` option
+      are gone.** A scaffolded human-visible page was intrusive (users design their own 404s; the
+      unstyled scaffold got rewritten anyway), and root-only detection was false comfort: App
+      Router `not-found.*` is per-segment, and dynamic-route misses render the *nearest* one,
+      bypassing both the root page and the middleware's wayfinding branch (the URL matches a route
+      pattern). Now: ax generates only `public/404.md` (the wayfinding-guide artifact, same
+      `renderWayfinding` body as the middleware, gated on `markdownTwins` like `auth.md`);
+      detection scans every `app/**/not-found.*` plus `pages/404.*` and recommends one
+      `<link rel="alternate" type="text/markdown" href="/404.md">` tag per unlinked page — the
+      human 404 surface belongs to the user, ax only owns machine artifacts.
 - [x] **Machine-readable build report** (`src/report.ts`; `--report[=path]` / `ax.config`
       `report`, default off; default path `.ora/report.json`). The structured twin of the CLI
       output: entries + written paths, MCP mounts + server card, WebMCP sites, per-artifact
@@ -922,8 +932,10 @@ consumer's source tree unasked), **write-once or append-only** (never overwrite,
     deliberately does **not** wire the component into `app/layout.tsx` (editing the file every page
     renders through, behind the owner's back, is not a postbuild step's call) — it prints the exact
     import + element instead.
-  - **`scaffoldAgent404`** (Phase 4.5) — the same pattern: a user-owned `not-found.tsx` written once,
-    backed by a data module regenerated every build from the real route tree.
+  - **`scaffoldAgent404`** (Phase 4.5) — was the same pattern (a user-owned `not-found.tsx` written
+    once, backed by a regenerated data module) until the 2026-08-28 redesign removed it; see the
+    Phase 4.5 update above. The 404 story is now the generated `public/404.md` + a link-tag
+    recommendation, with no scaffold and no config option.
 
 **3. The report became a handoff, not a log (`src/report.ts` v2 + `src/ora-checks.ts`).** The plugin's
 half of the loop is deterministic detection/emission/scaffolding; the other half — authoring content,
@@ -1147,8 +1159,9 @@ ceremony.
      entries, with the default floor (`/api/auth/**`, `/api/webhooks/**`) pre-noted. Answers
      become an `isGated` matcher (compose `defaultIsGated` unless the user deselects the floor).
      A reviewed detection beats free-text glob authoring.
-   - **Scaffold opt-ins** (`scaffoldLlmsTxt`, `scaffoldJsonLd`, `scaffoldRobots`,
-     `scaffoldAgent404`) — **default yes in the wizard.** This is not a contradiction of the
+   - **Scaffold opt-ins** (`scaffoldLlmsTxt`, `scaffoldJsonLd`, `scaffoldRobots`; historically
+     also `scaffoldAgent404`, removed 2026-08-28) — **default yes in the wizard.** This is not a
+     contradiction of the
      config's `false` defaults: config defaults are `false` because *silent* writes into a source
      tree are invasive; in a wizard the user is present and the ask itself is the opt-in.
      Default-yes-when-asked / default-no-when-silent is one coherent policy — state it in the docs.
diff --git a/fixtures/bare/report.golden.json b/fixtures/bare/report.golden.json
index b6bc6ee..9bf2f29 100644
--- a/fixtures/bare/report.golden.json
+++ b/fixtures/bare/report.golden.json
@@ -16,7 +16,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -67,6 +69,13 @@
       "bytes": 87,
       "chars": 87,
       "tokens": 22
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 643,
+      "chars": 637,
+      "tokens": 159
     }
   ],
   "ora": {
@@ -160,7 +169,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/bare/twins.golden/404.md b/fixtures/bare/twins.golden/404.md
new file mode 100644
index 0000000..f4b6ef6
--- /dev/null
+++ b/fixtures/bare/twins.golden/404.md
@@ -0,0 +1,21 @@
+---
+title: "Page not found — bare"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: /404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/config-overrides/report.golden.json b/fixtures/config-overrides/report.golden.json
index 66a8878..9ac8c8e 100644
--- a/fixtures/config-overrides/report.golden.json
+++ b/fixtures/config-overrides/report.golden.json
@@ -35,7 +35,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -86,6 +88,13 @@
       "bytes": 658,
       "chars": 658,
       "tokens": 165
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 655,
+      "chars": 649,
+      "tokens": 162
     }
   ],
   "ora": {
@@ -181,7 +190,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/config-overrides/twins.golden/404.md b/fixtures/config-overrides/twins.golden/404.md
new file mode 100644
index 0000000..ee36ac3
--- /dev/null
+++ b/fixtures/config-overrides/twins.golden/404.md
@@ -0,0 +1,21 @@
+---
+title: "Page not found — config-overrides"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: /404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/deploy-variants/report.golden.json b/fixtures/deploy-variants/report.golden.json
index de7c4e6..9747df7 100644
--- a/fixtures/deploy-variants/report.golden.json
+++ b/fixtures/deploy-variants/report.golden.json
@@ -16,7 +16,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -67,6 +69,13 @@
       "bytes": 98,
       "chars": 98,
       "tokens": 25
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 674,
+      "chars": 668,
+      "tokens": 167
     }
   ],
   "ora": {
@@ -165,7 +174,7 @@
     "basePath \"/app\" means the catalog is served at /app/.well-known/ai-catalog.json, not at the conventional /.well-known/ai-catalog.json a crawler probes. Point agents at it (ARD §6.1):",
     "  • Add to your root layout <head>: <link rel=\"ai-catalog\" href=\"/app/.well-known/ai-catalog.json\" />",
     "  • Add to robots.txt (app/robots.ts or public/robots.txt): Agentmap: /app/.well-known/ai-catalog.json",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/app/404.md\" />` so agents can hop from it to /app/404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/deploy-variants/twins.golden/404.md b/fixtures/deploy-variants/twins.golden/404.md
new file mode 100644
index 0000000..7452234
--- /dev/null
+++ b/fixtures/deploy-variants/twins.golden/404.md
@@ -0,0 +1,21 @@
+---
+title: "Page not found — deploy-variants"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: /app/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/app/.well-known/ai-catalog.json](/app/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/app/](/app/)
diff --git a/fixtures/discovery/report.golden.json b/fixtures/discovery/report.golden.json
index 9b1a71e..fc60af2 100644
--- a/fixtures/discovery/report.golden.json
+++ b/fixtures/discovery/report.golden.json
@@ -17,7 +17,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -80,6 +82,13 @@
       "bytes": 474,
       "chars": 468,
       "tokens": 117
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 722,
+      "chars": 714,
+      "tokens": 179
     }
   ],
   "ora": {
@@ -172,7 +181,7 @@
     "agents.md detected (public/agents.md) — confirm it has clear when-to-use / when-NOT-to-use guidance for agents.",
     "JSON-LD structured data detected (app/layout.tsx) — confirm it includes an Organization block with a \"sameAs\" array (LinkedIn/GitHub/npm/socials), a logo, and an address, and at least one more @type beyond Organization (SoftwareApplication/Product, or a FAQPage), so registries can disambiguate and rank your site — covering more schema.org types helps them understand it more fully. Make sure you also have an llms.txt: it and JSON-LD reinforce each other (what your site is for vs. what entity it is).",
     "Markdown twins exist for your pages — link each HTML page to its twin so crawlers find the machine-readable version. Add this to the page <head> (ax prints the tag; it never edits your layout): <link rel=\"alternate\" type=\"text/markdown\" href=\"https://discovery-fixture.example.com/index.md\" />",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/discovery/twins.golden/404.md b/fixtures/discovery/twins.golden/404.md
new file mode 100644
index 0000000..e35e749
--- /dev/null
+++ b/fixtures/discovery/twins.golden/404.md
@@ -0,0 +1,21 @@
+---
+title: "Page not found — discovery"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://discovery-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/) — markdown: [/index.md](/index.md)
diff --git a/fixtures/hybrid/report.golden.json b/fixtures/hybrid/report.golden.json
index f346908..128ae18 100644
--- a/fixtures/hybrid/report.golden.json
+++ b/fixtures/hybrid/report.golden.json
@@ -18,7 +18,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -79,6 +81,13 @@
       "bytes": 145,
       "chars": 145,
       "tokens": 36
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 725,
+      "chars": 719,
+      "tokens": 180
     }
   ],
   "ora": {
@@ -172,7 +181,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/hybrid/twins.golden/404.md b/fixtures/hybrid/twins.golden/404.md
new file mode 100644
index 0000000..7339fd7
--- /dev/null
+++ b/fixtures/hybrid/twins.golden/404.md
@@ -0,0 +1,23 @@
+---
+title: "Page not found — hybrid"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://hybrid-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/)
+- [/about](/about)
+- [/dashboard](/dashboard)
diff --git a/fixtures/llms-txt/report.golden.json b/fixtures/llms-txt/report.golden.json
index 79d6ca8..78a7c05 100644
--- a/fixtures/llms-txt/report.golden.json
+++ b/fixtures/llms-txt/report.golden.json
@@ -24,7 +24,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -76,6 +78,13 @@
       "bytes": 405,
       "chars": 405,
       "tokens": 101
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 771,
+      "chars": 763,
+      "tokens": 191
     }
   ],
   "ora": {
@@ -168,7 +177,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/llms-txt/twins.golden/404.md b/fixtures/llms-txt/twins.golden/404.md
new file mode 100644
index 0000000..f683aea
--- /dev/null
+++ b/fixtures/llms-txt/twins.golden/404.md
@@ -0,0 +1,22 @@
+---
+title: "Page not found — llms-txt"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://llms-txt-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+- [/llms.txt](/llms.txt) — what this site is for and its key pages, in plain language
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/markdown-twins/report.golden.json b/fixtures/markdown-twins/report.golden.json
index 3285fe7..4cffb69 100644
--- a/fixtures/markdown-twins/report.golden.json
+++ b/fixtures/markdown-twins/report.golden.json
@@ -17,7 +17,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -118,6 +120,13 @@
       "bytes": 591,
       "chars": 589,
       "tokens": 147
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 939,
+      "chars": 925,
+      "tokens": 231
     }
   ],
   "ora": {
@@ -213,7 +222,7 @@
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
     "Markdown twins exist for your pages — link each HTML page to its twin so crawlers find the machine-readable version. Add this to the page <head> (ax prints the tag; it never edits your layout): <link rel=\"alternate\" type=\"text/markdown\" href=\"https://markdown-twins-fixture.example.com/guides/setup.md\" />",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/markdown-twins/twins.golden/404.md b/fixtures/markdown-twins/twins.golden/404.md
new file mode 100644
index 0000000..ad1bf48
--- /dev/null
+++ b/fixtures/markdown-twins/twins.golden/404.md
@@ -0,0 +1,25 @@
+---
+title: "Page not found — markdown-twins"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://markdown-twins-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/) — markdown: [/index.md](/index.md)
+- [/guides/setup](/guides/setup) — markdown: [/guides/setup.md](/guides/setup.md)
+- [/hand](/hand) — markdown: [/hand.md](/hand.md)
+- [/live](/live) — markdown: [/live.md](/live.md)
+- [/shell](/shell)
diff --git a/fixtures/mcp-adapter-gated/report.golden.json b/fixtures/mcp-adapter-gated/report.golden.json
index c466b9f..1b72b7f 100644
--- a/fixtures/mcp-adapter-gated/report.golden.json
+++ b/fixtures/mcp-adapter-gated/report.golden.json
@@ -32,7 +32,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -109,6 +111,13 @@
       "bytes": 960,
       "chars": 954,
       "tokens": 239
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 888,
+      "chars": 878,
+      "tokens": 220
     }
   ],
   "ora": {
@@ -224,7 +233,7 @@
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
     "Gated routes should keep their honest 401/403 status and point agents at the auth guide: add a WWW-Authenticate header and a Link (or body) pointer to /auth.md in your gated route handlers. A 200 \"this is gated\" page is a soft auth wall agents are built to distrust; ax generates the guide but never rewrites your handlers.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/mcp-adapter-gated/twins.golden/404.md b/fixtures/mcp-adapter-gated/twins.golden/404.md
new file mode 100644
index 0000000..d041d3e
--- /dev/null
+++ b/fixtures/mcp-adapter-gated/twins.golden/404.md
@@ -0,0 +1,23 @@
+---
+title: "Page not found — mcp-adapter-gated"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://mcp-gated-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+- [/auth.md](/auth.md) — how to obtain access to the gated surfaces
+- [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json) — the MCP server card (connection + capabilities)
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/mcp-adapter/report.golden.json b/fixtures/mcp-adapter/report.golden.json
index 8070ca7..cbb4672 100644
--- a/fixtures/mcp-adapter/report.golden.json
+++ b/fixtures/mcp-adapter/report.golden.json
@@ -34,7 +34,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -92,6 +94,13 @@
       "bytes": 596,
       "chars": 596,
       "tokens": 149
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 814,
+      "chars": 806,
+      "tokens": 202
     }
   ],
   "ora": {
@@ -190,7 +199,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/mcp-adapter/twins.golden/404.md b/fixtures/mcp-adapter/twins.golden/404.md
new file mode 100644
index 0000000..2bd79f0
--- /dev/null
+++ b/fixtures/mcp-adapter/twins.golden/404.md
@@ -0,0 +1,22 @@
+---
+title: "Page not found — mcp-adapter"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://mcp-adapter-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+- [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json) — the MCP server card (connection + capabilities)
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/mcp-multi-server/report.golden.json b/fixtures/mcp-multi-server/report.golden.json
index 0bd2385..4513c6a 100644
--- a/fixtures/mcp-multi-server/report.golden.json
+++ b/fixtures/mcp-multi-server/report.golden.json
@@ -57,7 +57,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -156,6 +158,13 @@
       "bytes": 962,
       "chars": 956,
       "tokens": 239
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 924,
+      "chars": 912,
+      "tokens": 228
     }
   ],
   "ora": {
@@ -270,7 +279,7 @@
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
     "Gated routes should keep their honest 401/403 status and point agents at the auth guide: add a WWW-Authenticate header and a Link (or body) pointer to /auth.md in your gated route handlers. A 200 \"this is gated\" page is a soft auth wall agents are built to distrust; ax generates the guide but never rewrites your handlers.",
     "Markdown twins exist for your pages — link each HTML page to its twin so crawlers find the machine-readable version. Add this to the page <head> (ax prints the tag; it never edits your layout): <link rel=\"alternate\" type=\"text/markdown\" href=\"https://mcp-multi-fixture.example.com/index.md\" />",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/mcp-multi-server/twins.golden/404.md b/fixtures/mcp-multi-server/twins.golden/404.md
new file mode 100644
index 0000000..f1a6c33
--- /dev/null
+++ b/fixtures/mcp-multi-server/twins.golden/404.md
@@ -0,0 +1,23 @@
+---
+title: "Page not found — mcp-multi-server"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://mcp-multi-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+- [/auth.md](/auth.md) — how to obtain access to the gated surfaces
+- [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json) — the MCP server card (connection + capabilities)
+
+## Pages that do exist
+
+- [/](/) — markdown: [/index.md](/index.md)
diff --git a/fixtures/mdx-content/report.golden.json b/fixtures/mdx-content/report.golden.json
index f0bc03a..a5ead75 100644
--- a/fixtures/mdx-content/report.golden.json
+++ b/fixtures/mdx-content/report.golden.json
@@ -17,7 +17,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -95,6 +97,13 @@
       "bytes": 543,
       "chars": 543,
       "tokens": 136
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 726,
+      "chars": 718,
+      "tokens": 180
     }
   ],
   "ora": {
@@ -188,7 +197,7 @@
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
     "Markdown twins exist for your pages — link each HTML page to its twin so crawlers find the machine-readable version. Add this to the page <head> (ax prints the tag; it never edits your layout): <link rel=\"alternate\" type=\"text/markdown\" href=\"https://mdx-content-fixture.example.com/guide.md\" />",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/mdx-content/twins.golden/404.md b/fixtures/mdx-content/twins.golden/404.md
new file mode 100644
index 0000000..8a5c77a
--- /dev/null
+++ b/fixtures/mdx-content/twins.golden/404.md
@@ -0,0 +1,21 @@
+---
+title: "Page not found — mdx-content"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://mdx-content-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/) — markdown: [/index.md](/index.md)
diff --git a/fixtures/middleware/report.golden.json b/fixtures/middleware/report.golden.json
index 93a7b02..3799b5c 100644
--- a/fixtures/middleware/report.golden.json
+++ b/fixtures/middleware/report.golden.json
@@ -17,7 +17,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": true,
@@ -93,6 +95,13 @@
       "bytes": 783,
       "chars": 781,
       "tokens": 195
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 795,
+      "chars": 785,
+      "tokens": 196
     }
   ],
   "ora": {
@@ -185,6 +194,6 @@
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
     "Markdown twins exist for your pages — link each HTML page to its twin so crawlers find the machine-readable version. Add this to the page <head> (ax prints the tag; it never edits your layout): <link rel=\"alternate\" type=\"text/markdown\" href=\"https://middleware-fixture.example.com/docs.md\" />",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you."
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router."
   ]
 }
diff --git a/fixtures/middleware/twins.golden/404.md b/fixtures/middleware/twins.golden/404.md
new file mode 100644
index 0000000..360424c
--- /dev/null
+++ b/fixtures/middleware/twins.golden/404.md
@@ -0,0 +1,23 @@
+---
+title: "Page not found — middleware"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://middleware-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/) — markdown: [/index.md](/index.md)
+- [/docs](/docs) — markdown: [/docs.md](/docs.md)
+- [/shell](/shell)
diff --git a/fixtures/openapi/report.golden.json b/fixtures/openapi/report.golden.json
index 92e4747..31c144e 100644
--- a/fixtures/openapi/report.golden.json
+++ b/fixtures/openapi/report.golden.json
@@ -24,7 +24,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -95,6 +97,13 @@
       "bytes": 916,
       "chars": 910,
       "tokens": 228
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 825,
+      "chars": 815,
+      "tokens": 204
     }
   ],
   "ora": {
@@ -209,7 +218,7 @@
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
     "Gated routes should keep their honest 401/403 status and point agents at the auth guide: add a WWW-Authenticate header and a Link (or body) pointer to /auth.md in your gated route handlers. A 200 \"this is gated\" page is a soft auth wall agents are built to distrust; ax generates the guide but never rewrites your handlers.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/openapi/twins.golden/404.md b/fixtures/openapi/twins.golden/404.md
new file mode 100644
index 0000000..3bd0ae3
--- /dev/null
+++ b/fixtures/openapi/twins.golden/404.md
@@ -0,0 +1,23 @@
+---
+title: "Page not found — openapi"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://openapi-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+- [/auth.md](/auth.md) — how to obtain access to the gated surfaces
+- [/openapi.json](/openapi.json) — the REST API, as an OpenAPI document
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/pages-bare/report.golden.json b/fixtures/pages-bare/report.golden.json
index a12e6e2..647beb7 100644
--- a/fixtures/pages-bare/report.golden.json
+++ b/fixtures/pages-bare/report.golden.json
@@ -18,7 +18,13 @@
   "agent404": {
     "notFoundPresent": true,
     "agentAware": false,
-    "source": "pages/404.tsx"
+    "pages": [
+      {
+        "source": "pages/404.tsx",
+        "agentAware": false
+      }
+    ],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -74,6 +80,13 @@
       "bytes": 153,
       "chars": 153,
       "tokens": 38
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 706,
+      "chars": 700,
+      "tokens": 175
     }
   ],
   "ora": {
@@ -168,7 +181,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "pages/404.tsx exists but doesn't point agents anywhere — an agent hitting a 404 needs to know why (the URL doesn’t exist; retrying won’t help) and how to continue. Add links to your llms.txt and /.well-known/ai-catalog.json plus a short list of real routes (visible text is enough; agents read the HTML). ax won’t touch your not-found page once you have one.",
+    "pages/404.tsx doesn’t point agents anywhere — an agent hitting a 404 needs to know why (the URL doesn’t exist; retrying won’t help) and how to continue. Add `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` to it so agents can hop to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. The tag is invisible to human visitors, and your page stays yours — ax never edits it.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/pages-bare/twins.golden/404.md b/fixtures/pages-bare/twins.golden/404.md
new file mode 100644
index 0000000..1697faa
--- /dev/null
+++ b/fixtures/pages-bare/twins.golden/404.md
@@ -0,0 +1,22 @@
+---
+title: "Page not found — pages-bare"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://pages-bare-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/)
+- [/about](/about)
diff --git a/fixtures/pages-mcp/report.golden.json b/fixtures/pages-mcp/report.golden.json
index d7164f2..837c652 100644
--- a/fixtures/pages-mcp/report.golden.json
+++ b/fixtures/pages-mcp/report.golden.json
@@ -34,7 +34,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -92,6 +94,13 @@
       "bytes": 594,
       "chars": 594,
       "tokens": 149
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 810,
+      "chars": 802,
+      "tokens": 201
     }
   ],
   "ora": {
@@ -190,7 +199,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No pages/404.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No pages/404.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/pages-mcp/twins.golden/404.md b/fixtures/pages-mcp/twins.golden/404.md
new file mode 100644
index 0000000..46cced5
--- /dev/null
+++ b/fixtures/pages-mcp/twins.golden/404.md
@@ -0,0 +1,22 @@
+---
+title: "Page not found — pages-mcp"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://pages-mcp-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+- [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json) — the MCP server card (connection + capabilities)
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/pages-webmcp-declarative/report.golden.json b/fixtures/pages-webmcp-declarative/report.golden.json
index 79e43de..744f7f7 100644
--- a/fixtures/pages-webmcp-declarative/report.golden.json
+++ b/fixtures/pages-webmcp-declarative/report.golden.json
@@ -24,7 +24,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -75,6 +77,13 @@
       "bytes": 656,
       "chars": 654,
       "tokens": 164
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 703,
+      "chars": 697,
+      "tokens": 174
     }
   ],
   "ora": {
@@ -168,7 +177,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No pages/404.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No pages/404.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/pages-webmcp-declarative/twins.golden/404.md b/fixtures/pages-webmcp-declarative/twins.golden/404.md
new file mode 100644
index 0000000..03ddb13
--- /dev/null
+++ b/fixtures/pages-webmcp-declarative/twins.golden/404.md
@@ -0,0 +1,21 @@
+---
+title: "Page not found — pages-webmcp-declarative"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://pages-webmcp-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/)
diff --git a/fixtures/webmcp-declarative/report.golden.json b/fixtures/webmcp-declarative/report.golden.json
index 8a44791..d666487 100644
--- a/fixtures/webmcp-declarative/report.golden.json
+++ b/fixtures/webmcp-declarative/report.golden.json
@@ -24,7 +24,9 @@
   },
   "agent404": {
     "notFoundPresent": false,
-    "agentAware": false
+    "agentAware": false,
+    "pages": [],
+    "markdownGuide": "public/404.md"
   },
   "middleware": {
     "present": false,
@@ -75,6 +77,13 @@
       "bytes": 668,
       "chars": 666,
       "tokens": 167
+    },
+    {
+      "artifact": "404.md",
+      "path": "public/404.md",
+      "bytes": 703,
+      "chars": 697,
+      "tokens": 174
     }
   ],
   "ora": {
@@ -168,7 +177,7 @@
     "No robots.txt found — add one (app/robots.ts or public/robots.txt) that explicitly Allows the reputable AI agents you want to reach, scoped to specific User-agent groups (never \"User-agent: *\"), plus a \"Sitemap:\" line. Note: Next's MetadataRoute.Robots (app/robots.ts) has no field for the \"Agentmap:\" catalog pointer — put that line in a static public/robots.txt. Set scaffoldRobots: true in ax.config to have one written for you.",
     "No agents.md found — consider adding one (public/agents.md) with when-to-use / when-NOT-to-use guidance for agents. ax won't write its content for you; the companion skill can help author it from your repo.",
     "No JSON-LD structured data found in your layouts/pages — structured data is how registries and agents disambiguate and rank your site. Add an Organization block in your root layout <head> (<script type=\"application/ld+json\">) with a \"sameAs\" array linking your LinkedIn/GitHub/npm/social profiles (the entity-disambiguation signal registries value), and at least one more schema.org @type beyond Organization — SoftwareApplication or Product for an app/API, or a FAQPage — since covering more types helps registries understand your site more fully. JSON-LD pairs with an llms.txt: llms.txt tells agents what your site is for, JSON-LD identifies it as an entity registries can rank — add both, not one alone. ax won’t author the block (the fields are judgment content); the companion skill can help draft it from your repo.",
-    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add one that tells agents why the 404 happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a build-time route manifest) written for you.",
+    "No app/not-found.tsx found — agents that hit a missing URL get Next.js’s bare default 404, a dead end that makes them give up or guess. Add a standard 404 page in your own design system (a clear “page not found” and a way back home), and include `<link rel=\"alternate\" type=\"text/markdown\" href=\"/404.md\" />` so agents can hop from it to /404.md — the generated wayfinding guide (real routes + discovery links) this build writes. Rendered in the page’s JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.",
     "Serve agents the generated markdown automatically: First run `npx ax manifest` (and wire it as the \"prebuild\" script so it stays fresh — `middleware.ts` is compiled during `next build`, so the manifest must exist before the build starts). Then: add `import { withAx } from '@ora-ai/ax/middleware';` and `import { axManifest } from './ax-manifest';`, create middleware.ts with `export default withAx({ manifest: axManifest });`, and export the matcher literal `export const config = { matcher: ['/((?!_next|api|.*\\\\..*|favicon|robots|health|status).*)'] };`. The middleware rewrites a request to its markdown twin only when the manifest lists one, never touches gated paths, and answers unknown URLs from detected agents with a 200 markdown wayfinding body — it composes with (never replaces) your existing middleware, and keeps your own gating (UA filters, bot walls) from ever blocking the published discovery artifacts."
   ]
 }
diff --git a/fixtures/webmcp-declarative/twins.golden/404.md b/fixtures/webmcp-declarative/twins.golden/404.md
new file mode 100644
index 0000000..0b8ba74
--- /dev/null
+++ b/fixtures/webmcp-declarative/twins.golden/404.md
@@ -0,0 +1,21 @@
+---
+title: "Page not found — webmcp-declarative"
+description: "Where to continue when a URL on this site does not exist: discovery links and real routes."
+canonical_url: https://webmcp-declarative-fixture.example.com/404.md
+last_updated: <last_updated>
+generated-by: "@ora-ai/ax"
+---
+
+# Page not found
+
+The URL you requested does not exist on this site. It may have moved, or it may never have existed —
+requesting it again will keep returning this response. Do not retry; start from the links
+below instead.
+
+## Start here
+
+- [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) — machine-readable catalog of everything this site offers agents
+
+## Pages that do exist
+
+- [/](/)
diff --git a/packages/ax/src/agent-404.ts b/packages/ax/src/agent-404.ts
index f3ead92..b9f9e87 100644
--- a/packages/ax/src/agent-404.ts
+++ b/packages/ax/src/agent-404.ts
@@ -1,174 +1,154 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 
-import { catalogServedPath } from './discovery.js';
+import { isGeneratedMarkdown, renderFrontmatter } from './markdown-artifact.js';
+import type { ServingManifestData } from './manifest.js';
+import { renderWayfinding } from './middleware/wayfinding.js';
 import { buildRouterModel, type RouterModel } from './router-model.js';
+import { absoluteOrServedUrl, servedPath } from './site-url.js';
+import { walkFiles } from './walk-files.js';
 
 // Agent-aware 404. When an AI agent fetches a URL that doesn't exist, a default 404 page is a
 // dead end: the agent either gives up or hallucinates a next step. Mintlify's crawl benchmark
 // found that a single llms.txt link on error responses eliminates most agent 404 dead-ends, and
-// Vercel's agent-readability guidance recommends signposting llms.txt from every response. This
-// module applies that to the Next.js 404 path:
+// Vercel's agent-readability guidance recommends signposting llms.txt from every response.
 //
-//   - Detect `app/not-found.*`; when present, check (textually) whether it carries any agent
-//     signposts (llms.txt / ai-catalog); recommend adding them when it doesn't.
-//   - Opt-in (`scaffoldAgent404: true`): scaffold an agent-aware `app/not-found.tsx` ONCE (the
-//     file is the user's — never overwritten), importing a small data module
-//     (`app/not-found-agent-data.*`) that IS regenerated on every run with the app's current
-//     static route list and discovery links. The route manifest is the part only a build-time
-//     tool can supply: at runtime nothing knows the route table, but the source tree does.
+// The division of labor here keeps the two audiences' surfaces apart. The human-visible 404 page
+// is the site owner's design domain — ax never writes or scaffolds one. ax's contribution is the
+// machine artifact: a generated `public/404.md` (the "404 wayfinding guide" — discovery links plus
+// the routes that do exist, rendered by the same `renderWayfinding` the negotiation middleware
+// serves, so the two channels can never disagree), plus a detect-and-recommend pass asking the
+// site's own 404 page(s) to carry one `<link rel="alternate" type="text/markdown">` tag pointing
+// at it. The tag is invisible to human visitors; an agent that fetched the HTML 404 follows it to
+// the markdown guide in one hop.
 //
-// The scaffolded page explains to agents why the 404 happened (the URL doesn't exist — don't
-// retry), and how to continue (the site's discovery artifacts + real routes), both as visible
-// text an agent reading HTML will parse and as a schema.org ItemList in JSON-LD.
-//
-// The 404 convention differs by router: the App Router's is `app/not-found.*`, the Pages Router's
-// is `pages/404.*`. The component and its regenerated data module are otherwise identical, so only
-// the target directory and file name change — resolved once from the primary router.
-
-/** Cap on routes embedded in the data module — a navigation aid, not a sitemap replacement. */
-const MAX_ROUTES = 50;
+// Detection is granular on purpose. The App Router's `not-found.tsx` is per-segment: a
+// `notFound()` thrown inside `app/docs/[slug]/page.tsx` renders the *nearest* `not-found` file
+// (e.g. `app/docs/not-found.tsx`), bypassing the root one — and those data-driven misses on
+// dynamic routes are exactly the ones the middleware structurally can't answer (the URL matches a
+// route pattern, so whether it exists is only knowable at request time). So the detector scans
+// every `app/**/not-found.*` plus the Pages Router's root `pages/404.*`, and each file is asked to
+// carry the link.
 
-/** Base name (sans extension) of the regenerated data module the scaffolded page imports. */
-const DATA_MODULE_BASE = 'not-found-agent-data';
-
-/** Signals that an existing not-found page already points agents somewhere useful. */
-const AGENT_SIGNPOST_RE = /llms\.txt|ai-catalog|agentGuidance/;
-
-/** Where the 404 page lives and what it's named, per router convention. */
-interface NotFoundTarget {
-  /** The router directory the 404 page and its data module live in. */
-  dir: string;
-  /** Existing 404-page file names to detect, across the extensions that render one. */
-  detectNames: string[];
-  /** Base name (sans extension) of the page ax scaffolds. */
-  scaffoldBase: string;
-}
+/** The 404 wayfinding guide's URL pathname (basePath-prefixed at serve time). */
+export const NOT_FOUND_MD_PATHNAME = '/404.md';
 
 /**
- * The 404 target for the primary router: `app/not-found.*` for an App Router app, `pages/404.*` for
- * a Pages Router app. Undefined when the project has neither router.
+ * Signals that a 404 page already points agents onward: the wayfinding-guide link this module asks
+ * for, or direct signposts (llms.txt / the AI Catalog) a hand-built page may carry instead.
  */
-function notFoundTarget(router: RouterModel): NotFoundTarget | undefined {
-  if (router.primary === 'app' && router.appDir) {
-    return {
-      dir: router.appDir,
-      detectNames: ['not-found.tsx', 'not-found.jsx', 'not-found.js'],
-      scaffoldBase: 'not-found',
-    };
-  }
-  if (router.primary === 'pages' && router.pagesDir) {
-    return {
-      dir: router.pagesDir,
-      detectNames: ['404.tsx', '404.jsx', '404.js'],
-      scaffoldBase: '404',
-    };
-  }
-  return undefined;
-}
+const AGENT_SIGNPOST_RE = /404\.md|llms\.txt|ai-catalog/;
+
+/** App Router 404 file names — valid at the root and in any route segment. */
+const APP_NOT_FOUND_NAMES: ReadonlySet<string> = new Set([
+  'not-found.tsx',
+  'not-found.jsx',
+  'not-found.js',
+]);
+
+/** Pages Router 404 file names — root-level only (that router has no per-segment 404). */
+const PAGES_404_NAMES = ['404.tsx', '404.jsx', '404.js'];
 
 export interface Agent404Options {
   cwd: string;
-  /** `ax.config` `scaffoldAgent404`, resolved. Opt-in — defaults to `false`. */
-  scaffold: boolean;
-  /** `next.config` `basePath`, or `''` if unset — discovery links are served under it. */
+  /** `next.config` `basePath`, or `''` if unset — the recommended link href is served under it. */
   basePath: string;
-  /** Whether an llms.txt source was detected this run (drives which links the data module lists). */
-  llmsTxtFound: boolean;
-  /** Whether a sitemap source was detected this run. */
-  sitemapFound: boolean;
-  warn: (message: string) => void;
+  /**
+   * Whether this build generates `public/404.md` (markdownTwins on, a router present). Off, the
+   * recommendations can't ask for a link to a file that won't exist, so they ask to re-enable the
+   * feature instead.
+   */
+  notFoundMdPlanned: boolean;
   recommend: (message: string) => void;
   /** The shared router model. Built from `cwd` when omitted, so the detector runs standalone. */
   router?: RouterModel;
 }
 
+/** One detected 404 page and whether it signposts agents. */
+export interface Detected404Page {
+  /** Source path relative to the project root. */
+  source: string;
+  /** Whether the page links agents onward (`/404.md`, llms.txt, or the AI Catalog). */
+  agentAware: boolean;
+}
+
 export interface Agent404Result {
-  /** Whether an `app/not-found.*` exists (after any scaffolding this run performed). */
+  /** Whether any 404 page exists (root or segment-level, either router). */
   notFoundPresent: boolean;
-  /** The not-found source path relative to the project root, if present. */
-  source?: string;
-  /** Whether the page carries agent signposts (llms.txt / ai-catalog links). */
+  /** True only when every detected 404 page signposts agents; false when none exists. */
   agentAware: boolean;
-  /** Path of the not-found page scaffolded on *this* run, if any. */
-  scaffoldedPath?: string;
-  /** Path of the regenerated route-manifest data module, if written this run. */
-  dataModulePath?: string;
+  /** Every detected 404 page: `app/**` `not-found.*` (root and per-segment) plus `pages/404.*`. */
+  pages: Detected404Page[];
 }
 
 /**
- * Detect-and-recommend (and, opted in, scaffold) for an agent-aware 404 page. Never overwrites the
- * user's `not-found.*`; only the generated data module is rewritten on every run, and only once a
- * scaffolded (or signpost-aware) page exists to import it. Any filesystem error warns rather than
- * throws — a helpful extra file must never be why a build breaks.
+ * Detect-and-recommend for the site's 404 pages. Read-only by design: the human-visible 404 is the
+ * user's page in the user's design system, so ax only ever asks — for a page where none exists, or
+ * for the one alternate-link tag where a page doesn't carry it. Never throws; an unreadable file
+ * just reads as not agent-aware.
  */
-export function manageAgent404(options: Agent404Options): Agent404Result {
-  const { cwd, warn, recommend } = options;
+export function detectAgent404(options: Agent404Options): Agent404Result {
+  const { cwd, recommend } = options;
   const router = options.router ?? buildRouterModel(cwd);
-  const target = notFoundTarget(router);
-  if (!target) return { notFoundPresent: false, agentAware: false };
-
-  const notFoundFile = target.detectNames
-    .map((name) => join(target.dir, name))
-    .find((path) => existsSync(path));
 
-  if (notFoundFile) {
-    const source = relative(cwd, notFoundFile);
-    const agentAware = fileMentionsSignposts(notFoundFile);
+  const files: string[] = [];
+  if (router.appDir !== undefined) {
+    for (const file of walkFiles(router.appDir, (name) => APP_NOT_FOUND_NAMES.has(name))) {
+      files.push(file.absolutePath);
+    }
+  }
+  if (router.pagesDir !== undefined) {
+    const pagesDir = router.pagesDir;
+    for (const name of PAGES_404_NAMES) {
+      const path = join(pagesDir, name);
+      if (existsSync(path)) files.push(path);
+    }
+  }
 
-    if (agentAware) {
-      // A previously-scaffolded (or hand-built) agent-aware page: keep its route manifest fresh
-      // when it imports our data module and scaffolding is (still) opted in.
-      const dataModulePath =
-        options.scaffold && fileImportsDataModule(notFoundFile)
-          ? writeDataModule(target.dir, options, router)
+  const pages: Detected404Page[] = files
+    .map((file) => ({ source: relative(cwd, file), agentAware: fileMentionsSignposts(file) }))
+    .sort((a, b) => a.source.localeCompare(b.source));
+
+  const guidePath = servedPath(options.basePath, NOT_FOUND_MD_PATHNAME);
+  const linkTag = `<link rel="alternate" type="text/markdown" href="${guidePath}" />`;
+  const guideClause = options.notFoundMdPlanned
+    ? `${guidePath} — the generated wayfinding guide (real routes + discovery links) this build writes`
+    : `${guidePath}, the generated wayfinding guide — currently NOT written because markdownTwins ` +
+      'is disabled in ax.config; set it back to true first';
+
+  if (pages.length === 0) {
+    // Which page to create follows the primary router's convention; the design is the user's.
+    const conventionPath =
+      router.primary === 'app' && router.appDir !== undefined
+        ? `${relative(cwd, router.appDir)}/not-found.tsx`
+        : router.primary === 'pages' && router.pagesDir !== undefined
+          ? `${relative(cwd, router.pagesDir)}/404.tsx`
           : undefined;
-      return {
-        notFoundPresent: true,
-        source,
-        agentAware: true,
-        ...(dataModulePath !== undefined ? { dataModulePath } : {}),
-      };
+    if (conventionPath !== undefined) {
+      recommend(
+        `No ${conventionPath} found — agents that hit a missing URL get Next.js’s bare default ` +
+          '404, a dead end that makes them give up or guess. Add a standard 404 page in your own ' +
+          'design system (a clear “page not found” and a way back home), and include ' +
+          `\`${linkTag}\` so agents can hop from it to ${guideClause}. Rendered in the page’s ` +
+          'JSX, React hoists the tag into <head> (App Router); use next/head in the Pages Router.',
+      );
     }
-
-    recommend(
-      `${source} exists but doesn't point agents anywhere — an agent hitting a 404 needs to know ` +
-        'why (the URL doesn’t exist; retrying won’t help) and how to continue. Add links to your ' +
-        `llms.txt and ${catalogServedPath(options.basePath)} plus a short list of real routes ` +
-        '(visible text is enough; agents read the HTML). ax won’t touch your not-found ' +
-        'page once you have one.',
-    );
-    return { notFoundPresent: true, source, agentAware: false };
+    return { notFoundPresent: false, agentAware: false, pages };
   }
 
-  if (!options.scaffold) {
-    const conventionPath = `${relative(cwd, target.dir)}/${target.scaffoldBase}.tsx`;
+  const unlinked = pages.filter((page) => !page.agentAware);
+  if (unlinked.length > 0) {
+    const list = unlinked.map((page) => page.source).join(', ');
+    const plural = unlinked.length !== 1;
     recommend(
-      `No ${conventionPath} found — agents that hit a missing URL get Next.js’s bare default 404, ` +
-        'a dead end that makes them give up or guess. Add one that tells agents why the 404 ' +
-        'happened and how to continue (links to llms.txt, the ai-catalog, and your real routes), ' +
-        'or set scaffoldAgent404: true in ax.config to have an agent-aware page (plus a ' +
-        'build-time route manifest) written for you.',
+      `${list} do${plural ? '' : 'es'}n’t point agents anywhere — an agent hitting a 404 needs ` +
+        'to know why (the URL doesn’t exist; retrying won’t help) and how to continue. Add ' +
+        `\`${linkTag}\` to ${plural ? 'each page' : 'it'} so agents can hop to ${guideClause}. ` +
+        'The tag is invisible to human visitors, and your page stays yours — ax never edits it.',
     );
-    return { notFoundPresent: false, agentAware: false };
   }
 
-  const scaffolded = scaffoldNotFound(cwd, target, options);
-  if (!scaffolded) return { notFoundPresent: false, agentAware: false };
-
-  const dataModulePath = writeDataModule(target.dir, options, router);
-  warn(
-    `Scaffolded an agent-aware 404 page at ${relative(cwd, scaffolded)} — edit it freely (it's ` +
-      `yours; ax never overwrites it). Its imported ${DATA_MODULE_BASE} module is ` +
-      'regenerated on every build so the route list and discovery links stay fresh.',
-  );
-  return {
-    notFoundPresent: true,
-    source: relative(cwd, scaffolded),
-    agentAware: true,
-    scaffoldedPath: scaffolded,
-    ...(dataModulePath !== undefined ? { dataModulePath } : {}),
-  };
+  return { notFoundPresent: true, agentAware: unlinked.length === 0, pages };
 }
 
 function fileMentionsSignposts(path: string): boolean {
@@ -179,155 +159,96 @@ function fileMentionsSignposts(path: string): boolean {
   }
 }
 
-function fileImportsDataModule(path: string): boolean {
-  try {
-    return readFileSync(path, 'utf8').includes(DATA_MODULE_BASE);
-  } catch {
-    return false;
-  }
+export interface NotFoundMdPlan {
+  /** Full file contents (frontmatter + wayfinding body). */
+  content: string;
+  /** Served URL path, basePath-prefixed. */
+  servedPath: string;
+  /** How many routes the guide's manifest lists (the body caps what it prints). */
+  routeCount: number;
 }
 
-/** The discovery links the data module lists — only artifacts that actually exist this run. */
-function discoveryLinks(options: Agent404Options): Array<{ url: string; purpose: string }> {
-  const prefix = options.basePath === '/' ? '' : options.basePath.replace(/\/$/, '');
-  const links = [
-    {
-      url: catalogServedPath(options.basePath),
-      purpose: 'machine-readable catalog of everything this site offers agents (AI Catalog / ARD)',
-    },
-  ];
-  if (options.llmsTxtFound) {
-    links.push({
-      url: `${prefix}/llms.txt`,
-      purpose: 'what this site is for and its key pages, in plain language',
-    });
-  }
-  if (options.sitemapFound) {
-    links.push({ url: `${prefix}/sitemap.xml`, purpose: 'every public URL on this site' });
-  }
-  return links;
+export interface BuildNotFoundMdOptions {
+  /**
+   * The serving-manifest data the guide renders from. The caller overlays this run's own outputs
+   * (planned twins, the auth guide, the catalog) so the guide describes the build it ships with,
+   * not the previous one.
+   */
+  manifest: ServingManifestData;
+  siteUrl: string | undefined;
+  basePath: string;
+  siteDisplayName: string;
+  /** Injectable clock for deterministic tests; defaults to the wall clock. */
+  now?: Date;
 }
 
 /**
- * Regenerates the data module (`not-found-agent-data.{ts,js}`, beside the 404 page) with the current
- * static route list and discovery links. Generated output, clearly marked, rewritten every run — the
- * same contract as the `emit: 'route'` handlers. Routes span both routers (`router.listPageRoutes`).
+ * Builds the generated `public/404.md` — the fixed-path twin of "you hit a dead end": the same
+ * wayfinding body the negotiation middleware serves rendered without a request URL, under the
+ * standard generated-markdown frontmatter. Pure — the CLI writes it (see
+ * {@link applyNotFoundMdPlan}) after the review gate, alongside the twins and the auth guide.
  */
-function writeDataModule(
-  dir: string,
-  options: Agent404Options,
-  router: RouterModel,
-): string | undefined {
-  const useTypeScript = existsSync(join(options.cwd, 'tsconfig.json'));
-  const filePath = join(dir, `${DATA_MODULE_BASE}.${useTypeScript ? 'ts' : 'js'}`);
+export function buildNotFoundMd(options: BuildNotFoundMdOptions): NotFoundMdPlan {
+  const now = options.now ?? new Date();
+  const frontmatter = renderFrontmatter({
+    title: `Page not found — ${options.siteDisplayName}`,
+    description:
+      'Where to continue when a URL on this site does not exist: discovery links and real routes.',
+    canonicalUrl: absoluteOrServedUrl(options.siteUrl, options.basePath, NOT_FOUND_MD_PATHNAME),
+    lastUpdated: now.toISOString(),
+  });
 
-  const routes = router.listPageRoutes().slice(0, MAX_ROUTES);
-  const payload = { discovery: discoveryLinks(options), routes };
-
-  const source =
-    `// Generated by ax (scaffoldAgent404). Do not edit by hand — regenerated on every\n` +
-    `// build so the 404 page's route list and discovery links stay current.\n` +
-    `export const agentGuidance = ${JSON.stringify(payload, null, 2)}${useTypeScript ? ' as const' : ''};\n`;
+  return {
+    content: `${frontmatter}\n${renderWayfinding(options.manifest)}`,
+    servedPath: servedPath(options.basePath, NOT_FOUND_MD_PATHNAME),
+    routeCount: options.manifest.routes.length,
+  };
+}
 
-  try {
-    writeFileSync(filePath, source, 'utf8');
-  } catch (err) {
-    options.warn(
-      `Tried to write the 404 route manifest at ${filePath} but couldn't (${(err as Error).message}).`,
-    );
-    return undefined;
-  }
-  return filePath;
+export interface ApplyNotFoundMdResult {
+  /** Path written, relative to the project root, when the plan was written. */
+  written?: string;
+  /** Path deleted (a previously generated 404.md this run no longer produces). */
+  deleted?: string;
 }
 
 /**
- * Scaffolds the 404 page once into the primary router (`app/not-found.{tsx,jsx}` or
- * `pages/404.{tsx,jsx}`). Never overwrites; warns instead of throwing. The component source is
- * identical across routers — both default-export a React component that imports the data module.
+ * Writes the planned `public/404.md`, or — when there is no plan — removes a previously
+ * *generated* one (never a user-authored file: the generated-by marker is the guard, same as the
+ * twins and auth.md). Filesystem errors warn rather than throw.
  */
-function scaffoldNotFound(
+export function applyNotFoundMdPlan(
   cwd: string,
-  target: NotFoundTarget,
-  options: Agent404Options,
-): string | undefined {
-  const useTypeScript = existsSync(join(cwd, 'tsconfig.json'));
-  const filePath = join(target.dir, `${target.scaffoldBase}.${useTypeScript ? 'tsx' : 'jsx'}`);
+  plan: NotFoundMdPlan | undefined,
+  warn: (message: string) => void,
+): ApplyNotFoundMdResult {
+  const filePath = join(cwd, 'public', '404.md');
+
+  if (plan === undefined) {
+    if (!existsSync(filePath)) return {};
+    try {
+      if (!isGeneratedMarkdown(readFileSync(filePath, 'utf8'))) return {};
+      rmSync(filePath, { force: true });
+      return { deleted: relative(cwd, filePath) };
+    } catch (err) {
+      warn(`Could not remove the stale public/404.md (${(err as Error).message}).`);
+      return {};
+    }
+  }
 
   try {
-    if (existsSync(filePath)) return undefined;
-    mkdirSync(target.dir, { recursive: true });
-    writeFileSync(filePath, notFoundSource(), 'utf8');
+    if (existsSync(filePath) && !isGeneratedMarkdown(readFileSync(filePath, 'utf8'))) {
+      warn(
+        'public/404.md exists but was not generated by ax — leaving it untouched. Delete it if ' +
+          'you want the generated 404 wayfinding guide instead.',
+      );
+      return {};
+    }
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, plan.content, 'utf8');
+    return { written: relative(cwd, filePath) };
   } catch (err) {
-    options.warn(
-      `Tried to scaffold an agent-aware 404 page at ${filePath} but couldn't (${(err as Error).message}).`,
-    );
-    return undefined;
+    warn(`Could not write public/404.md (${(err as Error).message}).`);
+    return {};
   }
-  return filePath;
-}
-
-/**
- * The scaffolded page source. Valid as both `.tsx` and `.jsx` (no type annotations needed). The
- * agent guidance is ordinary visible HTML — agents read the page text — plus a schema.org
- * ItemList in JSON-LD for structured-data readers. Human visitors see a normal 404 with helpful
- * links; there is nothing to hide from either audience.
- */
-function notFoundSource(): string {
-  return `// Agent-aware 404, scaffolded by ax (scaffoldAgent404). This file is yours:
-// edit it freely, ax never overwrites it. The ./${DATA_MODULE_BASE} import IS
-// regenerated on every build (current routes + discovery links) — keep importing it and your
-// 404 page never goes stale.
-import { agentGuidance } from './${DATA_MODULE_BASE}';
-
-export default function NotFound() {
-  const itemList = {
-    '@context': 'https://schema.org',
-    '@type': 'WebPage',
-    name: 'Page not found',
-    mainEntity: {
-      '@type': 'ItemList',
-      itemListElement: agentGuidance.routes.map((route, index) => ({
-        '@type': 'ListItem',
-        position: index + 1,
-        url: route,
-      })),
-    },
-  };
-
-  return (
-    <main>
-      <h1>404 — page not found</h1>
-      <p>
-        This URL does not exist on this site. It may have moved, or it may never have existed —
-        requesting it again will keep returning 404.
-      </p>
-
-      <section aria-labelledby="agent-guidance">
-        <h2 id="agent-guidance">If you are an AI agent</h2>
-        <p>Do not retry this URL. To find what you were looking for, start from:</p>
-        <ul>
-          {agentGuidance.discovery.map((link) => (
-            <li key={link.url}>
-              <a href={link.url}>{link.url}</a> — {link.purpose}
-            </li>
-          ))}
-        </ul>
-        <h2>Pages that do exist</h2>
-        <ul>
-          {agentGuidance.routes.map((route) => (
-            <li key={route}>
-              <a href={route}>{route}</a>
-            </li>
-          ))}
-        </ul>
-      </section>
-
-      <script
-        type="application/ld+json"
-        dangerouslySetInnerHTML={{ __html: JSON.stringify(itemList) }}
-      />
-    </main>
-  );
-}
-`;
 }
diff --git a/packages/ax/src/cli.ts b/packages/ax/src/cli.ts
index bc9553f..c27958e 100644
--- a/packages/ax/src/cli.ts
+++ b/packages/ax/src/cli.ts
@@ -9,6 +9,7 @@ import {
   measureArtifact,
   measureContent,
 } from './artifact-size.js';
+import { applyNotFoundMdPlan, type ApplyNotFoundMdResult } from './agent-404.js';
 import { applyAuthMdPlan, type ApplyAuthMdResult } from './auth-md.js';
 import { AxConfigError, findExistingConfig } from './config.js';
 import { entryUrlPath } from './entries.js';
@@ -372,7 +373,18 @@ export async function runCli(argv: string[], io: CliIO = {}): Promise<number> {
   const authMdResult = generated.twinPlan.enabled
     ? applyAuthMdPlan(cwd, generated.authMdPlan, twinWarn)
     : {};
-  reportMarkdownTwinOutcome(cwd, generated, twinResult, authMdResult, reportTarget, stdout);
+  const notFoundMdResult = generated.twinPlan.enabled
+    ? applyNotFoundMdPlan(cwd, generated.notFoundMdPlan, twinWarn)
+    : {};
+  reportMarkdownTwinOutcome(
+    cwd,
+    generated,
+    twinResult,
+    authMdResult,
+    notFoundMdResult,
+    reportTarget,
+    stdout,
+  );
 
   // Token-aware sizes: report each artifact this build wrote in bytes *and* estimated tokens
   // (chars ÷ 4), since tokens — not disk size — are what constrain the agent that later reads it.
@@ -393,6 +405,11 @@ export async function runCli(argv: string[], io: CliIO = {}): Promise<number> {
   if (authMdResult.written !== undefined && generated.authMdPlan !== undefined) {
     sizes.push(measureContent(generated.authMdPlan.content, 'auth.md', authMdResult.written));
   }
+  if (notFoundMdResult.written !== undefined && generated.notFoundMdPlan !== undefined) {
+    sizes.push(
+      measureContent(generated.notFoundMdPlan.content, '404.md', notFoundMdResult.written),
+    );
+  }
   generated.report.sizes = sizes;
 
   // Recommendations print to the terminal only when no report is being written — a report run
@@ -812,6 +829,12 @@ function printExposureSummary(
         `surface${surfaceCount === 1 ? '' : 's'})`,
     );
   }
+  if (generated.notFoundMdPlan !== undefined) {
+    stdout(
+      `[ax]   • 404 wayfinding guide → ${generated.notFoundMdPlan.servedPath} (where agents ` +
+        'continue from a dead-end URL)',
+    );
+  }
 }
 
 /**
@@ -825,6 +848,7 @@ function reportMarkdownTwinOutcome(
   generated: GenerateCatalogResult,
   twinResult: ApplyTwinPlanResult,
   authMdResult: ApplyAuthMdResult,
+  notFoundMdResult: ApplyNotFoundMdResult,
   reportTarget: true | string | undefined,
   stdout: (line: string) => void,
 ): void {
@@ -837,13 +861,19 @@ function reportMarkdownTwinOutcome(
   }));
   twins.deleted = twinResult.deleted;
   if (authMdResult.written === undefined) delete twins.authMd;
+  if (notFoundMdResult.written !== undefined) {
+    generated.report.agent404.markdownGuide = notFoundMdResult.written;
+  }
 
-  // The twins and auth guide written this run are shown (with their sizes) in the consolidated file
+  // The twins and guides written this run are shown (with their sizes) in the consolidated file
   // tree the caller prints, so no "✓ wrote" summary line here. Removals and the skipped-route
   // warning stay: they aren't files that landed on disk, so the tree has no row for them.
   if (authMdResult.deleted !== undefined) {
     stdout(`[ax] ✓ removed ${authMdResult.deleted} (no gated surfaces remain)`);
   }
+  if (notFoundMdResult.deleted !== undefined) {
+    stdout(`[ax] ✓ removed ${notFoundMdResult.deleted} (no router to describe misses for)`);
+  }
   if (twinResult.deleted.length > 0) {
     stdout(
       `[ax] ✓ removed ${twinResult.deleted.length} stale markdown twin` +
diff --git a/packages/ax/src/config-schema.ts b/packages/ax/src/config-schema.ts
index 2cd9612..56423e2 100644
--- a/packages/ax/src/config-schema.ts
+++ b/packages/ax/src/config-schema.ts
@@ -79,14 +79,6 @@ export interface AxConfig {
    * happening silently on every build with zero config.
    */
   scaffoldLlmsTxt?: boolean;
-  /**
-   * Whether to scaffold an agent-aware 404 page (`app/not-found.tsx`) when none exists, plus a
-   * route-manifest data module (`app/not-found-agent-data.*`) that is regenerated on every build.
-   * The page tells agents why the 404 happened and how to continue (discovery links + the app's
-   * real routes); the not-found file itself is scaffolded once and never overwritten. **Opt-in —
-   * defaults to `false`**, same reasoning as `scaffoldLlmsTxt`.
-   */
-  scaffoldAgent404?: boolean;
   /**
    * Whether to manage `public/robots.txt`. When on, ax appends the discovery pointers it is
    * uniquely placed to know — a `Sitemap:` line (only when a sitemap actually exists) and an
@@ -109,7 +101,8 @@ export interface AxConfig {
   /**
    * Whether to generate markdown twins — per-page markdown files in `public/` (route `/docs` →
    * `/docs.md`) derived from markdown sources (`page.mdx`) or the build's prerendered HTML, plus a
-   * `public/auth.md` guide when gated surfaces exist. **Default `true`**, unlike the scaffolds:
+   * `public/auth.md` guide when gated surfaces exist and a `public/404.md` wayfinding guide (where
+   * an agent continues from a dead-end URL). **Default `true`**, unlike the scaffolds:
    * twins are *generated artifacts* (regenerated every build, marked generated-by, never yours to
    * edit), not one-time source-tree scaffolds, and the first run that would write them is confirmed
    * at the review-before-publish gate, so nothing ships silently. Set `false` to opt out entirely.
@@ -221,7 +214,6 @@ export const axConfigSchema: Record<string, unknown> = {
     },
     emit: { type: 'string', enum: ['static', 'route'] },
     scaffoldLlmsTxt: { type: 'boolean' },
-    scaffoldAgent404: { type: 'boolean' },
     scaffoldRobots: { type: 'boolean' },
     scaffoldJsonLd: { type: 'boolean' },
     markdownTwins: { type: 'boolean' },
diff --git a/packages/ax/src/config.ts b/packages/ax/src/config.ts
index c5affdf..4f0e016 100644
--- a/packages/ax/src/config.ts
+++ b/packages/ax/src/config.ts
@@ -105,7 +105,6 @@ function withDefaults(config: AxConfig): ResolvedAxConfig {
     siteUrl: config.siteUrl,
     emit: config.emit ?? 'static',
     scaffoldLlmsTxt: config.scaffoldLlmsTxt ?? false,
-    scaffoldAgent404: config.scaffoldAgent404 ?? false,
     scaffoldRobots: config.scaffoldRobots ?? false,
     scaffoldJsonLd: config.scaffoldJsonLd ?? false,
     // Default ON, unlike the scaffolds: twins are regenerated build artifacts (never user-owned
diff --git a/packages/ax/src/generate.ts b/packages/ax/src/generate.ts
index 4f9f0ec..6e61538 100644
--- a/packages/ax/src/generate.ts
+++ b/packages/ax/src/generate.ts
@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 
-import { manageAgent404 } from './agent-404.js';
+import { buildNotFoundMd, detectAgent404, type NotFoundMdPlan } from './agent-404.js';
 import { buildAuthMd, type AuthMdPlan } from './auth-md.js';
 import { loadAxConfig } from './config.js';
 import { detectAgentsMd } from './detect-agents-md.js';
@@ -24,6 +24,7 @@ import { buildDiscoveryRecommendations } from './discovery.js';
 import { applyEntryOverrides, entryUrlPath, sanitizeOverrideAuth } from './entries.js';
 import { defaultIsGated, resolveGating, type GateTarget, type IsGated } from './gating.js';
 import { loadProjectEnv } from './load-project-env.js';
+import { buildServingManifest } from './manifest.js';
 import { buildMarkdownAlternateRecommendation } from './markdown-alternate.js';
 import { planMarkdownTwins, type MarkdownTwinPlan } from './markdown-twins.js';
 import { buildMiddlewareWiringInstruction, detectMiddleware } from './middleware-wiring.js';
@@ -96,6 +97,12 @@ export interface GenerateCatalogResult {
   twinPlan: MarkdownTwinPlan;
   /** The generated `/auth.md`, when gated surfaces exist. Written by the CLI with the twins. */
   authMdPlan?: AuthMdPlan;
+  /**
+   * The generated `/404.md` wayfinding guide (same body the negotiation middleware serves for
+   * unknown URLs). Written by the CLI with the twins; absent when `markdownTwins` is off or the
+   * project has no router.
+   */
+  notFoundMdPlan?: NotFoundMdPlan;
 }
 
 /** Presence-shape shared by the detect-and-recommend detectors (`{found, source?}`). */
@@ -697,16 +704,46 @@ export async function generateCatalog(
     recommend(message);
   }
 
-  // Agent-aware 404: detect-and-recommend, or (opted in) scaffold a not-found page whose
-  // route-manifest data module is regenerated every build. Runs after the artifact detectors so
-  // its discovery links only reference what actually exists.
-  const agent404 = manageAgent404({
+  // The generated /404.md wayfinding guide: the same body the negotiation middleware serves for
+  // unknown URLs, as a fixed-path artifact the site's own 404 page links via
+  // <link rel="alternate" type="text/markdown">. Rendered from serving-manifest data with this
+  // run's own outputs overlaid (planned twins, the auth guide, the catalog and cards written
+  // alongside), so the guide describes the build it ships with, not the previous one. Gated on
+  // markdownTwins like auth.md — the same class of regenerated public markdown artifact — and
+  // skipped for a project with no router (nothing is a page miss there).
+  let notFoundMdPlan: NotFoundMdPlan | undefined;
+  if (config.markdownTwins && router.routers.length > 0) {
+    const notFoundManifest = buildServingManifest({ cwd, router, isGated: gating, basePath });
+    notFoundManifest.artifacts.aiCatalog ??= servedPath(basePath, '/.well-known/ai-catalog.json');
+    if (llmsTxtResult.found) {
+      notFoundManifest.artifacts.llmsTxt ??= servedPath(basePath, '/llms.txt');
+    }
+    if (authMdPlan !== undefined) notFoundManifest.artifacts.authMd ??= authMdPlan.servedPath;
+    if (serverCardPlan !== undefined) {
+      notFoundManifest.artifacts.mcpServerCard ??= servedPath(
+        basePath,
+        '/.well-known/mcp/server-card.json',
+      );
+    }
+    for (const twin of twinPlan.writes) {
+      notFoundManifest.markdownTwins[servedPath(basePath, twin.route)] = twin.servedPath;
+    }
+    notFoundMdPlan = buildNotFoundMd({
+      manifest: notFoundManifest,
+      siteUrl,
+      basePath,
+      siteDisplayName: site.displayName,
+    });
+  }
+
+  // Agent-aware 404: detect-and-recommend only. The human-visible 404 page (root and per-segment
+  // not-found files alike) is the user's design domain — ax asks each detected page to carry the
+  // one alternate-link tag pointing at the /404.md guide, and asks for a standard 404 page when
+  // none exists at all.
+  const agent404 = detectAgent404({
     cwd,
-    scaffold: config.scaffoldAgent404,
     basePath,
-    llmsTxtFound: llmsTxtResult.found,
-    sitemapFound: sitemap.found,
-    warn,
+    notFoundMdPlanned: notFoundMdPlan !== undefined,
     recommend,
     router,
   });
@@ -772,7 +809,8 @@ export async function generateCatalog(
     agent404: {
       notFoundPresent: agent404.notFoundPresent,
       agentAware: agent404.agentAware,
-      ...(agent404.source !== undefined ? { source: agent404.source } : {}),
+      pages: agent404.pages,
+      // `markdownGuide` is reconciled by the CLI once /404.md is on disk, like markdownTwins.
     },
     middleware: {
       present: middlewareStatus.present,
@@ -892,6 +930,7 @@ export async function generateCatalog(
     reportTarget: config.report,
     twinPlan,
     ...(authMdPlan !== undefined ? { authMdPlan } : {}),
+    ...(notFoundMdPlan !== undefined ? { notFoundMdPlan } : {}),
     ...(serverCardPlan ? { serverCardPlan } : {}),
     ...(llmsTxtResult.scaffoldedBody !== undefined
       ? { scaffoldedLlmsTxtBody: llmsTxtResult.scaffoldedBody }
diff --git a/packages/ax/src/index.ts b/packages/ax/src/index.ts
index 507d4c7..6316b7a 100644
--- a/packages/ax/src/index.ts
+++ b/packages/ax/src/index.ts
@@ -271,7 +271,18 @@ export {
   type WebMcpToolSite,
 } from './detect-webmcp.js';
 
-export { manageAgent404, type Agent404Options, type Agent404Result } from './agent-404.js';
+export {
+  applyNotFoundMdPlan,
+  buildNotFoundMd,
+  detectAgent404,
+  NOT_FOUND_MD_PATHNAME,
+  type Agent404Options,
+  type Agent404Result,
+  type ApplyNotFoundMdResult,
+  type BuildNotFoundMdOptions,
+  type Detected404Page,
+  type NotFoundMdPlan,
+} from './agent-404.js';
 
 export {
   applyMarkdownHeaders,
diff --git a/packages/ax/src/init-config.ts b/packages/ax/src/init-config.ts
index 9c2534d..60dc5a0 100644
--- a/packages/ax/src/init-config.ts
+++ b/packages/ax/src/init-config.ts
@@ -28,7 +28,6 @@ export interface InitAnswers {
   scaffoldLlmsTxt: boolean;
   scaffoldJsonLd: boolean;
   scaffoldRobots: boolean;
-  scaffoldAgent404: boolean;
   markdownTwins: boolean;
   report: boolean;
   /**
@@ -109,14 +108,9 @@ export function renderAxConfig(answers: InitAnswers, target: ConfigFileTarget):
       String(answers.scaffoldRobots),
     ),
     field(
-      'Scaffold an agent-aware 404 that tells agents why a page is missing and lists your real ' +
-        'routes and discovery artifacts, so a wrong URL is a signpost instead of a dead end.',
-      'scaffoldAgent404',
-      String(answers.scaffoldAgent404),
-    ),
-    field(
-      'Generate markdown twins of your prerendered pages (route /docs → /docs.md) plus /auth.md ' +
-        'when surfaces are gated. Regenerated every build — generated output, never yours to edit.',
+      'Generate markdown twins of your prerendered pages (route /docs → /docs.md), /auth.md when ' +
+        'surfaces are gated, and the /404.md wayfinding guide lost agents continue from. ' +
+        'Regenerated every build — generated output, never yours to edit.',
       'markdownTwins',
       String(answers.markdownTwins),
     ),
diff --git a/packages/ax/src/init.ts b/packages/ax/src/init.ts
index c807c0c..397af69 100644
--- a/packages/ax/src/init.ts
+++ b/packages/ax/src/init.ts
@@ -628,12 +628,11 @@ function writeGatingCards(
  * `wireManifest`, which isn't a config field at all) so the mapping in {@link collectInteractive} is
  * one explicit switch rather than a name-matching convention.
  */
-type SetupOptionValue =
-  'llmsTxt' | 'jsonLd' | 'robots' | 'agent404' | 'markdownTwins' | 'report' | 'manifest';
+type SetupOptionValue = 'llmsTxt' | 'jsonLd' | 'robots' | 'markdownTwins' | 'report' | 'manifest';
 
 /**
- * The seven setup choices, each pre-selected — replaces what used to be seven sequential y/n
- * confirms. One question reads faster than seven, and a list makes the *shape* of what's on offer
+ * The six setup choices, each pre-selected — replaces what used to be sequential y/n
+ * confirms. One question reads faster than six, and a list makes the *shape* of what's on offer
  * visible at a glance instead of trickling out one item at a time. Labels stay short; a clause is
  * added only where the name alone doesn't say what the user would be giving up by deselecting it,
  * and that clause states the value to the user/agents, not the mechanism.
@@ -656,14 +655,9 @@ const SETUP_OPTIONS: Array<{ value: SetupOptionValue; label: string; selected: t
       'Add robots.txt pointers + AI-crawler rules — so agent crawlers find (and may read) your artifacts',
     selected: true,
   },
-  {
-    value: 'agent404',
-    label: 'Scaffold an agent-aware 404 page — steers lost agents back',
-    selected: true,
-  },
   {
     value: 'markdownTwins',
-    label: 'Markdown twins on every build (/docs → /docs.md)',
+    label: 'Markdown twins on every build (/docs → /docs.md, plus a /404.md wayfinding guide)',
     selected: true,
   },
   {
@@ -741,7 +735,6 @@ async function collectInteractive(
       scaffoldLlmsTxt: setupSelected('llmsTxt'),
       scaffoldJsonLd: setupSelected('jsonLd'),
       scaffoldRobots: setupSelected('robots'),
-      scaffoldAgent404: setupSelected('agent404'),
       // Twin *intent* lands in config; generation happens at build (twins need the prerendered output).
       markdownTwins: setupSelected('markdownTwins'),
       report: setupSelected('report'),
@@ -971,7 +964,6 @@ export async function runInit(argv: string[], io: InitIO = {}): Promise<number>
       scaffoldLlmsTxt: true,
       scaffoldJsonLd: true,
       scaffoldRobots: true,
-      scaffoldAgent404: true,
       markdownTwins: true,
       report: true,
     };
diff --git a/packages/ax/src/manifest.ts b/packages/ax/src/manifest.ts
index f26c0f6..fe63898 100644
--- a/packages/ax/src/manifest.ts
+++ b/packages/ax/src/manifest.ts
@@ -54,6 +54,8 @@ export interface ServingManifestData {
     mcpServerCards?: string[];
     llmsTxt?: string;
     authMd?: string;
+    /** The generated 404 wayfinding guide (`/404.md`), when present. */
+    notFoundMd?: string;
     openapi?: string;
   };
 }
@@ -92,6 +94,7 @@ export function buildServingManifest(options: BuildServingManifestOptions): Serv
       const segments = pathSegments(file.relativeDir);
       const name = base.slice(0, -'.md'.length);
       if (segments.length === 0 && name === 'auth') continue; // the auth guide, not a route twin
+      if (segments.length === 0 && name === '404') continue; // the 404 wayfinding guide, not a route twin
       const route =
         name === 'index' && segments.length === 0
           ? '/'
@@ -166,6 +169,9 @@ export function buildServingManifest(options: BuildServingManifestOptions): Serv
   if (existsSync(join(cwd, 'public', 'auth.md'))) {
     artifacts.authMd = servedPath(basePath, '/auth.md');
   }
+  if (existsSync(join(cwd, 'public', '404.md'))) {
+    artifacts.notFoundMd = servedPath(basePath, '/404.md');
+  }
   if (existsSync(join(cwd, 'public', 'openapi.json'))) {
     artifacts.openapi = servedPath(basePath, '/openapi.json');
   }
diff --git a/packages/ax/src/middleware/index.ts b/packages/ax/src/middleware/index.ts
index 7a308b5..84433c5 100644
--- a/packages/ax/src/middleware/index.ts
+++ b/packages/ax/src/middleware/index.ts
@@ -83,7 +83,8 @@ export interface WithAxOptions {
  * the build never lists a gated route's twin, and artifacts aren't gateable surfaces).
  */
 function discoveryPaths(manifest: AxServingManifest): ReadonlySet<string> {
-  const { aiCatalog, mcpServerCard, mcpServerCards, llmsTxt, authMd, openapi } = manifest.artifacts;
+  const { aiCatalog, mcpServerCard, mcpServerCards, llmsTxt, authMd, notFoundMd, openapi } =
+    manifest.artifacts;
   return new Set(
     [
       aiCatalog,
@@ -91,6 +92,7 @@ function discoveryPaths(manifest: AxServingManifest): ReadonlySet<string> {
       ...(mcpServerCards ?? []),
       llmsTxt,
       authMd,
+      notFoundMd,
       openapi,
       ...Object.values(manifest.markdownTwins),
     ].filter((path): path is string => typeof path === 'string'),
diff --git a/packages/ax/src/middleware/manifest-shape.ts b/packages/ax/src/middleware/manifest-shape.ts
index c78dff8..667a930 100644
--- a/packages/ax/src/middleware/manifest-shape.ts
+++ b/packages/ax/src/middleware/manifest-shape.ts
@@ -30,6 +30,7 @@ export interface AxServingManifest {
     readonly mcpServerCards?: readonly string[];
     readonly llmsTxt?: string;
     readonly authMd?: string;
+    readonly notFoundMd?: string;
     readonly openapi?: string;
   };
 }
diff --git a/packages/ax/src/middleware/wayfinding.ts b/packages/ax/src/middleware/wayfinding.ts
index cbf0932..88ce5ce 100644
--- a/packages/ax/src/middleware/wayfinding.ts
+++ b/packages/ax/src/middleware/wayfinding.ts
@@ -4,6 +4,11 @@
 // discovery artifacts that actually exist, straight from the build-generated manifest instead of a
 // generic template. Plain clients never see this: the middleware only serves it to detected
 // agents / markdown-Accept requesters, so browsers keep the app's honest 404.
+//
+// The same renderer also produces the body of the generated `public/404.md` (see
+// src/agent-404.ts) — the fixed-path artifact a site's own 404 page links via
+// `<link rel="alternate" type="text/markdown">` for agents the middleware never sees. One
+// renderer, two delivery channels, so the two can never disagree about the directions.
 
 import type { AxServingManifest } from './manifest-shape.js';
 
@@ -27,15 +32,19 @@ const ARTIFACT_PURPOSES: ReadonlyArray<{
 ];
 
 /**
- * Renders the wayfinding markdown for `pathname`. Born passing the generated-markdown audit
- * criteria by construction: opens with an H1, contains markdown links, uses no code fences (an
- * even count of zero), and stays orders of magnitude under the 100k-char ceiling via `MAX_ROUTES`.
+ * Renders the wayfinding markdown for `pathname` — or, with no pathname, the generic body the
+ * static `public/404.md` ships (a fixed file can't know which URL was missed, so its title and
+ * opening stay URL-neutral). Born passing the generated-markdown audit criteria by construction:
+ * opens with an H1, contains markdown links, uses no code fences (an even count of zero), and
+ * stays orders of magnitude under the 100k-char ceiling via `MAX_ROUTES`.
  */
-export function renderWayfinding(manifest: AxServingManifest, pathname: string): string {
+export function renderWayfinding(manifest: AxServingManifest, pathname?: string): string {
   const lines: string[] = [
-    `# ${pathname} — not found`,
+    pathname !== undefined ? `# ${pathname} — not found` : '# Page not found',
     '',
-    'This URL does not exist on this site. It may have moved, or it may never have existed —',
+    pathname !== undefined
+      ? 'This URL does not exist on this site. It may have moved, or it may never have existed —'
+      : 'The URL you requested does not exist on this site. It may have moved, or it may never have existed —',
     'requesting it again will keep returning this response. Do not retry; start from the links',
     'below instead.',
     '',
@@ -53,9 +62,12 @@ export function renderWayfinding(manifest: AxServingManifest, pathname: string):
     lines.push('## Start here', '', ...artifactLines, '');
   }
 
-  if (manifest.routes.length > 0) {
+  // Gated routes are never listed: a login-walled page offered as "where to continue" is a dead
+  // end with extra steps, and the gating policy never advertises a gated surface as open.
+  const routes = manifest.routes.filter((route) => !manifest.gatedPaths.includes(route));
+  if (routes.length > 0) {
     lines.push('## Pages that do exist', '');
-    for (const route of manifest.routes.slice(0, MAX_ROUTES)) {
+    for (const route of routes.slice(0, MAX_ROUTES)) {
       const twin = manifest.markdownTwins[route];
       lines.push(
         twin !== undefined
@@ -63,10 +75,8 @@ export function renderWayfinding(manifest: AxServingManifest, pathname: string):
           : `- [${route}](${route})`,
       );
     }
-    if (manifest.routes.length > MAX_ROUTES) {
-      lines.push(
-        `- …and ${manifest.routes.length - MAX_ROUTES} more — see the discovery links above.`,
-      );
+    if (routes.length > MAX_ROUTES) {
+      lines.push(`- …and ${routes.length - MAX_ROUTES} more — see the discovery links above.`);
     }
     lines.push('');
   }
diff --git a/packages/ax/src/report.ts b/packages/ax/src/report.ts
index 0ae4717..4aeca90 100644
--- a/packages/ax/src/report.ts
+++ b/packages/ax/src/report.ts
@@ -156,11 +156,19 @@ export interface BuildReport {
     llmsTxt: ReportArtifact;
     openapi: ReportArtifact;
   };
-  /** Agent-aware 404 status: whether a not-found page exists and whether it signposts agents. */
+  /**
+   * Agent-aware 404 status. `pages` lists every detected 404 page — App Router `not-found.*`
+   * files at the root *and* in route segments (a `notFound()` inside a segment renders the nearest
+   * one, bypassing the root), plus the Pages Router's `pages/404.*` — each with whether it links
+   * agents onward (the `/404.md` alternate link, llms.txt, or the AI Catalog). `agentAware` is
+   * true only when every detected page does. `markdownGuide` is the generated `public/404.md`
+   * wayfinding guide, reconciled by the CLI after the write.
+   */
   agent404: {
     notFoundPresent: boolean;
     agentAware: boolean;
-    source?: string;
+    pages: Array<{ source: string; agentAware: boolean }>;
+    markdownGuide?: string;
   };
   /**
    * The negotiation middleware: whether a `middleware.{ts,js}` exists and whether it wires the
diff --git a/packages/ax/test/agent-404.test.ts b/packages/ax/test/agent-404.test.ts
index b0634f4..582ff71 100644
--- a/packages/ax/test/agent-404.test.ts
+++ b/packages/ax/test/agent-404.test.ts
@@ -4,23 +4,30 @@ import { join } from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
-import { manageAgent404 } from '../src/agent-404.js';
+import {
+  applyNotFoundMdPlan,
+  buildNotFoundMd,
+  detectAgent404,
+  NOT_FOUND_MD_PATHNAME,
+} from '../src/agent-404.js';
+import type { ServingManifestData } from '../src/manifest.js';
+import { isGeneratedMarkdown } from '../src/markdown-artifact.js';
 
 let dir: string;
-let warnings: string[];
 let recommendations: string[];
+let warnings: string[];
 
-const warn = (message: string): void => {
-  warnings.push(message);
-};
 const recommend = (message: string): void => {
   recommendations.push(message);
 };
+const warn = (message: string): void => {
+  warnings.push(message);
+};
 
 beforeEach(() => {
   dir = mkdtempSync(join(tmpdir(), 'ax-agent-404-'));
-  warnings = [];
   recommendations = [];
+  warnings = [];
 });
 
 afterEach(() => {
@@ -33,198 +40,212 @@ function write(relPath: string, contents: string): void {
   writeFileSync(full, contents, 'utf8');
 }
 
-function run(overrides: Partial<Parameters<typeof manageAgent404>[0]> = {}) {
-  return manageAgent404({
+function run(overrides: Partial<Parameters<typeof detectAgent404>[0]> = {}) {
+  return detectAgent404({
     cwd: dir,
-    scaffold: false,
     basePath: '',
-    llmsTxtFound: false,
-    sitemapFound: false,
-    warn,
+    notFoundMdPlanned: true,
     recommend,
     ...overrides,
   });
 }
 
-describe('manageAgent404 — detect-and-recommend', () => {
-  it('does nothing without an app dir', () => {
+const LINK_TAG = '<link rel="alternate" type="text/markdown" href="/404.md" />';
+
+describe('detectAgent404 — no 404 page at all', () => {
+  it('does nothing without a router', () => {
     const result = run();
-    expect(result).toEqual({ notFoundPresent: false, agentAware: false });
+    expect(result).toEqual({ notFoundPresent: false, agentAware: false, pages: [] });
     expect(recommendations).toEqual([]);
   });
 
-  it('recommends adding a not-found page when none exists', () => {
+  it('recommends creating a standard 404 page carrying the alternate-link tag', () => {
     mkdirSync(join(dir, 'app'), { recursive: true });
 
     const result = run();
     expect(result.notFoundPresent).toBe(false);
-    expect(recommendations.join('\n')).toContain('No app/not-found.tsx found');
-    expect(recommendations.join('\n')).toContain('scaffoldAgent404');
+    const message = recommendations.join('\n');
+    expect(message).toContain('No app/not-found.tsx found');
+    // The page's design is the user's — the recommendation asks for a standard page + one tag,
+    // never a route list or agent-addressed content.
+    expect(message).toContain('your own design system');
+    expect(message).toContain(LINK_TAG);
+    expect(message).not.toContain('scaffold');
   });
 
-  it('recommends signposts when a not-found page exists without any', () => {
+  it('recommends the pages/404 convention path for a Pages Router app', () => {
+    mkdirSync(join(dir, 'pages'), { recursive: true });
+
+    const result = run();
+    expect(result.notFoundPresent).toBe(false);
+    expect(recommendations.join('\n')).toContain('No pages/404.tsx found');
+  });
+
+  it('says the guide is not written when markdownTwins is off', () => {
+    mkdirSync(join(dir, 'app'), { recursive: true });
+
+    run({ notFoundMdPlanned: false });
+    expect(recommendations.join('\n')).toContain('markdownTwins');
+    expect(recommendations.join('\n')).toContain('disabled');
+  });
+});
+
+describe('detectAgent404 — pages exist', () => {
+  it('recommends the link tag for a page that points agents nowhere', () => {
     write(
       join('app', 'not-found.tsx'),
       'export default function NotFound() { return <h1>404</h1>; }',
     );
 
     const result = run();
-    expect(result).toMatchObject({
+    expect(result).toEqual({
       notFoundPresent: true,
       agentAware: false,
-      source: join('app', 'not-found.tsx'),
+      pages: [{ source: join('app', 'not-found.tsx'), agentAware: false }],
     });
-    expect(recommendations.join('\n')).toContain('point agents anywhere');
+    const message = recommendations.join('\n');
+    expect(message).toContain(LINK_TAG);
+    expect(message).toContain('ax never edits it');
   });
 
-  it('stays quiet when an existing not-found page already signposts agents', () => {
+  it('stays quiet when the page links the wayfinding guide', () => {
     write(
       join('app', 'not-found.tsx'),
-      'export default function NotFound() { return <a href="/llms.txt">llms.txt</a>; }',
+      `export default function NotFound() { return <main>${LINK_TAG}<h1>404</h1></main>; }`,
     );
 
     const result = run();
     expect(result).toMatchObject({ notFoundPresent: true, agentAware: true });
     expect(recommendations).toEqual([]);
   });
-});
 
-describe('manageAgent404 — scaffolding (opt-in)', () => {
-  it('scaffolds not-found.tsx plus the data module, with current routes and links', () => {
-    write('tsconfig.json', '{}');
-    write(join('app', 'page.tsx'), 'export default function Page() { return null; }');
-    write(join('app', 'docs', 'page.tsx'), 'export default function Page() { return null; }');
+  it('accepts hand-built signposts (llms.txt / ai-catalog links) as agent-aware too', () => {
     write(
-      join('app', 'blog', '[slug]', 'page.tsx'),
-      'export default function Page() { return null; }',
+      join('app', 'not-found.tsx'),
+      'export default function NotFound() { return <a href="/llms.txt">llms.txt</a>; }',
     );
 
-    const result = run({ scaffold: true, llmsTxtFound: true, sitemapFound: true });
-
-    expect(result.notFoundPresent).toBe(true);
-    expect(result.agentAware).toBe(true);
-    expect(existsSync(join(dir, 'app', 'not-found.tsx'))).toBe(true);
-
-    const data = readFileSync(join(dir, 'app', 'not-found-agent-data.ts'), 'utf8');
-    expect(data).toContain('Generated by ax');
-    // Static routes only — the dynamic [slug] route must be absent (never guessed).
-    expect(data).toContain('"/docs"');
-    expect(data).not.toContain('[slug]');
-    // Discovery links reflect what was actually detected this run.
-    expect(data).toContain('/.well-known/ai-catalog.json');
-    expect(data).toContain('/llms.txt');
-    expect(data).toContain('/sitemap.xml');
-
-    expect(warnings.join('\n')).toContain('Scaffolded an agent-aware 404 page');
-  });
-
-  it('omits llms.txt / sitemap links when those artifacts are absent', () => {
-    write('tsconfig.json', '{}');
-    write(join('app', 'page.tsx'), 'export default function Page() { return null; }');
-
-    run({ scaffold: true });
-    const data = readFileSync(join(dir, 'app', 'not-found-agent-data.ts'), 'utf8');
-    expect(data).toContain('/.well-known/ai-catalog.json');
-    expect(data).not.toContain('/llms.txt');
-    expect(data).not.toContain('/sitemap.xml');
-  });
-
-  it('prefixes discovery links with basePath', () => {
-    write('tsconfig.json', '{}');
-    write(join('app', 'page.tsx'), 'export default function Page() { return null; }');
-
-    run({ scaffold: true, basePath: '/store', llmsTxtFound: true });
-    const data = readFileSync(join(dir, 'app', 'not-found-agent-data.ts'), 'utf8');
-    expect(data).toContain('/store/.well-known/ai-catalog.json');
-    expect(data).toContain('/store/llms.txt');
+    expect(run().agentAware).toBe(true);
+    expect(recommendations).toEqual([]);
   });
 
-  it('never overwrites an existing not-found page, but keeps a scaffolded one fresh', () => {
-    write('tsconfig.json', '{}');
-    write(join('app', 'page.tsx'), 'export default function Page() { return null; }');
-
-    // First run scaffolds; a second run must not rewrite not-found.tsx but must regenerate data.
-    run({ scaffold: true });
-    const scaffolded = readFileSync(join(dir, 'app', 'not-found.tsx'), 'utf8');
-    write(join('app', 'pricing', 'page.tsx'), 'export default function Page() { return null; }');
+  it('detects segment-level not-found files, naming only the unlinked ones', () => {
+    // Dynamic-route misses (`/docs/[slug]` with a bad slug) render the *nearest* not-found file,
+    // bypassing the root one — so a linked root page alone is not agent-aware coverage.
+    write(join('app', 'not-found.tsx'), `export default () => ${JSON.stringify(LINK_TAG)};`);
+    write(
+      join('app', 'docs', 'not-found.jsx'),
+      'export default function NotFound() { return null; }',
+    );
 
-    const result = run({ scaffold: true });
-    expect(readFileSync(join(dir, 'app', 'not-found.tsx'), 'utf8')).toBe(scaffolded);
-    expect(result.scaffoldedPath).toBeUndefined();
-    const data = readFileSync(join(dir, 'app', 'not-found-agent-data.ts'), 'utf8');
-    expect(data).toContain('"/pricing"');
+    const result = run();
+    expect(result.agentAware).toBe(false);
+    expect(result.pages).toEqual([
+      { source: join('app', 'docs', 'not-found.jsx'), agentAware: false },
+      { source: join('app', 'not-found.tsx'), agentAware: true },
+    ]);
+    const message = recommendations.join('\n');
+    expect(message).toContain(join('app', 'docs', 'not-found.jsx'));
+    expect(message).not.toContain(join('app', 'not-found.tsx'));
   });
 
-  it('scaffolds .jsx and a .js data module for a JavaScript project', () => {
-    write(join('app', 'page.jsx'), 'export default function Page() { return null; }');
+  it('detects across both routers at once', () => {
+    write(join('app', 'not-found.tsx'), 'export default () => null;');
+    write(join('pages', '404.tsx'), 'export default () => null;');
 
-    run({ scaffold: true });
-    expect(existsSync(join(dir, 'app', 'not-found.jsx'))).toBe(true);
-    expect(existsSync(join(dir, 'app', 'not-found-agent-data.js'))).toBe(true);
+    const result = run();
+    expect(result.pages.map((page) => page.source)).toEqual([
+      join('app', 'not-found.tsx'),
+      join('pages', '404.tsx'),
+    ]);
   });
 
-  it('does not regenerate the data module for a hand-written page that never imports it', () => {
-    write('tsconfig.json', '{}');
-    write(
-      join('app', 'not-found.tsx'),
-      'export default function NotFound() { return <a href="/llms.txt">llms.txt</a>; }',
-    );
+  it('prefixes the recommended link href with basePath', () => {
+    write(join('app', 'not-found.tsx'), 'export default () => null;');
 
-    run({ scaffold: true });
-    expect(existsSync(join(dir, 'app', 'not-found-agent-data.ts'))).toBe(false);
+    run({ basePath: '/store' });
+    expect(recommendations.join('\n')).toContain('href="/store/404.md"');
   });
 
   it('never throws — a scan is best-effort', () => {
-    expect(() => run({ scaffold: true })).not.toThrow();
+    expect(() => run()).not.toThrow();
   });
 });
 
-describe('manageAgent404 — Pages Router', () => {
-  it('does nothing without an app or pages dir', () => {
-    expect(run()).toEqual({ notFoundPresent: false, agentAware: false });
-  });
-
-  it('detects an existing pages/404.tsx and recommends signposts when it has none', () => {
-    write(join('pages', '404.tsx'), 'export default function NotFound() { return <h1>404</h1>; }');
+const manifest: ServingManifestData = {
+  basePath: '',
+  routes: ['/', '/docs', '/pricing'],
+  dynamicRoutePrefixes: ['/blog'],
+  markdownTwins: { '/docs': '/docs.md' },
+  gatedPaths: [],
+  artifacts: {
+    aiCatalog: '/.well-known/ai-catalog.json',
+    llmsTxt: '/llms.txt',
+    authMd: '/auth.md',
+  },
+};
 
-    const result = run();
-    expect(result).toMatchObject({
-      notFoundPresent: true,
-      agentAware: false,
-      source: join('pages', '404.tsx'),
+describe('buildNotFoundMd', () => {
+  it('renders frontmatter plus the URL-neutral wayfinding body', () => {
+    const plan = buildNotFoundMd({
+      manifest,
+      siteUrl: 'https://example.com',
+      basePath: '',
+      siteDisplayName: 'Example',
+      now: new Date('2026-08-28T00:00:00.000Z'),
     });
-    expect(recommendations.join('\n')).toContain('point agents anywhere');
-  });
-
-  it('recommends the pages/404 convention path when none exists', () => {
-    mkdirSync(join(dir, 'pages'), { recursive: true });
 
-    const result = run();
-    expect(result.notFoundPresent).toBe(false);
-    expect(recommendations.join('\n')).toContain('No pages/404.tsx found');
+    expect(plan.servedPath).toBe(NOT_FOUND_MD_PATHNAME);
+    expect(plan.routeCount).toBe(3);
+    expect(isGeneratedMarkdown(plan.content)).toBe(true);
+    expect(plan.content).toContain('title: "Page not found — Example"');
+    expect(plan.content).toContain('canonical_url: https://example.com/404.md');
+    expect(plan.content).toContain('# Page not found');
+    expect(plan.content).toContain('[/docs](/docs) — markdown: [/docs.md](/docs.md)');
+    expect(plan.content).toContain('[/llms.txt](/llms.txt)');
+    expect(plan.content).toContain('[/auth.md](/auth.md)');
+  });
+
+  it('serves under basePath and falls back to the served path with no site origin', () => {
+    const plan = buildNotFoundMd({
+      manifest: { ...manifest, basePath: '/store' },
+      siteUrl: undefined,
+      basePath: '/store',
+      siteDisplayName: 'Example',
+    });
+    expect(plan.servedPath).toBe('/store/404.md');
+    expect(plan.content).toContain('canonical_url: /store/404.md');
   });
+});
 
-  it('scaffolds pages/404.tsx plus a data module whose routes come from the pages dir', () => {
-    write('tsconfig.json', '{}');
-    write(join('pages', 'index.tsx'), 'export default function H() { return null; }');
-    write(join('pages', 'about.tsx'), 'export default function A() { return null; }');
+describe('applyNotFoundMdPlan', () => {
+  const plan = () =>
+    buildNotFoundMd({
+      manifest,
+      siteUrl: 'https://example.com',
+      basePath: '',
+      siteDisplayName: 'Example',
+    });
 
-    const result = run({ scaffold: true });
-    expect(result.notFoundPresent).toBe(true);
-    expect(existsSync(join(dir, 'pages', '404.tsx'))).toBe(true);
+  it('writes public/404.md and removes it when there is no plan', () => {
+    const written = applyNotFoundMdPlan(dir, plan(), warn);
+    expect(written).toEqual({ written: join('public', '404.md') });
+    expect(existsSync(join(dir, 'public', '404.md'))).toBe(true);
 
-    const dataModule = readFileSync(join(dir, 'pages', 'not-found-agent-data.ts'), 'utf8');
-    expect(dataModule).toContain('"/about"');
-    expect(dataModule).toContain('"/"');
+    const deleted = applyNotFoundMdPlan(dir, undefined, warn);
+    expect(deleted).toEqual({ deleted: join('public', '404.md') });
+    expect(existsSync(join(dir, 'public', '404.md'))).toBe(false);
+    expect(warnings).toEqual([]);
   });
 
-  it('prefers the App Router when both routers are present', () => {
-    write('tsconfig.json', '{}');
-    mkdirSync(join(dir, 'app'), { recursive: true });
-    mkdirSync(join(dir, 'pages'), { recursive: true });
+  it('never overwrites or deletes a user-authored public/404.md', () => {
+    write(join('public', '404.md'), '# my own 404 guide\n');
+
+    expect(applyNotFoundMdPlan(dir, plan(), warn)).toEqual({});
+    expect(readFileSync(join(dir, 'public', '404.md'), 'utf8')).toBe('# my own 404 guide\n');
+    expect(warnings.join('\n')).toContain('not generated by ax');
 
-    run({ scaffold: true });
-    expect(existsSync(join(dir, 'app', 'not-found.tsx'))).toBe(true);
-    expect(existsSync(join(dir, 'pages', '404.tsx'))).toBe(false);
+    expect(applyNotFoundMdPlan(dir, undefined, warn)).toEqual({});
+    expect(existsSync(join(dir, 'public', '404.md'))).toBe(true);
   });
 });
diff --git a/packages/ax/test/cli-twins.test.ts b/packages/ax/test/cli-twins.test.ts
index 96a7bc7..5f65e87 100644
--- a/packages/ax/test/cli-twins.test.ts
+++ b/packages/ax/test/cli-twins.test.ts
@@ -123,6 +123,38 @@ describe('runCli markdown twins', () => {
     });
   });
 
+  it('writes the /404.md wayfinding guide alongside the twins and reconciles the report', async () => {
+    writeAppWithPrerender();
+    const code = await runCli(['--yes', '--report'], io());
+    expect(code).toBe(0);
+
+    expect(stdout.some((l) => l.includes('404 wayfinding guide → /404.md'))).toBe(true);
+    const guide = readFileSync(join(dir, 'public', '404.md'), 'utf8');
+    expect(guide).toContain(`generated-by: "${GENERATED_BY}"`);
+    expect(guide).toContain('# Page not found');
+    // The guide links the twin written this same run — overlaid at plan time, not read off disk.
+    expect(guide).toContain('markdown: [/index.md](/index.md)');
+
+    const report = readReport();
+    expect(report.agent404.markdownGuide).toBe(join('public', '404.md'));
+    expect(report.sizes.some((s) => s.artifact === '404.md')).toBe(true);
+  });
+
+  it('markdownTwins: false plans no /404.md and leaves an existing generated one alone', async () => {
+    writeAppWithPrerender();
+    write(
+      'ax.config.ts',
+      "export default { siteUrl: 'https://example.com', markdownTwins: false };\n",
+    );
+    write('public/404.md', `---\ntitle: "x"\ngenerated-by: "${GENERATED_BY}"\n---\n\nold\n`);
+    const code = await runCli(['--yes', '--report'], io());
+    expect(code).toBe(0);
+    // Turning the feature off is the user's call; deleting their public/ contents on that signal
+    // is not ours to make silently — same posture as the twins.
+    expect(readFileSync(join(dir, 'public', '404.md'), 'utf8')).toContain('old');
+    expect(readReport().agent404.markdownGuide).toBeUndefined();
+  });
+
   it('refreshes an existing serving manifest after the twins land', async () => {
     writeAppWithPrerender();
     write('ax-manifest.ts', 'export const axManifest = {} as const;\n');
diff --git a/packages/ax/test/config.test.ts b/packages/ax/test/config.test.ts
index c4ea6b8..37c45fd 100644
--- a/packages/ax/test/config.test.ts
+++ b/packages/ax/test/config.test.ts
@@ -26,7 +26,6 @@ describe('loadAxConfig', () => {
       siteUrl: undefined,
       emit: 'static',
       scaffoldLlmsTxt: false,
-      scaffoldAgent404: false,
       scaffoldRobots: false,
       scaffoldJsonLd: false,
       markdownTwins: true,
diff --git a/packages/ax/test/fixtures-integration.test.ts b/packages/ax/test/fixtures-integration.test.ts
index cc5c975..b01fae2 100644
--- a/packages/ax/test/fixtures-integration.test.ts
+++ b/packages/ax/test/fixtures-integration.test.ts
@@ -268,14 +268,15 @@ describe('generateCatalog against the Pages Router fixtures', () => {
     expect(validateCatalogArd(catalog).valid).toBe(true);
     expect(report.routers).toEqual(['pages']);
 
-    // pages-bare ships a plain pages/404.tsx: detected, but not agent-aware — so a "signpost it"
-    // recommendation, proving the Pages Router 404 convention is recognized (not just app/not-found).
+    // pages-bare ships a plain pages/404.tsx: detected, but not agent-aware — so a "link the
+    // wayfinding guide" recommendation, proving the Pages Router 404 convention is recognized
+    // (not just app/not-found).
     expect(report.agent404).toMatchObject({
       notFoundPresent: true,
       agentAware: false,
-      source: join('pages', '404.tsx'),
+      pages: [{ source: join('pages', '404.tsx'), agentAware: false }],
     });
-    expect(recommendations.some((r) => r.includes("doesn't point agents anywhere"))).toBe(true);
+    expect(recommendations.some((r) => r.includes('doesn’t point agents anywhere'))).toBe(true);
   });
 
   it('lists Pages Router content routes, excluding special/dynamic/error files', () => {
diff --git a/packages/ax/test/generate.test.ts b/packages/ax/test/generate.test.ts
index 6a9cbc6..41f416d 100644
--- a/packages/ax/test/generate.test.ts
+++ b/packages/ax/test/generate.test.ts
@@ -137,6 +137,59 @@ describe('generateCatalog agent-readiness recommendations', () => {
   });
 });
 
+// The generated /404.md wayfinding guide: planned whenever markdownTwins is on and a router
+// exists, rendered from serving-manifest data with this run's own outputs (planned twins, the
+// catalog) overlaid so the guide describes the build it ships with.
+describe('generateCatalog notFoundMdPlan', () => {
+  it('plans /404.md for an App Router app, listing routes and the catalog it writes this run', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'demo' }), 'utf8');
+    mkdirSync(join(dir, 'app', 'docs'), { recursive: true });
+    writeFileSync(join(dir, 'app', 'page.tsx'), 'export default () => null;', 'utf8');
+    writeFileSync(join(dir, 'app', 'docs', 'page.tsx'), 'export default () => null;', 'utf8');
+
+    const { notFoundMdPlan } = await generateCatalog({ cwd: dir });
+
+    expect(notFoundMdPlan?.servedPath).toBe('/404.md');
+    expect(notFoundMdPlan?.content).toContain('# Page not found');
+    expect(notFoundMdPlan?.content).toContain('[/docs](/docs)');
+    // The catalog is written alongside this run, so the guide may link it before it's on disk.
+    expect(notFoundMdPlan?.content).toContain('/.well-known/ai-catalog.json');
+    expect(notFoundMdPlan?.content).toContain('generated-by: "@ora-ai/ax"');
+  });
+
+  it('plans no /404.md when markdownTwins is off or no router exists', async () => {
+    // No app/ or pages/ dir at all → nothing is a page miss → no guide.
+    expect((await generateCatalog({ cwd: dir })).notFoundMdPlan).toBeUndefined();
+
+    mkdirSync(join(dir, 'app'), { recursive: true });
+    writeFileSync(join(dir, 'app', 'page.tsx'), 'export default () => null;', 'utf8');
+    writeFileSync(join(dir, 'ax.config.mjs'), 'export default { markdownTwins: false };\n', 'utf8');
+    expect((await generateCatalog({ cwd: dir })).notFoundMdPlan).toBeUndefined();
+  });
+
+  it('reports every detected 404 page, segment-level included', async () => {
+    mkdirSync(join(dir, 'app', 'docs'), { recursive: true });
+    writeFileSync(join(dir, 'app', 'page.tsx'), 'export default () => null;', 'utf8');
+    writeFileSync(
+      join(dir, 'app', 'not-found.tsx'),
+      'export default () => <link rel="alternate" type="text/markdown" href="/404.md" />;',
+      'utf8',
+    );
+    writeFileSync(join(dir, 'app', 'docs', 'not-found.tsx'), 'export default () => null;', 'utf8');
+
+    const { report } = await generateCatalog({ cwd: dir });
+
+    expect(report.agent404).toEqual({
+      notFoundPresent: true,
+      agentAware: false,
+      pages: [
+        { source: join('app', 'docs', 'not-found.tsx'), agentAware: false },
+        { source: join('app', 'not-found.tsx'), agentAware: true },
+      ],
+    });
+  });
+});
+
 // The build report is what a coding agent reads instead of the CLI output, and its `ora` section is
 // what makes it actionable: each artifact the plugin knows about, expressed as the Ora checks it
 // contributes to.
diff --git a/packages/ax/test/init-config.test.ts b/packages/ax/test/init-config.test.ts
index 31d6b75..2f36e4a 100644
--- a/packages/ax/test/init-config.test.ts
+++ b/packages/ax/test/init-config.test.ts
@@ -16,7 +16,6 @@ function answers(overrides: Partial<InitAnswers> = {}): InitAnswers {
     scaffoldLlmsTxt: true,
     scaffoldJsonLd: true,
     scaffoldRobots: true,
-    scaffoldAgent404: true,
     markdownTwins: true,
     report: true,
     ...overrides,
@@ -44,7 +43,6 @@ describe('renderAxConfig', () => {
       'scaffoldLlmsTxt',
       'scaffoldJsonLd',
       'scaffoldRobots',
-      'scaffoldAgent404',
       'markdownTwins',
       'report',
     ]) {
@@ -81,7 +79,6 @@ describe('renderAxConfig', () => {
       scaffoldLlmsTxt: true,
       scaffoldJsonLd: true,
       scaffoldRobots: false,
-      scaffoldAgent404: true,
       markdownTwins: true,
       report: true,
     };
diff --git a/packages/ax/test/init.test.ts b/packages/ax/test/init.test.ts
index ab19dc6..7284880 100644
--- a/packages/ax/test/init.test.ts
+++ b/packages/ax/test/init.test.ts
@@ -789,11 +789,11 @@ describe('runInit markdown twins + serving-manifest wiring', () => {
 
   it('declining the twin and manifest questions writes markdownTwins: false and wires no prebuild', async () => {
     writeBareApp(dir);
-    // Setup order: llmsTxt, jsonLd, robots, agent404, markdownTwins, report, manifest — deselect
+    // Setup order: llmsTxt, jsonLd, robots, markdownTwins, report, manifest — deselect
     // markdownTwins and manifest, keep the rest. Only the build offer remains a confirm.
     const prompter = new ScriptedPrompter({
       text: ['https://acme.com'],
-      multiSelect: [['llmsTxt', 'jsonLd', 'robots', 'agent404', 'report']],
+      multiSelect: [['llmsTxt', 'jsonLd', 'robots', 'report']],
       confirm: [false],
     });
     const code = await runInit([], { ...io(), prompter });
@@ -814,7 +814,7 @@ describe('runInit setup multi-select', () => {
     // Deselect only jsonLd and manifest; everything else in SETUP_OPTIONS stays selected.
     const prompter = new ScriptedPrompter({
       text: ['https://acme.com'],
-      multiSelect: [['llmsTxt', 'robots', 'agent404', 'markdownTwins', 'report']],
+      multiSelect: [['llmsTxt', 'robots', 'markdownTwins', 'report']],
       confirm: [false],
     });
 
@@ -825,7 +825,6 @@ describe('runInit setup multi-select', () => {
     expect(source).toContain('scaffoldJsonLd: false,');
     expect(source).toContain('scaffoldLlmsTxt: true,');
     expect(source).toContain('scaffoldRobots: true,');
-    expect(source).toContain('scaffoldAgent404: true,');
     expect(source).toContain('markdownTwins: true,');
     expect(source).toContain('report: true,');
 
diff --git a/packages/ax/test/middleware.test.ts b/packages/ax/test/middleware.test.ts
index 1c2ceb8..0c77940 100644
--- a/packages/ax/test/middleware.test.ts
+++ b/packages/ax/test/middleware.test.ts
@@ -192,6 +192,24 @@ describe('withAx — wayfinding for unknown URLs', () => {
     expect(body.length).toBeLessThan(100_000);
   });
 
+  it('renders a URL-neutral body without a pathname — the static /404.md variant', () => {
+    const body = renderWayfinding(manifest);
+    expect(body).toMatch(/^# Page not found/);
+    expect(body).toContain('The URL you requested does not exist');
+    expect(body).toContain('[/docs](/docs) — markdown: [/docs.md](/docs.md)');
+  });
+
+  it('never lists gated routes — a login-walled page is no place to send a lost agent', () => {
+    const gated: AxServingManifest = {
+      ...manifest,
+      routes: ['/docs', '/members'],
+      gatedPaths: ['/members'],
+    };
+    const body = renderWayfinding(gated, '/missing');
+    expect(body).toContain('[/docs](/docs)');
+    expect(body).not.toContain('/members');
+  });
+
   it('caps the route list and says so', () => {
     const big: AxServingManifest = {
       ...manifest,