dazzer-connect 0.2.0 → 0.4.0

package/README.md

@@ -67,6 +67,74 @@ The second carries a pass, for clients that cannot do that:
 
 Merge either one with any `mcpServers` entries you already have, save, and restart your client.
 
+## Put files into Dazzer
+
+Dazzer takes a new file only with a description of it. A single new file needs an entry under its own name in a descriptions file, passed with `--described-in`, just as a folder does. The descriptions file is shown below.
+
+```bash
+dazzer add report.pdf
+dazzer add ./backlog
+```
+
+A folder is walked with its subfolders. Hidden files are left alone, and nothing outside the folder is ever sent. The first time, you are asked which space things go in: run the same command again with `--space "<name>"`, or with `--keep-to-myself`. A folder run ends with a count of what went in and what was skipped. Add `--why` to see each file that was skipped, and why. A run that left a file out exits with a failure code. A file already in Dazzer was not left out. In a folder run, neither was a file held while you are asked whether it is a newer version of one already there.
+
+A folder run without a descriptions file sends nothing and says so.
+
+### With what your assistant wrote about each file
+
+Your own AI assistant can read the files and say what each one is. It writes that into one JSON file, called the descriptions file. Each key is a file's path inside the folder, or the file's name when you add just one, and what sits under a key is that file's entry:
+
+```json
+{
+  "notes/plan.md": {
+    "description": {
+      "what_it_is": { "text": "the plan for the spring launch", "quote": "Spring launch plan" },
+      "what_it_covers": { "text": "who ships what, week by week", "quote": "Week 1: design review" },
+      "what_it_decides": null,
+      "how_much_was_read": { "all": true }
+    },
+    "facts": [{ "text": "the launch is on 14 April", "quote": "Launch: 14 April" }],
+    "document_date": "2026-03-01"
+  },
+  "scan.png": {
+    "description": {
+      "what_it_is": { "text": "a photo of the gate log", "quote": "GATE LOG" },
+      "what_it_covers": { "text": "who signed for the gate overnight", "quote": "night porter" },
+      "what_it_decides": null,
+      "how_much_was_read": { "all": true }
+    },
+    "transcription": "GATE LOG\nSigned by the night porter at four."
+  }
+}
+```
+
+Save it beside the folder, never inside it — for example as `backlog-descriptions.json` next to `backlog`. Inside the folder, it is one more file a run has to tell apart from the documents. Then:
+
+```bash
+dazzer add ./backlog --described-in ./backlog-descriptions.json
+```
+
+Each file goes with its own entry. The descriptions file named by `--described-in` is not sent with them, even when it sits inside the folder, and the run says to move it.
+
+- Each entry's form is checked before its file is sent. An entry in a form Dazzer refuses, such as a date written as "March 2026", holds its file back, and a line names the field and the form it takes. What the entry says is judged by Dazzer once the file has arrived.
+- A file with no entry, or whose entry has no description, is not sent. The count says how many, and names them while there are few.
+- An entry that names no file being added is reported, and nothing is sent for it. If no entry names a file being added, or none has a description, nothing is sent at all.
+- A file Dazzer refuses is named, with why it was not added. A file refused for its kind or its size is only counted, and `--why` names it.
+- Whatever Dazzer did not keep of an entry is printed file by file, in plain words.
+- Sent again, a folder already in Dazzer says how many files took the description sent now, how many already had one, and how many did not take the one sent.
+
+An assistant that can run commands runs this one itself. One that cannot gives you the descriptions file to save beside the folder, and the line to run.
+
+## Keep it up to date
+
+Dazzer takes files only from a recent enough copy of this tool. An older copy is told so on its first call, before it sends anything, with the one command that updates it:
+
+```bash
+npm install -g dazzer-connect@latest
+```
+
+Once a day, the tool also tells you when a newer version is out. It looks at most once a day, never makes a command wait for the answer, and stays quiet if it cannot find out. What it remembers sits in the same settings folder as the rest of its state, below.
+
 ## Other commands
 
 ```bash

package/dist/index.js

@@ -8,6 +8,10 @@ import { Command } from "commander";
 import { open, stat as statPath } from "node:fs/promises";
 import { basename, extname } from "node:path";
 
+// src/lib/api-client.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
 // src/lib/output.ts
 function writeOut(message) {
   process.stdout.write(`${message}
@@ -19,6 +23,8 @@ function writeErr(message) {
 }
 var CANNOT_REACH_DAZZER = "I can't reach Dazzer right now \u2014 nothing was sent. Try again shortly.";
 var SIGN_IN_NO_LONGER_VALID = "Your Dazzer sign-in is no longer valid. Reconnect your client (or run `dazzer auth login`).";
+var UPDATE_THE_TOOL = "npm install -g dazzer-connect@latest";
+var newerToolIsOut = (version2) => `Version ${version2} of dazzer is out. Update it with: ${UPDATE_THE_TOOL}`;
 function printDeviceInstructions(deviceAuth) {
   writeOut("");
   if (deviceAuth.verification_uri_complete) {
@@ -265,6 +271,7 @@ function assertHttpsServiceAddress(address) {
   }
   return address.replace(/\/$/, "");
 }
+var CLIENT_HEADER = "x-dazzer-client";
 function readOfferedPlaces(offered) {
   if (!Array.isArray(offered)) return [];
   return offered.flatMap((place) => {
@@ -314,6 +321,31 @@ function refusalPlaces(body) {
     ...typeof keep === "boolean" ? { keepToYourself: keep } : {}
   };
 }
+var wordsIn = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
+function refusalAbout(body) {
+  if (typeof body !== "object" || body === null) return {};
+  const flat = body;
+  const enveloped = typeof flat.error === "object" && flat.error !== null ? flat.error.details : void 0;
+  const fields = [
+    ...wordsIn(flat.field) === void 0 ? [] : [flat.field],
+    ...Array.isArray(enveloped) ? enveloped.flatMap((detail) => {
+      const named2 = typeof detail === "object" && detail !== null ? wordsIn(detail.field) : void 0;
+      return named2 === void 0 ? [] : [named2];
+    }) : []
+  ];
+  const dropped = Array.isArray(flat.dropped) ? flat.dropped.flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null) return [];
+    const line = wordsIn(entry.line);
+    const reason = wordsIn(entry.reason);
+    return line === void 0 || reason === void 0 ? [] : [{ line, reason }];
+  }) : [];
+  const howMuch = typeof flat.how_much_was_read === "object" && flat.how_much_was_read !== null ? wordsIn(flat.how_much_was_read.reason) : void 0;
+  return {
+    ...fields.length > 0 ? { fields } : {},
+    ...dropped.length > 0 ? { dropped } : {},
+    ...howMuch === void 0 ? {} : { howMuchWasRead: howMuch }
+  };
+}
 async function resolveCredential(auth2) {
   let held;
   try {
@@ -357,7 +389,8 @@ async function callDazzer(request) {
   const fetchFn = request.fetchFn ?? fetch;
   const headers = {
     accept: "application/json",
-    authorization: `Bearer ${credential.held}`
+    authorization: `Bearer ${credential.held}`,
+    [CLIENT_HEADER]: request.client
   };
   if (request.body !== void 0) headers["content-type"] = "application/json";
   let res;
@@ -382,15 +415,99 @@ async function callDazzer(request) {
       httpStatus: res.status,
       ...detail === void 0 ? {} : { detail },
       ...code === void 0 ? {} : { code },
-      ...refusalPlaces(body)
+      ...refusalPlaces(body),
+      ...refusalAbout(body)
     };
   }
   return { status: "ok", httpStatus: res.status, body };
 }
+var REGISTRY = "https://registry.npmjs.org";
+var LOOK_AT_MOST_MS = 3e3;
+var A_DAY_MS = 24 * 60 * 60 * 1e3;
+var NEWER_TOOL_FILE = "newer-version.json";
+function releaseOf(version2) {
+  if (typeof version2 !== "string") return null;
+  const said = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})$/.exec(version2);
+  return said === null ? null : [Number(said[1]), Number(said[2]), Number(said[3])];
+}
+function isLater(published, mine) {
+  const theirs = releaseOf(published);
+  const own = /^(\d{1,6}\.\d{1,6}\.\d{1,6})(-[^+]+)?(\+.+)?$/.exec(mine);
+  const ours = own === null ? null : releaseOf(own[1]);
+  if (theirs === null || own === null || ours === null) return false;
+  for (let at = 0; at < 3; at += 1) {
+    if (theirs[at] !== ours[at]) return (theirs[at] ?? 0) > (ours[at] ?? 0);
+  }
+  return own[2] !== void 0;
+}
+async function recall(file) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function remember(folder, file, what) {
+  try {
+    await mkdir(folder, { recursive: true });
+    await writeFile(file, `${JSON.stringify(what)}
+`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+var withinADay = (then, now) => typeof then === "number" && Number.isFinite(then) && then <= now && now - then < A_DAY_MS;
+function lookForNewerTool(check) {
+  const now = check.now ?? Date.now;
+  const file = join(check.folder, NEWER_TOOL_FILE);
+  const stop = new AbortController();
+  const looked = (async () => {
+    try {
+      const before = await recall(file);
+      if (withinADay(before.looked_at, now()) || stop.signal.aborted) return;
+      const signal = AbortSignal.any([
+        stop.signal,
+        AbortSignal.timeout(check.lookAtMostMs ?? LOOK_AT_MOST_MS)
+      ]);
+      const res = await (check.fetchFn ?? fetch)(
+        `${REGISTRY}/${encodeURIComponent(check.name)}/latest`,
+        { headers: { accept: "application/json" }, signal }
+      );
+      const published = res.ok ? (await res.json()).version : void 0;
+      if (stop.signal.aborted) return;
+      const latest = releaseOf(published) === null ? void 0 : published;
+      await remember(check.folder, file, {
+        ...await recall(file),
+        looked_at: now(),
+        ...latest === void 0 ? {} : { latest }
+      });
+    } catch {
+    }
+  })();
+  return {
+    looked,
+    finish: async () => {
+      stop.abort();
+      try {
+        await looked;
+        const known = await recall(file);
+        const latest = known.latest;
+        if (typeof latest !== "string" || !isLater(latest, check.version)) return null;
+        if (withinADay(known.told_at, now())) return null;
+        const kept = await remember(check.folder, file, { ...known, told_at: now() });
+        return kept ? newerToolIsOut(latest) : null;
+      } catch {
+        return null;
+      }
+    }
+  };
+}
 
 // src/lib/config-store.ts
-import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir as mkdir2, readFile as readFile2, unlink, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
 import envPaths from "env-paths";
 
 // src/lib/discovery.ts
@@ -454,9 +571,9 @@ async function discoverEndpoints(issuer, fetchFn = fetch) {
 
 // src/lib/config-store.ts
 var paths = envPaths("dazzer", { suffix: "" });
-var CONFIG_FILE = join(paths.config, "auth.json");
+var CONFIG_FILE = join2(paths.config, "auth.json");
 async function ensureConfigDir() {
-  await mkdir(paths.config, { recursive: true });
+  await mkdir2(paths.config, { recursive: true });
 }
 var MAX_CLIENT_ID_LENGTH = 512;
 async function saveAuthMetadata(meta) {
@@ -469,12 +586,12 @@ async function saveAuthMetadata(meta) {
   const savedToStore = typeof meta.savedToStore === "boolean" ? meta.savedToStore : void 0;
   await ensureConfigDir();
   const checked = { issuer, clientId, expiresAt, savedToStore };
-  await writeFile(CONFIG_FILE, `${JSON.stringify(checked, null, 2)}
+  await writeFile2(CONFIG_FILE, `${JSON.stringify(checked, null, 2)}
 `, "utf8");
 }
 async function loadAuthMetadata() {
   try {
-    const raw = await readFile(CONFIG_FILE, "utf8");
+    const raw = await readFile2(CONFIG_FILE, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.issuer !== "string" || typeof parsed.clientId !== "string") {
       return null;
@@ -640,7 +757,7 @@ function createTokenStore() {
 
 // src/lib/walk.ts
 import { readdir, realpath, stat } from "node:fs/promises";
-import { join as join2, sep } from "node:path";
+import { join as join3, sep } from "node:path";
 function inside(base, candidate) {
   return candidate === base || candidate.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
 }
@@ -665,7 +782,7 @@ async function walkFolder(root) {
     entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
-      const full = join2(dir, entry.name);
+      const full = join3(dir, entry.name);
       const relative = `${prefix}${entry.name}`;
       if (entry.isSymbolicLink()) {
         await followShortcut(full, relative);
@@ -733,7 +850,7 @@ async function walkFolder(root) {
 var SPACE_PATH = "/documents/v1/space";
 var LANDING_PATH = "/documents/v1/landing";
 var LANDED_PATH = "/documents/v1/landed";
-var cannotOpen = (name) => `Couldn't open ${name} \u2014 check its permissions.`;
+var cannotOpen = (name2) => `Couldn't open ${name2} \u2014 check its permissions.`;
 var SLOWING_DOWN = "Slowing down to stay within limits \u2014 still going.";
 var ALREADY_IN = "That one's already in \u2014 nothing to do.";
 var waitingOnYou = (many) => `${many} waiting on your answer.`;
@@ -756,9 +873,38 @@ var NUMBER_WORDS = [
   "ten"
 ];
 var inWords = (many) => NUMBER_WORDS[many] ?? String(many);
-var cannotFind = (name) => `Couldn't find ${name}.`;
-var didNotFinish = (name) => `The send didn't finish \u2014 ${name} is not in Dazzer. Try again shortly.`;
-var wentWrong = (name) => `Something went wrong and ${name} is not in Dazzer. Try again shortly.`;
+var cannotFind = (name2) => `Couldn't find ${name2}.`;
+var didNotFinish = (name2) => `The send didn't finish \u2014 ${name2} is not in Dazzer. Try again shortly.`;
+var wentWrong = (name2) => `Something went wrong and ${name2} is not in Dazzer. Try again shortly.`;
+var descriptionsNotFound = (name2) => `Couldn't find the descriptions file ${name2} \u2014 nothing was sent.`;
+var descriptionsUnreadable = (name2) => `Couldn't read the descriptions file ${name2} \u2014 nothing was sent.`;
+var descriptionsNotJson = (name2) => `The descriptions file ${name2} is not JSON \u2014 nothing was sent.`;
+var descriptionsNotAnObject = (name2) => `The descriptions file ${name2} is not one JSON object keyed by file path \u2014 nothing was sent.`;
+var isTheDescriptionsFile = (name2) => `${name2} is the descriptions file \u2014 nothing was sent.`;
+function namingNoFile(keys) {
+  const many = keys.length;
+  const which = many <= NAMED_WHEN_AT_MOST ? ` \u2014 ${listed(keys.map(asPrinted))}` : "";
+  return `${many} ${many === 1 ? "entry names" : "entries name"} no file being added${which}. Nothing was sent for ${many === 1 ? "it" : "them"}.`;
+}
+var noEntryMatches = (name2, example) => `No entry in ${name2} names a file being added \u2014 nothing was sent.` + (example === void 0 ? "" : ` A key looks like ${JSON.stringify(asPrinted(example))}.`);
+var keepItBeside = "The descriptions file is inside the folder. Keep it beside the folder instead, so no later run sends it as a document.";
+var itHadNoDescription = "It had no description.";
+var NOTHING_DESCRIBED = "Nothing was sent. No file here has a description.";
+var DESCRIBE_THEM = "Write what each file is in a descriptions file. Then run this again with --described-in.";
+var notSentNoDescription = (name2) => `${name2} was not sent. It has no description.`;
+var notAdded = (name2, because2) => [`${name2} was not added.`, ...because2].join(" ");
+function alreadyThereDescriptions(counted) {
+  const parts = [
+    ...counted.filed > 0 ? [`${counted.filed} took the description sent now`] : [],
+    ...counted.alreadyDescribed > 0 ? [`${counted.alreadyDescribed} already had a description`] : [],
+    ...counted.notKept > 0 ? [`${counted.notKept} did not take the description sent`] : []
+  ];
+  return `Of those already there: ${parts.join(", ")}.`;
+}
+var itsDescriptionFiledNow = "Its description was filed now.";
+var itAlreadyHasOne = "It already has a description, and keeps it.";
+var itsDescriptionNotKept = "The description sent was not kept.";
+var NAMED_WHEN_AT_MOST = 5;
 var choiceLine = (space, scopeId) => `  ${asPrinted(space)} \u2014 ${scopeId}`;
 var answerWith = (keepToYourself, numbered) => {
   const ways = [
@@ -788,8 +934,8 @@ var DECLARED_BY_EXTENSION = {
   ".webp": "image/webp"
 };
 var UNDECLARED = "application/octet-stream";
-function asPrinted(name) {
-  return name.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ").trim();
+function asPrinted(name2) {
+  return name2.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ").trim();
 }
 function readEnvelope(body) {
   if (typeof body !== "object" || body === null) return null;
@@ -865,10 +1011,11 @@ function askedWith(options) {
   if (answer === void 0 || answer === "") return {};
   return { space: /^\d+$/.test(answer) ? Number(answer) : answer };
 }
-async function settleSpace(options, auth2, deps, voice, name) {
+async function settleSpace(options, auth2, deps, voice, name2) {
   const answer = await callPaced(
     {
       baseUrl: options.baseUrl,
+      client: options.client,
       path: SPACE_PATH,
       method: "POST",
       body: askedWith(options),
@@ -879,12 +1026,12 @@ async function settleSpace(options, auth2, deps, voice, name) {
     voice
   );
   if (answer.status !== "ok") {
-    say(voice.write, answer, name);
+    say(voice.write, answer, name2);
     return null;
   }
   const data = readEnvelope(answer.body);
   if (data === null) {
-    voice.write(wentWrong(name));
+    voice.write(wentWrong(name2));
     return null;
   }
   const space = typeof data.space === "string" && data.space.trim() !== "" ? data.space : null;
@@ -893,7 +1040,7 @@ async function settleSpace(options, auth2, deps, voice, name) {
   }
   const question = typeof data.question === "string" && data.question !== "" ? data.question : null;
   if (question === null) {
-    voice.write(wentWrong(name));
+    voice.write(wentWrong(name2));
     return null;
   }
   voice.write(question);
@@ -905,6 +1052,7 @@ async function settleSpace(options, auth2, deps, voice, name) {
 var HELD_FOR_AN_ANSWER = "same_name_different_contents";
 function fromAnswer(answer) {
   if (answer.status === "refused") {
+    if (aboutThisTool(answer)) return { kind: "stop", answer };
     if (answer.code === HELD_FOR_AN_ANSWER && answer.detail !== void 0) {
       return { kind: "held", question: answer.detail };
     }
@@ -915,16 +1063,23 @@ function fromAnswer(answer) {
       // Carried, not filled in: absent stays absent, so nothing downstream can print an offer the
       // service did not make.
       ...answer.choices === void 0 ? {} : { choices: answer.choices },
-      ...answer.keepToYourself === void 0 ? {} : { keepToYourself: answer.keepToYourself }
+      ...answer.keepToYourself === void 0 ? {} : { keepToYourself: answer.keepToYourself },
+      ...answer.fields === void 0 ? {} : { fields: answer.fields },
+      ...answer.dropped === void 0 ? {} : { dropped: answer.dropped },
+      ...answer.howMuchWasRead === void 0 ? {} : { howMuchWasRead: answer.howMuchWasRead }
     };
   }
   return { kind: "stop", answer };
 }
+function aboutThisTool(answer) {
+  return answer.status === "refused" && answer.fields?.includes(CLIENT_HEADER) === true;
+}
 async function sendOne(input) {
   const { deps, handle, options, voice } = input;
   const described = await callPaced(
     {
       baseUrl: options.baseUrl,
+      client: options.client,
       path: LANDING_PATH,
       method: "POST",
       body: {
@@ -984,9 +1139,10 @@ async function sendOne(input) {
   const landed = await callPaced(
     {
       baseUrl: options.baseUrl,
+      client: options.client,
       path: LANDED_PATH,
       method: "POST",
-      body: { ticket: landing.ticket },
+      body: { ticket: landing.ticket, ...input.described },
       auth: input.auth,
       fetchFn: deps.fetchFn
     },
@@ -996,11 +1152,310 @@ async function sendOne(input) {
   if (landed.status !== "ok") return fromAnswer(landed);
   const stored = readEnvelope(landed.body);
   if (stored === null) return { kind: "went-wrong" };
-  if (stored.already_here === true) return { kind: "already-here" };
+  const alreadyHere = stored.already_here === true;
+  const becameOfIt = whatBecameOfIt(stored, alreadyHere, "description" in (input.described ?? {}));
+  if (alreadyHere) return { kind: "already-here", ...becameOfIt };
   return {
     kind: "added",
     fileName: typeof stored.file_name === "string" ? asPrinted(stored.file_name) : asPrinted(basename(input.path)),
-    space: typeof stored.space_name === "string" ? stored.space_name : null
+    space: typeof stored.space_name === "string" ? stored.space_name : null,
+    ...becameOfIt
+  };
+}
+var ENTRY_FIELDS = ["description", "facts", "document_date", "transcription"];
+var DESCRIPTION_FIELDS = [
+  "what_it_is",
+  "what_it_covers",
+  "what_it_decides",
+  "how_much_was_read"
+];
+var QUOTED_FIELDS = ["text", "quote"];
+var MOST_FACTS = 100;
+var MOST_TYPED_CHARACTERS = 1e6;
+var MOST_MESSAGE_BYTES = 1024 * 1024;
+var LONGEST_TICKET = 4096;
+var A_DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+var A_MOMENT_ON_THE_DAY = /^T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+var EARLIEST_YEAR = 1e3;
+function aDateTheDoorReads(value) {
+  const written = value.trim();
+  const day = A_DAY.exec(written.slice(0, 10));
+  if (day === null) return false;
+  const [year, month, date] = [Number(day[1]), Number(day[2]), Number(day[3])];
+  if (year < EARLIEST_YEAR) return false;
+  const midnight = new Date(Date.UTC(year, month - 1, date));
+  if (midnight.getUTCFullYear() !== year || midnight.getUTCMonth() !== month - 1 || midnight.getUTCDate() !== date) {
+    return false;
+  }
+  if (written.length === 10) return true;
+  return A_MOMENT_ON_THE_DAY.test(written.slice(10)) && !Number.isNaN(new Date(written).getTime());
+}
+var sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function asKey(path) {
+  let key = path.normalize("NFC").replaceAll("\\", "/");
+  while (key.startsWith("./")) key = key.slice(2);
+  return key;
+}
+async function readDescriptions(path) {
+  const name2 = asPrinted(basename(path));
+  let handle;
+  try {
+    handle = await open(path, "r");
+  } catch (err) {
+    const missing = err?.code === "ENOENT";
+    return { said: missing ? descriptionsNotFound(name2) : descriptionsUnreadable(name2) };
+  }
+  let text;
+  let identity;
+  try {
+    const info = await handle.stat({ bigint: true });
+    identity = { dev: info.dev, ino: info.ino };
+    text = await handle.readFile("utf8");
+  } catch {
+    return { said: descriptionsUnreadable(name2) };
+  } finally {
+    await handle.close();
+  }
+  const json = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return { said: descriptionsNotJson(name2) };
+  }
+  if (!isPlainObject(parsed)) return { said: descriptionsNotAnObject(name2) };
+  const entries = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(parsed)) {
+    const matched = asKey(key);
+    const already = entries.get(matched);
+    entries.set(matched, { keys: [...already?.keys ?? [], key], value: already?.value ?? value });
+  }
+  return { name: name2, entries, identity };
+}
+function quoted(text) {
+  const flat = asPrinted(text);
+  return `"${flat.length > 40 ? `${flat.slice(0, 40)}\u2026` : flat}"`;
+}
+var A_QUOTED_SENTENCE = '{"text": "...", "quote": "..."}';
+function strayKey(value, fields, where, mayHold) {
+  const stray = Object.keys(value).find((key) => !fields.includes(key));
+  return stray === void 0 ? void 0 : `${where} holds ${quoted(stray)}. It holds only ${mayHold}.`;
+}
+function quotedSentenceWrong(value, where) {
+  const stray = strayKey(value, QUOTED_FIELDS, where, "text and quote");
+  if (stray !== void 0) return stray;
+  for (const field of QUOTED_FIELDS) {
+    const said = value[field];
+    if (said !== void 0 && said !== null && typeof said !== "string") {
+      return `the ${field} of ${where} is not text. Write it in quotes, like "Spring launch plan".`;
+    }
+  }
+  return void 0;
+}
+function lineWrong(description, line, mayBeNull) {
+  if (!(line in description)) return void 0;
+  const value = description[line];
+  if (value === null && mayBeNull) return void 0;
+  const where = `description.${line}`;
+  if (!isPlainObject(value)) {
+    return `${where} is not an object. Write it like ${A_QUOTED_SENTENCE}${mayBeNull ? ", or null when the document settles nothing" : ""}.`;
+  }
+  return quotedSentenceWrong(value, where);
+}
+function descriptionWrong(value) {
+  if (!isPlainObject(value)) {
+    return `description is not an object. Write it like {"what_it_is": ${A_QUOTED_SENTENCE}, ...}.`;
+  }
+  return strayKey(
+    value,
+    DESCRIPTION_FIELDS,
+    "description",
+    "what_it_is, what_it_covers, what_it_decides and how_much_was_read"
+  ) ?? lineWrong(value, "what_it_is", false) ?? lineWrong(value, "what_it_covers", false) ?? lineWrong(value, "what_it_decides", true);
+}
+function factsWrong(value) {
+  if (!Array.isArray(value)) return `facts is not a list. Write it like [${A_QUOTED_SENTENCE}].`;
+  if (value.length > MOST_FACTS) {
+    return `facts holds ${value.length} facts. It takes at most ${MOST_FACTS}.`;
+  }
+  for (const [at, fact] of value.entries()) {
+    const where = `fact ${at + 1}`;
+    if (!isPlainObject(fact)) {
+      return `${where} is not an object. Write each fact like ${A_QUOTED_SENTENCE}.`;
+    }
+    const wrong = quotedSentenceWrong(fact, where);
+    if (wrong !== void 0) return wrong;
+  }
+  return void 0;
+}
+function dateWrong(value) {
+  if (typeof value !== "string") return 'document_date is not text. Write it like "2026-03-01".';
+  return aDateTheDoorReads(value) ? void 0 : `document_date ${quoted(value)} is not a date. Write it like "2026-03-01".`;
+}
+function typedWrong(value) {
+  if (typeof value !== "string") {
+    return "transcription is not text. Write the typed-out words as one string.";
+  }
+  return /\S/.test(value) && value.length > MOST_TYPED_CHARACTERS ? `transcription runs to ${value.length.toLocaleString("en-US")} characters. It takes at most ${MOST_TYPED_CHARACTERS.toLocaleString("en-US")}.` : void 0;
+}
+function sizeWrong(entry) {
+  const bytes = Buffer.byteLength(
+    JSON.stringify({ ticket: "t".repeat(LONGEST_TICKET), ...entry }),
+    "utf8"
+  );
+  return bytes > MOST_MESSAGE_BYTES ? `its entry comes to ${bytes.toLocaleString("en-US")} bytes. One message takes at most ${MOST_MESSAGE_BYTES.toLocaleString("en-US")}.` : void 0;
+}
+function checkEntry(found) {
+  if (found.keys.length > 1) {
+    return {
+      wrong: `${found.keys.length} entries name it \u2014 ${listed(found.keys.map(quoted))}. Keep one.`
+    };
+  }
+  const entry = found.value;
+  if (!isPlainObject(entry)) {
+    return {
+      wrong: 'its entry is not an object. Write it like {"description": {...}, "facts": [...], "document_date": "2026-03-01"}.'
+    };
+  }
+  const wrong = strayKey(
+    entry,
+    ENTRY_FIELDS,
+    "its entry",
+    "description, facts, document_date and transcription"
+  ) ?? ("description" in entry ? descriptionWrong(entry.description) : void 0) ?? ("facts" in entry ? factsWrong(entry.facts) : void 0) ?? ("document_date" in entry ? dateWrong(entry.document_date) : void 0) ?? ("transcription" in entry ? typedWrong(entry.transcription) : void 0) ?? sizeWrong(entry);
+  return wrong === void 0 ? { described: entry } : { wrong };
+}
+var wordsOf = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
+var listOf = (value) => Array.isArray(value) ? value : [];
+var LINE_DROPPED = {
+  "line-empty": "it has no words",
+  "line-too-long": "it is too long",
+  "line-verbatim-from-document": "its words are copied out of the document",
+  "quote-empty": "it quotes nothing",
+  "quote-too-long": "its quote is too long",
+  "unstorable-characters": "it holds a character that cannot be stored",
+  "quote-not-in-document": "the words it quotes are not in the document"
+};
+var A_LINE = {
+  what_it_is: "The line saying what it is",
+  what_it_covers: "The line saying what it covers",
+  what_it_decides: "The line saying what it decides"
+};
+var HOW_MUCH_NOT_KEPT = {
+  "not-said": "Its description does not say how much of the file was read.",
+  "which-part-empty": "Its description says only part of the file was read, and not which part.",
+  "which-part-unstorable-characters": "The part it says was read holds a character that cannot be stored.",
+  "which-part-too-long": "The part it says was read is too long. Say it in one short sentence.",
+  "which-part-line-break-or-marker": "The part it says was read is not one plain line."
+};
+var HOW_MUCH_NOT_KEPT_OTHERWISE = "Its description does not say how much of the file was read in a form Dazzer keeps.";
+var FACT_DROPPED = {
+  "fact-empty": "it has no words",
+  "fact-too-long": "it is too long",
+  "quote-empty": "it quotes nothing",
+  "quote-too-long": "its quote is too long",
+  "unstorable-characters": "it holds a character that cannot be stored",
+  "quote-not-in-document": "the words it quotes are not in the document",
+  "nothing-to-check-it-against": "there are no words in the file to check it against"
+};
+var DATE_NOT_KEPT = {
+  "later-than-today": "it is later than today",
+  "document-already-held": "the document was already here, with the date it came with",
+  "stored-as-the-moment-it-arrived": "that day had not begun in universal time, so the moment it arrived is kept"
+};
+var DESCRIPTION_NOT_FILED = {
+  nothing_to_check_it_against: "there are no words in the file to check it against"
+};
+var TYPING_NOT_USED = {
+  not_used_file_has_its_own_text: "the file has words of its own",
+  not_used_document_already_held: "the document was already here"
+};
+var because = (words, name2) => {
+  const said = words[name2];
+  return said === void 0 ? ` (${name2}).` : `, because ${said}.`;
+};
+var lineNotKept = (dropped) => `${A_LINE[dropped.line] ?? "A line of its description"} was not kept${because(LINE_DROPPED, dropped.reason)}`;
+var howMuchNotKept = (reason) => HOW_MUCH_NOT_KEPT[reason] ?? HOW_MUCH_NOT_KEPT_OTHERWISE;
+function whatToDoAbout(refused) {
+  return refused.code === "description_missing" ? DESCRIBE_THEM : void 0;
+}
+var ADD_THE_TEXT = "Add the text you read in it to its entry.";
+function notAddedBecause(refused) {
+  const dropped = (refused.dropped ?? []).map(lineNotKept);
+  const howMuch = refused.howMuchWasRead === void 0 ? [] : [howMuchNotKept(refused.howMuchWasRead)];
+  switch (refused.code) {
+    case "description_missing":
+      return ["It has no description."];
+    case "description_not_kept": {
+      const noLineKept = refused.fields?.includes("description") === true;
+      const said = [...noLineKept ? ["No line of its description was kept."] : [], ...dropped];
+      const all = [...said, ...howMuch];
+      return all.length > 0 ? all : ["Its description was not kept."];
+    }
+    case "nothing_to_check_it_against":
+      return [
+        "Dazzer holds no words of it to check its description against.",
+        ADD_THE_TEXT,
+        ...howMuch
+      ];
+    case "transcription_too_long":
+      return ["The text typed out of it is longer than Dazzer keeps for one file."];
+    case "try_again_shortly":
+      return ["It could not be read just now. Try again shortly."];
+    case "could_not_read_it":
+      return ["Dazzer could not read its words.", ADD_THE_TEXT];
+    default:
+      return void 0;
+  }
+}
+function whatBecameOfIt(stored, alreadyHere, descriptionSent) {
+  const lines = [];
+  let filing;
+  const description = isPlainObject(stored.description) ? stored.description : null;
+  if (description !== null) {
+    const state = wordsOf(description.state);
+    const what = wordsOf(description.what);
+    if (descriptionSent && state !== void 0) {
+      filing = state === "filed" ? "filed" : alreadyHere && state === "not_filed" && what === void 0 ? "already-described" : "not-kept";
+    }
+    if (state === "not_filed" && what !== void 0) {
+      lines.push("Its description was not kept.");
+    } else if (state !== void 0 && state !== "filed" && state !== "none_supplied" && !(alreadyHere && state === "not_filed")) {
+      lines.push(
+        state === "not_filed" ? "Its description was not filed." : `Its description was not filed${because(DESCRIPTION_NOT_FILED, state)}`
+      );
+    }
+    for (const dropped of listOf(description.dropped)) {
+      if (!isPlainObject(dropped)) continue;
+      const line = wordsOf(dropped.line);
+      const reason = wordsOf(dropped.reason);
+      if (line !== void 0 && reason !== void 0) lines.push(lineNotKept({ line, reason }));
+    }
+    const howMuch = isPlainObject(description.how_much_was_read) ? description.how_much_was_read : null;
+    if (howMuch !== null && wordsOf(howMuch.what) !== void 0) {
+      lines.push(howMuchNotKept(wordsOf(howMuch.reason) ?? ""));
+    }
+  }
+  const facts = isPlainObject(stored.facts) ? stored.facts : null;
+  for (const dropped of listOf(facts?.dropped)) {
+    if (!isPlainObject(dropped)) continue;
+    const reason = wordsOf(dropped.reason);
+    if (typeof dropped.fact === "number" && reason !== void 0) {
+      lines.push(`Fact ${dropped.fact} was not kept${because(FACT_DROPPED, reason)}`);
+    }
+  }
+  const date = isPlainObject(stored.date_not_kept) ? wordsOf(stored.date_not_kept.reason) : void 0;
+  if (date !== void 0 && !(alreadyHere && date === "document-already-held")) {
+    lines.push(`Its date was not kept${because(DATE_NOT_KEPT, date)}`);
+  }
+  const typed = wordsOf(stored.transcription);
+  if (typed !== void 0 && typed !== "used" && !(alreadyHere && typed === "not_used_document_already_held")) {
+    lines.push(`The text typed out of it was not used${because(TYPING_NOT_USED, typed)}`);
+  }
+  return {
+    notKept: lines.map(asPrinted),
+    ...filing === void 0 ? {} : { description: filing }
   };
 }
 async function sendOneSafely(input) {
@@ -1017,6 +1472,7 @@ async function openOne(path) {
     return err?.code === "ENOENT" ? "missing" : "cannot-open";
   }
 }
+var LEAVES_A_FILE_OUT = (skip) => skip.reason !== "already-here" && skip.reason !== "the-descriptions-file";
 var REASON_ORDER = [
   "type-not-readable",
   "too-large",
@@ -1024,8 +1480,13 @@ var REASON_ORDER = [
   "refused",
   "cannot-open",
   "did-not-finish",
-  "leads-out"
+  "leads-out",
+  "entry-wrong-shape",
+  "no-description",
+  "the-descriptions-file"
 ];
+var NAMED_ALWAYS = /* @__PURE__ */ new Set(["entry-wrong-shape"]);
+var namedWithoutWhy = (skip) => NAMED_ALWAYS.has(skip.reason) || skip.named === true;
 var FROM_THE_SERVICE = {
   type_not_readable: "type-not-readable",
   too_large: "too-large"
@@ -1037,7 +1498,10 @@ var COUNTED = {
   refused: (many) => `${many} refused`,
   "cannot-open": (many) => `${many} I couldn't open`,
   "did-not-finish": (many) => `${many} that didn't finish`,
-  "leads-out": (many) => `${many} shortcut${many === 1 ? "" : "s"} out of the folder`
+  "leads-out": (many) => `${many} shortcut${many === 1 ? "" : "s"} out of the folder`,
+  "entry-wrong-shape": (many) => `${many} with an entry in the wrong shape`,
+  "no-description": (many) => `${many} with no description`,
+  "the-descriptions-file": (many) => `${many} that ${many === 1 ? "is" : "are"} the descriptions file`
 };
 var IN_DETAIL = {
   "type-not-readable": "a file type I can't read",
@@ -1046,7 +1510,10 @@ var IN_DETAIL = {
   refused: "refused",
   "cannot-open": "I couldn't open it",
   "did-not-finish": "the send didn't finish",
-  "leads-out": "a shortcut out of the folder"
+  "leads-out": "a shortcut out of the folder",
+  "entry-wrong-shape": "not sent: its entry is in the wrong shape.",
+  "no-description": "not sent: it has no description.",
+  "the-descriptions-file": "the descriptions file itself, never sent"
 };
 function countLine(added, space, skipped, why) {
   const documents = `${added} document${added === 1 ? "" : "s"} in ${named(space)}.`;
@@ -1055,11 +1522,13 @@ function countLine(added, space, skipped, why) {
     const many = skipped.filter((skip) => skip.reason === reason).length;
     return many === 0 ? [] : [COUNTED[reason](many)];
   }).join(", ");
-  return `${documents} ${skipped.length} skipped \u2014 ${reasons}.${why ? "" : " Run with --why to see each."}`;
+  const pointAtWhy = !why && skipped.some((skip) => !namedWithoutWhy(skip) && skip.reason !== "the-descriptions-file");
+  return `${documents} ${skipped.length} skipped \u2014 ${reasons}.${pointAtWhy ? " Run with --why to see each." : ""}`;
 }
 function whyLine(skip) {
-  const because = skip.said === void 0 ? IN_DETAIL[skip.reason] : skip.reason === "refused" ? `refused: ${skip.said}` : skip.said;
-  return `${asPrinted(skip.relative)} \u2014 ${because}`;
+  if (skip.line !== void 0) return skip.line;
+  const because2 = skip.said === void 0 ? IN_DETAIL[skip.reason] : skip.reason === "refused" ? `refused: ${skip.said}` : skip.said;
+  return `${asPrinted(skip.relative)} \u2014 ${because2}`;
 }
 var FROM_THE_WALK = {
   "leads-out": "leads-out",
@@ -1068,90 +1537,146 @@ var FROM_THE_WALK = {
 async function runAdd(options, deps = {}) {
   const voice = voiceFor(deps.write ?? ((line) => process.stdout.write(`${line}
 `)));
-  const name = asPrinted(basename(options.file));
+  const name2 = asPrinted(basename(options.file));
   let isFolder;
   try {
     isFolder = (await statPath(options.file)).isDirectory();
   } catch (err) {
     voice.write(
-      err?.code === "ENOENT" ? cannotFind(name) : cannotOpen(name)
+      err?.code === "ENOENT" ? cannotFind(name2) : cannotOpen(name2)
     );
     return { ok: false };
   }
-  return isFolder ? await addFolder(options, deps, voice) : await addOneFile(options, deps, voice);
+  let descriptions;
+  if (options.describedIn !== void 0) {
+    const read = await readDescriptions(options.describedIn);
+    if ("said" in read) {
+      voice.write(read.said);
+      return { ok: false };
+    }
+    descriptions = read;
+  }
+  return isFolder ? await addFolder(options, deps, voice, descriptions) : await addOneFile(options, deps, voice, descriptions);
 }
-async function addOneFile(options, deps, voice) {
-  const name = asPrinted(basename(options.file));
+async function addOneFile(options, deps, voice, descriptions) {
+  const name2 = asPrinted(basename(options.file));
   const handle = await openOne(options.file);
   if (typeof handle === "string") {
-    voice.write(handle === "missing" ? cannotFind(name) : cannotOpen(name));
+    voice.write(handle === "missing" ? cannotFind(name2) : cannotOpen(name2));
     return { ok: false };
   }
   try {
-    const byteSize = (await handle.stat()).size;
+    const info = await handle.stat({ bigint: true });
+    const byteSize = Number(info.size);
+    let described;
+    if (descriptions !== void 0) {
+      if (sameFile({ dev: info.dev, ino: info.ino }, descriptions.identity)) {
+        voice.write(isTheDescriptionsFile(name2));
+        return { ok: false };
+      }
+      const key = asKey(basename(options.file));
+      const found = descriptions.entries.get(key);
+      if (found === void 0 && descriptions.entries.size > 0) {
+        voice.write(noEntryMatches(descriptions.name, basename(options.file)));
+        return { ok: false };
+      }
+      const namingNothing = [...descriptions.entries].filter(([other]) => other !== key).flatMap(([, other]) => other.keys);
+      if (namingNothing.length > 0) voice.write(namingNoFile(namingNothing.sort()));
+      if (found !== void 0) {
+        const checked = checkEntry(found);
+        if ("wrong" in checked) {
+          voice.write(`${name2} \u2014 not sent: ${checked.wrong}`);
+          return { ok: false };
+        }
+        described = checked.described;
+      }
+    }
     const auth2 = deps.auth ?? await resolveAuth(options);
     if (auth2 === null) {
       voice.write(CANNOT_REACH_DAZZER);
       return { ok: false };
     }
-    const settled = await settleSpace(options, auth2, deps, voice, name);
+    const settled = await settleSpace(options, auth2, deps, voice, name2);
     if (settled === null) return { ok: false };
     const outcome = await sendOneSafely({
       path: options.file,
       handle,
       byteSize,
       scopeId: settled.scopeId,
+      ...described === void 0 ? {} : { described },
       options,
       deps,
       auth: auth2,
       voice
     });
-    switch (outcome.kind) {
-      case "added":
-        voice.write(`${outcome.fileName} is in Dazzer, in ${named(outcome.space)}.`);
-        return { ok: true };
-      case "already-here":
-        voice.write(ALREADY_IN);
-        return { ok: true };
-      // ONE FILE, ONE QUESTION, IN THE SERVICE'S OWN WORDS. It is the only thing that knows what it
-      // already holds and what the space is called, and rewriting its question here would be a
-      // second wording of a question somebody approved. Nothing was added and nobody has answered,
-      // so this run did not do what it was asked to — the same answer a run that asked where things
-      // go gives.
-      case "held":
-        voice.write(outcome.question);
-        return { ok: false };
-      // ONE FILE, ONE REFUSAL, AND THE PLACES IT OFFERED. The sentence is the service's and is
-      // printed as sent; the places under it are the service's too, and without them a refusal
-      // that says to name one of them is a dead end for the person holding this one file.
-      case "refused":
-        voice.write(outcome.said ?? wentWrong(name));
-        offerThePlaces(voice.write, outcome);
-        return { ok: false };
-      case "did-not-finish":
-        voice.write(didNotFinish(name));
-        return { ok: false };
-      case "not-reached":
-        voice.write(CANNOT_REACH_DAZZER);
-        return { ok: false };
-      case "went-wrong":
-        voice.write(wentWrong(name));
-        return { ok: false };
-      // IT OPENED AND WOULD NOT READ — answered in the approved sentence for a file that cannot be
-      // opened, because that is the same thing a person can act on, and never as a crash.
-      case "cannot-read":
-        voice.write(cannotOpen(name));
-        return { ok: false };
-      case "stop":
-        say(voice.write, outcome.answer, name);
-        return { ok: false };
+    const result = answerForOneFile(outcome, name2, voice);
+    if (outcome.kind === "added" && descriptions !== void 0 && !("description" in (described ?? {}))) {
+      voice.write(itHadNoDescription);
     }
+    if (outcome.kind === "already-here" && outcome.description !== void 0) {
+      voice.write(
+        outcome.description === "filed" ? itsDescriptionFiledNow : outcome.description === "already-described" ? itAlreadyHasOne : itsDescriptionNotKept
+      );
+    }
+    if (outcome.kind === "added" || outcome.kind === "already-here") {
+      for (const line of outcome.notKept) voice.write(`${name2}: ${line}`);
+    }
+    return result;
   } finally {
     await handle.close();
   }
 }
-async function addFolder(options, deps, voice) {
-  const name = asPrinted(basename(options.file));
+function answerForOneFile(outcome, name2, voice) {
+  switch (outcome.kind) {
+    case "added":
+      voice.write(`${outcome.fileName} is in Dazzer, in ${named(outcome.space)}.`);
+      return { ok: true };
+    case "already-here":
+      voice.write(ALREADY_IN);
+      return { ok: true };
+    // ONE FILE, ONE QUESTION, IN THE SERVICE'S OWN WORDS. It is the only thing that knows what it
+    // already holds and what the space is called, and rewriting its question here would be a
+    // second wording of a question somebody approved. Nothing was added and nobody has answered,
+    // so this run did not do what it was asked to — the same answer a run that asked where things
+    // go gives.
+    case "held":
+      voice.write(outcome.question);
+      return { ok: false };
+    // ONE FILE, ONE REFUSAL, AND THE PLACES IT OFFERED. The sentence is the service's and is
+    // printed as sent; the places under it are the service's too, and without them a refusal
+    // that says to name one of them is a dead end for the person holding this one file. A refusal
+    // whose sentence is written for whoever makes the call is said in this command's own words.
+    case "refused": {
+      const because2 = notAddedBecause(outcome);
+      voice.write(
+        because2 === void 0 ? outcome.said ?? wentWrong(name2) : notAdded(name2, because2)
+      );
+      const next = whatToDoAbout(outcome);
+      if (next !== void 0) voice.write(next);
+      offerThePlaces(voice.write, outcome);
+      return { ok: false };
+    }
+    case "did-not-finish":
+      voice.write(didNotFinish(name2));
+      return { ok: false };
+    case "not-reached":
+      voice.write(CANNOT_REACH_DAZZER);
+      return { ok: false };
+    case "went-wrong":
+      voice.write(wentWrong(name2));
+      return { ok: false };
+    // IT OPENED AND WOULD NOT READ — answered in the approved sentence for a file that cannot be
+    // opened, because that is the same thing a person can act on, and never as a crash.
+    case "cannot-read":
+      voice.write(cannotOpen(name2));
+      return { ok: false };
+    case "stop":
+      say(voice.write, outcome.answer, name2);
+      return { ok: false };
+  }
+}
+async function addFolder(options, deps, voice, descriptions) {
+  const name2 = asPrinted(basename(options.file));
   const walked = await (async () => {
     try {
       return await walkFolder(options.file);
@@ -1160,7 +1685,30 @@ async function addFolder(options, deps, voice) {
     }
   })();
   if (walked === null) {
-    voice.write(cannotOpen(name));
+    voice.write(cannotOpen(name2));
+    return { ok: false };
+  }
+  const found = new Set([...walked.files, ...walked.skipped].map((one) => asKey(one.relative)));
+  const entries = [...descriptions?.entries ?? /* @__PURE__ */ new Map()];
+  const namingNothing = entries.filter(([key]) => !found.has(key)).flatMap(([, entry]) => entry.keys).sort();
+  if (descriptions !== void 0 && entries.length > 0 && entries.every(([key]) => !found.has(key))) {
+    voice.write(
+      noEntryMatches(
+        descriptions.name,
+        await aKeyItWouldMatch(walked.files, descriptions.identity)
+      )
+    );
+    return { ok: false };
+  }
+  const worthAsking = walked.files.some((file) => {
+    const entry = descriptions?.entries.get(asKey(file.relative));
+    if (entry === void 0) return false;
+    const checked = checkEntry(entry);
+    return "wrong" in checked || "description" in checked.described;
+  });
+  if (walked.files.length > 0 && !worthAsking) {
+    voice.write(NOTHING_DESCRIBED);
+    voice.write(DESCRIBE_THEM);
     return { ok: false };
   }
   const auth2 = deps.auth ?? await resolveAuth(options);
@@ -1168,7 +1716,7 @@ async function addFolder(options, deps, voice) {
     voice.write(CANNOT_REACH_DAZZER);
     return { ok: false };
   }
-  const settled = await settleSpace(options, auth2, deps, voice, name);
+  const settled = await settleSpace(options, auth2, deps, voice, name2);
   if (settled === null) return { ok: false };
   const skipped = walked.skipped.map((skip) => ({
     relative: skip.relative,
@@ -1177,7 +1725,33 @@ async function addFolder(options, deps, voice) {
   const held = [];
   let added = 0;
   let ran = true;
+  const notKept = [];
+  const alreadyThere = { filed: 0, alreadyDescribed: 0, notKept: 0 };
   for (const file of walked.files) {
+    let described;
+    const entry = descriptions?.entries.get(asKey(file.relative));
+    if (entry !== void 0) {
+      const checked = checkEntry(entry);
+      if ("wrong" in checked) {
+        skipped.push({
+          relative: file.relative,
+          reason: "entry-wrong-shape",
+          said: `not sent: ${checked.wrong}`
+        });
+        continue;
+      }
+      described = checked.described;
+    }
+    if (described === void 0 || !("description" in described)) {
+      skipped.push(
+        descriptions !== void 0 && await isFile(file.path, descriptions.identity) ? { relative: file.relative, reason: "the-descriptions-file" } : {
+          relative: file.relative,
+          reason: "no-description",
+          line: notSentNoDescription(asPrinted(file.relative))
+        }
+      );
+      continue;
+    }
     const handle = await openOne(file.path);
     if (typeof handle === "string") {
       skipped.push({ relative: file.relative, reason: "cannot-open" });
@@ -1185,11 +1759,13 @@ async function addFolder(options, deps, voice) {
     }
     let outcome;
     try {
-      outcome = await sendOneSafely({
+      const info = await handle.stat({ bigint: true });
+      outcome = descriptions !== void 0 && sameFile({ dev: info.dev, ino: info.ino }, descriptions.identity) ? "the-descriptions-file" : await sendOneSafely({
         path: file.path,
         handle,
-        byteSize: (await handle.stat()).size,
+        byteSize: Number(info.size),
         scopeId: settled.scopeId,
+        ...described === void 0 ? {} : { described },
         options,
         deps,
         auth: auth2,
@@ -1198,6 +1774,18 @@ async function addFolder(options, deps, voice) {
     } finally {
       await handle.close();
     }
+    if (outcome === "the-descriptions-file") {
+      skipped.push({ relative: file.relative, reason: "the-descriptions-file" });
+      continue;
+    }
+    if (outcome.kind === "added" || outcome.kind === "already-here") {
+      if (outcome.notKept.length > 0)
+        notKept.push({ relative: file.relative, lines: outcome.notKept });
+    }
+    if (outcome.kind === "already-here" && outcome.description !== void 0) {
+      const answer = outcome.description;
+      alreadyThere[answer === "filed" ? "filed" : answer === "already-described" ? "alreadyDescribed" : "notKept"] += 1;
+    }
     if (outcome.kind === "added") {
       added += 1;
       continue;
@@ -1215,12 +1803,19 @@ async function addFolder(options, deps, voice) {
       continue;
     }
     if (outcome.kind === "refused") {
+      const because2 = notAddedBecause(outcome);
+      const reason = (outcome.code === void 0 ? void 0 : FROM_THE_SERVICE[outcome.code]) ?? "refused";
       skipped.push({
         relative: file.relative,
-        // KEYED ON THE SERVICE'S CODE, never on the words it sent: the words are the person's and
-        // may be reworded, the code is the label the service publishes.
-        reason: (outcome.code === void 0 ? void 0 : FROM_THE_SERVICE[outcome.code]) ?? "refused",
-        ...outcome.said === void 0 ? {} : { said: outcome.said }
+        reason,
+        ...outcome.said === void 0 ? {} : { said: outcome.said },
+        ...because2 === void 0 ? {} : { line: notAdded(asPrinted(file.relative), because2) },
+        // REFUSED ALTHOUGH IT CARRIED AN ENTRY, which every file sent now does: most likely about
+        // what the entry says, which only the person's assistant can put right, so it is named
+        // without anybody having to run the whole folder again with `--why`. A refusal about the
+        // file's kind or size is about the file, not its entry, so it stays a count that `--why`
+        // names: a folder with thirty spreadsheets in it is one line, not thirty.
+        ...reason === "refused" ? { named: true } : {}
       });
       continue;
     }
@@ -1233,15 +1828,30 @@ async function addFolder(options, deps, voice) {
       continue;
     }
     if (outcome.kind === "not-reached") voice.write(CANNOT_REACH_DAZZER);
-    else say(voice.write, outcome.answer, name);
+    else say(voice.write, outcome.answer, name2);
     ran = false;
     break;
   }
   skipped.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
   held.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
+  notKept.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
+  const undescribed = skipped.filter((skip) => skip.reason === "no-description");
+  if (undescribed.length <= NAMED_WHEN_AT_MOST) {
+    for (const skip of undescribed) skip.named = true;
+  }
   voice.write(countLine(added, settled.space, skipped, options.why === true));
+  if (skipped.some((skip) => skip.reason === "the-descriptions-file")) voice.write(keepItBeside);
+  if (alreadyThere.filed + alreadyThere.alreadyDescribed + alreadyThere.notKept > 0) {
+    voice.write(alreadyThereDescriptions(alreadyThere));
+  }
+  if (namingNothing.length > 0) voice.write(namingNoFile(namingNothing));
   if (held.length > 0) voice.write(waitingOnYou(held.length));
-  if (options.why === true) for (const skip of skipped) voice.write(whyLine(skip));
+  for (const skip of skipped) {
+    if (options.why === true || namedWithoutWhy(skip)) voice.write(whyLine(skip));
+  }
+  for (const one of notKept) {
+    for (const line of one.lines) voice.write(`${asPrinted(one.relative)}: ${line}`);
+  }
   const onlyOne = held.length === 1 ? held[0] : void 0;
   if (onlyOne !== void 0) {
     voice.write(onlyOne.question);
@@ -1253,7 +1863,25 @@ async function addFolder(options, deps, voice) {
       )
     );
   }
-  return { ok: ran };
+  return { ok: ran && !skipped.some(LEAVES_A_FILE_OUT) };
+}
+async function isFile(path, identity) {
+  try {
+    const info = await statPath(path, { bigint: true });
+    return sameFile({ dev: info.dev, ino: info.ino }, identity);
+  } catch {
+    return false;
+  }
+}
+async function aKeyItWouldMatch(files, descriptionsFile) {
+  for (const file of files) {
+    try {
+      const info = await statPath(file.path, { bigint: true });
+      if (!sameFile({ dev: info.dev, ino: info.ino }, descriptionsFile)) return file.relative;
+    } catch {
+    }
+  }
+  return void 0;
 }
 function offerThePlaces(write, offer) {
   const places = offer.choices ?? [];
@@ -1262,10 +1890,10 @@ function offerThePlaces(write, offer) {
   for (const place of places) write(choiceLine(place.space, place.scopeId));
   write(answerWith(keepToYourself, places.length > 0));
 }
-function say(write, answer, name) {
+function say(write, answer, name2) {
   switch (answer.status) {
     case "refused":
-      write(answer.detail ?? wentWrong(name));
+      write(answer.detail ?? wentWrong(name2));
       offerThePlaces(write, answer);
       return;
     case "sign-in-invalid":
@@ -1978,23 +2606,40 @@ function signInServerDefaults() {
 
 // src/index.ts
 var require2 = createRequire(import.meta.url);
-var { version } = require2("../package.json");
+var { name, version } = require2("../package.json");
+var client = `${name}/${version}`;
 var program = new Command();
 program.name("dazzer").description("Sign in to Dazzer from your terminal").version(version);
-program.command("add").description("Put a file, or a whole folder, into Dazzer").argument("<path>", "The file or folder to add").option("--space <name>", "The space to put it in \u2014 the name you were shown, or its number").option("--keep-to-myself", "Keep it to yourself, rather than putting it in a shared space").option("--why", "Show each document that was skipped, and why").action(async (file, opts) => {
-  const env = validateEnv();
-  const result = await runAdd({
-    file,
-    space: opts.space,
-    keepToMyself: opts.keepToMyself === true,
-    why: opts.why === true,
-    baseUrl: env.DAZZER_API_BASE_URL,
-    issuer: env.DAZZER_AUTH_ISSUER,
-    clientId: env.DAZZER_AUTH_CLIENT_ID,
-    resource: env.DAZZER_AUTH_RESOURCE
-  });
-  if (!result.ok) process.exitCode = 1;
+var newerTool;
+program.hook("preAction", () => {
+  newerTool = lookForNewerTool({ name, version, folder: getConfigDir() });
+});
+program.hook("postAction", async () => {
+  const said = await newerTool?.finish();
+  if (said) process.stderr.write(`${said}
+`);
 });
+program.command("add").description("Put a file, or a whole folder, into Dazzer").argument("<path>", "The file or folder to add").option("--space <name>", "The space to put it in \u2014 the name you were shown, or its number").option("--keep-to-myself", "Keep it to yourself, rather than putting it in a shared space").option("--why", "Show each document that was skipped, and why").option(
+  "--described-in <file>",
+  "A JSON file saying what each file is, keyed by its path inside the folder"
+).action(
+  async (file, opts) => {
+    const env = validateEnv();
+    const result = await runAdd({
+      file,
+      space: opts.space,
+      keepToMyself: opts.keepToMyself === true,
+      why: opts.why === true,
+      ...opts.describedIn === void 0 ? {} : { describedIn: opts.describedIn },
+      client,
+      baseUrl: env.DAZZER_API_BASE_URL,
+      issuer: env.DAZZER_AUTH_ISSUER,
+      clientId: env.DAZZER_AUTH_CLIENT_ID,
+      resource: env.DAZZER_AUTH_RESOURCE
+    });
+    if (!result.ok) process.exitCode = 1;
+  }
+);
 var auth = program.command("auth").description("Manage sign-in");
 auth.command("login").description("Sign in through your browser; falls back to a device code when headless").option("--issuer <url>", "Authorization server URL").option("--client-id <id>", "OAuth client id").option("--resource <url>", "Resource indicator for access tokens").option("--no-browser", "Use the device-code flow instead of opening a browser").action(
   async (opts) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dazzer-connect",
   "private": false,
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Sign in to Dazzer \u2014 the memory your AI tools share \u2014 from a terminal, for clients that cannot sign in themselves",
   "license": "MIT",
   "type": "module",
@@ -34,16 +34,16 @@
     "dev": "tsx src/index.ts"
   },
   "dependencies": {
-    "@napi-rs/keyring": "^2.0.0",
+    "@napi-rs/keyring": "^2.1.0",
     "commander": "^15.0.0",
     "env-paths": "^4.0.0",
-    "zod": "^4.6.1"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@dazzer/auth-ui": "workspace:*",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.2",
     "esbuild": "^0.28.2",
-    "tsx": "^4.23.13",
+    "tsx": "^4.23.15",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11"
   },