dazzer-connect 0.1.1 → 0.3.0

package/dist/index.js

@@ -4,6 +4,392 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
 
+// src/commands/add.ts
+import { open, stat as statPath } from "node:fs/promises";
+import { basename, extname } from "node:path";
+
+// src/lib/output.ts
+function writeOut(message) {
+  process.stdout.write(`${message}
+`);
+}
+function writeErr(message) {
+  process.stderr.write(`${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`).";
+function printDeviceInstructions(deviceAuth) {
+  writeOut("");
+  if (deviceAuth.verification_uri_complete) {
+    writeOut("To finish signing in, open this link in your browser:");
+    writeOut(`  ${deviceAuth.verification_uri_complete}`);
+  } else {
+    writeOut("To finish signing in, open this page in your browser:");
+    writeOut(`  ${deviceAuth.verification_uri}`);
+    writeOut("");
+    writeOut("Then enter this code:");
+    writeOut(`  ${deviceAuth.user_code}`);
+  }
+  writeOut("");
+  writeOut("Waiting for you to approve in the browser...");
+}
+function printBrowserOpening(url) {
+  writeOut("");
+  writeOut("Opening your browser to sign in\u2026");
+  writeOut("If it doesn't open automatically, paste this into your browser:");
+  writeOut(`  ${url}`);
+  writeOut("");
+}
+function printLoginSuccess(keychainOk) {
+  writeOut("");
+  writeOut("Signed in successfully.");
+  if (!keychainOk) {
+    writeErr("Warning: could not save tokens to the OS keychain. Use the config below.");
+  }
+}
+function printConnectGuidance(mcpServerUrl, accessToken) {
+  const url = mcpServerUrl.replace(/\/$/, "");
+  writeOut("");
+  writeOut("Connect an AI client to Dazzer.");
+  writeOut("");
+  writeOut("Recommended \u2014 add this server by URL and sign in from your client;");
+  writeOut("it stays connected and renews itself:");
+  writeOut("");
+  writeOut("{");
+  writeOut('  "mcpServers": {');
+  writeOut('    "dazzer": {');
+  writeOut(`      "url": "${url}"`);
+  writeOut("    }");
+  writeOut("  }");
+  writeOut("}");
+  writeOut("");
+  writeOut("Fallback \u2014 only if your client cannot sign in and needs a pasted token.");
+  writeOut("This token expires in about an hour; re-run `dazzer auth login` to renew:");
+  writeOut("");
+  writeOut("{");
+  writeOut('  "mcpServers": {');
+  writeOut('    "dazzer": {');
+  writeOut(`      "url": "${url}",`);
+  writeOut('      "headers": {');
+  writeOut(`        "Authorization": "Bearer ${accessToken}"`);
+  writeOut("      }");
+  writeOut("    }");
+  writeOut("  }");
+  writeOut("}");
+  writeOut("");
+}
+function printAuthStatus(params) {
+  switch (params.state) {
+    case "signed-out":
+      writeOut("Not signed in. Run: dazzer auth login");
+      return;
+    case "store-unreadable":
+      writeOut("Cannot tell \u2014 this machine's credential store could not be opened.");
+      writeOut("  Common on servers and containers, which often have none.");
+      writeOut("  Run: dazzer auth login \u2014 it prints a pass you can paste in.");
+      return;
+    case "expired":
+      writeOut("Your sign-in has expired or been revoked. Run: dazzer auth login");
+      return;
+    case "unverified":
+      writeOut(
+        "Signed in on this device, but the sign-in server could not be reached to confirm it."
+      );
+      if (params.issuer) {
+        writeOut(`  Signed in at: ${params.issuer}`);
+      }
+      if (params.lastKnownExpiresAt) {
+        writeOut(`  Last confirmed expiry: ${new Date(params.lastKnownExpiresAt).toISOString()}`);
+      }
+      writeOut("  Check your connection, then run this again to confirm.");
+      return;
+    case "signed-in":
+      writeOut("Signed in \u2014 confirmed just now.");
+      if (params.issuer) {
+        writeOut(`  Signed in at: ${params.issuer}`);
+      }
+      if (params.expiresAt) {
+        writeOut(
+          `  This token expires ${new Date(params.expiresAt).toISOString()} and refreshes automatically.`
+        );
+      }
+      return;
+  }
+}
+function printLogoutSuccess() {
+  writeOut("Signed out.");
+}
+function printLogoutStoreLocked(offerForget) {
+  writeErr(
+    "Not signed out. This machine's credential store could not be opened, so a sign-in saved here may still work."
+  );
+  writeErr(
+    offerForget ? "  Unlock it and try again. If this machine has no credential store, run: dazzer auth logout --forget-this-machine" : "  Unlock it and try again."
+  );
+}
+function printLogoutNotCancelledYet() {
+  writeErr(
+    "Not signed out. Your sign-in could not be cancelled right now, so it is still saved here."
+  );
+  writeErr("  Try again: dazzer auth logout");
+}
+function printLogoutCannotCancel() {
+  writeOut(
+    "Signed out on this device, but your sign-in could not be cancelled at the server. It stops working once it goes 30 days unused."
+  );
+}
+function printLogoutNothingFound() {
+  writeOut("No saved sign-in was found here to cancel.");
+}
+function printLogoutIncomplete(cancelledAtServer) {
+  if (cancelledAtServer) {
+    writeErr(
+      "Not fully signed out. Your sign-in is cancelled, but this machine's credential store would not let it be removed, so what is saved here can work for up to an hour."
+    );
+  } else {
+    writeErr(
+      "Not signed out. This machine's credential store would not let your saved sign-in be removed, so it may still work from here."
+    );
+  }
+  writeErr("  Try again: dazzer auth logout");
+}
+function printLogoutForgotten() {
+  writeOut(
+    "Forgot this machine's sign-in record. Nothing was cancelled, and any sign-in still saved in this machine's credential store stays there."
+  );
+}
+function printForgetFailed(configDir) {
+  writeErr("Not forgotten: this machine's sign-in record could not be removed.");
+  writeErr(`  Remove it by hand: ${configDir}`);
+}
+function printLogoutPassLeft() {
+  writeOut(
+    "No sign-in that can be renewed is saved here. A short-lived pass this machine's credential store would not remove stops working within the hour."
+  );
+}
+function printLogoutBadSettings() {
+  writeErr(
+    "Not signed out. DAZZER_AUTH_ISSUER or DAZZER_AUTH_CLIENT_ID is not a valid setting, so there is nowhere to cancel your sign-in."
+  );
+  writeErr("  Fix it, then run: dazzer auth logout");
+}
+function printForgetRefused() {
+  writeErr(
+    "Not forgotten: a sign-in may be saved in this machine's credential store. Unlock it if needed, then run: dazzer auth logout"
+  );
+}
+function fail(message) {
+  writeErr(`Error: ${message}`);
+  process.exit(1);
+}
+
+// src/lib/refresh.ts
+var RefreshRejectedError = class extends Error {
+  constructor(oauthError) {
+    super(`Could not refresh token: ${oauthError}`);
+    this.oauthError = oauthError;
+    this.name = "RefreshRejectedError";
+  }
+  oauthError;
+};
+async function refreshAccessToken(options) {
+  const fetchFn = options.fetchFn ?? fetch;
+  const params = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: options.clientId,
+    refresh_token: options.refreshToken
+  });
+  if (options.resource) {
+    params.set("resource", options.resource);
+  }
+  const res = await fetchFn(options.discovery.tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: params.toString()
+  });
+  const body = await res.json();
+  if (!res.ok) {
+    const error = typeof body.error === "string" ? body.error : "refresh_failed";
+    throw new RefreshRejectedError(error);
+  }
+  const accessToken = body.access_token;
+  const refreshToken = body.refresh_token;
+  if (typeof accessToken !== "string") {
+    throw new Error("The authorization server returned an unexpected refresh response.");
+  }
+  const newRefresh = typeof refreshToken === "string" ? refreshToken : options.refreshToken;
+  const expiresIn = typeof body.expires_in === "number" ? body.expires_in : null;
+  await options.tokenStore.save({ accessToken, refreshToken: newRefresh });
+  return { accessToken, refreshToken: newRefresh, expiresIn };
+}
+async function getValidAccessToken(options) {
+  const stored = await options.tokenStore.load();
+  if (!stored) {
+    return { status: "signed-out" };
+  }
+  try {
+    const refreshed = await refreshAccessToken({ ...options, refreshToken: stored.refreshToken });
+    return { status: "refreshed", expiresIn: refreshed.expiresIn };
+  } catch (err) {
+    if (err instanceof RefreshRejectedError) {
+      return { status: "rejected" };
+    }
+    return { status: "unreachable" };
+  }
+}
+async function persistLoginTokens(tokenStore, tokens) {
+  if (!tokens.refresh_token) {
+    throw new Error("The authorization server did not return a refresh token.");
+  }
+  const stored = {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token
+  };
+  await tokenStore.save(stored);
+  return stored;
+}
+
+// src/lib/api-client.ts
+function assertHttpsServiceAddress(address) {
+  let parsed;
+  try {
+    parsed = new URL(address);
+  } catch {
+    throw new Error(`Not a valid Dazzer address: ${address}. Check DAZZER_API_BASE_URL.`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(
+      `The Dazzer address must be an https URL (got ${parsed.protocol}//). Check DAZZER_API_BASE_URL.`
+    );
+  }
+  return address.replace(/\/$/, "");
+}
+var CLIENT_HEADER = "x-dazzer-client";
+function readOfferedPlaces(offered) {
+  if (!Array.isArray(offered)) return [];
+  return offered.flatMap((place) => {
+    if (typeof place !== "object" || place === null) return [];
+    const { scope_id: scopeId, space } = place;
+    if (typeof scopeId !== "number" || !Number.isFinite(scopeId)) return [];
+    if (typeof space !== "string" || space.trim() === "") return [];
+    return [{ scopeId, space }];
+  });
+}
+async function readJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return void 0;
+  }
+}
+function refusalDetail(body) {
+  if (typeof body !== "object" || body === null) return void 0;
+  const flat = body.detail;
+  if (typeof flat === "string" && flat !== "") return flat;
+  const enveloped = body.error;
+  if (typeof enveloped === "object" && enveloped !== null) {
+    const message = enveloped.message;
+    if (typeof message === "string" && message !== "") return message;
+  }
+  return void 0;
+}
+function refusalCode(body) {
+  if (typeof body !== "object" || body === null) return void 0;
+  const flat = body.code;
+  if (typeof flat === "string" && flat !== "") return flat;
+  const enveloped = body.error;
+  if (typeof enveloped === "object" && enveloped !== null) {
+    const code = enveloped.code;
+    if (typeof code === "string" && code !== "") return code;
+  }
+  return void 0;
+}
+function refusalPlaces(body) {
+  if (typeof body !== "object" || body === null) return {};
+  const offered = body.choices;
+  const places = readOfferedPlaces(offered);
+  const keep = body.keep_to_yourself;
+  return {
+    ...places.length > 0 ? { choices: places } : {},
+    ...typeof keep === "boolean" ? { keepToYourself: keep } : {}
+  };
+}
+async function resolveCredential(auth2) {
+  let held;
+  try {
+    held = await auth2.tokenStore.load();
+  } catch {
+    return { status: "store-unreadable" };
+  }
+  if (!held) return { status: "signed-out" };
+  let state;
+  try {
+    state = await getValidAccessToken(auth2);
+  } catch {
+    return { status: "store-unreadable" };
+  }
+  switch (state.status) {
+    case "signed-out":
+      return { status: "signed-out" };
+    case "rejected":
+      return { status: "sign-in-invalid" };
+    case "unreachable":
+      return { held: held.accessToken };
+    case "refreshed": {
+      try {
+        const rotated = await auth2.tokenStore.load();
+        return rotated ? { held: rotated.accessToken } : { status: "signed-out" };
+      } catch {
+        return { status: "store-unreadable" };
+      }
+    }
+  }
+}
+async function callDazzer(request) {
+  const base = assertHttpsServiceAddress(request.baseUrl);
+  const credential = await resolveCredential(request.auth);
+  if (!("held" in credential)) {
+    if (credential.status === "sign-in-invalid") {
+      return { status: "sign-in-invalid", message: SIGN_IN_NO_LONGER_VALID };
+    }
+    return { status: credential.status };
+  }
+  const fetchFn = request.fetchFn ?? fetch;
+  const headers = {
+    accept: "application/json",
+    authorization: `Bearer ${credential.held}`,
+    [CLIENT_HEADER]: request.client
+  };
+  if (request.body !== void 0) headers["content-type"] = "application/json";
+  let res;
+  try {
+    res = await fetchFn(`${base}${request.path}`, {
+      method: request.method ?? "POST",
+      headers,
+      body: request.body === void 0 ? void 0 : JSON.stringify(request.body)
+    });
+  } catch {
+    return { status: "unreachable", message: CANNOT_REACH_DAZZER };
+  }
+  if (res.status === 401) {
+    return { status: "sign-in-invalid", message: SIGN_IN_NO_LONGER_VALID };
+  }
+  const body = await readJson(res);
+  if (!res.ok) {
+    const detail = refusalDetail(body);
+    const code = refusalCode(body);
+    return {
+      status: "refused",
+      httpStatus: res.status,
+      ...detail === void 0 ? {} : { detail },
+      ...code === void 0 ? {} : { code },
+      ...refusalPlaces(body)
+    };
+  }
+  return { status: "ok", httpStatus: res.status, body };
+}
+
 // src/lib/config-store.ts
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -22,12 +408,26 @@ function assertHttpsIssuer(issuer) {
   }
   return issuer.replace(/\/$/, "");
 }
-async function discoverEndpoints(issuer) {
+var DiscoveryAnswered = class extends Error {
+  constructor(status) {
+    super(`Could not reach the authorization server (${status}). Check --issuer.`);
+    this.status = status;
+    this.name = "DiscoveryAnswered";
+  }
+  status;
+};
+var DiscoveryUnusable = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DiscoveryUnusable";
+  }
+};
+async function discoverEndpoints(issuer, fetchFn = fetch) {
   const normalized = assertHttpsIssuer(issuer);
   const url = `${normalized}/.well-known/oauth-authorization-server`;
-  const res = await fetch(url);
+  const res = await fetchFn(url);
   if (!res.ok) {
-    throw new Error(`Could not reach the authorization server (${res.status}). Check --issuer.`);
+    throw new DiscoveryAnswered(res.status);
   }
   const body = await res.json();
   const authorizationEndpoint = body.authorization_endpoint;
@@ -35,13 +435,15 @@ async function discoverEndpoints(issuer) {
   const tokenEndpoint = body.token_endpoint;
   const revocationEndpoint = body.revocation_endpoint;
   if (typeof tokenEndpoint !== "string" || tokenEndpoint === "") {
-    throw new Error("This authorization server is missing a token endpoint.");
+    throw new DiscoveryUnusable("This authorization server is missing a token endpoint.");
   }
   const hasAuthorization = typeof authorizationEndpoint === "string" && authorizationEndpoint !== "";
   const hasDevice = typeof deviceAuthorizationEndpoint === "string" && deviceAuthorizationEndpoint !== "";
   const hasRevocation = typeof revocationEndpoint === "string" && revocationEndpoint !== "";
   if (!hasAuthorization && !hasDevice) {
-    throw new Error("This authorization server does not support browser or device sign-in.");
+    throw new DiscoveryUnusable(
+      "This authorization server does not support browser or device sign-in."
+    );
   }
   return {
     issuer: typeof body.issuer === "string" ? body.issuer : normalized,
@@ -66,8 +468,9 @@ async function saveAuthMetadata(meta) {
     throw new Error("The authorization server returned an unusable client id.");
   }
   const expiresAt = typeof meta.expiresAt === "number" && Number.isFinite(meta.expiresAt) ? meta.expiresAt : null;
+  const savedToStore = typeof meta.savedToStore === "boolean" ? meta.savedToStore : void 0;
   await ensureConfigDir();
-  const checked = { issuer, clientId, expiresAt };
+  const checked = { issuer, clientId, expiresAt, savedToStore };
   await writeFile(CONFIG_FILE, `${JSON.stringify(checked, null, 2)}
 `, "utf8");
 }
@@ -78,15 +481,1222 @@ async function loadAuthMetadata() {
     if (typeof parsed.issuer !== "string" || typeof parsed.clientId !== "string") {
       return null;
     }
-    return parsed;
+    const { savedToStore, ...rest } = parsed;
+    return typeof savedToStore === "boolean" ? { ...rest, savedToStore } : rest;
   } catch {
     return null;
   }
 }
-async function clearAuthMetadata() {
-  try {
-    await unlink(CONFIG_FILE);
-  } catch {
+async function clearAuthMetadata() {
+  try {
+    await unlink(CONFIG_FILE);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+function getConfigDir() {
+  return paths.config;
+}
+
+// src/lib/send.ts
+var DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;
+var DEFAULT_ATTEMPTS = 5;
+var BLOCK_BYTES = 256 * 1024;
+var RESUMABLE_START = "x-goog-resumable";
+function connectionDroppedLine(arrived, total) {
+  const percent = total > 0 ? Math.floor(arrived / total * 100) : 0;
+  return `Connection dropped at ${percent}% \u2014 picking up where it stopped.`;
+}
+function pieceEnd(start, total, chunkBytes) {
+  const proposed = Math.min(start + chunkBytes, total);
+  if (proposed >= total) return total;
+  const aligned = Math.floor(proposed / BLOCK_BYTES) * BLOCK_BYTES;
+  return aligned > start ? aligned : proposed;
+}
+function rangeReached(res) {
+  const range = res.headers.get("range");
+  if (range === null || range === "") return 0;
+  const match = /bytes=0-(\d+)/i.exec(range);
+  if (match?.[1] === void 0) return null;
+  return Number(match[1]) + 1;
+}
+async function openSession(uploadUrl, contentType, fetchFn) {
+  let res;
+  try {
+    res = await fetchFn(uploadUrl, {
+      method: "POST",
+      headers: { [RESUMABLE_START]: "start", "content-type": contentType },
+      // Never followed. The store answers this exchange with a 3xx-shaped status of its own that
+      // is not a redirect, and following it would send the session somewhere nobody signed.
+      redirect: "manual"
+    });
+  } catch {
+    return { started: null, reached: false };
+  }
+  if (res.status !== 200 && res.status !== 201) return { started: null, reached: true };
+  const location = res.headers.get("location");
+  return location === null || location === "" ? { started: null, reached: true } : { started: location };
+}
+async function askWhatArrived(session, total, fetchFn) {
+  let res;
+  try {
+    res = await fetchFn(session, {
+      method: "PUT",
+      headers: { "content-range": `bytes */${total}` },
+      redirect: "manual"
+    });
+  } catch {
+    return null;
+  }
+  if (res.status === 200 || res.status === 201) return total;
+  if (res.status !== 308) return null;
+  return rangeReached(res);
+}
+async function sendFile(input) {
+  const fetchFn = input.fetchFn ?? fetch;
+  const chunkBytes = input.chunkBytes ?? DEFAULT_CHUNK_BYTES;
+  let attemptsLeft = input.attempts ?? DEFAULT_ATTEMPTS;
+  const session = await openSession(input.uploadUrl, input.contentType, fetchFn);
+  if (session.started === null) {
+    return { status: "not-started", reached: session.reached };
+  }
+  let arrived = 0;
+  while (arrived < input.byteSize) {
+    const end = pieceEnd(arrived, input.byteSize, chunkBytes);
+    const piece = await input.read(arrived, end - arrived);
+    let res;
+    try {
+      res = await fetchFn(session.started, {
+        method: "PUT",
+        headers: {
+          "content-type": input.contentType,
+          "content-range": `bytes ${arrived}-${end - 1}/${input.byteSize}`
+        },
+        body: piece,
+        redirect: "manual"
+      });
+    } catch {
+      attemptsLeft -= 1;
+      if (attemptsLeft <= 0) return { status: "incomplete", arrived };
+      const confirmed = await askWhatArrived(session.started, input.byteSize, fetchFn);
+      if (confirmed === null) return { status: "incomplete", arrived };
+      if (confirmed >= input.byteSize) return { status: "sent", arrived: input.byteSize };
+      input.onNote?.(connectionDroppedLine(confirmed, input.byteSize));
+      arrived = confirmed;
+      continue;
+    }
+    if (res.status === 200 || res.status === 201)
+      return { status: "sent", arrived: input.byteSize };
+    if (res.status !== 308) return { status: "incomplete", arrived };
+    const reached = rangeReached(res);
+    if (reached === null || reached <= arrived) return { status: "incomplete", arrived };
+    arrived = reached;
+  }
+  return { status: "sent", arrived };
+}
+
+// src/lib/token-store.ts
+import { Entry } from "@napi-rs/keyring";
+var SERVICE = "dazzer-oauth-cli";
+var ACCESS_ACCOUNT = "access-token";
+var REFRESH_ACCOUNT = "refresh-token";
+var KeychainTokenStore = class {
+  constructor(openEntry = (account) => new Entry(SERVICE, account)) {
+    this.openEntry = openEntry;
+  }
+  openEntry;
+  async save(tokens) {
+    this.openEntry(ACCESS_ACCOUNT).setPassword(tokens.accessToken);
+    this.openEntry(REFRESH_ACCOUNT).setPassword(tokens.refreshToken);
+  }
+  async load() {
+    const accessToken = this.openEntry(ACCESS_ACCOUNT).getPassword();
+    const refreshToken = this.openEntry(REFRESH_ACCOUNT).getPassword();
+    if (!accessToken || !refreshToken) {
+      return null;
+    }
+    return { accessToken, refreshToken };
+  }
+  async loadRefreshToken() {
+    return this.openEntry(REFRESH_ACCOUNT).getPassword() || null;
+  }
+  /**
+   * NOTHING SAVED IS NOT AN ERROR, AND A FAILED REMOVAL IS NEVER HIDDEN. A delete of nothing answers
+   * `false` rather than throwing, so there is no missing-entry error to swallow. What the keychain
+   * library does throw is a removal the store refused. Swallowing that told a person they were signed
+   * out while their sign-in was still saved on the machine.
+   *
+   * THE LONG-LIVED HALF GOES FIRST, AND IF IT WILL NOT, NOTHING ELSE IS TOUCHED. Both then stay, so a
+   * second sign-out still finds a whole sign-in to cancel. Removing the access token anyway would leave
+   * only the refresh token — which can still renew a sign-in for weeks. Once the refresh token is gone,
+   * an access token left behind by a failed second removal expires within the hour.
+   */
+  async clear() {
+    this.openEntry(REFRESH_ACCOUNT).deletePassword();
+    this.openEntry(ACCESS_ACCOUNT).deletePassword();
+  }
+};
+function createTokenStore() {
+  return new KeychainTokenStore();
+}
+
+// src/lib/walk.ts
+import { readdir, realpath, stat } from "node:fs/promises";
+import { join as join2, sep } from "node:path";
+function inside(base, candidate) {
+  return candidate === base || candidate.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
+}
+async function walkFolder(root) {
+  const base = await realpath(root);
+  if (!(await stat(base)).isDirectory()) {
+    throw new Error("walkFolder was given something that is not a folder");
+  }
+  const files = [];
+  const skipped = [];
+  const handedOver = /* @__PURE__ */ new Set();
+  const walked = /* @__PURE__ */ new Set([base]);
+  async function descend(dir, prefix, isRoot = false) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (isRoot) throw err;
+      skipped.push({ path: dir, relative: prefix.replace(/\/$/, ""), reason: "unreadable" });
+      return;
+    }
+    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 relative = `${prefix}${entry.name}`;
+      if (entry.isSymbolicLink()) {
+        await followShortcut(full, relative);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await enter(full, relative);
+        continue;
+      }
+      if (entry.isFile()) take(full, relative);
+    }
+  }
+  async function enter(full, relative) {
+    let real;
+    try {
+      real = await realpath(full);
+    } catch {
+      skipped.push({ path: full, relative, reason: "unreadable" });
+      return;
+    }
+    if (walked.has(real)) return;
+    walked.add(real);
+    await descend(real, `${relative}/`);
+  }
+  function take(full, relative, real) {
+    const identity = real ?? full;
+    if (handedOver.has(identity)) return;
+    handedOver.add(identity);
+    files.push({ path: full, relative });
+  }
+  async function followShortcut(full, relative) {
+    let real;
+    try {
+      real = await realpath(full);
+    } catch {
+      skipped.push({ path: full, relative, reason: "unreadable" });
+      return;
+    }
+    if (!inside(base, real)) {
+      skipped.push({ path: full, relative, reason: "leads-out" });
+      return;
+    }
+    let kind;
+    try {
+      kind = await stat(real);
+    } catch {
+      skipped.push({ path: full, relative, reason: "unreadable" });
+      return;
+    }
+    if (kind.isDirectory()) {
+      if (walked.has(real)) return;
+      walked.add(real);
+      await descend(real, `${relative}/`);
+      return;
+    }
+    if (kind.isFile()) take(real, relative, real);
+  }
+  await descend(base, "", true);
+  files.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
+  skipped.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
+  return { files, skipped };
+}
+
+// src/commands/add.ts
+var SPACE_PATH = "/documents/v1/space";
+var LANDING_PATH = "/documents/v1/landing";
+var LANDED_PATH = "/documents/v1/landed";
+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.`;
+var collectedQuestion = (names, space) => `${names.length} of those look like newer versions of documents already in ${space} \u2014 ${listed(names)}. Treat all ${inWords(names.length)} as newer versions, keep all ${inWords(names.length)} as separate documents, or go through them one at a time?`;
+function listed(names) {
+  if (names.length <= 1) return names[0] ?? "";
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+var NUMBER_WORDS = [
+  "",
+  "one",
+  "two",
+  "three",
+  "four",
+  "five",
+  "six",
+  "seven",
+  "eight",
+  "nine",
+  "ten"
+];
+var inWords = (many) => NUMBER_WORDS[many] ?? String(many);
+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 = [
+    '--space "<name>"',
+    ...numbered ? ["--space <number>"] : [],
+    ...keepToYourself ? ["--keep-to-myself"] : []
+  ];
+  const last = ways[ways.length - 1] ?? "";
+  const said = ways.length === 1 ? last : `${ways.slice(0, -1).join(", ")}, or ${last}`;
+  return `Run this again with ${said}.`;
+};
+var DECLARED_BY_EXTENSION = {
+  ".csv": "text/csv",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".gif": "image/gif",
+  ".htm": "text/html",
+  ".html": "text/html",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".markdown": "text/markdown",
+  ".md": "text/markdown",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".rtf": "application/rtf",
+  ".text": "text/plain",
+  ".txt": "text/plain",
+  ".webp": "image/webp"
+};
+var UNDECLARED = "application/octet-stream";
+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;
+  const data = body.data;
+  return typeof data === "object" && data !== null ? data : null;
+}
+function readChoices(data) {
+  return readOfferedPlaces(data.choices);
+}
+function readLanding(body) {
+  const data = readEnvelope(body);
+  if (data === null) return null;
+  const { ticket, upload_url: uploadUrl, content_type: contentType, space_name: space } = data;
+  if (typeof ticket !== "string" || ticket === "") return null;
+  if (typeof uploadUrl !== "string" || uploadUrl === "") return null;
+  if (typeof contentType !== "string" || contentType === "") return null;
+  return {
+    ticket,
+    upload_url: uploadUrl,
+    content_type: contentType,
+    space_name: typeof space === "string" && space.trim() !== "" ? space : null
+  };
+}
+function named(space) {
+  return space === null ? "that space" : space;
+}
+async function resolveAuth(options) {
+  const tokenStore = createTokenStore();
+  const meta = await loadAuthMetadata();
+  const issuer = meta?.issuer ?? options.issuer;
+  try {
+    const discovery = await discoverEndpoints(issuer);
+    return {
+      discovery,
+      clientId: meta?.clientId ?? options.clientId,
+      tokenStore,
+      resource: options.resource
+    };
+  } catch {
+    return null;
+  }
+}
+var FIRST_WAIT_MS = 1e3;
+var LONGEST_WAIT_MS = 3e4;
+var PACED_ATTEMPTS = 6;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function voiceFor(write) {
+  let said = false;
+  return {
+    write,
+    slowingDown: () => {
+      if (said) return;
+      said = true;
+      write(SLOWING_DOWN);
+    }
+  };
+}
+async function callPaced(request, deps, voice) {
+  const wait = deps.delay ?? sleep;
+  let waiting = FIRST_WAIT_MS;
+  for (let attempt = 1; ; attempt += 1) {
+    const answer = await callDazzer(request);
+    if (answer.status !== "refused" || answer.httpStatus !== 429) return answer;
+    if (attempt >= PACED_ATTEMPTS) return answer;
+    voice.slowingDown();
+    await wait(waiting);
+    waiting = Math.min(waiting * 2, LONGEST_WAIT_MS);
+  }
+}
+function askedWith(options) {
+  if (options.keepToMyself === true) return { keep_to_myself: true };
+  const answer = options.space?.trim();
+  if (answer === void 0 || answer === "") return {};
+  return { space: /^\d+$/.test(answer) ? Number(answer) : answer };
+}
+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),
+      auth: auth2,
+      fetchFn: deps.fetchFn
+    },
+    deps,
+    voice
+  );
+  if (answer.status !== "ok") {
+    say(voice.write, answer, name2);
+    return null;
+  }
+  const data = readEnvelope(answer.body);
+  if (data === null) {
+    voice.write(wentWrong(name2));
+    return null;
+  }
+  const space = typeof data.space === "string" && data.space.trim() !== "" ? data.space : null;
+  if (data.settled === true) {
+    return { scopeId: typeof data.scope_id === "number" ? data.scope_id : null, space };
+  }
+  const question = typeof data.question === "string" && data.question !== "" ? data.question : null;
+  if (question === null) {
+    voice.write(wentWrong(name2));
+    return null;
+  }
+  voice.write(question);
+  const choices = readChoices(data);
+  for (const choice of choices) voice.write(choiceLine(choice.space, choice.scopeId));
+  voice.write(answerWith(data.keep_to_yourself === true, choices.length > 0));
+  return null;
+}
+var HELD_FOR_AN_ANSWER = "same_name_different_contents";
+function fromAnswer(answer) {
+  if (answer.status === "refused") {
+    if (answer.code === HELD_FOR_AN_ANSWER && answer.detail !== void 0) {
+      return { kind: "held", question: answer.detail };
+    }
+    return {
+      kind: "refused",
+      ...answer.detail === void 0 ? {} : { said: answer.detail },
+      ...answer.code === void 0 ? {} : { code: answer.code },
+      // 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 }
+    };
+  }
+  return { kind: "stop", answer };
+}
+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: {
+        file_name: basename(input.path),
+        byte_size: input.byteSize,
+        mime_type: DECLARED_BY_EXTENSION[extname(input.path).toLowerCase()] ?? UNDECLARED,
+        ...input.scopeId === null ? {} : { scope_id: input.scopeId }
+      },
+      auth: input.auth,
+      fetchFn: deps.fetchFn
+    },
+    deps,
+    voice
+  );
+  if (described.status !== "ok") return fromAnswer(described);
+  const landing = readLanding(described.body);
+  if (landing === null) return { kind: "went-wrong" };
+  let couldNotRead = false;
+  let sent;
+  try {
+    sent = await sendFile({
+      uploadUrl: landing.upload_url,
+      contentType: landing.content_type,
+      byteSize: input.byteSize,
+      read: async (start, length) => {
+        try {
+          const buffer = Buffer.allocUnsafe(length);
+          let filled = 0;
+          while (filled < length) {
+            const { bytesRead } = await handle.read(
+              buffer,
+              filled,
+              length - filled,
+              start + filled
+            );
+            if (bytesRead === 0) break;
+            filled += bytesRead;
+          }
+          return filled === length ? buffer : buffer.subarray(0, filled);
+        } catch (err) {
+          couldNotRead = true;
+          throw err;
+        }
+      },
+      fetchFn: deps.uploadFetchFn,
+      chunkBytes: deps.chunkBytes,
+      attempts: deps.attempts,
+      onNote: voice.write
+    });
+  } catch (err) {
+    if (couldNotRead) return { kind: "cannot-read" };
+    throw err;
+  }
+  if (sent.status !== "sent") {
+    return sent.status === "not-started" && !sent.reached ? { kind: "not-reached" } : { kind: "did-not-finish" };
+  }
+  const landed = await callPaced(
+    {
+      baseUrl: options.baseUrl,
+      client: options.client,
+      path: LANDED_PATH,
+      method: "POST",
+      body: { ticket: landing.ticket, ...input.described },
+      auth: input.auth,
+      fetchFn: deps.fetchFn
+    },
+    deps,
+    voice
+  );
+  if (landed.status !== "ok") return fromAnswer(landed);
+  const stored = readEnvelope(landed.body);
+  if (stored === null) return { kind: "went-wrong" };
+  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,
+    ...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) {
+  try {
+    return await sendOne(input);
+  } catch {
+    return { kind: "went-wrong" };
+  }
+}
+async function openOne(path) {
+  try {
+    return await open(path, "r");
+  } catch (err) {
+    return err?.code === "ENOENT" ? "missing" : "cannot-open";
+  }
+}
+var REASON_ORDER = [
+  "type-not-readable",
+  "too-large",
+  "already-here",
+  "refused",
+  "cannot-open",
+  "did-not-finish",
+  "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"
+};
+var COUNTED = {
+  "type-not-readable": (many) => `${many} file type${many === 1 ? "" : "s"} I can't read`,
+  "too-large": (many) => `${many} too large`,
+  "already-here": (many) => `${many} already there`,
+  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`,
+  "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",
+  "too-large": "too large",
+  "already-here": "already there",
+  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",
+  "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, 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(", ");
+  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}`;
+}
+var FROM_THE_WALK = {
+  "leads-out": "leads-out",
+  unreadable: "cannot-open"
+};
+async function runAdd(options, deps = {}) {
+  const voice = voiceFor(deps.write ?? ((line) => process.stdout.write(`${line}
+`)));
+  const name2 = asPrinted(basename(options.file));
+  let isFolder;
+  try {
+    isFolder = (await statPath(options.file)).isDirectory();
+  } catch (err) {
+    voice.write(
+      err?.code === "ENOENT" ? cannotFind(name2) : cannotOpen(name2)
+    );
+    return { ok: false };
+  }
+  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, descriptions) {
+  const name2 = asPrinted(basename(options.file));
+  const handle = await openOne(options.file);
+  if (typeof handle === "string") {
+    voice.write(handle === "missing" ? cannotFind(name2) : cannotOpen(name2));
+    return { ok: false };
+  }
+  try {
+    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, 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
+    });
+    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();
+  }
+}
+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);
+    } catch {
+      return null;
+    }
+  })();
+  if (walked === null) {
+    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);
+  if (auth2 === null) {
+    voice.write(CANNOT_REACH_DAZZER);
+    return { ok: false };
+  }
+  const settled = await settleSpace(options, auth2, deps, voice, name2);
+  if (settled === null) return { ok: false };
+  const skipped = walked.skipped.map((skip) => ({
+    relative: skip.relative,
+    reason: FROM_THE_WALK[skip.reason]
+  }));
+  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" });
+      continue;
+    }
+    let outcome;
+    try {
+      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: Number(info.size),
+        scopeId: settled.scopeId,
+        ...described === void 0 ? {} : { described },
+        options,
+        deps,
+        auth: auth2,
+        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") {
+      skipped.push({ relative: file.relative, reason: "already-here" });
+      continue;
+    }
+    if (outcome.kind === "held") {
+      held.push({
+        relative: file.relative,
+        name: basename(file.path),
+        question: outcome.question
+      });
+      continue;
+    }
+    if (outcome.kind === "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 },
+        // 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;
+    }
+    if (outcome.kind === "cannot-read") {
+      skipped.push({ relative: file.relative, reason: "cannot-open" });
+      continue;
+    }
+    if (outcome.kind === "did-not-finish" || outcome.kind === "went-wrong") {
+      skipped.push({ relative: file.relative, reason: "did-not-finish" });
+      continue;
+    }
+    if (outcome.kind === "not-reached") voice.write(CANNOT_REACH_DAZZER);
+    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);
+  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));
+  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);
+  } else if (held.length > 1) {
+    voice.write(
+      collectedQuestion(
+        held.map((one) => asPrinted(one.name)),
+        named(settled.space)
+      )
+    );
+  }
+  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;
+  if (places.length === 0 && !keepToYourself) return;
+  for (const place of places) write(choiceLine(place.space, place.scopeId));
+  write(answerWith(keepToYourself, places.length > 0));
+}
+function say(write, answer, name2) {
+  switch (answer.status) {
+    case "refused":
+      write(answer.detail ?? wentWrong(name2));
+      offerThePlaces(write, answer);
+      return;
+    case "sign-in-invalid":
+    case "unreachable":
+      write(answer.message);
+      return;
+    case "signed-out":
+      printAuthStatus({ state: "signed-out" });
+      return;
+    case "store-unreadable":
+      printAuthStatus({ state: "store-unreadable" });
+      return;
+    case "ok":
+      return;
   }
 }
 
@@ -134,12 +1744,12 @@ async function requestDeviceCode(options) {
 }
 async function pollForTokens(options) {
   const fetchFn = options.fetchFn ?? fetch;
-  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep2 = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const baseIntervalMs = (options.deviceAuth.interval ?? 5) * 1e3;
   let intervalMs = options.pollIntervalMs ?? baseIntervalMs;
   const deadline = Date.now() + (options.maxWaitMs ?? options.deviceAuth.expires_in * 1e3);
   while (Date.now() < deadline) {
-    await sleep(intervalMs);
+    await sleep2(intervalMs);
     const params = new URLSearchParams({
       grant_type: "urn:ietf:params:oauth:grant-type:device_code",
       device_code: options.deviceCode,
@@ -329,279 +1939,111 @@ function buildAuthorizeUrl(endpoint, params) {
 }
 function statusPage(title, heading, body, mark) {
   return renderDocument({
-    title,
-    centered: true,
-    body: pageShell(`${mark}<h1>${heading}</h1><p>${body}</p>
-<div class="foot">Dazzer secure sign-in</div>`)
-  });
-}
-function successPage() {
-  return statusPage(
-    "Signed in to Dazzer",
-    "You're signed in",
-    "You can close this tab and return to your terminal.",
-    successMark
-  );
-}
-function errorPage(reason) {
-  return statusPage(
-    "Sign-in failed",
-    "Something went wrong",
-    `We couldn't complete sign-in (${escapeHtml(reason)}). Close this tab and run the command again.`,
-    errorMark
-  );
-}
-function sendHtml(res, html) {
-  res.statusCode = 200;
-  res.setHeader("Content-Type", "text/html; charset=utf-8");
-  res.end(html);
-}
-async function runLoopbackFlow(options) {
-  const fetchFn = options.fetchFn ?? fetch;
-  const { authorizationEndpoint } = options.discovery;
-  if (!authorizationEndpoint) {
-    throw new Error("This authorization server does not support browser sign-in.");
-  }
-  const { verifier, challenge } = createPkce();
-  const state = base64url(randomBytes(16));
-  const scope = options.scope ?? DEFAULT_SCOPE2;
-  const { code, redirectUri } = await new Promise(
-    (resolve, reject) => {
-      let timer;
-      const server = createServer((req, res2) => {
-        const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
-        if (requestUrl.pathname !== CALLBACK_PATH) {
-          res2.statusCode = 404;
-          res2.end("Not found");
-          return;
-        }
-        const addr = server.address();
-        const redirect = `http://127.0.0.1:${addr.port}${CALLBACK_PATH}`;
-        const returnedState = requestUrl.searchParams.get("state");
-        const errorParam = requestUrl.searchParams.get("error");
-        const returnedCode = requestUrl.searchParams.get("code");
-        const finish = (err) => {
-          if (timer) clearTimeout(timer);
-          server.close();
-          if (err) reject(err);
-        };
-        if (errorParam) {
-          sendHtml(res2, errorPage(errorParam));
-          finish(new Error(`Sign-in failed: ${errorParam}.`));
-          return;
-        }
-        if (returnedState !== state) {
-          sendHtml(res2, errorPage("state_mismatch"));
-          finish(new Error("Sign-in failed: state mismatch."));
-          return;
-        }
-        if (!returnedCode) {
-          sendHtml(res2, errorPage("missing_code"));
-          finish(new Error("Sign-in failed: no authorization code returned."));
-          return;
-        }
-        sendHtml(res2, successPage());
-        finish();
-        resolve({ code: returnedCode, redirectUri: redirect });
-      });
-      server.on("error", (err) => {
-        if (timer) clearTimeout(timer);
-        reject(err);
-      });
-      server.listen(0, "127.0.0.1", () => {
-        const addr = server.address();
-        const redirect = `http://127.0.0.1:${addr.port}${CALLBACK_PATH}`;
-        const authorizeUrl = buildAuthorizeUrl(authorizationEndpoint, {
-          clientId: options.clientId,
-          redirectUri: redirect,
-          scope,
-          state,
-          challenge,
-          resource: options.resource
-        });
-        timer = setTimeout(() => {
-          server.close();
-          reject(new Error("Timed out waiting for sign-in. Run the command again."));
-        }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-        (options.openBrowser ?? launchBrowser)(authorizeUrl);
-        options.onPrompt?.(authorizeUrl);
-      });
-    }
-  );
-  const params = new URLSearchParams({
-    grant_type: "authorization_code",
-    code,
-    redirect_uri: redirectUri,
-    client_id: options.clientId,
-    code_verifier: verifier
-  });
-  if (options.resource) {
-    params.set("resource", options.resource);
-  }
-  const res = await fetchFn(options.discovery.tokenEndpoint, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: params.toString()
-  });
-  const body = await res.json();
-  if (!res.ok) {
-    const error = typeof body.error === "string" ? body.error : "token_exchange_failed";
-    throw new Error(`Token request failed: ${error}`);
-  }
-  const accessToken = body.access_token;
-  if (typeof accessToken !== "string") {
-    throw new Error("The authorization server returned an unexpected token response.");
-  }
-  return {
-    access_token: accessToken,
-    refresh_token: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
-    expires_in: typeof body.expires_in === "number" ? body.expires_in : void 0,
-    token_type: typeof body.token_type === "string" ? body.token_type : void 0
-  };
-}
-function browserLikelyAvailable() {
-  if (process.platform === "darwin" || process.platform === "win32") {
-    return true;
-  }
-  return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
-}
-
-// src/lib/output.ts
-function writeOut(message) {
-  process.stdout.write(`${message}
-`);
-}
-function writeErr(message) {
-  process.stderr.write(`${message}
-`);
-}
-function printDeviceInstructions(deviceAuth) {
-  writeOut("");
-  if (deviceAuth.verification_uri_complete) {
-    writeOut("To finish signing in, open this link in your browser:");
-    writeOut(`  ${deviceAuth.verification_uri_complete}`);
-  } else {
-    writeOut("To finish signing in, open this page in your browser:");
-    writeOut(`  ${deviceAuth.verification_uri}`);
-    writeOut("");
-    writeOut("Then enter this code:");
-    writeOut(`  ${deviceAuth.user_code}`);
-  }
-  writeOut("");
-  writeOut("Waiting for you to approve in the browser...");
-}
-function printBrowserOpening(url) {
-  writeOut("");
-  writeOut("Opening your browser to sign in\u2026");
-  writeOut("If it doesn't open automatically, paste this into your browser:");
-  writeOut(`  ${url}`);
-  writeOut("");
-}
-function printLoginSuccess(keychainOk) {
-  writeOut("");
-  writeOut("Signed in successfully.");
-  if (!keychainOk) {
-    writeErr("Warning: could not save tokens to the OS keychain. Use the config below.");
-  }
-}
-function printConnectGuidance(mcpServerUrl, accessToken) {
-  const url = mcpServerUrl.replace(/\/$/, "");
-  writeOut("");
-  writeOut("Connect an AI client to Dazzer.");
-  writeOut("");
-  writeOut("Recommended \u2014 add this server by URL and sign in from your client;");
-  writeOut("it stays connected and renews itself:");
-  writeOut("");
-  writeOut("{");
-  writeOut('  "mcpServers": {');
-  writeOut('    "dazzer": {');
-  writeOut(`      "url": "${url}"`);
-  writeOut("    }");
-  writeOut("  }");
-  writeOut("}");
-  writeOut("");
-  writeOut("Fallback \u2014 only if your client cannot sign in and needs a pasted token.");
-  writeOut("This token expires in about an hour; re-run `dazzer auth login` to renew:");
-  writeOut("");
-  writeOut("{");
-  writeOut('  "mcpServers": {');
-  writeOut('    "dazzer": {');
-  writeOut(`      "url": "${url}",`);
-  writeOut('      "headers": {');
-  writeOut(`        "Authorization": "Bearer ${accessToken}"`);
-  writeOut("      }");
-  writeOut("    }");
-  writeOut("  }");
-  writeOut("}");
-  writeOut("");
-}
-function printAuthStatus(params) {
-  switch (params.state) {
-    case "signed-out":
-      writeOut("Not signed in. Run: dazzer auth login");
-      return;
-    case "store-unreadable":
-      writeOut("Cannot tell \u2014 this machine's credential store could not be opened.");
-      writeOut("  Common on servers and containers, which often have none.");
-      writeOut("  Run: dazzer auth login \u2014 it prints a pass you can paste in.");
-      return;
-    case "expired":
-      writeOut("Your sign-in has expired or been revoked. Run: dazzer auth login");
-      return;
-    case "unverified":
-      writeOut(
-        "Signed in on this device, but the sign-in server could not be reached to confirm it."
-      );
-      if (params.issuer) {
-        writeOut(`  Signed in at: ${params.issuer}`);
-      }
-      if (params.lastKnownExpiresAt) {
-        writeOut(`  Last confirmed expiry: ${new Date(params.lastKnownExpiresAt).toISOString()}`);
-      }
-      writeOut("  Check your connection, then run this again to confirm.");
-      return;
-    case "signed-in":
-      writeOut("Signed in \u2014 confirmed just now.");
-      if (params.issuer) {
-        writeOut(`  Signed in at: ${params.issuer}`);
-      }
-      if (params.expiresAt) {
-        writeOut(
-          `  This token expires ${new Date(params.expiresAt).toISOString()} and refreshes automatically.`
-        );
-      }
-      return;
-  }
+    title,
+    centered: true,
+    body: pageShell(`${mark}<h1>${heading}</h1><p>${body}</p>
+<div class="foot">Dazzer secure sign-in</div>`)
+  });
 }
-function printLogoutSuccess(serverRevoked) {
-  if (serverRevoked) {
-    writeOut("Signed out.");
-    return;
-  }
-  writeOut(
-    "Signed out on this device. We could not reach the server to revoke your tokens, so they will expire on their own."
+function successPage() {
+  return statusPage(
+    "Signed in to Dazzer",
+    "You're signed in",
+    "You can close this tab and return to your terminal.",
+    successMark
   );
 }
-function fail(message) {
-  writeErr(`Error: ${message}`);
-  process.exit(1);
+function errorPage(reason) {
+  return statusPage(
+    "Sign-in failed",
+    "Something went wrong",
+    `We couldn't complete sign-in (${escapeHtml(reason)}). Close this tab and run the command again.`,
+    errorMark
+  );
 }
-
-// src/lib/refresh.ts
-var RefreshRejectedError = class extends Error {
-  constructor(oauthError) {
-    super(`Could not refresh token: ${oauthError}`);
-    this.oauthError = oauthError;
-    this.name = "RefreshRejectedError";
-  }
-  oauthError;
-};
-async function refreshAccessToken(options) {
+function sendHtml(res, html) {
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "text/html; charset=utf-8");
+  res.end(html);
+}
+async function runLoopbackFlow(options) {
   const fetchFn = options.fetchFn ?? fetch;
+  const { authorizationEndpoint } = options.discovery;
+  if (!authorizationEndpoint) {
+    throw new Error("This authorization server does not support browser sign-in.");
+  }
+  const { verifier, challenge } = createPkce();
+  const state = base64url(randomBytes(16));
+  const scope = options.scope ?? DEFAULT_SCOPE2;
+  const { code, redirectUri } = await new Promise(
+    (resolve, reject) => {
+      let timer;
+      const server = createServer((req, res2) => {
+        const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (requestUrl.pathname !== CALLBACK_PATH) {
+          res2.statusCode = 404;
+          res2.end("Not found");
+          return;
+        }
+        const addr = server.address();
+        const redirect = `http://127.0.0.1:${addr.port}${CALLBACK_PATH}`;
+        const returnedState = requestUrl.searchParams.get("state");
+        const errorParam = requestUrl.searchParams.get("error");
+        const returnedCode = requestUrl.searchParams.get("code");
+        const finish = (err) => {
+          if (timer) clearTimeout(timer);
+          server.close();
+          if (err) reject(err);
+        };
+        if (errorParam) {
+          sendHtml(res2, errorPage(errorParam));
+          finish(new Error(`Sign-in failed: ${errorParam}.`));
+          return;
+        }
+        if (returnedState !== state) {
+          sendHtml(res2, errorPage("state_mismatch"));
+          finish(new Error("Sign-in failed: state mismatch."));
+          return;
+        }
+        if (!returnedCode) {
+          sendHtml(res2, errorPage("missing_code"));
+          finish(new Error("Sign-in failed: no authorization code returned."));
+          return;
+        }
+        sendHtml(res2, successPage());
+        finish();
+        resolve({ code: returnedCode, redirectUri: redirect });
+      });
+      server.on("error", (err) => {
+        if (timer) clearTimeout(timer);
+        reject(err);
+      });
+      server.listen(0, "127.0.0.1", () => {
+        const addr = server.address();
+        const redirect = `http://127.0.0.1:${addr.port}${CALLBACK_PATH}`;
+        const authorizeUrl = buildAuthorizeUrl(authorizationEndpoint, {
+          clientId: options.clientId,
+          redirectUri: redirect,
+          scope,
+          state,
+          challenge,
+          resource: options.resource
+        });
+        timer = setTimeout(() => {
+          server.close();
+          reject(new Error("Timed out waiting for sign-in. Run the command again."));
+        }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        (options.openBrowser ?? launchBrowser)(authorizeUrl);
+        options.onPrompt?.(authorizeUrl);
+      });
+    }
+  );
   const params = new URLSearchParams({
-    grant_type: "refresh_token",
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
     client_id: options.clientId,
-    refresh_token: options.refreshToken
+    code_verifier: verifier
   });
   if (options.resource) {
     params.set("resource", options.resource);
@@ -613,83 +2055,25 @@ async function refreshAccessToken(options) {
   });
   const body = await res.json();
   if (!res.ok) {
-    const error = typeof body.error === "string" ? body.error : "refresh_failed";
-    throw new RefreshRejectedError(error);
+    const error = typeof body.error === "string" ? body.error : "token_exchange_failed";
+    throw new Error(`Token request failed: ${error}`);
   }
   const accessToken = body.access_token;
-  const refreshToken = body.refresh_token;
   if (typeof accessToken !== "string") {
-    throw new Error("The authorization server returned an unexpected refresh response.");
-  }
-  const newRefresh = typeof refreshToken === "string" ? refreshToken : options.refreshToken;
-  const expiresIn = typeof body.expires_in === "number" ? body.expires_in : null;
-  await options.tokenStore.save({ accessToken, refreshToken: newRefresh });
-  return { accessToken, refreshToken: newRefresh, expiresIn };
-}
-async function getValidAccessToken(options) {
-  const stored = await options.tokenStore.load();
-  if (!stored) {
-    return { status: "signed-out" };
-  }
-  try {
-    const refreshed = await refreshAccessToken({ ...options, refreshToken: stored.refreshToken });
-    return { status: "refreshed", expiresIn: refreshed.expiresIn };
-  } catch (err) {
-    if (err instanceof RefreshRejectedError) {
-      return { status: "rejected" };
-    }
-    return { status: "unreachable" };
-  }
-}
-async function persistLoginTokens(tokenStore, tokens) {
-  if (!tokens.refresh_token) {
-    throw new Error("The authorization server did not return a refresh token.");
+    throw new Error("The authorization server returned an unexpected token response.");
   }
-  const stored = {
-    accessToken: tokens.access_token,
-    refreshToken: tokens.refresh_token
+  return {
+    access_token: accessToken,
+    refresh_token: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
+    expires_in: typeof body.expires_in === "number" ? body.expires_in : void 0,
+    token_type: typeof body.token_type === "string" ? body.token_type : void 0
   };
-  await tokenStore.save(stored);
-  return stored;
-}
-
-// src/lib/token-store.ts
-import { Entry } from "@napi-rs/keyring";
-var SERVICE = "dazzer-oauth-cli";
-var ACCESS_ACCOUNT = "access-token";
-var REFRESH_ACCOUNT = "refresh-token";
-function accessEntry() {
-  return new Entry(SERVICE, ACCESS_ACCOUNT);
-}
-function refreshEntry() {
-  return new Entry(SERVICE, REFRESH_ACCOUNT);
 }
-var KeychainTokenStore = class {
-  async save(tokens) {
-    accessEntry().setPassword(tokens.accessToken);
-    refreshEntry().setPassword(tokens.refreshToken);
-  }
-  async load() {
-    const accessToken = accessEntry().getPassword();
-    const refreshToken = refreshEntry().getPassword();
-    if (!accessToken || !refreshToken) {
-      return null;
-    }
-    return { accessToken, refreshToken };
-  }
-  async clear() {
-    try {
-      accessEntry().deletePassword();
-    } catch {
-    }
-    try {
-      refreshEntry().deletePassword();
-    } catch {
-    }
+function browserLikelyAvailable() {
+  if (process.platform === "darwin" || process.platform === "win32") {
+    return true;
   }
-};
-function createTokenStore() {
-  return new KeychainTokenStore();
+  return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
 }
 
 // src/commands/login.ts
@@ -738,16 +2122,37 @@ async function runLogin(options) {
     keychainOk = false;
   }
   const expiresAt = typeof tokens.expires_in === "number" ? Date.now() + tokens.expires_in * 1e3 : null;
-  await saveAuthMetadata({
-    issuer: discovery.issuer,
-    clientId: options.clientId,
-    expiresAt
-  });
+  const previous = await loadAuthMetadata();
+  const keepPrevious = !keychainOk && previous?.savedToStore === true;
+  await saveAuthMetadata(
+    keepPrevious ? previous : {
+      issuer: discovery.issuer,
+      clientId: options.clientId,
+      expiresAt,
+      savedToStore: keychainOk
+    }
+  );
   printLoginSuccess(keychainOk);
   printConnectGuidance(options.resource ?? discovery.issuer, tokens.access_token);
 }
 
 // src/lib/revoke.ts
+var RevocationRefused = class extends Error {
+  constructor(status) {
+    super(`Token revocation failed (${status}).`);
+    this.status = status;
+    this.name = "RevocationRefused";
+  }
+  status;
+};
+var RevocationRedirected = class extends Error {
+  constructor(status) {
+    super(`Token revocation was redirected (${status}).`);
+    this.status = status;
+    this.name = "RevocationRedirected";
+  }
+  status;
+};
 async function revokeToken(options) {
   const fetchFn = options.fetchFn ?? fetch;
   const params = new URLSearchParams({
@@ -758,47 +2163,142 @@ async function revokeToken(options) {
   const res = await fetchFn(options.revocationEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: params.toString()
+    body: params.toString(),
+    redirect: "manual"
   });
+  if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
+    throw new RevocationRedirected(res.status);
+  }
   if (!res.ok) {
-    throw new Error(`Token revocation failed (${res.status}).`);
+    throw new RevocationRefused(res.status);
   }
 }
 
 // src/commands/logout.ts
-async function runLogout(options = {}) {
+function mayWorkLater(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function afterFailure(error) {
+  if (error instanceof DiscoveryUnusable) return "refused";
+  if (error instanceof DiscoveryAnswered || error instanceof RevocationRefused) {
+    return mayWorkLater(error.status) ? "unanswered" : "refused";
+  }
+  return "unanswered";
+}
+function sameOrigin(address, issuer) {
+  try {
+    return new URL(address).origin === new URL(issuer).origin;
+  } catch {
+    return false;
+  }
+}
+async function cancelAtServer(refreshToken, server, fetchFn) {
+  try {
+    assertHttpsIssuer(server.issuer);
+  } catch {
+    return "refused";
+  }
+  try {
+    const { revocationEndpoint } = await discoverEndpoints(server.issuer, fetchFn);
+    if (!revocationEndpoint || !sameOrigin(revocationEndpoint, server.issuer)) return "refused";
+    await revokeToken({
+      revocationEndpoint,
+      clientId: server.clientId,
+      token: refreshToken,
+      tokenTypeHint: "refresh_token",
+      fetchFn
+    });
+    return "cancelled";
+  } catch (error) {
+    return afterFailure(error);
+  }
+}
+async function removeRecordAfterSignOut() {
+  try {
+    await clearAuthMetadata();
+  } catch {
+  }
+}
+function defaultServer(defaults) {
+  try {
+    return defaults();
+  } catch {
+    return null;
+  }
+}
+async function endWithStoreUnopened(meta, options) {
+  const platform = options.platform ?? process.platform;
+  const mayForget = (platform === "linux" || platform === "freebsd") && meta?.savedToStore !== true;
+  if (!options.forgetThisMachine) {
+    printLogoutStoreLocked(mayForget);
+    return { ok: false };
+  }
+  if (!mayForget) {
+    printForgetRefused();
+    return { ok: false };
+  }
+  try {
+    await clearAuthMetadata();
+  } catch {
+    printForgetFailed(getConfigDir());
+    return { ok: false };
+  }
+  printLogoutForgotten();
+  return { ok: true };
+}
+async function runLogout(options) {
   const tokenStore = options.tokenStore ?? createTokenStore();
   const meta = await loadAuthMetadata();
-  const tokens = await tokenStore.load().catch(() => null);
-  let serverRevoked = true;
-  if (meta && tokens) {
+  let refreshToken;
+  try {
+    refreshToken = await tokenStore.loadRefreshToken();
+  } catch {
+    return endWithStoreUnopened(meta, options);
+  }
+  if (refreshToken === null) {
+    let passRemoved = true;
     try {
-      const discovery = await discoverEndpoints(options.issuer ?? meta.issuer);
-      if (!discovery.revocationEndpoint) {
-        throw new Error("This authorization server does not support token revocation.");
-      }
-      const clientId = options.clientId ?? meta.clientId;
-      await revokeToken({
-        revocationEndpoint: discovery.revocationEndpoint,
-        clientId,
-        token: tokens.refreshToken,
-        tokenTypeHint: "refresh_token",
-        fetchFn: options.fetchFn
-      });
-      await revokeToken({
-        revocationEndpoint: discovery.revocationEndpoint,
-        clientId,
-        token: tokens.accessToken,
-        tokenTypeHint: "access_token",
-        fetchFn: options.fetchFn
-      });
+      await tokenStore.clear();
     } catch {
-      serverRevoked = false;
+      passRemoved = false;
+    }
+    await removeRecordAfterSignOut();
+    if (!passRemoved) {
+      printLogoutPassLeft();
+    } else if (meta?.savedToStore === false) {
+      printLogoutSuccess();
+    } else {
+      printLogoutNothingFound();
     }
+    return { ok: true };
+  }
+  if (options.forgetThisMachine) {
+    printForgetRefused();
+    return { ok: false };
+  }
+  const server = meta ?? defaultServer(options.defaults);
+  if (!server) {
+    printLogoutBadSettings();
+    return { ok: false };
+  }
+  const atServer = await cancelAtServer(refreshToken, server, options.fetchFn ?? fetch);
+  if (atServer === "unanswered") {
+    printLogoutNotCancelledYet();
+    return { ok: false };
+  }
+  try {
+    await tokenStore.clear();
+  } catch {
+    printLogoutIncomplete(atServer === "cancelled");
+    return { ok: false };
+  }
+  await removeRecordAfterSignOut();
+  if (atServer === "refused") {
+    printLogoutCannotCancel();
+  } else {
+    printLogoutSuccess();
   }
-  await tokenStore.clear();
-  await clearAuthMetadata();
-  printLogoutSuccess(serverRevoked);
+  return { ok: true };
 }
 
 // src/commands/status.ts
@@ -829,12 +2329,18 @@ async function runStatus(options) {
     });
     return;
   }
-  const result = await getValidAccessToken({
-    discovery,
-    clientId,
-    tokenStore,
-    resource: options.resource
-  });
+  let result;
+  try {
+    result = await getValidAccessToken({
+      discovery,
+      clientId,
+      tokenStore,
+      resource: options.resource
+    });
+  } catch {
+    printAuthStatus({ state: "store-unreadable" });
+    return;
+  }
   switch (result.status) {
     case "signed-out":
       printAuthStatus({ state: "signed-out" });
@@ -851,7 +2357,7 @@ async function runStatus(options) {
       return;
     case "refreshed": {
       const expiresAt = result.expiresIn ? Date.now() + result.expiresIn * 1e3 : null;
-      await saveAuthMetadata({ issuer: discovery.issuer, clientId, expiresAt });
+      await saveAuthMetadata({ issuer: discovery.issuer, clientId, expiresAt, savedToStore: true });
       printAuthStatus({ state: "signed-in", issuer: discovery.issuer, expiresAt });
       return;
     }
@@ -866,7 +2372,14 @@ var cliEnvSchema = z.object({
   /** OAuth public client id. */
   DAZZER_AUTH_CLIENT_ID: z.string().min(1).default("dazzer-cli-local"),
   /** Resource indicator for JWT access tokens. Defaults to the production MCP server. */
-  DAZZER_AUTH_RESOURCE: z.url().default("https://graph.dazzer.io/mcp")
+  DAZZER_AUTH_RESOURCE: z.url().default("https://graph.dazzer.io/mcp"),
+  /**
+   * Where Dazzer itself is — the main service, as opposed to the sign-in server the other three
+   * settings describe. It defaults to the same host the sign-in audience above already names,
+   * because they are the same service seen from two sides; the default lives here, beside the
+   * others, so no library and no command carries a production host of its own.
+   */
+  DAZZER_API_BASE_URL: z.url().default("https://graph.dazzer.io")
 });
 var cachedEnv = null;
 function validateEnv() {
@@ -875,12 +2388,38 @@ function validateEnv() {
   }
   return cachedEnv;
 }
+function signInServerDefaults() {
+  const settings = cliEnvSchema.pick({ DAZZER_AUTH_ISSUER: true, DAZZER_AUTH_CLIENT_ID: true }).parse(process.env);
+  return { issuer: settings.DAZZER_AUTH_ISSUER, clientId: settings.DAZZER_AUTH_CLIENT_ID };
+}
 
 // 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").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) => {
@@ -893,8 +2432,15 @@ auth.command("login").description("Sign in through your browser; falls back to a
     });
   }
 );
-auth.command("logout").description("Sign out and remove stored tokens").action(async () => {
-  await runLogout();
+auth.command("logout").description("Cancel your sign-in and remove it from this machine").option(
+  "--forget-this-machine",
+  "On a machine with no credential store, remove its sign-in record without cancelling anything"
+).action(async (opts) => {
+  const result = await runLogout({
+    defaults: signInServerDefaults,
+    forgetThisMachine: opts.forgetThisMachine === true
+  });
+  if (!result.ok) process.exitCode = 1;
 });
 auth.command("status").description("Show sign-in status").option("--issuer <url>", "Authorization server URL").option("--client-id <id>", "OAuth client id").option("--resource <url>", "Resource indicator for access tokens").action(async (opts) => {
   await runStatus({