@madewithremy/admin 0.1.30 → 0.1.32

package/dist/prod.js

@@ -36,10 +36,10 @@ function fatal(message) {
   throw new CliError(message);
 }
 var AdminApiError = class extends Error {
-  constructor(method, path7, status2, body) {
-    super(`API ${method} ${path7} returned ${status2}: ${JSON.stringify(body)}`);
+  constructor(method, path8, status2, body) {
+    super(`API ${method} ${path8} returned ${status2}: ${JSON.stringify(body)}`);
     this.method = method;
-    this.path = path7;
+    this.path = path8;
     this.status = status2;
     this.body = body;
     this.name = "AdminApiError";
@@ -1036,6 +1036,13 @@ function summarizeRelease(release) {
     publishedAt: release.publishedAt ?? null,
     ...release.previewUrl ? { previewUrl: release.previewUrl } : {}
   };
+  const readers = (release.dataSources ?? []).filter((d) => d.reader);
+  if (readers.length > 0 && release.status === "live") {
+    summary2.readers = readers.map((d) => ({
+      slug: d.slug,
+      unread: d.readerUnread ?? 0
+    }));
+  }
   if (release.status !== "failed") {
     return summary2;
   }
@@ -2939,7 +2946,7 @@ var filesSpecs = {
     usage: "Usage: remy-admin files list"
   },
   "files rm": {
-    usage: "Usage: remy-admin files rm --store <name> --key <key> [--private]",
+    usage: "Usage: remy-admin files rm --store <name> --key <key> [--public|--private]",
     flags: {
       ...ACCESS_FLAGS,
       store: { type: "string" },
@@ -2950,6 +2957,45 @@ var filesSpecs = {
 function resolveAccess(a) {
   return a.bool("private") ? "private" : "public";
 }
+async function readAccess(ctx, a, key) {
+  if (a.bool("private")) {
+    return "private";
+  }
+  if (a.bool("public")) {
+    return "public";
+  }
+  const store = storeOf(a);
+  const { stores } = await summary(ctx);
+  const held = stores.filter((s) => s.store === store && s.objectCount > 0);
+  if (held.length === 1) {
+    return held[0].access;
+  }
+  if (held.length === 0) {
+    if (key === void 0) {
+      return "public";
+    }
+    fatal(`Store "${store}" holds no objects, public or private.`);
+  }
+  if (key === void 0) {
+    const counts = held.map((s) => `${s.objectCount.toLocaleString()} ${s.access}`).join(", ");
+    fatal(
+      `Store "${store}" holds objects in both halves (${counts}): pass --public or --private.`
+    );
+  }
+  for (const access of ["private", "public"]) {
+    try {
+      await stat(ctx, { store, access, key });
+      return access;
+    } catch (err) {
+      if (!(err instanceof AdminApiError) || err.status !== 404) {
+        throw err;
+      }
+    }
+  }
+  fatal(
+    `No object "${key}" in store "${store}" (looked in its private and public halves).`
+  );
+}
 function storeOf(a) {
   return a.str("store") || DEFAULT_STORE;
 }
@@ -2960,8 +3006,8 @@ function requireKeyFlag(a) {
   }
   return key;
 }
-function refOf(a, key) {
-  return { store: storeOf(a), access: resolveAccess(a), key };
+async function refOf(ctx, a, key) {
+  return { store: storeOf(a), access: await readAccess(ctx, a, key), key };
 }
 async function filesPut(ctx, a) {
   const file = a.req("file");
@@ -2987,7 +3033,7 @@ async function filesPut(ctx, a) {
 }
 async function filesGet(ctx, a) {
   const key = a.req("key");
-  const ref = refOf(a, key);
+  const ref = await refOf(ctx, a, key);
   const { url } = await sign(
     ctx,
     ref,
@@ -2997,7 +3043,9 @@ async function filesGet(ctx, a) {
   const abs = path2.isAbsolute(outPath) ? outPath : path2.join(WORKSPACE_DIR, outPath);
   const res = await fetch(url);
   if (!res.ok || !res.body) {
-    fatal(`Download failed: ${res.status} ${res.statusText}`);
+    fatal(
+      res.status === 403 || res.status === 404 ? `No object "${key}" in the ${ref.access} half of store "${ref.store}" (download answered ${res.status}).` : `Download failed: ${res.status} ${res.statusText}`
+    );
   }
   await pipeline(
     Readable.fromWeb(res.body),
@@ -3006,16 +3054,18 @@ async function filesGet(ctx, a) {
   out({ path: abs, size: fs2.statSync(abs).size });
 }
 async function filesSign(ctx, a) {
-  out(await sign(ctx, refOf(a, requireKeyFlag(a)), a.num("ttl")));
+  out(
+    await sign(ctx, await refOf(ctx, a, requireKeyFlag(a)), a.num("ttl"))
+  );
 }
 async function filesStat(ctx, a) {
-  out(await stat(ctx, refOf(a, requireKeyFlag(a))));
+  out(await stat(ctx, await refOf(ctx, a, requireKeyFlag(a))));
 }
 async function filesLs(ctx, a) {
   out(
     await ls(ctx, {
       store: storeOf(a),
-      access: resolveAccess(a),
+      access: await readAccess(ctx, a),
       prefix: a.str("prefix"),
       q: a.str("q"),
       cursor: a.str("cursor"),
@@ -3035,7 +3085,13 @@ async function filesRm(ctx, a) {
   if (!key) {
     fatal("--key is required.");
   }
-  out(await remove(ctx, { store, access: resolveAccess(a), key }));
+  out(
+    await remove(ctx, {
+      store,
+      access: await readAccess(ctx, a, key),
+      key
+    })
+  );
 }
 var filesHandlers = {
   "files put": filesPut,
@@ -3059,12 +3115,12 @@ Subcommands:
 
 Usage:
   remy-admin files put [--public|--private] [--store <name>] [--key <key>] [--cache-control <value>] <file>
-  remy-admin files get [--private] [--store <name>] [--out <path>] <key>
-  remy-admin files sign [--private] [--store <name>] [--ttl <seconds>] --key <key>
-  remy-admin files stat [--private] [--store <name>] --key <key>
-  remy-admin files ls [--private] [--store <name>] [--prefix <prefix>] [--q <substring>] [--limit <n>]
+  remy-admin files get [--public|--private] [--store <name>] [--out <path>] <key>
+  remy-admin files sign [--public|--private] [--store <name>] [--ttl <seconds>] --key <key>
+  remy-admin files stat [--public|--private] [--store <name>] --key <key>
+  remy-admin files ls [--public|--private] [--store <name>] [--prefix <prefix>] [--q <substring>] [--limit <n>]
   remy-admin files list
-  remy-admin files rm --store <name> --key <key> [--private]
+  remy-admin files rm --store <name> --key <key> [--public|--private]
 
 Examples:
   remy-admin files put --public ./hero.jpg
@@ -3074,7 +3130,10 @@ Examples:
   remy-admin files rm --store handoff --key <key> --private
 
 Notes:
-  - Defaults to a public store named 'assets'; pass --private / --store to change.
+  - Defaults to the store named 'assets'. put writes public unless --private.
+    Reads (get, sign, stat, ls, rm) without --public or --private use the half
+    of the store that holds objects; in a store holding both, a key is found
+    wherever it is, and ls asks which.
   - Handing someone a large or sensitive file? Use a PRIVATE store + \`sign\`:
     the link is unguessable, expires (--ttl seconds, max 7 days), and the object
     stays deletable with \`rm\`. Never use the account media CDN
@@ -3092,8 +3151,8 @@ Notes:
   - Public image URLs accept transform params, e.g. ?w=400&fit=cover.`;
 
 // src/commands/dataSources.ts
-import fs5 from "fs";
-import path5 from "path";
+import fs6 from "fs";
+import path6 from "path";
 
 // src/ops/dataSources.ts
 import { createHash as createHash2 } from "crypto";
@@ -3111,7 +3170,7 @@ var summarize = (d) => ({
   ...d.errorMessage ? { error: d.errorMessage } : {}
 });
 async function addDocument(ctx, params) {
-  const { slug, filename, content, metadata, onProgress } = params;
+  const { slug, filename, content, metadata, entities: entities2, onProgress } = params;
   const contentHash = createHash2("sha256").update(content).digest("hex");
   const token = await call(
     ctx,
@@ -3121,7 +3180,8 @@ async function addDocument(ctx, params) {
       slug,
       filename,
       contentHash,
-      ...metadata ? { metadata } : {}
+      ...metadata ? { metadata } : {},
+      ...entities2 ? { entities: entities2 } : {}
     }
   );
   if (token.alreadyCurrent) {
@@ -3147,7 +3207,8 @@ async function addDocument(ctx, params) {
       contentHash,
       contentType: token.contentType,
       size: content.length,
-      ...metadata ? { metadata } : {}
+      ...metadata ? { metadata } : {},
+      ...entities2 ? { entities: entities2 } : {}
     }
   );
   return {
@@ -3324,6 +3385,35 @@ function count(ctx, params) {
     ...candidate ? { candidate: true } : {}
   });
 }
+function entities(ctx, params) {
+  const { slug, filter, limit, candidate } = params;
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/entities`,
+    {
+      slug,
+      ...filter ? { filter } : {},
+      ...limit !== void 0 ? { limit } : {},
+      ...candidate ? { candidate: true } : {}
+    }
+  );
+}
+function passages(ctx, params) {
+  const { slug, filter, cursor, limit, candidate } = params;
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/passages`,
+    {
+      slug,
+      ...filter ? { filter } : {},
+      ...cursor ? { cursor } : {},
+      ...limit !== void 0 ? { limit } : {},
+      ...candidate ? { candidate: true } : {}
+    }
+  );
+}
 function configGet(ctx, slug) {
   return call(
     ctx,
@@ -3485,6 +3575,67 @@ function deleteSource(ctx, slug) {
     { slug }
   );
 }
+var DICTIONARY_PAGE_ENTRIES = 1e4;
+var DICTIONARY_PAGE_BYTES = 4e6;
+async function pushDictionary(ctx, params) {
+  const { slug, entries } = params;
+  const stage = await call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/dictionary/stage`,
+    {
+      slug,
+      ...params.linkerVersion !== void 0 ? { linkerVersion: params.linkerVersion } : {}
+    }
+  );
+  const perPage = Math.min(
+    DICTIONARY_PAGE_ENTRIES,
+    stage.pageMaxEntries || DICTIONARY_PAGE_ENTRIES
+  );
+  let pages2 = 0;
+  let start2 = 0;
+  while (start2 < entries.length) {
+    let end = start2;
+    let bytes = 0;
+    while (end < entries.length && end - start2 < perPage) {
+      const size = JSON.stringify(entries[end]).length;
+      if (end > start2 && bytes + size > DICTIONARY_PAGE_BYTES) {
+        break;
+      }
+      bytes += size;
+      end += 1;
+    }
+    await call(ctx, "POST", `${base(ctx.appId)}/dictionary/page`, {
+      slug,
+      stageId: stage.stageId,
+      page: pages2,
+      entries: entries.slice(start2, end)
+    });
+    pages2 += 1;
+    start2 = end;
+    params.onProgress?.(start2, entries.length);
+  }
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/dictionary/commit`,
+    { slug, stageId: stage.stageId, pages: pages2 }
+  );
+}
+function dictionary(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/dictionary`,
+    { slug: params.slug }
+  );
+}
+function link(ctx, params) {
+  return call(ctx, "POST", `${base(ctx.appId)}/link`, {
+    slug: params.slug,
+    text: params.text
+  });
+}
 
 // src/ops/dataSourceJobs.ts
 var DEFAULT_WAIT_TIMEOUT_MS2 = 60 * 60 * 1e3;
@@ -3643,6 +3794,39 @@ function describeProgress(job, start2) {
 // src/commands/_shared/dataSources.ts
 var DEFAULT_SOURCE = "default";
 var sourceOf = (a) => a.str("source") || DEFAULT_SOURCE;
+function parseKeyValuePairs(raw, flag) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const pairs2 = {};
+  for (const part of raw.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      fatal(`--${flag} entries must be key=value (got "${trimmed}").`);
+    }
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    pairs2[key] = value === "true" ? true : value === "false" ? false : value !== "" && !Number.isNaN(Number(value)) ? Number(value) : value;
+  }
+  if (Object.keys(pairs2).length === 0) {
+    fatal(`--${flag} needs at least one key=value pair.`);
+  }
+  return pairs2;
+}
+function documentSelectorOf(raw) {
+  if (raw.trimStart().startsWith("{")) {
+    try {
+      return JSON.parse(raw);
+    } catch (err) {
+      fatal(`--filter is not valid JSON: ${err.message}`);
+    }
+  }
+  return { metadata: parseKeyValuePairs(raw, "filter") };
+}
 var timeoutOf = (a) => {
   const seconds = a.str("timeout");
   return seconds ? { timeoutMs: Number(seconds) * 1e3 } : {};
@@ -4658,9 +4842,118 @@ Retrieval evals:
   with --candidate, compare, promote or drop.
 `;
 
-// src/commands/dataSourceJobs.ts
+// src/commands/dataSourceDictionary.ts
 import fs4 from "fs";
 import path4 from "path";
+var dataSourceDictionarySpecs = {
+  "datasources dictionary push": {
+    usage: "Usage: remy-admin datasources dictionary push [--source <slug>] [--linker-version <n>] <file.jsonl>",
+    positionals: [{ name: "file", required: true }],
+    flags: {
+      source: { type: "string" },
+      "linker-version": { type: "number", min: 1 }
+    }
+  },
+  "datasources dictionary status": {
+    usage: "Usage: remy-admin datasources dictionary status [--source <slug>]",
+    flags: {
+      source: { type: "string" }
+    }
+  },
+  "datasources link": {
+    usage: "Usage: remy-admin datasources link [--source <slug>] <text>",
+    positionals: [{ name: "text", required: true }],
+    flags: {
+      source: { type: "string" }
+    }
+  }
+};
+function readEntries(file) {
+  const abs = path4.isAbsolute(file) ? file : path4.join(WORKSPACE_DIR, file);
+  let content;
+  try {
+    content = fs4.readFileSync(abs, "utf8");
+  } catch (err) {
+    fatal(`Could not read "${file}": ${err.message}`);
+  }
+  const entries = [];
+  content.split("\n").forEach((line, i) => {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      fatal(`${file}:${i + 1} is not valid JSON.`);
+    }
+    if (typeof parsed?.id !== "string" || !Array.isArray(parsed?.names) || !parsed.names.every((name) => typeof name === "string")) {
+      fatal(`${file}:${i + 1} needs { "id": "...", "names": ["...", ...] }.`);
+    }
+    entries.push({ id: parsed.id, names: parsed.names });
+  });
+  if (entries.length === 0) {
+    fatal(`"${file}" has no entries.`);
+  }
+  return entries;
+}
+async function dictionaryPush(ctx, a) {
+  const entries = readEntries(a.req("file"));
+  const linkerVersion = a.num("linker-version");
+  out(
+    await pushDictionary(ctx, {
+      slug: sourceOf(a),
+      entries,
+      ...linkerVersion !== void 0 ? { linkerVersion } : {},
+      onProgress: (sent, total) => progress(`pushing ${sent.toLocaleString()}/${total.toLocaleString()}\u2026`)
+    })
+  );
+}
+async function dictionaryStatus(ctx, a) {
+  out(await dictionary(ctx, { slug: sourceOf(a) }));
+}
+async function link2(ctx, a) {
+  out(await link(ctx, { slug: sourceOf(a), text: a.req("text") }));
+}
+var dataSourceDictionaryHandlers = {
+  "datasources dictionary push": dictionaryPush,
+  "datasources dictionary status": dictionaryStatus,
+  "datasources link": link2
+};
+var dataSourceDictionaryHelp = `
+Dictionary:
+  remy-admin datasources dictionary push [--source <slug>] [--linker-version <n>] <file.jsonl>
+  remy-admin datasources dictionary status [--source <slug>]
+  remy-admin datasources link [--source <slug>] <text>
+
+  A dictionary is your own entity ids and the names each goes by, a
+  projection of your tables: one JSONL line per entry,
+  {"id": "P-101A", "names": ["P-101A", "Main Feed Pump"]}. Push it whole; it
+  replaces the source's dictionary. From then on every passage carries the
+  ids whose names its text mentions, beside the ones its document asserts,
+  so --entities on search and count, and \`datasources entities\`, find a tag
+  wherever it's written. Passages indexed before are re-tagged in the
+  background (a relink; \`dictionary status\` shows it), with nothing
+  re-embedded. An unchanged dictionary commits nothing.
+
+  Matching ignores case and a tag's separators (P-101A, P101A, p 101a) and
+  an inch or foot mark after a size (8"-P-1057-A1A is 8-P-1057-A1A), takes
+  whole words only (P-101AB is not P-101A), and prefers the longest name; a
+  name two ids claim tags both. A name needs three letters or digits (two in
+  Chinese, Japanese or Korean). The push reports ambiguous names, the most
+  claimed (each with one name as pushed), and names that can't match their
+  own text as written (\`unmatchable\`). Up to 250,000 entries, 16 names
+  each, a million names.
+
+  \`link\` shows what the current dictionary finds in any text: check one
+  there before relying on it. --linker-version moves a dictionary to a newer
+  matching rule; without it a push keeps the one its dictionary has.
+`;
+
+// src/commands/dataSourceJobs.ts
+import fs5 from "fs";
+import path5 from "path";
 var dataSourceJobsSpecs = {
   "datasources jobs start": {
     usage: "Usage: remy-admin datasources jobs start [--source <slug>] (--store <name> [--access <private|public>] [--prefix <p>] | --manifest <file.jsonl>) [--limit <n>] [--budget <dollars>] [--concurrency <n>] [--priority] [--approve] [--wait] [--timeout <sec>]",
@@ -4738,10 +5031,10 @@ async function jobsStart(ctx, a) {
   }
   let source;
   if (manifest) {
-    const abs = path4.isAbsolute(manifest) ? manifest : path4.join(WORKSPACE_DIR, manifest);
+    const abs = path5.isAbsolute(manifest) ? manifest : path5.join(WORKSPACE_DIR, manifest);
     let content;
     try {
-      content = fs4.readFileSync(abs);
+      content = fs5.readFileSync(abs);
     } catch (err) {
       fatal(`Could not read manifest "${manifest}": ${err.message}`);
     }
@@ -4867,12 +5160,13 @@ Bulk ingestion (jobs):
   A job loads a whole corpus at once. It reads either every object under a
   prefix of one of the app's file stores (\`files put\` fills one; an app can
   write one at runtime) or a manifest you upload: JSONL, one line per document,
-  {"url": "https://\u2026", "filename": "x.pdf", "externalId": "\u2026", "metadata": {\u2026}}.
-  filename, externalId and metadata are optional; the URL must be public.
+  {"url": "https://\u2026", "filename": "x.pdf", "externalId": "\u2026", "metadata": {\u2026},
+  "entities": ["\u2026"]}. Everything but the URL is optional; it must be public.
 
-  Nothing is spent until you say so. The platform counts the source, reads a
-  sample of about a hundred documents, and writes a plan: documents, chunks,
-  cost per stage (embedding, extraction, contextual) at today's rates, storage,
+  Nothing past the sample runs until you say so. The platform counts the
+  source, reads a sample of about a hundred documents, and writes a plan:
+  documents, chunks, cost per stage (embedding, extraction, contextual, and
+  the mapper's own model calls, priced from the sample's) at today's rates, storage,
   whether it fits where the source lives, and a duration. \`jobs status\` shows
   it; \`jobs approve\` starts the run. Two gates: the corpus has to fit the
   source's placement (a shared-pool source over the per-source cap answers
@@ -4954,7 +5248,8 @@ function mapTest(ctx, params) {
       ...selectionBody(params.selection),
       ...params.keys ? { keys: params.keys } : {},
       ...params.limit !== void 0 ? { limit: params.limit } : {},
-      ...params.dev ? { dev: true } : {}
+      ...params.dev ? { dev: true } : {},
+      ...params.releaseId ? { releaseId: params.releaseId } : {}
     }
   );
 }
@@ -4982,6 +5277,7 @@ function quarantine(ctx, params) {
     "GET",
     `${base5(ctx.appId)}/jobs/${params.id}/quarantine${qs({
       ...params.kind ? { kind: params.kind } : {},
+      ...params.stage ? { stage: params.stage } : {},
       ...params.reason ? { reason: params.reason } : {},
       ...params.cursor ? { cursor: params.cursor } : {},
       ...params.limit !== void 0 ? { limit: params.limit } : {}
@@ -5019,12 +5315,13 @@ var dataSourceMappersSpecs = {
     }
   },
   "datasources map test": {
-    usage: "Usage: remy-admin datasources map test [--source <slug>] (--store <name> [--access <private|public>] [--prefix <p>] | --connector) [--keys k1,k2,...] [--limit <n>] [--dev] [--full]",
+    usage: "Usage: remy-admin datasources map test [--source <slug>] (--store <name> [--access <private|public>] [--prefix <p>] | --connector) [--keys k1,k2,...] [--limit <n>] [--dev [--release <dev-release-id>]] [--full]",
     flags: {
       source: { type: "string" },
       ...SELECTION_FLAGS,
       limit: { type: "number", min: 1 },
       dev: { type: "boolean" },
+      release: { type: "string" },
       full: { type: "boolean" }
     },
     requireAnyOf: {
@@ -5050,10 +5347,11 @@ var dataSourceMappersSpecs = {
     }
   },
   "datasources jobs quarantine": {
-    usage: "Usage: remy-admin datasources jobs quarantine <id> [--kind skip|error] [--reason <text>] [--cursor <id>] [--limit <n>]",
+    usage: "Usage: remy-admin datasources jobs quarantine <id> [--kind skip|error] [--stage map|read] [--reason <text>] [--cursor <id>] [--limit <n>]",
     positionals: [{ name: "id", required: true }],
     flags: {
       kind: { type: "string" },
+      stage: { type: "string" },
       reason: { type: "string" },
       cursor: { type: "string" },
       limit: { type: "number", min: 1 }
@@ -5135,7 +5433,8 @@ async function mapTest2(ctx, a) {
     selection: selectionOf(a),
     ...keysOf(a) ? { keys: keysOf(a) } : {},
     ...limit !== void 0 ? { limit } : {},
-    ...a.bool("dev") ? { dev: true } : {}
+    ...a.bool("dev") ? { dev: true } : {},
+    ...a.str("release") ? { releaseId: a.str("release") } : {}
   });
   const results = a.bool("full") ? result.results : result.results.map(
     (r) => r.outcome.kind === "documents" ? {
@@ -5206,18 +5505,32 @@ async function quarantine2(ctx, a) {
   const id = a.req("id");
   const limit = a.num("limit");
   const kind = kindOf(a);
+  const stage = a.str("stage");
+  if (stage !== void 0 && stage !== "map" && stage !== "read") {
+    fatal(`--stage must be "map" or "read" (got "${stage}").`);
+  }
   const reason = a.str("reason");
   const cursor = a.str("cursor");
   const result = await quarantine(ctx, {
     id,
     ...kind ? { kind } : {},
+    ...stage ? { stage } : {},
     ...reason ? { reason } : {},
     ...cursor ? { cursor } : {},
     ...limit !== void 0 ? { limit } : {}
   });
+  const { skipped, errors, readErrors } = result.counts;
+  const notes = [
+    ...skipped + errors > 0 ? [
+      `Mapping: fix the mapper, push, \`datasources map deploy\`, then \`datasources jobs replay ${id}\` to run these through it again.`
+    ] : [],
+    ...readErrors > 0 ? [
+      `Reading: fix the reader and publish, then \`datasources reader retry --source ${result.dataSource.slug} --job ${id}\` reads these again.`
+    ] : []
+  ];
   out({
     ...result,
-    note: result.counts.skipped + result.counts.errors === 0 ? "Nothing quarantined: the mapper produced documents (or deletions) for every object." : `Fix the mapper, push, \`datasources map deploy\`, then \`datasources jobs replay ${id}\` to run these through it again.`
+    note: notes.length === 0 ? "Nothing quarantined: the mapper produced documents (or deletions) for every object, and the reader read every document." : notes.join(" ")
   });
 }
 async function replay2(ctx, a) {
@@ -5255,10 +5568,10 @@ var dataSourceMappersHandlers = {
 var dataSourceMappersHelp = `
 Mapping raw objects into documents (mappers):
   remy-admin datasources inspect [--source <slug>] (--store <name> [--prefix <p>] | --connector) [--keys k1,k2] [--limit <n>]
-  remy-admin datasources map test [--source <slug>] (--store <name> [--prefix <p>] | --connector) [--keys k1,k2] [--limit <n>] [--dev] [--full]
+  remy-admin datasources map test [--source <slug>] (--store <name> [--prefix <p>] | --connector) [--keys k1,k2] [--limit <n>] [--dev [--release <id>]] [--full]
   remy-admin datasources map deploy [--source <slug>] [--release <id>]
   remy-admin datasources remap [--source <slug>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]
-  remy-admin datasources jobs quarantine <id> [--kind skip|error] [--reason <text>] [--cursor <id>] [--limit <n>]
+  remy-admin datasources jobs quarantine <id> [--kind skip|error] [--stage map|read] [--reason <text>] [--cursor <id>] [--limit <n>]
   remy-admin datasources jobs replay <id> [--kind skip|error] [--wait] [--timeout <sec>]
 
   A source takes every object it is given as one document. When the file is
@@ -5299,6 +5612,234 @@ Mapping raw objects into documents (mappers):
   pauses with pauseReason 'skips' for a look at the quarantine.
 `;
 
+// src/ops/dataSourceReaders.ts
+function base6(appId) {
+  return `/_internal/v2/apps/${appId}/datasources`;
+}
+function readerTest(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reader/test`,
+    {
+      slug: params.slug,
+      ...params.documents ? { documents: params.documents } : {},
+      ...params.limit !== void 0 ? { limit: params.limit } : {},
+      ...params.releaseId ? { releaseId: params.releaseId } : {}
+    }
+  );
+}
+function readerStatus(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reader/status`,
+    { slug: params.slug }
+  );
+}
+function readerRetry(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reader/retry`,
+    {
+      slug: params.slug,
+      ...params.jobId ? { jobId: params.jobId } : {}
+    }
+  );
+}
+function reread(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reread`,
+    {
+      slug: params.slug,
+      ...params.unread ? { unread: true } : {},
+      ...params.filter ? { filter: params.filter } : {},
+      ...params.budgetDollars !== void 0 ? { budgetDollars: params.budgetDollars } : {},
+      ...params.limit !== void 0 ? { limit: params.limit } : {}
+    }
+  );
+}
+
+// src/commands/dataSourceReaders.ts
+var dataSourceReadersSpecs = {
+  "datasources reader test": {
+    usage: "Usage: remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2,...] [--limit <n>] [--release <dev-release-id>]",
+    flags: {
+      source: { type: "string" },
+      dev: { type: "boolean" },
+      documents: { type: "string" },
+      limit: { type: "number", min: 1 },
+      release: { type: "string" }
+    }
+  },
+  "datasources reader status": {
+    usage: "Usage: remy-admin datasources reader status [--source <slug>]",
+    flags: {
+      source: { type: "string" }
+    }
+  },
+  "datasources reader retry": {
+    usage: "Usage: remy-admin datasources reader retry [--source <slug>] [--job <id>]",
+    flags: {
+      source: { type: "string" },
+      job: { type: "string" }
+    }
+  },
+  "datasources reread": {
+    usage: "Usage: remy-admin datasources reread [--source <slug>] [--unread] [--filter <k=v,...|json>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]",
+    flags: {
+      source: { type: "string" },
+      unread: { type: "boolean" },
+      filter: { type: "string" },
+      budget: { type: "number", min: 0.01 },
+      limit: { type: "number", min: 1 },
+      wait: { type: "boolean" },
+      timeout: { type: "string" }
+    }
+  }
+};
+async function readerTest2(ctx, a) {
+  if (!a.bool("dev")) {
+    fatal(
+      "reader test runs the dev session's reader only: pass --dev. The live reader reads through deliveries and `datasources reread`."
+    );
+  }
+  const slug = sourceOf(a);
+  const raw = a.str("documents");
+  const documents2 = raw?.split(",").map((id) => id.trim()).filter(Boolean);
+  if (raw !== void 0 && documents2?.length === 0) {
+    fatal("--documents needs at least one document id.");
+  }
+  const limit = a.num("limit");
+  const result = await readerTest(ctx, {
+    slug,
+    ...documents2 ? { documents: documents2 } : {},
+    ...limit !== void 0 ? { limit } : {},
+    ...a.str("release") ? { releaseId: a.str("release") } : {}
+  });
+  out({
+    dataSource: slug,
+    ...result,
+    note: "Ran the LOCAL reader through the dev session, writing into the dev session's database. Query its tables to check what it wrote; publish to make it the live reader, then `datasources reread --unread` reads what it has not."
+  });
+  if (result.failed > 0) {
+    throw new CliError(
+      `The reader failed on ${result.failed} of ${result.documents.length} document(s).`,
+      EXIT.buildFailed
+    );
+  }
+}
+async function readerStatus2(ctx, a) {
+  const slug = sourceOf(a);
+  const result = await readerStatus(ctx, { slug });
+  const { reader, deliveries, documents: documents2 } = result;
+  out({
+    dataSource: slug,
+    ...result,
+    note: !reader ? `The live release declares no reader for "${slug}". Declare one in mindstudio.json's dataSources and publish.` : deliveries.parked > 0 ? `${deliveries.parked} delivery(ies) failed six times and parked. Fix the reader and publish, then \`datasources reader retry\`.` : documents2.unread > 0 ? `${documents2.unread.toLocaleString()} live document(s) not read yet. \`datasources reread --unread\` plans reading them.` : "Every live document has been read."
+  });
+}
+async function readerRetry2(ctx, a) {
+  const slug = sourceOf(a);
+  const jobId = a.str("job");
+  const result = await readerRetry(ctx, {
+    slug,
+    ...jobId ? { jobId } : {}
+  });
+  out({
+    dataSource: slug,
+    ...jobId ? { job: jobId } : {},
+    ...result,
+    note: result.retried === 0 ? jobId ? `Job ${jobId}'s reader failed on nothing.` : "Nothing parked." : `Queued ${result.retried.toLocaleString()} delivery(ies) again; \`datasources reader status\` shows them drain.`
+  });
+}
+async function reread2(ctx, a) {
+  const slug = sourceOf(a);
+  const raw = a.str("filter");
+  const budget = a.num("budget");
+  const limit = a.num("limit");
+  const { job } = await reread(ctx, {
+    slug,
+    ...a.bool("unread") ? { unread: true } : {},
+    ...raw !== void 0 ? { filter: documentSelectorOf(raw) } : {},
+    ...budget !== void 0 ? { budgetDollars: budget } : {},
+    ...limit !== void 0 ? { limit } : {}
+  });
+  if (!a.bool("wait")) {
+    out({
+      dataSource: slug,
+      job,
+      note: `Planning: the reread prices reading from the reader's history, or reads a first slice for real to measure it. \`datasources jobs status ${job.id}\` shows the plan; \`datasources jobs approve ${job.id}\` runs it.`
+    });
+    return;
+  }
+  await waitAndReport(ctx, a, job.id, "plan", {
+    dataSource: slug,
+    action: "reread"
+  });
+}
+var dataSourceReadersHandlers = {
+  "datasources reader test": readerTest2,
+  "datasources reader status": readerStatus2,
+  "datasources reader retry": readerRetry2,
+  "datasources reread": reread2
+};
+var dataSourceReadersHelp = `
+Reading documents into the app (readers):
+  remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2] [--limit <n>] [--release <id>]
+  remy-admin datasources reader status [--source <slug>]
+  remy-admin datasources reader retry [--source <slug>] [--job <id>]
+  remy-admin datasources reread [--source <slug>] [--unread] [--filter <k=v|json>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]
+
+  A READER is app code the platform runs over every document a source
+  builds, writing what it finds into the app's own tables: the extraction an
+  app would otherwise run from a cron over allDocuments(), with the
+  platform's batching, retries, budgets and pauses. Declare it in
+  mindstudio.json:
+    "dataSources": [{ "slug": "archive", "reader": { "path": "dist/datasources/archive.reader.ts" } }]
+  The file exports defineReader(Archive, { read, removed, cleared?,
+  relinked? }) from @mindstudio-ai/agent. read(document) gets the document
+  (id, sourceId, filename, metadata, entities, url), document.chunks(), its
+  passages as indexed with each one's entities, and document.bytes(), the
+  file it came from; removed(documentId) is called when a document leaves
+  the source; cleared(sourceId) once when the source is deleted; relinked(
+  document) when a new dictionary re-tagged a document already read, for
+  rows derived from its tags. Throwing fails that document, which is
+  retried. A document can be
+  read more than once, so read() replaces the document's rows as a set,
+  keyed by its id, and removed() deletes them. Options on the declaration:
+  timeoutMs (per document, default 60000, max 300000) and concurrency
+  (frames in flight for the source, default 16, max 64).
+
+  The reader always runs against the LIVE release, its code and its
+  database: nothing reads until the app publishes one. From then on every
+  document whose build lands on the active version is read, every removed
+  document delivered as removed, whether it came through add(), a sync or a
+  job. A job over a reader source reads as its last stage: the job stays
+  running until its documents are read, \`jobs status\` says "reading N of M",
+  a document the reader fails on lands in the job's quarantine (stage read),
+  and a reader failing on far more documents than it did at first pauses the
+  job with pauseReason 'reader'.
+
+  The loop: \`reader test --dev\` runs the LOCAL reader through the dev
+  session over real documents, writing into the dev session's database, and
+  prints each outcome; publish, and \`releases wait\` reports each reader's
+  unread documents; \`reread --unread\` reads them. \`reread\` is a job that
+  plans first: it prices reading from what the live reader has done (after a
+  hundred documents), or reads a first slice for real and measures spend,
+  failures and the live database's growth, then waits for \`jobs approve\`.
+  Without --unread it reads every built document again (a changed reader).
+  \`reader status\` shows the reader, its deliveries (pending, in flight,
+  retrying, parked, recent errors), unread documents, the measured cost per
+  document and the live database's size. Deliveries outside jobs retry after
+  1, 5, 15, 60 and 240 minutes, then park; \`reader retry\` sends parked ones
+  again, and \`reader retry --job <id>\` the documents a job's reader failed
+  on.
+`;
+
 // src/commands/dataSources.ts
 var INGEST_FLAGS = {
   chunking: { type: "string" },
@@ -5329,11 +5870,12 @@ var CONFIG_FLAGS = {
 };
 var dataSourcesSpecs = {
   "datasources add": {
-    usage: "Usage: remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--wait] [--timeout <sec>] <file...>",
+    usage: "Usage: remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--wait] [--timeout <sec>] <file...>",
     positionals: [{ name: "file", required: true, variadic: true }],
     flags: {
       source: { type: "string" },
       metadata: { type: "string" },
+      entities: { type: "string" },
       wait: { type: "boolean" },
       timeout: { type: "string" }
     }
@@ -5362,7 +5904,7 @@ var dataSourcesSpecs = {
     }
   },
   "datasources search": {
-    usage: "Usage: remy-admin datasources search [--source <slug>] [--top-k <n>] [--mode <hybrid|semantic|lexical>] [--filter <k=v,...|json>] [--phrase <text>] [--contains <words>] [--max-per-document <n>] [--rerank <true|false>] [--hybrid <true|false>] [--highlight] [--candidate] <query>",
+    usage: "Usage: remy-admin datasources search [--source <slug>] [--top-k <n>] [--mode <hybrid|semantic|lexical>] [--filter <k=v,...|json>] [--entities <id,...>] [--phrase <text>] [--contains <words>] [--max-per-document <n>] [--rerank <true|false>] [--hybrid <true|false>] [--highlight] [--candidate] <query>",
     positionals: [{ name: "query", required: true }],
     flags: {
       source: { type: "string" },
@@ -5372,6 +5914,7 @@ var dataSourcesSpecs = {
       hybrid: { type: "string" },
       mode: { type: "string" },
       filter: { type: "string" },
+      entities: { type: "string" },
       phrase: { type: "string" },
       contains: { type: "string" },
       "max-per-document": { type: "number", min: 1 },
@@ -5398,12 +5941,38 @@ var dataSourcesSpecs = {
     }
   },
   "datasources count": {
-    usage: "Usage: remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--contains <words>] [--phrase <text>] [--candidate]",
+    usage: "Usage: remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--candidate]",
+    flags: {
+      source: { type: "string" },
+      filter: { type: "string" },
+      entities: { type: "string" },
+      contains: { type: "string" },
+      phrase: { type: "string" },
+      candidate: { type: "boolean" }
+    }
+  },
+  "datasources entities": {
+    usage: "Usage: remy-admin datasources entities [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--limit <n>] [--candidate]",
+    flags: {
+      source: { type: "string" },
+      filter: { type: "string" },
+      entities: { type: "string" },
+      contains: { type: "string" },
+      phrase: { type: "string" },
+      limit: { type: "number", min: 1 },
+      candidate: { type: "boolean" }
+    }
+  },
+  "datasources passages": {
+    usage: "Usage: remy-admin datasources passages [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--cursor <cursor>] [--limit <n>] [--candidate]",
     flags: {
       source: { type: "string" },
       filter: { type: "string" },
+      entities: { type: "string" },
       contains: { type: "string" },
       phrase: { type: "string" },
+      cursor: { type: "string" },
+      limit: { type: "number", min: 1 },
       candidate: { type: "boolean" }
     }
   },
@@ -5449,22 +6018,24 @@ async function dataSourcesAdd(ctx, a) {
   const files = a.rest("file");
   const slug = sourceOf(a);
   const metadata = parseKeyValuePairs(a.str("metadata"), "metadata");
+  const entities2 = parseIdList(a.str("entities"));
   const results = [];
   for (const file of files) {
-    const abs = path5.isAbsolute(file) ? file : path5.join(WORKSPACE_DIR, file);
+    const abs = path6.isAbsolute(file) ? file : path6.join(WORKSPACE_DIR, file);
     let bytes;
     try {
-      bytes = fs5.readFileSync(abs);
+      bytes = fs6.readFileSync(abs);
     } catch (err) {
       fatal(`Could not read file "${file}": ${err.message}`);
     }
-    const filename = path5.basename(file);
+    const filename = path6.basename(file);
     results.push(
       await addDocument(ctx, {
         slug,
         filename,
         content: bytes,
         ...metadata ? { metadata } : {},
+        ...entities2 ? { entities: entities2 } : {},
         onProgress: progress
       })
     );
@@ -5535,6 +6106,7 @@ async function dataSourcesStatus(ctx, a) {
     activeVersion: source.activeVersion,
     candidate: source.candidate,
     job: source.job,
+    relink: source.relink,
     failures: (failures?.documents ?? []).map(summarize),
     moreFailures: !!failures?.nextCursor
   });
@@ -5550,16 +6122,7 @@ async function dataSourcesRm(ctx, a) {
     out({ deleted: documentId });
     return;
   }
-  let filter;
-  if (rawFilter.trimStart().startsWith("{")) {
-    try {
-      filter = JSON.parse(rawFilter);
-    } catch (err) {
-      fatal(`--filter is not valid JSON: ${err.message}`);
-    }
-  } else {
-    filter = { metadata: parseKeyValuePairs(rawFilter, "filter") };
-  }
+  const filter = documentSelectorOf(rawFilter);
   const slug = sourceOf(a);
   const result = await rmWhereAll(ctx, {
     slug,
@@ -5614,6 +6177,40 @@ async function dataSourcesCount(ctx, a) {
     })
   );
 }
+async function dataSourcesEntities(ctx, a) {
+  const filter = filterFromFlags(a);
+  const limit = a.num("limit");
+  out(
+    await entities(ctx, {
+      slug: sourceOf(a),
+      ...filter ? { filter } : {},
+      ...limit !== void 0 ? { limit } : {},
+      ...a.bool("candidate") ? { candidate: true } : {}
+    })
+  );
+}
+async function dataSourcesPassages(ctx, a) {
+  const filter = filterFromFlags(a);
+  const limit = a.num("limit");
+  const cursor = a.str("cursor");
+  const result = await passages(ctx, {
+    slug: sourceOf(a),
+    ...filter ? { filter } : {},
+    ...cursor ? { cursor } : {},
+    ...limit !== void 0 ? { limit } : {},
+    ...a.bool("candidate") ? { candidate: true } : {}
+  });
+  out({
+    ...result,
+    ...result.nextCursor ? { note: `More: pass --cursor ${result.nextCursor} for the next page.` } : {}
+  });
+}
+function parseIdList(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  return raw.split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+}
 function filterFromFlags(a) {
   let filter = {};
   const raw = a.str("filter");
@@ -5631,6 +6228,10 @@ function filterFromFlags(a) {
       }
     }
   }
+  const entities2 = parseIdList(a.str("entities"));
+  if (entities2?.length) {
+    filter.entities = entities2;
+  }
   const phrase = a.str("phrase");
   if (phrase) {
     filter.phrase = phrase;
@@ -5641,29 +6242,6 @@ function filterFromFlags(a) {
   }
   return Object.keys(filter).length ? filter : void 0;
 }
-function parseKeyValuePairs(raw, flag) {
-  if (raw === void 0) {
-    return void 0;
-  }
-  const pairs2 = {};
-  for (const part of raw.split(",")) {
-    const trimmed = part.trim();
-    if (!trimmed) {
-      continue;
-    }
-    const eq = trimmed.indexOf("=");
-    if (eq <= 0) {
-      fatal(`--${flag} entries must be key=value (got "${trimmed}").`);
-    }
-    const key = trimmed.slice(0, eq).trim();
-    const value = trimmed.slice(eq + 1).trim();
-    pairs2[key] = value === "true" ? true : value === "false" ? false : value !== "" && !Number.isNaN(Number(value)) ? Number(value) : value;
-  }
-  if (Object.keys(pairs2).length === 0) {
-    fatal(`--${flag} needs at least one key=value pair.`);
-  }
-  return pairs2;
-}
 function triState2(a, flag, key) {
   const raw = a.str(flag);
   if (raw === void 0) {
@@ -5890,6 +6468,8 @@ var dataSourcesHandlers = {
   "datasources create": dataSourcesCreate,
   "datasources config": dataSourcesConfig,
   "datasources count": dataSourcesCount,
+  "datasources entities": dataSourcesEntities,
+  "datasources passages": dataSourcesPassages,
   "datasources move": dataSourcesMove,
   "datasources revectorize": dataSourcesRevectorize,
   "datasources promote": dataSourcesPromote,
@@ -5907,6 +6487,11 @@ Subcommands:
   status       Show a source's counts and its failed documents (--all walks every document)
   rm           Remove a document, or every document matching a filter
   search       Query a corpus \u2014 useful to sanity-check one you just built
+  count        How many passages match a filter (words, a phrase, entities, metadata)
+  passages     Every passage matching a filter, unranked, a page at a time
+  entities     Which entities the matching passages are about, most first
+  dictionary   push|status: send a source its dictionary of names, or show the current one
+  link         What the source's dictionary finds in a piece of text
   create       Create an empty source, optionally on dedicated capacity
   config       Show or change how a corpus is processed and searched
   move         Move a corpus between shared and dedicated capacity, data intact
@@ -5919,6 +6504,8 @@ Subcommands:
   map test     Run a source's mapper over real objects and show the outcomes; nothing ingested
   map deploy   Make a build's compiled mapper the source's active one (a branch build will do)
   remap        Re-apply the active mapper to every raw copy the source holds
+  reader       test|status|retry: run the dev session's reader, see its deliveries, resend failed ones
+  reread       Read a source's documents again with its live reader, priced first
   hydrate      Reload an evicted index ahead of the first search
   reindex      Recreate a dedicated source's collection with the current shape, refilled from stored vectors
   sample       Draw a sample of a source into a new one with the same config
@@ -5929,12 +6516,14 @@ Subcommands:
   delete       Delete a whole data source \u2014 documents, vectors and versions
 
 Usage:
-  remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--wait] [--timeout <sec>] <file...>
+  remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--wait] [--timeout <sec>] <file...>
   remy-admin datasources list
   remy-admin datasources status [--source <slug>] [--status error] [--all]
   remy-admin datasources rm [--source <slug>] (--document <id> | --filter <k=v,...|json>)
   remy-admin datasources search [--source <slug>] [search options] <query>
-  remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--contains <words>] [--phrase <text>] [--candidate]
+  remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--candidate]
+  remy-admin datasources entities [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--limit <n>] [--candidate]
+  remy-admin datasources passages [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--cursor <c>] [--limit <n>] [--candidate]
   remy-admin datasources create --source <slug> [--name <name>] [--placement <resource-id|shared>] [rebuild settings...]
   remy-admin datasources config [--source <slug>] [--placement <resource-id|shared>] [settings...]
   remy-admin datasources move [--source <slug>] --to <resource-id|shared> [--chains <n>] [--restart] [--wait] [--timeout <sec>]
@@ -5955,6 +6544,15 @@ Count:
   count (none exists), and not the set search returns. The SDK's
   \`Source.count(filter)\` is the same call for an app.
 
+Entities:
+  A document can assert what it is about as your own ids (\`add --entities\`,
+  a mapper's \`entities\`, a manifest line's \`entities\`), and every passage
+  carries them. \`--entities a,b\` on search and count narrows to passages
+  about any of them. \`entities\` lists which entities the matching passages
+  are about, most first, with how many passages carry each (approximate, and
+  passages, not documents): filter on one entity to see what appears beside
+  it. The SDK's \`Source.entities({ filter, limit })\` is the same call.
+
 Search options:
   --top-k <n>              Results to return (default 5, max 50)
   --mode <m>               hybrid (default) | semantic | lexical. Lexical is
@@ -5963,11 +6561,12 @@ Search options:
   --filter <k=v,...>       Match document metadata set at add time. Values
                            coerce: true/false and numbers become typed.
                            Pass a JSON object for the full grammar:
-                           metadata, filename, documentIds, pages, contains,
-                           phrase \u2014 e.g. --filter '{"pages":{"max":3}}'.
+                           metadata, filename, documentIds, entities, pages,
+                           contains, phrase \u2014 e.g. --filter '{"pages":{"max":3}}'.
                            Metadata takes numeric ranges via {gte,lte}: store
                            dates as integers (YYYYMMDD or epoch seconds), then
                            --filter '{"metadata":{"date":{"gte":20250101}}}'
+  --entities <id,...>      Chunk must be about any of these entities
   --phrase <text>          Chunk must contain this exact word sequence
   --contains <words>       Chunk must contain ALL these words, any order
   --max-per-document <n>   Cap hits per document; backfills from others
@@ -6056,6 +6655,8 @@ Notes:
   Re-adding an unchanged file is free: no upload, no re-embedding. Re-adding
     with a different --metadata updates the tags in place, also free.
   --metadata tags documents for search-time filtering (scalars, \u226416 keys).
+  --entities names what a document is about, as your own ids (\u2264256, no spaces
+    or commas); an empty --entities clears them. Also free on a re-add.
   rm --filter removes every matching document in pages of a thousand: k=v
     pairs match metadata; a JSON object takes the full selector \u2014 metadata,
     filename, documentIds, externalIdPrefix (the key a job or connector
@@ -6095,7 +6696,7 @@ Examples:
   remy-admin datasources revectorize --source archive-sample --max-chars 900 --wait
   remy-admin datasources eval run --set <setId> --candidate --label small-chunks --wait
   remy-admin datasources eval compare <runA> <runB>
-${dataSourceJobsHelp}${dataSourceConnectorsHelp}${dataSourceMappersHelp}${dataSourceEvalsHelp}`;
+${dataSourceJobsHelp}${dataSourceConnectorsHelp}${dataSourceMappersHelp}${dataSourceReadersHelp}${dataSourceEvalsHelp}${dataSourceDictionaryHelp}`;
 
 // src/ops/voice.ts
 function normalizeE164(input) {
@@ -7932,21 +8533,21 @@ Examples:
 // src/ops/infra.ts
 var DEFAULT_WAIT_TIMEOUT_MS4 = 10 * 60 * 1e3;
 var POLL_MS5 = 3e3;
-function base6(appId) {
+function base7(appId) {
   return `/_internal/v2/apps/${appId}/infra`;
 }
 function list14(ctx, params) {
   return call(
     ctx,
     "GET",
-    `${base6(ctx.appId)}${params?.includeDestroyed ? "?includeDestroyed=true" : ""}`
+    `${base7(ctx.appId)}${params?.includeDestroyed ? "?includeDestroyed=true" : ""}`
   );
 }
 function get12(ctx, params) {
   return call(
     ctx,
     "GET",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}`
   );
 }
 function logs(ctx, params) {
@@ -7961,11 +8562,11 @@ function logs(ctx, params) {
   return call(
     ctx,
     "GET",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/logs${search2 ? `?${search2}` : ""}`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/logs${search2 ? `?${search2}` : ""}`
   );
 }
 function provision(ctx, params) {
-  return call(ctx, "POST", base6(ctx.appId), {
+  return call(ctx, "POST", base7(ctx.appId), {
     offeringId: params.offeringId,
     ...params.name ? { name: params.name } : {}
   });
@@ -7974,28 +8575,28 @@ function hibernate(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/hibernate`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/hibernate`
   );
 }
 function resume2(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/resume`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/resume`
   );
 }
 function destroy(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/destroy`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/destroy`
   );
 }
 function resize(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/resize`,
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/resize`,
     { offeringId: params.offeringId }
   );
 }
@@ -8003,7 +8604,7 @@ function rename(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/rename`,
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/rename`,
     { name: params.name }
   );
 }
@@ -8572,7 +9173,9 @@ var SPECS = {
   ...dataSourceJobsSpecs,
   ...dataSourceConnectorsSpecs,
   ...dataSourceEvalsSpecs,
+  ...dataSourceDictionarySpecs,
   ...dataSourceMappersSpecs,
+  ...dataSourceReadersSpecs,
   ...voiceSpecs,
   ...agentSpecs,
   ...tasksSpecs,
@@ -8603,7 +9206,9 @@ var HANDLERS = {
   ...dataSourceJobsHandlers,
   ...dataSourceConnectorsHandlers,
   ...dataSourceEvalsHandlers,
+  ...dataSourceDictionaryHandlers,
   ...dataSourceMappersHandlers,
+  ...dataSourceReadersHandlers,
   ...voiceHandlers,
   ...agentHandlers,
   ...tasksHandlers,
@@ -8644,8 +9249,8 @@ var GROUP_HELP = {
 };
 
 // src/ctx.ts
-import fs6 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path7 from "path";
 
 // src/parseJsonConfig.ts
 import JSON5 from "json5";
@@ -8674,10 +9279,10 @@ function parseJsonConfig(raw) {
 // src/ctx.ts
 var DEFAULT_BASE_URL = "https://api.mindstudio.ai";
 function loadWorkspaceAppId(workspaceDir = WORKSPACE_DIR) {
-  const manifestPath = path6.join(workspaceDir, "mindstudio.json");
+  const manifestPath = path7.join(workspaceDir, "mindstudio.json");
   let raw;
   try {
-    raw = fs6.readFileSync(manifestPath, "utf-8");
+    raw = fs7.readFileSync(manifestPath, "utf-8");
   } catch (err) {
     if (err.code === "ENOENT") {
       throw new Error(`mindstudio.json not found at ${manifestPath}`);
@@ -8775,32 +9380,60 @@ function resolveRoute(argv) {
   if (sub && KEYS.has(two)) {
     return { key: two, argv: argv.slice(2) };
   }
-  if (group === "domains" && sub === "custom") {
-    return {
-      error: `Unknown subcommand: domains custom ${action ?? ""}. Run 'remy-admin domains --help'`
-    };
+  if (group === "db" && sub) {
+    return { key: "db query", argv: argv.slice(1) };
   }
-  if (group === "settings" && ["allowlist", "test-accounts", "frame-ancestors"].includes(sub ?? "")) {
-    return {
-      error: `Unknown subcommand: settings ${sub} ${action ?? ""}. Run 'remy-admin settings --help'`
-    };
+  return { error: unknownSubcommand(group, sub, action) };
+}
+function keysUnder(words) {
+  const prefix = `${words.join(" ")} `;
+  return [...KEYS].filter((key) => key.startsWith(prefix)).sort();
+}
+function unknownSubcommand(group, sub, action) {
+  const asked = [group, sub, action].filter(Boolean).join(" ");
+  const nested = sub ? keysUnder([group, sub]) : [];
+  if (nested.length > 0) {
+    const actions = nested.map((key) => key.split(" ")[2]);
+    return `Unknown subcommand: ${asked}. '${group} ${sub}' takes: ${actions.join(", ")}. Run 'remy-admin ${group} ${sub} --help' for their usage.`;
   }
-  if (group === "datasources" && (sub === "jobs" || sub === "eval" || sub === "map")) {
-    return {
-      error: `Unknown subcommand: datasources ${sub} ${action ?? ""}. Run 'remy-admin datasources --help'`
-    };
+  const subs = [...new Set(keysUnder([group]).map((key) => key.split(" ")[1]))];
+  return `Unknown subcommand: ${asked}. '${group}' takes: ${subs.join(", ")}. Run 'remy-admin ${group} --help'.`;
+}
+function leadingWords(argv) {
+  const words = [];
+  for (const token of argv) {
+    if (token.startsWith("-")) {
+      break;
+    }
+    words.push(token);
   }
-  if (group === "email" && ["domains", "inbound-domains"].includes(sub ?? "")) {
-    return {
-      error: `Unknown subcommand: email ${sub} ${action ?? ""}. Run 'remy-admin email --help'`
-    };
+  return words;
+}
+function commandHelp(argv) {
+  const words = leadingWords(argv);
+  const group = words[0];
+  const guide = `Run 'remy-admin ${group} --help' for the ${group} guide.`;
+  for (let n = Math.min(words.length, 3); n >= 2; n--) {
+    const key = words.slice(0, n).join(" ");
+    if (KEYS.has(key)) {
+      return `${SPECS[key].usage}
+
+${guide}`;
+    }
   }
-  if (group === "db" && sub) {
-    return { key: "db query", argv: argv.slice(1) };
+  if (words.length >= 2) {
+    const under = keysUnder(words.slice(0, 2));
+    if (under.length > 0) {
+      const usages = under.map(
+        (key) => `  ${SPECS[key].usage.replace(/^Usage:\s*/, "")}`
+      );
+      return `Usage:
+${usages.join("\n")}
+
+${guide}`;
+    }
   }
-  return {
-    error: `Unknown subcommand: ${group} ${sub ?? ""}. Run 'remy-admin ${group} --help'`
-  };
+  return void 0;
 }
 function resolveHelp(argv) {
   const group = argv[0];
@@ -8815,7 +9448,10 @@ function resolveHelp(argv) {
     return groupHelp;
   }
   const scan = group === "db" ? argv.slice(1, argv[1] === "query" ? 3 : 2) : argv.slice(1);
-  return scan.some((t) => t === "--help" || t === "-h") ? groupHelp : void 0;
+  if (!scan.some((t) => t === "--help" || t === "-h")) {
+    return void 0;
+  }
+  return commandHelp(argv) ?? groupHelp;
 }
 
 // src/prod.ts