@@ -105,6 +105,7 @@ for editor autocomplete and non-Python validation.
 metadata: metaobjects            # optional, default "metaobjects" — relative to this file
 providers:                       # optional; "module:symbol" refs, resolved config-relative (no PYTHONPATH=)
   - my_project.providers:register_custom_types
+libraries: [ai]                  # optional; MetaObjects-shipped library packages (see below)
 targets:
   api:
     outDir: src/generated/api
@@ -142,6 +143,44 @@ targets:
   consulted. Config mode activates only when no positional `<metadata_dir>`
   is given.
 
+## `libraries` — opting into a MetaObjects-shipped library package
+
+MetaObjects ships a small set of standard metadata packages under `library/`. A project
+opts into one by name, and its nodes become available to `extends`:
+
+```ts
+// metaobjects.config.ts  (Node `meta`)
+export default defineConfig({
+  libraries: ["ai"],             // makes metaobjects::ai::LlmCallBase resolvable
+  generators: [entityFile()],
+});
+```
+
+```yaml
+# metaobjects.config.yaml  (Python `metaobjects`)
+libraries: [ai]
+```
+
+```jsonc
+// then, in your own metadata
+{ "object.entity": { "name": "AgentCall", "extends": "metaobjects::ai::LlmCallBase", ... } }
+```
+
+- **Opt-in, never automatic.** A library package registers real top-level nodes. A project
+  that never references one should not find them in its model, its generated output or its
+  docs — so nothing is loaded until the key names it.
+- **An unknown name is a hard config error** that lists the packages this version ships.
+  The programmatic loader API skips an unrecognised package instead, deliberately: an API
+  caller asking for something a given version does not ship should still be able to load
+  its own metadata, but a name a human typed into a config file is a mistake worth failing
+  on — skipped, it resurfaces later as `ERR_UNRESOLVED_SUPER` pointing at the adopter's own
+  metadata, which is the wrong place to send someone looking.
+- **Every command that loads metadata honours it** — `gen`, `verify`, `docs`, `migrate`,
+  `prompt-snapshot`. It was previously reachable only from the programmatic
+  `MetaDataLoader.fromDirectory`, which no CLI uses, so a generator that consumes a library
+  was registered *for* the command line while its input was unreachable *through* it
+  ([#333](https://github.com/metaobjectsdev/metaobjects/issues/333)).
+
 ## `meta gen` / `meta verify` run an advisory anti-pattern pass (Node `meta`)
 
 Both `meta verify` and a real `meta gen` write run (not `--dry-run`) end with a
 
@@ -14,7 +14,7 @@
 import { resolve as resolvePath, basename } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { log } from "../lib/log.js";
-import { loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -284,6 +284,10 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // if the metadata genuinely uses an unregistered type.
   let loadedConfig: Awaited<ReturnType<typeof loadMetaobjectsConfig>> | undefined;
   let configProviders: NonNullable<Awaited<ReturnType<typeof loadMetaobjectsConfig>>["providers"]> | undefined;
+  // The same config's contributions to the metadata LOAD — providers plus the shipped
+  // `libraries` a project opts into (#333). `configProviders` stays separate because the
+  // site surface has its own loader and takes providers alone.
+  let configLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   // hasConfig gates the api surface: api docs describe the GENERATED REST
   // surface, which only exists when there is a (loadable) gen config. A config
   // that EXISTS but fails to load degrades to model-only with a warning.
@@ -297,13 +301,15 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     try {
       loadedConfig = await loadMetaobjectsConfig(genConfigDir);
       configProviders = loadedConfig.providers;
+      configLoadOptions = loadMemoryOptionsFrom(loadedConfig);
     } catch (err) {
       log.warn(
         `docs: metaobjects.config.ts failed to load (${(err as Error).message}); ` +
           `generating docs without its providers`,
       );
       loadedConfig = undefined;
       configProviders = undefined;
+      configLoadOptions = {};
     }
   }
 
@@ -347,7 +353,7 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   try {
     root = await loadMemory(collection.configDir, {
       files: collection.files,
-      ...(configProviders !== undefined ? { providers: configProviders } : {}),
+      ...configLoadOptions,
     });
   } catch (err) {
     log.error(`docs: failed to load metadata: ${(err as Error).message}`);
 
@@ -1,7 +1,7 @@
 import { relative } from "node:path";
 import { parseGenArgs } from "../lib/args.js";
 import { resolveGenConfig } from "../lib/config.js";
-import { loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { formatGenResult, formatGenResultToon, type GenFileEntry, type GenFileStatus } from "../lib/output.js";
 import { formatGenResultJson } from "../lib/output-json.js";
 import type { OutputFormat } from "../lib/format.js";
@@ -99,7 +99,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   try {
     metadata = await loadMemory(collection.configDir, {
       files: collection.files,
-      ...(forgeConfig.providers !== undefined ? { providers: forgeConfig.providers } : {}),
+      ...loadMemoryOptionsFrom(forgeConfig),
     });
   } catch (err) {
     log.error(`failed to load metadata: ${(err as Error).message}`);
 
@@ -12,7 +12,7 @@ import { toonEncode } from "../lib/format.js";
 import { buildKyselyFromUrl, redactUrl } from "../lib/kysely.js";
 import { log } from "../lib/log.js";
 import { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
-import { loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
 import {
   buildExpectedSchemaWithProvenance,
@@ -601,12 +601,11 @@ export async function migrateCommand(
   // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
   // providers. migrate's postgres/sqlite path also reads the config later
   // for columnNamingStrategy; we load it once here and reuse below.
-  let postgresConfigProviders: readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[] | undefined;
+  let postgresLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   try {
-    const forgeConfig = await loadMetaobjectsConfig(genRoot);
-    postgresConfigProviders = forgeConfig.providers;
+    postgresLoadOptions = loadMemoryOptionsFrom(await loadMetaobjectsConfig(genRoot));
   } catch {
-    postgresConfigProviders = undefined;
+    postgresLoadOptions = {};
   }
 
   // Discovery and load are two separate failure modes, kept in separate try blocks
@@ -626,7 +625,7 @@ export async function migrateCommand(
   try {
     metadata = await loadMemory(collection.configDir, {
       files: collection.files,
-      ...(postgresConfigProviders !== undefined ? { providers: postgresConfigProviders } : {}),
+      ...postgresLoadOptions,
     });
   } catch (err) {
     log.error(`failed to load metadata: ${(err as Error).message}`);
@@ -1029,19 +1028,17 @@ export async function runBaseline(
       `your metadata; for a new/empty database run \`${greenfieldCreateCmd(config.dialect)}\` instead.`,
     );
     let metadata;
-    // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers
+    // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers/libraries
     // and the columnNamingStrategy — mirroring the DB path (and `meta gen`) so
     // offline baseline resolves config-registered custom subtypes too (#157).
-    let baselineConfigProviders:
-      | readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[]
-      | undefined;
+    let baselineLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
     let baselineStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
     try {
       const cfg = await loadMetaobjectsConfig(genRoot);
-      baselineConfigProviders = cfg.providers;
+      baselineLoadOptions = loadMemoryOptionsFrom(cfg);
       if (cfg.columnNamingStrategy) baselineStrategy = cfg.columnNamingStrategy;
     } catch {
-      // config absent — no custom providers, default snake_case
+      // config absent — no custom providers, no libraries, default snake_case
     }
     // `baseline` records a STARTING POINT, so it is deliberately NOT scoped: the
     // `--from-db` arm captures whatever the database holds (there is no provenance
@@ -1056,7 +1053,7 @@ export async function runBaseline(
       const collection = await resolveCollection(metaRoot);
       metadata = await loadMemory(collection.configDir, {
         files: collection.files,
-        ...(baselineConfigProviders !== undefined ? { providers: baselineConfigProviders } : {}),
+        ...baselineLoadOptions,
       });
     } catch (err) {
       log.error(`migrate baseline: failed to load metadata: ${(err as Error).message}`);
@@ -1176,19 +1173,17 @@ export async function runOfflineGenerate(
     log.error(`migrate: --dialect required for offline generation (or use --from-db)`);
     return 2;
   }
-  // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers
+  // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers/libraries
   // and the columnNamingStrategy — mirroring the DB path (and `meta gen`) so
   // offline generate resolves config-registered custom subtypes too (#157).
-  let offlineConfigProviders:
-    | readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[]
-    | undefined;
+  let offlineLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   let offlineStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
   try {
     const cfg = await loadMetaobjectsConfig(genRoot);
-    offlineConfigProviders = cfg.providers;
+    offlineLoadOptions = loadMemoryOptionsFrom(cfg);
     if (cfg.columnNamingStrategy) offlineStrategy = cfg.columnNamingStrategy;
   } catch {
-    // config absent — no custom providers, default snake_case
+    // config absent — no custom providers, no libraries, default snake_case
   }
 
   let metadata;
@@ -1197,7 +1192,7 @@ export async function runOfflineGenerate(
     collection = await resolveCollection(metaRoot);
     metadata = await loadMemory(collection.configDir, {
       files: collection.files,
-      ...(offlineConfigProviders !== undefined ? { providers: offlineConfigProviders } : {}),
+      ...offlineLoadOptions,
     });
   } catch (err) {
     log.error(`migrate: failed to load metadata: ${(err as Error).message}`);
@@ -1440,12 +1435,11 @@ async function runD1Migrate(
 
   // 3. Load metadata. Best-effort config read for consumer providers; falls
   //    back to default core+forge bundle if metaobjects.config.ts is absent.
-  let d1ConfigProviders: readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[] | undefined;
+  let d1LoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   try {
-    const forgeConfig = await loadMetaobjectsConfig(genRoot);
-    d1ConfigProviders = forgeConfig.providers;
+    d1LoadOptions = loadMemoryOptionsFrom(await loadMetaobjectsConfig(genRoot));
   } catch {
-    d1ConfigProviders = undefined;
+    d1LoadOptions = {};
   }
 
   // Discovery and load are separate failure modes (the `meta gen` pattern);
@@ -1463,7 +1457,7 @@ async function runD1Migrate(
   try {
     metadata = await loadMemory(collection.configDir, {
       files: collection.files,
-      ...(d1ConfigProviders !== undefined ? { providers: d1ConfigProviders } : {}),
+      ...d1LoadOptions,
     });
   } catch (err) {
     log.error(`migrate: failed to load metadata: ${(err as Error).message}`);
 
@@ -14,7 +14,7 @@ import { parsePromptSnapshotArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { snapshotPaths, unifiedDiff } from "../lib/snapshot.js";
-import { loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { TYPE_TEMPLATE, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
 import { render, ESCAPERS, type RenderFormat } from "@metaobjectsdev/render";
@@ -53,28 +53,29 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
   // invocation that worked before metadata sources were resolvable at all.
   const projectRoot = collection.configDir;
 
-  // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
-  // providers. prompt-snapshot doesn't require codegen config; if it's absent
+  // Best-effort load of metaobjects.config.ts to pick up consumer-supplied providers
+  // and shipped `libraries`. prompt-snapshot doesn't require codegen config; if it's absent
   // or invalid, fall back to defaults — the loader still works for any
   // metadata that only uses core+forge subtypes.
-  let configProviders: NonNullable<Awaited<ReturnType<typeof loadMetaobjectsConfig>>["providers"]> | undefined;
+  let configLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   try {
     // `metaobjects.config.ts` gets its own nearest-ancestor walk, not `projectRoot`:
     // it answers a different question from `.metaobjects/config.json` (design §4.6)
     // and in a Maven- or pip-rooted monorepo the two legitimately sit in different
     // directories, so reading it from the collection's would silently drop this
     // package's providers (#326). Same path whenever the two files sit together.
-    const forgeConfig = await loadMetaobjectsConfig(resolveGenConfigDir(cwd, projectRoot));
-    configProviders = forgeConfig.providers;
+    configLoadOptions = loadMemoryOptionsFrom(
+      await loadMetaobjectsConfig(resolveGenConfigDir(cwd, projectRoot)),
+    );
   } catch {
-    configProviders = undefined;
+    configLoadOptions = {};
   }
 
   let root;
   try {
     root = await loadMemory(collection.configDir, {
       files: collection.files,
-      ...(configProviders !== undefined ? { providers: configProviders } : {}),
+      ...configLoadOptions,
     });
   } catch (err) {
     log.error(`failed to load metadata: ${(err as Error).message}`);
 
@@ -15,7 +15,7 @@ import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
-import { loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { computeCodegenDrift } from "../lib/codegen-drift.js";
 import { checkRequirements, summariseRequirements } from "../lib/requirement-check.js";
 import { checkVerifiedBy } from "../lib/verified-by-scan.js";
@@ -204,15 +204,18 @@ export async function verifyCommand(
   } catch {
     forgeConfig = undefined;
   }
-  const configProviders = forgeConfig?.providers;
+  // Both of the gen config's contributions to the load, together — see
+  // `loadMemoryOptionsFrom`. Threading `providers` and forgetting `libraries` is how
+  // a shipped library became unloadable through the CLI (#333).
+  const configLoadOptions = loadMemoryOptionsFrom(forgeConfig);
 
   // ADR-0023 strict-by-default (#96): verify loads strict unless --lax is passed,
   // so an undeclared/typo'd own @attr fails verify (matching Java's Maven goal).
   let root: Awaited<ReturnType<typeof loadMemory>>;
   try {
     root = await loadMemory(collection.configDir, {
       files: collection.files,
-      ...(configProviders !== undefined ? { providers: configProviders } : {}),
+      ...configLoadOptions,
       strict: !flags.lax,
     });
   } catch (err) {
 
@@ -41,9 +41,7 @@ EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
 DOCS FLAGS:
-  <metadata>            Project root to resolve metadata from. Passing it SCOPES the run to
-                        that directory's own sources; no ancestor .metaobjects/config.json is
-                        consulted. Omitted (default), the project is discovered by walking up.
+  <metadata>            Project root to resolve metadata from; passing it SCOPES the run (default: cwd)
   --out <dir>, -o       Output directory for the pages (default: ./docs)
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
   --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)