docs(agent-context): correct the migrate guidance shipped to adopters

The `metaobjects-verify` skill — scaffolded into every adopter repo by
`meta init` and mirrored into llms.txt — told agents to run
`meta migrate baseline --dialect sqlite` on a **fresh** database. That is the
exact greenfield trap 0.20.1 refused at the CLI: an offline baseline derives the
"existing" snapshot from the metadata, recording the target shape as already
applied, so no table is ever created, every later migrate reports `no changes`,
and the failure surfaces later at the API layer as `no such table`. An agent
following the shipped skill would have walked a newcomer straight into it.

Corrected to the working greenfield path (`--from-db … --slug init --apply`),
with `baseline --from-db` kept for its real use — adopting a database that
already has its schema. The skill also claimed the no-snapshot hint points at
`baseline`; it points at `--from-db … --apply`.

Also fixes a second inaccuracy in the same family across the skill, its
reference, and both llms 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 passes
`--dialect` — which selects the diff pipeline, not just the SQL flavor — and
distinguishes the offline, live (`--from-db`) and replay (`apply-pending`) forms.

Edited at the canonical `agent-context/` source; the sdk bundle was reproduced
with `bundle-agent-context.mjs` and the four `agent-context-conformance`
goldens regenerated.

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

Author: dmealing

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

@@ -147,11 +147,18 @@ What this means in practice:
   it. You point it at the same database your server connects to:
 
   ```
-  meta migrate --db postgresql://... --slug initial   # emit migration SQL
-  meta migrate --db postgresql://... --apply          # apply pending migrations
-  meta migrate --dry-run                              # preview without writing
+  meta migrate --from-db --db postgresql://... --dialect postgres --slug init --apply
+                                                      # first migration on a brand-new database
+  meta migrate --dialect postgres --slug add-user-shipping          # everyday: emit migration SQL
+  meta migrate --dialect postgres --slug add-user-shipping --apply --db postgresql://...
+                                                      # ...and apply it
+  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`.
+
 - Dialects: `postgres` (default), `sqlite`, and `d1` (Cloudflare D1, TS-only).
 - The JVM and Python ports have **no** migration command of their own — their
   former migrate goals/modules were removed, and (ADR-0015 Decision 2) the JVM

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

@@ -40,37 +40,53 @@ active format, so callers can parse them without scraping stderr.
 
 ## The workflow
 
-### Fresh database: baseline first
+### Fresh database: create the tables with `--from-db … --apply`
 
 The default `meta migrate` path is **offline** — it diffs metadata against a
 committed schema snapshot rather than the live DB. On a fresh database there is no
-snapshot yet; run the `baseline` step once before the first migration generate:
+snapshot yet, so the first command introspects the (empty) database instead:
 
 ```bash
-meta migrate baseline --dialect sqlite     # seed snapshot from metadata (no DB needed)
-meta migrate baseline --dialect postgres   # same for Postgres
-meta migrate baseline --from-db --db postgresql://... --dialect postgres
-                                           # alternative: seed from live DB (for existing schemas)
+meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
 ```
 
-`baseline` writes a reference snapshot to `.metaobjects/migrations/` and exits
-without emitting any SQL. After this, `meta migrate --dialect <d> --slug <name>`
-operates offline against that snapshot.
+That diffs metadata against what is *actually* in the database (nothing), emits the
+full `CREATE TABLE` set, applies it, and records the resulting snapshot — so the
+everyday offline flow works immediately afterwards, with no extra step.
+
+**Do NOT reach for `meta migrate baseline` on a database that does not exist yet.**
+An offline baseline derives the "existing" snapshot from your *metadata*, recording
+your entities' target shape as already applied: no table is ever created, every
+later `meta migrate` reports `no changes` (exit 0), and the failure only surfaces at
+the API layer as `no such table`. The CLI now refuses an offline baseline when it can
+prove the target `--db` is empty, and its no-snapshot hint routes to the `--from-db`
+command above.
 
-If you run `meta migrate` before baselining, the CLI surfaces a structured
-next-step hint pointing to the exact `baseline` command.
+`baseline` is for the other case — **adopting** metadata onto a database that already
+has its schema (a pre-existing, non-MetaObjects setup), where you want to record
+current state without emitting any DDL:
+
+```bash
+meta migrate baseline --from-db --db postgresql://... --dialect postgres
+```
 
 ### Generating a migration
 
 1. **Generate a migration** by diffing metadata vs the prior state (the live DB or a
    committed snapshot). The engine emits paired `up.sql` + `down.sql`:
 
    ```bash
-   meta migrate --db postgresql://...               # emit up.sql + down.sql
-   meta migrate --db postgresql://... --slug initial # name the migration
-   meta migrate --dry-run                            # preview without writing
+   meta migrate --dialect postgres --slug add-user-shipping   # offline: diff vs the committed snapshot
+   meta migrate --dialect postgres --slug add-user-shipping --dry-run   # preview without writing
+   meta migrate --from-db --db postgresql://... --dialect postgres --slug add-user-shipping
+                                                              # 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
+   ignored without `--from-db` or `--apply`); pass `--from-db` when you want the
+   diff taken against the live database.
+
 2. **Review the SQL.** Read the emitted `up.sql` (forward) and `down.sql`
    (rollback) before applying. Destructive changes (drop column / drop table) are
    opt-in — the engine blocks them unless explicitly allowed, and routes ambiguous
@@ -80,7 +96,10 @@ next-step hint pointing to the exact `baseline` command.
    a ledger table:
 
    ```bash
-   meta migrate --db postgresql://... --apply                # run pending up.sql
+   meta migrate --dialect postgres --slug add-user-shipping --db postgresql://... --apply
+                                                              # generate ...and apply it
+   meta migrate apply-pending --db postgresql://... --dialect postgres
+                                                              # replay committed migrations, no diff (fresh DB / CI)
    meta migrate --db postgresql://... --rollback <target>     # run down.sql for migrations newer than <target>
    meta migrate --db postgresql://... --rollback ""           # roll back everything (empty target)
    ```

docs/llms/llms-full.txt

@@ -272,8 +272,11 @@ $ 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)
 
-# Diff metadata vs live DB and emit migration SQL files (Node meta only, used by every port)
-$ meta migrate --db file:./dev.db --slug add-subscriber
+# 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.
+$ 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
 
 # Flatten loaded metadata to a canonical JSON snapshot
 $ meta export --out ./snapshot.json

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 --db <url> --slug <name>` — diff metadata vs the live DB and emit migration SQL files under `.metaobjects/migrations`. 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` 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 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

@@ -147,11 +147,18 @@ What this means in practice:
   it. You point it at the same database your server connects to:
 
   ```
-  meta migrate --db postgresql://... --slug initial   # emit migration SQL
-  meta migrate --db postgresql://... --apply          # apply pending migrations
-  meta migrate --dry-run                              # preview without writing
+  meta migrate --from-db --db postgresql://... --dialect postgres --slug init --apply
+                                                      # first migration on a brand-new database
+  meta migrate --dialect postgres --slug add-user-shipping          # everyday: emit migration SQL
+  meta migrate --dialect postgres --slug add-user-shipping --apply --db postgresql://...
+                                                      # ...and apply it
+  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`.
+
 - Dialects: `postgres` (default), `sqlite`, and `d1` (Cloudflare D1, TS-only).
 - The JVM and Python ports have **no** migration command of their own — their
   former migrate goals/modules were removed, and (ADR-0015 Decision 2) the JVM

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

@@ -40,37 +40,53 @@ active format, so callers can parse them without scraping stderr.
 
 ## The workflow
 
-### Fresh database: baseline first
+### Fresh database: create the tables with `--from-db … --apply`
 
 The default `meta migrate` path is **offline** — it diffs metadata against a
 committed schema snapshot rather than the live DB. On a fresh database there is no
-snapshot yet; run the `baseline` step once before the first migration generate:
+snapshot yet, so the first command introspects the (empty) database instead:
 
 ```bash
-meta migrate baseline --dialect sqlite     # seed snapshot from metadata (no DB needed)
-meta migrate baseline --dialect postgres   # same for Postgres
-meta migrate baseline --from-db --db postgresql://... --dialect postgres
-                                           # alternative: seed from live DB (for existing schemas)
+meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
 ```
 
-`baseline` writes a reference snapshot to `.metaobjects/migrations/` and exits
-without emitting any SQL. After this, `meta migrate --dialect <d> --slug <name>`
-operates offline against that snapshot.
+That diffs metadata against what is *actually* in the database (nothing), emits the
+full `CREATE TABLE` set, applies it, and records the resulting snapshot — so the
+everyday offline flow works immediately afterwards, with no extra step.
+
+**Do NOT reach for `meta migrate baseline` on a database that does not exist yet.**
+An offline baseline derives the "existing" snapshot from your *metadata*, recording
+your entities' target shape as already applied: no table is ever created, every
+later `meta migrate` reports `no changes` (exit 0), and the failure only surfaces at
+the API layer as `no such table`. The CLI now refuses an offline baseline when it can
+prove the target `--db` is empty, and its no-snapshot hint routes to the `--from-db`
+command above.
 
-If you run `meta migrate` before baselining, the CLI surfaces a structured
-next-step hint pointing to the exact `baseline` command.
+`baseline` is for the other case — **adopting** metadata onto a database that already
+has its schema (a pre-existing, non-MetaObjects setup), where you want to record
+current state without emitting any DDL:
+
+```bash
+meta migrate baseline --from-db --db postgresql://... --dialect postgres
+```
 
 ### Generating a migration
 
 1. **Generate a migration** by diffing metadata vs the prior state (the live DB or a
    committed snapshot). The engine emits paired `up.sql` + `down.sql`:
 
    ```bash
-   meta migrate --db postgresql://...               # emit up.sql + down.sql
-   meta migrate --db postgresql://... --slug initial # name the migration
-   meta migrate --dry-run                            # preview without writing
+   meta migrate --dialect postgres --slug add-user-shipping   # offline: diff vs the committed snapshot
+   meta migrate --dialect postgres --slug add-user-shipping --dry-run   # preview without writing
+   meta migrate --from-db --db postgresql://... --dialect postgres --slug add-user-shipping
+                                                              # 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
+   ignored without `--from-db` or `--apply`); pass `--from-db` when you want the
+   diff taken against the live database.
+
 2. **Review the SQL.** Read the emitted `up.sql` (forward) and `down.sql`
    (rollback) before applying. Destructive changes (drop column / drop table) are
    opt-in — the engine blocks them unless explicitly allowed, and routes ambiguous
@@ -80,7 +96,10 @@ next-step hint pointing to the exact `baseline` command.
    a ledger table:
 
    ```bash
-   meta migrate --db postgresql://... --apply                # run pending up.sql
+   meta migrate --dialect postgres --slug add-user-shipping --db postgresql://... --apply
+                                                              # generate ...and apply it
+   meta migrate apply-pending --db postgresql://... --dialect postgres
+                                                              # replay committed migrations, no diff (fresh DB / CI)
    meta migrate --db postgresql://... --rollback <target>     # run down.sql for migrations newer than <target>
    meta migrate --db postgresql://... --rollback ""           # roll back everything (empty target)
    ```

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

@@ -147,11 +147,18 @@ What this means in practice:
   it. You point it at the same database your server connects to:
 
   ```
-  meta migrate --db postgresql://... --slug initial   # emit migration SQL
-  meta migrate --db postgresql://... --apply          # apply pending migrations
-  meta migrate --dry-run                              # preview without writing
+  meta migrate --from-db --db postgresql://... --dialect postgres --slug init --apply
+                                                      # first migration on a brand-new database
+  meta migrate --dialect postgres --slug add-user-shipping          # everyday: emit migration SQL
+  meta migrate --dialect postgres --slug add-user-shipping --apply --db postgresql://...
+                                                      # ...and apply it
+  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`.
+
 - Dialects: `postgres` (default), `sqlite`, and `d1` (Cloudflare D1, TS-only).
 - The JVM and Python ports have **no** migration command of their own — their
   former migrate goals/modules were removed, and (ADR-0015 Decision 2) the JVM