create-evda 0.1.5 → 0.1.7

package/lib/roles.mjs

@@ -22,8 +22,56 @@ export const ROLES = {
   // Who may read each circle: one grant file per (reader, circle), kept outside the circles as the
   // substrate keeps members/ outside ecos/. The access answer cannot live inside what it protects.
   grants: { layer: "circles", kind: "dir" },
+  // Where circles held FROM OTHER HOLDERS land (HQ-835): `<mounts>/<owner record id>/<circle>/`, one
+  // directory per owner and one subfolder per circle, so several circles from one owner are held
+  // side by side. Unmapped, a record holds one circle per owner at `mounts/<owner record id>`.
+  mounts: { layer: "circles", kind: "dir" },
+  // Where the owner's agent leaves messages for them and their replies come back (HQ-1246,
+  // lib/messages.mjs). Not part of any layer, like agents: a record without the mapping still has
+  // one, at `messages/`, which is what the phone app reads too.
+  messages: { layer: null, kind: "dir" },
+  // The four roles every record has at any scale (Spec 07 section 2, "Four roles, at every scale",
+  // HQ-1371). Each maps to one or more paths: the role's own key and any `<role>/<facet>` key, so a
+  // record with three journal folders writes `journal`, `journal/captures`, `journal/dreams`. Every
+  // value stays a string, so a reader that only knows string mappings still opens the record.
+  // `work` may instead name a live source, `harlequin:` or `harlequin:<project>` (or the object
+  // `{ "source": "harlequin", "project": "<id>" }`), read by lib/work.mjs.
+  journal: { layer: null, kind: "dir", four: true },
+  work: { layer: null, kind: "dir", four: true, source: true },
+  collections: { layer: null, kind: "dir", four: true },
+  knowledge: { layer: null, kind: "dir", four: true },
 };
 
+export const FOUR_ROLES = ["journal", "work", "collections", "knowledge"];
+
+// Keys named before the four roles, each a facet of one of them. They keep working under their
+// own names (every tool that reads `record/daily` still does); the four-role reader counts them.
+export const LEGACY_FACETS = { "record/daily": "journal", "record/captures": "journal", "record/people": "collections", ledger: "knowledge" };
+
+// The sources `work` can name. Anything else is refused by doctor rather than read as a path.
+export const WORK_SOURCES = ["harlequin"];
+
+// The four role a mapping key fills, or null: `journal`, `journal/dreams`, `record/daily` all fill
+// journal.
+export function fourRoleOf(key) {
+  if (LEGACY_FACETS[key]) return LEGACY_FACETS[key];
+  const base = key.split("/")[0];
+  return FOUR_ROLES.includes(base) && (key === base || key.length > base.length + 1) ? base : null;
+}
+
+// The spec a key is read with: its own, or its four role's for a facet key.
+const specOf = (role) => ROLES[role] ?? (fourRoleOf(role) && role.includes("/") ? ROLES[fourRoleOf(role)] : undefined);
+
+// A `work` value that names a source rather than a folder, as { source, project }, or null for a
+// path. The string form is `<source>:` or `<source>:<project>`, the same scheme-prefix shape a
+// reference uses (Spec 07 section 4).
+export function workSource(value) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) return { source: value.source, project: value.project ?? null, form: "object" };
+  if (typeof value !== "string") return null;
+  const m = /^([a-z][a-z0-9-]*):(.*)$/.exec(value);
+  return m ? { source: m[1], project: m[2] === "" ? null : m[2], form: "string" } : null;
+}
+
 export const ROLE_NAMES = Object.keys(ROLES);
 
 export function rolesForLayer(layer) {
@@ -33,11 +81,15 @@ export function rolesForLayer(layer) {
 // Resolve one role. Never throws for an absent or missing role; the caller decides how loud
 // to be. Throws only when a mapped path escapes the record, which is refused everywhere.
 export function resolveRole(evda, role) {
-  const spec = ROLES[role];
+  const spec = specOf(role);
   const rel = evda.manifest.mapping[role];
   if (rel === undefined) {
     return { role, layer: spec?.layer ?? null, known: !!spec, mapped: false, rel: null, abs: null, exists: false };
   }
+  if (spec?.source) {
+    const source = workSource(rel);
+    if (source) return { role, layer: null, kind: "source", known: true, mapped: true, rel: null, abs: null, exists: true, isDir: false, source };
+  }
   if (isAbsolute(rel)) {
     throw new EvdaError(`REFUSED: mapping for "${role}" is absolute (${rel}). Mappings are relative to the record root.`, {
       code: "BAD_MAPPING",
@@ -87,3 +139,56 @@ export function ledgerFile(evda) {
   }
   return r;
 }
+
+// The four roles of a record (HQ-1371), each a list of what fills it. A path entry is
+// { key, role, rel, abs, exists, isDir }; a source entry (work only) is { key, role, source }.
+// `problems` are sentences for doctor, never thrown: a path that is missing or is a file, one path
+// filling two roles, a path inside a sub-record (which has its own four roles), and a work source
+// this tool cannot read. `subRecords` is the list of sub-record roots relative to the record.
+// EVDA_ROLES_FALSIFY=<mode,...>, for the tests: two-roles skips the one-path-one-role check,
+// missing-path skips the existence check, into-subrecord skips the sub-record check.
+export const ROLES_FALSIFY_MODES = ["two-roles", "missing-path", "into-subrecord"];
+const rolesFalsified = (mode) => (process.env.EVDA_ROLES_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+export function fourRoles(evda, { subRecords = [] } = {}) {
+  const roles = Object.fromEntries(FOUR_ROLES.map((r) => [r, []]));
+  const problems = [];
+  for (const key of Object.keys(evda.manifest.mapping)) {
+    const role = fourRoleOf(key);
+    if (!role) continue;
+    let r;
+    try { r = resolveRole(evda, key); } catch (e) { problems.push(e.message); continue; }
+    if (r.kind === "source") {
+      const { source, project } = r.source;
+      if (typeof source !== "string" || !WORK_SOURCES.includes(source)) { problems.push(`"${key}" names the source ${JSON.stringify(source)}; this tool reads ${WORK_SOURCES.join(", ")}, or a folder of effort files.`); continue; }
+      if (project !== null && (typeof project !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(project))) { problems.push(`"${key}" names the project ${JSON.stringify(project)}, which is not a board project id.`); continue; }
+      roles.work.push({ key, role, source: { source, project } });
+      continue;
+    }
+    if (typeof evda.manifest.mapping[key] !== "string") { problems.push(`"${key}" must be a path relative to the record${role === "work" ? `, or a source such as "harlequin:"` : ""}.`); continue; }
+    const rel = r.rel.replace(/\/+$/, "");
+    if (!r.exists) { if (!rolesFalsified("missing-path")) problems.push(`"${key}" is mapped to ${rel}, which does not exist.`); }
+    else if (!r.isDir) problems.push(`"${key}" is mapped to ${rel}, which is a file; a role holds a folder.`);
+    const inside = subRecords.find((s) => rel === s || rel.startsWith(`${s}/`));
+    if (inside !== undefined && !rolesFalsified("into-subrecord")) problems.push(`"${key}" is mapped to ${rel}, inside the sub-record at ${inside}, which declares its own roles. A parent reaches a sub-record through a mount, never by mapping its folders.`);
+    roles[role].push({ key, role, rel, abs: r.abs, exists: r.exists, isDir: r.isDir });
+  }
+  // One path, one role. The same folder under two roles would give its files two answers.
+  const byPath = new Map();
+  for (const role of FOUR_ROLES) for (const e of roles[role]) if (e.rel !== undefined) {
+    const was = byPath.get(e.rel);
+    if (was && was.role !== role && !rolesFalsified("two-roles")) problems.push(`${e.rel} fills two roles, ${was.role} ("${was.key}") and ${role} ("${e.key}"). A folder fills one.`);
+    else if (!was) byPath.set(e.rel, e);
+  }
+  return { roles, problems, declared: FOUR_ROLES.filter((r) => roles[r].length) };
+}
+
+// The four role a path in the record is in, by the longest role path above it, or null.
+export function roleForPath(four, rel) {
+  let best = null;
+  for (const role of FOUR_ROLES) for (const e of four.roles[role]) {
+    if (e.rel === undefined) continue;
+    if (e.rel === "" || rel === e.rel || rel.startsWith(`${e.rel}/`)) if (!best || e.rel.length > best.rel.length) best = e;
+  }
+  return best;
+}

package/lib/routines.mjs

@@ -1,5 +1,6 @@
-// Starter routines: a morning organize and a weekly look back, each optional, each scheduled only on
-// the owner's yes.
+// Starter routines: a morning organize and a weekly look back. The morning organize is on by default
+// (HQ-1246, his call 2026-09-27: "We know that it needs to be organizing and stuff 100%"); setup says
+// so in one line and offers off. The weekly look back stays offered, never on without a yes.
 //
 // The first choice is Claude's own scheduler. A local scheduled task in the Claude desktop app runs
 // on this machine with access to this folder (https://code.claude.com/docs/en/desktop-scheduled-tasks).
@@ -10,8 +11,8 @@
 // calendar, through a login shell so the owner's `claude` is on PATH. `--install` writes it and
 // loads it; nothing else here schedules anything.
 
-import { mkdirSync, writeFileSync, existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { mkdirSync, writeFileSync, existsSync, realpathSync, rmSync, statSync } from "node:fs";
+import { delimiter, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { openEvda, holderOf } from "./manifest.mjs";
@@ -38,6 +39,43 @@ export const ROUTINES = {
 };
 export const ROUTINE_KEYS = Object.keys(ROUTINES);
 
+// EVDA_ROUTINES_FALSIFY=opt-in makes the default nothing, the state before HQ-1246, for the test
+// that shows the default is what installs it.
+export function defaultRoutines(env = process.env) {
+  return (env.EVDA_ROUTINES_FALSIFY ?? "").split(",").map((m) => m.trim()).includes("opt-in") ? [] : ["morning"];
+}
+
+// The owner's claude, found once at setup: EVDA_CLAUDE, then PATH, then where the installers put it.
+// A launchd job runs a login shell, which does not read .zshrc, so a claude on PATH only through
+// .zshrc is invisible to it; the job carries the path found here instead.
+export function findClaude(env = process.env) {
+  if (env.EVDA_CLAUDE) return env.EVDA_CLAUDE;
+  const home = env.HOME ?? homedir();
+  const dirs = [...(env.PATH ?? "").split(delimiter), join(home, ".local", "bin"), join(home, ".claude", "local"), "/opt/homebrew/bin", "/usr/local/bin"];
+  for (const d of dirs) {
+    if (!d) continue;
+    const p = join(d, "claude");
+    try { if (statSync(p).isFile()) return p; } catch {}
+  }
+  return null;
+}
+
+// macOS keeps a scheduled job out of these folders unless the shell running it has Full Disk Access.
+export function protectedLocation(dir, env = process.env) {
+  const home = env.HOME ?? homedir();
+  let real = resolve(dir);
+  try { real = realpathSync(real); } catch {}
+  let realHome = home;
+  try { realHome = realpathSync(home); } catch {}
+  for (const h of new Set([home, realHome])) {
+    for (const f of ["Documents", "Desktop", "Downloads", join("Library", "Mobile Documents")]) {
+      const base = join(h, f);
+      if (real === base || real.startsWith(base + sep) || resolve(dir).startsWith(base + sep)) return f === join("Library", "Mobile Documents") ? "iCloud Drive" : f;
+    }
+  }
+  return null;
+}
+
 const q = (s) => (/^[A-Za-z0-9_./:@=+-]+$/.test(s) ? s : `'${String(s).replace(/'/g, "'\\''")}'`);
 
 // The shell command a routine runs, with this machine's node and this package's bin.
@@ -58,7 +96,7 @@ export function desktopInstructions(key, dir) {
     `  Name:         ${r.id}`,
     `  Schedule:     ${r.when}`,
     `  Folder:       ${resolve(dir)}`,
-    "  Instructions: Run this command in the folder, then tell me the report path it prints and anything it SKIPPED:",
+    "  Instructions: Run this command in the folder, then tell me the report path it prints and anything that did not run:",
     `                ${routineCommand(key, dir)}`,
     "",
     "A local routine runs while the app is open and the computer is awake.",
@@ -72,7 +110,7 @@ export function label(key, evda) {
 
 const xml = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 
-export function launchdPlist(key, dir, { home = homedir() } = {}) {
+export function launchdPlist(key, dir, { home = homedir(), claude = null } = {}) {
   const evda = openEvda(dir);
   const r = ROUTINES[key];
   const log = join(home, "Library", "Logs", "evda", `${r.id}.log`);
@@ -93,6 +131,7 @@ export function launchdPlist(key, dir, { home = homedir() } = {}) {
     "  <dict>",
     cal,
     "  </dict>",
+    ...(claude ? ["  <key>EnvironmentVariables</key>", "  <dict>", `    <key>EVDA_CLAUDE</key><string>${xml(claude)}</string>`, "  </dict>"] : []),
     `  <key>StandardOutPath</key><string>${xml(log)}</string>`,
     `  <key>StandardErrorPath</key><string>${xml(log)}</string>`,
     "</dict>",
@@ -101,31 +140,116 @@ export function launchdPlist(key, dir, { home = homedir() } = {}) {
   ].join("\n");
 }
 
-// Write the launchd job and load it. `agentsDir` and `load` exist so tests never touch the real
-// ~/Library/LaunchAgents or launchctl.
-export function installLaunchd(key, dir, { agentsDir = process.env.EVDA_LAUNCH_AGENTS ?? join(homedir(), "Library", "LaunchAgents"), load = process.env.EVDA_NO_LAUNCHCTL !== "1", home = homedir() } = {}) {
-  if (process.platform !== "darwin" && load) throw new EvdaError("REFUSED: launchd is macOS only. Use the Claude desktop routine instead. Nothing was written.", { exit: 2 });
+// launchctl is off when the env handed in says so OR this process's own env does. A caller that
+// hands in a partial env (a test's `{ HOME }`) no longer drops the guard and loads a real job, which
+// is how io.evda.evda-morning-organize.*.atlas jobs stayed loaded after test runs.
+export const noLaunchctl = (env = process.env) => env.EVDA_NO_LAUNCHCTL === "1" || process.env.EVDA_NO_LAUNCHCTL === "1";
+
+// How launchctl is run. EVDA_LAUNCHCTL names a stand-in binary so the tests can drive the whole CLI
+// without the real launchctl; `launchctl` in the options is the same seam for in-process callers.
+export function runLaunchctl(args, env = process.env) {
+  const r = spawnSync(env.EVDA_LAUNCHCTL || "launchctl", args, { encoding: "utf8" });
+  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+const falsified = (env, mode) => (env.EVDA_ROUTINES_FALSIFY ?? "").split(",").map((m) => m.trim()).includes(mode);
+
+// Unload a job by its label, not by its file: a job whose file is already gone, or was loaded from
+// another path, is still unloaded. EVDA_ROUTINES_FALSIFY=skip-bootout skips it (the HQ-1246 bug:
+// the file went, the job stayed loaded), for the tests.
+function bootout(target, env, launchctl) {
+  if (!falsified(env, "skip-bootout")) launchctl(["bootout", target]);
+}
+
+// Loaded or not, asked of launchd itself: `launchctl print gui/<uid>/<label>` exits 0 only for a
+// loaded job (113 when there is none).
+const isLoaded = (target, launchctl) => launchctl(["print", target]).status === 0;
+
+// Write the launchd job and load it. `agentsDir`, `load` and `launchctl` exist so tests never touch
+// the real ~/Library/LaunchAgents or launchctl. A job already loaded under this label is unloaded
+// first, so a second install replaces it rather than failing to load a duplicate.
+export function installLaunchd(key, dir, { env = process.env, home = env.HOME ?? homedir(), agentsDir = env.EVDA_LAUNCH_AGENTS ?? process.env.EVDA_LAUNCH_AGENTS ?? join(home, "Library", "LaunchAgents"), load = !noLaunchctl(env), claude = findClaude(env), launchctl = (a) => runLaunchctl(a, env) } = {}) {
+  if (process.platform !== "darwin" && load && !env.EVDA_LAUNCHCTL) throw new EvdaError("REFUSED: launchd is macOS only. Use the Claude desktop routine instead. Nothing was written.", { exit: 2 });
   const evda = openEvda(dir);
-  const plist = launchdPlist(key, dir, { home });
+  const plist = launchdPlist(key, dir, { home, claude });
   mkdirSync(agentsDir, { recursive: true });
-  mkdirSync(join(home, "Library", "Logs", "evda"), { recursive: true });
-  const path = join(agentsDir, `${label(key, evda)}.plist`);
+  const name = label(key, evda);
+  const path = join(agentsDir, `${name}.plist`);
   const existed = existsSync(path);
   writeFileSync(path, plist);
   let loaded = "not loaded (EVDA_NO_LAUNCHCTL=1)";
   if (load) {
-    const uid = process.getuid?.() ?? "";
-    spawnSync("launchctl", ["bootout", `gui/${uid}`, path], { encoding: "utf8" });
-    const r = spawnSync("launchctl", ["bootstrap", `gui/${uid}`, path], { encoding: "utf8" });
+    // The log folder is made only for a job that is loaded, so an unloaded install writes nothing
+    // into the owner's home but the job file.
+    mkdirSync(join(home, "Library", "Logs", "evda"), { recursive: true });
+    const domain = `gui/${process.getuid?.() ?? ""}`;
+    bootout(`${domain}/${name}`, env, launchctl);
+    const r = launchctl(["bootstrap", domain, path]);
     loaded = r.status === 0 ? "loaded" : `launchctl bootstrap exited ${r.status}: ${(r.stderr ?? "").trim()}`;
   }
-  return { path, existed, loaded };
+  return { path, label: name, existed, loaded, claude };
+}
+
+// Turn a routine off: unload the job, remove its file, then look again. `off` is true only when
+// launchd has no job under the label and the file is gone; anything left is named in `left`.
+// Nothing there at all is not an error.
+export function uninstallLaunchd(key, dir, { env = process.env, home = env.HOME ?? homedir(), agentsDir = env.EVDA_LAUNCH_AGENTS ?? process.env.EVDA_LAUNCH_AGENTS ?? join(home, "Library", "LaunchAgents"), load = !noLaunchctl(env), launchctl = (a) => runLaunchctl(a, env) } = {}) {
+  const name = label(key, openEvda(dir));
+  const path = join(agentsDir, `${name}.plist`);
+  const target = `gui/${process.getuid?.() ?? ""}/${name}`;
+  const hadFile = existsSync(path);
+  const wasLoaded = load && isLoaded(target, launchctl);
+  if (!hadFile && !wasLoaded) return { path, label: name, removed: false, off: true, left: [] };
+  if (wasLoaded) bootout(target, env, launchctl);
+  rmSync(path, { force: true });
+  const left = [];
+  if (load && isLoaded(target, launchctl)) left.push(`launchd still has ${name} loaded (remove it: launchctl bootout ${target})`);
+  if (existsSync(path)) left.push(`the job file is still at ${path}`);
+  return { path, label: name, removed: true, off: left.length === 0, left };
+}
+
+// What setup does with the routines it was given (HQ-1246). On a Mac each is installed as a launchd
+// job; elsewhere nothing can be scheduled from here, so it prints the Claude desktop steps and says
+// so. Returns the lines to print.
+export function installAtSetup(keys, dir, { env = process.env, platform = process.platform } = {}) {
+  const lines = [];
+  for (const key of keys) {
+    const r = ROUTINES[key];
+    lines.push("");
+    if (platform === "darwin") {
+      const done = installLaunchd(key, dir, { env });
+      const lead = key === "morning" ? "Organizing is on" : `${r.title} is on`;
+      lines.push(`${lead}: ${r.when.toLowerCase()} your own Claude ${key === "morning" ? "files your notes into their day and writes what belongs where" : "reads your week back to you"}, in reports/. Turn it off: evda routine ${key} ${resolve(dir)} --uninstall`);
+      lines.push(`  launchd job ${done.path}: ${done.loaded}. It runs while this computer is on; asleep at that hour, it runs when it wakes.`);
+      if (!done.claude) lines.push("  Claude Code was not found on this computer, so the filing runs and the report says the AI part did not. Install Claude Code and sign in to add it.");
+    } else {
+      for (const l of desktopInstructions(key, dir).split("\n")) lines.push(l);
+      lines.push("Nothing was scheduled on this computer: add the routine above in the Claude desktop app.");
+    }
+  }
+  const where = keys.length && platform === "darwin" ? protectedLocation(dir, env) : null;
+  if (where) lines.push(`This record is in ${where}. A scheduled run cannot read it there unless the shell has Full Disk Access (System Settings, Privacy & Security, Full Disk Access), or move the record to a folder of its own.`);
+  return lines;
 }
 
 export function routineMain(args, { pickDir }) {
   const key = args[0];
-  if (!ROUTINE_KEYS.includes(key)) throw new EvdaError(`usage: evda routine <${ROUTINE_KEYS.join("|")}> [dir] [--launchd] [--install]`, { exit: 2 });
+  if (!ROUTINE_KEYS.includes(key)) throw new EvdaError(`usage: evda routine <${ROUTINE_KEYS.join("|")}> [dir] [--launchd] [--install] [--uninstall]`, { exit: 2 });
   const { dir, flags } = pickDir(args.slice(1));
+  if (flags.includes("--uninstall")) {
+    const r = uninstallLaunchd(key, dir);
+    if (!r.removed) {
+      console.log(`nothing to remove: no ${ROUTINES[key].id} job at ${r.path}`);
+      return 0;
+    }
+    const what = key === "morning" ? "organizing" : ROUTINES[key].title;
+    if (!r.off) {
+      console.log(`${what} is not off: ${r.left.join("; ")}.`);
+      return 1;
+    }
+    console.log(`removed ${r.path}: ${what} is off. Turn it back on: evda routine ${key} ${resolve(dir)} --install`);
+    return 0;
+  }
   if (flags.includes("--install")) {
     const r = installLaunchd(key, dir);
     console.log(`${r.existed ? "replaced" : "wrote"} ${r.path}: ${r.loaded}. ${ROUTINES[key].when}, it runs: ${routineCommand(key, dir)}`);

package/lib/secret-shape.mjs

@@ -0,0 +1,58 @@
+// Whether a string is shaped like a secret (a password, key or token), for every write that refuses
+// one: a reference, evda_write, a gather, and the Claude Code prompt hook (HQ-1385).
+//
+// node: built-ins only, and no imports at all: `evda hook install` copies this file byte for byte
+// beside the prompt hook in a record's .claude/hooks/, so the hook refuses exactly what the MCP
+// server refuses. lib/references.mjs re-exports it; `evda doctor` says when the copy is older.
+//
+// A value shaped like a secret refuses the write.
+// The shapes are the obvious ones: a private key block, a JWT, the prefixes the common services
+// stamp on their tokens, a bearer header, a URL carrying a password or a credential in its query,
+// and as a last net a long mixed-case high-entropy token that is not a UUID.
+const SECRET_PARAM = /^(key|token|access_token|api_key|apikey|auth|password|secret|sig|signature|session|x-amz-signature|x-amz-credential)$/i;
+const SECRET_VALUE = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "a private key block"],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/, "a JWT"],
+  [/\b(sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/, "an API key (sk-...)"],
+  [/\b(sk|pk|rk)_(live|test)_[A-Za-z0-9]{8,}\b/, "an API key (sk_live_...)"],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/, "a GitHub token"],
+  [/\bglpat-[A-Za-z0-9_-]{20,}\b/, "a GitLab token"],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, "a Slack token"],
+  [/\bAKIA[0-9A-Z]{16}\b/, "an AWS access key id"],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/, "a Google API key"],
+  [/\bBearer\s+[A-Za-z0-9._~+/-]{16,}=*/i, "a bearer token"],
+];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function entropy(s) {
+  const counts = new Map();
+  for (const c of s) counts.set(c, (counts.get(c) ?? 0) + 1);
+  let h = 0;
+  for (const n of counts.values()) {
+    const p = n / s.length;
+    h -= p * Math.log2(p);
+  }
+  return h;
+}
+
+// Why a string looks like a secret, or null.
+export function secretShape(value) {
+  if (typeof value !== "string") return null;
+  for (const [re, what] of SECRET_VALUE) if (re.test(value)) return what;
+  const m = /^(?:url:)?([a-z][a-z0-9+.-]*:\/\/[^\s]+)$/i.exec(value);
+  if (m) {
+    let u = null;
+    try { u = new URL(m[1]); } catch { u = null; }
+    if (u) {
+      if (u.password !== "") return "a password in the URL";
+      for (const k of u.searchParams.keys()) if (SECRET_PARAM.test(k)) return `a credential in the URL query (${k})`;
+    }
+  }
+  for (const tok of value.split(/[\s"'<>]+/)) {
+    if (tok.length < 40 || UUID.test(tok)) continue;
+    if (!/[A-Z]/.test(tok) || !/[a-z]/.test(tok) || !/\d/.test(tok)) continue;
+    if (!/^[A-Za-z0-9+/=_-]+$/.test(tok)) continue;
+    if (entropy(tok) >= 4.5) return "a long high-entropy token";
+  }
+  return null;
+}

package/lib/setup.mjs

@@ -58,7 +58,105 @@ export const PLATFORMS = {
 
 export const PLATFORM_KEYS = Object.keys(PLATFORMS);
 
+// What each company's own pages say about training and retention, for its consumer apps and for its
+// API or business plans. Quoted, never paraphrased inside the quotes, each with the page it came from
+// and the date it was read. This is what an agent answers with when someone asks which AI is safest:
+// the table and its date, never a ranking of which company is likelier to misuse data. A page that
+// could not be read says so rather than being filled in from memory.
+export const TERMS_CHECKED = "2026-09-22";
+export const PROVIDER_TERMS = {
+  claude: {
+    company: "Anthropic",
+    consumer: [
+      { says: "If you decide to turn off the model training setting, we will not use any new chats and coding sessions you have with Claude for future model training.", url: "https://privacy.claude.com/en/articles/12109829-how-do-i-change-my-model-improvement-privacy-settings" },
+      { says: "Deleted from our back-end storage systems within 30 days", about: "a chat you delete", url: "https://privacy.claude.com/en/articles/10023548-how-long-do-you-store-my-data" },
+      { says: "we may retain your data in a de-identified format for up to 5 years in our model training pipelines.", about: "with training on", url: "https://privacy.claude.com/en/articles/10023548-how-long-do-you-store-my-data" },
+    ],
+    business: [
+      { says: "Anthropic may not train models on Customer Content from Services.", url: "https://www.anthropic.com/legal/commercial-terms" },
+      { says: "For Anthropic API users, we automatically delete inputs and outputs on our backend within 30 days of receipt or generation", url: "https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data" },
+      { says: "Prompts submitted to, and outputs generated by, covered models are retained for 30 days to support our safety work, on every platform where these models are offered.", about: "the models that page names as covered", url: "https://privacy.claude.com/en/articles/15425996-data-retention-practices-for-covered-models" },
+    ],
+  },
+  chatgpt: {
+    company: "OpenAI",
+    consumer: [
+      { says: null, unread: "The page refused automated reads when checked. Read it yourself before relying on it.", url: "https://help.openai.com/en/articles/7730893-data-controls-faq" },
+    ],
+    business: [
+      { says: "As of March 1, 2023, data sent to the OpenAI API is not used to train or improve OpenAI models (unless you explicitly opt in to share data with us).", url: "https://platform.openai.com/docs/guides/your-data" },
+      { says: "By default, abuse monitoring logs are generated for all API feature usage and retained for up to 30 days, unless longer retention is required by law", url: "https://platform.openai.com/docs/guides/your-data" },
+      { says: null, unread: "ChatGPT Business and Enterprise: the page refused automated reads when checked.", url: "https://openai.com/enterprise-privacy/" },
+    ],
+  },
+  gemini: {
+    company: "Google",
+    consumer: [
+      { says: "If the Keep Activity setting is off: Your future chats won't appear in your Activity, and won't be used to train our AI models, unless you choose to send Google feedback.", url: "https://support.google.com/gemini/answer/13594961" },
+      { says: "Temporary chats and chats you have when Keep Activity is off are retained with your account for 72 hours", url: "https://support.google.com/gemini/answer/13594961" },
+      { says: "Reviewed chats are retained for up to three years.", about: "chats a person reviewed", url: "https://support.google.com/gemini/answer/13594961" },
+    ],
+    business: [
+      { says: "Google doesn't use your prompts (including associated system instructions, cached content, and files such as images, videos, or documents) or responses to improve our products", about: "the paid Gemini API", url: "https://ai.google.dev/gemini-api/terms" },
+      { says: "For Paid Services, Google logs prompts and responses for a limited period of time, solely for detecting and preventing violations of the Prohibited Use Policy", url: "https://ai.google.dev/gemini-api/terms" },
+      { says: "Workspace does not use customer data for training models without customer's prior permission or instruction.", url: "https://support.google.com/a/answer/15706919" },
+    ],
+  },
+  cursor: {
+    company: "Cursor (Anysphere)",
+    consumer: [
+      { says: "With Privacy Mode enabled, your code is never used for training.", url: "https://cursor.com/help/security-and-privacy/privacy" },
+      { says: "Anysphere retains your personal data only for as long as necessary to operate the Service effectively and to support legitimate business needs", url: "https://cursor.com/privacy" },
+    ],
+    business: [
+      { says: "For teams, Privacy Mode is enabled by default for all team members.", url: "https://cursor.com/help/security-and-privacy/privacy" },
+      { says: "ZDR doesn't apply when you use your own API keys.", url: "https://cursor.com/help/security-and-privacy/privacy" },
+    ],
+  },
+};
+
+// The "What each company says" section of the scaffolded README, generated from PROVIDER_TERMS.
+export function termsSection() {
+  const line = (t) => (t.says === null ? `  - ${t.unread} <${t.url}>` : `  - "${t.says}"${t.about ? ` (${t.about})` : ""} <${t.url}>`);
+  return [
+    `Quoted from each company's own pages, read on ${TERMS_CHECKED}. Terms change; each line links the page to check.`,
+    "",
+    ...Object.entries(PROVIDER_TERMS).flatMap(([k, p]) => [
+      `- **${p.company}** (${SHORT_NAMES_FOR_TERMS[k]})`,
+      "  - Personal plans:",
+      ...p.consumer.map((t) => `  ${line(t)}`),
+      "  - API and business plans:",
+      ...p.business.map((t) => `  ${line(t)}`),
+    ]),
+  ].join("\n");
+}
+
+// Who reads a new record, written into evda.json at setup: the AI the owner chose. The default is
+// not local, because most people have no local model; restriction is something they opt into.
+// Training is written as off only when they confirmed it.
+export function readerFor({ platform, platformName, trainingOff, date }) {
+  if (!platform) return null;
+  const r = { ai: platform };
+  if (platform === "other" && oneLineName(platformName)) r.name = oneLineName(platformName);
+  r.training = trainingOff ? "off" : "unknown";
+  if (trainingOff) r.confirmed = date;
+  return [r];
+}
+const oneLineName = (s) => String(s ?? "").replace(/\s+/g, " ").trim();
+
+// What a new owner is told about where their words go. In create-evda's finish screen, the
+// scaffolded README, and Spec 07 section 8; scripts/build-templates.mjs --check fails when the
+// spec's copy differs from this one.
+export const INTRO = [
+  "Your information is stored locally on your own devices as files you can open with anything. When your devices sync, what goes between them is locked with keys only your devices have, so EVÐA can't read it.",
+  "",
+  "The AI you choose reads what it needs to think with you. With training turned off, the company behind it says it won't use your information, and that promise is backed by their terms and by law. We can't prove it for them, and I don't want to pretend we can.",
+  "",
+  "If you want more than that, you have two options. You can run a model locally on your own computer, and you can just ask how to set it up. Or you can say something is just to be noted, and no AI reads it until you say it can.",
+].join("\n");
+
 const SHORT_NAMES = { claude: "Claude", chatgpt: "ChatGPT", gemini: "Gemini", cursor: "Cursor", other: "" };
+const SHORT_NAMES_FOR_TERMS = { claude: "Claude", chatgpt: "ChatGPT and Codex", gemini: "Gemini", cursor: "Cursor" };
 
 // The "Turning training off" section of the scaffolded README, generated from PLATFORMS so the
 // owner's copy and the setup flow say the same thing.
@@ -161,6 +259,10 @@ export const WELCOME = [
   "",
   "Freewrite with Iris about anything: what stresses you out, what you are unsure of, the things you do every day that feel slightly off. You will get better at seeing your thoughts, understanding why you do what you do, why certain people matter to you and why you react the way you do. Iris cannot give you the right answer for your life, but it is good at suggestions: take them, push back on what you disagree with, get specific, and get a new response back. Iris keeps it all in your EVÐA as you talk.",
   "",
+  "What it actually does is keep your words, not a summary of them. What you say goes in the way you said it, filed into the day it happened, the person it was about, or just the thought as it arrived. Nothing gets compressed into a takeaway, because the takeaway is the part that turns out to be wrong. Alongside the record sits a ledger: a claim about you, and what actually happened to it. A claim that does not hold gets marked as not holding, so it stops coming back.",
+  "",
+  "That is why it gets better the more you use it. In the first week Iris is working from almost nothing and will ask you things you have already answered. By the second month it is not asking those, and it can see things one day cannot show: the same frustration turning up in three places you thought were unrelated, a person you keep circling back to, a rule you set for yourself in March and quietly stopped following in June. You get that by writing, not by filling anything in.",
+  "",
   "It is not easy to put your deepest thoughts into a system, especially ones you have not admitted to yourself, never mind a friend or a therapist. EVÐA is built for exactly that, and it is open source so you can check. Your data is always yours, and never accessible to anyone at EVÐA: the company never receives your record. The AI you use does receive what Iris reads, which is why setup asks you to turn training off first.",
   "",
   "The only requirement is that you want to, and you are open to it. Iris is the default name; call it whatever you like.",
@@ -178,13 +280,23 @@ export function questions(agent = DEFAULT_AGENT_NAME) {
     { key: "voice", text: `How do you want ${agent} to talk to you?` },
     { key: "platform", text: "Which AI will you use it with?" },
     { key: "trainingOff", text: "Before anything personal goes in, turn model training off:" },
+    { key: "filing", text: `Should ${agent} file everything you say automatically, or only when you ask? (everything)` },
     { key: "import", text: "Bring in what your AI already knows about you?" },
     { key: "skill", text: `Install the evda skill for Claude Code, so ${agent} works through your EVÐA from any folder?` },
-    { key: "morning", text: "Add a morning organize routine, which files your captures into their day and reports what belongs where?" },
+    { key: "morning", text: "Organizing is on: each morning your own Claude files your notes into their day and writes what belongs where. Keep it on?" },
     { key: "weekly", text: "Add a weekly look back routine, which reads your week back to you?" },
   ];
 }
 
+// The filing answer (HQ-1385): "everything" or "asked", from what the owner typed. Empty is the
+// default the question shows, everything. null when the answer names neither.
+export function filingKey(answer) {
+  const a = String(answer ?? "").trim().toLowerCase().replace(/[.!]+$/, "");
+  if (a === "" || ["everything", "every", "all", "e", "1", "yes", "y", "automatically", "auto"].includes(a)) return "everything";
+  if (["asked", "ask", "a", "2", "no", "n", "only when i ask", "when i ask", "only when asked", "manual", "manually"].includes(a)) return "asked";
+  return null;
+}
+
 // What a yes to the import offer shows: the line before IMPORT_PROMPT and the line after it.
 export function importLines(agent = DEFAULT_AGENT_NAME) {
   return {
@@ -259,6 +371,12 @@ export async function interview(opts, io, { presets = [] } = {}) {
     }
     a.trainingOff = true;
   }
+  if (!a.filing) {
+    out("");
+    let key = null;
+    while (!key) key = filingKey(await ask(`${q("filing", agent)} `));
+    a.filing = key;
+  }
   out("");
   out(DICTATION);
   out("");
@@ -279,9 +397,11 @@ export async function interview(opts, io, { presets = [] } = {}) {
   }
   if (a.routines == null) {
     out("");
-    out("Routines are optional and nothing is scheduled without a yes. Each runs through your own AI, never an API key in EVÐA.");
-    a.routines = [];
-    for (const key of ["morning", "weekly"]) if (await yes(key)) a.routines.push(key);
+    out("Routines run through your own AI, never an API key in EVÐA.");
+    // Organizing is on by default (HQ-1246): only an explicit no turns it off.
+    const keep = String(await ask(`${q("morning", agent)} (yes/no) `)).trim().toLowerCase();
+    a.routines = ["no", "n", "off"].includes(keep) ? [] : ["morning"];
+    if (await yes("weekly")) a.routines.push("weekly");
   }
   return a;
 }