dazzer-connect 0.2.0 → 0.3.0

package/README.md

@@ -67,6 +67,60 @@ 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
+
+```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.
+
+### 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, a later `dazzer add ./backlog` without `--described-in` would send it like any other file. 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 goes in as usual, and the count names it.
+- An entry that names no file being added is reported, and nothing is sent for it. If no entry names a file being added, nothing is sent at all.
+- A file Dazzer refuses although it had an entry is named, in Dazzer's own words.
+- Whatever Dazzer did not keep of an entry is printed file by file, with what to change.
+- 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.
+
 ## Other commands
 
 ```bash

package/dist/index.js

@@ -265,6 +265,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) => {
@@ -357,7 +358,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;
@@ -733,7 +735,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 +758,34 @@ 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.";
+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 +815,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 +892,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 +907,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 +921,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);
@@ -925,6 +953,7 @@ async function sendOne(input) {
   const described = await callPaced(
     {
       baseUrl: options.baseUrl,
+      client: options.client,
       path: LANDING_PATH,
       method: "POST",
       body: {
@@ -984,9 +1013,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 +1026,269 @@ 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",
+  "quote-not-in-document": "the words it quotes are not in the document"
+};
+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 inPlainWords = (words, name2) => words[name2] ?? name2;
+var SHORT_EXAMPLE = 120;
+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);
+    const how = wordsOf(description.how);
+    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(how === void 0 ? what : `${what} ${how}`);
+    } else if (state !== void 0 && state !== "filed" && state !== "none_supplied" && !(alreadyHere && state === "not_filed")) {
+      lines.push(
+        state === "not_filed" ? "description not filed." : `description not filed: ${inPlainWords(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);
+      const what2 = wordsOf(dropped.what);
+      const how2 = wordsOf(dropped.how);
+      const why = what2 === void 0 ? reason === void 0 ? void 0 : inPlainWords(LINE_DROPPED, reason) : how2 === void 0 ? what2 : `${what2} ${how2}`;
+      if (line !== void 0 && why !== void 0) lines.push(`${line} dropped: ${why}`);
+    }
+    const howMuch = isPlainObject(description.how_much_was_read) ? description.how_much_was_read : null;
+    const howMuchWhat = howMuch === null ? void 0 : wordsOf(howMuch.what);
+    if (howMuch !== null && howMuchWhat !== void 0) {
+      const howMuchHow = wordsOf(howMuch.how);
+      const example = howMuch.example === void 0 ? "" : JSON.stringify(howMuch.example);
+      lines.push(
+        `how_much_was_read not kept: ${howMuchWhat}` + (howMuchHow === void 0 ? "" : ` ${howMuchHow}`) + (example !== "" && example.length <= SHORT_EXAMPLE ? ` Example: ${example}` : "")
+      );
+    }
+  }
+  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} dropped: ${inPlainWords(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(`document_date not kept: ${inPlainWords(DATE_NOT_KEPT, date)}`);
+  }
+  const typed = wordsOf(stored.transcription);
+  if (typed !== void 0 && typed !== "used" && !(alreadyHere && typed === "not_used_document_already_held")) {
+    lines.push(`transcription not used: ${inPlainWords(TYPING_NOT_USED, typed)}`);
+  }
+  return {
+    notKept: lines.map(asPrinted),
+    ...filing === void 0 ? {} : { description: filing }
   };
 }
 async function sendOneSafely(input) {
@@ -1024,8 +1312,12 @@ var REASON_ORDER = [
   "refused",
   "cannot-open",
   "did-not-finish",
-  "leads-out"
+  "leads-out",
+  "entry-wrong-shape",
+  "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 +1329,9 @@ 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`,
+  "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,16 +1340,19 @@ 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.",
+  "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)}.`;
+function countLine(added, space, skipped, why, undescribed = []) {
+  const documents = `${added} document${added === 1 ? "" : "s"} in ${named(space)}.` + (undescribed.length === 0 ? "" : ` ${undescribed.length} had no description${undescribed.length <= NAMED_WHEN_AT_MOST ? ` \u2014 ${listed(undescribed.map(asPrinted))}` : ""}.`);
   if (skipped.length === 0) return documents;
   const reasons = REASON_ORDER.flatMap((reason) => {
     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;
@@ -1068,90 +1365,139 @@ 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} \u2014 ${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.
+    case "refused":
+      voice.write(outcome.said ?? wentWrong(name2));
+      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 +1506,19 @@ 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 auth2 = deps.auth ?? await resolveAuth(options);
@@ -1168,7 +1526,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 +1535,24 @@ async function addFolder(options, deps, voice) {
   const held = [];
   let added = 0;
   let ran = true;
+  const undescribed = [];
+  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;
+    }
     const handle = await openOne(file.path);
     if (typeof handle === "string") {
       skipped.push({ relative: file.relative, reason: "cannot-open" });
@@ -1185,11 +1560,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,8 +1575,23 @@ 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;
+      if (descriptions !== void 0 && !("description" in (described ?? {}))) {
+        undescribed.push(file.relative);
+      }
       continue;
     }
     if (outcome.kind === "already-here") {
@@ -1220,7 +1612,11 @@ async function addFolder(options, deps, voice) {
         // 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 }
+        ...outcome.said === void 0 ? {} : { said: outcome.said },
+        // REFUSED ALTHOUGH IT CARRIED AN ENTRY: most likely about what the entry says, which only
+        // the person's assistant can put right — so it is named, in the service's own sentence,
+        // without anybody having to run the whole folder again with `--why` to find out.
+        ...described === void 0 ? {} : { named: true }
       });
       continue;
     }
@@ -1233,15 +1629,26 @@ 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);
-  voice.write(countLine(added, settled.space, skipped, options.why === true));
+  notKept.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
+  voice.write(countLine(added, settled.space, skipped, options.why === true, undescribed));
+  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)} \u2014 ${line}`);
+  }
   const onlyOne = held.length === 1 ? held[0] : void 0;
   if (onlyOne !== void 0) {
     voice.write(onlyOne.question);
@@ -1255,6 +1662,16 @@ async function addFolder(options, deps, voice) {
   }
   return { ok: ran };
 }
+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 ?? [];
   const keepToYourself = offer.keepToYourself === true;
@@ -1262,10 +1679,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 +2395,31 @@ 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;
-});
+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.3.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"
   },