fix(agent-context): the agent-facing docs learn ADR-0052's direction split and the sources set

Two shipped-and-wrong agent-facing surfaces. The human-facing docs were correct in both
cases — only the agent context missed the pass, which is the worse half to miss, because
an agent reads it as ground truth and acts on it without a second source.

1. @PromptStyle WAS DOCUMENTED EXACTLY BACKWARDS. capability-checklist.md claimed it "is on
   `template.output` ONLY; authoring it on `template.prompt` fails load with
   ERR_UNKNOWN_ATTR". The registry says the opposite — @PromptStyle is registered on
   `template.prompt` (spec/metamodel/template.json:120, byte-gated at
   expected-registry.json:4147). An agent following the checklist would have authored the
   attribute on the one subtype where it actually fails to load, then been told by the same
   file that the resulting error was impossible. The claim appeared TWICE in that block (the
   inventory line and the parenthetical), so deleting either alone left it standing.

   ADR-0052 Phase G swept the `metaobjects-prompts` skill and its five per-port references;
   `metaobjects-codegen` and `metaobjects-audit` were missed. Both now carry the ruling: a
   template subtype's axis is DIRECTION — `template.prompt` owns both halves of talking to a
   model (a prompt carrying @responseRef owns the parser, the tolerant extract and the FR-010
   output-format fragment), while `template.output` is outbound only and emits no parser.

   The audit heuristics were the load-bearing part: five of them told an auditor to flag a
   hand-rolled parser "where a `template.output` node exists", which is now the wrong node to
   look for — that check would miss every real finding and manufacture false ones. All
   re-keyed onto a responding `template.prompt`.

   Attr inventories reconciled against the registry rather than hand-inverted, which turned up
   four MORE errors the report did not mention: template.prompt was missing @PromptStyle and
   @responseFormat, template.output was missing @payloadRef/@textRef/@format/@maxchars, and
   template.toolcall was missing @maxtokens. The emitted TS filenames were stale too
   (.output.ts is now <Name>.response.ts, plus .responseFormat.ts / .extractor.ts) — verified
   against the generators, not the ADR, since an accepted ADR is a decision and the emitter is
   the fact. Generator CLASS names (SpringOutputParserGenerator et al) are unchanged and kept.

2. `sources` WAS ENTIRELY ABSENT from the scaffolded agent context — `grep -c sources` on
   agent-docs/body.ts returned 0 — while :225 actively asserted `.metaobjects/config.json`
   "is unchanged — it still holds static project state". It holds `sources`, the release's
   headline feature (config.ts:132). So every project scaffolded by `meta init` got agent
   docs that could not describe where its own metadata comes from, and positively said
   nothing had changed.

   Adds a "Where metadata comes from" section stating the rule the feature doc reserves this
   very file for: `metaobjects/` IS THE DEFAULT VALUE of `sources`, never a requirement, and
   must not be assumed to exist. Covers the declaration shape, that all five commands read
   the same set, that a path is read in place and never installed, four-CLI-surface support,
   set-not-list ordering, and strict unknown-key rejection.

   This closes the wording gap no-hardcoded-metadata-dir.test.ts's own allowlist entry
   recorded as known-and-open; that reason is updated rather than left describing a gap that
   no longer exists.

All five byte-gated agent-context-conformance expected trees regenerated via
sdk/scripts/regen-agent-context-conformance.ts.

Verified: sdk 278 pass / 0 fail. cli 596 pass / 2 fail — both pre-existing on main
(verify-requirements-e2e "dangling reference on status=abandoned exits 0" and
requirement-check "allowedValues"), fixed in a peer's unpushed commit, neither touched here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

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

@@ -347,10 +347,12 @@ Per finding: `file:line` → what → generated-equivalent exists? → recommend
   `object.value` fail load with `ERR_SUBTYPE_RULE_VIOLATION`; `@payloadRef` accepts the sourceless
   projection).
 - Silent-degradation hack (`try/except KeyError` or `?? ''` around formatting) — flag every instance.
-- Hand-rolled output parsing (regex / XML / ad-hoc JSON) vs declared `template.output` +
-  generated `parse*` / `safeParse*` / `extract*` parser — **generated in all five ports**
-  (Java's generated `<Name>Parser` owns the Jackson `readValue`); flag a hand-rolled parser
-  in a **non-generated** file where a `template.output` node exists.
+- Hand-rolled output parsing (regex / XML / ad-hoc JSON) vs a declared **responding
+  `template.prompt`** (one carrying `@responseRef`) + generated `parse*` / `safeParse*` /
+  `extract*` parser — **generated in all five ports** (Java's generated `<Name>Parser` owns
+  the Jackson `readValue`); flag a hand-rolled parser in a **non-generated** file where a
+  responding `template.prompt` exists. ADR-0052: a `template.output` is outbound only and
+  generates no parser, so it is not the node to look for here.
 - Engine-side formatting breaking byte-identical render (prompt-cache exact-prefix hits
   depend on byte-stability).
 - `template.toolcall` candidates: LLM tool schemas hand-defined per call vs modeled
@@ -477,7 +479,8 @@ The audit never edits code. Pattern: **dry-run → review the diff → apply**.
   leading-wildcard gating — do NOT flag the absence of those in a non-TS port.
 - **Output-parser codegen** ships in **all five ports** — Java's `SpringOutputParserGenerator`
   *generates* the `<Name>Parser` (the Jackson `readValue` lives inside that generated file). A
-  hand-rolled parser in a **non-generated** file where a `template.output` node exists IS a finding.
+  hand-rolled parser in a **non-generated** file where a **responding `template.prompt`**
+  (`@responseRef`) exists IS a finding. Per ADR-0052 a `template.output` emits no parser.
 - **Python** still hand-wires the FastAPI router + repository impl around a generated
   `APIRouter`; relationship / non-`table` source-kind / `field.object flattened` codegen is partial.
 - **C#** has no ObjectManager runtime tier (EF Core is the runtime) — hand services over the generated `DbContext` are expected.

agent-context/skills/metaobjects-audit/references/capability-checklist.md

@@ -171,17 +171,26 @@ soft-delete / status / type view it models.
 
 ## Template — `template.*` (prompt pillar)
 
-- **`template.prompt`** (`@payloadRef`, `@textRef`, `@responseRef`, `@requiredSlots`,
-  `@requiredTags`, `@maxTokens`, `@maxChars`, `@format`, `@model`) — hunt prompt strings
-  assembled inline in services, payloads built ad-hoc, output parsing without a typed
-  `@responseRef`, or token/char budgets enforced by hand.
-- **`template.output`** (`@kind` = `document` | `email`; `@subjectRef`, `@htmlBodyRef`,
-  `@textBodyRef`, `@promptStyle`, `@requiredTags`) — hunt hand-built document/email rendering +
-  hand-written parse-on-receipt the output template + generated render helper/parser cover.
-  (`@promptStyle` — the FR-010 output-format presentation — is on `template.output` ONLY;
-  authoring it on `template.prompt` fails load with `ERR_UNKNOWN_ATTR`.)
-- **`template.toolcall`** (`@toolName`, `@payloadRef`) — hunt hand-declared LLM tool schemas
-  a modeled tool call describes.
+**A template subtype's axis is DIRECTION** (ADR-0052): `template.prompt` owns everything about
+talking to a model — both the request and the reply — while `template.output` renders an
+artifact for a person or a file and generates **no parser**.
+
+- **`template.prompt`** (`@payloadRef`, `@textRef`, `@responseRef`, `@responseFormat`,
+  `@promptStyle`, `@requiredSlots`, `@requiredTags`, `@maxTokens`, `@maxChars`, `@format`,
+  `@model`) — hunt prompt strings assembled inline in services, payloads built ad-hoc,
+  token/char budgets enforced by hand, and **hand-written parse-on-receipt**: a prompt
+  declaring `@responseRef` owns the inbound half, so the strict parser, the tolerant
+  `extract` mapper and the FR-010 output-format fragment are all generated from it.
+  (`@promptStyle` — the FR-010 output-format presentation, `guide` / `inline` /
+  `exampleOnly` — is on `template.prompt` ONLY; authoring it on `template.output` fails load
+  with `ERR_UNKNOWN_ATTR`.)
+- **`template.output`** (`@kind` = `document` | `email`; `@textRef`, `@subjectRef`,
+  `@htmlBodyRef`, `@textBodyRef`, `@payloadRef`, `@format`, `@maxChars`, `@requiredTags`) —
+  **outbound only.** Hunt hand-built document/email rendering the output template + generated
+  render helper cover. It parses nothing: a parser here would be reading back text the system
+  just rendered and sent.
+- **`template.toolcall`** (`@toolName`, `@payloadRef`, `@maxTokens`) — hunt hand-declared LLM
+  tool schemas a modeled tool call describes.
 - **`template.base`** — abstract base.
 
 ## Attr — `attr.*`
@@ -256,8 +265,10 @@ subtypes with opposite polarity: `requirement.functional` fails when NOTHING imp
     is **generated in all five ports** (api-contract corpus, both lanes) — **flag hand-rolled
     filter parsing anywhere.** Only the richer surface (`?search=`, explicit
     `filter[or][N]` / `filter[and][N]` combinators, leading-wildcard gating) is TS-only.
-    Output-parser codegen also ships in **all five ports** — Java's `SpringOutputParserGenerator`
-    *generates* the parser (the Jackson `readValue` lives inside that generated file). **Python**
+    Output-parser codegen also ships in **all five ports**, keyed on a **responding
+    `template.prompt`** (`@responseRef`), never on a `template.output` (ADR-0052) — Java's
+    `SpringOutputParserGenerator` *generates* the parser (the Jackson `readValue` lives inside
+    that generated file). **Python**
     still hand-wires the FastAPI router around a generated `APIRouter` (relationship /
     non-`table` source-kind / flattened-object codegen is partial). **C#** has no
     ObjectManager runtime tier (EF Core *is* the runtime) — hand services over the generated

agent-context/skills/metaobjects-audit/references/csharp.md

@@ -104,4 +104,5 @@ version across these packages is an intra-port skew finding.
   TS-only — do NOT flag its absence in C#.
 - **Output-parser codegen ships in C#.** `output-parser` / `extractor` / `render-helper`
   generators are available (`dotnet meta gen --generators output-parser`). Absence of
-  wired output parsers where `template.output` nodes exist IS a finding.
+  wired output parsers where a **responding `template.prompt`** (`@responseRef`) exists IS a
+  finding. ADR-0052: a `template.output` is outbound only and generates no parser.

agent-context/skills/metaobjects-audit/references/java.md

@@ -49,7 +49,7 @@ plugin `<configuration>` — that is the source of truth for which generators ru
 | Hand-written `@RestController` on a CRUD entity | `SpringControllerGenerator` should own this; trust the `pom.xml` `<generators>` configuration, not stale docs |
 | `interface <Entity>Repository` with no `@generated` comment | `SpringRepositoryGenerator` emits the stub; compare field by field |
 | `// keep in sync with` / `// mirrors the` | second-source-of-truth comment — always a finding |
-| `ObjectMapper.readValue(` outside a `*Parser.java` file | check if a `template.output` node exists — output-parser codegen ships in Java |
+| `ObjectMapper.readValue(` outside a `*Parser.java` file | check if a responding `template.prompt` (`@responseRef`) exists — output-parser codegen ships in Java |
 | `LIMIT ?` / `OFFSET ?` assembled by hand | generated CRUD routes handle pagination; OMDB `getObjects` accepts `QueryOptions` |
 
 ---
@@ -92,7 +92,8 @@ versioning — **do not flag it** (only intra-port skew matters).
   *generates* the typed `<Name>Parser` class; the Jackson `readValue` call lives inside that
   generated file. It is NOT a defect to see Jackson deserialization in a generated `*Parser.java`
   file. **Do not flag Jackson `readValue` calls in generated `*Parser.java` files.** DO flag a
-  hand-rolled parser in a *non*-generated file where a `template.output` node exists.
+  hand-rolled parser in a *non*-generated file where a responding `template.prompt`
+  (`@responseRef`) exists — per ADR-0052 a `template.output` emits no parser.
 - **Core filter-operator codegen ships in Java — do NOT treat it as deferred.**
   `SpringControllerGenerator` generates the `?filter[field][op]=value` grammar (all 9 operators
   `eq/ne/gt/gte/lt/lte/in/like/isNull`): it parses via the runtime `FilterParser`, validates

agent-context/skills/metaobjects-audit/references/kotlin.md

@@ -101,7 +101,8 @@ cross-port versioning — **do not flag it** (only intra-port skew matters).
   `KotlinOutputParserGenerator` generates the typed parser class AND its deserialization body
   (a kotlinx `Json.decodeFromString` call inside the generated file — kotlinx, not Jackson: the
   #187 Jackson move was jsonb-codec-only, prompt payloads/parsers stay on kotlinx). Only flag
-  a hand-rolled parser in a NON-generated file where a `template.output` node exists.
+  a hand-rolled parser in a NON-generated file where a responding `template.prompt`
+  (`@responseRef`) exists — per ADR-0052 a `template.output` emits no parser.
 - **Core filter-operator codegen ships in Kotlin — do NOT treat it as deferred.**
   `KotlinSpringControllerGenerator` generates the `?filter[field][op]=value` grammar (all 9
   operators `eq/ne/gt/gte/lt/lte/in/like/isNull`) validated against the generated filter allowlist

agent-context/skills/metaobjects-audit/references/typescript.md

@@ -107,7 +107,7 @@ via `metamodelVersion` (see the Phase 0 cross-language consistency item).
 TypeScript is the reference implementation — it ships the full feature set:
 
 - Filter-operator codegen: **complete** — the core `?filter[field][op]` grammar (all 9 operators `eq/ne/gt/gte/lt/lte/in/like/isNull`, `<Entity>FilterAllowlist`) generates in every port; TS additionally ships the richer surface (`?search=`, `filter[or][N]` / `filter[and][N]` combinators, leading-wildcard gating).
-- Output-parser codegen: **complete** (`outputParser()` generator; `parse*`/`safeParse*`/`extract*` per `template.output`).
+- Output-parser codegen: **complete** (`outputParser()` generator; `parse*`/`safeParse*`/`extract*` emitted as `<Name>.response.ts` per **responding `template.prompt`** — one carrying `@responseRef`; ADR-0052).
 - ObjectManager: **complete** (`@metaobjectsdev/runtime-ts`; `kyselyDriver` / `inMemoryDriver`).
 - Schema migrate / `meta verify --db`: **complete** (TS owns the shared migrate engine — ADR-0015).
 - D1 dialect: **TS-only by design** — `dialect: "d1"` in `metaobjects.config.ts` targets Cloudflare D1 via the Wrangler CLI layout. Do NOT recommend porting D1 support to other languages.

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

@@ -61,8 +61,9 @@ name** (kebab-case) that surfaces in diagnostics — reference generators by tha
 name, never by inlining what they emit. Typical generators cover: the entity
 type/model, the DB table/schema, query/finder helpers, REST routes, client
 form/grid/hook artifacts, filter + sort allowlists, payload value-objects, and
-`template.output` parsers. You enable the subset your project needs; an abstract
-entity never emits instance/write artifacts regardless.
+parsers for a responding `template.prompt` (one carrying `@responseRef`). You
+enable the subset your project needs; an abstract entity never emits
+instance/write artifacts regardless.
 
 Per-entity opt-outs exist (e.g. skipping client-side artifacts for a given
 entity) and are set as attributes on the entity in metadata, not in code.

agent-context/skills/metaobjects-codegen/references/csharp.md

@@ -45,8 +45,8 @@ or run the default set. Output lands under `--namespace` in `--output-dir`.
 | `routes` | `<Entity>Routes.cs` — ASP.NET **Minimal API** CRUD per writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (`?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). A TPH base emits polymorphic `GET /<base>(+/{id})` + a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` (create injects the discriminator, cross-subtype get/update/delete → 404). |
 | `filter-allowlist` | per-entity `<Entity>FilterAllowlist` (FR-009 — the server-side field+operator allowlist the routes validate against). |
 | `callable` | `<Entity>.callable.g.cs` — an FR-015 calling method for a `source.rdb @kind="storedProc"|"tableFunction"`, via EF `FromSqlInterpolated` (args from the `@parameterRef` value object in declaration order). |
-| `payload` | `<Payload>.payload.cs` — the strict typed payload `record` (+ any nested element records) per `template.output` `@payloadRef` (an `object.value`) that the parser/extractor bind to. |
-| `output-parser` / `extractor` / `output-prompt` / `render-helper` | the `template.output` prompt-pillar artifacts — the strict parser, the tolerant `extract`, the **output-format prompt fragment** (`output-prompt`; presentation via `@promptStyle: guide`/`inline`/`exampleOnly`), and the typed render helper. See the **prompts** reference. |
+| `payload` | `<Payload>.payload.cs` — the strict typed payload `record` (+ any nested element records) per `template.prompt` `@payloadRef` / `@responseRef` (each an `object.value`): `@payloadRef` types the REQUEST, `@responseRef` the REPLY the parser/extractor bind to. |
+| `output-parser` / `extractor` / `output-prompt` / `render-helper` | the prompt-pillar artifacts for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: these tiers are INBOUND; `template.output` is outbound only and emits no parser). The strict parser, the tolerant `extract`, the **output-format prompt fragment** (`output-prompt`; presentation via `@promptStyle: guide`/`inline`/`exampleOnly`), and the typed render helper. See the **prompts** reference. |
 | `template` | the generic Mustache `templateGenerator()` primitive. |
 
 Metadata lives under `metaobjects/` (or wherever you point `--metadata-dir`) in the

agent-context/skills/metaobjects-codegen/references/java.md

@@ -101,8 +101,8 @@ separate `metaobjects-codegen-base` module instead.)
 | `SpringRepositoryGenerator` | `<Entity>Repository.java` — a hand-stubbed `interface` the consumer implements with their persistence layer (Spring Data JPA / jOOQ / JDBC). For a TPH base the interface is polymorphic + per-subtype-scoped (`listByType`/`findByIdAndType`/`createWithType`/`updateByIdAndType`/`deleteByIdAndType`) over the single table; subtype entities emit no own controller/DTO/repository — they fold into the base. |
 | `SpringValueObjectGenerator` | a Java 21 `record` per `object.value` reached through a `field.object @storage: jsonb` column (single or `@isArray`, transitively through nested VOs) — the typed component the Jackson jsonb codec serializes to/from (carries jakarta validation, unlike a plain payload record). Program D typed-jsonb VOs. |
 | `SpringPayloadGenerator` | a Java 21 `record` per `template` payload VO |
-| `SpringOutputParserGenerator` | the `template.output` strict parser-on-receipt (see the prompts reference) |
-| `SpringOutputPromptGenerator` | the FR-010 output-format prompt fragment for a `template.output` (presentation via `@promptStyle: guide`/`inline`/`exampleOnly`) |
+| `SpringOutputParserGenerator` | the strict parser-on-receipt for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: INBOUND; a `template.output` emits no parser). See the prompts reference. |
+| `SpringOutputPromptGenerator` | the FR-010 output-format prompt fragment for a responding `template.prompt` (presentation via `@promptStyle: guide`/`inline`/`exampleOnly`) |
 | `SpringRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
 | `LlmTraceHelperGenerator` | `<Entity>TraceHelper.java` per concrete entity — the LLM-trace helper |
 | `SpringFilterAllowlistGenerator` | per-entity filter allowlist |

agent-context/skills/metaobjects-codegen/references/kotlin.md

@@ -114,9 +114,9 @@ All live in `metaobjects-codegen-kotlin` under
 | `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController`, five CRUD endpoints on the cross-port REST contract, for writable entities (`source.rdb` `@kind="table"`). A TPH `@discriminator` base emits ONE controller: polymorphic `GET /<base>(+/{id})` plus a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` — create injects the discriminator from the URL (never the body); get/update/delete are scoped to the subtype (cross-subtype → 404); the discriminator is immutable. |
 | `KotlinRepositoryGenerator` | `<Entity>RepositoryBase.kt` — an `open class` consumer persistence seam per writable entity (the Kotlin peer of Java's `SpringRepositoryGenerator`, but with method bodies). Carries the #203 `@autoSet` CRUD stamping: `onCreate` columns stamped once at insert, `onUpdate` columns re-stamped on every write, both excluded from the caller-supplied set. |
 | `KotlinPayloadGenerator` | `<Template>Payload.kt` — `@Serializable` payload data class from a template's `@payloadRef` |
-| `KotlinOutputParserGenerator` | the `template.output` strict parser-on-receipt (see the prompts reference) |
-| `KotlinExtractorGenerator` | the FR-010 tolerant `extract` mapper for a `template.output` (all-nullable mirror → strict payload) |
-| `KotlinOutputPromptGenerator` | the FR-010 output-format prompt fragment for a `template.output` (presentation via `@promptStyle: guide`/`inline`/`exampleOnly`) |
+| `KotlinOutputParserGenerator` | the strict parser-on-receipt for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: INBOUND; a `template.output` emits no parser). See the prompts reference. |
+| `KotlinExtractorGenerator` | the FR-010 tolerant `extract` mapper for a responding `template.prompt` (all-nullable mirror → strict payload) |
+| `KotlinOutputPromptGenerator` | the FR-010 output-format prompt fragment for a responding `template.prompt` (presentation via `@promptStyle: guide`/`inline`/`exampleOnly`) |
 | `KotlinRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
 | `KotlinValidatorGenerator` | `MetadataStartupValidator.kt` + `ExposedTableValidator.kt` (once per project) |
 | `KotlinSpringConfigGenerator` | `MetadataExposedConfig.kt` — `@Configuration` wiring `Database.connect()` + the startup validator (once per project) |