fix(cli,sdk): a directory argument is the PROJECT ROOT, and the error now says so (#344)

`meta docs metaobjects` has never worked on Node and never will: the Node
positional is the project root, while the Python and C# `docs` positionals are
the metadata directory — and all three are spelled the same way in help text.
The Node one was literally named `<metadata>`.

The diagnostic then advised declaring `sources`, which from inside the metadata
directory is a second dead end: a `sources` entry is a tagged-union object
(`{ "path": … }`), so the bare string an author writes next fails config-schema
validation.

- `resolveCollection` names the mistake when the directory it resolved holds
  metadata but carries no `.metaobjects/config.json`, and points at the
  directory to pass instead. The discriminator is the document ROOT
  (`metadata.root` / a column-0 `metadata:`), NOT the file extension —
  `package.json` and `tsconfig.json` carry a recognized metadata extension, so
  an extension test would misdiagnose every JS project root with no metadata
  yet, and a confidently wrong hint is worse than the generic one.
- The generic message gained the shape it was asking for:
  `"sources": [{ "path": "model" }]`.
- The positional is renamed `[<project-root>]` in both help surfaces, and
  `DocsFlags.metadata` → `projectRoot` — the internal name is what kept
  regenerating the misleading word.
- The agent-context `metaobjects-codegen` references gained the cross-port note
  beside their own `docs` examples (the C# one shipped `dotnet meta docs
  metaobjects`, the exact string that misleads on Node), and the `sources` entry
  shape — which appeared in no installed skill — is now in the TS reference.

TypeScript-only, deliberately: the sibling ports' directory arguments are
metadata directories throughout, so the mistake is unreachable there. Their
identically worded `ERR_COLLECTION_NOT_FOUND` is untouched, and the cross-port
`source-resolution-conformance` corpus pins error CODES, not message text.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DhpswkF1NvwxhFWMmdAT15

Author: dmealing

CHANGELOG.md

@@ -301,6 +301,55 @@ extracting the authored examples from shipped docs, skills and fixtures and load
 under a strict loader — is tracked separately; `meta upgrade`'s retirement map is already
 the natural source of truth for "what must no longer appear in an example".
 
+### Fixed — `meta docs metaobjects` sent you down a dead end, twice ([#344](https://github.com/metaobjectsdev/metaobjects/issues/344))
+
+**Nothing here is a regression, and the CLI was behaving as designed** — which is the
+point. The Node `meta docs` positional is the **project root**; the Python and C# `docs`
+positionals are the **metadata directory** (`metaobjects docs ./metadata`, `dotnet meta
+docs metaobjects`), and all three are spelled the same way in help text. The Node one was
+literally named `<metadata>`. So `meta docs metaobjects --out out` told Node "the project
+root is `./metaobjects`", which asks it to find a `metaobjects/metaobjects/`.
+
+It then reported *"no metadata sources declared … Declare `sources` in
+`.metaobjects/config.json`, or run `meta init` to scaffold"* — and **following that advice
+does not work either.** Declaring `"sources": ["metaobjects/meta.x.yaml"]` fails config-schema
+validation, because a `sources` entry is a tagged-union OBJECT (`{ "path": … }`), never a
+bare string. Two dead ends in a row for a caller whose only mistake was passing the
+directory a sibling port's `docs` wants. Reproduced on this repo's own unmodified
+`examples/advanced-modeling`.
+
+**The error now names the mistake.** `resolveCollection` fires the targeted diagnostic when
+the directory it resolved holds metadata but carries no `.metaobjects/config.json` — the
+only project marker there is — and points at the directory to pass instead:
+
+```
+<dir>/metaobjects looks like a metadata directory, not a project root — it holds metadata
+files but carries no .metaobjects/config.json. A directory argument here is the PROJECT
+ROOT that CONTAINS your metadata … Try <dir> instead.
+```
+
+**The discriminator is the document ROOT, not the file extension**, and that distinction is
+load-bearing: `package.json` and `tsconfig.json` carry a recognized metadata extension, so
+an extension test would misdiagnose every JS project root that has no metadata yet — a
+confidently wrong hint, which is worse than the generic one it replaces. A cheap sniff for
+`metadata.root` (canonical JSON) / a top-level `metadata:` (sigil-free YAML, ADR-0006)
+decides it, on the already-failing path only, and both arms are pinned. The generic message
+also gained the shape it was asking for: `"sources": [{ "path": "model" }]`.
+
+**The positional is renamed `[<project-root>]`** in `meta --help` and `meta docs --help`,
+along with `DocsFlags.metadata` → `projectRoot` — cosmetic, no behavioural change, but the
+explanatory sentence was already there and did not prevent the trap; the internal name is
+what kept regenerating the misleading word. The agent-context `metaobjects-codegen`
+references gained the cross-port note beside their own `docs` examples (the C# reference
+shipped `dotnet meta docs metaobjects`, the exact string that misleads on Node), and the
+`sources` entry shape — which appeared in **no** installed skill — is now in the TypeScript
+reference.
+
+**TypeScript-only, deliberately.** The sibling ports' directory arguments are metadata
+directories throughout, so the mistake is structurally unreachable there; their identically
+worded `ERR_COLLECTION_NOT_FOUND` is untouched. The cross-port `source-resolution-conformance`
+corpus pins error CODES, not message text, and the code is unchanged.
+
 ### Added — every shipped metadata example is now gated against the strict registry ([#337](https://github.com/metaobjectsdev/metaobjects/issues/337))
 
 **The same failure has now landed three times, and an adopter found it every time.** A doc

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

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.

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):

docs/features/metadata-sources.md

@@ -193,6 +193,30 @@ through to the default and quietly generate from a stale `metaobjects/`.
 were declared anywhere up the walk, **and** no default `metaobjects/` directory
 exists either.
 
+### Every directory argument is the PROJECT ROOT
+
+`--cwd`, and the `meta docs` positional, name the project root — the directory that
+**contains** your metadata. They are never the metadata directory itself; where the
+metadata lives is `sources`' answer, and pointing a command at `metaobjects/` asks it
+to find a `metaobjects/metaobjects/`.
+
+That is worth stating because the mistake is predictable rather than careless: the
+**Python and C# `docs` positionals ARE the metadata directory** (`metaobjects docs
+./metadata`, `dotnet meta docs metaobjects`), and each port spells its own the same
+way in help text. The Node CLI is the one every stack uses for `migrate`,
+`verify --db` and the neutral model docs, so the two conventions meet on one machine.
+
+```bash
+meta docs --out ./docs            # ✅ from the project root — the normal form
+meta docs ./apps/api --out ./docs # ✅ a project root elsewhere (SCOPES the run to it)
+meta docs metaobjects --out ./docs # ❌ that is the metadata directory
+```
+
+Pointed at a metadata directory, `ERR_COLLECTION_NOT_FOUND` now says so and names the
+directory to pass instead
+([#344](https://github.com/metaobjectsdev/metaobjects/issues/344)) — it used to advise
+declaring `sources`, which from inside the metadata directory leads nowhere.
+
 ---
 
 ## `scope` — an output filter over fully-qualified names

fixtures/agent-context-conformance/python/expected/.claude/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.

fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/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):

fixtures/agent-context-conformance/ts-requirements/expected/.claude/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):

server/typescript/packages/cli/src/commands/docs.ts

@@ -1,4 +1,4 @@
-// `meta docs <metadata> --out <dir>` — STANDALONE neutral metadata docs.
+// `meta docs [<project-root>] --out <dir>` — STANDALONE neutral metadata docs.
 //
 // Emits one neutral page per entity (`<Entity>.md`) and one per
 // `template.output` (`<Template>.md`) from metadata ALONE — no gen config, no
@@ -39,16 +39,20 @@ import { generateSite, SITE_TEMPLATE_NAMES, SITE_ASSET_NAMES, readSiteFile } fro
 type DocsLayout = "flat" | "package";
 
 interface DocsFlags {
-  /** Project root holding `metaobjects/` (the metadata to document). */
-  metadata: string;
+  /** The PROJECT ROOT to resolve metadata from — the directory that CONTAINS
+   *  the metadata, never the metadata directory itself (#344). Named for what
+   *  it is: while it was called `metadata` the help text spelled the positional
+   *  `<metadata>`, which is what the Python and C# `docs` positionals actually
+   *  mean, and pointing this one at `metaobjects/` fails. */
+  projectRoot: string;
   /** Output directory for the rendered pages. */
   out: string;
   /** Page-placement layout. `flat` (default) writes `<Name>.md` at the out
    *  root; `package` folds pages under package-path subdirs (collision-proof
    *  for multi-package models with repeated short names). */
   layout: DocsLayout;
   /** Optional override for the project root used to resolve adopter
-   *  `templates/` overrides. Defaults to the metadata root. */
+   *  `templates/` overrides. Defaults to the project root. */
   templates?: string;
   /** Optional directory holding the prompt `.mustache` sources, for a project
    *  whose templates live outside the conventional `metaobjects/` or `templates/`
@@ -66,12 +70,12 @@ interface DocsFlags {
   outProvided: boolean;
   /** Whether `--layout` was explicitly passed (same override semantics). */
   layoutProvided: boolean;
-  /** Whether the `<metadata>` positional was explicitly passed. An explicit path
+  /** Whether the `<project-root>` positional was explicitly passed. An explicit path
    *  DEFINES the source set (`resolveCollection`'s `explicitDir` pin); the default
    *  cwd discovers one by walking up. Without this distinction the two are
    *  indistinguishable at the call site, which is how an explicitly-scoped run came
    *  to have an ancestor config's sources unioned into it (#327). */
-  metadataProvided: boolean;
+  projectRootProvided: boolean;
   /** FR-033 S3 — document the METAMODEL ITSELF (the built-in type/subtype/attr
    *  vocabulary) instead of a user's entities. Needs NO metadata + NO config. */
   metamodel: boolean;
@@ -93,7 +97,7 @@ function parseLayout(v: string | undefined, flag: string): DocsLayout {
 }
 
 function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
-  let metadata: string | undefined;
+  let projectRoot: string | undefined;
   let out: string | undefined;
   let templates: string | undefined;
   let prompts: string | undefined;
@@ -155,8 +159,8 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
       prompts = a.slice("--prompts=".length);
     } else if (a.startsWith("-")) {
       throw new Error(`unknown flag: ${a}`);
-    } else if (metadata === undefined) {
-      metadata = a;
+    } else if (projectRoot === undefined) {
+      projectRoot = a;
     } else {
       throw new Error(`unexpected argument: ${a}`);
     }
@@ -172,11 +176,11 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   if (wantApi) surfaces.push("api");
   if (wantRequirements) surfaces.push("requirements");
   return {
-    // `<metadata>` is the project root that contains metaobjects/; default cwd
-    // (mirrors how migrate/gen treat the working directory as the root).
-    metadata: metadata ?? cwd,
-    metadataProvided: metadata !== undefined,
-    // Default out dir, resolved against the metadata root below. In --metamodel
+    // `<project-root>` is the project root that CONTAINS the metadata; default
+    // cwd (mirrors how migrate/gen treat the working directory as the root).
+    projectRoot: projectRoot ?? cwd,
+    projectRootProvided: projectRoot !== undefined,
+    // Default out dir, resolved against the project root below. In --metamodel
     // mode the renderer writes under <out>/metamodel/, default ./docs/metamodel.
     out: out ?? (wantMetamodel ? "./docs/metamodel" : "./docs"),
     // Default flat preserves today's single-package output (+ existing goldens).
@@ -210,7 +214,7 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     return metamodelDocsCommand(cwd, flags.out);
   }
 
-  const metaRoot = resolvePath(cwd, flags.metadata);
+  const metaRoot = resolvePath(cwd, flags.projectRoot);
   // Absolute prompt-source dir for the site (--prompts), for a project whose
   // templates live outside metaobjects/ or templates/ (e.g. data/templates/).
   const promptsDir = flags.prompts !== undefined ? resolvePath(cwd, flags.prompts) : undefined;
@@ -238,11 +242,11 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // everything project-relative — `metaobjects.config.ts` and its providers,
   // the `docs.outDir` it names, the adopter `templates/` overrides, the owned
   // `codegen/docs-site/` theme — has to come from that same directory. Reading
-  // the config from the ambient `<metadata>` argument while the metadata came
+  // the config from the ambient `<project-root>` argument while the metadata came
   // from an ancestor renders the ancestor's model with the subdirectory's
   // (absent) providers. For a run at the project root the two are the same path.
   //
-  // An EXPLICIT `<metadata>` positional pins the collection rather than seeding a
+  // An EXPLICIT `<project-root>` positional pins the collection rather than seeding a
   // walk (#327). The argument has always meant "document this": before sources were
   // resolvable it read `<path>/metaobjects/` and nothing else, and passing it to
   // discovery turned it into a starting point, so the nearest ancestor
@@ -255,7 +259,7 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   try {
     collection = await resolveCollection(
       metaRoot,
-      flags.metadataProvided ? { explicitDir: metaRoot } : undefined,
+      flags.projectRootProvided ? { explicitDir: metaRoot } : undefined,
     );
   } catch (err) {
     log.error(`docs: ${(err as Error).message}`);