@@ -139,7 +139,9 @@ export default defineConfig({
     barrel(),
   ],
   docs: {
-    outDir:   "./docs",        // every surface lands here (run: meta docs)
+    outDir:   "./docs/generated",  // every surface lands here (run: meta docs).
+                               // A SUB-directory on purpose: these pages are regenerated
+                               // and overwritten, and docs/ itself is usually yours.
     layout:   "flat",          // or "package" for multi-package models
     // surfaces defaults to ["model", "api", "requirements", "agent"] — all four.
     // Deliberately NOT narrowed here: the requirements and agent surfaces emit ZERO
 
@@ -75,7 +75,11 @@ DOCS FLAGS:
   [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
                         your metadata, NOT the metadata directory. Passing it SCOPES the run
                         (default: cwd)
-  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
+                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
+                        for a directory that persists, which is what 'meta verify --docs'
+                        measures. The default is a sub-directory on purpose: these pages are
+                        regenerated and overwritten, and 'docs/' itself is usually yours.
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
   --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
 
@@ -272,7 +276,11 @@ FLAGS:
                         it SCOPES the run to that directory's own sources; no ancestor
                         .metaobjects/config.json is consulted. Omitted (default), the project
                         is discovered by walking up.
-  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
+                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
+                        for a directory that persists, which is what 'meta verify --docs'
+                        measures. The default is a sub-directory on purpose: these pages are
+                        regenerated and overwritten, and 'docs/' itself is usually yours.
   --model               Emit the markdown model surface (entity + template pages)
   --api                 Emit the markdown api surface (generated SDK reference)
   --requirements        Emit the declared requirement ledger (requirements.md + .toon).
@@ -281,7 +289,9 @@ FLAGS:
                         agent/ui.md (the generated forms and grids) and
                         agent/requirements.md (the ledger plus a claimed-node index).
                         Needs metaobjects.config.ts (the dialect and physical names come
-                        from it); each page is skipped when its tier has nothing to describe.
+                        from it); each page is skipped when its tier has nothing to describe
+                        — agent/ui.md needs a UI generator (a form, hook or grid) in the
+                        suite, not merely objects that could have one.
   --metamodel           Document the built-in metamodel vocabulary (no metadata needed)
   --site                Generate the browsable HTML documentation site (<out>/site/)
   --scaffold-site       Copy the site's templates + assets into codegen/docs-site/ to own (theme) them
 
@@ -272,8 +272,9 @@ export interface VerifyFlags {
    * A SEPARATE subverb rather than part of `--codegen`, because they check different
    * trees under different ownership rules: `--codegen` regenerates `outDir`/`targets` and
    * must respect the hand edits `meta gen` preserves, while the docs tree has no merge,
-   * no manifest, and lives in a directory (`./docs` by default) full of hand-written
-   * files it does not own. Folding them together would have to pick one of those rules
+   * no manifest, and lives in a directory the adopter chose (`./docs/generated` by
+   * default) that may hold hand-written files it does not own. Folding them together
+   * would have to pick one of those rules
    * for both.
    */
   docs: boolean;
 
@@ -19,9 +19,11 @@
 //      `.gen-state/.hashes.json` to tell a preserved hand edit from stale output; here
 //      there is no such offer to honour.
 //
-//   2. IT REPORTS A FILE AS EXTRA ONLY WHERE IT OWNS THE DIRECTORY. `docs.outDir`
-//      defaults to `./docs`, which in a real repository is full of hand-written
-//      documentation — this repository's own `docs/` holds a hundred such files. Its
+//   2. IT REPORTS A FILE AS EXTRA ONLY WHERE IT OWNS THE DIRECTORY. `docs.outDir` is a
+//      directory an adopter chooses, and it may well be one full of hand-written
+//      documentation — this repository's own `docs/` holds a hundred such files. (The
+//      default moved to `./docs/generated` for exactly that reason: defaulting into the
+//      most-owned directory name in the ecosystem contradicted this paragraph.) Its
 //      `api/` subtree is not ours either: on a multi-port project those pages are written
 //      by the OTHER port's docs command (`mvn metaobjects:docs`, `metaobjects docs`,
 //      `dotnet meta docs`), which this gate never runs, so a fresh run here legitimately
 
@@ -57,7 +57,11 @@ DOCS FLAGS:
   [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
                         your metadata, NOT the metadata directory. Passing it SCOPES the run
                         (default: cwd)
-  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
+                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
+                        for a directory that persists, which is what 'meta verify --docs'
+                        measures. The default is a sub-directory on purpose: these pages are
+                        regenerated and overwritten, and 'docs/' itself is usually yours.
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
   --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
 
 
@@ -19,6 +19,14 @@ import { run } from "../../src/index.js";
 // test/integration/ -> cli -> packages -> typescript -> server -> repo root
 const SHOWCASE = resolve(import.meta.dirname, "../../../../../../examples/showcase");
 
+// The docs root, taken from the CONFIG default rather than a `--out` flag — because the
+// gate reads the config and `--out` does not survive the run. The test used to pass
+// `--out <dir>/docs` while `verify --docs` resolved the default, and it only agreed
+// because the two happened to be the same string. When the default moved to
+// `docs/generated`, that coincidence ended and every case here failed at once: the two
+// doors onto one directory were never actually being compared.
+const DOCS_ROOT = join("docs", "generated");
+
 /** A throwaway copy of the showcase with a freshly generated docs tree. */
 function project(): string {
   const dir = mkdtempSync(join(tmpdir(), "verify-docs-"));
@@ -27,7 +35,7 @@ function project(): string {
 }
 
 async function generateDocs(dir: string): Promise<void> {
-  expect(await run(["docs", dir, "--out", join(dir, "docs")])).toBe(0);
+  expect(await run(["docs", dir])).toBe(0);
 }
 
 describe("meta verify --docs", () => {
@@ -38,12 +46,17 @@ describe("meta verify --docs", () => {
       // The agent surface materialises only with a loadable gen config, which the
       // showcase has. Assert the pages exist before asserting the gate is green, so a
       // green result cannot come from the surface having silently emitted nothing.
-      expect(existsSync(join(dir, "docs", "agent", "schema.md"))).toBe(true);
-      expect(existsSync(join(dir, "docs", "agent", "ui.md"))).toBe(true);
-      expect(existsSync(join(dir, "docs", "agent", "requirements.md"))).toBe(true);
+      expect(existsSync(join(dir, DOCS_ROOT, "agent", "schema.md"))).toBe(true);
+      expect(existsSync(join(dir, DOCS_ROOT, "agent", "requirements.md"))).toBe(true);
+      // NO ui.md, and that is the assertion. The showcase wires entity/queries/routes/
+      // prompt generators and not one UI generator, so nothing here emits a form, a hook
+      // or a grid — the page's metadata predicate (`servesReadApi`) said otherwise and
+      // produced a control table for forms that do not exist plus endpoints for a client
+      // that was never generated. Whether the tier exists is a GENERATOR fact.
+      expect(existsSync(join(dir, DOCS_ROOT, "agent", "ui.md"))).toBe(false);
       // Built from the REAL migrate-ts snapshot: the dialect comes from the project's
       // own config, not from `meta docs`'s neutral "sqlite" placeholder.
-      const schema = readFileSync(join(dir, "docs", "agent", "schema.md"), "utf8");
+      const schema = readFileSync(join(dir, DOCS_ROOT, "agent", "schema.md"), "utf8");
       expect(schema).toContain("`subscribers`");
       expect(schema).toContain("Declared by `acme::Subscriber`.");
 
@@ -57,7 +70,7 @@ describe("meta verify --docs", () => {
     const dir = project();
     try {
       await generateDocs(dir);
-      const page = join(dir, "docs", "agent", "schema.md");
+      const page = join(dir, DOCS_ROOT, "agent", "schema.md");
       writeFileSync(page, readFileSync(page, "utf8").replace("subscribers", "subscribersRENAMED"));
       expect(await run(["verify", "--cwd", dir, "--docs"])).toBe(1);
     } finally {
@@ -69,7 +82,8 @@ describe("meta verify --docs", () => {
     const dir = project();
     try {
       await generateDocs(dir);
-      rmSync(join(dir, "docs", "agent", "ui.md"));
+      // A page the showcase DOES emit — ui.md is not one of them (no UI generator).
+      rmSync(join(dir, DOCS_ROOT, "agent", "schema.md"));
       expect(await run(["verify", "--cwd", dir, "--docs"])).toBe(1);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -98,10 +112,10 @@ describe("meta verify --docs", () => {
       // hand-written documentation. Convicting those is the jurisdiction mistake
       // `verify --codegen`'s orphan branch was corrected for; with no manifest to appeal
       // to, this gate must never make it.
-      writeFileSync(join(dir, "docs", "ARCHITECTURE.md"), "# Ours, not MetaObjects'.\n");
+      writeFileSync(join(dir, DOCS_ROOT, "ARCHITECTURE.md"), "# Ours, not MetaObjects'.\n");
       // Inside `agent/` too: the gate convicts a STALE GENERATED page there, and it tells
       // the two apart by the `@generated` marker rather than by the directory alone.
-      writeFileSync(join(dir, "docs", "agent", "NOTES.md"), "# Also ours.\n");
+      writeFileSync(join(dir, DOCS_ROOT, "agent", "NOTES.md"), "# Also ours.\n");
       expect(await run(["verify", "--cwd", dir, "--docs"])).toBe(0);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -121,8 +135,8 @@ describe("meta verify --docs", () => {
       // Simulated by copying a generated page to a name no run emits: same shape, one
       // condition — a committed file carrying our marker that a fresh run does not
       // produce — without needing to break the project to reach it.
-      const stale = readFileSync(join(dir, "docs", "agent", "schema.md"), "utf8");
-      writeFileSync(join(dir, "docs", "agent", "schema.postgres.md"), stale);
+      const stale = readFileSync(join(dir, DOCS_ROOT, "agent", "schema.md"), "utf8");
+      writeFileSync(join(dir, DOCS_ROOT, "agent", "schema.postgres.md"), stale);
       expect(await run(["verify", "--cwd", dir, "--docs"])).toBe(1);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -137,7 +151,7 @@ describe("meta verify --docs", () => {
       // repository's `docs/` may hold a symlink to a build output absent on CI. `statSync`
       // follows it and throws ENOENT, which the caller reports as "regeneration failed" —
       // the gate going red, blaming the fresh run, for a dangling link it did not create.
-      symlinkSync(join(dir, "docs", "nowhere-at-all"), join(dir, "docs", "dangling.md"));
+      symlinkSync(join(dir, DOCS_ROOT, "nowhere-at-all"), join(dir, DOCS_ROOT, "dangling.md"));
       expect(await run(["verify", "--cwd", dir, "--docs"])).toBe(0);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -202,10 +216,10 @@ async function runCapturingStderr(args: string[]): Promise<{ exit: number; out:
 
 describe("meta verify --docs — a git-ignored page is not drift", () => {
   test("the F27 reproduction: generate all, commit two, gate is clean", async () => {
-    const dir = gitProject("docs/*\n!docs/requirements.md\n!docs/requirements.toon\n");
+    const dir = gitProject("docs/generated/*\n!docs/generated/requirements.md\n!docs/generated/requirements.toon\n");
     try {
       await generateDocs(dir);
-      git(dir, "add", "-f", ".gitignore", "docs/requirements.md", "docs/requirements.toon");
+      git(dir, "add", "-f", ".gitignore", "docs/generated/requirements.md", "docs/generated/requirements.toon");
       git(dir, "commit", "-qm", "docs");
 
       const { exit, out } = await runCapturingStderr(["verify", "--cwd", dir, "--docs"]);
@@ -218,12 +232,12 @@ describe("meta verify --docs — a git-ignored page is not drift", () => {
 
   test("...and a REAL edit to one of the two committed pages still convicts", async () => {
     // The other half. A rule that exempts everything is not a fix, it is a mute button.
-    const dir = gitProject("docs/*\n!docs/requirements.md\n!docs/requirements.toon\n");
+    const dir = gitProject("docs/generated/*\n!docs/generated/requirements.md\n!docs/generated/requirements.toon\n");
     try {
       await generateDocs(dir);
-      git(dir, "add", "-f", ".gitignore", "docs/requirements.md", "docs/requirements.toon");
+      git(dir, "add", "-f", ".gitignore", "docs/generated/requirements.md", "docs/generated/requirements.toon");
       git(dir, "commit", "-qm", "docs");
-      writeFileSync(join(dir, "docs", "requirements.md"), "hand-edited\n");
+      writeFileSync(join(dir, DOCS_ROOT, "requirements.md"), "hand-edited\n");
 
       const { exit, out } = await runCapturingStderr(["verify", "--cwd", dir, "--docs"]);
       expect(exit).toBe(1);
@@ -238,12 +252,12 @@ describe("meta verify --docs — a git-ignored page is not drift", () => {
   test("a TRACKED page is compared even when a pattern would ignore it", async () => {
     // The property the whole design rests on: git never reports a tracked path as
     // ignored. So this rule can never be used to hide a page the project commits.
-    const dir = gitProject("docs/\n");
+    const dir = gitProject("docs/generated/\n");
     try {
       await generateDocs(dir);
-      git(dir, "add", "-f", ".gitignore", "docs/agent/schema.md");
+      git(dir, "add", "-f", ".gitignore", "docs/generated/agent/schema.md");
       git(dir, "commit", "-qm", "docs");
-      writeFileSync(join(dir, "docs", "agent", "schema.md"), "hand-edited\n");
+      writeFileSync(join(dir, DOCS_ROOT, "agent", "schema.md"), "hand-edited\n");
 
       const { exit, out } = await runCapturingStderr(["verify", "--cwd", dir, "--docs"]);
       expect(exit).toBe(1);
@@ -255,7 +269,7 @@ describe("meta verify --docs — a git-ignored page is not drift", () => {
 
   test("ignoring EVERYTHING is refused, not reported clean", async () => {
     // A gate asked to check pages that could check none must not answer "no drift".
-    const dir = gitProject("docs/\n");
+    const dir = gitProject("docs/generated/\n");
     try {
       await generateDocs(dir);
       git(dir, "add", "-f", ".gitignore");
@@ -277,7 +291,7 @@ describe("meta verify --docs — a git-ignored page is not drift", () => {
       await generateDocs(dir);
       git(dir, "add", "-f", "docs");
       git(dir, "commit", "-qm", "docs");
-      rmSync(join(dir, "docs", "README.md"));
+      rmSync(join(dir, DOCS_ROOT, "README.md"));
 
       const { exit, out } = await runCapturingStderr(["verify", "--cwd", dir, "--docs"]);
       expect(exit).toBe(1);
@@ -300,14 +314,14 @@ describe("meta verify --docs — a git-ignored page is not drift", () => {
     // Untracked on purpose: git never reports a TRACKED path as ignored (the test
     // above), so the only way to reach this branch is the real-world shape — a leftover
     // generated page on a machine that has run `meta docs`, under an ignored path.
-    const dir = gitProject("docs/agent/stale-page.md\n");
+    const dir = gitProject("docs/generated/agent/stale-page.md\n");
     try {
       await generateDocs(dir);
       git(dir, "add", "-f", ".gitignore", "docs");
       git(dir, "commit", "-qm", "docs");
       // Ours by both halves of `isOurs`: under `agent/`, carrying the generated marker.
       writeFileSync(
-        join(dir, "docs", "agent", "stale-page.md"),
+        join(dir, DOCS_ROOT, "agent", "stale-page.md"),
         "<!-- @generated by meta docs -->\n\nA page a fresh run no longer emits.\n",
       );
 
@@ -330,13 +344,13 @@ describe("meta verify --docs — a git-ignored page is not drift", () => {
     // Stated as a CONTRAST on one fixture, because that is the only form that proves
     // the exemption is what produced the clean run: the same project, the same missing
     // page, exempt when git can answer and convicted when it cannot.
-    const dir = gitProject("docs/*\n!docs/requirements.md\n!docs/requirements.toon\n");
+    const dir = gitProject("docs/generated/*\n!docs/generated/requirements.md\n!docs/generated/requirements.toon\n");
     try {
       await generateDocs(dir);
-      git(dir, "add", "-f", ".gitignore", "docs/requirements.md", "docs/requirements.toon");
+      git(dir, "add", "-f", ".gitignore", "docs/generated/requirements.md", "docs/generated/requirements.toon");
       git(dir, "commit", "-qm", "docs");
       // An ignored page that is NOT on disk — the fresh-clone shape.
-      rmSync(join(dir, "docs", "README.md"));
+      rmSync(join(dir, DOCS_ROOT, "README.md"));
 
       const withGit = await runCapturingStderr(["verify", "--cwd", dir, "--docs"]);
       expect(withGit.exit).toBe(0);
@@ -361,18 +375,18 @@ describe("meta verify --docs — a git-ignored page is not drift", () => {
     // The exemption is computed over the fresh set BY NAME, on disk or not. Deciding
     // per-file-existence would have made `checked` a property of the machine: a dev box
     // that has run `meta docs` has all 589 pages present and a CI runner has two.
-    const body = "docs/*\n!docs/requirements.md\n!docs/requirements.toon\n";
+    const body = "docs/generated/*\n!docs/generated/requirements.md\n!docs/generated/requirements.toon\n";
     const withPages = gitProject(body);
     const withoutPages = gitProject(body);
     try {
       for (const dir of [withPages, withoutPages]) {
         await generateDocs(dir);
-        git(dir, "add", "-f", ".gitignore", "docs/requirements.md", "docs/requirements.toon");
+        git(dir, "add", "-f", ".gitignore", "docs/generated/requirements.md", "docs/generated/requirements.toon");
         git(dir, "commit", "-qm", "docs");
       }
       // One machine keeps every locally generated page; the other is a fresh clone.
-      rmSync(join(withoutPages, "docs", "README.md"));
-      rmSync(join(withoutPages, "docs", "agent"), { recursive: true, force: true });
+      rmSync(join(withoutPages, DOCS_ROOT, "README.md"));
+      rmSync(join(withoutPages, DOCS_ROOT, "agent"), { recursive: true, force: true });
 
       const a = await runCapturingStderr(["verify", "--cwd", withPages, "--docs"]);
       const b = await runCapturingStderr(["verify", "--cwd", withoutPages, "--docs"]);