docs(ports): fix C#/Java/Kotlin quickstart inaccuracies (audit-driven)

The launch review only pressure-tested TS+Python; auditing the other three ports
found the same class of defects (Java worst — a fabricated runtime example like
Python's). All fixes verified against generator/CLI/render source.

Java (docs/ports/java.md): Configure block cited a nonexistent JavaPojoGenerator
→ the real Spring* generators; the OMDB "Use" example was fabricated end-to-end
(ObjectManagerDb/.builder()/persist/getObjectsBy + a never-generated Author POJO)
→ real connection-first ObjectManagerDB API; FR-004 Renderer.render is an instance
method + RenderRequest is a record (no builder); Verify.verify/Renderer.verify
don't exist → Verify.check; mvn goal prose meta:gen → metaobjects:generate; added
the ${metaobjects.version}=7.11.3 note.

C# (docs/ports/csharp.md): `dotnet meta --help` is broken → `dotnet meta`; removed
the fictional ForgeTypesProvider + fixed CoreTypes.CoreTypesProvider/namespace;
"record per entity" → class; RenderRequest object-initializer; real .g.cs filenames;
/api/author → /api/authors; added the EF Core + Npgsql consumer-dep note.

Kotlin (docs/ports/kotlin.md): generator count 7/9 (contradictory) → the real 14
(added the 5 missing rows); entity generator also emits object.projection; the Use
example aligned to real emitted shape (nullable auto-PK, jakarta validation attrs,
no @serializable on entities); stale "122 tests" softened.

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

Author: dmealing

docs/ports/csharp.md

@@ -22,7 +22,7 @@ Install the CLI as a .NET tool:
 
 ```bash
 dotnet tool install --global MetaObjects.Cli
-dotnet meta --help
+dotnet meta          # bare invocation prints the usage banner
 ```
 
 The C# CLI is invoked as `dotnet meta` (command `dotnet-meta`), or run directly
@@ -59,12 +59,11 @@ If your app needs a metamodel subtype the core doesn't ship, declare an
 `IMetaDataTypeProvider` and compose it into the registry before loading:
 
 ```csharp
-using MetaObjects.Metadata;
+using MetaObjects;
 using MetaObjects.Loader;
 
 var registry = Provider.ComposeRegistry(new IMetaDataTypeProvider[] {
-    CoreTypesProvider.Instance,
-    ForgeTypesProvider.Instance,
+    CoreTypes.CoreTypesProvider,
     yourProvider,            // adds your custom subtype/attrs
 });
 
@@ -99,11 +98,13 @@ Schema migrations are owned by the Node `meta` CLI (ADR-0015) — the C# CLI is
 
 The codegen emits:
 
-- `Author.cs` — record per entity.
-- `AppDbContext.cs` — `DbSet<Author>`, projection `.ToView()`, `@storage` owned
+- `Author.g.cs` — class per entity (a mutable attributed POCO, not a record).
+- `AppDbContext.g.cs` — `DbSet<Author>`, projection `.ToView()`, `@storage` owned
   types via `OwnsOne` (single) / `OwnsMany(...).ToJson(...)` (`@isArray` array-of-VO),
   enum-as-string via `HasConversion<string>()`.
-- `Author.routes.cs` — CRUD minimal-API endpoints.
+- `AuthorRoutes.g.cs` — CRUD minimal-API endpoints.
+- `AuthorFilterAllowlist.g.cs` — the server-side filter/sort allowlist feeding the
+  generated list handler.
 
 ## Use
 
@@ -118,12 +119,18 @@ builder.Services.AddDbContext<AppDbContext>(opts =>
 
 var app = builder.Build();
 
-app.MapAuthorRoutes();   // generated — GET/POST/PUT/DELETE on /api/author
+app.MapAuthorRoutes();   // generated — GET/POST/PUT/DELETE on /api/authors
 app.Run();
 ```
 
 EF Core does the rest. The runtime has no MetaObjects dependency.
 
+**Consumer dependencies.** The generated `AppDbContext` and the `Program.cs`
+wiring above use EF Core (`AddDbContext`, `DbContext`, `UseNpgsql`), which
+MetaObjects does not pull in for you — add the two EF Core NuGet packages to
+the consuming app: `Microsoft.EntityFrameworkCore` and
+`Npgsql.EntityFrameworkCore.PostgreSQL`.
+
 ```csharp
 // Optional handwritten service over the generated DbContext
 public class AuthorService(AppDbContext db)
@@ -151,11 +158,12 @@ var payload = new WelcomePayload(
     PostCount: 12,
     Posts: new[] { new PostSummary("Hello") });
 
-string output = Renderer.Render(new RenderRequest(
-    Ref: "lobby/welcome",
-    Payload: payload,
-    Provider: provider,
-    Format: "xml"));
+string output = Renderer.Render(new RenderRequest {
+    Ref = "lobby/welcome",
+    Payload = payload,
+    Provider = provider,
+    Format = "xml",
+});
 ```
 
 `Verify` in `MetaObjects.Render` drift-checks every `template.*` against its

docs/ports/java.md

@@ -2,7 +2,7 @@
 
 The Java port targets Spring-Boot consumers on Maven. It ships the full metamodel
 + loader + conformance + OMDB runtime persistence engine + the FR-004 render engine,
-plus the `metaobjects-maven-plugin` for build-time codegen (`meta:gen` / `meta:editor`).
+plus the `metaobjects-maven-plugin` for build-time codegen (`mvn metaobjects:generate` / `metaobjects:editor`).
 
 Schema migrations are owned by the TypeScript toolchain (`@metaobjectsdev/cli migrate`);
 the Java diff-and-converge migration engine and its `meta:migrate` / live-DB-drift
@@ -12,8 +12,15 @@ Prompt / template drift is still checked via the `metaobjects-render` `Verify` A
 
 ## Install
 
+Set `${metaobjects.version}` to the current Maven Central release (`7.11.3`) — both
+the dependency and plugin blocks below resolve it from one `<properties>` entry:
+
 ```xml
 <!-- pom.xml -->
+<properties>
+  <metaobjects.version>7.11.3</metaobjects.version>
+</properties>
+
 <dependencies>
   <dependency>
     <groupId>com.metaobjects</groupId>
@@ -55,7 +62,19 @@ For Spring integration: add `metaobjects-core-spring`.
             </loader>
             <generators>
               <generator>
-                <classname>com.metaobjects.generator.java.JavaPojoGenerator</classname>
+                <classname>com.metaobjects.generator.spring.SpringDtoGenerator</classname>
+                <args>
+                  <outputDir>${project.build.directory}/generated-sources/java</outputDir>
+                </args>
+              </generator>
+              <generator>
+                <classname>com.metaobjects.generator.spring.SpringControllerGenerator</classname>
+                <args>
+                  <outputDir>${project.build.directory}/generated-sources/java</outputDir>
+                </args>
+              </generator>
+              <generator>
+                <classname>com.metaobjects.generator.spring.SpringRepositoryGenerator</classname>
                 <args>
                   <outputDir>${project.build.directory}/generated-sources/java</outputDir>
                 </args>
@@ -147,37 +166,61 @@ auto-create path was removed per ADR-0015.
 OMDB reads the same metadata at runtime and drives CRUD; no per-entity ORM
 boilerplate.
 
+The Java port generates **no typed entity POJO** — the only entity-shaped Java
+output is the immutable `<Entity>Dto` record (from `codegen-spring`). OMDB drives
+CRUD against the loaded metadata plus generic `ValueObject` instances, and its API
+is connection-first (you pass an `ObjectConnection` to each call):
+
 ```java
 import com.metaobjects.loader.MetaDataLoader;
-import com.metaobjects.omdb.ObjectManagerDb;
-import com.metaobjects.object.ValueObject;
-import acme.blog.Author;
-
+import com.metaobjects.manager.ObjectConnection;
+import com.metaobjects.manager.QueryOptions;
+import com.metaobjects.manager.db.ObjectManagerDB;
+import com.metaobjects.manager.exp.Expression;
+import com.metaobjects.object.MetaObject;
+import com.metaobjects.object.value.ValueObject;
+
+import javax.sql.DataSource;
 import java.nio.file.Path;
-import java.util.List;
+import java.util.Collection;
 
 public class App {
     public static void main(String[] args) throws Exception {
         MetaDataLoader loader = MetaDataLoader.fromDirectory(
             "app", Path.of("src/main/metaobjects"));
 
-        ObjectManagerDb om = ObjectManagerDb.builder()
-            .loader(loader)
-            .dataSource(/* javax.sql.DataSource */)
-            .build();
-
-        // CRUD
-        Author author = new Author();
-        author.setName("Ada");
-        om.persist(author);
-
-        List<Author> all = om.getObjectsBy(Author.class, new ValueObject());
-        Author fetched = om.getObjectById(Author.class, author.getId());
+        DataSource ds = /* your javax.sql.DataSource */;
+
+        ObjectManagerDB om = new ObjectManagerDB();
+        om.setDataSource(ds);
+        om.init();
+
+        MetaObject author = loader.getMetaObjectByName("acme::blog::Author");
+
+        ObjectConnection oc = om.getConnection();
+        try {
+            // CREATE — a generic ValueObject typed by the Author MetaObject
+            ValueObject row = (ValueObject) author.newInstance();
+            row.setString("name", "Ada");
+            om.createObject(oc, row);
+            oc.commit();
+
+            // QUERY — all rows, or filtered via an Expression
+            Collection<?> all = om.getObjects(oc, author, new QueryOptions());
+            ValueObject match = (ValueObject) om.getObjects(
+                    oc, author, new QueryOptions(new Expression("name", "Ada")))
+                .iterator().next();
+
+            // LOAD by primary key — re-reads the row into the object
+            om.loadObject(oc, match);
+        } finally {
+            om.releaseConnection(oc);
+        }
     }
 }
 ```
 
-Spring wiring lives in `metaobjects-core-spring`; declare an `ObjectManagerDb`
+Spring wiring lives in `metaobjects-core-spring`; declare an `ObjectManagerDB`
 bean with the Spring `DataSource` and let Spring inject it into your services.
 
 ## FR-004 — render engine
@@ -190,20 +233,23 @@ import java.util.Map;
 
 Provider provider = new FilesystemProvider(Path.of("./prompts"));
 
-String out = Renderer.render(RenderRequest.builder()
-    .ref("lobby/welcome")
-    .payload(Map.of(
-        "displayName", "Ada",
-        "postCount", 12L,
-        "posts", List.of(Map.of("title", "Hello"))))
-    .provider(provider)
-    .format("xml")
-    .build());
+Map<String, Object> payload = Map.of(
+    "displayName", "Ada",
+    "postCount", 12L,
+    "posts", List.of(Map.of("title", "Hello")));
+
+// RenderRequest is a record (template, ref, payload, provider, format, verify, maxChars);
+// pass a null template for a provider-resolved ref, and null verify/maxChars.
+// render() is an instance method.
+String out = new Renderer().render(
+    new RenderRequest(null, "lobby/welcome", payload, provider, "xml", null, null));
 ```
 
-`Verify.verify(loader, provider, options)` drift-checks every `template.*` node
-against its `@payloadRef`. Wire it into a Maven test (e.g. a JUnit assertion in
-the `test` phase).
+`Verify.check(templateText, fields, options)` returns a `List<VerifyError>` (empty
+= no drift) — it cross-checks a template's variables against its declared payload
+field tree (`List<PayloadField>`), flagging any variable absent from the payload
+(`ERR_VAR_NOT_ON_PAYLOAD`), unresolved partials, and unused required slots. Wire it
+into a Maven test (e.g. a JUnit assertion in the `test` phase).
 
 ## Generators
 
@@ -248,7 +294,7 @@ configuration model that has not yet been specced.
 | Payload-VO codegen | Yes — `SpringPayloadGenerator` (in `metaobjects-codegen-spring`) emits a Java 21 `record` per template, mirrors the Kotlin shape |
 | Output parser codegen (FR-006) | Yes — `SpringOutputParserGenerator` (in `metaobjects-codegen-spring`) — see usage below |
 | Migrations | TS-only (`@metaobjectsdev/cli migrate`) — the Java migration engine and the OMDB runtime auto-create path were both removed (ADR-0015); apply the TS-produced DDL to the database |
-| Drift verify | `Renderer.verify` / `Verify.verify` (prompts). Live-DB schema-drift verification is part of the TS migration toolchain |
+| Drift verify | `Verify.check` / `Verify.checkOutputPrompt` (prompts). Live-DB schema-drift verification is part of the TS migration toolchain |
 | Runtime metadata | Full — OMDB ObjectManager |
 | REST controller codegen | Spring Web MVC — `metaobjects-codegen-spring` (FR-008 §2.1) |
 
@@ -287,9 +333,10 @@ try {
 }
 ```
 
-`Verify.verify(loader, provider, options)` walks `template.output` nodes the
-same way it walks `template.prompt`, catching payload-VO ↔ parser drift at
-build time. Cross-port design is at
+The same `Verify` API guards the output side: `Verify.checkOutputPrompt(fragment,
+requiredFieldNames)` checks the output-format prompt fragment names every required
+field, and `Verify.check(...)` (with output-tag slots supplied via its
+`VerifyOptions`) catches payload-VO ↔ parser drift at build time. Cross-port design is at
 [ADR-0010](../../spec/decisions/ADR-0010-template-output-parser-codegen.md);
 the feature reference is at
 [`features/templates-and-payloads.md`](../features/templates-and-payloads.md#output-parsing-fr-006).

docs/ports/kotlin.md

@@ -9,7 +9,7 @@ wiring) via KotlinPoet.
 
 Two modules:
 
-- **`metaobjects-codegen-kotlin`** — 7 KotlinPoet-based generators.
+- **`metaobjects-codegen-kotlin`** — 14 KotlinPoet-based generators.
 - **`metaobjects-metadata-ktx`** — thin Kotlin facade over the Java loader + render
   engine for idiomatic Kotlin runtime use.
 
@@ -69,15 +69,20 @@ Two modules:
 
 ## Configure
 
-The 9 generators in `codegen-kotlin`:
+The 14 generators registered in `codegen-kotlin` (`GeneratorRegistry.kt`):
 
 | Generator | Output | Per |
 |---|---|---|
-| `KotlinEntityGenerator` | `<Entity>.kt` — Kotlin `data class` (Jackson-compatible; no `@Serializable`) | every `object.entity` + `object.value` |
+| `KotlinEntityGenerator` | `<Entity>.kt` — Kotlin `data class` (Jackson-compatible; no `@Serializable`) | every `object.entity`, `object.value`, and `object.projection` |
 | `KotlinExposedTableGenerator` | `<Entity>Table.kt` — Exposed `Table` object with PK + FK + `@storage` columns | entities with `source.rdb` |
 | `KotlinRelationsGenerator` | `<Entity>Relations.kt` — extension fns for `cardinality=many` query helpers | entities with to-many relationships |
+| `KotlinRepositoryGenerator` | `<Entity>RepositoryBase.kt` — persistence repository base (row-mapper + CRUD + patch) | writable entities (`source.rdb @kind="table"`) |
+| `KotlinFilterAllowlistGenerator` | `<Entity>FilterAllowlist.kt` — FR-009 filter allowlist (filterable field names + allowed ops per field) | writable entities (`source.rdb @kind="table"`) |
 | `KotlinPayloadGenerator` | `<Template>Payload.kt` — `@Serializable` payload from `@payloadRef` view-object | every `template.prompt` / `template.output` |
 | `KotlinOutputParserGenerator` | `<Template>Parser.kt` — `object` with `parseXxx` (throws `SerializationException`) + `safeParseXxx` (returns `Result<TPayload>`) | every `template.output` (FR-006) |
+| `KotlinOutputPromptGenerator` | `<Template>Prompt.kt` — output-format prompt fragment (FR-010) | every `template.output` |
+| `KotlinRenderHelperGenerator` | `<Template>RenderHelper.kt` — typed `render()` wrappers (document/email, keyed off `@kind`) | every `template.output` |
+| `KotlinExtractorGenerator` | `<Template>Extractor.kt` — strict typed `extract<Name>` payload helper (FR-010) | every nested-capable `template.output` |
 | `KotlinValidatorGenerator` | `MetadataStartupValidator.kt` + `ExposedTableValidator.kt` | once per project |
 | `KotlinSpringConfigGenerator` | `MetadataExposedConfig.kt` — `@Configuration` wiring `Database.connect()` + auto-validator | once per project |
 | `KotlinStoredProcGenerator` | Stored-procedure call wrappers | entities with `source.rdb @kind="storedProc"` |
@@ -158,11 +163,17 @@ For the `Author` example (see [entities.md](../features/entities.md)), the codeg
 emits:
 
 ```kotlin
-// generated/acme/blog/Author.kt
-data class Author(
-    val id: Long,
-    val name: String,
-    val bio: String? = null,
+// generated/acme/blog/Author.kt  (jakarta.validation imports elided)
+/**
+ * GENERATED — do not hand-edit. Regenerated from metadata.
+ */
+public data class Author(
+    public val id: Long? = null,        // field.long PK → nullable, auto-assigned on insert
+    @field:NotNull
+    @field:Size(min = 1, max = 200)
+    public val name: String,            // @required + @maxLength: 200
+    @field:Size(max = 2000)
+    public val bio: String? = null,     // optional + @maxLength: 2000
 )
 
 // generated/acme/blog/AuthorTable.kt
@@ -327,7 +338,8 @@ the contract is universal.
 
 ## Test count
 
-122 tests in `codegen-kotlin` (`mvn -pl codegen-kotlin test`). Snapshot tests gate
+Several hundred tests in `codegen-kotlin` (`mvn -pl codegen-kotlin test`; ~290
+`@Test` methods across ~50 test files). Snapshot tests gate
 within-Java output stability; `kotlin-compile-testing` gates generated-code
 validity; an end-to-end test exercises the full loop including the Java
 `Renderer`. Persistence-conformance + the cross-port API contract run in