create-evda 0.1.3 → 0.1.5

package/lib/presets.mjs

@@ -0,0 +1,328 @@
+// Presets: ways to organize a record, shipped as a library so an agent picks one instead of making
+// one up. Each is `presets/<id>/preset.json` in this package:
+//
+//   {
+//     "id": "journal",
+//     "title": "Journal",
+//     "for": "One sentence: who it suits.",
+//     "folders": [{ "path": "People", "type": "person", "connectors": ["contacts"], "note": "One file per person." }],
+//     "circles": [{ "name": "family", "public": false, "description": "...", "members": { "people": { "path": "People" } } }],
+//     "routines": ["weekly"]
+//   }
+//
+// `folders` are paths relative to the record root. A folder with a `type` gets folder.evda.json
+// (type, connectors, views), checked by the same validator doctor uses; a folder with no type is a
+// plain directory and nothing more. `circles` are starter circles, in the substrate's eco shape with
+// members by path, and they are only ever PROPOSED: a proposal file under proposals/, never a circle.
+// `routines` name routines lib/routines.mjs already knows, and are offered, never scheduled.
+//
+// Applying a preset only adds. It creates the directories that are missing, writes the manifests
+// that are missing, and reports the rest: a manifest that already says the same thing is skipped,
+// one that says something else is a conflict and is left exactly as it is, and a preset path that
+// already exists as a file is a conflict. Nothing is moved, renamed or deleted, so applying twice
+// writes nothing the second time. A shipped preset that does not validate fails
+// test/presets.test.mjs, so the person running it never meets one.
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { openEvda } from "./manifest.mjs";
+import { resolveRole } from "./roles.mjs";
+import { validateFolderManifest, FOLDER_MANIFEST, FOLDER_TYPES } from "./folders.mjs";
+import { ROUTINE_KEYS } from "./routines.mjs";
+import { onlyKeys, proposeCircle, refuse, PROPOSALS } from "./tools.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const PRESETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "presets");
+export const PRESET_FILE = "preset.json";
+export const PRESET_KEYS = ["id", "title", "for", "folders", "circles", "routines"];
+export const PRESET_FOLDER_KEYS = ["path", "type", "connectors", "views", "note"];
+export const PRESET_CIRCLE_KEYS = ["name", "public", "description", "members"];
+export const NONE = "none";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+const ID = /^[a-z0-9][a-z0-9-]*$/;
+const CIRCLE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+// A preset path: relative, forward slashes, no empty, dot or dot-dot segment, and no segment doctor's
+// walk would skip (a dot-directory or node_modules), because a folder doctor cannot see is a promise
+// nothing checks.
+function pathProblem(p) {
+  if (!nonEmpty(p)) return "must be a non-empty path";
+  if (p.includes("\\")) return "uses a backslash; paths use /";
+  if (p.startsWith("/")) return "is absolute; paths are relative to the record root";
+  for (const seg of p.split("/")) {
+    if (seg === "" || seg === "." || seg === "..") return `has an empty, . or .. segment`;
+    if (seg.startsWith(".") || seg === "node_modules") return `has the segment "${seg}", which doctor does not read`;
+  }
+  return null;
+}
+
+// Validate one preset. Returns a list of problem strings; empty is valid. Stricter than a folder
+// manifest on disk: an unknown key or type in something this package ships is a mistake, not a
+// newer tool's key to preserve.
+export function validatePreset(p, dirName = null) {
+  const problems = [];
+  const fail = (m) => problems.push(`${dirName ?? p?.id ?? "preset"}: ${m}`);
+  if (!isObject(p)) { fail("must hold a JSON object."); return problems; }
+  const unknown = Object.keys(p).filter((k) => !PRESET_KEYS.includes(k));
+  if (unknown.length) fail(`unknown key(s): ${unknown.join(", ")}.`);
+  if (!nonEmpty(p.id) || !ID.test(p.id)) fail(`"id" must be lowercase letters, digits and -, got ${JSON.stringify(p.id)}.`);
+  else if (dirName !== null && p.id !== dirName) fail(`"id" is ${JSON.stringify(p.id)} but the preset lives in ${dirName}/; the directory names it.`);
+  if (!nonEmpty(p.title)) fail(`"title" is missing.`);
+  if (!nonEmpty(p.for)) fail(`"for" is missing: one sentence saying who it suits.`);
+  else if (/\n/.test(p.for)) fail(`"for" is one sentence on one line.`);
+  const paths = new Set();
+  if (!Array.isArray(p.folders) || p.folders.length === 0) fail(`"folders" must be a non-empty list.`);
+  else {
+    p.folders.forEach((f, i) => {
+      const at = `folders[${i}]`;
+      if (!isObject(f)) { fail(`${at} must be { path, type?, connectors?, views?, note? }.`); return; }
+      const extra = Object.keys(f).filter((k) => !PRESET_FOLDER_KEYS.includes(k));
+      if (extra.length) fail(`${at} unknown key(s): ${extra.join(", ")}.`);
+      const bad = pathProblem(f.path);
+      if (bad) { fail(`${at} path ${bad}.`); return; }
+      if (paths.has(f.path)) fail(`${at} path ${f.path} is listed twice.`);
+      paths.add(f.path);
+      if (f.note !== undefined && !nonEmpty(f.note)) fail(`${at} "note" must be a sentence.`);
+      if (f.type === undefined) {
+        if (f.connectors !== undefined || f.views !== undefined) fail(`${at} (${f.path}) has connectors or views and no type. An untyped folder is a plain directory with no manifest to hold them.`);
+        return;
+      }
+      if (!FOLDER_TYPES.includes(f.type)) fail(`${at} (${f.path}) type ${JSON.stringify(f.type)} is not one of ${FOLDER_TYPES.join(", ")}.`);
+      const v = validateFolderManifest(manifestFor(f), `${f.path}/${FOLDER_MANIFEST}`);
+      for (const pr of v.problems) fail(pr.message);
+      for (const view of f.views ?? []) {
+        if (isObject(view) && nonEmpty(view.path) && pathProblem(view.path)) fail(`${at} view "${view.view}" path ${pathProblem(view.path)}.`);
+      }
+    });
+  }
+  if (p.circles !== undefined) {
+    if (!Array.isArray(p.circles)) fail(`"circles" must be a list.`);
+    else {
+      const names = new Set();
+      p.circles.forEach((c, i) => {
+        const at = `circles[${i}]`;
+        if (!isObject(c)) { fail(`${at} must be { name, public, description, members }.`); return; }
+        const extra = Object.keys(c).filter((k) => !PRESET_CIRCLE_KEYS.includes(k));
+        if (extra.length) fail(`${at} unknown key(s): ${extra.join(", ")}.`);
+        if (!nonEmpty(c.name) || !CIRCLE_NAME.test(c.name)) fail(`${at} "name" must be letters, digits, - and _.`);
+        else if (names.has(c.name)) fail(`${at} circle ${c.name} is listed twice.`);
+        else names.add(c.name);
+        if (typeof c.public !== "boolean") fail(`${at} "public" must be true or false.`);
+        if (!nonEmpty(c.description)) fail(`${at} "description" says in plain words who may read it and why.`);
+        if (!isObject(c.members) || Object.keys(c.members).length === 0) { fail(`${at} "members" must name at least one path.`); return; }
+        for (const [name, m] of Object.entries(c.members)) {
+          if (!isObject(m) || Object.keys(m).length !== 1 || !nonEmpty(m.path)) { fail(`${at} member "${name}" must be { path }; a preset circle holds folders this preset makes.`); continue; }
+          if (![...paths].some((fp) => m.path === fp || m.path.startsWith(`${fp}/`))) fail(`${at} member "${name}" path ${m.path} is not a folder this preset makes.`);
+        }
+      });
+    }
+  }
+  if (p.routines !== undefined) {
+    if (!Array.isArray(p.routines)) fail(`"routines" must be a list.`);
+    else {
+      for (const r of p.routines) if (!ROUTINE_KEYS.includes(r)) fail(`routine ${JSON.stringify(r)} is not one this package has (${ROUTINE_KEYS.join(", ")}).`);
+      if (new Set(p.routines).size !== p.routines.length) fail(`"routines" lists one twice.`);
+    }
+  }
+  return problems;
+}
+
+// The folder.evda.json a typed preset folder writes. The same three keys the scaffold writes.
+export function manifestFor(folder) {
+  return { type: folder.type, connectors: folder.connectors ?? [], views: folder.views ?? [] };
+}
+
+// Read one preset from `dir` (the presets directory). Throws when it is missing or does not validate.
+export function loadPreset(id, { dir = PRESETS_DIR } = {}) {
+  if (!nonEmpty(id) || !ID.test(id)) throw new EvdaError(`REFUSED: ${JSON.stringify(id)} is not a preset id. Presets: ${presetIds({ dir }).join(", ")}.`, { code: "NO_PRESET", exit: 2 });
+  const p = join(dir, id, PRESET_FILE);
+  if (!existsSync(p)) throw new EvdaError(`REFUSED: no preset named "${id}". Presets: ${presetIds({ dir }).join(", ")}.`, { code: "NO_PRESET", exit: 2 });
+  let preset;
+  try {
+    preset = JSON.parse(readFileSync(p, "utf8"));
+  } catch (e) {
+    throw new EvdaError(`REFUSED: preset ${id} is not valid JSON (${e.message}).`, { code: "BAD_PRESET", exit: 2 });
+  }
+  const problems = validatePreset(preset, id);
+  if (problems.length) throw new EvdaError(`REFUSED: preset ${id} is malformed: ${problems[0]}`, { code: "BAD_PRESET", exit: 2 });
+  return preset;
+}
+
+export function presetIds({ dir = PRESETS_DIR } = {}) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((n) => !n.startsWith(".") && existsSync(join(dir, n, PRESET_FILE))).sort();
+}
+
+// Every shipped preset, loaded and validated.
+export function listPresets(opts = {}) {
+  return presetIds(opts).map((id) => loadPreset(id, opts));
+}
+
+// What `folder`'s existing manifest lacks against the preset's: a different type, a connector or a
+// view the preset declares and it does not. [] means it already says what the preset says; a
+// connector or view the owner added beyond the preset is theirs and is not a difference.
+function differences(existing, want) {
+  const out = [];
+  if (!isObject(existing)) return ["it does not hold a JSON object"];
+  if (existing.type !== want.type) out.push(`its type is ${JSON.stringify(existing.type)}, the preset's is "${want.type}"`);
+  const has = Array.isArray(existing.connectors) ? existing.connectors : [];
+  const missing = want.connectors.filter((c) => !has.includes(c));
+  if (missing.length) out.push(`it does not declare connector(s) ${missing.join(", ")}`);
+  const views = Array.isArray(existing.views) ? existing.views.map((v) => v?.view) : [];
+  const noView = want.views.filter((v) => !views.includes(v.view)).map((v) => v.view);
+  if (noView.length) out.push(`it does not declare view(s) ${noView.join(", ")}`);
+  return out;
+}
+
+// The first segment of `rel` that exists and is not a directory, or null.
+function blockedBy(root, rel) {
+  const segs = rel.split("/");
+  for (let i = 1; i <= segs.length; i++) {
+    const sub = segs.slice(0, i).join("/");
+    const abs = join(root, sub);
+    let st;
+    try { st = lstatSync(abs); } catch { return null; }
+    if (st.isSymbolicLink()) { try { st = statSync(abs); } catch { return sub; } }
+    if (!st.isDirectory()) return sub;
+  }
+  return null;
+}
+
+const viewHeader = (v) => ["---", `view: ${v.view}`, `of: ${v.of}`, `in: ${v.in}`, "---", ""].join("\n");
+
+// The plan for applying preset `id` to the record at `root`, and with `dry: false` the writes.
+//   create     directories that do not exist yet
+//   write      manifests that do not exist yet ({ path, folder, manifest })
+//   views      view files a manifest declares that do not exist yet
+//   matched    manifests that exist and already say what the preset says (skipped)
+//   conflicts  manifests that exist and say something else, and preset paths that are files
+//              ({ path, why }); reported, never overwritten
+//   circles    preset circles with no circle and no proposal yet, proposed on apply
+//   routines   routines the preset suggests, offered and never scheduled
+export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRESETS_DIR } = {}) {
+  const evda = openEvda(resolve(root));
+  const preset = loadPreset(id, { dir });
+  const plan = { id: preset.id, title: preset.title, root: evda.dir, dry, create: [], write: [], views: [], matched: [], conflicts: [], circles: [], proposed: [], routines: preset.routines ?? [], folders: preset.folders.length };
+  const blocked = new Set();
+  for (const f of preset.folders) {
+    const abs = resolve(evda.dir, f.path);
+    if (!abs.startsWith(evda.dir + sep)) { plan.conflicts.push({ path: f.path, why: "resolves outside the record" }); continue; }
+    const file = blockedBy(evda.dir, f.path);
+    if (file) {
+      if (!blocked.has(file)) plan.conflicts.push({ path: file, why: `exists as a file, so the folder ${f.path} cannot be made there` });
+      blocked.add(file);
+      continue;
+    }
+    if (!existsSync(abs) && !plan.create.includes(f.path)) plan.create.push(f.path);
+    if (f.type === undefined) continue;
+    const want = manifestFor(f);
+    const mpath = `${f.path}/${FOLDER_MANIFEST}`;
+    const mabs = join(abs, FOLDER_MANIFEST);
+    if (!existsSync(mabs)) plan.write.push({ path: mpath, folder: f, manifest: want });
+    else if (!lstatSync(mabs).isFile()) plan.conflicts.push({ path: mpath, why: "exists and is not a file" });
+    else {
+      let existing;
+      try { existing = JSON.parse(readFileSync(mabs, "utf8")); } catch { plan.conflicts.push({ path: mpath, why: "exists and is not valid JSON" }); continue; }
+      const diff = differences(existing, want);
+      if (diff.length) plan.conflicts.push({ path: mpath, why: `exists and differs: ${diff.join("; ")}` });
+      else plan.matched.push({ path: mpath });
+    }
+    for (const v of want.views) {
+      if (!existsSync(resolve(evda.dir, v.path))) plan.views.push({ path: v.path, view: v });
+    }
+  }
+  const circlesRole = resolveRole(evda, "circles");
+  const proposals = join(evda.dir, PROPOSALS);
+  const proposalNames = existsSync(proposals) ? readdirSync(proposals) : [];
+  for (const c of preset.circles ?? []) {
+    const exists = circlesRole.mapped && existsSync(join(circlesRole.abs, c.name));
+    const proposed = proposalNames.some((n) => new RegExp(`^\\d{4}-\\d{2}-\\d{2}-circle-${c.name}(-\\d+)?\\.md$`).test(n));
+    if (!exists && !proposed) plan.circles.push(c);
+  }
+  if (dry) return plan;
+
+  for (const rel of plan.create) mkdirSync(join(evda.dir, rel), { recursive: true });
+  for (const w of plan.write) writeFileSync(join(evda.dir, w.path), JSON.stringify(w.manifest, null, 2) + "\n", { flag: "wx" });
+  for (const v of plan.views) {
+    mkdirSync(dirname(resolve(evda.dir, v.path)), { recursive: true });
+    writeFileSync(resolve(evda.dir, v.path), viewHeader(v.view), { flag: "wx" });
+  }
+  for (const c of plan.circles) {
+    const r = proposeCircle(evda, {
+      name: c.name,
+      who: c.public ? "Anyone." : "Only the people the owner grants it to, by name.",
+      what: Object.values(c.members).map((m) => m.path).join(", "),
+      why: `${c.description} Suggested by the ${preset.title} preset.`,
+    }, { now });
+    plan.proposed.push(r.path);
+  }
+  return plan;
+}
+
+// What preset `id` has that the record at `root` does not: the dry-run plan, which by construction
+// holds only additions and conflicts. This is how an agent proposes one folder from the library later.
+export function diffPreset(root, id, opts = {}) {
+  return applyPreset(root, id, { ...opts, dry: true });
+}
+
+export const planIsEmpty = (plan) => !plan.create.length && !plan.write.length && !plan.views.length && !plan.circles.length && !plan.conflicts.length;
+
+// The plan in plain words, for the owner to say yes or no to. Names each folder by its note.
+export function summary(plan, preset = loadPreset(plan.id)) {
+  const lines = [];
+  const adds = preset.folders.filter((f) => plan.create.includes(f.path) || plan.write.some((w) => w.folder.path === f.path));
+  if (!adds.length && !plan.circles.length && !plan.conflicts.length) {
+    lines.push(`This record already has everything the ${plan.title} preset makes. Nothing would be written.`);
+  } else {
+    lines.push(`The ${plan.title} preset would add ${adds.length} folder(s) to this record:`);
+    for (const f of adds) lines.push(`- ${f.path}/${f.type ? ` (${f.type})` : ""}${f.note ? `: ${f.note}` : ""}`);
+    if (plan.circles.length) lines.push(`It would propose ${plan.circles.length} circle(s), as proposal files only: ${plan.circles.map((c) => c.name).join(", ")}.`);
+    if (plan.matched.length) lines.push(`${plan.matched.length} folder(s) are already set up the same way and would be left alone.`);
+    for (const c of plan.conflicts) lines.push(`Left as it is: ${c.path} ${c.why}.`);
+    lines.push("Nothing is moved, renamed or deleted. It is applied only when the owner says yes.");
+  }
+  if (plan.routines.length) lines.push(`It suits the ${plan.routines.join(" and ")} routine(s), offered separately and never scheduled without a yes.`);
+  return lines.join("\n");
+}
+
+// Plan lines for the CLI, in the package's CHECKED / SKIPPED convention.
+export function planLines(plan, { diff = false } = {}) {
+  const out = [];
+  const verb = plan.dry || diff ? "would" : "did";
+  for (const p of plan.create) out.push(`  ${verb === "did" ? "created " : "create  "} ${p}/`);
+  for (const w of plan.write) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${w.path}  type ${w.manifest.type}${w.manifest.connectors.length ? `, connectors ${w.manifest.connectors.join(", ")}` : ""}`);
+  for (const v of plan.views) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${v.path}  view ${v.view.view} (header only)`);
+  if (!diff) for (const m of plan.matched) out.push(`  skipped  ${m.path}  already says the same`);
+  for (const c of plan.conflicts) out.push(`  CONFLICT ${c.path}  ${c.why}. Left as it is.`);
+  if (plan.proposed.length) for (const p of plan.proposed) out.push(`  proposed ${p}  (a proposal file; no circle was created)`);
+  else for (const c of plan.circles) out.push(`  propose  circle ${c.name}  (a proposal file only)`);
+  for (const r of plan.routines) out.push(`  offer    routine ${r}: evda routine ${r}  (nothing is scheduled without a yes)`);
+  return out;
+}
+
+// The MCP tools. Each takes the open record and its arguments, and refuses an argument it does not take.
+
+export function presetsTool(evda, args = {}) {
+  onlyKeys("evda_presets", args, ["id"]);
+  if (args.id === undefined) return { presets: listPresets().map((p) => ({ id: p.id, title: p.title, for: p.for, folders: p.folders.length })) };
+  return { preset: loadPreset(args.id) };
+}
+
+export function proposeStructureTool(evda, args = {}) {
+  onlyKeys("evda_propose_structure", args, ["id"], "It only proposes. Applying a preset is evda_apply_preset, after the owner says yes.");
+  if (!nonEmpty(args.id)) throw refuse(`evda_propose_structure needs "id", a preset from evda_presets.`, "NO_PRESET");
+  const plan = applyPreset(evda.dir, args.id, { dry: true });
+  return { plan, summary: summary(plan) };
+}
+
+export function applyPresetTool(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_apply_preset", args, ["id", "confirmed"], "It adds the preset's folders and manifests and nothing else; it never moves, renames or deletes.");
+  if (!nonEmpty(args.id)) throw refuse(`evda_apply_preset needs "id", a preset from evda_presets.`, "NO_PRESET");
+  if (args.confirmed !== true) throw refuse(`evda_apply_preset needs "confirmed": true, and that is true only when the owner said yes to this preset in this conversation. Show them evda_propose_structure first and wait.`, "NOT_CONFIRMED");
+  loadPreset(args.id);
+  const plan = applyPreset(evda.dir, args.id, { now });
+  return { plan, lines: planLines(plan) };
+}

package/lib/routines.mjs

@@ -0,0 +1,143 @@
+// Starter routines: a morning organize and a weekly look back, each optional, each scheduled only on
+// the owner's 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).
+// It is created in the app, so `evda routine` prints exactly what to put in it. A cloud routine
+// (`/schedule`) runs on a fresh clone with no access to local files, so it cannot reach a record.
+//
+// The fallback is launchd on a Mac: a job that runs `evda organize --with-ai` (or `look-back`) on a
+// 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 { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { openEvda, holderOf } from "./manifest.mjs";
+import { serverCommand } from "./connect.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const ROUTINES = {
+  morning: {
+    id: "evda-morning-organize",
+    title: "EVÐA morning organize",
+    when: "Daily at 8:00",
+    calendar: { Hour: 8, Minute: 0 },
+    command: ["organize", "--with-ai"],
+    does: "files new captures into their day and writes a report of what belongs where. Moves nothing.",
+  },
+  weekly: {
+    id: "evda-weekly-look-back",
+    title: "EVÐA weekly look back",
+    when: "Weekly on Sunday at 18:00",
+    calendar: { Weekday: 0, Hour: 18, Minute: 0 },
+    command: ["look-back"],
+    does: "reads the week back to you in a report: what recurred in your words and what changed. No scores.",
+  },
+};
+export const ROUTINE_KEYS = Object.keys(ROUTINES);
+
+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.
+export function routineCommand(key, dir) {
+  const r = ROUTINES[key];
+  const { command, args } = serverCommand(dir);
+  // serverCommand ends in `mcp <dir>`; a routine swaps that for its own command.
+  const base = [command, ...args.slice(0, -2)];
+  return [...base, r.command[0], resolve(dir), ...r.command.slice(1)].map(q).join(" ");
+}
+
+export function desktopInstructions(key, dir) {
+  const r = ROUTINES[key];
+  return [
+    `${r.title}: ${r.does}`,
+    "",
+    "In the Claude desktop app: open the Code tab, then Routines, then New routine, and choose Local.",
+    `  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:",
+    `                ${routineCommand(key, dir)}`,
+    "",
+    "A local routine runs while the app is open and the computer is awake.",
+  ].join("\n");
+}
+
+export function label(key, evda) {
+  const id = (holderOf(evda).id ?? "record").replace(/[^A-Za-z0-9.-]+/g, "-");
+  return `io.evda.${ROUTINES[key].id}.${id}`;
+}
+
+const xml = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+export function launchdPlist(key, dir, { home = homedir() } = {}) {
+  const evda = openEvda(dir);
+  const r = ROUTINES[key];
+  const log = join(home, "Library", "Logs", "evda", `${r.id}.log`);
+  const cal = Object.entries(r.calendar).map(([k, v]) => `      <key>${k}</key><integer>${v}</integer>`).join("\n");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    `  <key>Label</key><string>${xml(label(key, evda))}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    "    <string>/bin/zsh</string>",
+    "    <string>-lc</string>",
+    `    <string>${xml(routineCommand(key, dir))}</string>`,
+    "  </array>",
+    "  <key>StartCalendarInterval</key>",
+    "  <dict>",
+    cal,
+    "  </dict>",
+    `  <key>StandardOutPath</key><string>${xml(log)}</string>`,
+    `  <key>StandardErrorPath</key><string>${xml(log)}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].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 });
+  const evda = openEvda(dir);
+  const plist = launchdPlist(key, dir, { home });
+  mkdirSync(agentsDir, { recursive: true });
+  mkdirSync(join(home, "Library", "Logs", "evda"), { recursive: true });
+  const path = join(agentsDir, `${label(key, evda)}.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" });
+    loaded = r.status === 0 ? "loaded" : `launchctl bootstrap exited ${r.status}: ${(r.stderr ?? "").trim()}`;
+  }
+  return { path, existed, loaded };
+}
+
+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 });
+  const { dir, flags } = pickDir(args.slice(1));
+  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)}`);
+    return 0;
+  }
+  if (flags.includes("--launchd")) {
+    process.stdout.write(launchdPlist(key, dir));
+    return 0;
+  }
+  console.log(desktopInstructions(key, dir));
+  console.log("");
+  console.log(`Or on a Mac without the app open: evda routine ${key} ${resolve(dir)} --install (launchd, runs ${ROUTINES[key].when.toLowerCase()}).`);
+  console.log("A scheduled job cannot read a record inside Documents, Desktop, Downloads or iCloud Drive unless the shell has Full Disk Access.");
+  return 0;
+}

package/lib/setup.mjs

@@ -166,22 +166,75 @@ export const WELCOME = [
   "The only requirement is that you want to, and you are open to it. Iris is the default name; call it whatever you like.",
 ].join("\n");
 
+// The setup questions, in the order they are asked. The terminal interview and the EVÐA app both
+// read them from here, so the two surfaces cannot ask different things. `agent` is the name the
+// owner chose on the first question.
+export function questions(agent = DEFAULT_AGENT_NAME) {
+  return [
+    { 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: "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: "weekly", text: "Add a weekly look back routine, which reads your week back to you?" },
+  ];
+}
+
+// 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 {
+    intro: "Paste this into a new chat with ChatGPT, Claude, or whatever AI you already talk to:",
+    after: `Bring its answer to your first session with ${agent}. ${agent} files it as an import: what that AI said, not your own words, and a claim to check over time rather than a fact.`,
+  };
+}
+
+// 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);
   out("");
   const a = { ...opts };
-  if (a.agentName == null) a.agentName = (await ask(`What would you like to call your agent? (${DEFAULT_AGENT_NAME}) `)) || DEFAULT_AGENT_NAME;
+  const q = (key, agent) => questions(agent).find((x) => x.key === key).text;
+  if (a.agentName == null) a.agentName = (await ask(`${q("agentName")} `)) || DEFAULT_AGENT_NAME;
   const agent = a.agentName || DEFAULT_AGENT_NAME;
-  if (!a.owner) a.owner = await ask("What is your name? ");
-  if (!a.purpose) a.purpose = await ask(`What do you want ${agent} for? Say it however it comes out. `);
-  if (!a.voice) a.voice = await ask(`How do you want ${agent} to talk to you? `);
+  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("Which AI will you use it with?");
+    out(q("platform", agent));
     PLATFORM_KEYS.forEach((k, i) => out(`  ${i + 1}. ${PLATFORMS[k].label}`));
     let key = null;
     let raw = "";
@@ -195,7 +248,7 @@ export async function interview(opts, io) {
   const p = PLATFORMS[a.platform];
   if (!a.trainingOff) {
     out("");
-    out("Before anything personal goes in, turn model training off:");
+    out(q("trainingOff", agent));
     for (const line of p.training) out(`  ${line}`);
     if (p.url) out(`  ${p.url}`);
     let yes = false;
@@ -209,14 +262,26 @@ export async function interview(opts, io) {
   out("");
   out(DICTATION);
   out("");
-  const bring = (await ask("Bring in what your AI already knows about you? (yes/no) ")).toLowerCase();
+  const bring = (await ask(`${q("import", agent)} (yes/no) `)).toLowerCase();
   if (bring === "yes" || bring === "y") {
+    const lines = importLines(agent);
     out("");
-    out("Paste this into a new chat with ChatGPT, Claude, or whatever AI you already talk to:");
+    out(lines.intro);
     out("");
     out(`  ${IMPORT_PROMPT}`);
     out("");
-    out(`Bring its answer to your first session with ${agent}. ${agent} files it as an import: what that AI said, not your own words, and a claim to check over time rather than a fact.`);
+    out(lines.after);
+  }
+  const yes = async (key) => ["yes", "y"].includes((await ask(`${q(key, agent)} (yes/no) `)).toLowerCase());
+  if (a.skill == null) {
+    out("");
+    a.skill = await yes("skill");
+  }
+  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);
   }
   return a;
 }