create-evda 0.1.4 → 0.1.6

package/lib/references.mjs

@@ -34,6 +34,9 @@
 
 import { EvdaError } from "./errors.mjs";
 import { parseYaml } from "./yaml.mjs";
+import { secretShape } from "./secret-shape.mjs";
+
+export { secretShape };
 
 export const SCHEMES = ["contacts", "1password", "url", "evda"];
 export const REFERENCE_KEYS = ["ref", "label", "resolved"];
@@ -130,58 +133,9 @@ function bad(msg) {
   return new EvdaError(msg, { code: "BAD_REFERENCE", exit: 1 });
 }
 
-// Secret detection. A key named like a secret, or a value shaped like one, 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.
+// Secret detection is lib/secret-shape.mjs, shared with the prompt hook; a key named like a secret
+// is refused here too.
 const SECRET_KEY = /(pass(word|wd|phrase)?|secret|token|api[-_ ]?key|access[-_ ]?key|private[-_ ]?key|credential|bearer|cookie|session[-_ ]?id|otp|pin[-_ ]?code|client[-_ ]?secret)/i;
-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;
-}
 
 // Why a key name looks like it holds a secret, or null.
 export function secretKey(name) {

package/lib/render.mjs

@@ -0,0 +1,158 @@
+// Views rendered at publish (Spec 07 section 5, HQ-1351).
+//
+// One fact, stored once, as a typed entry placed by its subject. The public circle carries a
+// `render` member for each file the site reads, and the file is rendered on the way out from every
+// released entry whose frontmatter names the view:
+//
+//   ---
+//   kind: piece
+//   share: public        the mark, so the public circle's rule gathers it
+//   view: projects       which render member it feeds
+//   order: 3             its place in the rendered list; unique within the view
+//   id: proj_iris        the item's own id, repeated so a reader of the folder sees it
+//   title: Iris
+//   ---
+//   ```json
+//   { "id": "proj_iris", ... }     the item, exactly as the rendered file carries it
+//   ```
+//
+// A list view is the entries' items as one JSON list, sorted by `order`. An object view holds
+// exactly one entry and renders its item alone. The rendered bytes are deterministic (two-space
+// JSON, one trailing newline), so the same entries render to the same file on any device.
+//
+// Provenance (HQ-1367). An entry re-derived from its subject's own record says where from and when:
+//
+//   derived_from:        the record paths (a folder, a README) and shipped tickets (HQ-<n>) it was
+//     - "01_Projects/Evda/Iris - Universal Thinking Partner/README.md"
+//     - HQ-1351          derived from; a path must exist in the record
+//   derived_at: "2026-09-25"   when; an ISO date or date-time, never in the future
+//
+// Both or neither: an entry with only one is a problem, since a stranger's answer must trace to what
+// the record held. The fields live in the entry's frontmatter and never reach the rendered file.
+// `provenance` on each rendered entry reports them, with `changed`: the source files modified after
+// derived_at, which is a fact about files the publish pass reads to find what to re-derive.
+//
+// Everything that can go wrong is a problem the caller fails on, never a dropped entry: a view no
+// render member declares, a missing or repeated `order`, a body with no JSON block or one that does
+// not parse, an `id` in the frontmatter that is not the item's, an object view with two entries, a
+// render member that draws nothing. A publish with any problem refuses; doctor names each one.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { frontmatterOf, withoutSealed } from "./circles.mjs";
+
+// The frontmatter keys an entry uses to reach a view.
+export const VIEW = "view";
+export const ORDER = "order";
+export const DERIVED_FROM = "derived_from";
+export const DERIVED_AT = "derived_at";
+
+const TICKET = /^HQ-[1-9][0-9]*$/;
+const ISO = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+// The provenance an entry carries: { provenance } (null when it carries none) or { problem }.
+// `recordDir` resolves paths; `now` is injectable so a test can pin "the future".
+export function provenanceOf(front, recordDir, { now = new Date() } = {}) {
+  const from = front?.[DERIVED_FROM];
+  const at = front?.[DERIVED_AT];
+  if (from === undefined && at === undefined) return { provenance: null };
+  if (from === undefined) return { problem: `has ${DERIVED_AT} and no ${DERIVED_FROM}. A derived entry names what it was derived from.` };
+  if (at === undefined) return { problem: `has ${DERIVED_FROM} and no ${DERIVED_AT}. A derived entry says when it was derived.` };
+  if (!Array.isArray(from) || from.length === 0 || from.some((s) => typeof s !== "string" || s.trim() === "")) return { problem: `has ${DERIVED_FROM}: ${JSON.stringify(from)}; it is a non-empty list of record paths and HQ-<n> tickets.` };
+  const when = String(at);
+  if (!ISO.test(when) || Number.isNaN(Date.parse(when))) return { problem: `has ${DERIVED_AT}: ${JSON.stringify(at)}, which is not an ISO date.` };
+  const t = Date.parse(when);
+  if (t > now.getTime() + 24 * 3600 * 1000) return { problem: `has ${DERIVED_AT}: ${when}, which is in the future.` };
+  const root = resolve(recordDir);
+  const tickets = [];
+  const files = [];
+  for (const s of from) {
+    if (TICKET.test(s)) { tickets.push(s); continue; }
+    if (isAbsolute(s)) return { problem: `derives from ${JSON.stringify(s)}, an absolute path; a source is relative to the record root.` };
+    const abs = resolve(root, s);
+    if (abs !== root && !abs.startsWith(root + sep)) return { problem: `derives from ${JSON.stringify(s)}, which is outside the record.` };
+    if (!existsSync(abs)) return { problem: `derives from ${JSON.stringify(s)}, and nothing is there. A source the record does not hold cannot be traced to.` };
+    files.push({ path: s, abs });
+  }
+  // A date with no time is the end of that day: a source saved that afternoon was read for it.
+  const cutoff = /T/.test(when) ? t : t + 24 * 3600 * 1000;
+  const changed = files.filter((f) => { try { return statSync(f.abs).mtimeMs > cutoff; } catch { return false; } }).map((f) => f.path);
+  return { provenance: { from: [...from], at: when, tickets, files: files.map((f) => f.path), changed } };
+}
+
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+// The item an entry holds: the first ```json fence in the body. { value } or { problem }.
+export function entryJson(text) {
+  const m = /^```json[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*$/m.exec(text);
+  if (!m) return { problem: "has no ```json block. A view entry holds its item in one fenced JSON block." };
+  try {
+    return { value: JSON.parse(m[1]) };
+  } catch (e) {
+    return { problem: `its \`\`\`json block does not parse (${e.message}).` };
+  }
+}
+
+// Render the bytes of one view. Pure: the same entries render to the same bytes in any order.
+export function renderBytes(shape, items) {
+  const value = shape === "object" ? items[0] : items;
+  return Buffer.from(JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+// Group the files released into a public circle (`gathered` is `released()`'s row for it, or any
+// object with byPath and byRule lists of { path, abs, member, circle? }) by the view each names,
+// and render every render member of the circle.
+//
+// Returns { views, loose, problems }:
+//   views     one per render member: { member, view, path, shape, entries: [{ path, abs, sha256,
+//             order, id, home }], bytes } with entries sorted by order; bytes is null when the
+//             view has a problem
+//   loose     the released files that name no view, unchanged, exported as themselves
+//   problems  [{ path, message }], each one a refusal
+export function renderViews(evda, circle, gathered) {
+  const renders = Object.entries(circle.members).filter(([, m]) => m.kind === "render").map(([member, m]) => ({ member, view: m.view, path: m.rel, shape: m.shape, entries: [], bytes: null }));
+  const byView = new Map(renders.map((r) => [r.view, r]));
+  const loose = [];
+  const problems = [];
+  const problem = (path, message) => problems.push({ path, message });
+
+  for (const f of [...gathered.byPath, ...gathered.byRule]) {
+    let text;
+    try { text = readFileSync(f.abs, "utf8"); } catch (e) { problem(f.path, `could not be read (${e.message}).`); continue; }
+    // A sealed section (HQ-1220) is never rendered, whatever fence it holds.
+    text = withoutSealed(text).text;
+    const front = frontmatterOf(text);
+    const view = front?.[VIEW];
+    if (view === undefined || view === null || view === "") { loose.push(f); continue; }
+    if (typeof view !== "string") { problem(f.path, `has ${VIEW}: ${JSON.stringify(view)}, which is not a view name.`); continue; }
+    const target = byView.get(view);
+    if (!target) { problem(f.path, `names view "${view}", and no render member of circle "${circle.name}" declares it (declared: ${renders.map((r) => r.view).join(", ") || "none"}). A released entry that reaches nowhere is a silent drop.`); continue; }
+    const order = front[ORDER];
+    if (!Number.isInteger(order)) { problem(f.path, `has ${ORDER}: ${JSON.stringify(order)}; a view entry says where it goes with an integer.`); continue; }
+    const json = entryJson(text);
+    if (json.problem) { problem(f.path, json.problem); continue; }
+    const item = json.value;
+    const itemId = item && typeof item === "object" && !Array.isArray(item) ? item.id : undefined;
+    if (front.id !== undefined && itemId !== undefined && String(front.id) !== String(itemId)) { problem(f.path, `says id: ${JSON.stringify(front.id)} in its frontmatter and its item says "id": ${JSON.stringify(itemId)}. One id per fact.`); continue; }
+    const prov = provenanceOf(front, evda.dir);
+    if (prov.problem) { problem(f.path, prov.problem); continue; }
+    target.entries.push({ path: f.path, abs: f.abs, sha256: sha256Hex(Buffer.from(text, "utf8")), order, id: front.id ?? itemId ?? null, home: f.circle ?? circle.name, provenance: prov.provenance, item });
+  }
+
+  for (const r of renders) {
+    r.entries.sort((a, b) => a.order - b.order || a.path.localeCompare(b.path));
+    const seen = new Map();
+    for (const e of r.entries) {
+      if (seen.has(e.order)) problem(e.path, `has ${ORDER}: ${e.order} in view "${r.view}", and so does ${seen.get(e.order)}. One place per entry.`);
+      seen.set(e.order, e.path);
+    }
+    if (r.entries.length === 0) problem(r.path, `is rendered by member "${r.member}" from view "${r.view}", and no released entry names that view. A view that draws nothing is not published.`);
+    if (r.shape === "object" && r.entries.length > 1) problem(r.path, `is an object view ("${r.view}") and ${r.entries.length} entries name it: ${r.entries.map((e) => e.path).join(", ")}. An object view holds exactly one.`);
+    const mine = problems.some((p) => p.path === r.path || r.entries.some((e) => e.path === p.path));
+    if (!mine) r.bytes = renderBytes(r.shape, r.entries.map((e) => e.item));
+    for (const e of r.entries) delete e.item;
+  }
+
+  return { views: renders, loose, problems };
+}

package/lib/roles.mjs

@@ -22,8 +22,52 @@ 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" },
+  // 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 +77,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 +135,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/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.",
@@ -174,9 +276,11 @@ export function questions(agent = DEFAULT_AGENT_NAME) {
     { key: "agentName", text: `What would you like to call your agent? (${DEFAULT_AGENT_NAME})` },
     { key: "owner", text: "What is your name?" },
     { key: "purpose", text: `What do you want ${agent} for? Say it however it comes out.` },
+    { key: "preset", text: "How should your EVÐA be organized? Pick a starting set of folders, or start plain. Nothing you already have is moved." },
     { 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?" },
@@ -184,6 +288,15 @@ export function questions(agent = DEFAULT_AGENT_NAME) {
   ];
 }
 
+// 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 {
@@ -192,10 +305,27 @@ export function importLines(agent = DEFAULT_AGENT_NAME) {
   };
 }
 
+// The preset choice: a number from the menu (the last number is "none"), a preset id, a word from
+// its title, or none. `presets` is [{ id, title, for }], passed in rather than read here, because
+// this file is also bundled into the EVÐA app and reads no files. null when the answer names nothing.
+export const START_PLAIN = "None, start plain";
+export function presetKey(answer, presets) {
+  const a = String(answer ?? "").trim().toLowerCase();
+  if (!a || a === "none" || a === "plain" || a === START_PLAIN.toLowerCase()) return "none";
+  if (/^\d+$/.test(a)) {
+    const n = Number(a);
+    if (n === presets.length + 1) return "none";
+    return presets[n - 1]?.id ?? null;
+  }
+  const hit = presets.find((p) => p.id === a || p.title.toLowerCase() === a);
+  return hit ? hit.id : null;
+}
+
 // Ask the setup questions one at a time. `io.ask(prompt)` returns the answer (a promise or a
 // string); `io.out(line)` prints. Only questions whose flag is missing are asked. Returns the
-// answers, including `trainingOff` which is true only after the owner typed yes.
-export async function interview(opts, io) {
+// answers, including `trainingOff` which is true only after the owner typed yes. `presets` is the
+// preset library to offer; with none, the preset question is not asked.
+export async function interview(opts, io, { presets = [] } = {}) {
   const out = io.out;
   const ask = async (q) => oneLine(await io.ask(q));
   out(WELCOME);
@@ -206,6 +336,14 @@ export async function interview(opts, io) {
   const agent = a.agentName || DEFAULT_AGENT_NAME;
   if (!a.owner) a.owner = await ask(`${q("owner", agent)} `);
   if (!a.purpose) a.purpose = await ask(`${q("purpose", agent)} `);
+  if (a.preset == null && presets.length) {
+    out(q("preset", agent));
+    presets.forEach((p, i) => out(`  ${i + 1}. ${p.title}: ${p.for}`));
+    out(`  ${presets.length + 1}. ${START_PLAIN}`);
+    let key = null;
+    while (!key) key = presetKey(await ask("Number or name: "), presets);
+    a.preset = key;
+  }
   if (!a.voice) a.voice = await ask(`${q("voice", agent)} `);
   if (!a.platform) {
     out(q("platform", agent));
@@ -233,6 +371,12 @@ export async function interview(opts, io) {
     }
     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("");