metaobjects 0.9.0__py3-none-any.whl

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

@@ -0,0 +1,108 @@
+# Java parser-on-receipt
+
+For every `template.output`, `codegen-spring`'s `SpringOutputParserGenerator` 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.
+
+## Contents
+- Wire the generator
+- What it emits
+- The three-step consumer pattern
+- Recommended LLM caller (bring-your-own)
+- Drift gate
+
+## Wire the generator
+
+Add `SpringOutputParserGenerator` (alongside `SpringPayloadGenerator`, which emits
+the payload record it parses into) to the Maven plugin's `<generators>` list:
+
+```xml
+<generator>
+  <classname>com.metaobjects.generator.spring.SpringPayloadGenerator</classname>
+  <args><outputDir>${project.build.directory}/generated-sources/java</outputDir></args>
+</generator>
+<generator>
+  <classname>com.metaobjects.generator.spring.SpringOutputParserGenerator</classname>
+  <args><outputDir>${project.build.directory}/generated-sources/java</outputDir></args>
+</generator>
+```
+
+## What it emits
+
+Per `template.output`, `mvn metaobjects:generate` writes a `<Name>Parser` class with a static
+`parse` method returning the `@payloadRef` payload record. The strict path throws
+`com.fasterxml.jackson.core.JsonProcessingException` on malformed input:
+
+```java
+// generated <Name>Parser.java (shape)
+public final class NpcResponseParser {
+    private NpcResponseParser() { }   // no instances
+
+    public static NpcResponsePayload parse(String text) throws JsonProcessingException {
+        // Jackson-backed: validates the text against the payload record
+    }
+}
+```
+
+For `@format: json|xml` outputs the generator also emits a tolerant best-effort
+variant (`extractLenient(...)` returning an `ExtractionResult<NpcResponsePayload>`
+from `com.metaobjects.render.extract`) for cases where you want classification
+rather than a throw. The payload record itself comes from `SpringPayloadGenerator`
+— the parser is a companion to it, so the parser and payload VO can't silently
+drift.
+
+## 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:
+
+```java
+String promptText = Renderer.render(/* template ref + payload + provider */);
+String llmResponse = myLlmClient.call(promptText);     // YOUR code — no generated provider
+
+NpcResponsePayload npc = NpcResponseParser.parse(llmResponse);   // throws on bad shape
+```
+
+## Recommended LLM caller (bring-your-own)
+
+`codegen-spring` emits **no** provider/LLM-call layer and never will — calling is a
+commodity the ecosystem already solves, and a maintained vendor wrapper would chase
+SDK churn (ADR-0024). You bring the caller; MetaObjects owns the typed render →
+parse (above) → record. For the call step use the idiomatic JVM library:
+
+```java
+// Spring AI (recommended) — provider-agnostic ChatClient; YOUR code, no generated provider
+String response = chatClient.prompt()
+    .system(systemText)
+    .user(promptText)
+    .call()
+    .content();
+
+NpcResponsePayload npc = NpcResponseParser.parse(response);   // the generated parser, above
+```
+
+**Recommended: Spring AI** (`ChatClient`) — Spring-native, provider-agnostic
+(Anthropic / OpenAI / Azure / Bedrock / Ollama), fits an OMDB + Spring-tx app.
+Non-Spring JVM apps: **LangChain4j** (`ChatLanguageModel.generate(prompt)`) is the
+equivalent one-call seam.
+
+> The typed-trace recorder + render→call→record convenience loop ship in TypeScript
+> today; the JVM port is planned (ADR-0024). Until then the call is your code and the
+> generated parser is the typed receive side.
+
+## Drift gate
+
+The render module's static `Verify.check(String templateText, List<PayloadField> fields, VerifyOptions options)`
+walks a Mustache template's tokens against a payload field tree and returns a
+`List<VerifyError>` — each `{{...}}` reference that doesn't resolve against the
+payload fields yields an error (empty list = no drift). `VerifyOptions.empty()`
+supplies a fully-defaulted options record; `VerifyOptions(provider, requiredSlots,
+requiredTags)` adds partial resolution and required-slot/-tag checks. For the
+output-format fragment specifically, `Verify.checkOutputPrompt(String fragment,
+List<String> requiredFieldNames)` returns a `List<VerifyError>` for every required
+field name absent from the rendered fragment. Assert the returned list is empty in a
+JUnit test in the Maven `test` phase to fail the build on prompt/payload drift. The
+`metaobjects:verify` codegen-drift goal additionally catches a stale committed
+parser. The emitted parser imports Jackson (`com.fasterxml.jackson`), normally
+already on a Spring Boot classpath.

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

@@ -0,0 +1,130 @@
+# Kotlin parser-on-receipt
+
+For every `template.output`, `codegen-kotlin`'s `KotlinOutputParserGenerator` emits
+a **typed parser** that validates an LLM/raw response against the template's
+`@payloadRef` payload data class. This is the receive side only — codegen emits
+**no** provider/LLM-call layer; you compose the call yourself. The payload data
+class itself comes from `KotlinPayloadGenerator` (a `@Serializable data class`), so
+the parser and the payload VO can't silently drift.
+
+## Contents
+- Wire the generators
+- What it emits
+- The three-step consumer pattern
+- Consumer dependency
+- Recommended LLM caller (bring-your-own)
+- Drift gate
+
+## Wire the generators
+
+Add `KotlinOutputParserGenerator` (alongside `KotlinPayloadGenerator`, which emits
+the payload it parses into) to the Maven plugin's `<generators>` list:
+
+```xml
+<generator>
+  <classname>com.metaobjects.generator.kotlin.KotlinPayloadGenerator</classname>
+  <args><outputDir>${project.build.directory}/generated-sources/kotlin</outputDir></args>
+</generator>
+<generator>
+  <classname>com.metaobjects.generator.kotlin.KotlinOutputParserGenerator</classname>
+  <args><outputDir>${project.build.directory}/generated-sources/kotlin</outputDir></args>
+</generator>
+```
+
+## What it emits
+
+Per `template.output`, `mvn metaobjects:generate` writes a `<Name>Parser.kt`
+`object` with a dual API matching kotlinx.serialization's exception model plus the
+Kotlin stdlib `Result<T>` convention:
+
+```kotlin
+// generated <Name>Parser.kt (shape)
+object NpcResponseParser {
+    private val json: Json = Json { ignoreUnknownKeys = false }
+
+    /** Throws kotlinx.serialization.SerializationException on bad input. */
+    fun parseNpcResponse(text: String): NpcResponsePayload =
+        json.decodeFromString<NpcResponsePayload>(text)
+
+    /** Result-style — does not throw. */
+    fun safeParseNpcResponse(text: String): Result<NpcResponsePayload> =
+        runCatching { parseNpcResponse(text) }
+}
+```
+
+For `@format: json|xml` outputs the generator additionally emits a **tolerant**
+best-effort variant — `extractLenient(...)` returning an
+`ExtractionResult<NpcResponseExtracted>` (from `com.metaobjects.render.extract`) for
+cases where you want a classified per-field report rather than a throw. There are
+two overloads: a self-contained one (scalars/enums only; nested components stay
+null) and a `extractLenient(loader, text)` overload that delegates to the runtime
+`MetaObjectExtractor` to fully populate nested-object and array-of-object
+components. The lenient mirror type (`<Name>Extracted`) uses nullable fields per
+the Kotlin null-safety port — a missing/malformed component is `null`, not 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:
+
+```kotlin
+val response: String = myLlmClient.complete(promptText)   // YOUR code — no generated provider
+
+// Throwing path — propagate to your error handler
+val npc = NpcResponseParser.parseNpcResponse(response)
+
+// Or Result-style
+NpcResponseParser.safeParseNpcResponse(response)
+    .onSuccess { npc -> /* use it */ }
+    .onFailure { ex -> log.warn("LLM returned malformed payload", ex) }
+```
+
+## Consumer dependency
+
+The emitted parser imports `kotlinx.serialization.json.Json` and calls
+`Json.decodeFromString<T>(text)`. The `kotlinx-serialization-core` artifact alone
+(which `@Serializable` needs) does NOT include the JSON format — add the JSON
+artifact + the serialization plugin:
+
+```kotlin
+plugins { kotlin("plugin.serialization") version "1.9.x" }
+dependencies {
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.x")
+}
+```
+
+## Recommended LLM caller (bring-your-own)
+
+`codegen-kotlin` 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
+JVM library — Kotlin calls either directly:
+
+```kotlin
+// Spring AI (recommended) — provider-agnostic ChatClient; YOUR code, no generated provider
+val response: String = chatClient.prompt()
+    .system(systemText)
+    .user(promptText)
+    .call()
+    .content()
+
+val npc = NpcResponseParser.parseNpcResponse(response)   // the generated parser, above
+```
+
+**Recommended: Spring AI** (`ChatClient`) for a Spring app, or **LangChain4j**
+(`ChatLanguageModel.generate(prompt)`) for non-Spring JVM — both provider-agnostic,
+both a one-call seam Kotlin uses idiomatically.
+
+> The typed-trace recorder + render→call→record convenience loop ship in TypeScript
+> today; the JVM port is planned (ADR-0024). Until then the call is your code and the
+> generated parser is the typed receive side.
+
+## Drift gate
+
+The render engine is the Java `metaobjects-render` module (Kotlin wraps it). Its
+static `Verify.check(...)` walks a Mustache template's tokens against the payload
+field tree and returns a list of errors for any `{{...}}` reference that doesn't
+resolve against the payload — empty list = no drift. Assert it is empty in a JUnit
+test in the Maven `test` phase to fail the build on prompt/payload drift. The
+`metaobjects:verify` codegen-drift goal additionally catches a stale committed
+parser.

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

@@ -0,0 +1,116 @@
+# Python parser-on-receipt
+
+For every `template.output`, the `output-parser` generator (run via `metaobjects gen`)
+emits a **typed parser** that validates an LLM/raw response against the template's
+`@payloadRef` payload Pydantic model. This is the receive side only — codegen emits
+**no** provider/LLM-call layer; you compose the call yourself. The payload class comes
+from the sibling `payload` generator, so the parser and the payload VO can't silently
+drift.
+
+## Contents
+- Wire the generators
+- What it emits
+- The three-step consumer pattern
+- Recommended LLM caller (bring-your-own)
+- Consumer dependency
+- Drift gate
+
+## Wire the generators
+
+Select `output-parser` (the `payload` generator that emits the `<Name>Payload` it
+parses into runs alongside it):
+
+```bash
+metaobjects gen ./metadata --out ./generated --generators payload,output-parser
+```
+
+`metaobjects gen --list` shows every generator name; the programmatic
+`run_gen(..., generators=[...])` path takes the same names.
+
+## What it emits
+
+Per `template.output`, `metaobjects gen` writes one `<template_name>_output_parser.py`
+with a single throw-only entry point. Python uses one API (not TS's
+`parse`/`safeParse`) because raising `pydantic.ValidationError` is the idiomatic
+failure — the pydantic / Instructor / FastAPI norm; a Result-style wrapper would be
+un-Pythonic.
+
+```python
+# generated <template_name>_output_parser.py (shape)
+from .npc_response_payload import NpcResponsePayload   # the @payloadRef VO (Pydantic v2 BaseModel)
+
+def parse_npc_response(text: str) -> NpcResponsePayload:
+    """Validates text against the payload model.
+
+    Raises:
+        pydantic.ValidationError: when the input does not match the schema.
+    """
+    ...
+```
+
+For `@format: json|xml` outputs the generator additionally emits a **tolerant**
+best-effort variant — `extract_lenient_<name>(text) -> ExtractionResult[<Name>PayloadExtracted]`
+(from the `metaobjects` render `extract` engine) for cases where you want a classified
+per-field report rather than a raise. The lenient mirror (`<Name>PayloadExtracted`)
+uses `Optional[...]` fields — a missing/malformed component is `None`, not a raise.
+
+## 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:
+
+```python
+from pydantic import ValidationError
+from .npc_response_output_parser import parse_npc_response
+
+text = my_llm_client.complete(prompt_text)   # YOUR code — no generated provider
+try:
+    npc = parse_npc_response(text)           # raises pydantic.ValidationError on bad shape
+except ValidationError as exc:
+    log.warning("LLM returned malformed payload: %s", exc)
+```
+
+## Recommended LLM caller (bring-your-own)
+
+`metaobjects 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
+Python library:
+
+```python
+from litellm import completion   # LiteLLM — recommended
+
+resp = completion(
+    model="anthropic/claude-3-5-sonnet",
+    messages=[{"role": "system", "content": system_text},
+              {"role": "user", "content": prompt_text}],
+)
+text = resp.choices[0].message.content
+
+npc = parse_npc_response(text)   # the generated parser, above
+```
+
+**Recommended: LiteLLM** — one OpenAI-shaped `completion()` over 100+ providers; the
+raw text feeds straight into MetaObjects' typed parser/extract. If you want the *LLM*
+to enforce the typed shape instead, **Instructor** or **Pydantic-AI** return a
+validated Pydantic model — but that overlaps MetaObjects' own typed `extract`, so pick
+one boundary, not both.
+
+> The typed-trace recorder + render→call→record convenience loop ship in TypeScript
+> today; the Python port is planned (ADR-0024). Until then the call is your code and
+> the generated parser is the typed receive side.
+
+## Consumer dependency
+
+The generated parser imports `pydantic` (v2 — `model_validate_json`); `pip install
+pydantic`. The tolerant `extract_lenient_*` variant pulls the `metaobjects` render
+`extract` engine, already in the `metaobjects` package.
+
+## Drift gate
+
+The render module's `verify(template_text, fields, *, provider=None,
+required_slots=None, required_tags=None) -> list[VerifyError]` walks a Mustache
+template's tokens against the payload field tree — each `{{...}}` reference that
+doesn't resolve yields a `VerifyError` (empty list = no drift). Assert it is empty in a
+pytest test to fail the build on prompt/payload drift; `metaobjects verify`
+additionally catches a stale committed parser.

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

@@ -0,0 +1,150 @@
+# TypeScript parser-on-receipt
+
+For every `template.output` in your metadata, the `outputParser()` generator (from
+`@metaobjectsdev/codegen-ts/generators`) emits a **typed parser** that validates an
+LLM/raw response against the template's `@payloadRef` payload value-object. This is
+the receive side; codegen emits **no** provider/LLM-call layer — you compose the
+call yourself.
+
+## Contents
+- Wire the generator
+- What it emits
+- The three-step consumer pattern
+- Recommended LLM caller (bring-your-own)
+- Drift gate
+- See which fields a template consumes
+
+## Wire the generator
+
+```ts
+// metaobjects.config.ts
+import { defineConfig } from "@metaobjectsdev/cli";
+import { entityFile, queriesFile, barrel, promptRender, outputParser } from "@metaobjectsdev/codegen-ts/generators";
+
+export default defineConfig({
+  outDir: "src/generated",
+  generators: [
+    entityFile(), queriesFile(), barrel(),
+    promptRender(),    // render<Name>() per template.prompt (the send side)
+    outputParser(),    // parse*/safeParse* per template.output (the receive side)
+  ],
+});
+```
+
+`outputParser({ outDir: "src/generated/outputs", target: "default" })` are the
+options.
+
+## What it emits
+
+Per `template.output` (say named `NpcResponseOutput`, `@payloadRef:
+"NpcResponsePayload"`), `meta gen` writes a self-contained `NpcResponseOutput.output.ts`
+with a Zod schema + a dual API:
+
+```ts
+import { z } from "zod";
+
+const NpcResponseOutputSchema = z.object({
+  name: z.string(),
+  level: z.number().int(),
+  role: z.unknown(),   // field.enum is not value-constrained in the strict parser → z.unknown()
+});
+
+export type NpcResponseOutputData = z.infer<typeof NpcResponseOutputSchema>;
+export type NpcResponseOutputValidationError = z.ZodError;
+
+/** Throws ZodError on bad input. */
+export function parseNpcResponseOutput(text: string): NpcResponseOutputData { /* ... */ }
+
+/** Result-style; never throws. */
+export function safeParseNpcResponseOutput(text: string):
+  | { success: true; data: NpcResponseOutputData }
+  | { success: false; error: NpcResponseOutputValidationError } { /* ... */ }
+```
+
+The dual API mirrors Zod's idiomatic shape: `parse*` throws a `ZodError`,
+`safeParse*` returns a discriminated union. The emitted `<Name>Data` type is
+structurally identical to the `promptRender()` payload VO, so you can pass values
+between the render and parse sides interchangeably.
+
+Field-type → Zod mapping: `field.string` → `z.string()`; `field.int`/`long`/`short`/`byte`
+→ `z.number().int()`; `field.double`/`float` → `z.number()`; `field.boolean` →
+`z.boolean()`; `field.object` (with `@objectRef`) → a nested `z.object({...})`;
+`isArray: true` → wrapped in `z.array(...)`. Any subtype outside this scalar set —
+including `field.enum` — falls through to `z.unknown()` in the strict
+`parse*`/`safeParse*` schema (the value-constrained `z.enum([...])` form is emitted
+in the entity insert/update schemas, not in this output parser; the lenient extract
+path carries the enum-as-string handling).
+
+## 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:
+
+```ts
+import { renderNpcPrompt } from "./generated/prompts";
+import { parseNpcResponseOutput, safeParseNpcResponseOutput } from "./generated/NpcResponseOutput.output";
+
+const promptText  = renderNpcPrompt(payload, textProvider);
+const llmResponse = await myLlmProvider.call(promptText);   // YOUR code — no generated provider
+
+// Throwing path:
+const npc = parseNpcResponseOutput(llmResponse);
+
+// Result-style:
+const r = safeParseNpcResponseOutput(llmResponse);
+if (!r.success) log.warn("malformed LLM payload", r.error);
+else handle(r.data);
+```
+
+## Recommended LLM caller (bring-your-own)
+
+MetaObjects generates **no** provider/LLM-call layer and never will — the call is a
+commodity the ecosystem already solves, and a maintained vendor wrapper would just
+chase SDK churn (ADR-0024). You bring the caller; MetaObjects owns the typed
+render → parse → record. For the call step, plug the idiomatic library into the
+one-method `LlmClient` seam from `@metaobjectsdev/ai-runtime`:
+
+```ts
+import { generateText } from "ai";              // Vercel AI SDK — recommended
+import { anthropic } from "@ai-sdk/anthropic";
+import type { LlmClient } from "@metaobjectsdev/ai-runtime";
+
+export const llm: LlmClient = {
+  async complete({ prompt, model, system }) {
+    const { text } = await generateText({ model: anthropic(model), system, prompt });
+    return { body: text };  // also map usage/model/finishReason from the result → cost + token columns
+  },
+};
+```
+
+**Recommended: the Vercel AI SDK (`ai`)** — provider-agnostic (`generateText` /
+`generateObject` over Anthropic / OpenAI / Google / …), first-class structured
+output, the de-facto TS standard. Single-provider apps can implement `complete`
+directly over `@anthropic-ai/sdk` / `openai`; heavy chains can use LangChain.js —
+the seam is one method either way.
+
+With a client in hand, the generated `record<Entity>` helper (the `trace-helper`
+generator) and `@metaobjectsdev/ai-runtime`'s `callLlm` do render → call → **typed
+trace persist** in one call, recording request/response as typed value objects in
+your own DB. The parser above is the standalone receive side if you don't want the
+recorder.
+
+## Drift gate
+
+`meta verify` walks every `template.output`'s `@payloadRef` resolution and fails the
+build (exit 1, `(output)`-prefixed diagnostic) if a reference can't be resolved —
+catching payload-VO ↔ parser drift at build time. The emitted parser imports `zod`;
+it's usually already a dependency (Drizzle / `runtime-ts` lean on it), else
+`npm i zod`.
+
+## See which fields a template consumes
+
+Run `meta docs` to emit the model surface to `./docs` — one page per
+`template.output` at `docs/<Template>.md`. Each template page has a
+`## Template source` section that shows the Mustache source with every `{{var}}`
+linked to that field's doc page (`docs/<Owner>.md#field-<name>`), plus a variables
+table — so you can see exactly which payload fields a template reads. Those links are
+build-time drift-gated against the render `verify()` engine, so a link can't claim a
+field that `verify()` would reject. (`meta docs` is the single door for all docs —
+it's a command, not a `meta gen` generator; the model surface here lands in `./docs`,
+the SDK/API surface under `./docs/api`.)

metaobjects/agent_context/_content/skills/metaobjects-runtime-ui/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: metaobjects-runtime-ui
+description: Use when wiring MetaObjects generated code into an app: runtime queries/CRUD, REST routes, and the web client (forms, grids, filters).
+---
+
+# Wiring MetaObjects runtime + web client
+
+This skill is the procedure for putting generated code to work: querying/persisting
+through the runtime tier, serving the REST contract, and consuming it from the
+universal web client. It is port-agnostic — the cross-cutting contracts are here;
+the server- and client-specific imports/types live in reference fragments (pointed
+to at the bottom).
+
+## The runtime return-type contract
+
+A port's runtime returns **native in-process language types**, never wire strings.
+Query the runtime and you get back the language's natural type for each field:
+
+- `field.decimal` → the language's exact-decimal type (`BigDecimal` / `decimal` /
+  `Decimal`). Decimal is **lossless end-to-end** — no float round-tripping.
+- temporal fields → native date/instant types.
+- `field.object` (jsonb) → a native map/object.
+- **TypeScript is the documented outlier: `field.decimal` is a `string`** in the
+  TS runtime (JS has no native exact decimal), preserving precision as text.
+
+Wire canonicalization (integer minor units for currency, ISO-8601 strings for
+temporals, canonical hex for UUID) is applied only at the **serialization
+boundary** — when a row leaves over HTTP — never inside the runtime query path. So:
+compute with native types in-process; the HTTP layer handles wire encoding.
+
+## Generated repo / query helpers take the context as a parameter
+
+Generated finders and CRUD helpers **do not** reach for a module-level `db`
+singleton. They take the persistence context (connection / session / data-access
+handle) as an explicit **parameter**. You own the connection's lifecycle and pass
+it in:
+
+```
+const rows = await findPostsForAuthor(db, authorId);   // db is passed, not imported
+```
+
+This keeps generated code free of global state, makes it testable, and lets one
+process talk to multiple databases (multi-tenant, read-replica). Construct/own the
+context in your app; thread it through every generated call.
+
+## The REST contract
+
+Generated (or hand-written) routes speak one cross-port HTTP contract so the same
+universal web client serves any backend language.
+
+### URL grammar
+
+`apiPrefix` (default `/api`, set in project config) flows to both the server routes
+and the client fetch URLs. `<entity>` is lowercased + pluralized (`Author` →
+`authors`).
+
+| Verb | Path | Purpose |
+|---|---|---|
+| `GET` | `/<apiPrefix>/<entity>?filter[...][...]=...&sort=...&limit=N&offset=N&withCount=1` | List |
+| `GET` | `/<apiPrefix>/<entity>/:id` | Get by id |
+| `POST` | `/<apiPrefix>/<entity>` | Create (201) |
+| `PATCH` | `/<apiPrefix>/<entity>/:id` | Update (partial) |
+| `PUT` | `/<apiPrefix>/<entity>/:id` | Update (replace) — optional |
+| `DELETE` | `/<apiPrefix>/<entity>/:id` | Delete (204) |
+
+### Filter operators by field subtype
+
+Filters use a bracketed qs: `filter[<field>][<op>]=<value>`. A bare
+`filter[<field>]=<value>` is sugar for `eq`. The operator set is **gated by field
+subtype** via the generated `<Entity>FilterAllowlist` — an unsupported operator for
+a field → HTTP 400.
+
+| Operator | Strings | Numbers / Dates | Booleans |
+|---|---|---|---|
+| `eq`, `ne`, `isNull` | yes | yes | `eq` + `isNull` only |
+| `in`, `like` | yes | `in` only | – |
+| `gt`, `gte`, `lt`, `lte` | – | yes | – |
+
+These eight (`eq` `ne` `gt` `gte` `lt` `lte` `in` `like` `isNull`) are the whole
+closed set — every port implements these and only these.
+
+### Sort + pagination
+
+- `sort=<field>:asc|desc` — single sort key; the field must be in
+  `<Entity>SortAllowlist`.
+- `limit=N` / `offset=N` — page size + offset, identical across every endpoint.
+- `withCount=1` — switches the list response from `[<row>...]` to
+  `{ rows: [...], total: N }` (grids always send it).
+
+### Wire format
+
+JSON bodies (`application/json; charset=utf-8`). Single-row responses (`GET /:id`,
+`POST`, `PATCH`, `PUT`) have **no envelope** — the body is the row. Type encodings:
+
+| Field type | JSON | Notes |
+|---|---|---|
+| `field.string` / `field.uuid` / `field.enum` | string | UUID is canonical hex `8-4-4-4-12` |
+| `field.int` / `field.long` / `field.double` | number | `long` may be string on overflow (per-port) |
+| `field.boolean` | boolean | |
+| `field.date` | string | ISO 8601 `YYYY-MM-DD` |
+| `field.timestamp` | string | ISO 8601 with timezone |
+| `field.currency` | **integer minor units** | cents/yen; float arithmetic forbidden; server never formats |
+| `field.object` | object | per the sub-object schema |
+
+The currency invariant is load-bearing: integer minor units on the wire, always.
+Formatting happens client-side with locale-aware code.
+
+Errors: non-2xx returns `{ "error": "<short_code>", "message"?: "..." }`. 400 for
+validation/filter-parser errors, 404 for not-found (`{ "error": "not_found" }`),
+5xx implementation-defined. Treat any 4xx as user-facing, any 5xx as retryable.
+
+## The EntityFetcher browser contract
+
+The web client never calls `fetch` directly. Every generated hook delegates to a
+single `EntityFetcher` you supply once at the app root:
+
+```ts
+export type EntityFetcher = <T>(path: string, init?: RequestInit) => Promise<T>;
+```
+
+Your fetcher resolves the `path` (always starting with `apiPrefix`) to a full URL,
+attaches auth (cookie / bearer / API key) per your policy, parses the JSON, and
+throws on non-2xx (the hooks rely on the throw for error state). Provide it via the
+fetcher-provider at the tree root; every generated hook reads it from context. The
+generated grid and form components, filter-qs serializer, and cell renderers all
+sit on top of this one seam.
+
+---
+
+For this project's runtime + web-client specifics, read every `references/*.md` file in this skill's directory (one per server language and client framework in this project's stack).