@hawkeyexl/manni 0.1.0 → 0.3.0

package/dist/{chunk-Y6FSY35O.js → chunk-7M2YOXVG.js}

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@hawkeyexl/manni",
-  version: "0.1.0",
+  version: "0.3.0",
   description: "One command line for documentation that is meant to be checked. `manni meta` validates the presence and format of document metadata (Markdown frontmatter and more) against JSON Schema, built for CI. Formerly docmeta.",
   type: "module",
   bin: {
@@ -78,6 +78,7 @@ var package_default = {
     esbuild: "^0.28.2"
   },
   dependencies: {
+    "@axe-core/playwright": "^4.13.0",
     "@hawkeyexl/inference": "^0.3.1",
     "@xmldom/xmldom": "^0.9.12",
     ajv: "^8.17.1",
@@ -88,6 +89,7 @@ var package_default = {
     parse5: "^8.0.1",
     picocolors: "^1.1.1",
     picomatch: "^4.0.7",
+    "playwright-core": "^1.63.0",
     "smol-toml": "^1.8.0",
     yaml: "^2.6.1"
   },
@@ -152,8 +154,8 @@ var RENAME_ATTEMPTS = 3;
 function errorCode(err) {
   return typeof err === "object" && err !== null && "code" in err ? String(err.code) : void 0;
 }
-var wait = (ms) => new Promise((resolve12) => {
-  setTimeout(resolve12, ms);
+var wait = (ms) => new Promise((resolve14) => {
+  setTimeout(resolve14, ms);
 });
 async function writeFileAtomic(path, contents) {
   const tmp = join(
@@ -2609,11 +2611,17 @@ var BUILTINS = /* @__PURE__ */ new Map([
   ["anthropic:claude-subagent:2.1", __default23]
 ]);
 function assertPublishableBuiltinId(id) {
-  if (id.split(":")[0] === "check") {
+  const first = id.split(":")[0];
+  if (first === "check") {
     throw new Error(
       `Built-in id "${id}" is not publishable: the "check" first segment is reserved for corpus check identities (check:<name>, proposal 0026).`
     );
   }
+  if (first === "sidecar") {
+    throw new Error(
+      `Built-in id "${id}" is not publishable: the "sidecar" first segment is reserved for sidecar finding identities (sidecar:owned, proposal 0037).`
+    );
+  }
 }
 for (const id of BUILTINS.keys()) assertPublishableBuiltinId(id);
 function listBuiltins() {
@@ -2741,8 +2749,8 @@ var SCHEMA_KEYS = [
   "multipleOf"
 ];
 var RETRY_DELAY_MS = 500;
-var wait2 = (ms) => new Promise((resolve12) => {
-  setTimeout(resolve12, ms);
+var wait2 = (ms) => new Promise((resolve14) => {
+  setTimeout(resolve14, ms);
 });
 var RetryableFetchError = class extends DocmetaError {
 };
@@ -2994,6 +3002,277 @@ async function loadSchema(ref, options = {}) {
   }
 }
 
+// src/meta/core/resolve-schema.ts
+import { isAbsolute, relative, resolve } from "node:path";
+import picomatch from "picomatch";
+var DEFAULT_SCHEMAS = Object.freeze([
+  "google:okf:0.1",
+  "passo-uno:seven-action:1.0"
+]);
+var FILE_SCHEMA_KEY = "$schema";
+function schemaEntryRef(entry) {
+  return typeof entry === "string" ? entry : entry.ref;
+}
+function collectSchemaPins(config) {
+  const pins = /* @__PURE__ */ new Map();
+  for (const entry of config?.schemas ?? []) {
+    if (typeof entry === "string") continue;
+    if (entry.source === void 0 && entry.integrity === void 0) continue;
+    pins.set(entry.ref, {
+      ...entry.source !== void 0 ? { source: entry.source } : {},
+      ...entry.integrity !== void 0 ? { integrity: entry.integrity } : {}
+    });
+  }
+  return pins;
+}
+function rebaseConfigSchemaRefs(config, configDir, cwd) {
+  if (resolve(configDir) === resolve(cwd)) return config;
+  const rebase = (ref) => classifyRef(ref).kind === "file" && !isAbsolute(ref) ? resolve(configDir, ref) : ref;
+  const rebaseEntry = (entry) => typeof entry === "string" ? rebase(entry) : {
+    ...entry,
+    ref: rebase(entry.ref),
+    ...entry.source !== void 0 ? { source: rebase(entry.source) } : {}
+  };
+  return {
+    ...config,
+    ...config.schemas ? { schemas: config.schemas.map(rebaseEntry) } : {},
+    ...config.overrides ? {
+      overrides: config.overrides.map((o) => ({
+        ...o,
+        schemas: o.schemas.map(rebase)
+      }))
+    } : {}
+  };
+}
+var matcherCache = /* @__PURE__ */ new Map();
+function overrideGlobs(files) {
+  return typeof files === "string" ? [files] : files;
+}
+function matchesFileGlob(glob, filePath) {
+  return matches(glob, filePath);
+}
+function matches(glob, filePath) {
+  const key = JSON.stringify(glob);
+  let m = matcherCache.get(key);
+  if (!m) {
+    m = picomatch(glob, { dot: true });
+    matcherCache.set(key, m);
+  }
+  return m(filePath.replace(/\\/g, "/"));
+}
+function coerceFileSchema(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    return value;
+  }
+  throw new Error(
+    `Invalid "${FILE_SCHEMA_KEY}": must be a string or a list of strings.`
+  );
+}
+function dedupe(refs) {
+  return [...new Set(refs)];
+}
+function hostAllowed(url, hosts) {
+  const hostname = url.hostname.toLowerCase();
+  const host = url.host.toLowerCase();
+  return hosts.some((h) => {
+    const want = h.trim().toLowerCase();
+    return want === hostname || want === host;
+  });
+}
+function assertDocumentRefAllowed(ref, mode, params) {
+  const { kind } = classifyRef(ref);
+  if (kind === "builtin" || isPublishedBuiltinUrl(ref)) return;
+  if (kind === "url") {
+    if (mode === "local") {
+      throw new DocmetaError(
+        `Refusing the "${FILE_SCHEMA_KEY}" URL "${ref}": schemaTrust.documentRefs is "local", so a document may name a built-in id or a schema file inside the repository, but not a URL. Vendor it with \`manni meta schemas vendor ${ref}\` and reference the local copy, or put the URL in \`schemas:\` where an operator controls it.`
+      );
+    }
+    const hosts = params.config?.schemaTrust?.hosts;
+    if (!hosts || hosts.length === 0) return;
+    let url;
+    try {
+      url = new URL(ref);
+    } catch {
+      throw new DocmetaError(
+        `Refusing the "${FILE_SCHEMA_KEY}" URL "${ref}": it cannot be parsed as a URL, so it cannot be checked against schemaTrust.hosts.`
+      );
+    }
+    if (!hostAllowed(url, hosts)) {
+      throw new DocmetaError(
+        `Refusing the "${FILE_SCHEMA_KEY}" URL "${ref}": host "${url.host}" is not in schemaTrust.hosts (${hosts.join(", ")}). Add the host there, or reference a schema the config already names.`
+      );
+    }
+    return;
+  }
+  const root = params.trustRoot;
+  if (!root) return;
+  const abs = resolve(params.fileBase ?? process.cwd(), ref);
+  const within = relative(root.dir, abs);
+  if (within !== "" && !within.startsWith("..") && !isAbsolute(within)) return;
+  const boundary = root.source === "git" ? `the repository root (${root.dir})` : root.source === "config" ? `${root.dir} \u2014 no git repository was found, so the config file's own directory is the boundary` : `${root.dir} \u2014 no git repository and no config file were found, so the directory the command was run from is the boundary`;
+  const scope = root.source === "git" ? "the repository" : "the project";
+  throw new DocmetaError(
+    `Refusing the "${FILE_SCHEMA_KEY}" path "${ref}": it resolves outside ${boundary}. A document may only name a schema inside ${scope}; a path in \`schemas:\` or on \`--schema\` is not restricted this way.`
+  );
+}
+function resolveSchemaSetWithSource(params) {
+  const { filePath, fileSchema, cliSchemas, config } = params;
+  if (cliSchemas && cliSchemas.length > 0) {
+    return { schemas: dedupe(cliSchemas), source: "cli" };
+  }
+  const fromFile = coerceFileSchema(fileSchema);
+  if (fromFile && fromFile.length > 0) {
+    const mode = config?.schemaTrust?.documentRefs ?? "any";
+    if (mode === "none") {
+      params.onNotice?.(
+        `${filePath}: "${FILE_SCHEMA_KEY}" is ignored (${fromFile.join(", ")}) \u2014 schemaTrust.documentRefs is "none", so the schema set comes from the config instead. Remove the key from the document, or set schemaTrust.documentRefs to "local" or "any" to honor it.`
+      );
+    } else {
+      for (const ref of fromFile) assertDocumentRefAllowed(ref, mode, params);
+      return { schemas: dedupe(fromFile), source: "document" };
+    }
+  }
+  if (config?.overrides) {
+    for (const [i, ov] of config.overrides.entries()) {
+      if (matches(ov.files, filePath) && ov.schemas.length > 0) {
+        return { schemas: dedupe(ov.schemas), source: "override", overrideIndex: i };
+      }
+    }
+  }
+  if (config?.schemas && config.schemas.length > 0) {
+    return {
+      schemas: dedupe(config.schemas.map(schemaEntryRef)),
+      source: "config"
+    };
+  }
+  return { schemas: [...DEFAULT_SCHEMAS], source: "default" };
+}
+function resolveSchemaSet(params) {
+  return resolveSchemaSetWithSource(params).schemas;
+}
+function resolveElements(filePath, config) {
+  const out = [];
+  if (config?.elements) out.push(...config.elements);
+  for (const ov of config?.overrides ?? []) {
+    if (ov.elements && matches(ov.files, filePath)) out.push(...ov.elements);
+  }
+  return dedupe(out);
+}
+
+// src/meta/core/sidecar-fetch.ts
+var SIDECAR_FETCH_TIMEOUT_MS = 1e4;
+var SIDECAR_FETCH_MAX_BYTES = 5 * 1024 * 1024;
+var MAX_REDIRECTS = 5;
+var RETRY_DELAY_MS2 = 500;
+function sidecarUrlProblem(url) {
+  let parsed2;
+  try {
+    parsed2 = new URL(url);
+  } catch {
+    return "is not a valid URL";
+  }
+  if (parsed2.username !== "" || parsed2.password !== "") {
+    return 'carries a credential in the URL; put the token in an environment variable and name it with "tokenEnv"';
+  }
+  if (parsed2.protocol === "https:") return null;
+  if (parsed2.protocol === "http:" && isLoopback(parsed2.hostname)) return null;
+  if (parsed2.protocol === "http:") {
+    return "is plain http://; a bearer token over plaintext is a leak, and a public manifest is served over https too";
+  }
+  return `has the unsupported scheme "${parsed2.protocol}"`;
+}
+function isLoopback(host) {
+  return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1" || host.startsWith("127.");
+}
+async function fetchSidecar(url, opts = {}) {
+  if (opts.offline) {
+    throw new DocmetaError(
+      `Sidecar manifest ${url} is remote and the run is offline. Vendor it to a path, or drop --offline.`
+    );
+  }
+  const timeoutMs = opts.timeoutMs ?? SIDECAR_FETCH_TIMEOUT_MS;
+  const maxBytes = opts.maxBytes ?? SIDECAR_FETCH_MAX_BYTES;
+  const env = opts.env ?? process.env;
+  let token;
+  if (opts.tokenEnv !== void 0) {
+    token = env[opts.tokenEnv];
+    if (token === void 0 || token === "") {
+      throw new DocmetaError(
+        `Sidecar manifest ${url}: the environment variable ${opts.tokenEnv} named by "tokenEnv" is not set.`
+      );
+    }
+  }
+  let res = await requestWithRedirects(url, token, timeoutMs);
+  if (res instanceof Error || res.status >= 500) {
+    await new Promise((r) => setTimeout(r, RETRY_DELAY_MS2));
+    res = await requestWithRedirects(url, token, timeoutMs);
+  }
+  if (res instanceof Error) {
+    throw new DocmetaError(
+      `Sidecar manifest ${url} could not be fetched: ${res.message}`
+    );
+  }
+  if (!res.ok) {
+    const hint = res.status === 404 && token === void 0 ? ' (a private file answers 404 without a token; set "tokenEnv")' : res.status === 404 ? " (a private file answers 404 without a valid token)" : "";
+    throw new DocmetaError(
+      `Sidecar manifest ${url} could not be fetched: HTTP ${res.status}${hint}.`
+    );
+  }
+  return readCapped(url, res, maxBytes);
+}
+async function requestWithRedirects(url, token, timeoutMs) {
+  const origin = new URL(url).origin;
+  let current = url;
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const sameOrigin = new URL(current).origin === origin;
+    const headers = { accept: "text/plain, application/x-yaml, */*" };
+    if (token !== void 0 && sameOrigin) headers.authorization = `Bearer ${token}`;
+    let res;
+    try {
+      res = await fetch(current, {
+        headers,
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (err) {
+      const isAbort2 = err instanceof Error && err.name === "TimeoutError";
+      return isAbort2 ? new Error(`timed out after ${timeoutMs}ms`) : new Error(err instanceof Error ? err.message : String(err));
+    }
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      if (location === null) return res;
+      await res.body?.cancel();
+      current = new URL(location, current).toString();
+      continue;
+    }
+    return res;
+  }
+  return new Error(`more than ${MAX_REDIRECTS} redirects`);
+}
+async function readCapped(url, res, maxBytes) {
+  const body = res.body;
+  if (!body) return "";
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done || value === void 0) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new DocmetaError(
+        `Sidecar manifest ${url} is too large: the response exceeds the ${maxBytes}-byte limit.`
+      );
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
 // src/meta/extractors/frontmatter.ts
 import { parseDocument, LineCounter, isMap, isSeq, isScalar } from "yaml";
 import { parse as parseToml } from "smol-toml";
@@ -3753,8 +4032,8 @@ function ditaShape(content, root, filePath) {
   const lower = filePath?.toLowerCase() ?? "";
   const byExtension2 = (lower.endsWith(".dita") || lower.endsWith(".ditamap")) && DITA_ROOTS.has(name2);
   if (!byDoctype && !byClass && !byArch && !byExtension2) return void 0;
-  const isMap4 = /^\s*[-+]\s+map\//.test(cls) || MAP_ROOTS.has(name2) || lower.endsWith(".ditamap");
-  return isMap4 ? { kind: "map", container: "topicmeta", preamble: /* @__PURE__ */ new Set(["title"]) } : {
+  const isMap5 = /^\s*[-+]\s+map\//.test(cls) || MAP_ROOTS.has(name2) || lower.endsWith(".ditamap");
+  return isMap5 ? { kind: "map", container: "topicmeta", preamble: /* @__PURE__ */ new Set(["title"]) } : {
     kind: "topic",
     container: "metadata",
     preamble: /* @__PURE__ */ new Set([
@@ -5179,202 +5458,477 @@ function listFormats() {
   }));
 }
 
-// src/meta/core/resolve-schema.ts
-import { isAbsolute, relative, resolve } from "node:path";
-import picomatch from "picomatch";
-var DEFAULT_SCHEMAS = Object.freeze([
-  "google:okf:0.1",
-  "passo-uno:seven-action:1.0"
-]);
-var FILE_SCHEMA_KEY = "$schema";
-function schemaEntryRef(entry) {
-  return typeof entry === "string" ? entry : entry.ref;
-}
-function collectSchemaPins(config) {
-  const pins = /* @__PURE__ */ new Map();
-  for (const entry of config?.schemas ?? []) {
-    if (typeof entry === "string") continue;
-    if (entry.source === void 0 && entry.integrity === void 0) continue;
-    pins.set(entry.ref, {
-      ...entry.source !== void 0 ? { source: entry.source } : {},
-      ...entry.integrity !== void 0 ? { integrity: entry.integrity } : {}
-    });
+// src/meta/core/sidecars.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { isAbsolute as isAbsolute2, relative as relative4, resolve as resolve5, sep as sep2 } from "node:path";
+import {
+  LineCounter as LineCounter2,
+  isMap as isMap3,
+  isNode,
+  isScalar as isScalar2,
+  parseDocument as parseDocument3
+} from "yaml";
+
+// src/meta/core/load-files.ts
+import { stat as stat3 } from "node:fs/promises";
+import { extname, relative as relative3, resolve as resolve4 } from "node:path";
+import fg from "fast-glob";
+import picomatch2 from "picomatch";
+
+// src/meta/core/gitignore.ts
+import { spawn } from "node:child_process";
+import { dirname as dirname3, relative as relative2, resolve as resolve3, sep } from "node:path";
+
+// src/shared/git-root.ts
+import { existsSync } from "node:fs";
+import { dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
+function findGitRoot(cwd) {
+  let dir = resolve2(cwd);
+  for (; ; ) {
+    if (existsSync(join3(dir, ".git"))) return dir;
+    const parent = dirname2(dir);
+    if (parent === dir) return null;
+    dir = parent;
   }
-  return pins;
 }
-function rebaseConfigSchemaRefs(config, configDir, cwd) {
-  if (resolve(configDir) === resolve(cwd)) return config;
-  const rebase = (ref) => classifyRef(ref).kind === "file" && !isAbsolute(ref) ? resolve(configDir, ref) : ref;
-  const rebaseEntry = (entry) => typeof entry === "string" ? rebase(entry) : {
-    ...entry,
-    ref: rebase(entry.ref),
-    ...entry.source !== void 0 ? { source: rebase(entry.source) } : {}
-  };
+function searchPath(cwd) {
+  const start = resolve2(cwd);
+  const root = findGitRoot(start);
+  if (root === null) return [start];
+  const chain = [];
+  let dir = start;
+  for (; ; ) {
+    chain.push(dir);
+    if (dir === root) return chain;
+    const parent = dirname2(dir);
+    if (parent === dir) return chain;
+    dir = parent;
+  }
+}
+
+// src/meta/core/gitignore.ts
+var GITIGNORE_UNAVAILABLE = ".gitignore filtering was requested but git could not answer here (no repository, or no git on PATH); no files were skipped.";
+var unavailable = () => ({
+  ignored: /* @__PURE__ */ new Set(),
+  available: false
+});
+async function gitIgnored(paths, cwd) {
+  if (paths.length === 0) {
+    return { ignored: /* @__PURE__ */ new Set(), available: true };
+  }
+  const rootOf = /* @__PURE__ */ new Map();
+  const byRoot = /* @__PURE__ */ new Map();
+  let inSomeRepo = false;
+  for (const spelled of paths) {
+    const abs = resolve3(cwd, spelled);
+    const dir = dirname3(abs);
+    let root = rootOf.get(dir);
+    if (root === void 0) {
+      root = findGitRoot(dir);
+      rootOf.set(dir, root);
+    }
+    if (root === null) continue;
+    inSomeRepo = true;
+    const rel = relative2(root, abs).split(sep).join("/");
+    const bucket = byRoot.get(root);
+    if (bucket) bucket.push({ rel, spelled });
+    else byRoot.set(root, [{ rel, spelled }]);
+  }
+  if (!inSomeRepo) return unavailable();
+  const ignored = /* @__PURE__ */ new Set();
+  let answered = 0;
+  for (const [root, bucket] of byRoot) {
+    const answer = await checkIgnore(
+      bucket.map((b) => b.rel),
+      root
+    );
+    if (!answer.available) continue;
+    answered += 1;
+    for (const b of bucket) {
+      if (answer.ignored.has(b.rel)) ignored.add(b.spelled);
+    }
+  }
+  return answered > 0 ? { ignored, available: true } : unavailable();
+}
+function checkIgnore(paths, cwd) {
+  return new Promise((settle) => {
+    let done = false;
+    const finish = (answer) => {
+      if (done) return;
+      done = true;
+      settle(answer);
+    };
+    let child;
+    try {
+      child = spawn("git", ["check-ignore", "--stdin", "-z"], {
+        cwd,
+        windowsHide: true
+      });
+    } catch {
+      finish(unavailable());
+      return;
+    }
+    let out = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      out += chunk;
+    });
+    child.stderr.resume();
+    child.on("error", () => {
+      finish(unavailable());
+    });
+    child.stdin.on("error", () => {
+    });
+    child.on("close", (code) => {
+      if (code !== 0 && code !== 1) {
+        finish(unavailable());
+        return;
+      }
+      finish({
+        ignored: new Set(out.split("\0").filter((p) => p !== "")),
+        available: true
+      });
+    });
+    child.stdin.end(paths.join("\0"));
+  });
+}
+
+// src/meta/core/load-files.ts
+var DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**"];
+var STDIN_TOKEN = "-";
+var STDIN_LABEL = "<stdin>";
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+async function statOrNull(p) {
+  try {
+    return await stat3(p);
+  } catch {
+    return null;
+  }
+}
+function gitignoreOptions(opts) {
+  const asked = opts.flag === true || opts.flag === void 0 && opts.configured === true;
+  const notice = opts.onNotice;
   return {
-    ...config,
-    ...config.schemas ? { schemas: config.schemas.map(rebaseEntry) } : {},
-    ...config.overrides ? {
-      overrides: config.overrides.map((o) => ({
-        ...o,
-        schemas: o.schemas.map(rebase)
-      }))
+    respectGitignore: opts.flag ?? opts.configured ?? true,
+    ...asked && notice ? {
+      onGitignoreUnavailable: () => {
+        notice(GITIGNORE_UNAVAILABLE);
+      }
     } : {}
   };
 }
-var matcherCache = /* @__PURE__ */ new Map();
-function overrideGlobs(files) {
-  return typeof files === "string" ? [files] : files;
-}
-function matchesFileGlob(glob, filePath) {
-  return matches(glob, filePath);
-}
-function matches(glob, filePath) {
-  const key = JSON.stringify(glob);
-  let m = matcherCache.get(key);
-  if (!m) {
-    m = picomatch(glob, { dot: true });
-    matcherCache.set(key, m);
+async function resolveTargetSet(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const exts = (opts.exts ?? supportedExtensions()).map(
+    (e) => e.toLowerCase().startsWith(".") ? e.toLowerCase() : `.${e.toLowerCase()}`
+  );
+  const ignore = [...DEFAULT_IGNORE, ...opts.exclude ?? []];
+  const named = /* @__PURE__ */ new Set();
+  const walked = /* @__PURE__ */ new Set();
+  const keepByExt = (file) => exts.includes(extname(file).toLowerCase());
+  const missing = [];
+  for (const input of opts.inputs) {
+    if (input === STDIN_TOKEN) continue;
+    const posixInput = toPosix(input);
+    const abs = resolve4(cwd, posixInput);
+    const st = await statOrNull(abs);
+    if (st?.isFile()) {
+      named.add(toPosix(relative3(cwd, abs)));
+      continue;
+    }
+    if (st?.isDirectory()) {
+      const found2 = await fg(`${posixInput}/**/*`, {
+        cwd,
+        ignore,
+        onlyFiles: true,
+        dot: false
+      });
+      for (const f of found2) if (keepByExt(f)) walked.add(f);
+      continue;
+    }
+    if (!picomatch2.scan(posixInput).isGlob) {
+      missing.push(posixInput);
+      continue;
+    }
+    const found = await fg(posixInput, {
+      cwd,
+      ignore,
+      onlyFiles: true,
+      dot: false
+    });
+    for (const f of found) if (keepByExt(f)) walked.add(f);
   }
-  return m(filePath.replace(/\\/g, "/"));
+  if (missing.length > 0 && !opts.allowEmpty) {
+    const names = missing.map((m) => `"${m}"`).join(", ");
+    throw new DocmetaError(
+      missing.length === 1 ? `File not found: ${names}.` : `Files not found: ${names}.`
+    );
+  }
+  let gitignoreSkipped = 0;
+  if (opts.respectGitignore !== false && walked.size > 0) {
+    const candidates = [...walked].filter((f) => !named.has(f));
+    const { ignored, available } = await gitIgnored(candidates, cwd);
+    if (available) {
+      for (const f of ignored) {
+        if (walked.delete(f)) gitignoreSkipped += 1;
+      }
+    } else {
+      opts.onGitignoreUnavailable?.();
+    }
+  }
+  return {
+    files: [.../* @__PURE__ */ new Set([...named, ...walked])].sort(),
+    gitignoreSkipped
+  };
 }
-function coerceFileSchema(value) {
-  if (value === void 0 || value === null) return void 0;
-  if (typeof value === "string") return [value];
-  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
-    return value;
+function assertNonEmpty(p) {
+  if (p.allowEmpty || p.usingStdin || p.files.length > 0) return;
+  const tried = p.inputs.map((i) => `"${i}"`).join(", ");
+  const notes = [];
+  if (p.exts && p.exts.length > 0) {
+    notes.push(`extensions: ${p.exts.join(", ")}`);
   }
-  throw new Error(
-    `Invalid "${FILE_SCHEMA_KEY}": must be a string or a list of strings.`
+  if (p.exclude && p.exclude.length > 0) {
+    notes.push(`excludes: ${p.exclude.map((e) => `"${e}"`).join(", ")}`);
+  }
+  if (p.gitignoreSkipped && p.gitignoreSkipped > 0) {
+    notes.push(
+      `.gitignore skipped ${p.gitignoreSkipped} (pass --no-gitignore to check them)`
+    );
+  }
+  throw new DocmetaError(
+    [
+      `No files matched. Patterns tried: ${tried}.`,
+      ...notes.length > 0 ? [`Filters applied \u2014 ${notes.join("; ")}.`] : [],
+      `Nothing was ${p.action}, so this is an error rather than a pass.`,
+      `Pass --allow-empty (or set allowEmpty: true) if matching nothing is expected.`
+    ].join("\n")
   );
 }
-function dedupe(refs) {
-  return [...new Set(refs)];
+
+// src/meta/core/sidecars.ts
+var SIDECAR_OWNED_SCHEMA = "sidecar:owned";
+var SIDECAR_DUPLICATE_SCHEMA = "sidecar:duplicate";
+var SIDECAR_KEYWORD = "sidecar";
+var PATH_JOIN = "path";
+var posix = (p) => p.split(sep2).join("/");
+function reportedPath(abs, base) {
+  const rel = relative4(base, abs);
+  return rel === "" ? "." : posix(rel);
+}
+function sidecarJoin(sidecar) {
+  return sidecar.join ?? PATH_JOIN;
+}
+async function loadSidecars(config, opts) {
+  const configured = config?.sidecars;
+  if (!configured || configured.length === 0) return null;
+  const owners = /* @__PURE__ */ new Map();
+  const byPath = /* @__PURE__ */ new Map();
+  const byField = /* @__PURE__ */ new Map();
+  const entries = [];
+  for (const sidecar of configured) {
+    let text;
+    let file;
+    if (classifyRef(sidecar.file).kind === "url") {
+      file = sidecar.file;
+      text = await fetchSidecar(sidecar.file, {
+        ...sidecar.tokenEnv !== void 0 ? { tokenEnv: sidecar.tokenEnv } : {},
+        ...opts.offline !== void 0 ? { offline: opts.offline } : {},
+        ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+        ...opts.env !== void 0 ? { env: opts.env } : {}
+      });
+    } else {
+      const abs = isAbsolute2(sidecar.file) ? sidecar.file : resolve5(opts.configDir, sidecar.file);
+      file = reportedPath(abs, opts.base);
+      text = await readManifest(abs, file);
+    }
+    for (const key of sidecar.keys) owners.set(key, file);
+    const join7 = sidecarJoin(sidecar);
+    let target;
+    if (join7 === PATH_JOIN) {
+      target = byPath;
+    } else {
+      const existing = byField.get(join7);
+      if (existing) target = existing;
+      else {
+        target = /* @__PURE__ */ new Map();
+        byField.set(join7, target);
+      }
+    }
+    parseManifest(sidecar, text, file, opts.configDir, join7, target, entries);
+  }
+  return { owners, byPath, byField, entries };
 }
-function hostAllowed(url, hosts) {
-  const hostname = url.hostname.toLowerCase();
-  const host = url.host.toLowerCase();
-  return hosts.some((h) => {
-    const want = h.trim().toLowerCase();
-    return want === hostname || want === host;
-  });
+async function readManifest(abs, file) {
+  try {
+    return await readFile3(abs, "utf8");
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new DocmetaError(
+      `Sidecar manifest ${file} could not be read: ${reason}`
+    );
+  }
 }
-function assertDocumentRefAllowed(ref, mode, params) {
-  const { kind } = classifyRef(ref);
-  if (kind === "builtin" || isPublishedBuiltinUrl(ref)) return;
-  if (kind === "url") {
-    if (mode === "local") {
+function parseManifest(sidecar, text, file, configDir, join7, target, entries) {
+  const lc = new LineCounter2();
+  const doc = parseDocument3(text, { lineCounter: lc, uniqueKeys: false });
+  const problem = doc.errors[0];
+  if (problem) {
+    throw new DocmetaError(
+      `Sidecar manifest ${file} is not valid YAML: ${problem.message}`
+    );
+  }
+  const root = doc.contents;
+  if (root === null || isScalar2(root) && root.value === null) return;
+  if (!isMap3(root)) {
+    throw new DocmetaError(
+      `Sidecar manifest ${file}: the manifest must be a mapping from document ${join7 === PATH_JOIN ? "path" : `"${join7}"`} to owned keys.`
+    );
+  }
+  const owned = new Set(sidecar.keys);
+  const lineAt = (node) => {
+    const range = isNode(node) ? node.range : void 0;
+    return range ? lc.linePos(range[0]).line : void 0;
+  };
+  const seen = /* @__PURE__ */ new Map();
+  for (const pair of root.items) {
+    const spelled = isScalar2(pair.key) ? String(pair.key.value) : String(pair.key);
+    const entryLine = lineAt(pair.key);
+    const where = entryLine === void 0 ? file : `${file}:${entryLine}`;
+    if (seen.has(spelled)) {
+      const first = seen.get(spelled);
       throw new DocmetaError(
-        `Refusing the "${FILE_SCHEMA_KEY}" URL "${ref}": schemaTrust.documentRefs is "local", so a document may name a built-in id or a schema file inside the repository, but not a URL. Vendor it with \`manni meta schemas vendor ${ref}\` and reference the local copy, or put the URL in \`schemas:\` where an operator controls it.`
+        `Sidecar manifest ${where}: "${spelled}" is named twice (first at line ${first ?? "?"}). Merge the two entries into one.`
       );
     }
-    const hosts = params.config?.schemaTrust?.hosts;
-    if (!hosts || hosts.length === 0) return;
-    let url;
-    try {
-      url = new URL(ref);
-    } catch {
+    seen.set(spelled, entryLine);
+    if (!isMap3(pair.value)) {
       throw new DocmetaError(
-        `Refusing the "${FILE_SCHEMA_KEY}" URL "${ref}": it cannot be parsed as a URL, so it cannot be checked against schemaTrust.hosts.`
+        `Sidecar manifest ${where}: "${spelled}" must be a mapping of owned keys to values.`
       );
     }
-    if (!hostAllowed(url, hosts)) {
-      throw new DocmetaError(
-        `Refusing the "${FILE_SCHEMA_KEY}" URL "${ref}": host "${url.host}" is not in schemaTrust.hosts (${hosts.join(", ")}). Add the host there, or reference a schema the config already names.`
-      );
+    const indexKey = join7 === PATH_JOIN ? resolve5(configDir, spelled) : spelled;
+    const values = target.get(indexKey) ?? /* @__PURE__ */ new Map();
+    for (const kv of pair.value.items) {
+      const key = isScalar2(kv.key) ? String(kv.key.value) : String(kv.key);
+      if (key === FILE_SCHEMA_KEY) {
+        throw new DocmetaError(
+          `Sidecar manifest ${where}: "${spelled}" sets "${FILE_SCHEMA_KEY}" \u2014 a sidecar never chooses the schema a document is judged by; use "overrides" in the config.`
+        );
+      }
+      if (!owned.has(key)) {
+        throw new DocmetaError(
+          `Sidecar manifest ${where}: "${spelled}" sets "${key}", which this sidecar does not own. Add it to the sidecar's "keys", or remove it from the entry.`
+        );
+      }
+      const value = kv.value === null ? null : kv.value.toJS(doc, { maxAliasCount: 100 });
+      const line = lineAt(kv.key);
+      values.set(key, { value, file, ...line === void 0 ? {} : { line } });
     }
-    return;
+    target.set(indexKey, values);
+    entries.push({
+      join: join7,
+      ...join7 === PATH_JOIN ? { abs: indexKey } : {},
+      spelled,
+      file,
+      ...entryLine === void 0 ? {} : { line: entryLine }
+    });
   }
-  const root = params.trustRoot;
-  if (!root) return;
-  const abs = resolve(params.fileBase ?? process.cwd(), ref);
-  const within = relative(root.dir, abs);
-  if (within !== "" && !within.startsWith("..") && !isAbsolute(within)) return;
-  const boundary = root.source === "git" ? `the repository root (${root.dir})` : root.source === "config" ? `${root.dir} \u2014 no git repository was found, so the config file's own directory is the boundary` : `${root.dir} \u2014 no git repository and no config file were found, so the directory the command was run from is the boundary`;
-  const scope = root.source === "git" ? "the repository" : "the project";
-  throw new DocmetaError(
-    `Refusing the "${FILE_SCHEMA_KEY}" path "${ref}": it resolves outside ${boundary}. A document may only name a schema inside ${scope}; a path in \`schemas:\` or on \`--schema\` is not restricted this way.`
-  );
 }
-function resolveSchemaSetWithSource(params) {
-  const { filePath, fileSchema, cliSchemas, config } = params;
-  if (cliSchemas && cliSchemas.length > 0) {
-    return { schemas: dedupe(cliSchemas), source: "cli" };
-  }
-  const fromFile = coerceFileSchema(fileSchema);
-  if (fromFile && fromFile.length > 0) {
-    const mode = config?.schemaTrust?.documentRefs ?? "any";
-    if (mode === "none") {
-      params.onNotice?.(
-        `${filePath}: "${FILE_SCHEMA_KEY}" is ignored (${fromFile.join(", ")}) \u2014 schemaTrust.documentRefs is "none", so the schema set comes from the config instead. Remove the key from the document, or set schemaTrust.documentRefs to "local" or "any" to honor it.`
-      );
-    } else {
-      for (const ref of fromFile) assertDocumentRefAllowed(ref, mode, params);
-      return { schemas: dedupe(fromFile), source: "document" };
-    }
-  }
-  if (config?.overrides) {
-    for (const [i, ov] of config.overrides.entries()) {
-      if (matches(ov.files, filePath) && ov.schemas.length > 0) {
-        return { schemas: dedupe(ov.schemas), source: "override", overrideIndex: i };
-      }
-    }
+function joinValue(raw) {
+  if (typeof raw === "string") return raw;
+  if (typeof raw === "number" || typeof raw === "bigint") return String(raw);
+  if (typeof raw === "boolean") return String(raw);
+  return void 0;
+}
+function mergeSidecars(label, extracted, index, base) {
+  const none = () => void 0;
+  if (!index) return { extracted, collisions: [], joins: [], locate: none };
+  const collisions = [];
+  for (const key of Object.keys(extracted.data)) {
+    const file = index.owners.get(key);
+    if (file !== void 0) collisions.push({ key, file });
+  }
+  const sources = [];
+  const joins = [];
+  if (label !== STDIN_LABEL) {
+    const byPath = index.byPath.get(resolve5(base, label));
+    if (byPath) sources.push(byPath);
+  }
+  for (const [field, byValue] of index.byField) {
+    const value = joinValue(extracted.data[field]);
+    if (value === void 0) continue;
+    const hit = byValue.get(value);
+    if (!hit) continue;
+    sources.push(hit);
+    const first = hit.values().next().value;
+    joins.push({ field, value, file: first?.file ?? "manifest" });
   }
-  if (config?.schemas && config.schemas.length > 0) {
-    return {
-      schemas: dedupe(config.schemas.map(schemaEntryRef)),
-      source: "config"
-    };
+  if (sources.length === 0) {
+    return { extracted, collisions, joins, locate: none };
   }
-  return { schemas: [...DEFAULT_SCHEMAS], source: "default" };
+  const data = { ...extracted.data };
+  const merged = /* @__PURE__ */ new Map();
+  for (const supplied of sources) {
+    for (const [key, sv] of supplied) {
+      if (key in extracted.data) continue;
+      data[key] = sv.value;
+      merged.set(key, sv);
+    }
+  }
+  const locate = (pointer) => {
+    const top = topLevelKey(pointer);
+    if (top === void 0) return void 0;
+    const sv = merged.get(top);
+    if (!sv) return void 0;
+    return { file: sv.file, ...sv.line === void 0 ? {} : { line: sv.line } };
+  };
+  return { extracted: { ...extracted, data }, collisions, joins, locate };
 }
-function resolveSchemaSet(params) {
-  return resolveSchemaSetWithSource(params).schemas;
+function topLevelKey(pointer) {
+  if (pointer === "") return void 0;
+  if (!pointer.startsWith("/")) return pointer;
+  const seg = pointer.slice(1).split("/")[0] ?? "";
+  return seg.replace(/~1/g, "/").replace(/~0/g, "~");
 }
-function resolveElements(filePath, config) {
-  const out = [];
-  if (config?.elements) out.push(...config.elements);
-  for (const ov of config?.overrides ?? []) {
-    if (ov.elements && matches(ov.files, filePath)) out.push(...ov.elements);
-  }
-  return dedupe(out);
+function sidecarPointer(key) {
+  return `/${escapePointerSegment(key)}`;
+}
+function orphanEntries(index, loaded, base) {
+  if (!index) return [];
+  const have = new Set(loaded.map((l) => resolve5(base, l)));
+  return index.entries.filter(
+    (e) => e.join === PATH_JOIN && e.abs !== void 0 && !have.has(e.abs)
+  );
+}
+function orphanJoins(index, matched) {
+  if (!index) return [];
+  return index.entries.filter(
+    (e) => e.join !== PATH_JOIN && !(matched.get(e.join)?.has(e.spelled) ?? false)
+  );
+}
+function orphanError(orphans) {
+  const first = orphans[0];
+  if (!first) throw new Error("orphanError called with no orphans");
+  const where = first.line === void 0 ? first.file : `${first.file}:${first.line}`;
+  const more = orphans.length > 1 ? ` (${orphans.length - 1} more)` : "";
+  const what = first.join === PATH_JOIN ? `names "${first.spelled}", which this run did not load` : `names ${first.join} "${first.spelled}", which no loaded document carries`;
+  return new DocmetaError(
+    `Sidecar manifest ${where} ${what}${more}. Fix the entry, or remove it.`
+  );
 }
 
 // src/meta/core/config.ts
-import { resolve as resolve4 } from "node:path";
+import { resolve as resolve7 } from "node:path";
 import { parse as parseYaml2 } from "yaml";
 
 // src/shared/config-file.ts
-import { readFile as readFile3 } from "node:fs/promises";
-import { dirname as dirname3, join as join4, relative as relative2, resolve as resolve3 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { dirname as dirname4, join as join4, relative as relative5, resolve as resolve6 } from "node:path";
 import { parse as parseYaml } from "yaml";
 
-// src/shared/git-root.ts
-import { existsSync } from "node:fs";
-import { dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
-function findGitRoot(cwd) {
-  let dir = resolve2(cwd);
-  for (; ; ) {
-    if (existsSync(join3(dir, ".git"))) return dir;
-    const parent = dirname2(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-function searchPath(cwd) {
-  const start = resolve2(cwd);
-  const root = findGitRoot(start);
-  if (root === null) return [start];
-  const chain = [];
-  let dir = start;
-  for (; ; ) {
-    chain.push(dir);
-    if (dir === root) return chain;
-    const parent = dirname2(dir);
-    if (parent === dir) return chain;
-    dir = parent;
-  }
-}
-
 // src/shared/warn.ts
 var said = /* @__PURE__ */ new Set();
 function warn(message) {
@@ -5396,7 +5950,7 @@ var MOOSE_CONFIG_NAMES = [
 async function readDocument(path, source, opts) {
   let text;
   try {
-    text = await readFile3(path, "utf8");
+    text = await readFile4(path, "utf8");
   } catch {
     return null;
   }
@@ -5423,10 +5977,10 @@ function slice(document, opts) {
   return null;
 }
 function relativeSource(cwd, path) {
-  return relative2(cwd, path).replace(/\\/g, "/");
+  return relative5(cwd, path).replace(/\\/g, "/");
 }
 async function findConfigFile(cwd, opts) {
-  const start = resolve3(cwd);
+  const start = resolve6(cwd);
   for (const dir of searchPath(start)) {
     const family = [
       { names: FAMILY_CONFIG_NAMES, kind: "manni" },
@@ -5470,7 +6024,7 @@ async function findConfigFile(cwd, opts) {
   return null;
 }
 async function readConfigFile(explicitPath, cwd, opts) {
-  const path = resolve3(cwd, explicitPath);
+  const path = resolve6(cwd, explicitPath);
   const document = await readDocument(path, explicitPath, opts);
   if (document === null) {
     throw opts.toError(`Config file not found: "${explicitPath}".`);
@@ -5481,7 +6035,7 @@ async function readConfigFile(explicitPath, cwd, opts) {
   };
   return {
     path,
-    dir: dirname3(path),
+    dir: dirname4(path),
     source: explicitPath,
     text: document.text,
     kind: "explicit",
@@ -5507,6 +6061,7 @@ function asElementPaths(value, where, source) {
 }
 var OVERRIDE_KEYS = ["name", "files", "schemas", "elements"];
 var CHECK_KEYS = ["name", "query"];
+var SIDECAR_KEYS = ["file", "keys", "tokenEnv", "join"];
 var CHECK_NAME = /^[a-z0-9][a-z0-9._-]*$/;
 var RESERVED_CHECK_NAMES = /* @__PURE__ */ new Set(["query"]);
 var FILL_KEYS = [
@@ -5523,6 +6078,7 @@ var CONFIG_KEYS = [
   "schemas",
   "overrides",
   "checks",
+  "sidecars",
   "baseline",
   "allowEmpty",
   "respectGitignore",
@@ -5666,6 +6222,93 @@ function withSection(message, source, section) {
   if (/^[a-zA-Z]+(\[|\.| —)/.test(rest)) return `${head}${section}.${rest}`;
   return message;
 }
+function parseSidecars(raw, source) {
+  if (!Array.isArray(raw)) {
+    throw new DocmetaError(`${source}: "sidecars" must be a list.`);
+  }
+  const owners = /* @__PURE__ */ new Map();
+  return raw.map((entry, i) => {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new DocmetaError(`${source}: sidecars[${i}] must be a mapping.`);
+    }
+    const e = entry;
+    rejectUnknownKeys(e, SIDECAR_KEYS, `sidecars[${i}]`, source);
+    if (typeof e.file !== "string" || e.file.trim() === "") {
+      throw new DocmetaError(
+        `${source}: sidecars[${i}].file must be a non-empty string naming the manifest, relative to the config file.`
+      );
+    }
+    if (!Array.isArray(e.keys) || e.keys.length === 0 || e.keys.some((k) => typeof k !== "string" || k.trim() === "")) {
+      throw new DocmetaError(
+        `${source}: sidecars[${i}].keys must be a non-empty list of key names.`
+      );
+    }
+    const isUrl = classifyRef(e.file).kind === "url";
+    if (isUrl) {
+      const problem = sidecarUrlProblem(e.file);
+      if (problem !== null) {
+        throw new DocmetaError(`${source}: sidecars[${i}].file ${problem}.`);
+      }
+    }
+    if (e.tokenEnv !== void 0) {
+      if (typeof e.tokenEnv !== "string" || e.tokenEnv.trim() === "") {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].tokenEnv must be the name of an environment variable.`
+        );
+      }
+      if (!isUrl) {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].tokenEnv is set, but "file" is a path, so no request is made and the token would go nowhere. Remove it, or make "file" a URL.`
+        );
+      }
+    }
+    const keys = e.keys;
+    if (e.join !== void 0) {
+      if (typeof e.join !== "string" || e.join.trim() === "") {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].join must be "path" or the name of a top-level frontmatter field.`
+        );
+      }
+      if (e.join === FILE_SCHEMA_KEY) {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].join may not be "${FILE_SCHEMA_KEY}".`
+        );
+      }
+      if (keys.includes(e.join)) {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].join names "${e.join}", which the same entry owns \u2014 the value that selects an entry cannot come from the entry.`
+        );
+      }
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const key of keys) {
+      if (key === FILE_SCHEMA_KEY) {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].keys may not include "${FILE_SCHEMA_KEY}" \u2014 a sidecar never chooses the schema a document is judged by; use "overrides".`
+        );
+      }
+      if (seen.has(key)) {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].keys lists "${key}" twice.`
+        );
+      }
+      seen.add(key);
+      const owner = owners.get(key);
+      if (owner !== void 0) {
+        throw new DocmetaError(
+          `${source}: sidecars[${i}].keys claims "${key}", which sidecars[${owner}] already owns \u2014 a key has exactly one sidecar.`
+        );
+      }
+      owners.set(key, i);
+    }
+    return {
+      file: e.file,
+      keys,
+      ...typeof e.tokenEnv === "string" ? { tokenEnv: e.tokenEnv } : {},
+      ...typeof e.join === "string" ? { join: e.join } : {}
+    };
+  });
+}
 function parseConfigDocument(raw, source) {
   if (raw == null) return {};
   if (typeof raw !== "object" || Array.isArray(raw)) {
@@ -5739,6 +6382,9 @@ function parseConfigDocument(raw, source) {
   if (obj.checks !== void 0) {
     config.checks = parseChecks(obj.checks, source);
   }
+  if (obj.sidecars !== void 0) {
+    config.sidecars = parseSidecars(obj.sidecars, source);
+  }
   if (obj.elements !== void 0) {
     config.elements = asElementPaths(obj.elements, "elements", source);
   }
@@ -5907,8 +6553,8 @@ function parseFill(value, source) {
 function schemaTrustRoot(cwd, configDir) {
   const git = findGitRoot(cwd);
   if (git !== null) return { dir: git, source: "git" };
-  if (configDir !== void 0) return { dir: resolve4(configDir), source: "config" };
-  return { dir: resolve4(cwd), source: "cwd" };
+  if (configDir !== void 0) return { dir: resolve7(configDir), source: "config" };
+  return { dir: resolve7(cwd), source: "cwd" };
 }
 async function loadConfig(explicitPath, cwd = process.cwd()) {
   const file = explicitPath ? await readConfigFile(explicitPath, cwd, CONFIG_FILE) : await findConfigFile(cwd, CONFIG_FILE);
@@ -6089,7 +6735,7 @@ var Validator = class {
    * Callers with an extractor that supplies no column pass nothing and get the
    * previous behavior exactly.
    */
-  async validate(data, refs, lineFor, colFor) {
+  async validate(data, refs, lineFor, colFor, locate) {
     const { [FILE_SCHEMA_KEY]: _omit, ...subject } = data;
     void _omit;
     const errors = [];
@@ -6098,7 +6744,7 @@ var Validator = class {
       const ok = fn(subject);
       if (ok) continue;
       for (const e of fn.errors ?? []) {
-        errors.push(toFieldError(ref, e, lineFor, colFor));
+        errors.push(toFieldError(ref, e, lineFor, colFor, locate));
       }
     }
     return errors;
@@ -6118,7 +6764,7 @@ function subjectOf(e) {
       return void 0;
   }
 }
-function toFieldError(schema, e, lineFor, colFor) {
+function toFieldError(schema, e, lineFor, colFor, locate) {
   const defined = e;
   const instancePath = e.instancePath;
   const subject = subjectOf(defined);
@@ -6131,6 +6777,21 @@ function toFieldError(schema, e, lineFor, colFor) {
     message = `must NOT have additional property '${defined.params.additionalProperty}'`;
     wantsColumn = false;
   }
+  const located = locate?.(instancePath) ?? (defined.keyword === "additionalProperties" ? locate?.(
+    `${instancePath}/${escapePointerSegment(defined.params.additionalProperty)}`
+  ) : void 0);
+  if (located) {
+    return {
+      schema,
+      instancePath,
+      message,
+      keyword: e.keyword,
+      ...subject != null ? { subject } : {},
+      file: located.file,
+      ...located.line != null ? { line: located.line } : {},
+      ...wantsColumn && located.col != null ? { col: located.col } : {}
+    };
+  }
   const line = lineFor(instancePath);
   const col = wantsColumn ? colFor?.(instancePath) : void 0;
   return {
@@ -6146,13 +6807,13 @@ function toFieldError(schema, e, lineFor, colFor) {
 
 // src/meta/commands/validate.ts
 import { existsSync as existsSync2 } from "node:fs";
-import { readFile as readFile5 } from "node:fs/promises";
-import { resolve as resolve7, extname as extname2 } from "node:path";
+import { readFile as readFile6 } from "node:fs/promises";
+import { resolve as resolve9, extname as extname2 } from "node:path";
 
 // src/meta/core/baseline.ts
 import { createHash as createHash3 } from "node:crypto";
-import { readFile as readFile4 } from "node:fs/promises";
-import { relative as relative3, resolve as resolve5 } from "node:path";
+import { readFile as readFile5 } from "node:fs/promises";
+import { relative as relative6, resolve as resolve8 } from "node:path";
 var DEFAULT_BASELINE_PATH = ".manni-baseline.json";
 var LEGACY_BASELINE_PATH = ".docmeta-baseline.json";
 var BASELINE_VERSION = 1;
@@ -6160,13 +6821,13 @@ var FINGERPRINT_RE = /^[0-9a-f]{16}$/;
 function canonicalFilePath(file, ctx) {
   if (!ctx) return file;
   const from = ctx.runBase ?? ctx.base;
-  return relative3(ctx.base, resolve5(from, file)).replace(/\\/g, "/");
+  return relative6(ctx.base, resolve8(from, file)).replace(/\\/g, "/");
 }
 function canonicalSchemaRef(ref, ctx) {
   if (!ctx) return ref;
   if (classifyRef(ref).kind !== "file") return ref;
-  const abs = resolve5(ctx.cwd, ref);
-  return relative3(ctx.base, abs).replace(/\\/g, "/");
+  const abs = resolve8(ctx.cwd, ref);
+  return relative6(ctx.base, abs).replace(/\\/g, "/");
 }
 function fingerprint(e, ctx) {
   const parts = [
@@ -6195,303 +6856,129 @@ function serializeBaseline(baseline) {
 }
 function bad(source, detail) {
   throw new DocmetaError(`Baseline "${source}": ${detail}`);
-}
-function parseBaseline(text, source) {
-  let raw;
-  try {
-    raw = JSON.parse(stripBom(text));
-  } catch (err) {
-    bad(source, `invalid JSON: ${err.message}`);
-  }
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    bad(source, "top level must be an object.");
-  }
-  const obj = raw;
-  if (obj.version !== BASELINE_VERSION) {
-    bad(
-      source,
-      `unsupported version ${JSON.stringify(obj.version)} (this manni writes version ${BASELINE_VERSION}). Re-record it with \`manni meta validate --write-baseline\`.`
-    );
-  }
-  const generatedWith = typeof obj.generatedWith === "string" ? obj.generatedWith : "";
-  const rawEntries = obj.entries;
-  if (typeof rawEntries !== "object" || rawEntries === null || Array.isArray(rawEntries)) {
-    bad(source, '"entries" must be an object mapping file paths to fingerprints.');
-  }
-  const entries = /* @__PURE__ */ Object.create(null);
-  for (const [file, value] of Object.entries(
-    rawEntries
-  )) {
-    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
-      bad(source, `entries["${file}"] must be a list of fingerprint strings.`);
-    }
-    const malformed = value.find((v) => !FINGERPRINT_RE.test(v));
-    if (malformed !== void 0) {
-      bad(
-        source,
-        `entries["${file}"] contains ${JSON.stringify(malformed)}, which is not a fingerprint (16 lowercase hex characters).`
-      );
-    }
-    entries[file] = value;
-  }
-  return { version: BASELINE_VERSION, generatedWith, entries };
-}
-async function readBaseline(absPath, source) {
-  let text;
-  try {
-    text = await readFile4(absPath, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return null;
-    throw new DocmetaError(
-      `Baseline "${source}" could not be read: ${err.message}`
-    );
-  }
-  return parseBaseline(text, source);
-}
-async function writeBaselineFile(absPath, baseline, source) {
-  try {
-    await writeFileAtomic(absPath, serializeBaseline(baseline));
-  } catch (err) {
-    throw new DocmetaError(
-      `Baseline "${source}" could not be written: ${err.message}`
-    );
-  }
-}
-function buildBaseline(results, generatedWith, ctx) {
-  const entries = /* @__PURE__ */ Object.create(null);
-  for (const r of results) {
-    if (r.errors.length === 0) continue;
-    const prints = [...new Set(r.errors.map((e) => fingerprint(e, ctx)))].sort();
-    entries[canonicalFilePath(r.file, ctx)] = prints;
-  }
-  return { version: BASELINE_VERSION, generatedWith, entries };
-}
-function applyBaseline(results, baseline, ctx) {
-  let recorded = 0;
-  let suppressed = 0;
-  let stale = 0;
-  const applied = results.map((r) => {
-    const known = baseline.entries[canonicalFilePath(r.file, ctx)];
-    if (!known) return r;
-    const recordedHere = new Set(known);
-    recorded += recordedHere.size;
-    const seen = /* @__PURE__ */ new Set();
-    const fresh = [];
-    for (const e of r.errors) {
-      const print = fingerprint(e, ctx);
-      if (recordedHere.has(print)) {
-        seen.add(print);
-        suppressed += 1;
-      } else {
-        fresh.push(e);
-      }
-    }
-    stale += recordedHere.size - seen.size;
-    const baselined = r.errors.length - fresh.length;
-    return {
-      ...r,
-      ok: fresh.length === 0,
-      errors: fresh,
-      ...baselined > 0 ? { baselined } : {}
-    };
-  });
-  return { results: applied, recorded, suppressed, stale };
-}
-function diffBaselines(previous, next) {
-  const flatten = (b) => {
-    const out = /* @__PURE__ */ new Set();
-    if (!b) return out;
-    for (const [file, prints] of Object.entries(b.entries)) {
-      for (const p of prints) out.add(`${file}\0${p}`);
-    }
-    return out;
-  };
-  const before = flatten(previous);
-  const after = flatten(next);
-  let added = 0;
-  let removed = 0;
-  for (const k of after) if (!before.has(k)) added += 1;
-  for (const k of before) if (!after.has(k)) removed += 1;
-  return { added, removed };
-}
-function countFingerprints(baseline) {
-  let n = 0;
-  for (const prints of Object.values(baseline.entries)) n += prints.length;
-  return n;
-}
-
-// src/meta/core/load-files.ts
-import { stat as stat3 } from "node:fs/promises";
-import { extname, relative as relative4, resolve as resolve6 } from "node:path";
-import fg from "fast-glob";
-import picomatch2 from "picomatch";
-
-// src/meta/core/gitignore.ts
-import { spawn } from "node:child_process";
-var GITIGNORE_UNAVAILABLE = ".gitignore filtering was requested but git could not answer here (no repository, or no git on PATH); no files were skipped.";
-var unavailable = () => ({
-  ignored: /* @__PURE__ */ new Set(),
-  available: false
-});
-function gitIgnored(paths, cwd) {
-  if (paths.length === 0) {
-    return Promise.resolve({ ignored: /* @__PURE__ */ new Set(), available: true });
-  }
-  return new Promise((settle) => {
-    let done = false;
-    const finish = (answer) => {
-      if (done) return;
-      done = true;
-      settle(answer);
-    };
-    let child;
-    try {
-      child = spawn("git", ["check-ignore", "--stdin", "-z"], {
-        cwd,
-        windowsHide: true
-      });
-    } catch {
-      finish(unavailable());
-      return;
-    }
-    let out = "";
-    child.stdout.setEncoding("utf8");
-    child.stdout.on("data", (chunk) => {
-      out += chunk;
-    });
-    child.stderr.resume();
-    child.on("error", () => {
-      finish(unavailable());
-    });
-    child.stdin.on("error", () => {
-    });
-    child.on("close", (code) => {
-      if (code !== 0 && code !== 1) {
-        finish(unavailable());
-        return;
-      }
-      finish({
-        ignored: new Set(out.split("\0").filter((p) => p !== "")),
-        available: true
-      });
-    });
-    child.stdin.end(paths.join("\0"));
-  });
-}
-
-// src/meta/core/load-files.ts
-var DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**"];
-var STDIN_TOKEN = "-";
-var STDIN_LABEL = "<stdin>";
-function toPosix(p) {
-  return p.replace(/\\/g, "/");
-}
-async function statOrNull(p) {
-  try {
-    return await stat3(p);
-  } catch {
-    return null;
-  }
-}
-function gitignoreOptions(opts) {
-  const asked = opts.flag === true || opts.flag === void 0 && opts.configured === true;
-  const notice = opts.onNotice;
-  return {
-    respectGitignore: opts.flag ?? opts.configured ?? true,
-    ...asked && notice ? {
-      onGitignoreUnavailable: () => {
-        notice(GITIGNORE_UNAVAILABLE);
-      }
-    } : {}
-  };
-}
-async function resolveTargetSet(opts) {
-  const cwd = opts.cwd ?? process.cwd();
-  const exts = (opts.exts ?? supportedExtensions()).map(
-    (e) => e.toLowerCase().startsWith(".") ? e.toLowerCase() : `.${e.toLowerCase()}`
-  );
-  const ignore = [...DEFAULT_IGNORE, ...opts.exclude ?? []];
-  const named = /* @__PURE__ */ new Set();
-  const walked = /* @__PURE__ */ new Set();
-  const keepByExt = (file) => exts.includes(extname(file).toLowerCase());
-  const missing = [];
-  for (const input of opts.inputs) {
-    if (input === STDIN_TOKEN) continue;
-    const posixInput = toPosix(input);
-    const abs = resolve6(cwd, posixInput);
-    const st = await statOrNull(abs);
-    if (st?.isFile()) {
-      named.add(toPosix(relative4(cwd, abs)));
-      continue;
-    }
-    if (st?.isDirectory()) {
-      const found2 = await fg(`${posixInput}/**/*`, {
-        cwd,
-        ignore,
-        onlyFiles: true,
-        dot: false
-      });
-      for (const f of found2) if (keepByExt(f)) walked.add(f);
-      continue;
+}
+function parseBaseline(text, source) {
+  let raw;
+  try {
+    raw = JSON.parse(stripBom(text));
+  } catch (err) {
+    bad(source, `invalid JSON: ${err.message}`);
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    bad(source, "top level must be an object.");
+  }
+  const obj = raw;
+  if (obj.version !== BASELINE_VERSION) {
+    bad(
+      source,
+      `unsupported version ${JSON.stringify(obj.version)} (this manni writes version ${BASELINE_VERSION}). Re-record it with \`manni meta validate --write-baseline\`.`
+    );
+  }
+  const generatedWith = typeof obj.generatedWith === "string" ? obj.generatedWith : "";
+  const rawEntries = obj.entries;
+  if (typeof rawEntries !== "object" || rawEntries === null || Array.isArray(rawEntries)) {
+    bad(source, '"entries" must be an object mapping file paths to fingerprints.');
+  }
+  const entries = /* @__PURE__ */ Object.create(null);
+  for (const [file, value] of Object.entries(
+    rawEntries
+  )) {
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+      bad(source, `entries["${file}"] must be a list of fingerprint strings.`);
     }
-    if (!picomatch2.scan(posixInput).isGlob) {
-      missing.push(posixInput);
-      continue;
+    const malformed = value.find((v) => !FINGERPRINT_RE.test(v));
+    if (malformed !== void 0) {
+      bad(
+        source,
+        `entries["${file}"] contains ${JSON.stringify(malformed)}, which is not a fingerprint (16 lowercase hex characters).`
+      );
     }
-    const found = await fg(posixInput, {
-      cwd,
-      ignore,
-      onlyFiles: true,
-      dot: false
-    });
-    for (const f of found) if (keepByExt(f)) walked.add(f);
+    entries[file] = value;
   }
-  if (missing.length > 0 && !opts.allowEmpty) {
-    const names = missing.map((m) => `"${m}"`).join(", ");
+  return { version: BASELINE_VERSION, generatedWith, entries };
+}
+async function readBaseline(absPath, source) {
+  let text;
+  try {
+    text = await readFile5(absPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
     throw new DocmetaError(
-      missing.length === 1 ? `File not found: ${names}.` : `Files not found: ${names}.`
+      `Baseline "${source}" could not be read: ${err.message}`
     );
   }
-  let gitignoreSkipped = 0;
-  if (opts.respectGitignore !== false && walked.size > 0) {
-    const candidates = [...walked].filter((f) => !named.has(f));
-    const { ignored, available } = await gitIgnored(candidates, cwd);
-    if (available) {
-      for (const f of ignored) {
-        if (walked.delete(f)) gitignoreSkipped += 1;
+  return parseBaseline(text, source);
+}
+async function writeBaselineFile(absPath, baseline, source) {
+  try {
+    await writeFileAtomic(absPath, serializeBaseline(baseline));
+  } catch (err) {
+    throw new DocmetaError(
+      `Baseline "${source}" could not be written: ${err.message}`
+    );
+  }
+}
+function buildBaseline(results, generatedWith, ctx) {
+  const entries = /* @__PURE__ */ Object.create(null);
+  for (const r of results) {
+    if (r.errors.length === 0) continue;
+    const prints = [...new Set(r.errors.map((e) => fingerprint(e, ctx)))].sort();
+    entries[canonicalFilePath(r.file, ctx)] = prints;
+  }
+  return { version: BASELINE_VERSION, generatedWith, entries };
+}
+function applyBaseline(results, baseline, ctx) {
+  let recorded = 0;
+  let suppressed = 0;
+  let stale = 0;
+  const applied = results.map((r) => {
+    const known = baseline.entries[canonicalFilePath(r.file, ctx)];
+    if (!known) return r;
+    const recordedHere = new Set(known);
+    recorded += recordedHere.size;
+    const seen = /* @__PURE__ */ new Set();
+    const fresh = [];
+    for (const e of r.errors) {
+      const print = fingerprint(e, ctx);
+      if (recordedHere.has(print)) {
+        seen.add(print);
+        suppressed += 1;
+      } else {
+        fresh.push(e);
       }
-    } else {
-      opts.onGitignoreUnavailable?.();
     }
-  }
-  return {
-    files: [.../* @__PURE__ */ new Set([...named, ...walked])].sort(),
-    gitignoreSkipped
+    stale += recordedHere.size - seen.size;
+    const baselined = r.errors.length - fresh.length;
+    return {
+      ...r,
+      ok: fresh.length === 0,
+      errors: fresh,
+      ...baselined > 0 ? { baselined } : {}
+    };
+  });
+  return { results: applied, recorded, suppressed, stale };
+}
+function diffBaselines(previous, next) {
+  const flatten = (b) => {
+    const out = /* @__PURE__ */ new Set();
+    if (!b) return out;
+    for (const [file, prints] of Object.entries(b.entries)) {
+      for (const p of prints) out.add(`${file}\0${p}`);
+    }
+    return out;
   };
+  const before = flatten(previous);
+  const after = flatten(next);
+  let added = 0;
+  let removed = 0;
+  for (const k of after) if (!before.has(k)) added += 1;
+  for (const k of before) if (!after.has(k)) removed += 1;
+  return { added, removed };
 }
-function assertNonEmpty(p) {
-  if (p.allowEmpty || p.usingStdin || p.files.length > 0) return;
-  const tried = p.inputs.map((i) => `"${i}"`).join(", ");
-  const notes = [];
-  if (p.exts && p.exts.length > 0) {
-    notes.push(`extensions: ${p.exts.join(", ")}`);
-  }
-  if (p.exclude && p.exclude.length > 0) {
-    notes.push(`excludes: ${p.exclude.map((e) => `"${e}"`).join(", ")}`);
-  }
-  if (p.gitignoreSkipped && p.gitignoreSkipped > 0) {
-    notes.push(
-      `.gitignore skipped ${p.gitignoreSkipped} (pass --no-gitignore to check them)`
-    );
-  }
-  throw new DocmetaError(
-    [
-      `No files matched. Patterns tried: ${tried}.`,
-      ...notes.length > 0 ? [`Filters applied \u2014 ${notes.join("; ")}.`] : [],
-      `Nothing was ${p.action}, so this is an error rather than a pass.`,
-      `Pass --allow-empty (or set allowEmpty: true) if matching nothing is expected.`
-    ].join("\n")
-  );
+function countFingerprints(baseline) {
+  let n = 0;
+  for (const prints of Object.values(baseline.entries)) n += prints.length;
+  return n;
 }
 
 // src/meta/core/projection.ts
@@ -6898,16 +7385,16 @@ function parseErrorResult(file, format, message, keyword) {
 }
 function resolveBaselineRequest(opts, configured, configDir, cwd) {
   const named = (label) => ({
-    absPath: resolve7(cwd, label),
+    absPath: resolve9(cwd, label),
     label
   });
   const implied = () => {
     const base = configDir ?? cwd;
     if (configured !== void 0) {
-      return { absPath: resolve7(base, configured), label: configured };
+      return { absPath: resolve9(base, configured), label: configured };
     }
-    const current = resolve7(base, DEFAULT_BASELINE_PATH);
-    const legacy = resolve7(base, LEGACY_BASELINE_PATH);
+    const current = resolve9(base, DEFAULT_BASELINE_PATH);
+    const legacy = resolve9(base, LEGACY_BASELINE_PATH);
     if (!existsSync2(current) && existsSync2(legacy)) {
       warn(
         `"${LEGACY_BASELINE_PATH}" is the pre-rename baseline file name. Rename it to "${DEFAULT_BASELINE_PATH}".`
@@ -6975,6 +7462,11 @@ async function runValidate(opts) {
     action: "validated"
   });
   const trustRoot = schemaTrustRoot(cwd, configDir);
+  const sidecars = await loadSidecars(config, {
+    configDir: configDir ?? cwd,
+    base,
+    offline: opts.offline ?? config?.offline ?? false
+  });
   const validator = new Validator(
     schemaLoadOptions({
       // The config's directory when a config governs the run, so one project
@@ -6990,9 +7482,14 @@ async function runValidate(opts) {
     })
   );
   const results = [];
+  const joinHits = /* @__PURE__ */ new Map();
   const scoped = opts.inputs.length > 0 || // redundant with inputs.length (stdin is an input) — kept as belt-and-suspenders
   usingStdin || opts.as !== void 0 || opts.exts !== void 0 || opts.exclude !== void 0 && opts.exclude.length > 0 || opts.respectGitignore !== void 0 || (opts.cliSchemas?.length ?? 0) > 0;
   const configuredChecks = config?.checks ?? [];
+  if (!scoped) {
+    const orphans = orphanEntries(sidecars, files, base);
+    if (orphans.length > 0) throw orphanError(orphans);
+  }
   const checksWillRun = configuredChecks.length > 0 && opts.checks !== false && !scoped;
   const checkEntries = [];
   const checkResolved = /* @__PURE__ */ new Map();
@@ -7015,6 +7512,16 @@ async function runValidate(opts) {
       );
       return;
     }
+    const merged = mergeSidecars(label, extracted, sidecars, base);
+    extracted = merged.extracted;
+    for (const j of merged.joins) {
+      const byValue = joinHits.get(j.field) ?? /* @__PURE__ */ new Map();
+      const line = extracted.lineFor(j.field);
+      const hits = byValue.get(j.value) ?? [];
+      hits.push({ label, file: j.file, ...line != null ? { line } : {} });
+      byValue.set(j.value, hits);
+      joinHits.set(j.field, byValue);
+    }
     if (checksWillRun) checkEntries.push({ label, extracted });
     let resolved;
     try {
@@ -7044,7 +7551,8 @@ async function runValidate(opts) {
         extracted.data,
         schemaSet,
         extracted.lineFor,
-        extracted.colFor
+        extracted.colFor,
+        merged.locate
       );
     } catch (err) {
       if (!(err instanceof DocmetaError) || resolved.source !== "document") {
@@ -7055,6 +7563,17 @@ async function runValidate(opts) {
       );
       return;
     }
+    for (const { key, file } of merged.collisions) {
+      const line = extracted.lineFor(key);
+      errors.push({
+        schema: SIDECAR_OWNED_SCHEMA,
+        keyword: SIDECAR_KEYWORD,
+        subject: key,
+        instancePath: sidecarPointer(key),
+        message: `"${key}" is owned by sidecar ${file}; remove it from the document`,
+        ...line != null ? { line } : {}
+      });
+    }
     results.push({
       file: label,
       format: extractor.name,
@@ -7073,9 +7592,37 @@ async function runValidate(opts) {
     await processOne(STDIN_LABEL, content, forcedExtractor.extensions[0] ?? "");
   }
   for (const file of files) {
-    const content = await readFile5(resolve7(base, file), "utf8");
+    const content = await readFile6(resolve9(base, file), "utf8");
     await processOne(file, content, extname2(file));
   }
+  if (sidecars) {
+    const byLabel = new Map(results.map((r) => [r.file, r]));
+    const matched = /* @__PURE__ */ new Map();
+    for (const [field, byValue] of joinHits) {
+      matched.set(field, new Set(byValue.keys()));
+      for (const [value, hits] of byValue) {
+        if (hits.length < 2) continue;
+        for (const hit of hits) {
+          const others = hits.filter((h) => h.label !== hit.label).map((h) => h.label).join(", ");
+          const result = byLabel.get(hit.label);
+          if (!result) continue;
+          result.errors.push({
+            schema: SIDECAR_DUPLICATE_SCHEMA,
+            keyword: SIDECAR_KEYWORD,
+            subject: value,
+            instancePath: sidecarPointer(field),
+            message: `${hits.length} documents carry ${field} "${value}"; ${hit.file} cannot tell them apart (${others})`,
+            ...hit.line != null ? { line: hit.line } : {}
+          });
+          result.ok = false;
+        }
+      }
+    }
+    if (!scoped) {
+      const orphans = orphanJoins(sidecars, matched);
+      if (orphans.length > 0) throw orphanError(orphans);
+    }
+  }
   if (configuredChecks.length > 0 && opts.checks !== false) {
     if (scoped) {
       opts.onNotice?.("corpus checks skipped: run is scoped");
@@ -7165,14 +7712,14 @@ async function settleBaseline(results, request, ctx) {
 }
 
 // src/meta/commands/get.ts
-import { readFile as readFile6 } from "node:fs/promises";
-import { resolve as resolve8, extname as extname3 } from "node:path";
+import { readFile as readFile7 } from "node:fs/promises";
+import { resolve as resolve10, extname as extname3 } from "node:path";
 async function runGet(opts) {
   const cwd = opts.cwd ?? process.cwd();
   if (opts.fields.length === 0) {
     throw new DocmetaError("Specify at least one field to get.");
   }
-  const { config, inputs, base } = await resolveRunConfig({
+  const { config, inputs, base, configDir } = await resolveRunConfig({
     cwd,
     configPath: opts.configPath,
     noConfig: opts.noConfig,
@@ -7218,6 +7765,11 @@ async function runGet(opts) {
     action: "read"
   });
   const out = [];
+  const sidecars = await loadSidecars(config, {
+    configDir: configDir ?? cwd,
+    base,
+    offline: opts.offline ?? config?.offline ?? false
+  });
   const readOne = (label, content, extension) => {
     const extractor = forced ?? extractorForExtension(extension);
     if (!extractor) {
@@ -7227,9 +7779,14 @@ async function runGet(opts) {
     }
     let extracted;
     try {
-      extracted = extractor.extract(content, label, {
-        elements: resolveElements(label, config)
-      });
+      extracted = mergeSidecars(
+        label,
+        extractor.extract(content, label, {
+          elements: resolveElements(label, config)
+        }),
+        sidecars,
+        base
+      ).extracted;
     } catch (err) {
       if (err instanceof DocmetaError) throw err;
       const reason = err instanceof Error ? err.message : String(err);
@@ -7249,7 +7806,7 @@ async function runGet(opts) {
     readOne("<stdin>", opts.stdinContent ?? "", forced.extensions[0] ?? "");
   }
   for (const file of files) {
-    const content = await readFile6(resolve8(base, file), "utf8");
+    const content = await readFile7(resolve10(base, file), "utf8");
     readOne(file, content, extname3(file));
   }
   return out;
@@ -7286,16 +7843,16 @@ function parseJsonPointer(pointer) {
 
 // src/meta/commands/schemas.ts
 import { existsSync as existsSync3 } from "node:fs";
-import { mkdir as mkdir2, readFile as readFile7 } from "node:fs/promises";
-import { dirname as dirname4, extname as extname4, isAbsolute as isAbsolute2, join as join5, relative as relative5, resolve as resolve9, sep } from "node:path";
-import { parseDocument as parseDocument3, parse as parseYaml3, stringify } from "yaml";
+import { mkdir as mkdir2, readFile as readFile8 } from "node:fs/promises";
+import { dirname as dirname5, extname as extname4, isAbsolute as isAbsolute3, join as join5, relative as relative7, resolve as resolve11, sep as sep3 } from "node:path";
+import { parseDocument as parseDocument4, parse as parseYaml3, stringify } from "yaml";
 function getSchemasInfo() {
   return { builtins: listBuiltins(), formats: listFormats() };
 }
 var DEFAULT_VENDOR_DIR = "./schema";
 var DEFAULT_CONFIG_NAME = "manni.config.yaml";
 function posixRelative(from, to) {
-  return relative5(from, to).split(sep).join("/");
+  return relative7(from, to).split(sep3).join("/");
 }
 function vendorFileName(url) {
   let parsed2;
@@ -7360,7 +7917,7 @@ function renderConfig(existing, entries, section) {
   if (existing === null) {
     return stringify({ [META_SECTION]: { schemas: entries } });
   }
-  const doc = parseDocument3(existing);
+  const doc = parseDocument4(existing);
   doc.setIn(section === void 0 ? ["schemas"] : [section, "schemas"], entries);
   return doc.toString();
 }
@@ -7381,13 +7938,13 @@ async function runVendorSchema(opts) {
     );
   }
   const loaded = await loadConfig(opts.configPath, cwd);
-  const configPath = loaded?.path ?? resolve9(cwd, DEFAULT_CONFIG_NAME);
+  const configPath = loaded?.path ?? resolve11(cwd, DEFAULT_CONFIG_NAME);
   const configDir = loaded?.dir ?? cwd;
-  const absDir = resolve9(cwd, opts.dir ?? DEFAULT_VENDOR_DIR);
+  const absDir = resolve11(cwd, opts.dir ?? DEFAULT_VENDOR_DIR);
   const absFile = join5(absDir, vendorFileName(url));
   await assertNotIgnored(absFile, absDir, cwd, opts.onNotice);
   const fromConfig = posixRelative(configDir, absFile);
-  const ref = isAbsolute2(fromConfig) || fromConfig === "" ? absFile : fromConfig.startsWith(".") ? fromConfig : `./${fromConfig}`;
+  const ref = isAbsolute3(fromConfig) || fromConfig === "" ? absFile : fromConfig.startsWith(".") ? fromConfig : `./${fromConfig}`;
   const { bytes } = await fetchSchemaBytes(url, {
     ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
     ...opts.maxBytes !== void 0 ? { maxBytes: opts.maxBytes } : {}
@@ -7402,7 +7959,7 @@ async function runVendorSchema(opts) {
   }
   let unchanged = false;
   if (existsSync3(absFile)) {
-    const current = await readFile7(absFile);
+    const current = await readFile8(absFile);
     unchanged = bytes.equals(current);
     if (!unchanged && !folded.replaced) {
       throw new DocmetaError(
@@ -7412,7 +7969,7 @@ async function runVendorSchema(opts) {
   }
   await mkdir2(absDir, { recursive: true });
   await writeFileAtomic(absFile, bytes);
-  const existing = loaded ? await readFile7(configPath, "utf8") : null;
+  const existing = loaded ? await readFile8(configPath, "utf8") : null;
   const section = loaded ? loaded.section : META_SECTION;
   const text = renderConfig(existing, folded.entries, section);
   reparseConfig(text, posixRelative(cwd, configPath) || DEFAULT_CONFIG_NAME, section);
@@ -7531,7 +8088,7 @@ async function runInferSchema(opts) {
       `--min-coverage must be a percentage between 0 and 100, got ${minCoverage}.`
     );
   }
-  const { config, inputs, base } = await resolveRunConfig({
+  const { config, inputs, base, configDir } = await resolveRunConfig({
     cwd,
     configPath: opts.configPath,
     noConfig: opts.noConfig,
@@ -7539,6 +8096,11 @@ async function runInferSchema(opts) {
     onConfigLoaded: opts.onConfigLoaded
   });
   const usingStdin = inputs.includes(STDIN_TOKEN);
+  const sidecars = await loadSidecars(config, {
+    configDir: configDir ?? cwd,
+    base,
+    offline: opts.offline ?? config?.offline ?? false
+  });
   if (inputs.length === 0) {
     throw new DocmetaError(
       "No files to scan. Pass paths/globs, or add `paths:` under `meta:` in manni.config.yaml."
@@ -7557,10 +8119,10 @@ async function runInferSchema(opts) {
   }
   let absOut;
   if (opts.out !== void 0) {
-    absOut = resolve9(cwd, opts.out);
+    absOut = resolve11(cwd, opts.out);
     await assertNotIgnored(
       absOut,
-      dirname4(absOut),
+      dirname5(absOut),
       cwd,
       opts.onNotice,
       DRAFT_IGNORE_TEXT
@@ -7611,9 +8173,14 @@ async function runInferSchema(opts) {
     filesScanned += 1;
     let extracted;
     try {
-      extracted = extractor.extract(content, label, {
-        elements: resolveElements(label, config)
-      });
+      extracted = mergeSidecars(
+        label,
+        extractor.extract(content, label, {
+          elements: resolveElements(label, config)
+        }),
+        sidecars,
+        base
+      ).extracted;
     } catch (err) {
       unreadable.push({
         file: label,
@@ -7635,7 +8202,7 @@ async function runInferSchema(opts) {
     scanOne(STDIN_LABEL, opts.stdinContent ?? "", forced.extensions[0] ?? "");
   }
   for (const file of files) {
-    const content = await readFile7(resolve9(base, file), "utf8");
+    const content = await readFile8(resolve11(base, file), "utf8");
     scanOne(file, content, extname4(file));
   }
   for (const u of unreadable) {
@@ -7677,7 +8244,7 @@ async function runInferSchema(opts) {
   };
   const keys = kept.map(({ sawEmptyString: _drop, ...rest }) => rest);
   if (absOut !== void 0) {
-    await mkdir2(dirname4(absOut), { recursive: true });
+    await mkdir2(dirname5(absOut), { recursive: true });
     await writeFileAtomic(absOut, `${JSON.stringify(draft, null, 2)}
 `);
   }
@@ -7696,9 +8263,9 @@ async function runInferSchema(opts) {
 // src/meta/commands/query.ts
 import { randomBytes } from "node:crypto";
 import { existsSync as existsSync4 } from "node:fs";
-import { mkdir as mkdir3, open, readFile as readFile8, rename as rename2, rm as rm2 } from "node:fs/promises";
-import { dirname as dirname5, isAbsolute as isAbsolute3, resolve as resolve10, extname as extname5, sep as sep2 } from "node:path";
-import { parseDocument as parseDocument4, isMap as isMap3, isSeq as isSeq2, isScalar as isScalar2 } from "yaml";
+import { mkdir as mkdir3, open, readFile as readFile9, rename as rename2, rm as rm2 } from "node:fs/promises";
+import { dirname as dirname6, isAbsolute as isAbsolute4, resolve as resolve12, extname as extname5, sep as sep4 } from "node:path";
+import { parseDocument as parseDocument5, isMap as isMap4, isSeq as isSeq2, isScalar as isScalar3 } from "yaml";
 async function runQuery(opts) {
   const cwd = opts.cwd ?? process.cwd();
   const sql = opts.sql.trim();
@@ -7778,6 +8345,11 @@ async function runQuery(opts) {
     action: "queried"
   });
   const entries = [];
+  const sidecars = await loadSidecars(config, {
+    configDir: configDir ?? cwd,
+    base,
+    offline: opts.offline ?? config?.offline ?? false
+  });
   const readOne = (label, content, extension) => {
     const extractor = forced ?? extractorForExtension(extension);
     if (!extractor) {
@@ -7785,9 +8357,14 @@ async function runQuery(opts) {
         `Unsupported file type "${extension}" for "${label}". Supported: ${supportedExtensions().join(", ")}. Use --as to override.`
       );
     }
-    const extracted = extractor.extract(content, label, {
-      elements: resolveElements(label, config)
-    });
+    const extracted = mergeSidecars(
+      label,
+      extractor.extract(content, label, {
+        elements: resolveElements(label, config)
+      }),
+      sidecars,
+      base
+    ).extracted;
     entries.push({ label, extracted, extractor });
   };
   if (usingStdin) {
@@ -7805,10 +8382,10 @@ async function runQuery(opts) {
     readOne(STDIN_LABEL, opts.stdinContent ?? "", ext);
   }
   for (const file of files) {
-    const content = await readFile8(resolve10(base, file), "utf8");
+    const content = await readFile9(resolve12(base, file), "utf8");
     readOne(file, content, extname5(file));
   }
-  const db = opts.db === void 0 ? void 0 : { resolved: resolve10(cwd, opts.db), display: opts.db };
+  const db = opts.db === void 0 ? void 0 : { resolved: resolve12(cwd, opts.db), display: opts.db };
   const run = await runSql(sql, entries, {
     target: db,
     params: boundParams,
@@ -7820,6 +8397,7 @@ async function runQuery(opts) {
     configDir,
     configPath,
     trustRoot: schemaTrustRoot(cwd, configDir),
+    sidecars,
     onNotice: opts.onNotice
   });
   return { ...run, frame: { cwd, base: configDir ?? cwd, runBase: base } };
@@ -7883,7 +8461,7 @@ async function runSql(sql, entries, ctx) {
   );
   const { DatabaseSync } = await loadSqlite();
   if (target) {
-    await mkdir3(dirname5(target.resolved), { recursive: true });
+    await mkdir3(dirname6(target.resolved), { recursive: true });
     await prepareDbTarget(target.resolved, target.display);
   }
   let db;
@@ -8335,20 +8913,20 @@ function displayPath(ctx, abs) {
 }
 function assertSchemaWriteWithin(ctx, abs) {
   const within = posixRelative(ctx.trustRoot.dir, abs);
-  if (within !== "" && !within.startsWith("..") && !isAbsolute3(within)) return;
+  if (within !== "" && !within.startsWith("..") && !isAbsolute4(within)) return;
   throw new DocmetaError(
     `The resolved schema "${abs}" lives outside ${ctx.trustRoot.dir}; DDL edits schemas inside the repository. Evolve it where it lives, or vendor a copy in.`
   );
 }
 function foldPath(p) {
-  const abs = resolve10(p);
+  const abs = resolve12(p);
   return process.platform === "win32" ? abs.toLowerCase() : abs;
 }
 function filePinsByPath(ctx) {
   const byPath = /* @__PURE__ */ new Map();
   for (const [ref, pin] of collectSchemaPins(ctx.config)) {
     if (classifyRef(ref).kind !== "file") continue;
-    byPath.set(foldPath(resolve10(ctx.cwd, ref)), pin);
+    byPath.set(foldPath(resolve12(ctx.cwd, ref)), pin);
   }
   return byPath;
 }
@@ -8376,13 +8954,13 @@ async function loadSetMembers(refs, ctx) {
       });
       continue;
     }
-    const abs = resolve10(ctx.cwd, ref);
+    const abs = resolve12(ctx.cwd, ref);
     const canon = foldPath(abs);
     if (seenFiles.has(canon)) continue;
     seenFiles.add(canon);
     let text;
     try {
-      text = await readFile8(abs, "utf8");
+      text = await readFile9(abs, "utf8");
     } catch {
       throw new DocmetaError(
         `Schema file not found: "${ref}" (looked at ${abs}).`
@@ -8576,7 +9154,7 @@ async function planSchemaMutation(ops, entries, ctx) {
     const [, name2, ver] = target.builtinId.split(":");
     const safe = (s) => s.replace(/[^A-Za-z0-9._-]/g, "-");
     const forkName = `${safe(name2 ?? "schema")}-${safe(ver ?? "0")}.local.json`;
-    schemaAbs = resolve10(ctx.configDir ?? ctx.cwd, "schemas", forkName);
+    schemaAbs = resolve12(ctx.configDir ?? ctx.cwd, "schemas", forkName);
     assertSchemaWriteWithin(ctx, schemaAbs);
     if (existsSync4(schemaAbs)) {
       throw new DocmetaError(
@@ -8585,7 +9163,7 @@ async function planSchemaMutation(ops, entries, ctx) {
     }
     await assertNotIgnored(
       schemaAbs,
-      dirname5(schemaAbs),
+      dirname6(schemaAbs),
       ctx.cwd,
       ctx.onNotice,
       FORK_IGNORE_TEXT
@@ -8732,18 +9310,18 @@ async function planConfigEdit(ctx, edit, runRefs) {
   if (configPath === void 0 || configDir === void 0) {
     return { changes: [], repointed: false };
   }
-  const text = await readFile8(configPath, "utf8");
-  const doc = parseDocument4(stripBom(text));
+  const text = await readFile9(configPath, "utf8");
+  const doc = parseDocument5(stripBom(text));
   const display = displayPath(ctx, configPath);
   const rawRefOf = (item) => {
-    if (isScalar2(item) && typeof item.value === "string") return item.value;
-    if (isMap3(item)) {
+    if (isScalar3(item) && typeof item.value === "string") return item.value;
+    if (isMap4(item)) {
       const ref = item.get("ref");
       if (typeof ref === "string") return ref;
     }
     return void 0;
   };
-  const rebaseRaw = (raw) => classifyRef(raw).kind === "file" && !isAbsolute3(raw) ? resolve10(configDir, raw) : raw;
+  const rebaseRaw = (raw) => classifyRef(raw).kind === "file" && !isAbsolute4(raw) ? resolve12(configDir, raw) : raw;
   const wantSet = runRefs.map(rebaseRaw).sort().join("\n");
   const seqResolvesToRunSet = (node) => {
     if (!isSeq2(node)) return false;
@@ -8759,10 +9337,10 @@ async function planConfigEdit(ctx, edit, runRefs) {
     for (const item of node.items) {
       const raw = rawRefOf(item);
       if (raw === void 0 || !wants(raw)) continue;
-      if (isScalar2(item)) {
+      if (isScalar3(item)) {
         item.value = spec.newRef;
         n += 1;
-      } else if (isMap3(item)) {
+      } else if (isMap4(item)) {
         item.set("ref", spec.newRef);
         n += 1;
       }
@@ -8774,7 +9352,7 @@ async function planConfigEdit(ctx, edit, runRefs) {
   const overrides = doc.get("overrides", true);
   if (isSeq2(overrides)) {
     for (const entry of overrides.items) {
-      if (isMap3(entry)) repointCount += repoint(entry.get("schemas", true));
+      if (isMap4(entry)) repointCount += repoint(entry.get("schemas", true));
     }
   }
   const repointed = repointCount > 0;
@@ -8783,10 +9361,10 @@ async function planConfigEdit(ctx, edit, runRefs) {
   if (edit.integrity && isSeq2(topSeq)) {
     const wantPath = foldPath(edit.integrity.path);
     for (const item of topSeq.items) {
-      if (!isMap3(item)) continue;
+      if (!isMap4(item)) continue;
       const raw = rawRefOf(item);
       if (raw === void 0 || classifyRef(raw).kind !== "file") continue;
-      const abs = isAbsolute3(raw) ? raw : resolve10(configDir, raw);
+      const abs = isAbsolute4(raw) ? raw : resolve12(configDir, raw);
       if (foldPath(abs) !== wantPath) continue;
       pinFrom = item.get("integrity");
       item.set("integrity", edit.integrity.value);
@@ -9007,7 +9585,7 @@ function buildChanges(diff, entries, sentinel, ctx, renameHints = [], booleanAdd
         `"${file}": no writable format for that extension.`
       );
     }
-    if (existsSync4(resolve10(ctx.base, file))) {
+    if (existsSync4(resolve12(ctx.base, file))) {
       throw new DocmetaError(
         `"${file}" already exists; INSERT creates new files only.`
       );
@@ -9026,26 +9604,81 @@ function buildChanges(diff, entries, sentinel, ctx, renameHints = [], booleanAdd
         `"${from}" -> "${to}": a rename may not change the extension.`
       );
     }
-    if (existsSync4(resolve10(ctx.base, to))) {
+    if (existsSync4(resolve12(ctx.base, to))) {
       throw new DocmetaError(
         `"${to}" already exists; the rename would overwrite it.`
       );
     }
     changes.push({ file: from, renamed: to, written: false });
   }
+  refuseSidecarWrites(changes, entries, ctx);
   return changes;
 }
 function validateNewPath(p, base) {
   const refuse = (why) => {
     throw new DocmetaError(`"${p}" is not a usable path: ${why}.`);
   };
-  if (isAbsolute3(p)) refuse("it is absolute");
+  if (isAbsolute4(p)) refuse("it is absolute");
   if (p.split(/[\\/]/).some((segment) => segment === "..")) {
     refuse("it traverses upward");
   }
-  const abs = resolve10(base, p);
-  if (abs === resolve10(base)) refuse("it points at the corpus root, not a file");
-  if (!abs.startsWith(resolve10(base) + sep2)) refuse("it escapes the corpus");
+  const abs = resolve12(base, p);
+  if (abs === resolve12(base)) refuse("it points at the corpus root, not a file");
+  if (!abs.startsWith(resolve12(base) + sep4)) refuse("it escapes the corpus");
+}
+function refuseSidecarWrites(changes, entries, ctx) {
+  const index = ctx.sidecars;
+  if (!index) return;
+  const owned = (key) => index.owners.get(key);
+  const refuse = (file, key, owner) => {
+    throw new DocmetaError(
+      `"${file}": "${key}" is owned by sidecar ${owner}; edit the sidecar file instead.`
+    );
+  };
+  const data = new Map(entries.map((e) => [e.label, e.extracted.data]));
+  for (const c of changes) {
+    if ("schema" in c || "config" in c) continue;
+    if ("cleared" in c) {
+      for (const key of Object.keys(data.get(c.file) ?? {})) {
+        const owner = owned(key);
+        if (owner !== void 0) refuse(c.file, key, owner);
+      }
+      continue;
+    }
+    if ("created" in c) {
+      for (const key of Object.keys(c.to)) {
+        const owner = owned(key);
+        if (owner !== void 0) refuse(c.file, key, owner);
+      }
+      continue;
+    }
+    if ("renamed" in c) {
+      const entry = index.byPath.get(resolve12(ctx.base, c.file));
+      if (entry !== void 0 && entry.size > 0) {
+        const manifest = [...entry.values()][0]?.file ?? "manifest";
+        throw new DocmetaError(
+          `"${c.file}": sidecar ${manifest} names it; rename the manifest entry first.`
+        );
+      }
+      continue;
+    }
+    const keys = "renamedFrom" in c ? [c.key, c.renamedFrom] : [c.key];
+    for (const key of keys) {
+      const owner = owned(key);
+      if (owner !== void 0) refuse(c.file, key, owner);
+      const byValue = index.byField.get(key);
+      if (byValue === void 0) continue;
+      const raw = data.get(c.file)?.[key];
+      const value = typeof raw === "string" ? raw : typeof raw === "number" || typeof raw === "boolean" ? String(raw) : void 0;
+      const entry = value === void 0 ? void 0 : byValue.get(value);
+      if (entry !== void 0) {
+        const manifest = entry.values().next().value?.file ?? "manifest";
+        throw new DocmetaError(
+          `"${c.file}": "${key}" is the field sidecar ${manifest} joins on, and this document has an entry; change the manifest first.`
+        );
+      }
+    }
+  }
 }
 async function applyChanges(changes, entries, ctx, schemaPlan) {
   const schemaWrites = schemaPlan?.writes ?? [];
@@ -9073,14 +9706,14 @@ async function applyChanges(changes, entries, ctx, schemaPlan) {
   const pendingWrites = [];
   const pendingRenames = [];
   for (const [label, ops] of grouped) {
-    const path = resolve10(ctx.base, label);
+    const path = resolve12(ctx.base, label);
     if (ops.renamedTo !== void 0) {
       if (!existsSync4(path)) {
         throw new DocmetaError(
           `"${label}" is gone from disk since it was read; re-run the query.`
         );
       }
-      const toDisk = resolve10(ctx.base, ops.renamedTo);
+      const toDisk = resolve12(ctx.base, ops.renamedTo);
       if (existsSync4(toDisk)) {
         throw new DocmetaError(
           `"${ops.renamedTo}" appeared on disk since the plan; re-run the query.`
@@ -9113,10 +9746,15 @@ async function applyChanges(changes, entries, ctx, schemaPlan) {
     }
     const entry = byLabel.get(label);
     if (!entry) throw new DocmetaError(`No loaded entry for "${label}".`);
-    const content = await readFile8(path, "utf8");
-    const current = entry.extractor.extract(content, label, {
-      elements: resolveElements(label, ctx.config)
-    });
+    const content = await readFile9(path, "utf8");
+    const current = mergeSidecars(
+      label,
+      entry.extractor.extract(content, label, {
+        elements: resolveElements(label, ctx.config)
+      }),
+      ctx.sidecars,
+      ctx.base
+    ).extracted;
     if (ops.cleared) {
       if (!deepEqual(current.data, entry.extracted.data)) {
         throw new DocmetaError(
@@ -9150,9 +9788,14 @@ async function applyChanges(changes, entries, ctx, schemaPlan) {
       deletions: ops.deletions
     });
     if (ops.deletions.length > 0) {
-      const check = entry.extractor.extract(applied, label, {
-        elements: resolveElements(label, ctx.config)
-      });
+      const check = mergeSidecars(
+        label,
+        entry.extractor.extract(applied, label, {
+          elements: resolveElements(label, ctx.config)
+        }),
+        ctx.sidecars,
+        ctx.base
+      ).extracted;
       for (const key of ops.deletions) {
         if (check.data[key] !== void 0) {
           throw new DocmetaError(
@@ -9175,7 +9818,7 @@ async function applyChanges(changes, entries, ctx, schemaPlan) {
     }
     let now;
     try {
-      now = await readFile8(w.path, "utf8");
+      now = await readFile9(w.path, "utf8");
     } catch {
       now = void 0;
     }
@@ -9186,10 +9829,10 @@ async function applyChanges(changes, entries, ctx, schemaPlan) {
     }
   }
   const dirs = /* @__PURE__ */ new Set();
-  for (const w of schemaWrites) dirs.add(dirname5(w.path));
-  for (const r of pendingRenames) dirs.add(dirname5(r.to));
+  for (const w of schemaWrites) dirs.add(dirname6(w.path));
+  for (const r of pendingRenames) dirs.add(dirname6(r.to));
   for (const p of pendingWrites) {
-    if (p.ensureDir) dirs.add(dirname5(p.path));
+    if (p.ensureDir) dirs.add(dirname6(p.path));
   }
   for (const d of dirs) await mkdir3(d, { recursive: true });
   const writeSchema = async () => {
@@ -9304,8 +9947,8 @@ function skipExpression(sql, from) {
 }
 
 // src/meta/commands/fill.ts
-import { readFile as readFile9 } from "node:fs/promises";
-import { resolve as resolve11, extname as extname6, join as join6 } from "node:path";
+import { readFile as readFile10 } from "node:fs/promises";
+import { resolve as resolve13, extname as extname6, join as join6 } from "node:path";
 import {
   completeValidatedJSON,
   makeProvider,
@@ -9578,6 +10221,11 @@ async function runFill(opts) {
   let turnsUsed = 0;
   let inFlight = 0;
   const turnsExhausted = () => maxTurns != null && turnsUsed + inFlight >= maxTurns;
+  const sidecars = await loadSidecars(config, {
+    configDir: configDir ?? cwd,
+    base,
+    offline: opts.offline ?? config?.offline ?? false
+  });
   const processOne = async (label, content, extension) => {
     const extractor = forcedExtractor ?? extractorForExtension(extension);
     if (!extractor) {
@@ -9596,8 +10244,15 @@ async function runFill(opts) {
     }
     const elements = resolveElements(label, config);
     let extracted;
+    let merged;
     try {
-      extracted = extractor.extract(content, label, { elements });
+      merged = mergeSidecars(
+        label,
+        extractor.extract(content, label, { elements }),
+        sidecars,
+        base
+      );
+      extracted = merged.extracted;
     } catch (err) {
       return errorResult(label, extractor.name, err.message);
     }
@@ -9629,7 +10284,8 @@ async function runFill(opts) {
         extracted.data,
         schemaSet,
         extracted.lineFor,
-        extracted.colFor
+        extracted.colFor,
+        merged.locate
       );
     } catch (err) {
       if (!(err instanceof DocmetaError) || resolved.source !== "document") {
@@ -9643,6 +10299,19 @@ async function runFill(opts) {
       existingErrors,
       only
     );
+    const ownedCandidates = sidecars ? candidates.flatMap((c) => {
+      const file = sidecars.owners.get(c.key);
+      return file === void 0 ? [] : [{ key: c.key, file }];
+    }) : [];
+    const firstOwned = ownedCandidates[0];
+    if (firstOwned) {
+      return errorResult(
+        label,
+        extractor.name,
+        `"${firstOwned.key}" is owned by sidecar ${firstOwned.file}; manni meta fill cannot write a sidecar key. Add it to the manifest instead.`,
+        schemaSet
+      );
+    }
     if (candidates.length === 0) {
       return {
         file: label,
@@ -9783,9 +10452,9 @@ async function runFill(opts) {
     const fields = gate(candidates, proposals, threshold);
     const accepted = fields.filter((f) => f.written);
     if (accepted.length > 0) {
-      const merged = { ...extracted.data, ...patchOf(accepted) };
+      const merged2 = { ...extracted.data, ...patchOf(accepted) };
       const after = await validator.validate(
-        merged,
+        merged2,
         schemaSet,
         extracted.lineFor,
         extracted.colFor
@@ -9829,7 +10498,7 @@ async function runFill(opts) {
     }
     const changed = next !== content;
     if (changed && !dryRun && label !== "<stdin>") {
-      await writeFileAtomic(resolve11(base, label), next);
+      await writeFileAtomic(resolve13(base, label), next);
     }
     return {
       file: label,
@@ -9851,7 +10520,7 @@ async function runFill(opts) {
     );
   }
   const fileResults = await mapConcurrent(files, concurrency, async (file) => {
-    const content = await readFile9(resolve11(base, file), "utf8");
+    const content = await readFile10(resolve13(base, file), "utf8");
     return processOne(file, content, extname6(file));
   });
   results.push(...fileResults);
@@ -10169,15 +10838,19 @@ async function mapConcurrent(items, limit, fn) {
 }
 
 // src/meta/reporters/sarif.ts
-import { isAbsolute as isAbsolute4 } from "node:path";
+import { isAbsolute as isAbsolute5 } from "node:path";
 
 // src/meta/reporters/rule-id.ts
 var SYNTHETIC_SCHEMA = "(parse)";
 var PARSE_ERROR_RULE = "manni/parse-error";
 var SCHEMA_ERROR_RULE = "manni/schema-error";
+var SIDECAR_OWNED_RULE = "sidecar:owned/sidecar";
+var SIDECAR_DUPLICATE_RULE = "sidecar:duplicate/sidecar";
 var RESERVED_RULES = {
   [PARSE_ERROR_RULE]: "The document's metadata block could not be parsed.",
-  [SCHEMA_ERROR_RULE]: "No schema set could be resolved for the document."
+  [SCHEMA_ERROR_RULE]: "No schema set could be resolved for the document.",
+  [SIDECAR_OWNED_RULE]: "The document carries a key a sidecar manifest owns; the manifest is the only place that key may be set.",
+  [SIDECAR_DUPLICATE_RULE]: "Two documents carry the same value of a sidecar's join field, so one manifest entry matched both."
 };
 function ruleIdFor(e, frame) {
   if (e.schema === SYNTHETIC_SCHEMA) {
@@ -10205,7 +10878,7 @@ function uriFrame(frame) {
 }
 function artifactUri(file, frame) {
   const uri = canonicalFilePath(file, frame);
-  if (uri === "" || uri.startsWith("../") || isAbsolute4(uri)) return null;
+  if (uri === "" || uri.startsWith("../") || isAbsolute5(uri)) return null;
   return uri;
 }
 function renderSarif(results, opts = {}) {
@@ -10219,12 +10892,13 @@ function renderSarif(results, opts = {}) {
   for (const r of results) {
     if (r.errors.length === 0) continue;
     if (r.file === STDIN_LABEL) continue;
-    const uri = artifactUri(r.file, pathFrame);
-    if (uri === null) {
-      dropped += r.errors.length;
-      continue;
-    }
+    const docUri = artifactUri(r.file, pathFrame);
     for (const e of r.errors) {
+      const uri = e.file != null ? artifactUri(e.file, pathFrame) : docUri;
+      if (uri === null) {
+        dropped += 1;
+        continue;
+      }
       const ruleId = ruleIdFor(e, frame);
       if (!rules.has(ruleId)) {
         rules.set(ruleId, {
@@ -10332,7 +11006,7 @@ function renderJunit(results, opts = {}) {
     }
     lines.push(`${open2}>`);
     for (const e of r.errors) {
-      const where = e.line != null ? ` (line ${e.line})` : "";
+      const where = e.file != null ? ` (${e.file}${e.line != null ? `:${e.line}` : ""})` : e.line != null ? ` (line ${e.line})` : "";
       lines.push(
         `      <failure${attr("type", ruleIdFor(e, opts.frame))}${attr(
           "message",
@@ -10346,7 +11020,7 @@ function renderJunit(results, opts = {}) {
   return lines.join("\n");
 }
 
-// src/meta/reporters/color.ts
+// src/shared/color.ts
 import pc from "picocolors";
 function palette(enabled) {
   return pc.createColors(enabled);
@@ -10358,7 +11032,7 @@ function shouldColor(opts) {
   return Boolean(opts.isTTY);
 }
 
-// src/meta/reporters/github.ts
+// src/shared/github.ts
 function escapeWorkflowCommandMessage(message) {
   return message.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
 }
@@ -10441,7 +11115,7 @@ function renderPretty(results, summary, opts = {}) {
     }
     lines.push(`${c.red("\u2717")} ${r.file}${forgiven}`);
     for (const e of r.errors) {
-      const loc = e.line != null ? c.dim(`  (line ${e.line})`) : "";
+      const loc = e.file != null ? c.dim(`  (${e.file}${e.line != null ? `:${e.line}` : ""})`) : e.line != null ? c.dim(`  (line ${e.line})`) : "";
       lines.push(
         `    ${c.cyan(fieldLabel(e.instancePath))}  ${e.message}${loc}  ${c.dim(
           `[${e.schema}]`
@@ -10465,7 +11139,7 @@ function renderGithub(results) {
   const lines = [];
   for (const r of results) {
     for (const e of r.errors) {
-      const params = [`file=${escapeWorkflowCommandProperty(r.file)}`];
+      const params = [`file=${escapeWorkflowCommandProperty(e.file ?? r.file)}`];
       if (e.line != null) params.push(`line=${e.line}`);
       if (e.col != null) params.push(`col=${e.col}`);
       const msg = escapeWorkflowCommandMessage(
@@ -10739,9 +11413,15 @@ function cellFrom(value) {
 
 export {
   package_default,
+  palette,
+  shouldColor,
+  ToolError,
   programName,
   setProgramName,
-  ToolError,
+  findConfigFile,
+  readConfigFile,
+  escapeWorkflowCommandMessage,
+  escapeWorkflowCommandProperty,
   DocmetaError,
   toJsonText,
   writeFileAtomic,
@@ -10758,17 +11438,32 @@ export {
   fetchSchemaBytes,
   schemaLoadOptions,
   loadSchema,
+  DEFAULT_SCHEMAS,
+  schemaEntryRef,
+  collectSchemaPins,
+  rebaseConfigSchemaRefs,
+  resolveSchemaSet,
+  SIDECAR_FETCH_TIMEOUT_MS,
+  SIDECAR_FETCH_MAX_BYTES,
+  sidecarUrlProblem,
+  fetchSidecar,
   locateFrontmatter,
   frontmatterInnerText,
   extractFrontmatter,
   applyFrontmatter,
   extractorForExtension,
   supportedExtensions,
-  DEFAULT_SCHEMAS,
-  schemaEntryRef,
-  collectSchemaPins,
-  rebaseConfigSchemaRefs,
-  resolveSchemaSet,
+  SIDECAR_OWNED_SCHEMA,
+  SIDECAR_DUPLICATE_SCHEMA,
+  SIDECAR_KEYWORD,
+  PATH_JOIN,
+  sidecarJoin,
+  loadSidecars,
+  mergeSidecars,
+  sidecarPointer,
+  orphanEntries,
+  orphanJoins,
+  orphanError,
   parseConfig,
   loadConfig,
   resolveRunConfig,
@@ -10784,8 +11479,6 @@ export {
   runInferSchema,
   runQuery,
   runFill,
-  palette,
-  shouldColor,
   renderSarif,
   renderJunit,
   REPORT_FORMATS,
@@ -10811,4 +11504,4 @@ export {
   renderQuery,
   renderQueryCsv
 };
-//# sourceMappingURL=chunk-Y6FSY35O.js.map
+//# sourceMappingURL=chunk-7M2YOXVG.js.map