fix(migrate): only advance the snapshot when a migration was written

Independent review of the preceding three commits found the new guard
(`!dryRun && exitCode === 0 && !applyFailed`) also fires on the zero-change
branch, where the live path writes nothing. Reproduced on a real sqlite engine:
a database already matching its metadata but reached WITHOUT any committed
migration — a restored dump, hand-run DDL, an adopted DB — turned a plain
`meta migrate --from-db` drift check into an implicit baseline. It recorded the
target schema as already-applied with zero CREATE TABLE anywhere, so the offline
path reported `no changes` permanently and `apply-pending` provisioned an empty
database on CI. That is the 0.20.1 greenfield-baseline trap re-entered through a
different door.

The snapshot means "the schema the committed migrations land you in", so it now
advances exactly when this run wrote one — the rule runOfflineGenerate already
follows, returning on `no changes` before writing. Both motivating scenarios
(greenfield --from-db --apply, and --apply without --from-db) always write files,
so neither regresses; re-verified end to end in a cold project.

Also from the review:

- The snapshot carries the engine version introspection just captured. Writing
  bare `expected` dropped `meta.sqliteVersion`, which `emit` reads to choose
  native ALTER vs recreate-and-copy; on SQLite < 3.35 a later offline migration
  would have been un-appliable.
- A writeSnapshot failure is reported as itself rather than surfacing as
  "unexpected error" after the migration already applied.
- The post-write hint said "apply with `meta migrate --db <url> --apply`",
  which re-runs the diff: it demands --slug again (exit 2) and, if given one,
  emits a second migration with the same DDL. Now `meta migrate apply-pending
  --db <url>` (#242), verified by running the hint verbatim.
- Two stale `258` fixture counts survived in the files the refresh targeted
  (README.md, spec/roadmap.md); both are 260.
- "`--dialect` is always required" was false and contradicted the CLI's own
  --help: it is required offline and on `baseline`, and auto-detected from the
  URL scheme with `--db`. Corrected in the skill, its reference and both llms
  files.
- CHANGELOG [Unreleased] now states its registry scope (npm · PyPI · NuGet;
  Maven has no changed product file) and covers the agent-context fix, which
  ships to adopters in three of those packages.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3msoGxjRMwx94PhKSLDuE

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,12 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+**Scope: npm · PyPI · NuGet** — Maven Central has no changed product file (its
+`AgentDocsMojo` no longer scaffolds agent context; it redirects to the Node CLI).
+The migrate fix is npm-only (`@metaobjectsdev/cli`); the agent-context correction
+ships wherever the scaffolded skills ship — `@metaobjectsdev/sdk` on npm, the
+bundled content tree in the PyPI package, and the C# CLI on NuGet.
+
 ### Fixed — the live-DB `meta migrate` path now advances the committed snapshot
 
 The day-1 command `meta init` prints as its next step —
@@ -36,10 +42,50 @@ blocked, refused, or apply-failed run leaves the snapshot untouched rather than
 recording a schema the database is not in. The now-obsolete
 `--from-db did not advance the committed snapshot` warning is gone.
 
+The snapshot advances **exactly when the run wrote a migration** — the rule the
+offline path already follows (it returns on `no changes` before writing). A live
+run that emits nothing leaves it alone: recording the target schema as
+already-applied with no `CREATE TABLE` anywhere would be the greenfield-`baseline`
+trap by another door, leaving the offline path reporting `no changes` forever and
+`apply-pending` provisioning an empty database. The snapshot also now carries the
+engine version introspection just captured, which `emit` reads to choose native
+`ALTER` vs recreate-and-copy on older SQLite.
+
 Gated by a real-engine round-trip (`cli/test/integration/migrate-fromdb-snapshot.test.ts`):
 greenfield `--from-db … --apply` → offline incremental emits a real migration →
-apply → live re-diff converges to empty, plus the `--dry-run` and blocked-change
-no-write assertions.
+apply → live re-diff converges to empty, plus no-write assertions for `--dry-run`,
+a blocked destructive change, and a zero-change live run against a hand-migrated
+database.
+
+### Fixed — the post-write next-step hint named a command that fails
+
+After writing a migration, `meta migrate` printed ``apply with `meta migrate --db
+<url> --apply` ``. That re-runs the diff, so it demands `--slug` again (exit 2) and,
+if given one, emits a *second* migration carrying the same DDL. The hint now names
+`meta migrate apply-pending --db <url>` (#242), which replays what was just written
+with no diff. This matters more alongside the snapshot fix above: the snapshot now
+advances on a files-only run, so the offline path afterwards correctly reports
+`no changes` and no longer doubles as an accidental reminder that something is
+pending.
+
+### Fixed — the migrate guidance shipped to adopters as agent context
+
+The `metaobjects-verify` skill that `meta init` scaffolds into every adopter repo
+(and its `llms.txt` mirror) told agents to run `meta migrate baseline --dialect
+sqlite` on a **fresh** database — the exact greenfield trap `0.20.1` hardened the
+CLI to refuse. An offline baseline derives the "existing" snapshot from the
+metadata, recording the target shape as already applied, so no table is ever
+created and the failure surfaces later at the API layer as `no such table`. An
+agent following the shipped skill walked a newcomer straight into it. Corrected to
+the working `--from-db … --slug init --apply` path, with `baseline --from-db` kept
+for its real use — adopting a database that already has its schema.
+
+Same family, same files: `meta migrate --db <url> --slug <name>` was described as
+"diff metadata vs the live DB", but without `--from-db`/`--apply` that is the
+offline path and `--db` is ignored. Every example now distinguishes the offline,
+live (`--from-db`) and replay (`apply-pending`) forms, and states `--dialect`
+accurately (required offline and on `baseline`; auto-detected from the URL scheme
+when `--db` is given).
 
 ### Fixed — the documented Node server-boot command (`docs/ports/typescript.md`)
 

README.md

@@ -166,7 +166,7 @@ metaobjects/
 ├── CLAUDE.md                       # project instructions for Claude
 ├── spec/                           # canonical metamodel docs, ADRs, roadmap
 ├── fixtures/                       # 19 cross-language conformance corpora — the oracle
-│   ├── conformance/                # metamodel (loader + serializer + navigation), 258 fixtures
+│   ├── conformance/                # metamodel (loader + serializer + navigation), 260 fixtures
 │   ├── yaml-conformance/           # YAML authoring desugar
 │   ├── render-conformance/         # FR-004 byte-identical render oracle
 │   ├── verify-conformance/         # FR-004 template-drift gate

agent-context/skills/metaobjects-verify/SKILL.md

@@ -155,9 +155,11 @@ What this means in practice:
   meta migrate --dialect postgres --slug add-user-shipping --dry-run   # preview without writing
   ```
 
-  `--dialect` is always required — it selects the diff pipeline, not just the SQL
-  flavor. Do **not** run `meta migrate baseline` on a database that does not exist
-  yet; see `references/migration.md`.
+  Always pass `--dialect` — it selects the diff pipeline, not just the SQL flavor.
+  It is *required* on the offline path and on `baseline`; with `--db` the CLI can
+  auto-detect it from the URL scheme, but being explicit keeps the two paths
+  reading the same. Do **not** run `meta migrate baseline` on a database that does
+  not exist yet; see `references/migration.md`.
 
 - Dialects: `postgres` (default), `sqlite`, and `d1` (Cloudflare D1, TS-only).
 - The JVM and Python ports have **no** migration command of their own — their

agent-context/skills/metaobjects-verify/references/migration.md

@@ -82,8 +82,9 @@ meta migrate baseline --from-db --db postgresql://... --dialect postgres
                                                               # diff vs the LIVE database instead
    ```
 
-   `--dialect` is always required and is load-bearing — it selects the diff
-   pipeline, not just the SQL flavor. The default path is offline (`--db` is
+   `--dialect` is load-bearing — it selects the diff pipeline, not just the SQL
+   flavor. It is *required* offline and on `baseline`; with `--db` it is
+   auto-detected from the URL scheme. The default path is offline (`--db` is
    ignored without `--from-db` or `--apply`); pass `--from-db` when you want the
    diff taken against the live database.
 

docs/llms/llms-full.txt

@@ -272,8 +272,8 @@ $ meta verify --codegen      # regen-and-diff vs committed output
 $ meta verify --templates    # prompt {{field}} ↔ payload-VO drift
 $ meta verify --db postgres://...   # live-DB schema drift (Node meta only)
 
-# Emit migration SQL files (Node meta only, used by every port). --dialect is always
-# required — it selects the diff pipeline, not just the SQL flavor.
+# Emit migration SQL files (Node meta only, used by every port). --dialect selects the
+# diff pipeline, not just the SQL flavor: required offline, auto-detected from --db.
 $ meta migrate --from-db --db file:./dev.db --dialect sqlite --slug init --apply  # first migration, brand-new DB
 $ meta migrate --dialect sqlite --slug add-subscriber                             # everyday: diff vs the committed snapshot
 $ meta migrate --dialect sqlite --slug add-subscriber --db file:./dev.db --apply  # ...and apply it

docs/llms/llms.txt

@@ -69,7 +69,7 @@ MetaObjects deliberately does **not** ship one universal binary. Schema operatio
 - `meta init` — scaffold `metaobjects/`, `.metaobjects/`, and `metaobjects.config.ts`, **plus** the agent context: a slim `.metaobjects/AGENTS.md` + `CLAUDE.md` (auto-wired into the project's root `CLAUDE.md`/`AGENTS.md`) and six `metaobjects-*` Claude Code skills under `.claude/skills/` scoped to the project's stack. `meta init --refresh-docs` updates only the agent docs.
 - `meta gen [<entity>...]` — TS codegen from entities defined under `metaobjects/`. Supports `--dry-run` and `--watch`. Generators (`entityFile()`, `queriesFile()`, `routesFile()`, `formFile()`, `tanstackQuery()`, `tanstackGrid()`, `barrel()`) come from `@metaobjectsdev/codegen-ts/generators` (and per-framework siblings) and are wired in `metaobjects.config.ts`. Per-port codegen runs in that port's own build tool: `mvn metaobjects:generate` (Java/Kotlin), `dotnet meta gen` (C#), `metaobjects gen` (Python).
 - `meta verify` — drift check. `verify --codegen` (regen-and-diff vs committed output), `verify --templates` (prompt `{{field}}` ↔ payload-VO drift), `verify --db` (live-DB schema drift, Node `meta` only). Per-port codegen verify: `mvn metaobjects:verify -Dmeta.verify.mode=codegen|templates` (Java/Kotlin), `dotnet meta verify` (C#), `metaobjects verify` (Python).
-- `meta migrate --dialect <d> --slug <name>` — diff metadata vs the committed schema snapshot and emit migration SQL files under `.metaobjects/migrations`; add `--db <url> --apply` to run them. `--dialect` is always required and selects the diff pipeline, not just the SQL flavor. On a brand-new database the first command is `meta migrate --from-db --db <url> --dialect <d> --slug init --apply` (diff against the empty database, emit `CREATE TABLE`, apply, record the snapshot) — **not** `meta migrate baseline`, which is for adopting a database that already has its schema. `meta migrate apply-pending --db <url> --dialect <d>` replays committed migrations with no diff (fresh DB / CI). Supports SQLite (`file:`, `libsql:`), Postgres (`postgres:`, `postgresql:`), and Cloudflare D1 (TS only). `--dry-run` prints SQL to stdout. **Schema migration is owned by the Node `meta` CLI (ADR-0015) and used by every port regardless of backend language** — it is shipped as a standalone binary, so a JVM/Python/C# project needs no per-language migrate engine. There is no Maven, .NET, or Python migrate command.
+- `meta migrate --dialect <d> --slug <name>` — diff metadata vs the committed schema snapshot and emit migration SQL files under `.metaobjects/migrations`; add `--db <url> --apply` to run them. `--dialect` selects the diff pipeline, not just the SQL flavor — required offline and on `baseline`, auto-detected from the URL scheme when `--db` is given. On a brand-new database the first command is `meta migrate --from-db --db <url> --dialect <d> --slug init --apply` (diff against the empty database, emit `CREATE TABLE`, apply, record the snapshot) — **not** `meta migrate baseline`, which is for adopting a database that already has its schema. `meta migrate apply-pending --db <url> --dialect <d>` replays committed migrations with no diff (fresh DB / CI). Supports SQLite (`file:`, `libsql:`), Postgres (`postgres:`, `postgresql:`), and Cloudflare D1 (TS only). `--dry-run` prints SQL to stdout. **Schema migration is owned by the Node `meta` CLI (ADR-0015) and used by every port regardless of backend language** — it is shipped as a standalone binary, so a JVM/Python/C# project needs no per-language migrate engine. There is no Maven, .NET, or Python migrate command.
 - `meta export [--out <file>]` — flatten loaded metadata to one canonical JSON artifact.
 
 ## Monorepo layout

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md

@@ -155,9 +155,11 @@ What this means in practice:
   meta migrate --dialect postgres --slug add-user-shipping --dry-run   # preview without writing
   ```
 
-  `--dialect` is always required — it selects the diff pipeline, not just the SQL
-  flavor. Do **not** run `meta migrate baseline` on a database that does not exist
-  yet; see `references/migration.md`.
+  Always pass `--dialect` — it selects the diff pipeline, not just the SQL flavor.
+  It is *required* on the offline path and on `baseline`; with `--db` the CLI can
+  auto-detect it from the URL scheme, but being explicit keeps the two paths
+  reading the same. Do **not** run `meta migrate baseline` on a database that does
+  not exist yet; see `references/migration.md`.
 
 - Dialects: `postgres` (default), `sqlite`, and `d1` (Cloudflare D1, TS-only).
 - The JVM and Python ports have **no** migration command of their own — their

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-verify/references/migration.md

@@ -82,8 +82,9 @@ meta migrate baseline --from-db --db postgresql://... --dialect postgres
                                                               # diff vs the LIVE database instead
    ```
 
-   `--dialect` is always required and is load-bearing — it selects the diff
-   pipeline, not just the SQL flavor. The default path is offline (`--db` is
+   `--dialect` is load-bearing — it selects the diff pipeline, not just the SQL
+   flavor. It is *required* offline and on `baseline`; with `--db` it is
+   auto-detected from the URL scheme. The default path is offline (`--db` is
    ignored without `--from-db` or `--apply`); pass `--from-db` when you want the
    diff taken against the live database.
 

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-verify/SKILL.md

@@ -155,9 +155,11 @@ What this means in practice:
   meta migrate --dialect postgres --slug add-user-shipping --dry-run   # preview without writing
   ```
 
-  `--dialect` is always required — it selects the diff pipeline, not just the SQL
-  flavor. Do **not** run `meta migrate baseline` on a database that does not exist
-  yet; see `references/migration.md`.
+  Always pass `--dialect` — it selects the diff pipeline, not just the SQL flavor.
+  It is *required* on the offline path and on `baseline`; with `--db` the CLI can
+  auto-detect it from the URL scheme, but being explicit keeps the two paths
+  reading the same. Do **not** run `meta migrate baseline` on a database that does
+  not exist yet; see `references/migration.md`.
 
 - Dialects: `postgres` (default), `sqlite`, and `d1` (Cloudflare D1, TS-only).
 - The JVM and Python ports have **no** migration command of their own — their

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-verify/references/migration.md

@@ -82,8 +82,9 @@ meta migrate baseline --from-db --db postgresql://... --dialect postgres
                                                               # diff vs the LIVE database instead
    ```
 
-   `--dialect` is always required and is load-bearing — it selects the diff
-   pipeline, not just the SQL flavor. The default path is offline (`--db` is
+   `--dialect` is load-bearing — it selects the diff pipeline, not just the SQL
+   flavor. It is *required* offline and on `baseline`; with `--db` it is
+   auto-detected from the URL scheme. The default path is offline (`--db` is
    ignored without `--from-db` or `--apply`); pass `--from-db` when you want the
    diff taken against the live database.