@@ -7,6 +7,51 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### `meta gen --baseline=adopt` — the first run a pre-manifest project can actually perform
+
+The no-manifest refusal LED with *"ONE-TIME FIX: commit
+`.metaobjects/.gen-state/.hashes.json`"*, which the population it names cannot do: nothing
+writes a manifest until a `gen` succeeds, and a run where every file refuses writes none.
+So there was nothing to commit, and the next run refused identically. The only escape was
+`--baseline=fresh`, correctly framed as the lossy one — an adopter whose committed output
+was already a byte-identical regen still had to reason past a warning about losing work.
+Found by an adopter estate running the release candidate: 50 files refused, and the leading
+instruction was unfollowable.
+
+`--baseline=adopt` separates the two things `fresh` does at once. It records the files you
+HAVE as the merge base and **writes nothing**, so the manifest exists to commit and the
+regeneration arrives on the next run as its own reviewable diff. Placed at the refusal
+rather than at the top of the decision, so it can only ever convert a refusal into a
+recorded baseline: `unchanged` and the pristine-file overwrite a fresh clone depends on
+behave exactly as they do without the flag.
+
+**What adopting declares, stated because the name invites the other reading:** that the
+files you have *are* generated output. It protects edits made from that point on — they
+finally have a base to merge against — but an edit already inside one of those files
+becomes part of the base, so the next `gen` replaces it. The message says so, and a test
+pins it. Where the edit is the point, the sequence that keeps it is unchanged and still
+needs `--baseline=fresh` (see [own-your-codegen](docs/features/own-your-codegen.md)).
+
+Shipped in **TypeScript, Python and C#** — the three ports with a hash manifest. A new
+`adopted` write status carries it through the reporting layer rather than being folded
+into `unchanged`, because the run's whole product is the manifest and a summary that hid
+it would defeat the point. `fresh` remains TypeScript-only; Python and C# REFUSE that
+value with a message naming what they do implement, rather than accepting it and refusing
+files anyway.
+
+### BREAKING — a refused file now FAILS `gen` on Python and C# (exit 1), as it always has on TypeScript
+
+`metaobjects gen` and `dotnet meta gen` printed the refusal warning and exited **0**. An
+adopter who wired either into CI as a drift gate was therefore green while codegen was
+refusing to write — the gate did not gate, and nothing in the docs said so. TypeScript has
+exited 1 on a refusal since the manifest shipped.
+
+The three ports now agree. A build that starts failing on this was already unprotected,
+and the failure names its own remedy (`--baseline=adopt` above). Found while probing the
+adopt work, not by a gate: no conformance corpus covers CLI exit codes, and the
+divergence had no test on either side.
+
+
 ### BREAKING — the default provider composition registered vocabulary no other port has
 
 `forgeTypesProvider` leaves `defaultLoadMemoryProviders` and `meta types`. A `decision` /
 
@@ -36,6 +36,16 @@ You run a `gen` step. The runner:
      and the token, so an `@`-prefixed tag does not match it. Remove that token and
      regeneration never touches the file again.
 
+   **A refusal FAILS the run — exit 1 on every port** (TypeScript always did; Python and
+   C# warned and exited 0 until 1.0, so a `gen` wired into CI was green while codegen
+   refused to write). The one-time fix for a project that predates the committed manifest
+   is **`gen --baseline=adopt`**: it records the files you have as the baseline and writes
+   nothing, so there is finally a `.hashes.json` to commit — then `gen` again, and the
+   regeneration lands as its own diff. Adopting DECLARES those files to be generated
+   output, so an edit already inside one is part of the baseline and that regeneration
+   replaces it; commit before you run it. (TypeScript additionally has
+   `--baseline=fresh`: write fresh output now and discard the edits.)
+
    **The two rules protect a hand edit in opposite ways, so do not carry a habit across
    ports.** On TypeScript, C# and Python, *editing the content* is what takes ownership —
    that is what breaks the hash — and deleting the header changes nothing except your
 
@@ -272,6 +272,15 @@ refused, path named, exit 1). So the merge is machine-local: a file you edited a
 pushed is REFUSED on a fresh clone or in CI, not merged. Recovery is in
 `docs/features/own-your-codegen.md`.
 
+A project with NO manifest at all (it predates the manifest being committed) is a
+different case with a different fix: every stale file refuses, and a run where everything
+refuses writes no manifest — so "commit `.hashes.json`" has nothing to commit. Run
+`meta gen --baseline=adopt` once: it records the files you have as the merge base and
+writes nothing, leaving exactly one file to commit; the next `meta gen` is then the
+regeneration, as its own reviewable diff. Adopting declares those files to BE generated
+output, so an edit already inside one is part of the base and that regeneration replaces
+it — `--baseline=fresh` + `git checkout` is the sequence that KEEPS an edit.
+
 Hand-customizations that metadata can't express go in a sibling module you create and
 import yourself — `<Entity>.extra.ts` by convention. The name carries no tool behaviour:
 the file is safe because codegen writes only the paths it records, and the generated
 
@@ -120,6 +120,42 @@ at `-Dmeta.verify.templateRoot`). The one goal covers BOTH Java (`codegen-spring
 migrate engine, ADR-0015"); an unknown mode fails listing the valid ones. (Schema `--db` remains
 Node-only by the ADR-0015 design — see below.)
 
+## `gen` refuses rather than guesses — and `--baseline` is how you answer it
+
+Every port's `gen` decides per file whether it may overwrite, from a committed hash
+manifest (`.metaobjects/.gen-state/.hashes.json`). A file that still hashes to what the
+generator recorded writing is safe to overwrite; one that was edited, or that no record
+covers, is **refused by name and left exactly as it is**.
+
+**A refusal fails the run — exit 1 — on every port.** TypeScript has always done this;
+Python and C# printed the warning and exited 0 until 1.0, so an adopter who wired `gen`
+into CI as a drift gate was green while codegen was refusing to write. If a build starts
+failing on this at 1.0, it was already not protecting anything; the remedy below is the
+one-time fix.
+
+| flag | ports | what it does |
+|---|---|---|
+| `--baseline=default` | all | the above: refuse what cannot be proved to be generated output |
+| `--baseline=adopt` | TS · Python · C# | record the files you HAVE as the merge base and **write nothing** |
+| `--baseline=fresh` | TS only | overwrite the refused files from fresh output and re-baseline (**discards** hand edits) |
+
+**`adopt` exists because the refusal's own remedy was unreachable.** It told you to commit
+`.hashes.json` — but nothing writes a manifest until a `gen` succeeds, and a run where
+every file refuses writes none, so there was nothing to commit and the next run refused
+identically. `adopt` breaks that loop: it records what is on disk, writes not one byte of
+output, and leaves exactly one file to commit. Then `gen` again, and the regeneration
+arrives as its own reviewable diff.
+
+**What adopting declares** — say this out loud before running it: that the files you have
+*are* generated output. It protects edits made from that point on, because they finally
+have a base to merge against. An edit already inside one of those files becomes part of
+the base, so the next `gen` will replace it. Commit first, then read that second diff.
+Where the edit is the point, the sequence that keeps it is in
+[own-your-codegen](own-your-codegen.md#recovering-a-refused-file-on-a-machine-that-never-generated-it),
+and it needs `--baseline=fresh` (TypeScript). Python and C# implement `default` and
+`adopt` only; there, discard a refused file by deleting it and re-running, which writes it
+as new.
+
 ## `meta docs` surfaces — and the `agent/` one
 
 `meta docs` writes MARKDOWN, from metadata, into `docs.outDir` (default `./docs`). It
 
@@ -34,14 +34,29 @@ into an excluded directory, so the negation below it can never take effect — t
 would stay ignored and you would get none of this. `.gen-state/*` excludes the directory's
 *contents*, which leaves the negation able to re-include one of them.
 
-Then commit the manifest:
+Then produce the manifest and commit it:
 
 ```bash
-meta gen                                  # writes .gen-state/.hashes.json
+meta gen --baseline=adopt                 # records what you have; writes NOTHING else
 git add .metaobjects/.gitignore .metaobjects/.gen-state/.hashes.json
 git commit -m "chore: commit the codegen hash manifest"
+meta gen                                  # the regeneration, now on its own
 ```
 
+**Why `--baseline=adopt` and not a plain `meta gen`.** A plain run works only if your
+committed output still matches fresh output. If it does not — an engine or formatter moved
+it, which is the usual state of a project that has not regenerated in a few releases — every
+such file is refused, and a run where *everything* refuses writes **no manifest at all**:
+there is then nothing to commit, and the next run refuses identically. `--baseline=adopt`
+is the run that breaks that loop. It records the files you have as the merge base, writes
+not one byte of output, and leaves you with exactly one file to commit.
+
+**What adopting declares.** That the files you have *are* generated output. It protects
+edits you make from that point on — they now have a base to merge against — but an edit
+already inside one of those files becomes part of the base, so the `meta gen` that follows
+will replace it. Commit before you adopt and read that second diff; if it contains
+something you meant to keep, the "Keep the differences" recipe below is the way to keep it.
+
 ## Why the manifest and not the whole snapshot
 
 `.gen-state/` holds two different things. The snapshot **bodies** are a full second copy of
@@ -82,6 +97,12 @@ That means those files differ from fresh output and there is no hash recording t
   snapshot, and the second merges your version back in.
 - **Discard them.** `meta gen --baseline=fresh` overwrites and adopts fresh output as the
   baseline. This throws away hand edits in generated files, so read the refusal list first.
+- **Adopt what you have, then look.** `meta gen --baseline=adopt` writes nothing and only
+  records the current files as the base, so the refusals stop and the regeneration becomes
+  a separate, reviewable diff on the next run. Use it when you do not yet know whether
+  those differences are edits or just older output — it is the one option that changes no
+  file while you find out. It is not a way to keep an edit: see what adopting declares,
+  above.
 
 Run it once, commit the manifest, and the refusals stop: from then on every machine can
 tell your edits from its own output.
 
@@ -69,6 +69,15 @@ meta gen                         # real three-way merge; reports `merged`, exit
 To **discard** your version instead, `meta gen --baseline=fresh` on its own is the whole
 answer.
 
+`--baseline=adopt` is **not** a third option here, and it is worth saying why, because its
+name invites the mistake. Adopting records what is on disk as the merge base and writes
+nothing — right for a project that has no manifest at all (see
+[the manifest migration guide](migrations/commit-the-gen-state-hash-manifest.md)), where
+there is no other way to produce the file you are asked to commit. But the base it records
+is your *edited* text, so base and working copy are identical and the next `meta gen`
+merges fresh output straight over it. When the edit is the point, use the four-step
+sequence above.
+
 The remedy you will not find here is *"move the edit into a non-generated file"*. It
 works where the edit can live outside the generated file — and does not where the
 artifact is the point of the edit. A `requirementTests()` stub is the standing
 
@@ -36,6 +36,16 @@ You run a `gen` step. The runner:
      and the token, so an `@`-prefixed tag does not match it. Remove that token and
      regeneration never touches the file again.
 
+   **A refusal FAILS the run — exit 1 on every port** (TypeScript always did; Python and
+   C# warned and exited 0 until 1.0, so a `gen` wired into CI was green while codegen
+   refused to write). The one-time fix for a project that predates the committed manifest
+   is **`gen --baseline=adopt`**: it records the files you have as the baseline and writes
+   nothing, so there is finally a `.hashes.json` to commit — then `gen` again, and the
+   regeneration lands as its own diff. Adopting DECLARES those files to be generated
+   output, so an edit already inside one is part of the baseline and that regeneration
+   replaces it; commit before you run it. (TypeScript additionally has
+   `--baseline=fresh`: write fresh output now and discard the edits.)
+
    **The two rules protect a hand edit in opposite ways, so do not carry a habit across
    ports.** On TypeScript, C# and Python, *editing the content* is what takes ownership —
    that is what breaks the hash — and deleting the header changes nothing except your
 
@@ -36,6 +36,16 @@ You run a `gen` step. The runner:
      and the token, so an `@`-prefixed tag does not match it. Remove that token and
      regeneration never touches the file again.
 
+   **A refusal FAILS the run — exit 1 on every port** (TypeScript always did; Python and
+   C# warned and exited 0 until 1.0, so a `gen` wired into CI was green while codegen
+   refused to write). The one-time fix for a project that predates the committed manifest
+   is **`gen --baseline=adopt`**: it records the files you have as the baseline and writes
+   nothing, so there is finally a `.hashes.json` to commit — then `gen` again, and the
+   regeneration lands as its own diff. Adopting DECLARES those files to be generated
+   output, so an edit already inside one is part of the baseline and that regeneration
+   replaces it; commit before you run it. (TypeScript additionally has
+   `--baseline=fresh`: write fresh output now and discard the edits.)
+
    **The two rules protect a hand edit in opposite ways, so do not carry a habit across
    ports.** On TypeScript, C# and Python, *editing the content* is what takes ownership —
    that is what breaks the hash — and deleting the header changes nothing except your
 
@@ -36,6 +36,16 @@ You run a `gen` step. The runner:
      and the token, so an `@`-prefixed tag does not match it. Remove that token and
      regeneration never touches the file again.
 
+   **A refusal FAILS the run — exit 1 on every port** (TypeScript always did; Python and
+   C# warned and exited 0 until 1.0, so a `gen` wired into CI was green while codegen
+   refused to write). The one-time fix for a project that predates the committed manifest
+   is **`gen --baseline=adopt`**: it records the files you have as the baseline and writes
+   nothing, so there is finally a `.hashes.json` to commit — then `gen` again, and the
+   regeneration lands as its own diff. Adopting DECLARES those files to be generated
+   output, so an edit already inside one is part of the baseline and that regeneration
+   replaces it; commit before you run it. (TypeScript additionally has
+   `--baseline=fresh`: write fresh output now and discard the edits.)
+
    **The two rules protect a hand edit in opposite ways, so do not carry a habit across
    ports.** On TypeScript, C# and Python, *editing the content* is what takes ownership —
    that is what breaks the hash — and deleting the header changes nothing except your
 
@@ -36,6 +36,16 @@ You run a `gen` step. The runner:
      and the token, so an `@`-prefixed tag does not match it. Remove that token and
      regeneration never touches the file again.
 
+   **A refusal FAILS the run — exit 1 on every port** (TypeScript always did; Python and
+   C# warned and exited 0 until 1.0, so a `gen` wired into CI was green while codegen
+   refused to write). The one-time fix for a project that predates the committed manifest
+   is **`gen --baseline=adopt`**: it records the files you have as the baseline and writes
+   nothing, so there is finally a `.hashes.json` to commit — then `gen` again, and the
+   regeneration lands as its own diff. Adopting DECLARES those files to be generated
+   output, so an edit already inside one is part of the baseline and that regeneration
+   replaces it; commit before you run it. (TypeScript additionally has
+   `--baseline=fresh`: write fresh output now and discard the edits.)
+
    **The two rules protect a hand edit in opposite ways, so do not carry a habit across
    ports.** On TypeScript, C# and Python, *editing the content* is what takes ownership —
    that is what breaks the hash — and deleting the header changes nothing except your