@metaobjectsdev/sdk 0.24.4 → 0.25.0

package/agent-context/skills/metaobjects-runtime-ui/SKILL.md

@@ -43,6 +43,28 @@ 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.
 
+## Physical names come from the generated names artifact, never a literal
+
+The runtime tier is where the code codegen leaves to you gets written — a repository
+implementation, a raw query, a migration script, a log line — and that is where a table
+or column name gets respelled. Don't. A physical name is declared **once**, in metadata
+(`@table` / `@view` / `@column` / `@schema`), and every port emits a per-object names
+artifact carrying it: `ProgramNames.fields.createdAt.column` on TypeScript,
+`ProgramNames.CreatedAtColumn` on C#, `ProgramNames.CREATED_AT_COLUMN` on the JVM,
+`PROGRAM_CREATED_AT_COLUMN` on Python. Reference it. `@column` is free-form —
+`callPurpose` may live in `purpose_code` — so deriving a column from the field name is a
+guess that fails silently, and a literal is a second spelling of a fact the metadata
+owns: rename the column in metadata and the constant follows, the literal does not, and
+nothing tells you.
+
+**Prefer a typed handle where one exists.** A Drizzle column object, an Exposed `Column`,
+an EF Core property is type-checked against the schema; swapping it for a string constant
+trades a compile error for a runtime one. The constants are for the places with no
+handle: raw SQL, a string-keyed query builder, and a hand-written repository on a port
+whose generated model carries no persistence binding at all (Java, Python). Your server
+reference names the handle and the artifact for this stack; on the JVM the names
+generator is opt-in, and the `metaobjects-codegen` skill says how to wire it.
+
 ## The REST contract
 
 Generated (or hand-written) routes speak one cross-port HTTP contract so the same

package/agent-context/skills/metaobjects-runtime-ui/references/csharp.md

@@ -88,3 +88,18 @@ handler calls the `FilterParser` / `EfCoreFilterDispatch` runtime helpers in
 `MetaObjects.Codegen`, so your ASP.NET host references that assembly at runtime. The same
 universal TS/Angular web client consumes those routes unchanged — the wire format matches
 the Java, Kotlin, and Python backends byte-for-byte.
+
+## Physical names below LINQ
+
+Inside LINQ keep the property (`db.Authors.Where(a => a.Name == …)`): it is type-checked
+against the model, and a string constant there trades a compile error for a runtime one.
+Where LINQ does not reach — raw SQL, a migration script, a log line — take the physical
+name from the generated `<Entity>Names.g.cs`. `names` is in the default suite, and the
+generated entity and `AppDbContext` already read it, so it cannot disagree with the
+mapping: `AuthorNames.SourcePrimaryTable` is the table (the member is named for the
+source's `@kind`, so a view reads `SourceReplicaView` / `SourcePrimaryView` and a stored
+procedure `SourcePrimaryProc`), `AuthorNames.<Field>Column` the column,
+`AuthorNames.ColumnsByField` the whole map. `AuthorNames.Name` is the OBJECT's name —
+`Author`, not `authors` — so it is the one member that compiles while meaning something
+else than it did before 0.25.0. Never a literal — and never
+`nameof(Author.Name)`, which is the CLR property, not the column.

package/agent-context/skills/metaobjects-runtime-ui/references/java.md

@@ -110,3 +110,36 @@ writable entity, on the cross-port REST contract (five CRUD endpoints, `?sort`,
 `<Entity>Repository.java` is a stubbed interface you implement against OMDB (or any
 persistence layer) — wire the controller to call it. The same universal TS/Angular
 web client consumes those controllers unchanged.
+
+## Physical names in your repository implementation
+
+OMDB resolves columns itself — `setString("name", …)` and `getObjects` key by field — and
+nothing `codegen-spring` emits carries a physical name (the DTO is a record of logical
+names; the repository is a bare interface). The physical names appear in exactly one
+place: the persistence code **you** write behind `<Entity>Repository` (JDBC, jOOQ, a
+Spring Data query). Take them from the generated `<Entity>Names` — never a literal:
+
+```java
+jdbc.query("SELECT " + AuthorNames.NAME_COLUMN + " FROM " + AuthorNames.SOURCE_PRIMARY_TABLE
+         + " WHERE " + AuthorNames.ID_COLUMN + " = ?", mapper, id);
+```
+
+The class mirrors the metadata tree. Every node carries its own `TYPE`/`SUB_TYPE`/`NAME`,
+so `AuthorNames.NAME` is the OBJECT's name (`"Author"`) and the physical name sits under
+the member that says what it IS: `SOURCE_<ROLE>_TABLE` / `_VIEW` / `_MATERIALIZED_VIEW` /
+`_PROC` / `_FUNCTION`. `<ROLE>` is `PRIMARY` or `REPLICA`, so a write-through entity's read
+view has a member of its own rather than sharing the write table's. Alongside them sit
+`SOURCE_<ROLE>_KIND` and, when declared, `SOURCE_<ROLE>_SCHEMA`; there is no `READ_ONLY` —
+it was derived from `@kind`, never declared, so ask `SOURCE_<ROLE>_KIND`. An
+`identity.secondary` or `index.lookup` carries `IDENTITY_<NAME>_INDEX` /
+`INDEX_<NAME>_INDEX`, the database index name; `identity.primary` deliberately has none,
+because migrate names a primary key by a dialect-conditional formula this artifact must not
+restate.
+
+`AuthorNames.COLUMNS_BY_FIELD` carries the whole map when you need to build a projection
+list. It is opt-in on the JVM — add `SpringNamesGenerator` to the pom's `<generators>`
+(see the codegen reference). Its `columnNaming` defaults to `literal`, the same
+resolution OMDB uses at runtime; pass the same value to both, or the constant names a
+column no row lands in. There is no typed handle to prefer on this port — `<Entity>Names`
+is the only compile-checked route to a physical name, which is also why nothing else here
+catches a wrong pairing for free.

package/agent-context/skills/metaobjects-runtime-ui/references/kotlin.md

@@ -35,6 +35,12 @@ object AuthorTable : Table("authors") {
 }
 ```
 
+With `KotlinNamesGenerator` in the same `<generators>` run the binding reads
+`Table(AuthorNames.SOURCE_PRIMARY_TABLE)` and `varchar(AuthorNames.NAME_COLUMN, 200)`
+instead of the literals above — the Maven plugin builds the whole generator list before executing any of
+it, so adding the names generator turns the substitution on (an explicit `<useNames>`
+still wins).
+
 ## Query + persist with Exposed
 
 Obtain a `Database` (the generated `MetadataExposedConfig` `@Configuration` calls
@@ -73,6 +79,23 @@ Filtered reads use Exposed's `selectAll()` plus a `where { ... }` op tree (e.g.
 `integration-tests-kotlin` query-conformance runner does against Testcontainers
 Postgres.
 
+## Physical names outside the DSL
+
+Inside Exposed, bind to the `Column` object — `AuthorTable.name`, type-checked column by
+column — never `AuthorNames.NAME_COLUMN`. The constant is for what the DSL does not
+reach: `exec("…")` raw SQL, a Flyway script, a log line, an external system's column
+mapping. There it is `AuthorNames.SOURCE_PRIMARY_TABLE` / `AuthorNames.NAME_COLUMN`
+(opt-in: `KotlinNamesGenerator` in the pom — see the codegen reference), never a literal.
+Give both generators the same `columnNaming`, or the table and the constants disagree about
+a column.
+
+The object mirrors the metadata tree: `AuthorNames.NAME` is the OBJECT's name
+(`"Author"`), and a physical name sits under the member that says what it IS —
+`SOURCE_<ROLE>_TABLE` / `_VIEW` / `_PROC` and so on, `<ROLE>` being `PRIMARY` or `REPLICA`,
+so a write-through entity's replica view has a member of its own. Index names are
+`IDENTITY_<NAME>_INDEX` / `INDEX_<NAME>_INDEX`, which is what the generated
+`init { uniqueIndex(…) }` block references.
+
 ## Return-type contract
 
 An Exposed read yields **native in-process Kotlin/JVM types** at the column, never

package/agent-context/skills/metaobjects-runtime-ui/references/python.md

@@ -92,3 +92,28 @@ Protocol, not `int`. The PATCH body is typed `dict[str, Any]` **deliberately**:
 `<Entity>Create` / `<Entity>Patch` Pydantic models already validate constraints over HTTP
 (FR-036), and the `dict` seam preserves the FR-035 present-key PATCH tristate (absent ≠
 explicit-null) — retyping the PATCH parameter to the model would collapse that tristate.
+
+## Physical names in your repository implementation
+
+`ObjectManager` calls key by field name (`om.find_many("Author", {"name": …})`) and
+resolve the column themselves, so that path never needs a physical name. The moment the
+repository `Protocol` is backed by your own SQLAlchemy Core / asyncpg / psycopg code, it
+does — and nothing Python generates carries one: the Pydantic models, create/patch
+shapes, router and allowlist all key by field. Take it from the generated
+`<entity_snake>_names.py` (`names` is in the default suite):
+
+```python
+from generated.author_names import (
+    AUTHOR_SOURCE_PRIMARY_TABLE, AUTHOR_CREATED_AT_COLUMN, AUTHOR_ID_COLUMN,
+)
+
+row = await conn.fetchrow(
+    f"SELECT {AUTHOR_CREATED_AT_COLUMN} FROM {AUTHOR_SOURCE_PRIMARY_TABLE} "
+    f"WHERE {AUTHOR_ID_COLUMN} = $1",
+    author_id,
+)
+```
+
+There is no typed handle to prefer on this port, so this is never the wrong choice here.
+Pass the same `--column-naming` to `metaobjects gen` that you pass as `column_naming=` to
+`ObjectManager` (both default to `literal`), or the constant names a column no row lands in.

package/agent-context/skills/metaobjects-runtime-ui/references/tanstack.md

@@ -20,15 +20,20 @@ this package.
 ```bash
 npm install @metaobjectsdev/tanstack @metaobjectsdev/runtime-web
 npm install --save-dev @metaobjectsdev/codegen-ts-tanstack
+npm i @tanstack/react-table@^8.21.3
 ```
 
-Peer-deps: `@tanstack/react-query`, `@tanstack/react-table`.
+Peer-deps: `@tanstack/react-query`, `@tanstack/react-table`. **Pin the react-table
+major explicitly** — the registry's `latest` is v9, which removed `useReactTable`
+and `getCoreRowModel` (both used by `<EntityGrid>`), so a bare
+`npm i @tanstack/react-table` installs a version this package's `^8.20.0` peer range
+rejects and poisons every later install in the project with `ERESOLVE`.
 
 ## Key exports
 
 | Export | Purpose |
 |---|---|
-| `<EntityFetcherProvider value={fetcher}>` | supplies the single `EntityFetcher` every generated hook reads |
+| `<EntityFetcherProvider fetcher={fetcher} baseUrl="/api">` | supplies the single `EntityFetcher` every generated hook reads, plus the base URL it prepends. `baseUrl` is optional (default `""` = same origin at the root); generated hooks emit entity-relative paths. |
 | `useEntityFetcher()` | reads the fetcher from context (generated hooks call this) |
 | `<EntityGrid>` | opinionated TanStack Table component |
 | `<CellRendererProvider>` + `defaultCellRenderers` | renderer overrides keyed by the column's `meta.view` |
@@ -58,7 +63,7 @@ const fetcher = async <T,>(path: string, init?: RequestInit): Promise<T> => {
 
 export function App() {
   return (
-    <EntityFetcherProvider value={fetcher}>
+    <EntityFetcherProvider fetcher={fetcher} baseUrl="/api">
       <AuthorList />
     </EntityFetcherProvider>
   );
@@ -150,10 +155,15 @@ don't have to.
 
 ## Cell renderer overrides
 
-`<EntityGrid>` routes rendering through `CellRendererProvider`, keyed by `meta.view`
-(`text` / `number` / `date` / `boolean` / `currency` / `dropdown` / …). Override a
-key without touching generated code; per-column `cell` always wins, the provider
-fills in otherwise.
+`<EntityGrid>` routes rendering through `CellRendererProvider`, keyed by `meta.view` —
+which is the field's **registered `view.*` subtype** (`text` / `textarea` / `number` /
+`date` / `month` / `checkbox` / `hotlink` / `currency` / `dropdown` / `radio` /
+`password`), so a key that is not a registered subtype can never be selected. Override a
+key without touching generated code; per-column `cell` always wins, the provider fills in
+otherwise.
+
+A `field.timestamp` declares `view.date` and renders date-only by default. To show the
+time as well, override the `date` key — there is no `view.datetime` subtype.
 
 ```tsx
 import { CellRendererProvider } from "@metaobjectsdev/tanstack";
@@ -163,3 +173,20 @@ import { formatCurrency } from "@metaobjectsdev/runtime-web";
   <EntityGrid {...gridProps} />
 </CellRendererProvider>
 ```
+
+`view.image` has no default renderer and needs one wired: the field stores an opaque
+storage key, so the cell needs the app's `ImageUploadAdapter` to resolve a `src`. Close
+`imageCell` over your adapter — it is exported from this same package, so this costs no
+extra dependency.
+
+```tsx
+import { CellRendererProvider, imageCell } from "@metaobjectsdev/tanstack";
+
+<CellRendererProvider value={{ image: imageCell(adapter, { size: 48 }) }}>
+  <EntityGrid {...gridProps} />
+</CellRendererProvider>
+```
+
+`view.base`, `view.web` and `view.hidden` have no renderer either, and want none —
+the first two are abstract roots nothing emits, and a `view.hidden` field is dropped
+from the column set entirely (a blank cell would still carry a header and a sort target).

package/agent-context/skills/metaobjects-runtime-ui/references/typescript.md

@@ -67,6 +67,26 @@ await om.transaction(async (tx) => { /* ... */ });
 > `node-postgres`, `@neondatabase/serverless`; NOT on `better-sqlite3` / `bun:sqlite`
 > (no native RETURNING) — use a custom driver or `inMemoryDriver` there.
 
+### Physical names: the column object first, `<Entity>Names` where there is none
+
+The generated query helpers and `ObjectManager` never make you spell a table or column.
+Where you drop below them, bind to the Drizzle column object (`programs.createdAt` —
+checked against the schema at compile time), never a string. What Drizzle does not
+reach — a `sql` template fragment, a string-keyed Kysely identifier, a migration script,
+a log line — takes the generated `<Entity>.names.ts` (`namesFile()` is in the `meta init`
+scaffold):
+
+```ts
+import { sql } from "drizzle-orm";
+import { ProgramNames } from "./generated/Program.names.js";
+
+sql`SELECT ${sql.identifier(ProgramNames.fields.createdAt.column)}
+    FROM ${sql.identifier(ProgramNames.sources.primary.table)}`
+```
+
+A literal is a second spelling of a fact the metadata owns: `@column` is free-form, and a
+rename in metadata moves the constant, not the string.
+
 ## Return-type contract
 
 The runtime returns **native in-process types**, never wire strings — temporal

package/agent-context/skills/metaobjects-verify/SKILL.md

@@ -82,6 +82,16 @@ it and call the generated query/field instead of keeping the hand-rolled version
 This is the most common way a build ends up *declaring* a projection yet still
 hand-aggregating in a route — verify catches exactly that.
 
+**Read the whole report, not the first twenty lines.** Text output caps each
+advisory section at 20 lines and then says how many it held back; raise it with
+`--limit <n>` or remove it with `--limit all`. You are on a pipe, so your default
+format is already TOON: `meta verify` puts one machine-readable document on stdout
+carrying every gate's verdict, every anti-pattern finding and every requirement
+diagnostic — **uncapped** — with narration on stderr. `--format json` if you want
+JSON. A pass that did not run reports `status: "skipped"` and why, so an empty list
+always means "found nothing", never "never looked"; what the payload does not carry
+is named in its own `notRepresented[]`.
+
 **A bare `verify` is a partial check, not the full gate.** The Node/C# default runs
 only `--templates`; Java/Python's bare default runs only `--codegen` — either way,
 paired with the advisory anti-pattern pass above, never all three subverbs. Treat a
@@ -163,6 +173,24 @@ Make it a **ratchet**: it can't go green until the last offending field is migra
 backstop against reintroducing the smell. The same pattern generalizes to any semantic
 metadata rule your project wants enforced that `verify` structurally can't express.
 
+The other invariant worth a ratchet is **no physical name as a literal**. A table or
+column string in hand-written code is a second spelling of a declared fact, and nothing
+in `verify` compares your code to the schema — `--codegen` diffs generated files against
+a fresh regen, `--db` diffs the database against the metadata. Neither reads the
+repository you wrote. Build the alternation from the metadata's own `@table` / `@view` /
+`@column` values and fail on any hit outside generated output:
+
+```
+# fail the build if a declared physical name is spelled in hand-written source.
+# Illustrative — generate the alternation from your metadata, scope it to the
+# directories you hand-write. A typed ORM handle never matches this; a literal does.
+! grep -rEn '"(orders|created_at|purpose_code)"' src/ --exclude-dir=generated
+```
+
+Generated output is already covered upstream — every port's generators reference the
+names artifact instead of embedding the literal — so this ratchet is only ever about your
+code. The remedy for a hit is the `<Entity>Names` constant (`metaobjects-runtime-ui`).
+
 ## Schema migrations are the shared TypeScript engine — for every port
 
 This is the load-bearing architectural fact (ADR-0015): **schema migrations are

package/agent-context/templates/always-on.md.mustache

@@ -8,16 +8,57 @@
 MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable
 spine; generated code is the disposable artifact. Regenerate with `{{codegenCommand}}`.
 
+## Read the generated reference before you touch a tier
+{{#nodeDocsSurface}}
+`meta docs` writes four reference files under this project's docs output directory
+(`./docs` unless `docs.outDir` in `metaobjects.config.ts` says otherwise). They are
+generated from THIS project's metadata, so they describe what it actually is rather than
+what the framework does in general — and reading the relevant one first is how you avoid
+inferring the answer from generated code, which is the disposable half.
+
+- **`agent/schema.md`** — before touching persistence. Tables, columns, the field each
+  column came from, keys, foreign keys, constraints.
+- **`api/AGENT-API.md`** — before calling generated code. The types, endpoints and filter
+  operators the generators actually emitted.
+- **`agent/ui.md`** — before touching a form or a grid. The control, label, rules and
+  filterability per field, and each declared grid.
+- **`agent/requirements.md`** — before adding a capability. What is already claimed, and
+  what was deliberately **retired** — an entry saying a capability must not be rebuilt is
+  the one thing you cannot learn from the code, because the code is gone.
+
+Not there? Run `meta docs`. It reads the metadata and the config and needs nothing else.
+{{/nodeDocsSurface}}
+{{^nodeDocsSurface}}
+`{{docsCommand}}` writes ONE reference file under this project's docs output directory. It
+is generated from THIS project's metadata, so it describes what the project actually is
+rather than what the framework does in general — and reading it first is how you avoid
+inferring the answer from generated code, which is the disposable half.
+
+- **`{{apiSubDir}}/AGENT-API.md`** — before calling generated code. The types, endpoints and
+  filter operators the generators actually emitted.
+
+Not there? Run `{{docsCommand}}`.
+
+The other three pages of that reference — `agent/schema.md` (persistence), `agent/ui.md`
+(forms and grids) and `agent/requirements.md` (what is already claimed, and what was
+deliberately **retired**) — are written by the Node `meta docs` command and need a
+`metaobjects.config.ts`, which this stack does not have. Until it does, read the metadata
+itself for those three: it is the source those pages are generated from.
+{{/nodeDocsSurface}}
+
 ## Principles
 - **Adopting onto existing code? Metadata FOLLOWS the code.** On a migration (existing working code / live DB), author metadata + tune codegen to *reproduce* what the code already is — native types (`field.uuid` when the code uses `UUID`, not `field.string`), names, nullability — so regen changes as little existing code as possible. The only existing code that should change is the hand-written layer codegen replaces; ask when a modeling choice is ambiguous. (Greenfield: model-first, below.)
-- Pattern-derivable from metadata = codegen, never hand-write — FKs, CRUD, validators, finders, and the database schema and migrations. The schema is a disposable, generated artifact: change the metadata and regenerate. Don't hand-write divergent SQL; where a stack owns its own migration files (Flyway/Liquibase), they must **match** the generated schema, not invent it.
-- The **live database** is a derived artifact too — never hand-apply a schema change to a running DB (ad-hoc `psql`/console `ALTER`/`CREATE`/`DROP`), not even to preview a column or unblock a boot. Drive every schema change from the metadata, never ad-hoc: on the Node/TS-owned migrate stack that is `meta migrate` (metadata → DDL, ADR-0015); on a JVM stack whose migration tool `meta migrate` does not emit for (e.g. **Flyway**/Liquibase) author the migration to match the generated schema (the source of truth). A hand-applied ad-hoc change drifts the live DB from the metadata + migration history and collides at the next migrate/boot ("column already exists") — a state no migration can reproduce. Run `meta verify --db <url>` after any DB-touching work to catch that drift early — the URL is required, and the bare form exits 2.
-- Never hand-edit generated files — change the metadata and regenerate (three-way merge preserves hand-written regions).
-- Use the generated constants for any string that names metadata.
+- Pattern-derivable from metadata = codegen, never hand-write — FKs, CRUD, validators, finders, and the database schema and migrations. The schema is a disposable, generated artifact: change the metadata and regenerate. Don't hand-write divergent SQL; where a stack owns its own migration files, GENERATE them — `meta migrate --migration-format flyway` emits the paired `V<n>__`/`U<n>__` files a Flyway runner expects, and leaves applying them to Flyway.
+- The **live database** is a derived artifact too — never hand-apply a schema change to a running DB (ad-hoc `psql`/console `ALTER`/`CREATE`/`DROP`), not even to preview a column or unblock a boot. Drive every schema change from the metadata, never ad-hoc: on the Node/TS-owned migrate stack that is `meta migrate` (metadata → DDL, ADR-0015); on a **Flyway**-owned JVM stack that is `meta migrate --migration-format flyway`, which emits the migration and deliberately refuses `--apply` because Flyway owns applying it. Hand-authoring a migration to match the generated schema is the LAST resort — for a runner MetaObjects has no writer for — never the default for Flyway. A hand-applied ad-hoc change drifts the live DB from the metadata + migration history and collides at the next migrate/boot ("column already exists") — a state no migration can reproduce. Run `meta verify --db <url>` after any DB-touching work to catch that drift early — the URL is required, and the bare form exits 2.
+- Never hand-edit generated **output** — change the metadata and regenerate. (That bounds the files codegen *emits*; it says nothing about the generator that emits them — next bullet.) What survives a regen DIFFERS BY TOOLCHAIN, so never rely on it: the Node/TS `meta gen` path three-way-merges, so an edit inside a generated file is preserved (and is refused rather than guessed at when it cannot tell yours from its own stale output); the JVM generators overwrite, and several Kotlin ones — including `<Entity>.kt` — truncate unconditionally with no marker check. Put your own code in a subclass or a separate file, never in the generated one.
+- **The generators are yours — editing one is ordinary work, not an escalation.** Your generator list, and any generator source scaffolded into your repo (`codegen/generators/` on the Node/TS path), are your code: no `@generated` header, no upstream ownership, nothing to ask permission for. **A standing rule not to change the MetaObjects repo is not a rule about your generators** — that is a different repository, and generalising the first into the second is how an agent ends up hand-writing the exact layer it was told to generate. When generated output does not fit, in order: change the **metadata** if the model is wrong; else change **your own generator**; only then hand-write. Hand-writing what the metadata already describes is the last resort, not the first. Per-port specifics — including which ports have an eject command and which mean implementing a generator interface — are in the `metaobjects-codegen` skill.
+- Use the generated constants for any string that names metadata — a type, subtype or attribute name, and a **physical table or column name**: those are declared once (`@table` / `@column`) and emitted as the per-object `<Entity>Names` artifact, so never respell one as a literal outside its declaration. Prefer a typed ORM handle where one exists; the constant is for raw SQL, migrations and logs.
+- **Ownership has a converse — wire a generator only for output you will actually consume.** Generated code nothing imports is indistinguishable from generated code that does not COMPILE — one adopter carried 87 uncallable query helpers through two audits because a dead-file census read them as over-generation. Worse, an unused generated file still reads as an invitation: a routes file nobody mounted still says "register this as-is for stock CRUD", so the next reader adopts the thing you decided not to. If an entity needs no REST surface, grid or form, don't wire that generator at all, or narrow it with the generator's own `filter` — don't emit the file and leave it unimported.
 - The loaded metadata model is READ-ONLY — never inject nodes or mutate the tree at load time (no "enrich the model on load" hooks). Need an extra field/column? Author it in the metadata, or derive it during codegen (read the metadata, emit output). Mutating the loaded model makes it diverge from what's declared — a bad practice reserved for very rare cases.
 - **JVM:** serialize a MetaObject-backed instance (a `pojoAware`-flavor generated class, a runtime `ValueObject`, or any `MetaObjectAware` type) through the MetaObjects JSON layer — never hand-configure a Jackson/Gson mapper around the framework fields to make a default mapper cope.
 
 ## Authoring rules you must not violate
+- **Search the vocabulary before concluding it cannot be expressed — `meta types <term>`.** An unregistered TYPE or SUBTYPE fails the load in every command. An undeclared `@attr` is different: it fails `meta verify`, which loads strict, and NOT `meta gen`, which does not — so an invented attribute passes codegen silently and is caught by the drift gate rather than by the build. Either way inventing vocabulary is a failure you will hit, not a shortcut. Search names with `meta types <term>`, names and descriptions with `--all` ("find it by what it does"), and one construct's valid `@attrs` with `meta types <type>.<subType> --detail`; `--format json` returns the same answer as one machine-readable document, each attr with its `allowedValues`. Rows marked `[ts-only]` are TypeScript-only vocabulary the cross-port contract does not carry. It is the Node `meta` CLI and, like `meta migrate`, works whatever your backend — it reads the registry, so it needs no project. Ask for NEW vocabulary only once that search comes up empty.
 - Nodes are fused-key maps: `{"<type>.<subType>": { ... }}` (e.g. `{"field.string": {"name": "email"}}`) — never split the type and subtype into separate keys.
 - Attribute names are unique within a node; for multi-value use one array attr (`@values: [...]`).
 - An inline `@maxLength: 50` equals an `attr` child of the same name — never write both.

package/dist/agent-context/assemble.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"AAEA,OAAO,EACyD,KAAK,aAAa,EAAE,KAAK,KAAK,EAC7F,MAAM,YAAY,CAAC;AAuCpB,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG,aAAa,EAAE,CA0CrF"}
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"AAEA,OAAO,EACyD,KAAK,aAAa,EAAE,KAAK,KAAK,EAC7F,MAAM,YAAY,CAAC;AAmHpB,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG,aAAa,EAAE,CA8CrF"}

package/dist/agent-context/assemble.js

@@ -25,10 +25,58 @@ function stackLine(contentRoot, stack) {
         // fragment carries the project-agnostic how. See issue #1.
         line: `Stack: ${serverPart}, ${clientPart}.`,
         codegenCommand: meta ? meta.codegenCommand : "meta gen",
+        docsCommand: meta ? meta.docsCommand : "meta docs",
+        apiSubDir: meta ? meta.apiSubDir : "api",
     };
 }
-function applyTemplate(tpl, vars) {
-    return tpl.replace(/\{\{(\w+)\}\}/g, (_m, k) => {
+/**
+ * True when this stack runs the Node `meta` toolchain over a `metaobjects.config.ts`.
+ *
+ * This is the condition for the `agent/` docs surface EXISTING AT ALL: `meta docs` gates
+ * those three pages on a loadable gen config, because the physical names, the dialect and
+ * the view dispatch all come from it. A TypeScript server has one; so does any stack
+ * declaring a web CLIENT, because the React/TanStack tiers are generated by `meta gen`
+ * whatever the backend is. A port-only stack (java alone, python alone) has none, and for
+ * it the pointer must name only the one file its own docs command writes.
+ *
+ * The pointer landed verbatim in every stack before this existed, so a Python project was
+ * told to read four files that cannot exist and to run a command that cannot make them —
+ * on the one page an agent is told to trust.
+ */
+function hasNodeDocsSurface(stack) {
+    return stack.servers.includes("typescript") || stack.clients.length > 0;
+}
+/**
+ * Substitute `{{var}}` and the two section forms `{{#name}}…{{/name}}` (render when the
+ * flag is true) and `{{^name}}…{{/name}}` (render when it is false).
+ *
+ * Sections do NOT nest — one pass, non-greedy to the matching close tag — which is all the
+ * always-on template needs. An unknown variable or section name THROWS, and so does any
+ * section tag left standing after the pass (mistyped close tag, unclosed section, nesting):
+ * a silently empty substitution, or a literal `{{#…}}` shipped into a file an agent is told
+ * to trust, is the failure this whole surface exists to prevent.
+ */
+function applyTemplate(tpl, vars, sections) {
+    const resolved = tpl.replace(/\{\{([#^])(\w+)\}\}\n?([\s\S]*?)\{\{\/\2\}\}\n?/g, (_m, sigil, name, body) => {
+        if (!(name in sections)) {
+            throw new Error(`agent-context: unknown template section {{${sigil}${name}}}`);
+        }
+        // `#` shows its body when the flag is true, `^` when it is false.
+        const shownWhen = sigil === "#";
+        return sections[name] === shownWhen ? body : "";
+    });
+    // A section tag that SURVIVED the pass above is malformed — a mistyped close tag, an
+    // unclosed section, or a nested one (the single non-greedy pass matches the first close
+    // tag, leaving the inner pair behind). Every one of those would otherwise ship a literal
+    // `{{#…}}` into a file an agent is told to trust, which is the failure this mechanism
+    // exists to prevent, so the leftover is an ERROR rather than passed through. The
+    // variable pass below cannot catch it: `{{#a}}` is not a `\w+` match.
+    const leftover = resolved.match(/\{\{[#^/]\w*\}\}/);
+    if (leftover !== null) {
+        throw new Error(`agent-context: unresolved template section tag ${leftover[0]} — a section must be a ` +
+            "well-formed {{#name}}…{{/name}} or {{^name}}…{{/name}} pair, and sections do not nest");
+    }
+    return resolved.replace(/\{\{(\w+)\}\}/g, (_m, k) => {
         if (!(k in vars))
             throw new Error(`agent-context: unknown template variable {{${k}}}`);
         return vars[k];
@@ -40,8 +88,8 @@ export function assemble(opts) {
     const out = [];
     // 1. Always-on (AGENTS.md + CLAUDE.md, identical contents).
     const tpl = readFileSync(join(contentRoot, "templates", "always-on.md.mustache"), "utf8");
-    const { line, codegenCommand } = stackLine(contentRoot, stack);
-    const alwaysOn = applyTemplate(tpl, { stackLine: line, codegenCommand });
+    const { line, codegenCommand, docsCommand, apiSubDir } = stackLine(contentRoot, stack);
+    const alwaysOn = applyTemplate(tpl, { stackLine: line, codegenCommand, docsCommand, apiSubDir }, { nodeDocsSurface: hasNodeDocsSurface(stack) });
     out.push({ path: ".metaobjects/AGENTS.md", contents: alwaysOn });
     out.push({ path: ".metaobjects/CLAUDE.md", contents: alwaysOn });
     // 2. Skills: body + only the references whose token is in the stack.

package/dist/agent-context/assemble.js.map

@@ -1 +1 @@
-{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"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"}

package/dist/agent-context/scaffold.d.ts

@@ -30,7 +30,22 @@ export interface ScaffoldDecision {
     }[];
     /** the manifest to persist after writing. */
     manifest: Manifest;
-    /** paths the prior manifest tracked that are no longer assembled (e.g. stack shrank) — reported, never auto-deleted. */
+    /**
+     * Orphans safe to DELETE: the prior manifest tracked them, this stack no longer
+     * assembles them, and the on-disk content still hashes to what we recorded writing.
+     *
+     * Same predicate that separates `writes` from `conflicts` — we only ever remove a file
+     * we wrote and nobody has touched, so deleting is exactly as safe as the overwrite that
+     * predicate already authorises for a file still in the stack.
+     */
+    prunes: string[];
+    /**
+     * Orphans that are HAND-EDITED — reported, never auto-deleted. Losing an adopter's
+     * writing is worse than leaving a stale file behind.
+     *
+     * An orphan already absent from disk appears in neither list: there is nothing to delete
+     * and nothing to report. It simply leaves the manifest.
+     */
     removed: string[];
 }
 /**

package/dist/agent-context/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/agent-context/scaffold.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEvD,mFAAmF;AACnF,eAAO,MAAM,2BAA2B,qCAAqC,CAAC;AAE9E,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,CAAC,CAAC;IACX;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,uFAAuF;IACvF,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjE,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IACnB,wHAAwH;IACxH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAClD,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,gBAAgB,CA8BnB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,GAAG,IAAI,CAYhB"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/agent-context/scaffold.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEvD,mFAAmF;AACnF,eAAO,MAAM,2BAA2B,qCAAqC,CAAC;AAE9E,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,CAAC,CAAC;IACX;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,uFAAuF;IACvF,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjE,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAClD,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,gBAAgB,CA8CnB;AAwDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,GAAG,IAAI,CAahB"}

package/dist/agent-context/scaffold.js

@@ -30,15 +30,90 @@ export function planScaffold(opts) {
             conflicts.push({ path: f.path, newPath: `${f.path}.new`, contents: f.contents });
         }
     }
+    // An orphan is a path the prior manifest tracked that this stack no longer assembles —
+    // typically a language fragment left by `--refresh-docs --server <other>`. It used to be
+    // reported and never deleted whatever its state, so a python.md sat in a TypeScript
+    // project forever while every SKILL.md footer told the reader to read every
+    // references/*.md "one per server language in this project's stack".
     const assembledPaths = new Set(assembled.map((f) => f.path));
-    const removed = prior ? Object.keys(prior.files).filter((p) => !assembledPaths.has(p)) : [];
+    const prunes = [];
+    const removed = [];
+    for (const path of prior ? Object.keys(prior.files) : []) {
+        if (assembledPaths.has(path))
+            continue;
+        const current = readCurrent(path);
+        if (current === undefined)
+            continue; // already gone — nothing to do
+        if (hashContents(current) === prior?.files[path])
+            prunes.push(path);
+        else
+            removed.push(path);
+    }
     return {
         writes,
         conflicts,
+        // `files` holds only what this run assembled, so a pruned orphan does not survive into
+        // the new manifest — otherwise it would be re-reported as an orphan on every run.
         manifest: { version: 1, generatedBy, servers: stack.servers, clients: stack.clients, files },
+        prunes,
         removed,
     };
 }
+/**
+ * The ordered release coordinate of a version — `[minor, patch]` — or `null` when the
+ * version cannot be ordered as a plain release.
+ *
+ * The MAJOR is deliberately dropped. It is a per-registry constant, not information:
+ * npm/PyPI/NuGet ship `0.<m>.<p>` and Maven Central the same `<m>.<p>` on its historical
+ * major `7`, so the minor.patch IS the shared release coordinate across all four (this is
+ * the same reduction the JVM's `releaseCoordinate` has always made for equality).
+ *
+ * Returns `null` — meaning "not orderable, so nudge" — for anything that is not exactly
+ * three dot-separated integers. That deliberately covers prereleases (`0.24.5-rc.1`),
+ * build metadata (`0.24.5+abc`), and the `0.0.0` sentinel a port emits when it cannot
+ * resolve its own installed version. Each must keep nudging: an RC-scaffolded context
+ * against a final release is still worth refreshing, and an unknown install must never
+ * be allowed to assert "in sync".
+ */
+function releaseSeries(version) {
+    if (version === undefined)
+        return null;
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+    if (m === null)
+        return null;
+    if (version.trim() === UNRESOLVED_VERSION)
+        return null; // never assert in-sync on unknown
+    return [Number(m[2]), Number(m[3])];
+}
+/** The sentinel a port stamps when it cannot resolve its own installed version. */
+const UNRESOLVED_VERSION = "0.0.0";
+/**
+ * True when the manifest was stamped by a release STRICTLY NEWER than the installed one.
+ *
+ * This is the one exemption from "any drift nudges", and it exists because of the
+ * publish-what-changed rule (docs/RELEASING.md): a registry publishes only when it has a
+ * changed product file, so a port legitimately sits behind npm — while `meta agent-docs`,
+ * the canonical scaffolder for EVERY port, stamps the npm version it was run from. A
+ * Python install at `0.24.4` whose context was scaffolded by npm `0.24.7` is correct, and
+ * nudging it is [#347](https://github.com/metaobjectsdev/metaobjects/issues/347) exactly:
+ * the remedy re-runs the scaffolder, which re-stamps `0.24.7`, so the advisory can never
+ * be satisfied and fires on every build forever. An advisory that cries wolf in the inner
+ * loop gets tuned out, and then it is not there for the upgrade it exists for.
+ *
+ * KNOWN BOUND, stated rather than hidden: ordering on minor.patch assumes both versions
+ * sit in the same release SERIES. That holds for every release to date and for every
+ * release after the 1.0/8.0 cut, but not ACROSS it — at that one cut a `0.24.x`-stamped
+ * context against a `1.0.0` install compares (24,x) > (0,0) and is read as "ahead", so the
+ * nudge is suppressed once when it should fire. The cost is a missed advisory, never a
+ * wrong action, and re-scaffolding at 1.0 is part of the cut anyway.
+ */
+function contextIsAheadOfInstall(generatedBy, currentVersion) {
+    const stamped = releaseSeries(generatedBy);
+    const installed = releaseSeries(currentVersion);
+    if (stamped === null || installed === null)
+        return false; // not orderable → nudge
+    return stamped[0] > installed[0] || (stamped[0] === installed[0] && stamped[1] > installed[1]);
+}
 /**
  * A one-line nudge if the scaffolded agent context predates the installed MetaObjects
  * (so `gen`/`verify` can remind the user to refresh the skills after an upgrade), or
@@ -49,11 +124,13 @@ export function agentContextStaleness(opts) {
     const { manifest, currentVersion } = opts;
     if (manifest === undefined)
         return null; // no agent context here → nothing to nudge
-    // Exact-equality on purpose: ANY drift nudges (a re-scaffold is cheap + idempotent).
-    // Don't "fix" this into a semver compare — a prerelease/build-metadata difference is
-    // still a reason to refresh, and the nudge is advisory, never a gate.
+    // Exact-equality FIRST: ANY drift nudges (a re-scaffold is cheap + idempotent). A
+    // prerelease/build-metadata difference is still a reason to refresh, so this is not a
+    // semver compare — see releaseSeries() for the ONE case that is exempt.
     if (manifest.generatedBy === currentVersion)
         return null; // in sync
+    if (contextIsAheadOfInstall(manifest.generatedBy, currentVersion))
+        return null;
     const from = manifest.generatedBy ?? "an older MetaObjects";
     return (`MetaObjects agent context was generated by ${from}; you're on ${currentVersion}. ` +
         `Re-run 'meta init --docs-only --refresh-docs' to refresh the .claude/skills docs.`);