docs: correct overstated and wrong claims found by a cross-port audit

Six adopter-facing inaccuracies, each verified against code before changing:

- "shipped as a standalone binary so non-TS adopters need no Node toolchain"
  (cli.md, llms.txt) — no binary is published: releases carry ZERO assets, no CI
  job builds one, and even a self-built executable needs the `pg` peer resolvable
  for Postgres. A JVM/.NET/Python shop DOES need Node to create or evolve a
  database; say so plainly instead of implying otherwise.

- "Spring REST + DTO + JPA repositories" (llms.txt, llms-full.txt, java README)
  — nothing JPA is emitted. No JpaRepository extends, no jakarta/javax.persistence
  import, and codegen-spring's pom has no spring-data-jpa dependency. The
  generator emits a repository INTERFACE whose own javadoc says the consumer
  implements it. Now described as what it is.

- `mvn meta:gen` / `mvn meta:verify` — wrong on BOTH counts. The plugin's
  goalPrefix is `metaobjects` and there is no `gen` goal (the mojos are
  generate/editor/verify/docs/agent-docs), so a Java adopter copying these gets
  "No plugin found for prefix 'meta'". Corrected across the live docs; references
  to the REMOVED `meta:migrate` mojo are left as the historical name.

- MIGRATION.md told 6.x→7.x upgraders that verify covers "database schema". The
  verify mojo has zero database/JDBC handling and `mode=db` is rejected.

- csharp.md "The runtime has no MetaObjects dependency" — generated routes emit
  `using MetaObjects.Codegen.Runtime;`. Narrowed to the case where it is true
  (entities + DbContext) and stated the exception.

- python.md called filter operators "a known gap" — they ship: there is a
  registered filter-allowlist generator and a runtime filter parser. This one
  UNDERSOLD the port.

No product code changed. The sibling metaobjects.dev site carries mirrors of the
llms files and is updated in the same pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KTGT5ksntpcJDZVJ5VyXHS

Author: dmealing

CLAUDE.md

@@ -8,10 +8,15 @@ command surface splits in two:
 
 - **Schema is language-agnostic** — it operates on the shared canonical metadata +
   a DB connection. It lives in **one canonical Node `meta` CLI** (`migrate`,
-  `verify --db`), used by any project regardless of backend language, shipped as a
-  standalone binary so non-TS adopters need no Node toolchain for schema ops. This
-  is the "Flyway/Atlas-style standalone tool" model — not re-implemented per
-  language.
+  `verify --db`), used by any project regardless of backend language. This is the
+  "Flyway/Atlas-style standalone tool" model — not re-implemented per language.
+
+  **A non-TS adopter needs Node (or Bun) to create or evolve a database.** No
+  pre-built binary is published today — releases carry no binaries, and a
+  self-built single-file executable still needs the `pg` peer resolvable for the
+  Postgres dialect (see the `@metaobjectsdev/cli` README). Plan for `npx meta …`
+  in your build, or vendor the CLI. Shipping a real release binary is tracked as
+  future work; until it exists, this doc will not claim one.
 - **Codegen is inherently language-specific** (`codegen-spring` is Java,
   `codegen-ts` is TS, …) — so it runs in **each language's own build tool**. There
   is no unified codegen binary, no proxying, and no `meta-ts`/`meta-java` names.
@@ -29,8 +34,8 @@ command surface splits in two:
 | **Vocabulary search** (`types`) | **Node `meta`** | `meta types [query]` | **any backend** — apropos/`kubectl explain` over the live metamodel registry (names + descriptions + when-to-use); the vocabulary is cross-port identical (registry-conformance) |
 | TS codegen | Node `meta` | `meta gen` | TS projects |
 | C# codegen | `dotnet meta` | `dotnet meta gen` / `verify --templates` / `verify --codegen` | a .NET tool (`ToolCommandName=dotnet-meta`); invoked `dotnet meta` so it never shadows the Node `meta`; ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2; bare `verify` = `--templates`). `gen` also accepts `--template-spec <json>` (+ `--template-root <dir>`, default `templates`) — the declarative Mustache template-codegen surface (the cross-port JSON contract shared with Python); see [declarative template scopes](codegen-concepts.md#declarative-template-scopes) |
-| Java/Kotlin codegen | Maven plugin | `mvn metaobjects:generate` (`meta:gen`) | Kotlin generators run through the same goal — see below. The `generate`/`verify`/`docs` goals are declared `threadSafe` and support parallel multi-module reactor builds (`mvn -T`) (#233) |
-| Java/Kotlin verify | Maven plugin | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`meta:verify`) | parameter-driven ADR-0021 D2 modes (one goal covers BOTH Java + Kotlin): `codegen` (default, back-compat — regen + fail on drift vs committed output, generator-neutral) / `templates` (`{{field}}`↔payload drift via the render `Verify` engine). `db` rejected ("schema verify is the migrate engine, ADR-0015") |
+| Java/Kotlin codegen | Maven plugin | `mvn metaobjects:generate` (`metaobjects:generate`) | Kotlin generators run through the same goal — see below. The `generate`/`verify`/`docs` goals are declared `threadSafe` and support parallel multi-module reactor builds (`mvn -T`) (#233) |
+| Java/Kotlin verify | Maven plugin | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`metaobjects:verify`) | parameter-driven ADR-0021 D2 modes (one goal covers BOTH Java + Kotlin): `codegen` (default, back-compat — regen + fail on drift vs committed output, generator-neutral) / `templates` (`{{field}}`↔payload drift via the render `Verify` engine). `db` rejected ("schema verify is the migrate engine, ADR-0015") |
 | Python codegen | console-script | `metaobjects gen` / `verify --codegen` / `verify --templates` | `[project.scripts] metaobjects` — **not** `meta` (that's the Node schema CLI); ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2). `gen` also accepts `--template-spec <json>` (+ `--templates <dir>`, default `templates`) — the declarative Mustache template-codegen surface (the cross-port JSON contract shared with C#); see [declarative template scopes](codegen-concepts.md#declarative-template-scopes) |
 
 ## `verify` is one verb with explicit subverbs (ADR-0021 D2)
@@ -74,7 +79,7 @@ historical template/prompt drift gate, the C# back-compat default), `verify
 --codegen` (regenerate the default generator suite to a temp dir and diff against
 the committed `--out` tree, never touching it), and a **clean `--db` rejection
 (exit 2)** — bare `dotnet meta verify` keeps `--templates` and prints the subverb
-note. The **Java/Kotlin `mvn meta:verify`** port expresses the same vocabulary as a
+note. The **Java/Kotlin `mvn metaobjects:verify`** port expresses the same vocabulary as a
 `mode` parameter (Maven goals are parameter-driven, not flag-driven): `-Dmeta.verify.mode=codegen`
 (default, byte-identical to the historical goal — regen-to-temp + diff vs committed
 output; drift is computed per **unique `outputDir`** over the whole `<generators>`
@@ -160,7 +165,7 @@ codegen surfaces do not run it.
 
 No port other than the Node `meta` exposes `migrate` or `verify --db`. The C#,
 Java, Python, and Kotlin command surfaces are **codegen only** (`gen` + codegen
-`verify`). The Java port's former `meta:migrate` / live-DB `meta:verify` Maven
+`verify`). The Java port's former `metaobjects:migrate` / live-DB `metaobjects:verify` Maven
 goals and the C#/Python migrate surfaces were removed in the schema-authority
 consolidation; the only schema entry point anywhere is the Node `meta`.
 
@@ -228,7 +233,7 @@ its message now points at `npx meta agent-docs --server <lang>`.
 ## Running Kotlin codegen via Maven
 
 `codegen-kotlin`'s generators extend `MultiFileDirectGeneratorBase` — the same
-generator SPI the `meta:gen` Mojo loads — so they run through the existing goal
+generator SPI the `metaobjects:generate` Mojo loads — so they run through the existing goal
 with no Kotlin-specific Mojo. Configure a Kotlin generator on the Maven plugin:
 
 ```xml

docs/features/cli.md

@@ -193,5 +193,5 @@ for the per-port pass/skip ledger.
 
 - [yaml-authoring.md](yaml-authoring.md) — how YAML lowers to canonical JSON
 - [entities.md](entities.md) — what the loader navigates
-- [migrations-and-drift.md](migrations-and-drift.md) — `meta:verify` runs the loader at build time
+- [migrations-and-drift.md](migrations-and-drift.md) — `metaobjects:verify` runs the loader at build time
 - [2026-05-25-cross-language-loader-architecture-unification.md](../superpowers/specs/2026-05-25-cross-language-loader-architecture-unification.md)

docs/features/loaders.md

@@ -13,7 +13,7 @@ There are **7 drift sources**, and the toolchain has a guard for each.
 |---|---|---|
 | **Code-vs-DB** | Codegen — the generated SQL DDL is emitted from the same metadata as the entity / table code. | Build time |
 | **Code-vs-API-doc** | Cross-port codegen from the same metadata. | Build time |
-| **DB-vs-metadata** | `meta verify --db` (TS CLI) — introspects the live DB and fails if it has drifted from metadata. Includes modeled projection **view bodies** (a changed `CREATE VIEW` is `replace-view` drift); a hand-authored *unmodeled* view is unmanaged and never flagged. A schema concern owned by the Node toolchain regardless of server language; on the JVM ports the runtime auto-create/validator path was removed (ADR-0015) and the `meta:verify` Maven goal is not available. Cloudflare D1 has no client wire protocol, so it can't go through `--db`'s Kysely-driver introspection — use `meta verify --dialect d1 [--d1 <binding>] [--remote]` instead (the same wrangler-shelled-out path `meta migrate --dialect d1` uses); `--remote` is required to check the *deployed* database, not the local `wrangler dev` shadow copy. Pointing `--db file:` at wrangler's local D1 state directory (`.wrangler/state/**/d1/**`) still runs, but only verifies that local copy — `verify` warns when it detects this. | CI on every PR |
+| **DB-vs-metadata** | `meta verify --db` (TS CLI) — introspects the live DB and fails if it has drifted from metadata. Includes modeled projection **view bodies** (a changed `CREATE VIEW` is `replace-view` drift); a hand-authored *unmodeled* view is unmanaged and never flagged. A schema concern owned by the Node toolchain regardless of server language; on the JVM ports the runtime auto-create/validator path was removed (ADR-0015) and the `metaobjects:verify` Maven goal is not available. Cloudflare D1 has no client wire protocol, so it can't go through `--db`'s Kysely-driver introspection — use `meta verify --dialect d1 [--d1 <binding>] [--remote]` instead (the same wrangler-shelled-out path `meta migrate --dialect d1` uses); `--remote` is required to check the *deployed* database, not the local `wrangler dev` shadow copy. Pointing `--db file:` at wrangler's local D1 state directory (`.wrangler/state/**/d1/**`) still runs, but only verifies that local copy — `verify` warns when it detects this. | CI on every PR |
 | **Migration-vs-metadata** | The Node `meta migrate` emits migrations FROM metadata diffs — they cannot drift from metadata by construction. Schema migrations for **every** port are owned by this Node toolchain (`@metaobjectsdev/cli migrate`, ADR-0015); the C# and Python migrate surfaces were removed. | Build time |
 | **Generated-edited** | `@generated` headers in emitted code + three-way merge that preserves hand-edits inside non-generated regions. | Code review |
 | **Prompt-vs-payload** | FR-004 `Renderer.verify` parses `{{...}}` references in templates and checks each one exists on the payload VO. | Build time + runtime |
@@ -195,8 +195,8 @@ meta migrate --db postgresql://... --apply          # apply pending migrations
 | Port | Command | What it does |
 |---|---|---|
 | TypeScript | `meta verify --db` | Introspects the live DB; reports DB-vs-metadata drift. |
-| Java | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`meta:verify` Maven goal) + `Renderer.verify` (build-time) | The codegen/template-drift `meta:verify` Maven goal is alive and is how Java gates drift in CI (`codegen` mode regens + fails on drift vs committed output; `templates` mode drift-checks `{{...}}` references against the payload VO via `Renderer.verify`). Only the *live-DB-schema* `meta:verify` goal was removed — that's TS-owned now (`meta verify --db`) — along with the runtime auto-create validator (ADR-0015). |
-| Kotlin | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`meta:verify` Maven goal — same goal covers both Java + Kotlin) + `MetadataStartupValidator` (startup) | Same as Java — the `meta:verify` Maven goal remains, plus template-drift and startup validation. |
+| Java | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`metaobjects:verify` Maven goal) + `Renderer.verify` (build-time) | The codegen/template-drift `metaobjects:verify` Maven goal is alive and is how Java gates drift in CI (`codegen` mode regens + fails on drift vs committed output; `templates` mode drift-checks `{{...}}` references against the payload VO via `Renderer.verify`). Only the *live-DB-schema* `metaobjects:verify` goal was removed — that's TS-owned now (`meta verify --db`) — along with the runtime auto-create validator (ADR-0015). |
+| Kotlin | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`metaobjects:verify` Maven goal — same goal covers both Java + Kotlin) + `MetadataStartupValidator` (startup) | Same as Java — the `metaobjects:verify` Maven goal remains, plus template-drift and startup validation. |
 | C# | `meta verify ./metadata --templates ./prompts` | Drift-checks templates against their payload VOs (FR-004 prompt-drift). |
 | Python | `python -m metaobjects.render.verify` | Same as C# verify — template-vs-payload drift. |
 

docs/features/migrations-and-drift.md

@@ -470,8 +470,8 @@ and checks each one exists on the payload VO. If a template references
 | Port | Command |
 |---|---|
 | TypeScript | `meta verify` (CLI) |
-| Java | `mvn meta:verify` (Maven goal) |
-| Kotlin | `mvn meta:verify` (same Maven goal) |
+| Java | `mvn metaobjects:verify` (Maven goal) |
+| Kotlin | `mvn metaobjects:verify` (same Maven goal) |
 | C# | `dotnet meta verify <metadataDir> --templates <root>` |
 | Python | `python -m metaobjects.render.verify` |
 

docs/features/templates-and-payloads.md

@@ -50,12 +50,12 @@ The pillars are views on the same metadata, not separate products. All four ship
 Emit idiomatic per-language code from a single metadata model.
 
 - TypeScript: Drizzle + Zod + Fastify integration (and React / TanStack on the client side)
-- Java: Spring REST + DTO + JPA repositories via `codegen-spring`
+- Java: Spring REST + DTO + repository interfaces (the persistence impl is consumer-supplied) via `codegen-spring`
 - Kotlin: KotlinPoet + Exposed + Spring via `codegen-kotlin`
 - C#: EF Core + ASP.NET
 - Python: Pydantic + FastAPI
 
-Hand-edit-preserving regeneration uses a three-way merge so engineers can extend generated entities without losing their work when metadata changes. M:N relationship codegen (FR-018) ships in all five ports: entity navigation, idiomatic ORM wiring (Drizzle m2m / EF Core `UsingEntity` / Spring repo+JPA / Exposed / Pydantic), and REST traversal (`GET /<source-plural>/{id}/<relation>`).
+Hand-edit-preserving regeneration uses a three-way merge so engineers can extend generated entities without losing their work when metadata changes. M:N relationship codegen (FR-018) ships in all five ports: entity navigation, idiomatic ORM wiring (Drizzle m2m / EF Core `UsingEntity` / Spring repo interface / Exposed / Pydantic), and REST traversal (`GET /<source-plural>/{id}/<relation>`).
 
 ### Runtime metadata
 
@@ -94,7 +94,7 @@ Because the render is conformance-gated, the determinism guarantee holds in ever
 | Language | Status | Notes |
 |---|---|---|
 | TypeScript | Reference implementation, npm `0.21.3` | All four pillars. 2500+ tests passing. Owns the canonical schema-migration toolchain used by every port (ADR-0015). Bun-first dev. |
-| Java | Maven Central `7.21.3` | Spring REST + JPA codegen, OMDB runtime persistence (pure data-access) with Spring-tx. Fully green across all conformance corpora. |
+| Java | Maven Central `7.21.3` | Spring REST + DTO + repository-interface codegen, OMDB runtime persistence (pure data-access) with Spring-tx. Fully green across all conformance corpora. |
 | Kotlin | Maven Central `7.21.3` | KotlinPoet codegen + Exposed runtime + `metadata-ktx` facade. Ships via the Java reactor. |
 | C# | NuGet `0.21.3` (.NET tool) | Loader + canonical serializer + EF Core + ASP.NET codegen + render/verify. `dotnet meta` tool. |
 | Python | PyPI `0.21.3` | Loader + serializer + render + verify + codegen + `ObjectManager` runtime. Fully green across all corpora. |