@metaobjectsdev/sdk 0.24.0 → 0.24.2

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

@@ -71,10 +71,33 @@ code behind a grep hit; a "duplicate" validator's *divergence* is the finding.
   design, and a real estate reports most of itself unclaimed on day one). Score the prose
   it would replace, and prefer ONE concrete claim an author can check over a
   whole-estate migration.
+  **First establish the estate LOADS.** An older ledger fails the load outright, so
+  `meta verify` never runs and everything in `references/requirements.md` is unavailable:
+  `@violation` and `@verifiedBy` were retired in **0.24.0** (no deprecation shim — ADR-0023
+  seals the registry); an index key declaring both `@fields` and `@expr` is refused since
+  **0.24.1**; and **0.24.2** turned `@status: abandoned | superseded` into **`retired`**. Run
+  **`meta upgrade`** (previews by default; `--apply` writes) before auditing, and audit the
+  upgraded tree. It rewrites only what has one correct answer and **refuses the rest, exiting
+  non-zero** — a refusal is itself a finding, naming the entries whose disposition nobody
+  recorded.
+  **Then audit the `retired` entries specifically.** They are where the ledger earns its
+  keep — agents proposing a retired capability's rebuild is the one failure this mechanism
+  has controlled evidence against — and they are also where it decays quietly. Check that
+  each `@statement` reads as a PROHIBITION rather than a diary entry ("X is never done",
+  not "we used to do X"), and that `@counterexample` describes the REVIVAL. A retired entry
+  whose statement narrates history is invisible to the reader it exists to stop.
 - [ ] **F. Drift-gate adoption.** Is `meta verify` wired into CI / pre-commit? Which
   subverbs (`--codegen` / `--templates` / `--db`)? Committed-codegen freshness gate?
   Advisories heeded? Routine `--no-verify` bypass? Loader `ERR_*` / warnings addressed?
   Parse the stable `code` field, not message text (ADR-0009).
+  **Is any advisory half switched OFF?** A gate can be wired, green, and muted. The
+  requirements authoring lint is advisory and mutable — `--no-requirement-lint` or
+  `META_NO_REQUIREMENT_LINT=1` silences it while the gate above it still runs and can still
+  exit 1, so a green pipeline says nothing about the seven `WARN_REQUIREMENT_*` authoring
+  checks. Grep CI config and scripts for both spellings. Muted is not automatically a defect —
+  a project that made a deliberate call is fine — but it moves those checks back onto the
+  auditor (see `references/requirements.md`), so **say which it is** rather than reporting the
+  ledger as lint-clean.
   **Coverage completeness — "wired" is not "covers it all."** A gate can be present
   yet blind to a whole artifact class. Confirm each subverb actually covers what the
   project HAS: (a) **templates** — `verify --templates` on a CLI before the #193 fix

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

@@ -114,15 +114,17 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 
 - **`identity.primary`** (`@generation`) — hunt hand-assigned primary keys / ID generation
   the primary identity's `@generation` strategy models.
-- **`identity.secondary`** (`@fields`; physical escapes `@using`/`@expr`/`@where`/`@orders`) — a
-  UNIQUE alternate key (uniqueness is the type — the legacy `@unique` attr was removed from it);
+- **`identity.secondary`** (keys off `@fields` XOR `@expr` — exactly one, never both; physical
+  escapes `@using`/`@where`/`@orders`) — a UNIQUE alternate key (uniqueness is the type — the
+  legacy `@unique` attr was removed from it, and the same XOR rule as `index.lookup` applies here
+  because ADR-0040 puts uniqueness in the TYPE: a secondary identity IS a unique index);
   hunt hand-rolled unique constraints or raw-SQL partial/functional unique indexes it models.
 - **`identity.reference`** (`@references`, `@enforce`) — hunt hand-written FK constraints /
   reference enforcement the reference identity already declares.
 
 ## Index — `index.*` (non-unique retrieval)
 
-- **`index.lookup`** (`@fields` required; physical escapes `@using`/`@expr`/`@where`/`@orders`) —
+- **`index.lookup`** (keys off `@fields` XOR `@expr` — exactly one, never both; physical escapes `@using`/`@where`/`@orders`) —
   a NON-unique retrieval index (uniqueness is what distinguishes it from `identity.secondary`);
   hunt hand-created lookup / recency indexes (`CREATE INDEX …`) it models.
 
@@ -238,6 +240,12 @@ subtypes with opposite polarity: `requirement.functional` fails when NOTHING imp
   recorded as a TODO, or a ticket number in a comment. **ABSENT disposition means UNDECIDED**,
   which is the point: a gap nobody has ruled on reads differently from one deliberately
   accepted.
+- **The doc slots behave differently on this node type** — do not audit them by the generic
+  rule below. `title` is CHARTERED here (a requirement's `name` is an identifier, so the label
+  lives in `title`) and is **rendered** by `meta docs`, heading each entry after its dotted
+  path; `summary` is INERT (nothing reads it, and `@statement` is already the required
+  one-liner) and `meta verify` warns on one. So an absent `summary` is correct, a populated
+  one is the finding, and a populated `title` is correct.
 - **CALIBRATION — entirely opt-in and warning-only where it counts.** A project declaring no
   `requirement.*` nodes sees no diagnostics at all, and object coverage ("entities claimed
   by nothing") ships as a WARNING deliberately — a real estate carrying one requirement will

package/agent-context/skills/metaobjects-audit/references/requirements.md

@@ -9,8 +9,38 @@ effort re-deriving what a green run already proves.
 
 ## What verify has already proven (do not re-check by hand)
 
-Links sit at or below the L4 floor, nesting agrees with levels, `@status` values are legal,
-and references resolve (with dangling allowed on `planned`, whose nodes do not exist yet).
+A run answers two different questions in two separate sections. Both are already-proven
+ground; neither is worth an auditor's time.
+
+**The gate** settles referential integrity: links sit at or below the L4 floor, nesting
+agrees with levels, `@status` values are legal, and references resolve (with dangling allowed
+on `planned`, whose nodes do not exist yet).
+
+**The authoring lint** — printed under its own heading, advisory, and unable to change the
+exit code — settles the naming and prose defects you would otherwise find by reading every
+entry:
+
+| code | what a clean run has already proven |
+|---|---|
+| `WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE` | no `name` is blank, space-padded, or carries a `.` / `/` / `:` that breaks the dotted path or the generated stub's filename |
+| `WARN_REQUIREMENT_NAME_READS_AS_PROSE` | no `name` is a sentence sitting in the address slot |
+| `WARN_REQUIREMENT_NAME_RESTATES_STATEMENT` | no `name` and `@statement` are the same sentence written twice |
+| `WARN_REQUIREMENT_PROSE_EMPTY` | no `@statement` / `@counterexample` is declared-but-blank (the loader enforces presence, never content) |
+| `WARN_REQUIREMENT_PROSE_DUPLICATED` | no `description` repeats `@statement` whole or as its opening sentence, and no `@counterexample` repeats it |
+| `WARN_REQUIREMENT_INERT_DOC_SLOT` | no `summary` is set — nothing reads it, and `@statement` is already the required one-liner |
+| `WARN_REQUIREMENT_TITLE_IS_AN_ID` | no `title` leads with a catalogue or ticket id |
+
+Two limits, and each puts something back on your list:
+
+- **The lint is mutable.** `--no-requirement-lint` / `META_NO_REQUIREMENT_LINT=1` silences the
+  advisory half while the gate still runs. **Establish whether the project mutes it** (§F of
+  the checklist asks this) — against a muted lint the whole table above proves nothing.
+- **It reports only EXACT repeats.** A paraphrase — `description` restating `@statement` in
+  different words, a `@counterexample` that merely negates it — is invisible to the tool and
+  is a legitimate hand finding.
+
+`title` is deliberately NOT flagged as an inert slot; it is chartered as the entry's label and
+is rendered (see item 6). Do not report a populated `title` as a defect.
 
 ## What only a human or an agent reading the code can catch
 
@@ -40,6 +70,14 @@ functional one.
 model. If the tree is flat, or every entry is L3, the levels are carrying no information and
 should be simplified rather than defended.
 
+**6. Titles that are not labels.** `title` is now **rendered** — `meta docs` heads each entry
+`## checkout.payment — Payment capture`, the path first and the label after it — so a slot
+that used to be inert is read by every reader of the generated page. The lint catches only
+the id-shaped case (`FR-448 …`); it cannot tell a *useless* label from a good one. Read the
+titles: one that restates `@statement`, or repeats the path in prose, is now visible noise in
+a heading rather than a private authoring habit. An absent `title` is NOT a finding — the
+entry heads by its path alone, which is what every sibling surface addresses it by.
+
 ## Scope — do NOT flag these as defects
 
 - **Unclaimed `object.value` / `object.projection`.** Exempt by design: a value is a shape, a

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

@@ -590,17 +590,32 @@ does NOT enforce uniqueness. Choose the right construct by what the constraint I
 | Unique alternate key (e.g. email, slug) | `identity.secondary` — uniqueness is the type |
 | Query-performance index, no uniqueness | `index.lookup` |
 
-`@fields` names the indexed columns and is **required** (at least one). The db provider
-contributes physical-tuning attrs: `@orders` (per-column sort direction), `@using` (access
-method — `gin`/`gist`/`hash`; default `btree`), `@expr` (key expression derived from
-`@fields`, e.g. for a functional index), and `@where` (partial-index predicate).
+**An index keys off EXACTLY ONE of `@fields` or `@expr`.** `@fields` names the indexed
+columns; `@expr` is a raw key expression used **instead of** `@fields` (a functional index).
+Declaring **neither** — or **both** — is `ERR_INVALID_INDEX`. This applies to
+`identity.secondary` as well as `index.lookup`: uniqueness lives in the type, so a unique
+index keys itself the same way.
+
+Legacy metadata declaring both used to load, with `@fields` **silently discarded**. If you
+meet one, `meta upgrade --apply` drops `@fields` — do not hand-pick the survivor: the index
+in the database is the expression one, so keeping `@expr` reproduces it and keeping
+`@fields` would emit a migration against live data.
+
+The db provider contributes physical-tuning attrs alongside either form: `@orders`
+(per-column sort direction), `@using` (access method — `gin`/`gist`/`hash`; default
+`btree`), and `@where` (partial-index predicate).
 
 ```json
 { "index.lookup": { "name": "byCreatedAt", "@fields": ["createdAt"], "@orders": ["desc"] } }
 { "index.lookup": { "name": "byStatusCreatedAt", "@fields": ["status", "createdAt"] } }
-{ "index.lookup": { "name": "byEmailCI", "@fields": ["email"], "@expr": "lower(email)" } }
+{ "index.lookup": { "name": "byEmailCI", "@expr": "lower(email)" } }
+{ "identity.secondary": { "name": "uniqLowerEmail", "@expr": "lower(email)" } }
 ```
 
+> **Do not write `@fields` and `@expr` together.** It reads as "index this column, by this
+> expression", but the expression is the whole key — the `@fields` list was silently
+> discarded. It is now refused rather than half-honoured.
+
 `index.lookup` is a sibling of `identity.*` — declare it as a direct child of an `object.entity`,
 at the same level as fields and identities.
 
@@ -828,8 +843,16 @@ amendment 2026-08-06.)
 
 **Origin vocabulary (#195).** `origin.aggregate @agg` takes `count`/`sum`/`avg`/`min`/`max`
 (numeric reduces over `@of`), `any`/`all` (predicate quantifiers over a `@filter`; `@of`
-forbidden; empty set → `any=false`, `all=true`), and `collect` (an array rollup of `@of`
-into an `isArray` field, with optional `@distinct` / `@orderBy`). Any aggregate may be
+forbidden; empty set → `any=false`, `all=true`), and `collect` (an array rollup
+into an `isArray` field, with optional `@distinct` / `@orderBy`). **`collect` is the one
+`@agg` where `@of` is OPTIONAL (#335):** name a column with `@of` to collect scalars, or
+omit `@of` on a `field.object @objectRef` to collect each related row as that declared
+value object — a **whole-object rollup**, lowered to `jsonb_agg(jsonb_build_object(…))`
+on Postgres. The whole-object form requires an explicit `@via`, refuses `@distinct` (it is
+a no-op whenever the value object carries the primary key), and requires every value-object
+member to match a field on the `@via` **terminal** entity by name, with the same subtype
+and array-ness. The declared value object IS the exposure: a field the entity has and the
+value object omits is not projected. Any aggregate may be
 row-scoped with `@filter`. `origin.computed` carries a closed structured `@expr` tree (a
 derived scalar). `origin.first` picks one related row's column (`@of`) along `@via`,
 ordered by a **required `@orderBy`** (`["field:asc|desc", …]`, with the PK as tie-break) —

package/agent-context/skills/metaobjects-authoring/references/requirements.md

@@ -5,13 +5,31 @@ describe. Read the existing requirement nodes before designing anything. Two rul
 more than the rest.
 
 **1. A requirement is PRESCRIPTIVE — it states what should be true, never what happened.**
-So when a capability is retired, **delete its requirement** in the same change that removes
-the code. `status` is `planned | live | partial`; there is no member meaning "we used to do
-this", because every one of those three describes something meant to be true now or soon.
-
-What a deleted entry leaves behind is a diff, which is the right home for it. If something
-about the retirement is worth carrying forward — why it went, what replaced it — put that in
-`notes` on the entry that survives, where a reader looking at today's model will find it.
+`status` is `planned | live | partial | retired`, and every one of them states something
+meant to be true. `retired` is not the exception: it means **"this was built, then
+deliberately removed, and must not be rebuilt"** — a prohibition in force, falsifiable by
+exactly one observable, the capability reappearing.
+
+So write a retired entry as a rule, not a diary. `statement: "An unpaid order is never
+expired by a wall-clock timer"` is a prohibition; `"We used to expire orders on a timer"` is
+history wearing a requirement's shape, and no gate will catch it. On a retired entry
+`counterexample` describes **the revival** — the thing a future reader is about to propose.
+
+**Do not delete a retired capability's entry.** Keeping it is the single most load-bearing
+thing this vocabulary does: given a brief for a capability that had been retired, agents
+working from the model alone proposed rebuilding it 24 times out of 24. The entry is what
+stops that, so a retirement is a status change plus a rewritten statement, never a deletion.
+
+Three rules the loader enforces on `retired`:
+
+- **`implementedBy` is REFUSED** — a retired capability has no implementation by definition.
+  What used to implement it goes in `notes`. If deleting the references feels wrong, the
+  capability is probably not retired: an entry whose nodes are still there is `live` or
+  `partial`.
+- **`supersededBy` names the requirement that replaced it**, legal here only, and RESOLVED —
+  so the chain still works when the replacement is itself retired later.
+- It never counts toward object coverage, and is exempt from the architectural universality
+  check.
 
 Leaving a dangling `implementedBy` is **correct only on `planned`**: the entry precedes the
 nodes. On `live` or `partial` the same dangling reference is an error — the model moved and
@@ -27,10 +45,9 @@ rule kills *"the system is reliable"*. If you cannot say what breaking it looks
 delete it.
 
 **Four prose slots, and `statement` is the one that means "description".** A requirement can
-also carry the common `title`, `description` and `notes`, and they overlap badly unless you
-decide the split before writing any of them:
+also carry the common `description` and `notes`, and they overlap badly unless you decide the
+split before writing any of them:
 
-- `title` — a short **noun-phrase** label (`name` is an identifier; this is what an index shows)
 - `statement` — **the claim**. This IS the description of what the requirement is
 - `counterexample` — **what would falsify the claim**, which is what makes it checkable
 - `description` — **the scope**: what the claim covers, what it deliberately does not, and
@@ -38,12 +55,33 @@ decide the split before writing any of them:
 - `notes` — **the evidence**: how you know the `status` is true — citations, vocabularies, the
   control you ran to prove an absence was real
 
+**`title` is a LABEL and is chartered here; `summary` is not.** A requirement's `name` is an
+identifier and its address renders as a dotted camelCase path, so a short noun-phrase `title` is
+what an index shows — the requirement attribute table in `spec/capability-ledger.md` says so by
+name, and the generated requirements page renders it in the heading after the path
+(`## checkout.payment — Payment capture`). `summary` is different: `statement` is already the
+required one-line sentence, so a `summary` can only repeat it and nothing reads it (`verify` warns,
+`WARN_REQUIREMENT_INERT_DOC_SLOT`). `notes` is unrendered on purpose — chartered internal-only.
+
+**Never put a catalogue or ticket id in `title`.** A title is a noun phrase; an id is not a name.
+`title: "FR-467 — Order recording"` is two things in one slot — put the id in `trackedBy` and
+keep the phrase as the title. `verify` warns (`WARN_REQUIREMENT_TITLE_IS_AN_ID`).
+
+**The `name` is an address, so write it as an identifier.** It is the segment of the dotted
+path (`Ordering.Placement.Recorded`) and the filename of the generated test stub. A `.` in a
+name is indistinguishable from nesting — `Orders.Recorded` and `Orders` containing `Recorded`
+produce the same path — and a sentence for a name puts the claim somewhere nothing reads it.
+Both load; `verify` warns (`WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE`,
+`WARN_REQUIREMENT_NAME_READS_AS_PROSE`, `WARN_REQUIREMENT_NAME_RESTATES_STATEMENT`).
+
 Two failure modes, both of which look like diligence. A `description` that **paraphrases the
 statement** is padding, and it makes every later reader trust the ledger less — leave it off
 instead, it is optional. A `description` that **narrates the evidence** belongs in `notes`;
 the tell is a fact you had to read the implementation to learn. Mechanical test for the last
 line: *would this sentence have to change if the code changed but the model did not?* Then it
-is `notes`.
+is `notes`. `verify` warns on the exact repeats (`WARN_REQUIREMENT_PROSE_DUPLICATED`), and on
+a `statement` or `counterexample` that is present but blank (`WARN_REQUIREMENT_PROSE_EMPTY`) —
+the loader requires those attrs to exist, never to say anything.
 
 **Hierarchy is nesting, and links live at the bottom.** L1 solution, L2 segment, L3
 service — these never reference the model. **L4** binds a declared top-level node — an

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

@@ -72,6 +72,16 @@ dotnet meta docs metaobjects --out Docs   # → Docs/api/csharp (AGENT-API.md +
 `AGENT-API.md` — the exact imports, signatures, and payload field shapes for the
 generated code. **Before calling any generated code, read `api/csharp/AGENT-API.md`.**
 
+**The two `docs` positionals are NOT the same argument.** This one is the METADATA
+directory. The Node `meta docs` positional — used by every stack, since `migrate`,
+`verify --db` and the neutral model docs are Node-only — is the PROJECT ROOT that
+CONTAINS the metadata. Run `meta docs` with no positional, from the project root:
+
+```bash
+dotnet meta docs metaobjects --out Docs   # C#: the METADATA dir
+meta docs --out Docs                      # Node: run from the PROJECT ROOT (no positional)
+```
+
 ## Persistence + routes are the deployed artifact
 
 C# generates a *complete* server stack: the entity classes + `AppDbContext` ARE the

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

@@ -38,6 +38,16 @@ metaobjects docs ./metadata --out ./docs   # → ./docs/api/python (AGENT-API.md
 `AGENT-API.md` — the exact imports, signatures, and payload field shapes for the
 generated code. **Before calling any generated code, read `api/python/AGENT-API.md`.**
 
+**The two `docs` positionals are NOT the same argument.** This one is the METADATA
+directory. The Node `meta docs` positional — used by every stack, since `migrate`,
+`verify --db` and the neutral model docs are Node-only — is the PROJECT ROOT that
+CONTAINS the metadata. Run `meta docs` with no positional, from the project root:
+
+```bash
+metaobjects docs ./metadata --out ./docs   # Python: the METADATA dir
+meta docs --out ./docs                     # Node: run from the PROJECT ROOT (no positional)
+```
+
 ## Generators
 
 Wire generators by their stable name (`--generators <names>`), or run the default set.

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

@@ -67,6 +67,17 @@ block, and the inferred types.
 A second file, `.metaobjects/config.json`, holds static project state parseable by
 non-TS tooling; `meta init` scaffolds both plus the `metaobjects/` source dir.
 
+`sources` in that file is where the metadata lives — `metaobjects/` is only its
+DEFAULT value, so a project can point it anywhere. **Every entry is an OBJECT, never
+a bare string**, and it names a DIRECTORY or a file:
+
+```jsonc
+{ "schema_version": 1, "sources": [{ "path": "model" }, { "path": "../shared/metadata" }] }
+```
+
+Every command's directory argument (`meta docs <project-root>`, `--cwd`) is the
+PROJECT ROOT that CONTAINS the metadata — never the metadata directory itself.
+
 ## The generators
 
 From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
@@ -122,10 +133,10 @@ cross-subtype 404. Conformance-gated by `fixtures/api-contract-conformance/tph`
 (HTTP wire shape) and `fixtures/persistence-conformance/tph-*` (single-table
 runtime semantics).
 
-## Docs — `meta docs` (one door, two surfaces)
+## Docs — `meta docs` (one door, three surfaces)
 
 Documentation is NOT a `meta gen` generator. The single door is the `meta docs`
-command, which emits two cross-linked **surfaces** under one output dir (default
+command, which emits three cross-linked **surfaces** under one output dir (default
 `./docs`):
 
 - **model surface** (`./docs/<Entity>.md`, `./docs/<Template>.md`) — the neutral
@@ -135,11 +146,19 @@ command, which emits two cross-linked **surfaces** under one output dir (default
   `./docs/api/AGENT-API.md`) — the SDK/API reference: the concrete imports,
   function signatures, payload field shapes, and runnable examples for *this*
   project's generated code.
+- **requirements surface** (`./docs/requirements.md`, `./docs/requirements.toon`) —
+  the declared `requirement.*` ledger as documentation, with each entry headed by its
+  dotted path and its `title` where it has one, and each entity page naming the
+  requirements that claim it. Metadata-alone like the model surface, so it needs no
+  gen config. **On by default since 0.24.0** — a project declaring no `requirement.*`
+  nodes writes no requirements file and the run says nothing about the surface at all,
+  deliberately: reporting "0 requirement pages" would advertise a surface that never ran.
 
 ```bash
-npx meta docs                     # both surfaces → ./docs (model) + ./docs/api (api)
+npx meta docs                     # all three → ./docs (model) + ./docs/api + ./docs/requirements.*
 npx meta docs --model             # model surface only
 npx meta docs --api               # api surface only
+npx meta docs --requirements      # requirement ledger only
 npx meta docs --out ./site-docs   # write under a different root
 ```
 

package/agent-context/skills/metaobjects-fit-assessment/SKILL.md

@@ -18,13 +18,14 @@ DEFERRED, ON PURPOSE — capability requirements (`requirement.functional` /
 `requirement.architectural`). This skill deliberately says NOTHING about them, and that is a
 decision, not an omission.
 
-Why not now: (1) the grounding rule above requires every capability claim be verifiable
-against the CURRENT RELEASE, and `requirement.*` is not in one yet. (2) The signal->feature
-mapping is unvalidated against this skill's own kill criterion: the controlled evidence
-(0/24 model-only revivals) measures POST-adoption model-reading, and the feature's premise --
-that the disproof lives nowhere in the model -- cuts against pre-adoption detectability. If
-the reasoning was never written down, there is nothing for an evidence-cited assessment to
-cite. (3) Whether anyone fills the ledger in is itself untested; advertising it pre-adoption
+Why not now: (1) SPENT -- this read "not in a release yet", and it is now. `requirement.*`
+shipped in 0.22.0 and has evolved twice since (0.23.0 added `planned` / `@disposition` /
+`@trackedBy`; 0.24.0 made the vocabulary prescriptive-only). Do not repeat this reason.
+(2) The signal->feature mapping is unvalidated against this skill's own kill criterion: the
+controlled evidence (0/24 model-only revivals) measures POST-adoption model-reading, and the
+feature's premise -- that the disproof lives nowhere in the model -- cuts against pre-adoption
+detectability. If the reasoning was never written down, there is nothing for an evidence-cited
+assessment to cite. (3) Whether anyone fills the ledger in is itself untested; advertising it pre-adoption
 is the brochure failure this skill exists to avoid.
 
 TRIGGER to revisit — the release carrying `requirement.*` has shipped, AND either:
@@ -34,6 +35,23 @@ TRIGGER to revisit — the release carrying `requirement.*` has shipped, AND eit
   Arm B  a team that adopted via this assessment hits a resurrection the ledger would have
          caught, or asks why the assessment never mentioned it.
 
+ARM A HAS FIRED (dogfooded adopter estate, 2026-08-13). Three retired or reversed capability
+decisions were each citable PRE-adoption at file:line -- a removal commit, two explicit
+do-not-reintroduce comments on the very constant an agent would revive, an .env.example line
+saying the knob does not exist. The ANTI-TRIGGER did NOT fire: every one traced to committed
+prose. Bound it honestly -- n=1, and that estate is unusually disciplined about recording
+reversals in co-located prose, which is precisely the manual work `requirement.*` systematizes,
+so it is a confound rather than a clean sample. It also partly falsifies the feature's own
+premise that the disproof lives nowhere in the model.
+
+SO THE DEFERRAL NOW RESTS ON (3) ALONE, which makes it a judgement about VALUE rather than a
+fact about the release. Unprompted uptake is still unmeasured, and a later cross-estate reading
+sharpened the question: ledger value tracks whether the ledger is EXECUTABLE -- whether some
+mechanism can falsify a claim -- not when it was written. The largest ledger measured carried
+no harness and produced no defect found by any mechanism. Advertising that to a team that will
+hand-maintain it is the brochure failure this skill exists to avoid. Revisiting means deciding
+the SHAPE below is worth spending, not re-checking whether the capability exists.
+
 ANTI-TRIGGER (defer -> never): if dogfooded entries trace only to tribal knowledge with no
 repo artifact, this assessment structurally cannot speak to the feature as a finding.
 
@@ -46,8 +64,10 @@ R0 verdict line: no verdict may turn on it.
 
 # MetaObjects Fit & Migration Assessment
 
-_Assessment prompt v1 (post-Phase-0 refinement). Grounded against MetaObjects npm `0.17.x` /
-Maven `7.9.x` — verify every capability claim against the current release before asserting it._
+_Assessment prompt v1 (post-Phase-0 refinement). Body originally grounded against MetaObjects
+npm `0.17.x` / Maven `7.9.x`; capability claims re-swept against npm `0.24.x` / Maven `7.24.x`
+on 2026-08-25, but not every line has been re-derived since — verify every capability claim
+against the current release before asserting it._
 
 You are an AI assistant running a **pre-adoption fit assessment** for MetaObjects
 (https://github.com/metaobjectsdev/metaobjects — the cross-language metadata standard:
@@ -265,11 +285,13 @@ signature class. Hunt all ten classes:
    **necessity test**: expressible when every output column is a passthrough
    (`origin.passthrough @from/@via`), a count/sum/avg/min/max (`origin.aggregate
    @agg/@of/@via`, row-scoped with `@filter`), a predicate quantifier (`origin.aggregate
-   @agg: any|all`), an array rollup (`origin.aggregate @agg: collect`), a non-aggregate
-   derived scalar (`origin.computed @expr`), an argmax-style "one related row's column"
-   pick (`origin.first @via` — covers the common `DISTINCT ON` / lateral-join shape),
-   a soft-delete/status/type row-scope (an
-   object-level `@filter` on `object.projection`), or `extends`-borrowed — and joins
+   @agg: any|all`), an array rollup (`origin.aggregate @agg: collect` — with `@of`
+   naming one column, or `@of` OMITTED since 0.24.1 to collect each related row as the
+   carrying field's declared value object, which is the `json_agg(row_to_json(...))` shape),
+   a non-aggregate derived scalar (`origin.computed @expr`), an argmax-style "one related
+   row's column" pick (`origin.first @via` — covers the common `DISTINCT ON` / lateral-join
+   shape), a soft-delete/status/type row-scope (an object-level `@filter` on
+   `object.projection`), or `extends`-borrowed — and joins
    follow declared relationships/`identity.reference` FKs. Expressible → projection
    candidate (note: an unmodeled hand view is *unmanaged* — invisible to `verify --db`;
    modeling it is what makes it gateable). `DISTINCT ON` and lateral join are **not**
@@ -313,7 +335,7 @@ concrete — lead with it.
 | schema vs model (5 + the DDL copy in 6) | spine owns DDL via `meta migrate`; **`meta verify --db`** (Node `meta` only; PG/SQLite/D1) |
 | opaque JSON columns (6-implicit) | `object.value` + `field.object @storage: jsonb` — the shape gets ONE checkable declaration + generated codecs |
 | read-model SQL (8) | `object.projection` + `origin.*` generate the view DDL |
-| scattered prompts (10) | `template.prompt` + typed payload VO + external text; **`meta verify --templates`** / `Renderer.verify` fails when a `{{field}}` no longer matches the payload; `template.output` (FR-006) + the tolerant `extract` parser and output-format fragment (FR-010) generate both sides of the tag contract |
+| scattered prompts (10) | `template.prompt` + typed payload VO + external text; **`meta verify --templates`** / `Renderer.verify` fails when a `{{field}}` no longer matches the payload; a **responding** `template.prompt` — one carrying `@responseRef` — generates parser-on-receipt (FR-006) plus the output-format fragment and tolerant `extract` (FR-010), i.e. both sides of the tag contract. A `template.output` is **outbound only** and emits no parser (ADR-0052, 0.24.0) |
 | the metadata itself | strict provenance (ADR-0023): unknown attrs fail load |
 
 State the honest limits in the same section: `verify` cannot catch semantic mismodeling
@@ -428,8 +450,11 @@ promising it or counting it in benefits:
   count them).
 - email/URL/IP regexes → `@stringFormat: email` / `field.uri` / `field.inet`.
 - opaque JSON columns → `object.value` + `field.object @storage: jsonb` (from P2-b).
-- inline prompts / ad-hoc payload dicts / regex output parsing → `template.prompt` /
-  `template.output` / `template.toolcall`.
+- inline prompts / ad-hoc payload dicts → `template.prompt` / `template.toolcall`; a
+  hand-rolled regex or JSON-scrape of an LLM **reply** → a *responding* `template.prompt`
+  (one carrying `@responseRef`), never `template.output` — the subtype's axis is DIRECTION
+  and an output is outbound only (ADR-0052). Rendered emails / documents / config exports
+  are what `template.output` is for.
 - doc comments hand-written in migrations (`COMMENT ON`) → the common `description` attr.
 - a recurring closed variant-set as N sibling modules → project-registered provider
   subtype — VOCAB CANDIDATE, advisory only, never load-bearing for the verdict.
@@ -572,9 +597,11 @@ Every prose prediction gets a claim. Ceiling statements (P5-b) MUST carry
   runtime; consumer hand-wires the FastAPI router + repository impl; `metaobjects`
   console script `gen`/`verify` (no migrate).
 - **Prompt pillar** (all five ports): render + payload-VO codegen + `verify` templates +
-  `template.output` parser-on-receipt (FR-006) + output-format fragment & tolerant
-  `extract` (FR-010). MCP exposure of declared prompts/tools: not shipped — never
-  promise it.
+  parser-on-receipt for a **responding `template.prompt`** (FR-006) + output-format fragment
+  & tolerant `extract` (FR-010). Since 0.24.0 that whole inbound tier keys off `@responseRef`
+  on a `template.prompt`; a `template.output` is outbound-only and emits none of it
+  (ADR-0052) — do not promise a parser for one. MCP exposure of declared
+  prompts/tools: not shipped — never promise it.
 - **Not shipped, never promise**: `api.*`/`operation.*`/`binding.*` declared-API surface;
   the cut `byte`/`short`/`class` field stubs (non-functional, removed from the registry);
   `index.fulltext`/`vector`/`spatial` (reserved, unregistered); native PG enums /

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

@@ -46,6 +46,28 @@ Two more are caught structurally rather than by a command: **generated-edited**
 **migration-vs-metadata** (migrations are emitted *from* metadata diffs, so they
 can't drift by construction).
 
+## Before any of this: the metadata has to LOAD — `meta upgrade` for retired vocabulary
+
+`verify` cannot report drift in a model it could not read. The registry is sealed
+(ADR-0023), so a retired name has **no deprecation shim** — it is a load error, and
+the run stops before the first drift check. Retirements that bite an existing estate:
+`@readOnly` → `@mutability` and `origin.collection` → `origin.aggregate @agg: collect`
+(0.24.0); `@violation` → `@counterexample`, plus `@verifiedBy`, `@supersededBy` and
+`@status: abandoned | superseded` on `requirement.*` (0.24.0, FR-038); and an index key
+declaring **both** `@fields` and `@expr`, refused since 0.24.1.
+
+```
+meta upgrade            # previews every rewrite; writes nothing
+meta upgrade --apply    # makes them
+```
+
+Node-only, because it edits the metadata documents every port shares — a Java, Python
+or C# project runs `npx meta upgrade` against its own sources. Canonical JSON and YAML
+alike. It rewrites from the same table the loader's errors are generated from, fixes
+only what has one correct answer, and **refuses the rest with a non-zero exit** so a
+pipeline cannot record a partial migration as done. See
+`references/requirements.md` for what it refuses on a ledger and why.
+
 ## Run `meta verify` before you call a build done
 
 Make a bare `meta verify` the last step before you consider any MetaObjects work

package/agent-context/skills/metaobjects-verify/references/requirements.md

@@ -13,6 +13,37 @@ subverb**: requirements are metadata, so they are checked on *every* `meta verif
 A typo'd `@status` fails the **load** ("failed to load metadata"), before verify runs. If you
 see that, no other diagnostic in the run is trustworthy — fix it first and re-run.
 
+## A load failure on RETIRED vocabulary — run `meta upgrade`, do not hand-sweep
+
+`@status` is not the only way the load fails before any of this runs. **0.24.0** retired
+`@violation` (→ `@counterexample`) and `@verifiedBy`; **0.24.1** made an index key `@fields`
+**XOR** `@expr`, so a node declaring both is now `ERR_INVALID_INDEX`. **0.24.2 reversed half
+of the 0.24.0 cut**: `abandoned` and `superseded` become **`@status: retired`**, and
+`@supersededBy` is registered again — this time as a reference the loader resolves. There is no deprecation shim for any of them —
+the registry is sealed (ADR-0023), so a legacy document does not load at all and every check on
+this page is unreachable until it does.
+
+```
+meta upgrade            # previews every rewrite; writes nothing
+meta upgrade --apply    # makes them
+```
+
+It rewrites from the same table the loader's error text is generated from, so the fix you are
+told about and the edit the tool makes cannot drift apart. It fixes only what has one correct
+answer and **refuses the rest, exiting non-zero** — a partial migration can never be recorded
+as finished by CI. Two refusals are expected on a real ledger and both are yours to decide:
+
+- **`@status: abandoned` / `superseded` are no longer refused** — they rewrite to `retired`,
+  and the same run drops the `@implementedBy` that a retired entry may not carry. This was the
+  canonical judgement case in 0.24.0; FR-039 made it determinate.
+- **`origin.collection`.** Retired to `origin.aggregate @agg: collect`; the attribute sets
+  differ, so the tool will not guess.
+
+`@fields` beside `@expr` **is** rewritten, and the survivor is not a coin toss: that pair loaded
+before 0.24.1 with `@fields` silently discarded, so the index already in your database is the
+expression one. `upgrade` drops `@fields` — which reproduces the object that exists and emits no
+DDL change. Do not hand-pick the other survivor; that invents a new index and migrates live data.
+
 ## The status asymmetry — the one that surprises people
 
 The **same** unresolved `@implementedBy` reference is:
@@ -49,6 +80,8 @@ name the remedy; this table exists so you can act on one without re-deriving the
 | `ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS` | a `live`/`partial` `requirement.architectural` that nothing implements | a policy declared and applied to nothing. Claim the nodes it governs, or drop it to `planned` — which is exempt, because it is not applied yet by definition. |
 | `ERR_REQUIREMENT_LEVEL_NESTING` | a node's `@level` disagrees with the level of the parent it nests under | nesting IS the hierarchy. Move the node to the right parent rather than editing the level to match where it happens to sit. |
 | `ERR_REQUIREMENT_BAD_LEVEL` | `@level` is not an integer inside the allowed range | levels are L1–L5 and nothing else. |
+| `ERR_REQUIREMENT_RETIRED_HAS_IMPLEMENTORS` | a `@status: retired` entry declares `@implementedBy` | a retired capability has no implementation by definition. Delete the attribute and put what used to implement it in `notes`; if the nodes are still there, the capability is `live` or `partial`, not retired. |
+| `ERR_REQUIREMENT_SUPERSEDED_BY_NOT_RETIRED` | `@supersededBy` on a status other than `retired` | it names what REPLACED a withdrawn capability, so on a live one there is nothing for it to say. |
 | `ERR_MISSING_REQUIRED_ATTR` | a required attr is absent | `@statement`, `@status` and `@counterexample` are required on both subtypes; `@level` is required on `functional` and optional on `architectural`. |
 | `ERR_BAD_ATTR_VALUE` | a closed-enum attr has an unknown value | `@status` and `@disposition` are enforced by the LOADER, so a typo fails the load in every port rather than passing in some. |
 
@@ -56,6 +89,40 @@ name the remedy; this table exists so you can act on one without re-deriving the
 reasons, so reading only the code you hit can send you the wrong way. The question is not
 "is this ref valid?" — usually it is — but "does the LEVEL match the shape of the ref?"
 
+## The authoring lint — a second section, never an error
+
+`verify` also prints an **authoring lint** under its own heading, after the gate's own
+warnings:
+
+```
+meta verify — requirements: 6 authoring warning(s) (advisory — does not fail the build):
+```
+
+Read it as a different claim from everything above. The gate says the ledger **disagrees with
+the model**; the lint says it agrees but **records less than its author thinks**. Every finding
+is a warning and none can change the exit code, so a lint-only run is a passing run.
+
+| code | what it means | fix |
+|---|---|---|
+| `WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE` | the `name` holds a character that breaks the dotted path or the generated stub filename | rename it. A `.` is the common one and the worst: `Orders.Recorded` and `Orders` containing `Recorded` produce the **same** path, so the address stops identifying one node. |
+| `WARN_REQUIREMENT_NAME_READS_AS_PROSE` | the `name` is a sentence | the name is an address — make it an identifier and put the prose in `@statement`. |
+| `WARN_REQUIREMENT_NAME_RESTATES_STATEMENT` | `name` and `@statement` say the same thing | the claim is written twice. Keep `@statement` (every surface reads it) and shorten the name. |
+| `WARN_REQUIREMENT_PROSE_EMPTY` | `@statement` or `@counterexample` is present but blank | the loader requires the attr to EXIST, never to say anything. Write the sentence, or delete the entry. |
+| `WARN_REQUIREMENT_PROSE_DUPLICATED` | `description` repeats `@statement` (whole, or as its opening sentence), or `@counterexample` does | `@statement` is already the description. `description` holds the SCOPE; drop it entirely if the scope is obvious. |
+| `WARN_REQUIREMENT_INERT_DOC_SLOT` | `summary` is set on a requirement | `@statement` is already the required one-line sentence, so a summary can only repeat it, and nothing reads it. Delete it. (`title` is NOT flagged — it is chartered as the entry's label.) |
+| `WARN_REQUIREMENT_TITLE_IS_AN_ID` | `title` holds a catalogue or ticket id | a title is a noun phrase and an id is not a name. **Split** it — the id to `@trackedBy`, the phrase stays the title. Do not move the whole string; that throws the label away. |
+
+Findings from both sections are addressed by the requirement's **dotted path**, never its
+bare name — two branches of a ledger may reuse a name, so a bare one can be ambiguous.
+
+Mute the lint with `--no-requirement-lint` or `META_NO_REQUIREMENT_LINT=1`. That silences the
+advisory half **only** — the gate above still runs and can still exit 1.
+
+Two deliberate silences. The lint reports only **exact** repeats, never a paraphrase — a
+similarity threshold on prose produces findings you can argue with. And it never judges
+whether a statement is true or a counterexample sufficient; those are the judgements the
+ledger exists to record.
+
 ## `verify` does not look at your tests
 
 It used to. `@verifiedBy` asked you to name a test, and `verify` checked that the **name**

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAkBA,OAAO,EAKL,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,UAAU;IACzB;2EACuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;4BAGwB;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C;;;;;gFAK4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C;;gFAE4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChE;;;;2EAIuE;IACvE,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC9D;AAaD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9B,OAAO,CAAC,UAAU,CAAC,CA0ErB"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAmBA,OAAO,EAKL,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,UAAU;IACzB;2EACuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;4BAGwB;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C;;;;;gFAK4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C;;gFAE4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChE;;;;2EAIuE;IACvE,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC9D;AA8ED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9B,OAAO,CAAC,UAAU,CAAC,CA6FrB"}

package/dist/collection.js

@@ -10,13 +10,79 @@
 // today (`DEFAULT_SOURCES` in `sources.ts`); a project that declares
 // `sources` can point anywhere. No other call site may assume the directory
 // name — this is where that assumption is allowed to live, exactly once.
-import { join, resolve } from "node:path";
-import { ParseError, codeSource } from "@metaobjectsdev/metadata";
+import { dirname, extname, join, resolve } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { ParseError, codeSource, SUBTYPE_ROOT, TYPE_METADATA } from "@metaobjectsdev/metadata";
 import { CONFIG_FILE, loadConfig } from "./config.js";
 import { discoverCollectionRoot, exists, isDir } from "./discovery.js";
 import { compileScope, matchesScope } from "./scope.js";
-import { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+import { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR, isMetadataFile } from "./metadata-files.js";
 import { DEFAULT_SOURCES, orderedPathSpecs, resolveSpecPath, resolveSources, } from "./sources.js";
+/** The canonical-JSON document root key (`metadata.root`) and the sigil-free
+ *  YAML root mapping key (`metadata:`, at column 0 — ADR-0006), built from the
+ *  metamodel constants rather than spelled out. */
+const JSON_ROOT_KEY = `${TYPE_METADATA}.${SUBTYPE_ROOT}`;
+const YAML_ROOT_KEY = new RegExp(`^${TYPE_METADATA}\\s*:`, "m");
+/** Bound on the sniff below: one hit is enough to diagnose, and this runs only
+ *  on a path that has already failed. */
+const MAX_SNIFFED_FILES = 20;
+/**
+ * Cheap "is this file a metadata DOCUMENT?" sniff — for a diagnostic, never for
+ * loading. It decides whether to change an error MESSAGE; nothing downstream
+ * reads its answer, and a false negative costs only the generic message.
+ *
+ * A file-EXTENSION test cannot answer this: `package.json` and `tsconfig.json`
+ * carry a recognized metadata extension ({@link isMetadataFile}), so every JS
+ * project root that has no metadata yet would be misdiagnosed as a metadata
+ * directory — a confidently wrong hint, which is worse than the generic one it
+ * would replace. The document root is `metadata.root` in canonical JSON and the
+ * sigil-free `metadata:` key in YAML authoring (ADR-0006), so those are what
+ * this looks for.
+ */
+async function sniffsAsMetadataDocument(file) {
+    const text = await readFile(file, "utf8").catch(() => undefined);
+    if (text === undefined)
+        return false;
+    if (extname(file).toLowerCase() !== ".json") {
+        // YAML: the root mapping key, at column 0. Not a parse — this package has
+        // no YAML parser, and acquiring one to improve an error message would be a
+        // dependency bought with nothing.
+        return YAML_ROOT_KEY.test(text);
+    }
+    try {
+        const doc = JSON.parse(text);
+        return typeof doc === "object" && doc !== null && JSON_ROOT_KEY in doc;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Does `dir` hold metadata but carry no project marker — i.e. is it the
+ * METADATA directory, handed to a command whose directory argument is the
+ * PROJECT ROOT? (#344)
+ *
+ * That mistake is predictable rather than careless: the sibling `docs`
+ * positionals in the Python and C# ports ARE the metadata directory, and all
+ * three are spelled the same way. The generic diagnostic then advises declaring
+ * `sources`, which from inside the metadata directory is a dead end.
+ *
+ * Only the top level is scanned. A metadata directory has metadata files in it;
+ * recursing would walk `node_modules/` on the very input this must NOT
+ * misdiagnose.
+ */
+async function holdsMetadataButIsNoRoot(dir, hasConfig) {
+    // A directory carrying the marker IS a project root, by the only definition
+    // of one there is (`discovery.ts`). Nothing to diagnose.
+    if (hasConfig)
+        return false;
+    const entries = await readdir(dir).catch(() => []);
+    for (const entry of entries.filter(isMetadataFile).slice(0, MAX_SNIFFED_FILES)) {
+        if (await sniffsAsMetadataDocument(join(dir, entry)))
+            return true;
+    }
+    return false;
+}
 /** Narrow the zod-inferred `Config["scope"]` (whose `.optional()` fields are
  *  typed `T | undefined` even when present) down to `Scope`'s
  *  exactOptionalPropertyTypes-safe shape — a key is omitted entirely rather
@@ -98,8 +164,24 @@ export async function resolveCollection(startDir, opts) {
     // whenever a discovered config declares no `sources`, where nothing has
     // probed it at all.
     if (specs === DEFAULT_SOURCES && !(await isDir(join(configDir, DEFAULT_METADATA_DIR)))) {
+        // #344 — name the one wrong answer worth naming before falling back to the
+        // generic advice. Told "declare sources" while standing in the metadata
+        // directory, an author declares the metadata FILES, and the config schema
+        // then rejects a bare string (a `sources` entry is `{ "path": … }`) — two
+        // dead ends in a row for a caller whose only mistake was passing the
+        // directory the sibling ports' `docs` positional wants.
+        if (await holdsMetadataButIsNoRoot(configDir, hasConfig)) {
+            const parent = dirname(configDir);
+            const near = await discoverCollectionRoot(parent);
+            const suggested = near.hasConfig ? near.dir : parent;
+            throw new ParseError(`${configDir} looks like a metadata directory, not a project root — it holds metadata ` +
+                `files but carries no ${DEFAULT_METAOBJECTS_DIR}/${CONFIG_FILE}. A directory argument here is ` +
+                `the PROJECT ROOT that CONTAINS your metadata; where the metadata lives is then the root's ` +
+                `"sources" (default: the "${DEFAULT_METADATA_DIR}" directory beneath it). Try ${suggested} instead.`, { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") });
+        }
         throw new ParseError(`no metadata sources declared in ${configDir} and no default "${DEFAULT_METADATA_DIR}" directory found. ` +
-            `Declare "sources" in ${DEFAULT_METAOBJECTS_DIR}/config.json, or run 'meta init' to scaffold.`, { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") });
+            `Declare "sources" in ${DEFAULT_METAOBJECTS_DIR}/${CONFIG_FILE} — each entry is an OBJECT, ` +
+            `e.g. "sources": [{ "path": "model" }] — or run 'meta init' to scaffold.`, { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") });
     }
     const sources = await resolveSources(configDir, specs);
     const scope = compileScope(toScope(scopeSpec));

package/dist/collection.js.map

@@ -1 +1 @@
-{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,6DAA6D;AAC7D,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,yEAAyE;AACzE,mEAAmE;AACnE,0EAA0E;AAC1E,qEAAqE;AACrE,4EAA4E;AAC5E,yEAAyE;AACzE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,cAAc,GAGf,MAAM,cAAc,CAAC;AA6CtB;;;iCAGiC;AACjC,SAAS,OAAO,CAAC,IAAqB;IACpC,OAAO;QACL,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,IAA+B;IAE/B,MAAM,QAAQ,GAAG,IAAI,EAAE,WAAW,CAAC;IAEnC,wEAAwE;IACxE,6EAA6E;IAC7E,qEAAqE;IACrE,2EAA2E;IAC3E,wEAAwE;IACxE,2EAA2E;IAC3E,yEAAyE;IACzE,6EAA6E;IAC7E,IAAI,SAAiB,CAAC;IACtB,IAAI,SAAkB,CAAC;IACvB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9B,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,EAAE,WAAW,CAAC,CAAC,CAAC;IAClF,CAAC;SAAM,CAAC;QACN,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,KAAK,GAA0B,eAAe,CAAC;IACnD,IAAI,SAA0B,CAAC;IAC/B,IAAI,WAAiC,CAAC;IAEtC,IAAI,SAAS,EAAE,CAAC;QACd,iEAAiE;QACjE,uEAAuE;QACvE,sEAAsE;QACtE,mEAAmE;QACnE,uEAAuE;QACvE,aAAa;QACb,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC;QACvE,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC;QAChD,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC;QACtB,WAAW,GAAG,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC;IACnC,CAAC;IAED,2EAA2E;IAC3E,+EAA+E;IAC/E,EAAE;IACF,0EAA0E;IAC1E,4EAA4E;IAC5E,6EAA6E;IAC7E,8EAA8E;IAC9E,yEAAyE;IACzE,wEAAwE;IACxE,wEAAwE;IACxE,oBAAoB;IACpB,IAAI,KAAK,KAAK,eAAe,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,UAAU,CAClB,mCAAmC,SAAS,oBAAoB,oBAAoB,qBAAqB;YACvG,wBAAwB,uBAAuB,+CAA+C,EAChG,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/C,MAAM,YAAY,GAChB,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;IACjF,OAAO;QACL,SAAS;QACT,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACjC,OAAO;QACP,4EAA4E;QAC5E,mEAAmE;QACnE,WAAW,EAAE;YACX,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;SACpF;QACD,OAAO,EAAE,CAAC,GAAW,EAAW,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC;QAC3D,cAAc,EACZ,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAW,EAAW,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,YAAY,CAAC;QACpG,oBAAoB,EAAE,WAAW;KAClC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "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.0",
+    "@metaobjectsdev/metadata": "0.24.2",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/src/collection.ts

@@ -10,12 +10,13 @@
 // today (`DEFAULT_SOURCES` in `sources.ts`); a project that declares
 // `sources` can point anywhere. No other call site may assume the directory
 // name — this is where that assumption is allowed to live, exactly once.
-import { join, resolve } from "node:path";
-import { ParseError, codeSource } from "@metaobjectsdev/metadata";
+import { dirname, extname, join, resolve } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { ParseError, codeSource, SUBTYPE_ROOT, TYPE_METADATA } from "@metaobjectsdev/metadata";
 import { CONFIG_FILE, loadConfig, type Config } from "./config.js";
 import { discoverCollectionRoot, exists, isDir } from "./discovery.js";
 import { compileScope, matchesScope, type Scope } from "./scope.js";
-import { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+import { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR, isMetadataFile } from "./metadata-files.js";
 import {
   DEFAULT_SOURCES,
   orderedPathSpecs,
@@ -68,6 +69,71 @@ export interface Collection {
   readonly migrateScopePatterns: readonly string[] | undefined;
 }
 
+/** The canonical-JSON document root key (`metadata.root`) and the sigil-free
+ *  YAML root mapping key (`metadata:`, at column 0 — ADR-0006), built from the
+ *  metamodel constants rather than spelled out. */
+const JSON_ROOT_KEY = `${TYPE_METADATA}.${SUBTYPE_ROOT}`;
+const YAML_ROOT_KEY = new RegExp(`^${TYPE_METADATA}\\s*:`, "m");
+
+/** Bound on the sniff below: one hit is enough to diagnose, and this runs only
+ *  on a path that has already failed. */
+const MAX_SNIFFED_FILES = 20;
+
+/**
+ * Cheap "is this file a metadata DOCUMENT?" sniff — for a diagnostic, never for
+ * loading. It decides whether to change an error MESSAGE; nothing downstream
+ * reads its answer, and a false negative costs only the generic message.
+ *
+ * A file-EXTENSION test cannot answer this: `package.json` and `tsconfig.json`
+ * carry a recognized metadata extension ({@link isMetadataFile}), so every JS
+ * project root that has no metadata yet would be misdiagnosed as a metadata
+ * directory — a confidently wrong hint, which is worse than the generic one it
+ * would replace. The document root is `metadata.root` in canonical JSON and the
+ * sigil-free `metadata:` key in YAML authoring (ADR-0006), so those are what
+ * this looks for.
+ */
+async function sniffsAsMetadataDocument(file: string): Promise<boolean> {
+  const text = await readFile(file, "utf8").catch(() => undefined);
+  if (text === undefined) return false;
+  if (extname(file).toLowerCase() !== ".json") {
+    // YAML: the root mapping key, at column 0. Not a parse — this package has
+    // no YAML parser, and acquiring one to improve an error message would be a
+    // dependency bought with nothing.
+    return YAML_ROOT_KEY.test(text);
+  }
+  try {
+    const doc: unknown = JSON.parse(text);
+    return typeof doc === "object" && doc !== null && JSON_ROOT_KEY in doc;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Does `dir` hold metadata but carry no project marker — i.e. is it the
+ * METADATA directory, handed to a command whose directory argument is the
+ * PROJECT ROOT? (#344)
+ *
+ * That mistake is predictable rather than careless: the sibling `docs`
+ * positionals in the Python and C# ports ARE the metadata directory, and all
+ * three are spelled the same way. The generic diagnostic then advises declaring
+ * `sources`, which from inside the metadata directory is a dead end.
+ *
+ * Only the top level is scanned. A metadata directory has metadata files in it;
+ * recursing would walk `node_modules/` on the very input this must NOT
+ * misdiagnose.
+ */
+async function holdsMetadataButIsNoRoot(dir: string, hasConfig: boolean): Promise<boolean> {
+  // A directory carrying the marker IS a project root, by the only definition
+  // of one there is (`discovery.ts`). Nothing to diagnose.
+  if (hasConfig) return false;
+  const entries = await readdir(dir).catch(() => [] as string[]);
+  for (const entry of entries.filter(isMetadataFile).slice(0, MAX_SNIFFED_FILES)) {
+    if (await sniffsAsMetadataDocument(join(dir, entry))) return true;
+  }
+  return false;
+}
+
 /** Narrow the zod-inferred `Config["scope"]` (whose `.optional()` fields are
  *  typed `T | undefined` even when present) down to `Scope`'s
  *  exactOptionalPropertyTypes-safe shape — a key is omitted entirely rather
@@ -155,9 +221,28 @@ export async function resolveCollection(
   // whenever a discovered config declares no `sources`, where nothing has
   // probed it at all.
   if (specs === DEFAULT_SOURCES && !(await isDir(join(configDir, DEFAULT_METADATA_DIR)))) {
+    // #344 — name the one wrong answer worth naming before falling back to the
+    // generic advice. Told "declare sources" while standing in the metadata
+    // directory, an author declares the metadata FILES, and the config schema
+    // then rejects a bare string (a `sources` entry is `{ "path": … }`) — two
+    // dead ends in a row for a caller whose only mistake was passing the
+    // directory the sibling ports' `docs` positional wants.
+    if (await holdsMetadataButIsNoRoot(configDir, hasConfig)) {
+      const parent = dirname(configDir);
+      const near = await discoverCollectionRoot(parent);
+      const suggested = near.hasConfig ? near.dir : parent;
+      throw new ParseError(
+        `${configDir} looks like a metadata directory, not a project root — it holds metadata ` +
+          `files but carries no ${DEFAULT_METAOBJECTS_DIR}/${CONFIG_FILE}. A directory argument here is ` +
+          `the PROJECT ROOT that CONTAINS your metadata; where the metadata lives is then the root's ` +
+          `"sources" (default: the "${DEFAULT_METADATA_DIR}" directory beneath it). Try ${suggested} instead.`,
+        { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") },
+      );
+    }
     throw new ParseError(
       `no metadata sources declared in ${configDir} and no default "${DEFAULT_METADATA_DIR}" directory found. ` +
-        `Declare "sources" in ${DEFAULT_METAOBJECTS_DIR}/config.json, or run 'meta init' to scaffold.`,
+        `Declare "sources" in ${DEFAULT_METAOBJECTS_DIR}/${CONFIG_FILE} — each entry is an OBJECT, ` +
+        `e.g. "sources": [{ "path": "model" }] — or run 'meta init' to scaffold.`,
       { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") },
     );
   }