metaobjects 0.9.0__py3-none-any.whl

metaobjects/agent_context/_content/skills/metaobjects-codegen/references/java.md

@@ -0,0 +1,94 @@
+# Java codegen specifics
+
+The Java port targets Spring Boot consumers on Maven. Codegen runs as a build-time
+Maven plugin goal — there is no standalone `meta` binary on the Java side (the Node
+`meta` is for schema migrations only; see the migration reference).
+
+## Maven coordinates
+
+All artifacts share `groupId` `com.metaobjects` and one version property:
+
+| Artifact | Purpose |
+|---|---|
+| `metaobjects-metadata` | metamodel + loader |
+| `metaobjects-omdb` | runtime persistence (ObjectManagerDb) |
+| `metaobjects-render` | FR-004 render + `Verify` (prompt/template drift) |
+| `metaobjects-codegen-spring` | the Spring codegen generators |
+| `metaobjects-maven-plugin` | the build-time codegen plugin |
+| `metaobjects-core-spring` | optional Spring wiring |
+
+## Plugin config in `pom.xml`
+
+The plugin's `generate` goal binds to the `generate-sources` phase. Point its
+`<loader><sourceDir>` at your metadata and list one `<generator>` per output you
+want, by fully-qualified class name.
+
+```xml
+<build>
+  <plugins>
+    <plugin>
+      <groupId>com.metaobjects</groupId>
+      <artifactId>metaobjects-maven-plugin</artifactId>
+      <version>${metaobjects.version}</version>
+      <executions>
+        <execution>
+          <id>generate</id>
+          <phase>generate-sources</phase>
+          <goals><goal>generate</goal></goals>
+          <configuration>
+            <loader>
+              <sourceDir>src/main/metaobjects</sourceDir>
+            </loader>
+            <generators>
+              <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.SpringDtoGenerator</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>
+              </generator>
+            </generators>
+          </configuration>
+        </execution>
+      </executions>
+    </plugin>
+  </plugins>
+</build>
+```
+
+## Run
+
+```bash
+mvn metaobjects:generate   # the codegen goal directly (goalPrefix=metaobjects, goal=generate)
+mvn compile                # also runs it (the goal is bound to generate-sources)
+```
+
+A `metaobjects:verify` Maven goal exists for **codegen-drift** (re-generate and diff vs
+committed output). Schema migration and live-DB drift are NOT Java goals — they run
+through the Node `meta` tool (see the migration reference).
+
+## `codegen-spring` generators
+
+All live in `metaobjects-codegen-spring` under
+`com.metaobjects.generator.spring.*`; wire any subset, typically all three of the
+first group together:
+
+| Generator | Output |
+|---|---|
+| `SpringControllerGenerator` | `<Entity>Controller.java` per writable entity (`source.rdb` `@kind="table"`) — Spring Web MVC, five CRUD endpoints on the cross-port REST contract (`?sort`, `?limit`/`?offset`, `?withCount=1` envelope, 404/400 envelopes) |
+| `SpringDtoGenerator` | `<Entity>Dto.java` as a Java 21 `record`; wrapped primitives (`Long`/`Integer`/`Boolean`) so missing JSON props deserialise to `null`; currency = `Long` (integer minor units) |
+| `SpringRepositoryGenerator` | `<Entity>Repository.java` — a hand-stubbed `interface` the consumer implements with their persistence layer (Spring Data JPA / jOOQ / JDBC) |
+| `SpringPayloadGenerator` | a Java 21 `record` per template payload VO |
+| `SpringOutputParserGenerator` | the `template.output` parser-on-receipt (see the prompts reference) |
+| `SpringFilterAllowlistGenerator` | per-entity filter allowlist |
+
+Metadata lives under `src/main/metaobjects/` in the same canonical JSON the other
+ports read — fused-key form, `source.rdb` + `@table`, `@column` for a renamed
+physical column.

metaobjects/agent_context/_content/skills/metaobjects-codegen/references/kotlin.md

@@ -0,0 +1,110 @@
+# Kotlin codegen specifics
+
+The Kotlin port is a **codegen tier built on top of the Java port**. The loader,
+render engine, and Maven plugin are all Java; `codegen-kotlin` emits idiomatic
+Kotlin (`@Serializable data class`, Exposed `Table` objects, Spring
+`@RestController`/`@Configuration`) via KotlinPoet. Codegen runs as the same
+build-time Maven plugin goal the Java port uses — there is no standalone `meta`
+binary on the JVM side (the Node `meta` is for schema migrations only; see the
+migration reference).
+
+## Contents
+- Maven coordinates
+- Plugin config in `pom.xml`
+- Run
+- `codegen-kotlin` generators
+
+## Maven coordinates
+
+All artifacts share `groupId` `com.metaobjects` and one version property:
+
+| Artifact | Purpose |
+|---|---|
+| `metaobjects-metadata` | metamodel + loader |
+| `metaobjects-metadata-ktx` | thin Kotlin facade over the Java loader + render engine |
+| `metaobjects-render` | render + `Verify` + tolerant `extract` (prompt/template) |
+| `metaobjects-codegen-kotlin` | the Kotlin (KotlinPoet) generators |
+| `metaobjects-maven-plugin` | the build-time codegen plugin |
+
+Generated entities and Exposed tables need the consumer's own runtime deps —
+`org.jetbrains.exposed:exposed-core` and
+`org.jetbrains.kotlinx:kotlinx-serialization-json` (the latter for
+`@Serializable`/parser output).
+
+## Plugin config in `pom.xml`
+
+The plugin's `generate` goal binds to the `generate-sources` phase. Point its
+`<loader><sourceDir>` at your metadata and list one `<generator>` per output you
+want, by fully-qualified class name. The Kotlin generators run through the same
+Java plugin via the shared SPI:
+
+```xml
+<build>
+  <plugins>
+    <plugin>
+      <groupId>com.metaobjects</groupId>
+      <artifactId>metaobjects-maven-plugin</artifactId>
+      <version>${metaobjects.version}</version>
+      <executions>
+        <execution>
+          <id>generate</id>
+          <phase>generate-sources</phase>
+          <goals><goal>generate</goal></goals>
+          <configuration>
+            <loader>
+              <sourceDir>src/main/metaobjects</sourceDir>
+            </loader>
+            <generators>
+              <generator>
+                <classname>com.metaobjects.generator.kotlin.KotlinEntityGenerator</classname>
+                <args><outputDir>${project.build.directory}/generated-sources/kotlin</outputDir></args>
+              </generator>
+              <generator>
+                <classname>com.metaobjects.generator.kotlin.KotlinExposedTableGenerator</classname>
+                <args><outputDir>${project.build.directory}/generated-sources/kotlin</outputDir></args>
+              </generator>
+              <generator>
+                <classname>com.metaobjects.generator.kotlin.KotlinSpringControllerGenerator</classname>
+                <args><outputDir>${project.build.directory}/generated-sources/kotlin</outputDir></args>
+              </generator>
+            </generators>
+          </configuration>
+        </execution>
+      </executions>
+    </plugin>
+  </plugins>
+</build>
+```
+
+## Run
+
+```bash
+mvn metaobjects:generate   # the codegen goal directly (goalPrefix=metaobjects, goal=generate)
+mvn compile                # also runs it (the goal is bound to generate-sources)
+```
+
+A `metaobjects:verify` Maven goal exists for **codegen-drift** (re-generate and diff
+vs committed output). Schema migration and live-DB drift are NOT JVM goals — they run
+through the Node `meta` tool (see the migration reference).
+
+## `codegen-kotlin` generators
+
+All live in `metaobjects-codegen-kotlin` under
+`com.metaobjects.generator.kotlin.*`; wire the subset you need by FQ class name:
+
+| Generator | Output |
+|---|---|
+| `KotlinEntityGenerator` | `<Entity>.kt` — `@Serializable data class` per `object.entity` / `object.value` |
+| `KotlinExposedTableGenerator` | `<Entity>Table.kt` — Exposed `Table` object (PK + FK + `@storage` columns) for entities with `source.rdb` |
+| `KotlinRelationsGenerator` | `<Entity>Relations.kt` — extension fns for `@cardinality="many"` query helpers |
+| `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController`, five CRUD endpoints on the cross-port REST contract, for writable entities (`source.rdb` `@kind="table"`) |
+| `KotlinPayloadGenerator` | `<Template>Payload.kt` — `@Serializable` payload data class from a template's `@payloadRef` |
+| `KotlinOutputParserGenerator` | the `template.output` parser-on-receipt (see the prompts reference) |
+| `KotlinValidatorGenerator` | `MetadataStartupValidator.kt` + `ExposedTableValidator.kt` (once per project) |
+| `KotlinSpringConfigGenerator` | `MetadataExposedConfig.kt` — `@Configuration` wiring `Database.connect()` + the startup validator (once per project) |
+| `KotlinStoredProcGenerator` | stored-procedure call wrappers for `source.rdb` `@kind="storedProc"` |
+| `KotlinFilterAllowlistGenerator` | per-entity filter allowlist |
+
+Metadata lives under `src/main/metaobjects/` in the same canonical JSON the other
+ports read — fused-key form, `source.rdb` + `@table`, `@column` for a renamed
+physical column.

metaobjects/agent_context/_content/skills/metaobjects-codegen/references/typescript.md

@@ -0,0 +1,135 @@
+# TypeScript codegen specifics
+
+The TS port is the reference implementation, published to npm as `@metaobjectsdev/*`
+packages. Codegen runs through the Node `meta` CLI (`@metaobjectsdev/cli`, binary
+`meta`).
+
+## Contents
+- Install
+- `metaobjects.config.ts`
+- The generators
+- Run
+- Multiple output targets
+- Field subtype → column mapping
+
+## Install
+
+```bash
+npm install --save-dev @metaobjectsdev/cli @metaobjectsdev/codegen-ts
+npm install            @metaobjectsdev/metadata @metaobjectsdev/runtime-ts
+```
+
+For the React + TanStack codegen packages, also:
+
+```bash
+npm install --save-dev @metaobjectsdev/codegen-ts-react @metaobjectsdev/codegen-ts-tanstack
+```
+
+## `metaobjects.config.ts`
+
+Codegen is wired in a type-checked TS config at the project root. `defineConfig`
+comes from `@metaobjectsdev/cli`; the generators come from their packages.
+
+```ts
+import { defineConfig } from "@metaobjectsdev/cli";
+import { entityFile, queriesFile, routesFile, barrel } from "@metaobjectsdev/codegen-ts/generators";
+import { formFile } from "@metaobjectsdev/codegen-ts-react";
+import { tanstackQuery, tanstackGrid } from "@metaobjectsdev/codegen-ts-tanstack";
+
+export default defineConfig({
+  outDir: "src/generated",
+  dialect: "postgres",                 // "postgres" | "sqlite" | "d1" (D1 is TS-only)
+  apiPrefix: "/api",                   // flows to routes AND client fetch URLs
+  columnNamingStrategy: "snake_case",  // "snake_case" (default) | "literal" | "kebab-case"
+  generators: [
+    entityFile(), queriesFile(), routesFile(), barrel(),
+    formFile(), tanstackQuery(), tanstackGrid(),
+  ],
+});
+```
+
+A second file, `.metaobjects/config.json`, holds static project state parseable by
+non-TS tooling; `meta init` scaffolds both plus the `metaobjects/` source dir.
+
+## The generators
+
+From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
+
+| Generator | Emits per entity |
+|---|---|
+| `entityFile()` | `<Entity>.ts` — Drizzle table + FK `.references()` + `relations()` + inferred types + Zod insert/update schemas + `<Entity>FilterAllowlist` / `<Entity>SortAllowlist` |
+| `queriesFile()` | `<Entity>.queries.ts` — typed CRUD (`findPostById`, `listPosts`, `createPost`, `updatePost`, `deletePostById`) |
+| `routesFile()` | `<Entity>.routes.ts` — Fastify CRUD routes on the cross-port REST contract. `routesFileHono()` is the Hono/Workers variant |
+| `barrel()` | `index.ts` re-exporting each `<Entity>.ts` (one-shot, not per-entity) |
+| `promptRender()` | `render<Name>()` per `template.prompt` |
+| `outputParser()` | `<Name>.output.ts` (`parse*` / `safeParse*`) per `template.output` |
+
+## Docs — `meta docs` (one door, two surfaces)
+
+Documentation is NOT a `meta gen` generator. The single door is the `meta docs`
+command, which emits two cross-linked **surfaces** under one output dir (default
+`./docs`):
+
+- **model surface** (`./docs/<Entity>.md`, `./docs/<Template>.md`) — the neutral
+  metadata reference: one page per entity and per template, including the linked
+  template-source section.
+- **api surface** (`./docs/api/<Entity>.md`, `./docs/api/README.md`,
+  `./docs/api/AGENT-API.md`) — the SDK/API reference: the concrete imports,
+  function signatures, payload field shapes, and runnable examples for *this*
+  project's generated code.
+
+```bash
+npx meta docs                     # both surfaces → ./docs (model) + ./docs/api (api)
+npx meta docs --model             # model surface only
+npx meta docs --api               # api surface only
+npx meta docs --out ./site-docs   # write under a different root
+```
+
+Other flags: `--layout flat|package`, `--base-url <url>`. Configure defaults in a
+`docs:` block in `metaobjects.config.ts` (`outDir`, `layout`, `baseUrl`,
+`surfaces`); CLI flags override it. The api surface needs the gen config
+(it documents what the codegen produced); with no config it is skipped with a note,
+and the model surface still emits from metadata alone.
+
+**Before calling any generated code, read `./docs/api/AGENT-API.md`** — it has the
+exact imports, signatures, payload field shapes, and runnable examples for this
+project's generated API, so you don't have to guess them.
+
+From `@metaobjectsdev/codegen-ts-react`: `formFile()` → `<Entity>.form.tsx`.
+From `@metaobjectsdev/codegen-ts-tanstack`: `tanstackQuery()` → `<Entity>.hooks.ts`
+(5 React Query hooks), `tanstackGrid()` → `<Entity>.columns.tsx`,
+`tanstackGridHook()` → `<Entity>.grid.tsx`.
+
+`entityFile({ allowlists: false })` drops the `runtime-ts/drizzle-fastify` import
+for edge/worker consumers that don't mount server routes. Per-entity opt-out:
+`@emitTanstack: false` on the entity skips its hook + column files.
+
+## Run
+
+```bash
+npx meta gen                 # load metadata → render → 3-way merge → write
+npx meta gen --dry-run       # preview without writing
+npx meta gen --watch         # re-run on metadata file change
+npx meta gen Author Post     # scope to named entities
+```
+
+Generated files carry an `@generated by @metaobjectsdev/codegen-ts` header; the
+runner overwrites those and refuses to touch files without it. Hand-customizations
+that metadata can't express live in sibling `<Entity>.extra.ts` files.
+
+## Multiple output targets
+
+A `targets: { web: { outDir }, api: { outDir } }` registry plus a per-generator
+`target` routes each artifact to its own package (model → database package, routes →
+API app, hooks/forms → web app). The top-level `outDir` is the implicit `default`
+(entity-module) target; set `entityModuleImportBase` on it when generators route
+elsewhere so cross-target imports resolve. With no `targets`, output is
+byte-identical to a single-`outDir` project.
+
+## Field subtype → column mapping
+
+Deterministic per dialect: `field.string` + `@maxLength` → `varchar(N)`,
+`field.currency` → integer minor units (`bigint`), `field.uuid` → native `uuid`
+(Postgres) + `gen_random_uuid()`, `field.enum` → `varchar` + `CHECK`. Override a
+field's physical column name with `@column` on the field; the DB schema name lives
+on `source.rdb` via `@schema`.

metaobjects/agent_context/_content/skills/metaobjects-prompts/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: metaobjects-prompts
+description: Use when declaring or using MetaObjects prompt construction: template.prompt/template.output, typed payload projections, provider-resolved text, deterministic render, prompt-drift verify, and parser-on-receipt.
+---
+
+# MetaObjects prompt construction
+
+The fourth pillar: **a prompt is code, not a string scattered across services.**
+Declare a prompt's payload as a typed projection (payload bloat becomes a diff),
+keep its text external and provider-resolved, and render it deterministically —
+snapshot-testable, cache-stable, and drift-checked at build time. The same
+machinery renders any text artifact: emails, exports, docs, `llms.txt`.
+
+This skill is port-agnostic. The exact render/parse API for *this* project's server
+language lives in a reference fragment (pointed to at the bottom).
+
+## The two template subtypes
+
+A **template** is a typed pair: a logical reference to external text + a payload
+value-object declaring exactly what data the text expects.
+
+| Subtype | Use | Extra attrs |
+|---|---|---|
+| `template.prompt` | LLM-targeted | `@maxTokens`, `@requiredSlots`, `@model` |
+| `template.output` | email / docs / config / export | (generic only) |
+
+Both carry the generic attrs:
+
+| Attr | Required | Purpose |
+|---|---|---|
+| `@payloadRef` | yes | the `object.value` declaring the payload shape |
+| `@textRef` | yes | the 2-layer logical text reference `group/source`, resolved by a provider |
+| `@format` | no | `text` (default) / `html` / `xml` / `csv` / `json` / `markdown` / `spreadsheet` — drives the escaper |
+| `@maxChars` | no | build-time size budget |
+
+## The payload is an `object.value` projection
+
+The payload is **not** an entity — it's an `object.value` whose every field carries
+an `origin.*` child saying where its value comes from. Three origin subtypes:
+
+| Origin | Behavior |
+|---|---|
+| `origin.passthrough @from "Entity.field"` | payload property matches the source field |
+| `origin.aggregate @agg <count\|sum\|avg\|min\|max>` | `count`→long, `avg`→double, others match source |
+| `origin.collection @via "Parent.rel"` | a list of a nested payload, assembled from a relationship |
+
+Declaring the payload as a projection is what makes payload bloat visible: adding a
+field to the prompt is a diff on the `object.value`, and a renamed source field
+breaks the build instead of silently degrading the prompt.
+
+```json
+{
+  "metadata.root": {
+    "package": "acme::blog",
+    "children": [
+      {
+        "object.value": {
+          "name": "WelcomePayload",
+          "children": [
+            { "field.string": { "name": "displayName",
+              "children": [ { "origin.passthrough": { "@from": "Author.name" } } ] } },
+            { "field.long": { "name": "postCount",
+              "children": [ { "origin.aggregate": { "@agg": "count", "@of": "Post.id", "@via": "Author.posts" } } ] } },
+            { "field.object": { "name": "posts", "@objectRef": "PostSummary",
+              "children": [ { "origin.collection": { "@via": "Author.posts" } } ] } }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "PostSummary",
+          "children": [
+            { "field.string": { "name": "title",
+              "children": [ { "origin.passthrough": { "@from": "Post.title" } } ] } }
+          ]
+        }
+      },
+      {
+        "template.prompt": {
+          "name": "WelcomePrompt",
+          "@payloadRef": "WelcomePayload",
+          "@textRef": "lobby/welcome",
+          "@format": "xml",
+          "@maxTokens": 500
+        }
+      }
+    ]
+  }
+}
+```
+
+## Prompt text is external + provider-resolved (never inlined)
+
+`@textRef` is a 2-layer logical reference `group/source` (folder/file,
+table/key, collection/document). The prompt text itself **never lives in
+metadata** — at runtime a configured **provider** resolves the reference to the
+actual Mustache text:
+
+- a filesystem provider (L1 = folder, L2 = file) — the dev default;
+- an in-memory provider (a string map) — tests;
+- a classpath/resource provider on the JVM;
+- or a consumer-supplied provider (RDB / vector store / …).
+
+Locale, A/B, dynamic, and evolutionary prompt variants all live behind the
+provider seam without touching metadata.
+
+## `render()` is deterministic + byte-stable
+
+Rendering is a pure function: `(payload VO, resolved text) → string`. Same inputs,
+byte-identical output — across runs and across every language port. That stability
+is what protects **exact-prefix prompt-cache hits**: a stray whitespace change can't
+silently break a cache prefix because the output doesn't drift. Determinism rules
+the engine enforces:
+
+- arrays only for iteration (no object-key iteration);
+- no locale/number/date formatting in the engine — pre-format on the payload;
+- pinned trailing-newline + Mustache standalone-tag whitespace;
+- `@format` drives an engine-owned escaper (CSV/spreadsheet escapers neutralize a
+  leading `= + - @ \t \r` per the OWASP CSV-injection guard).
+
+For the `xml`-format example above with payload `{ displayName: "Ada", postCount:
+12, posts: [{title:"Hello"}, {title:"Mustache"}] }`, every port renders the same
+bytes. You render the prompt, call your LLM client (provider-agnostic — codegen
+emits no provider-side schema), then parse the response.
+
+## `verify` fails the build on prompt-drift
+
+For every template, the verify step resolves the text, parses each `{{...}}`
+reference, and checks it exists on the payload VO. If the text references
+`{{authorName}}` but the payload only has `displayName`, **the build fails.** This
+is the prompt-vs-payload drift gate — run it in CI. It walks both `template.prompt`
+and `template.output` nodes the same way.
+
+## `template.output` also generates a parser-on-receipt
+
+For every `template.output`, codegen emits a **typed parser** that turns an LLM/raw
+response back into the `@payloadRef` value-object — the reverse direction, reusing
+the same payload VO (no new authoring). Each port emits it idiomatically: a
+throw-on-invalid parse plus, where the language has the precedent, a Result-style
+"safe" variant that doesn't throw. The parser file is a companion to the payload-VO
+file; `verify` catches payload-VO ↔ parser drift at build time too.
+
+The three-step consumer pattern is identical everywhere: render the prompt → call
+your LLM client → parse the response with the generated parser.
+
+---
+
+For this project's server-language parser specifics, read every `references/*.md` file in this skill's directory (one per server language in this project's stack).

metaobjects/agent_context/_content/skills/metaobjects-prompts/references/csharp.md

@@ -0,0 +1,110 @@
+# C# parser-on-receipt
+
+For every `template.output`, `MetaObjects.Codegen`'s `OutputParserGenerator` emits a
+**typed parser** that validates an LLM/raw response against the template's
+`@payloadRef` payload record. This is the receive side only — codegen emits **no**
+provider/LLM-call layer; you compose the call yourself. The payload record comes from
+the payload generator, so the parser and the payload VO can't silently drift.
+
+## Contents
+- Wire the generator
+- What it emits
+- The three-step consumer pattern
+- Recommended LLM caller (bring-your-own)
+- Consumer dependency
+- Drift gate
+
+## Wire the generator
+
+`OutputParserGenerator` (stable name `output-parser`) runs as part of
+`dotnet meta gen`, alongside the payload generator that emits the record it parses
+into:
+
+```bash
+dotnet meta gen ./metadata --out ./Generated --namespace Acme.Blog
+```
+
+## What it emits
+
+Per `template.output`, `dotnet meta gen` writes one `<TemplateName>.output.cs` with a
+static `<TemplateName>Parser` following the .NET BCL `Parse`/`TryParse` dual API —
+`Parse` throws, `TryParse` returns a bool plus an out-error:
+
+```csharp
+// generated <TemplateName>.output.cs (shape)
+public static class NpcResponseParser
+{
+    /// <exception cref="JsonException">malformed JSON or schema mismatch.</exception>
+    public static NpcResponse Parse(string text) =>
+        JsonSerializer.Deserialize<NpcResponse>(text, Options)
+            ?? throw new JsonException("deserialized to null");
+
+    public static bool TryParse(string text,
+        [NotNullWhen(true)] out NpcResponse? value,
+        [NotNullWhen(false)] out string? error) { /* ... */ }
+}
+```
+
+The `[NotNullWhen]` attrs let nullable-flow analysis use `value` without a null-check
+after a `true` return (and `error` after `false`). For `@format: json|xml` outputs the
+generator also emits a tolerant `Extract(string[, ExtractOptions])` (self-contained) +
+`Extract(MetaObject, string, ...)` (runtime-delegating, fully populating nested
+components) returning an `ExtractionResult` with a nullable `<Payload>Extracted` mirror
+— a classified per-field report rather than a throw.
+
+## The three-step consumer pattern
+
+Render the prompt → call your LLM client (provider-agnostic; nothing is generated
+here) → parse the response with the generated parser:
+
+```csharp
+string llmResponse = await myLlmClient.CompleteAsync(promptText);   // YOUR code — no generated provider
+
+// Throwing path
+var npc = NpcResponseParser.Parse(llmResponse);
+
+// TryParse for explicit error handling
+if (NpcResponseParser.TryParse(llmResponse, out var npc, out var error))
+    return Ok(npc);
+return BadRequest(new { error });
+```
+
+## Recommended LLM caller (bring-your-own)
+
+`dotnet meta gen` emits **no** provider/LLM-call layer and never will — calling is a
+commodity the ecosystem already solves (ADR-0024). You bring the caller; MetaObjects
+owns the typed render → parse (above) → record. For the call step use the idiomatic
+.NET library:
+
+```csharp
+using Microsoft.Extensions.AI;   // recommended — IChatClient is provider-agnostic
+
+IChatClient client = /* an Anthropic / OpenAI / Azure IChatClient */;
+ChatResponse resp = await client.GetResponseAsync(promptText);
+string text = resp.Text;
+
+var npc = NpcResponseParser.Parse(text);   // the generated parser, above
+```
+
+**Recommended: Microsoft.Extensions.AI** (`IChatClient`) — the emerging
+provider-agnostic .NET standard; its one-method shape matches MetaObjects' call seam.
+For higher-level agent orchestration, **Semantic Kernel** layers on top of the same
+`IChatClient`.
+
+> The typed-trace recorder + render→call→record convenience loop ship in TypeScript
+> today; the C# port is planned (ADR-0024). Until then the call is your code and the
+> generated parser is the typed receive side.
+
+## Consumer dependency
+
+`System.Text.Json` ships in the .NET 8 BCL — no NuGet to add. The generated parser
+uses strict (case-sensitive) options.
+
+## Drift gate
+
+`MetaObjects.Render`'s `Verify.Check(string templateText, IReadOnlyList<PayloadField>
+fields, VerifyOptions? options = null) -> IReadOnlyList<VerifyError>` walks a Mustache
+template's tokens against the payload field tree — each `{{...}}` that doesn't resolve
+yields a `VerifyError(Code, Path)` (empty list = no drift). Assert it is empty in an
+xUnit test to fail the build on prompt/payload drift; `dotnet meta verify` additionally
+catches a stale committed parser.