@metaobjectsdev/sdk 0.24.4 → 0.24.5

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

@@ -150,12 +150,13 @@ don't silently churn the existing code.
 
 ## Write your own generators — the built-ins rarely fit an app exactly
 
-The built-in generators (entity, queries, routes, form, grid, barrel) cover the
-common shape, but **real apps routinely need output the built-ins don't emit as-is**
-— a bespoke REST contract, custom DTO/response shapes, an app-specific service or
-repository layer, a UI the defaults don't produce. When that happens the model-first
-move is **not** to abandon metadata and hand-write the layer. Write a **custom
-generator** that reads the same metadata and emits *your* app's shape.
+The built-in generators (entity, queries, routes, routes-hono, barrel, form, hooks,
+grid, grid-hook) cover the common shape, but **real apps routinely need output the
+built-ins don't emit as-is** — a bespoke REST contract, custom DTO/response shapes,
+an app-specific service or repository layer, a UI the defaults don't produce. When
+that happens the model-first move is **not** to abandon metadata and hand-write the
+layer. Write a **custom generator** that reads the same metadata and emits *your*
+app's shape.
 
 Treat this as a first-class, expected activity — not an escape hatch. A custom
 generator is still model-first: it derives from the metadata spine, so it
@@ -163,6 +164,12 @@ regenerates on change and stays consistent across every entity — the leverage
 forfeit by hand-writing. Hand-rolling *away from* metadata is the anti-pattern;
 generating *your own shape from* metadata is the point.
 
+This is for when the *shape* itself needs to change. If a built-in's shape is
+already right and only the *target* is wrong — a different framework than the
+shipped reference emits for — take ownership of that generator instead of writing
+one from scratch; see "Your framework isn't the default" below, and your language
+reference for the command that does it.
+
 The plugin interface is small (`@metaobjectsdev/codegen-ts`): a `Generator` is
 `{ name, filter?, generate }`, where `generate(ctx)` returns `EmittedFile[]`
 (`{ path, content }`). `perEntity` / `oncePerRun` wrap the common cases:
@@ -190,6 +197,31 @@ the `generators` array in `metaobjects.config.ts` next to the built-ins — it r
 the same pass, writes under the same target rules, and carries the `@generated`
 header so it round-trips like any other.
 
+## Your framework isn't the default — the retargeting procedure
+
+If the shipped templates do not emit for your stack, retargeting is the **normal first
+move** — not a workaround and not a sign of a bug. Owning a generator is the supported
+path to any framework; MetaObjects does not ship a codegen package per framework and is
+not waiting to.
+
+The doctrine, in order of what to try:
+
+1. **Check config first.** Several apparent codegen failures are one config value
+   (module-specifier style, output directory, dialect, API prefix). Change it and retest
+   before writing any code.
+2. **Own the generator, not the renderer.** Take a copy of the reference template for the
+   artifact that is wrong and edit the one step your framework disagrees about. Each
+   template's header names what its emit is coupled to and which call to swap.
+3. **Compose, do not fork.** Call the exported render function and wrap its result where
+   you can, so you keep receiving upstream fixes. Forking a whole renderer is the thing
+   to avoid — not owning the generator.
+4. **Server-tier output is usually already portable.** The entity module and the query
+   helpers carry no HTTP-framework coupling; retargeting is usually only needed at the
+   routes and UI tiers.
+
+Hand-rolling *away from* metadata is the anti-pattern. Generating *your own shape from*
+metadata is the point.
+
 ### Never read metadata through an `own*()` accessor (ADR-0039) — top bug source
 
 When writing OR reviewing a generator, **read every field/node property and iterate
@@ -239,6 +271,18 @@ output/template · doesn't fit → write a generator that emits your shape *from
 metadata* · only the genuinely un-modelable (business algorithms, external calls) is
 hand-written outside codegen — and it still imports the generated types.
 
+**The commands and config keys that implement the steps above differ per port, and the
+ports differ in how much is written down.** TypeScript has the whole procedure as a
+documented one — `meta eject`, the `metaobjects.config.ts` keys, the exported `render*`
+functions — in this skill's `references/typescript.md`. **The other ports have no eject
+command.** There, owning a generator means implementing that port's generator interface
+— `com.metaobjects.generator.Generator` (Java / Kotlin),
+`metaobjects.codegen.generator.Generator` (Python), `MetaObjects.Codegen.IGenerator`
+(C#) — and registering it with the build tool that runs codegen for your port. Their
+`references/` fragments document what each built-in emits, which is what you compare
+your own emit against; they do not carry a step-by-step retargeting procedure, so do
+not go looking for one.
+
 ## Dialects
 
 Generated DB schema/DDL targets a SQL **dialect**:

package/agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -11,6 +11,7 @@ packages. Codegen runs through the Node `meta` CLI (`@metaobjectsdev/cli`, binar
 - Run
 - Multiple output targets
 - Field subtype → column mapping
+- Retargeting to another framework — the TypeScript procedure
 
 ## Install
 
@@ -43,6 +44,7 @@ import { tanstackQuery, tanstackGrid } from "@metaobjectsdev/codegen-ts-tanstack
 export default defineConfig({
   outDir: "src/generated",
   dialect: "postgres",                 // "postgres" | "sqlite" | "d1" (D1 is TS-only)
+  extStyle: "js",                      // "js" (default) for Node ESM / plain tsc; "none" for a bundler-resolution toolchain — see SKILL.md "Your framework isn't the default"
   apiPrefix: "/api",                   // flows to routes AND client fetch URLs
   columnNamingStrategy: "snake_case",  // "snake_case" (default) | "literal" | "kebab-case"
   timestampMode: "string",             // "string" (default, ISO-8601 wire contract) | "date" (Drizzle native Date)
@@ -231,3 +233,106 @@ The VO type, its Zod `InsertSchema`, and this `.$type<>()` all import the VO fro
 the same module (layout/package/`extStyle`-aware resolution). An opaque jsonb column
 (`field.string @dbColumnType: jsonb`) gets no `.$type<>()` — it stays `unknown`,
 which is the correct shape for freeform payloads with no fixed VO.
+
+## Retargeting to another framework — the TypeScript procedure
+
+This is the TypeScript implementation of the retargeting doctrine in SKILL.md
+("Your framework isn't the default"). Read that first for the order of moves;
+everything below — `meta eject`, `metaobjects.config.ts` keys, the exported
+`render*` functions — is Node-CLI-specific and exists only on this port.
+
+The shipped reference templates emit for **Fastify on Node** (plus a Hono variant) with
+Drizzle and Zod. If that is not your stack, retargeting is the **normal first move** — not
+a workaround and not a sign of a bug. Each template's header carries a `targets:` line
+naming exactly what its emit is coupled to and which call to swap.
+
+Work the list in order; the first two cost nothing.
+
+**1. Check the target-shaped config first.** Several apparent codegen failures are one
+config value in `metaobjects.config.ts`:
+
+- **`extStyle`** — `"js"` emits `./Entity.js` specifiers, correct for Node ESM and a plain
+  `tsc` with `nodenext`. Bundlers disagree on whether they perform the TypeScript
+  `.js`→`.ts` rewrite: it fails outright under **Turbopack** — including between two
+  generated files, which makes the whole generated tree unresolvable — while Vite and
+  esbuild are documented to accept it and webpack needs `resolve.extensionAlias` to do the
+  same. **If a generated import fails to resolve, set `extStyle: "none"` and retest** for
+  your toolchain rather than assuming either setting from this list.
+- **`clientDirective`** — `true` prepends `"use client";` to the generated form, hooks,
+  columns and grid-hook modules. Defaults to `false`. **Set it if your framework compiles
+  server and client from one tree** (React Server Components — Next.js App Router and
+  friends); leave it off otherwise, where the directive is inert and some bundlers warn
+  about it.
+- **`outDir`** / **`targets`** — where output lands, per generator.
+- **`apiPrefix`**, **`dialect`** — route mounting and column mapping.
+
+**2. Ask whether your framework splits the module graph.** Some frameworks compile server
+and client from one source tree and resolve each half under *different export conditions*
+(React Server Components, Angular universal, Qwik). Where they do:
+
+- a generated artifact using client-only APIs may need a **marker directive** or a distinct
+  import path, and
+- the resulting error frequently **names a package that is installed and present** — because
+  resolution failed under the server condition, not because the dependency is missing.
+
+Read that error as a *boundary* problem, not a dependency problem. The fix belongs in the
+generator that emits the artifact, which you own.
+
+**3. If the emit is wrong for your framework, own the generator.**
+
+    meta eject --list          # every template you can take ownership of
+    meta eject form            # copies it to codegen/generators/form.ts
+
+Then compose the engine and replace only the step that differs. Every generator's renderer
+is exported, so wrapping is available — but **how much that buys you differs by tier, and
+it is worth knowing which one you are in before you start**:
+
+- **Entity module (`entity`)** — genuinely composable. `renderDrizzleSchema`,
+  `renderZodValidators`, `renderInferredTypes`, `renderFilterAllowlist` and friends are
+  separate exported sections the template assembles into a `Code[]`. Swap or drop one and
+  keep the rest.
+- **Routes and UI (`routes`, `routes-hono`, `form`, `hooks`, `grid`, `grid-hook`)** — one
+  whole-file renderer each, so "replace a step" really means wrap the whole output. That
+  is enough for a marker directive, a header, or a post-process, and it is what the RSC
+  case below needs. It is **not** enough to retarget the emitted framework: if you need
+  Svelte or Angular instead of React, you are writing a renderer, and the honest move is
+  to keep the generator's metadata walk and replace the render call entirely.
+
+**`"use client"` needs no ejecting at all — it is a config knob.** The generated form,
+hooks, columns and grid-hook modules are client components; React Server Components
+frameworks (Next.js App Router and friends) require the directive saying so. Set it once:
+
+```ts
+export default defineConfig({
+  clientDirective: true,   // prepend `"use client";` to generated client artifacts
+  // ...
+});
+```
+
+Defaults to `false`, because the directive is only *required* under RSC and is inert
+(and warned about by some bundlers) everywhere else. It is applied ahead of the
+`@generated` header, exactly once, and only to the four client artifacts — the entity
+module, the query helpers and `<Entity>.meta.ts` are untouched, since `.meta.ts` is plain
+data and in RSC the boundary is the importing component, not everything it reaches.
+
+For the general wrap-the-output case — a directive or header MetaObjects does not model:
+
+```ts
+// codegen/generators/form.ts — OWNED
+import { renderFormFile } from "@metaobjectsdev/codegen-ts-react";
+
+// ...inside generate():
+if (!ctx.renderContext) throw new Error("renderContext is required (provided by runGen)");
+const body = renderFormFile(entity, ctx.renderContext);
+return { path, content: `// @my-framework:client\n` + body };
+```
+
+You keep receiving upstream fixes to `renderFormFile` while owning the one line your
+framework cares about. **Forking the whole renderer is the thing to avoid**, not owning the
+generator.
+
+**4. Server-tier output is usually already portable.** The entity module (a table plus
+validation schemas) and the query helpers (which take `db` as a parameter rather than
+importing a singleton) carry no HTTP-framework coupling — a server-rendered component can
+call a generated query directly. Retargeting is usually only needed at the routes and UI
+tiers.

package/agent-context/skills/metaobjects-prompts/references/typescript.md

@@ -22,7 +22,16 @@ provider/LLM-call layer — you compose the call yourself.
 ```ts
 // metaobjects.config.ts
 import { defineConfig } from "@metaobjectsdev/cli";
-import { entityFile, queriesFile, barrel, promptRender, outputParser } from "@metaobjectsdev/codegen-ts/generators";
+// The entity trio + barrel come from the OWNED copies `meta init` scaffolded into
+// ./codegen/generators/ (ADR-0034). Importing them from the package instead is the
+// deprecated path, and quietly hands their shape back to the package — so keep these
+// lines as `meta init` wrote them and add only the prompt pair below.
+import { entityFile } from "./codegen/generators/entity.js";
+import { queriesFile } from "./codegen/generators/queries.js";
+import { barrel } from "./codegen/generators/barrel.js";
+// promptRender / outputParser are NOT in the ownable set — the render and parse engines
+// are upstream-owned, so importing them from the package is the supported pattern.
+import { promptRender, outputParser } from "@metaobjectsdev/codegen-ts/generators";
 
 export default defineConfig({
   outDir: "src/generated",

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

@@ -20,9 +20,14 @@ 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
 

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,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;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

@@ -39,6 +39,61 @@ export function planScaffold(opts) {
         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 +104,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.`);

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.24.4",
+  "version": "0.24.5",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.24.4",
+    "@metaobjectsdev/metadata": "0.24.5",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/src/agent-context/scaffold.ts

@@ -79,6 +79,60 @@ export function planScaffold(opts: {
   };
 }
 
+/**
+ * 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: string | undefined): [number, number] | null {
+  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: string | undefined, currentVersion: string): boolean {
+  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
@@ -91,10 +145,11 @@ export function agentContextStaleness(opts: {
 }): string | null {
   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}. ` +