@@ -363,6 +363,47 @@ longer registered by default**. Metadata carrying any of them fails the load wit
   `writeRecord`, `listRecords`, `promoteRecord`, `supersede`, …). Nothing in the library
   and no adopter estate imported them.
 
+## 13. Two tool-state defaults that move at the cut
+
+Neither is metadata — no `metamodelVersion` move, no vocabulary change — but both are
+adopter-visible, so they are here rather than only in the changelog.
+
+### `meta docs` now defaults `outDir` to `./docs/generated`
+
+It was `./docs`, which in most repositories is the *human* documentation folder. A bare
+`meta docs` scattered 29 generated pages through one estate's `docs/` — a business-strategy
+document, product screenshots, email drafts — and wanted to own `docs/README.md`. The docs
+drift gate's own rule is that `docs.outDir` is a directory, not a namespace MetaObjects
+owns, which is precisely the argument against defaulting into the most-owned directory name
+in the ecosystem.
+
+**If you were relying on the old default**, pin it explicitly — one line, and your pages
+stay exactly where they are:
+
+```ts
+export default defineConfig({
+  docs: { outDir: "./docs" },
+});
+```
+
+Otherwise the next `meta docs` writes to `docs/generated/` and `meta verify --docs`
+measures there. `meta init` now scaffolds the key, so a new project's choice is visible
+rather than implied. (`--out` is still a per-run override; it does not persist, which is
+why the config key is what a gate needs.)
+
+### Python: `.gen-state/.hashes.json` keys are project-relative
+
+The manifest lives at the project root, and its keys were relative to `--out`. Two runs
+with different `--out` therefore shared one manifest keyed by names that mean different
+files, and the manifest is the only thing that can tell "this is exactly what I wrote"
+from "somebody edited this" on a machine that did not generate the code. The multi-target
+path (`metaobjects.config.yaml`) had the same shape by construction. Keys are now relative
+to the project, as the TypeScript port's have always been.
+
+**Nothing to do.** The old spelling is read as a fallback and dropped the next time each
+file is recorded, so an existing manifest keeps working and converges on its own. The
+first `metaobjects gen` after upgrading will rewrite the keys; commit the result.
+
 ## Additive in 1.0 (no migration required)
 
 - **`field.uri` / `field.inet` subtypes + `@stringFormat`** (`email` / `hostname`)
 
@@ -44,6 +44,7 @@
 import argparse
 import dataclasses
 import json
+import os
 import re
 import sys
 import tempfile
@@ -376,6 +377,7 @@ def _run_suite(
     emit_package_init: bool = True,
     gen_state_dir: str | None = None,
     column_naming: str = DEFAULT_COLUMN_NAMING,
+    project_root: str | None = None,
 ) -> list[str]:
     """Run a generator suite against an ALREADY-LOADED ``root`` into ``out_dir``.
 
@@ -405,6 +407,11 @@ def _run_suite(
         emit_package_init=emit_package_init,
         gen_state_dir=gen_state_dir,
         column_naming=column_naming,
+        # Manifest keys are relative to the PROJECT, which is what the manifest is
+        # anchored on — not to ``--out``, which varies per run while the manifest does
+        # not. Passed alongside gen_state_dir because the two are one decision: state
+        # that lives in the project must be keyed by the project.
+        project_root=project_root,
     )
     suite = generators if generators is not None else _default_generators()
     result = run_gen(config, root, generators=suite, entity_filter=entity_filter)
@@ -792,10 +799,14 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             print(f"  {msg}", file=sys.stderr)
         return 1
     gen_state = gen_state_dir_for(args.metadata_dir)
+    # Same anchor the manifest itself uses. Both passes below key against it, so a
+    # `--template-spec` artifact and a default-suite artifact land in one key space.
+    gen_project_root = str(project_root_for(args.metadata_dir))
     column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
     written = _run_suite(
         root, args.out, generators, entities,
         gen_state_dir=gen_state, column_naming=column_naming,
+        project_root=gen_project_root,
     )
     if spec_gens:
         # The template-spec pass renders user-supplied templates: a bad ref or a
@@ -807,6 +818,7 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             spec_written = _run_suite(
                 root, args.out, spec_gens, entities, emit_package_init=False,
                 gen_state_dir=gen_state, column_naming=column_naming,
+                project_root=gen_project_root,
             )
         except RenderError as exc:
             print(
@@ -828,9 +840,15 @@ def _run_gen_targets(
     root: MetaData,
     *,
     gen_state_dir: str | None = None,
+    project_root: str | None = None,
 ) -> tuple[list[str], list[str]]:
     """Run each target's suite into its ``outDir``. Returns (all_written, errors).
 
+    This is the path the manifest keying matters most on: every target writes into its
+    OWN ``outDir`` while all of them share ONE ``gen_state_dir``, so out-dir-relative
+    keys meant target B's hash could claim ownership of target A's identically-named
+    file. ``project_root`` is the common anchor that makes the keys distinct.
+
     Cross-target duplicate-output-path guard (#267): ``run_gen``'s collision guard
     is per-pass, so two targets writing the same full path would silently clobber
     (generated files carry the @generated header). We accumulate every written full
@@ -851,7 +869,8 @@ def _run_gen_targets(
         out_dir = config.out_dir_for(t)
         try:
             written = _run_suite(
-                root, out_dir, gens, t.entities, gen_state_dir=gen_state_dir
+                root, out_dir, gens, t.entities, gen_state_dir=gen_state_dir,
+                project_root=project_root,
             )
         except ValueError as exc:  # intra-target run_gen collision → clean error
             errors.append(f"target '{t.name}': {exc}")
@@ -921,6 +940,7 @@ def _cmd_gen_neutral_fallback(args: argparse.Namespace) -> int:
     written = _run_suite(
         root, args.out, generators, entities,
         gen_state_dir=gen_state, column_naming=column_naming,
+        project_root=str(root_dir.resolve()),
     )
     for path in written:
         print(path)
@@ -982,7 +1002,9 @@ def _cmd_gen_config(args: argparse.Namespace) -> int:
         return 1
 
     written, errors = _run_gen_targets(
-        config, targets, root, gen_state_dir=gen_state_dir_for(config.metadata_dir())
+        config, targets, root,
+        gen_state_dir=gen_state_dir_for(config.metadata_dir()),
+        project_root=str(project_root_for(config.metadata_dir())),
     )
     if errors:
         for msg in errors:
@@ -1033,28 +1055,44 @@ def _relative_set(root: Path) -> dict[str, str]:
     return files
 
 
-def _is_ours_for(gen_state_dir: str | None):
+def _is_ours_for(gen_state_dir: str | None, out_prefix: str = ""):
     """Jurisdiction predicate for the ``extra`` verdict: did WE write this path?
 
     ``out_dir`` is a DIRECTORY, not a namespace this tool owns — the same ruling the
     TypeScript gate reached (0.24.3), for the same reason. Broadening the comparison
     beyond ``*.py`` means the gate now sees every stranger's file too, and convicting
     those turns a project with zero drift into a red build.
 
-    The manifest already records what we WROTE, keyed relative to ``out_dir`` — the
-    same key space this diff uses — so it answers the ownership question exactly.
+    The manifest already records what we WROTE, so it answers the ownership question
+    exactly — but it is keyed relative to the PROJECT while this diff is keyed relative
+    to ``out_dir``. ``out_prefix`` (the out dir, relative to the project) is what turns
+    one into the other. Getting this wrong is silent in the direction that matters: a
+    lookup that finds nothing makes ``is_ours`` false for every file, and the gate simply
+    stops reporting stale output while still printing a clean verdict.
+
+    The out-dir-relative name is tried as a fallback, because that is how a manifest
+    written before the re-keying spells it — the same fallback ``decide_and_write``
+    makes, so the write path and the gate cannot disagree about which entry is a record
+    of this file.
+
     FAILS CLOSED, matching :func:`is_pristine_generated`: with no manifest at all
     nothing is proven, so every file stays in scope and the old verdict stands.
     """
     if gen_state_dir is None or not has_hash_manifest(gen_state_dir):
         return lambda _rel: True
-    return lambda rel: read_generated_hash(gen_state_dir, rel) is not None
+
+    def is_ours(rel: str) -> bool:
+        key = os.path.join(out_prefix, rel) if out_prefix else rel
+        return read_generated_hash(gen_state_dir, key, legacy_rel_path=rel) is not None
+
+    return is_ours
 
 
 def _diff_report(
     expected: dict[str, str],
     committed: dict[str, str],
     gen_state_dir: str | None = None,
+    out_prefix: str = "",
 ) -> int:
     """Compare a regenerated file map against the committed one; print the
     standard ``verify --codegen`` drift report. Returns 0 (in sync) or 1.
@@ -1065,8 +1103,11 @@ def _diff_report(
 
     ``gen_state_dir`` scopes the ``extra`` verdict to files we have a record of
     writing — see :func:`_is_ours_for`. Omit it to keep the unscoped verdict.
+    ``out_prefix`` is the committed out dir relative to the project, which is what
+    translates this diff's out-dir-relative keys into the manifest's project-relative
+    ones; omit it only when the two coincide.
     """
-    is_ours = _is_ours_for(gen_state_dir)
+    is_ours = _is_ours_for(gen_state_dir, out_prefix)
     changed = sorted(
         k for k in expected if k in committed and expected[k] != committed[k]
     )
@@ -1179,7 +1220,14 @@ def _verify_codegen(args: argparse.Namespace) -> int:
         expected = _relative_set(Path(tmp))
         committed = _relative_set(Path(args.out))
 
-    return _diff_report(expected, committed, gen_state_dir_for(args.metadata_dir))
+    # The manifest is keyed relative to the project; this diff is keyed relative to
+    # `--out`. Hand over the prefix that translates one into the other, or the
+    # jurisdiction lookup finds nothing and the `extra` verdict silently empties.
+    project_root = project_root_for(args.metadata_dir)
+    return _diff_report(
+        expected, committed, gen_state_dir_for(args.metadata_dir),
+        os.path.relpath(Path(args.out).resolve(), project_root),
+    )
 
 
 def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
@@ -1234,7 +1282,8 @@ def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
     # `_cmd_gen_neutral_fallback` writes its manifest to), so the jurisdiction lookup
     # must be built from that, not from args.metadata_dir (None here by definition).
     return _diff_report(
-        expected, committed, str(root_dir.resolve() / ".metaobjects" / ".gen-state")
+        expected, committed, str(root_dir.resolve() / ".metaobjects" / ".gen-state"),
+        os.path.relpath(Path(args.out).resolve(), root_dir.resolve()),
     )
 
 
@@ -1351,7 +1400,16 @@ def _verify_codegen_config(args: argparse.Namespace) -> int:
             # Same jurisdiction rule as _diff_report — this rung inlines its diff to
             # report per-target, so the guard has to be inlined with it. Without it,
             # broadening the comparison past *.py convicts every stranger's file.
-            is_ours = _is_ours_for(gen_state_dir_for(config.metadata_dir()))
+            #
+            # PER-TARGET prefix, because that is the whole point on this rung: two
+            # targets with different outDirs share one manifest, and the key that tells
+            # their identically-named files apart is the one anchored on the project.
+            is_ours = _is_ours_for(
+                gen_state_dir_for(config.metadata_dir()),
+                os.path.relpath(
+                    Path(real_outdir).resolve(), project_root_for(config.metadata_dir())
+                ),
+            )
             extra = sorted(k for k in committed if k not in expected and is_ours(k))
 
             names = "+".join(
 
@@ -17,6 +17,22 @@ class GenConfig:
     # ``<project>/.metaobjects/.gen-state``. COMMIT the manifest: it is the only thing
     # that makes hand-edit detection work on a machine that did not generate the code.
     gen_state_dir: str | None = None
+    # The project the manifest belongs to — the directory holding ``metaobjects/`` and
+    # ``.metaobjects/``. Manifest keys are relative to THIS, not to ``out_dir``.
+    #
+    # They used to be out-dir-relative while the manifest itself is anchored on the
+    # project, so two runs with different ``--out`` shared one manifest keyed by names
+    # that mean different files: `gen --out /tmp/a` and `gen --out /tmp/b` both record
+    # `alarm_names.py`, and run B's hash then claims ownership of run A's file. The
+    # manifest is the only thing that can tell "this is exactly what I wrote" from
+    # "somebody edited this" on a machine that did not generate the code, so one that can
+    # be populated from an unrelated tree and keyed ambiguously is one that can say yes to
+    # the wrong file. TS keys project-root-relative, which is also what makes multiple
+    # output targets work.
+    #
+    # None keeps the out-dir-relative keys, so a programmatic caller that never had a
+    # project root is unchanged. The CLI always sets it.
+    project_root: str | None = None
     # Only "flat" is implemented; a non-default value is REFUSED below rather than
     # silently ignored (see __post_init__).
     output_layout: str = "flat"
 
@@ -46,15 +46,14 @@ def content_hash(content: str) -> str:
     Same algorithm as every other port, so identical file content hashes identically
     everywhere.
 
-    The KEYS, however, deliberately differ: TypeScript keys by path relative to the
-    PROJECT ROOT (it supports multiple output targets), while this port and C# key
-    relative to their single out dir. A manifest is therefore NOT portable between
-    ports. An earlier version of this docstring claimed a conformance fixture could
-    compare them directly — it cannot, and the claim was never true.
-
-    Because the key here is out-dir-relative, running gen twice with different out dirs
-    against ONE ``gen_state_dir`` collides two distinct files onto one key. Give each
-    out dir its own gen-state dir.
+    The KEYS are relative to the PROJECT ROOT, as TypeScript's are — the manifest is
+    anchored on the project, so a key that means "this name, relative to whichever out
+    dir ran last" made two runs with different ``--out`` share one manifest in which run
+    B's hash claimed ownership of run A's file. (There is no per-out-dir gen-state dir to
+    escape into: ``gen_state_dir`` is derived from the metadata directory, so the advice
+    this docstring used to give could not be followed.) A manifest is still NOT portable
+    between ports — an earlier version of this docstring claimed a conformance fixture
+    could compare them directly, and it never could.
     """
     return hashlib.sha256(content.encode("utf-8")).hexdigest()
 
@@ -100,23 +99,47 @@ def _save_hashes(gen_state_dir: str, hashes: dict[str, str]) -> None:
         fh.write("\n")
 
 
-def read_generated_hash(gen_state_dir: str, rel_path: str) -> str | None:
-    """The hash recorded when we last wrote ``rel_path``, or None if never."""
-    return _load_hashes(gen_state_dir).get(rel_path)
+def read_generated_hash(
+    gen_state_dir: str, rel_path: str, legacy_rel_path: str | None = None
+) -> str | None:
+    """The hash recorded when we last wrote ``rel_path``, or None if never.
+
+    ``legacy_rel_path`` is the OUT-DIR-relative key the same file was recorded under
+    before keys became project-root-relative. Reading both is what keeps the re-keying
+    from invalidating every existing manifest: without it a previously-recorded file
+    becomes unrecorded, which is fail-closed (``gen`` REFUSES it) but makes every
+    adopter regenerate to get past a change they did not ask for. The legacy entry is
+    dropped the next time the file is recorded, so a manifest converges on one spelling
+    without a migration command.
+    """
+    hashes = _load_hashes(gen_state_dir)
+    recorded = hashes.get(rel_path)
+    if recorded is None and legacy_rel_path is not None:
+        return hashes.get(legacy_rel_path)
+    return recorded
 
 
-def is_pristine_generated(gen_state_dir: str, rel_path: str, current: str) -> bool:
+def is_pristine_generated(
+    gen_state_dir: str, rel_path: str, current: str, legacy_rel_path: str | None = None
+) -> bool:
     """Whether the file is byte-for-byte what we recorded writing.
 
     FAILS CLOSED — False when it cannot be proven.
     """
-    recorded = read_generated_hash(gen_state_dir, rel_path)
+    recorded = read_generated_hash(gen_state_dir, rel_path, legacy_rel_path)
     return recorded is not None and recorded == content_hash(current)
 
 
-def _record(gen_state_dir: str, rel_path: str, content: str) -> None:
+def _record(
+    gen_state_dir: str, rel_path: str, content: str, legacy_rel_path: str | None = None
+) -> None:
     hashes = _load_hashes(gen_state_dir)
     hashes[rel_path] = content_hash(content)
+    # Drop the pre-re-keying spelling in the same write. Leaving it would keep a key
+    # that means "this name, relative to whichever out dir ran last" alive forever —
+    # which is the ambiguity being removed.
+    if legacy_rel_path is not None and legacy_rel_path != rel_path:
+        hashes.pop(legacy_rel_path, None)
     _save_hashes(gen_state_dir, hashes)
 
 
@@ -133,17 +156,22 @@ def decide_and_write(
     *,
     gen_state_dir: str | None = None,
     rel_path: str | None = None,
+    legacy_rel_path: str | None = None,
 ) -> str:
     """Decide and perform the write for one generated file.
 
     ``gen_state_dir`` enables hash-based hand-edit detection; ``rel_path`` is the key
     it is recorded under (defaults to the basename, which is correct for a single
-    flat output directory).
+    flat output directory). ``legacy_rel_path`` is the key the same file may already
+    be recorded under from before keys became project-root-relative — read as a
+    fallback, and removed once the file is recorded under the new key.
     """
     if not os.path.exists(path):
         _write(path, content)
         if gen_state_dir is not None:
-            _record(gen_state_dir, rel_path or os.path.basename(path), content)
+            _record(
+                gen_state_dir, rel_path or os.path.basename(path), content, legacy_rel_path
+            )
         return "new"
 
     if strategy == "skip-existing":
@@ -165,12 +193,12 @@ def decide_and_write(
     if current == content:
         # Nothing to do, but record it: a first run over already-correct output should
         # leave the file recognisable as ours next time.
-        _record(gen_state_dir, key, content)
+        _record(gen_state_dir, key, content, legacy_rel_path)
         return "unchanged"
 
-    if is_pristine_generated(gen_state_dir, key, current):
+    if is_pristine_generated(gen_state_dir, key, current, legacy_rel_path):
         _write(path, content)
-        _record(gen_state_dir, key, content)
+        _record(gen_state_dir, key, content, legacy_rel_path)
         return "overwrite"
 
     # Edited, or never recorded. Deliberately does NOT record the current content: