@metaobjectsdev/sdk 0.24.0 → 0.24.1

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

@@ -122,7 +122,7 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 
 ## 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.
 

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

@@ -590,17 +590,27 @@ 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.
+
+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 +838,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-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):

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":"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,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC/F,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,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,cAAc,GAGf,MAAM,cAAc,CAAC;AA6CtB;;mDAEmD;AACnD,MAAM,aAAa,GAAG,GAAG,aAAa,IAAI,YAAY,EAAE,CAAC;AACzD,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,IAAI,aAAa,OAAO,EAAE,GAAG,CAAC,CAAC;AAEhE;yCACyC;AACzC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,wBAAwB,CAAC,IAAY;IAClD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACjE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,CAAC;QAC5C,0EAA0E;QAC1E,2EAA2E;QAC3E,kCAAkC;QAClC,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,aAAa,IAAI,GAAG,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,KAAK,UAAU,wBAAwB,CAAC,GAAW,EAAE,SAAkB;IACrE,4EAA4E;IAC5E,yDAAyD;IACzD,IAAI,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAc,CAAC,CAAC;IAC/D,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,EAAE,CAAC;QAC/E,IAAI,MAAM,wBAAwB,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;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,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,0EAA0E;QAC1E,qEAAqE;QACrE,wDAAwD;QACxD,IAAI,MAAM,wBAAwB,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;YACzD,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;YAClC,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,MAAM,CAAC,CAAC;YAClD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;YACrD,MAAM,IAAI,UAAU,CAClB,GAAG,SAAS,2EAA2E;gBACrF,wBAAwB,uBAAuB,IAAI,WAAW,iCAAiC;gBAC/F,4FAA4F;gBAC5F,4BAA4B,oBAAoB,gCAAgC,SAAS,WAAW,EACtG,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAC9E,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,UAAU,CAClB,mCAAmC,SAAS,oBAAoB,oBAAoB,qBAAqB;YACvG,wBAAwB,uBAAuB,IAAI,WAAW,8BAA8B;YAC5F,yEAAyE,EAC3E,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "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.1",
     "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") },
     );
   }