create-evda 0.1.5 → 0.1.6

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.",
@@ -178,6 +280,7 @@ 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?" },
@@ -185,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 {
@@ -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("");

package/lib/skills.mjs

@@ -0,0 +1,266 @@
+// Skills the agent writes for itself (HQ-1377): a process it found itself repeating, written down
+// once so the next run follows it instead of rediscovering it.
+//
+// A skill lives in the record at `.claude/skills/<name>/SKILL.md`, the Anthropic skill format (a
+// `name` and a `description` saying when to use it, in frontmatter, then the steps). Claude Code
+// loads that folder on its own when a session opens in the record; every other app reads the same
+// files through the MCP server's evda_skills tool. The folder is a dot folder, so it is never a
+// record entry, yet it syncs with the record, so a skill travels to every device the record does.
+//
+// Two refusals, each with a test in test/skills.test.mjs:
+//   1. Nothing outside `.claude/skills/<name>/`. The tool takes a name, never a path, and a name
+//      that is not kebab-case (which is how `..` and `/` would get in) is refused.
+//   2. Nothing that is a rule about the owner's life. A skill is how the agent works. A threshold,
+//      count or streak about a person is never a skill, whoever asks (Mike, 2026-09-16: the mean is
+//      relative to the person, and a rule with a number in it about their life is the wrong shape).
+//
+// Revising: a skill that went wrong on a run is rewritten with revise: true and what went wrong; the
+// previous text is appended to REVISIONS.md beside it, so a revision never loses what it replaced.
+//
+// EVDA_SKILLS_FALSIFY=<mode,...>, for the tests: outside skips the path check, owner-rules skips the
+// life-rule check, frontmatter makes doctor accept any frontmatter, no-hint turns the repeated-
+// process line in the MCP server off.
+
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { frontmatterOf } from "./circles.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const SKILLS_REL = ".claude/skills";
+export const SKILL_FILE = "SKILL.md";
+export const REVISIONS_FILE = "REVISIONS.md";
+export const NAME_MAX = 64;
+export const DESCRIPTION_MAX = 1024;
+export const SKILLS_FALSIFY_MODES = ["outside", "owner-rules", "frontmatter", "no-hint"];
+export const skillsFalsified = (mode, env = process.env) => (env.EVDA_SKILLS_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const STEP = /^\s*(?:\d+[.)]|[-*])\s+\S/m;
+const SAYS_WHEN = /\b(?:use|when|whenever|before|after)\b/i;
+
+const pad = (n) => String(n).padStart(2, "0");
+const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+
+function refuse(message, code) {
+  return new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+}
+
+// ---- what counts as a rule about the owner's life ----
+
+// Words that point at the owner rather than at the agent. "you" is left out on purpose: a skill
+// talks to the agent as "you".
+const OWNER_WORDS = /\b(?:the owner|owner's|they|them|their|theirs|he|him|his|she|her|hers)\b/i;
+// A quota over a period with a unit of living: "8 hours a night", "3 drinks per week".
+const QUOTA = /\b\d+(?:\.\d+)?\s*(?:x\s*)?(?:times?|hours?|hrs?|minutes?|mins?|days?|nights?|drinks?|cups?|glasses|meals?|snacks?|calories|kcal|steps|grams?|g|kg|lbs?|pounds|reps?|sets|miles|km|servings?|pages|sessions?|workouts?)\s+(?:a|an|per|each|every)\s+(?:day|week|month|night|morning|evening|weekend)\b/i;
+// A streak is the word itself, or a run counted in days: "five days in a row", "consecutive nights".
+// "twice in a row" about a correction is how the agent notices a process, and is not one.
+const STREAK = /\bstreaks?\b|\bchain unbroken\b|\b(?:days?|nights?|weeks?|mornings?)\s+(?:in a row|straight)\b|\bconsecutive\s+(?:days?|nights?|weeks?|mornings?)\b/i;
+const EVERY = /\b(?:every|each)\s+(?:single\s+)?(?:day|night|morning|evening|week)\b|\bdaily\b|\bnightly\b/i;
+const MUST = /\b(?:must|should|has to|have to|needs? to|required|make sure|never miss|no exceptions)\b/i;
+const THRESHOLD = /\b(?:at least|at most|no more than|fewer than|less than|more than|under|over|up to|max(?:imum)?|min(?:imum)?|limit(?:ed)? (?:to|of)|cap(?:ped)? at|target of|goal of|quota of)\s+\$?\d/i;
+const LIFE = /\b(?:sleep|slept|bed|bedtime|wake|woke|eat|ate|eating|food|meals?|snacks?|drink|drinks|drinking|alcohol|sugar|calories|carbs|protein|weight|weigh|exercise|workouts?|gym|run|running|steps|screen time|phone|scroll|spend|spent|spending|money|budget|meditat\w*|water|caffeine|coffee|study|studied|read|journal\w*|smok\w*|vap\w*|weed|thc|sex|porn|social media)\b/i;
+
+// The line and the reason when a text reads as a rule about the owner's life, or null.
+export function ownerRule(text, { owner = "", env = process.env } = {}) {
+  if (skillsFalsified("owner-rules", env)) return null;
+  const first = String(owner ?? "").trim().split(/\s+/)[0] ?? "";
+  const named = first.length >= 2 ? new RegExp(`\\b${first.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i") : null;
+  const lines = String(text).split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    const aboutOwner = OWNER_WORDS.test(l) || (named ? named.test(l) : false);
+    let why = null;
+    if (QUOTA.test(l)) why = "a quota over a period";
+    else if (aboutOwner && STREAK.test(l)) why = "a streak";
+    else if (aboutOwner && EVERY.test(l) && MUST.test(l)) why = "something they must do every day";
+    else if (aboutOwner && THRESHOLD.test(l) && LIFE.test(l)) why = "a threshold on how they live";
+    if (why) return { line: i + 1, text: l.trim(), why };
+  }
+  return null;
+}
+
+// ---- reading and checking ----
+
+// The record's skills folder, absolute, or null when it would resolve outside the record (a
+// symlinked .claude pointing elsewhere). Existence is not required.
+export function skillsDir(evda) {
+  const abs = join(evda.dir, SKILLS_REL);
+  if (skillsFalsified("outside")) return abs;
+  let p = evda.dir;
+  for (const part of SKILLS_REL.split("/")) {
+    p = join(p, part);
+    if (!existsSync(p)) break;
+    if (lstatSync(p).isSymbolicLink()) {
+      const real = realpathSync(p);
+      const root = realpathSync(evda.dir);
+      if (real !== root && !real.startsWith(root + sep)) return null;
+    }
+  }
+  return abs;
+}
+
+// The problems with one skill's text, as sentences, and what it parsed to. `folder` is the name of
+// the directory it sits in, which the frontmatter name must match.
+export function checkSkill(text, { folder = null, owner = "", env = process.env } = {}) {
+  const problems = [];
+  const warnings = [];
+  // What the skill format requires (a parseable name and description) fails; what makes a skill
+  // useful (it says when, it has steps) is required of one the agent writes, and only warned about
+  // in one written by hand, which may be prose (Mike's vault skills are, and they load fine).
+  const advisories = [];
+  const front = frontmatterOf(text);
+  const loose = skillsFalsified("frontmatter", env);
+  const name = front?.name;
+  const description = front?.description;
+  if (!loose) {
+    if (!front) problems.push(`has no frontmatter: it starts with a --- block holding name and description.`);
+    else {
+      if (typeof name !== "string" || !KEBAB.test(name)) problems.push(`name ${JSON.stringify(name ?? null)} is not kebab-case (lowercase letters, digits and single hyphens).`);
+      else if (name.length > NAME_MAX) problems.push(`name is ${name.length} characters; at most ${NAME_MAX}.`);
+      else if (folder !== null && name !== folder) problems.push(`name ${JSON.stringify(name)} differs from its folder ${JSON.stringify(folder)}.`);
+      if (typeof description !== "string" || description.trim() === "") problems.push(`has no description. The description is what tells an agent when to use it.`);
+      else if (description.length > DESCRIPTION_MAX) problems.push(`description is ${description.length} characters; at most ${DESCRIPTION_MAX}.`);
+      else if (!SAYS_WHEN.test(description)) advisories.push(`description does not say when to use it (no "use", "when", "before" or "after" in it).`);
+    }
+    const body = bodyOf(text);
+    if (!STEP.test(body)) advisories.push(`has no steps: the body holds no numbered or bulleted step.`);
+  }
+  const rule = ownerRule(bodyOf(text) + "\n" + (typeof description === "string" ? description : ""), { owner, env });
+  if (rule) warnings.push(`line ${rule.line} reads as a rule about the owner's life (${rule.why}): "${rule.text}". A skill is how the agent works, never a threshold, count or streak about a person.`);
+  return { name: typeof name === "string" ? name : folder, description: typeof description === "string" ? description : null, problems, advisories, warnings: [...advisories, ...warnings] };
+}
+
+function bodyOf(text) {
+  const lines = String(text).split("\n");
+  if (lines[0] !== "---") return text;
+  const end = lines.indexOf("---", 1);
+  return end === -1 ? text : lines.slice(end + 1).join("\n");
+}
+
+// Every skill in the record, sorted by folder name: { name, folder, path, description, problems,
+// warnings }. A folder with no SKILL.md is reported as a problem, not skipped.
+export function listSkills(evda, { env = process.env } = {}) {
+  const dir = skillsDir(evda);
+  if (dir === null) return { dir: SKILLS_REL, outside: true, skills: [] };
+  if (!existsSync(dir)) return { dir: SKILLS_REL, skills: [] };
+  const owner = evda.manifest?.owner?.name ?? "";
+  const skills = [];
+  for (const folder of readdirSync(dir).sort()) {
+    if (folder.startsWith(".")) continue;
+    const abs = join(dir, folder);
+    if (!lstatSync(abs).isDirectory()) continue;
+    const path = `${SKILLS_REL}/${folder}/${SKILL_FILE}`;
+    const file = join(abs, SKILL_FILE);
+    if (!existsSync(file)) { skills.push({ name: folder, folder, path, description: null, problems: [`${folder}/ holds no ${SKILL_FILE}.`], advisories: [], warnings: [] }); continue; }
+    const r = checkSkill(readFileSync(file, "utf8"), { folder, owner, env });
+    skills.push({ folder, path, ...r });
+  }
+  return { dir: SKILLS_REL, skills };
+}
+
+// One skill's whole text by name.
+export function getSkill(evda, name) {
+  if (typeof name !== "string" || !KEBAB.test(name)) throw new EvdaError(`REFUSED: evda_skills: ${JSON.stringify(name ?? null)} is not a skill name (kebab-case), so it names nothing in ${SKILLS_REL}.`, { code: "BAD_SKILL_NAME", exit: 2 });
+  const dir = skillsDir(evda);
+  const file = dir && join(dir, name, SKILL_FILE);
+  if (!file || !existsSync(file)) {
+    const have = listSkills(evda).skills.map((s) => s.folder);
+    throw new EvdaError(`No skill named ${JSON.stringify(name)} in ${SKILLS_REL}. ${have.length ? `There are: ${have.join(", ")}.` : "There are none yet."}`, { code: "NO_SKILL", exit: 2 });
+  }
+  return { name, path: `${SKILLS_REL}/${name}/${SKILL_FILE}`, text: readFileSync(file, "utf8") };
+}
+
+// ---- writing ----
+
+const yamlString = (s) => (/^[\w(][^:#\n]*$/.test(s) && !/^(?:true|false|null|yes|no|~)$/i.test(s) && !/\s$/.test(s) ? s : JSON.stringify(s));
+const titleOf = (name) => name.split("-").map((w, i) => (i === 0 ? w[0].toUpperCase() + w.slice(1) : w)).join(" ");
+
+export function renderSkill({ name, description, steps }) {
+  return `---\nname: ${name}\ndescription: ${yamlString(description.replace(/\s*\n\s*/g, " ").trim())}\n---\n\n# ${titleOf(name)}\n\n${steps.trim()}\n`;
+}
+
+// Write a new skill, or revise one with revise: true and `why` (what went wrong on the run).
+export function writeSkill(evda, args = {}, { now = new Date(), env = process.env } = {}) {
+  const allowed = ["name", "description", "steps", "revise", "why"];
+  const extra = Object.keys(args).filter((k) => !allowed.includes(k));
+  if (extra.length) throw refuse(`evda_write_skill does not take ${extra.map((k) => JSON.stringify(k)).join(", ")}. It takes a name, never a path: a skill is always ${SKILLS_REL}/<name>/${SKILL_FILE}.`, "UNKNOWN_ARGUMENT");
+  const { name, description, steps } = args;
+  if (typeof name !== "string" || !KEBAB.test(name) || name.length > NAME_MAX) {
+    if (!(skillsFalsified("outside", env) && typeof name === "string" && name)) {
+      throw refuse(`evda_write_skill: the name ${JSON.stringify(name ?? null)} is not kebab-case of at most ${NAME_MAX} characters, so it could land outside ${SKILLS_REL}/. A skill is only ever written at ${SKILLS_REL}/<name>/${SKILL_FILE}.`, "OUTSIDE_SKILLS");
+    }
+  }
+  if (typeof description !== "string" || description.trim() === "") throw refuse(`evda_write_skill needs "description": when to use it, starting "Use when".`, "NO_DESCRIPTION");
+  if (typeof steps !== "string" || steps.trim() === "") throw refuse(`evda_write_skill needs "steps": the steps, one numbered line each.`, "NO_STEPS");
+  const dir = skillsDir(evda);
+  if (dir === null) throw refuse(`${SKILLS_REL} resolves outside the record (a symlink), so no skill is written there.`, "OUTSIDE_SKILLS");
+  const folder = resolve(dir, name);
+  if (!skillsFalsified("outside", env) && !folder.startsWith(dir + sep)) throw refuse(`${name} resolves outside ${SKILLS_REL}/.`, "OUTSIDE_SKILLS");
+  const text = renderSkill({ name, description, steps });
+  const check = checkSkill(text, { folder: skillsFalsified("outside", env) ? null : name, env });
+  const bad = [...check.problems, ...check.advisories];
+  if (bad.length) throw refuse(`evda_write_skill: the skill ${bad.join(" ")}`, "BAD_SKILL");
+  const rule = ownerRule(`${description}\n${steps}`, { owner: evda.manifest?.owner?.name ?? "", env });
+  if (rule) throw refuse(`evda_write_skill: line ${rule.line} reads as a rule about the owner's life (${rule.why}): "${rule.text}". A skill is how you work (the steps of a process you repeat), never a threshold, count or streak about a person. Write the process without it.`, "OWNER_RULE");
+  const file = join(folder, SKILL_FILE);
+  const rel = `${SKILLS_REL}/${name}/${SKILL_FILE}`;
+  const exists = existsSync(file);
+  if (exists && args.revise !== true) throw refuse(`a skill named ${name} already exists at ${rel}. To change it after a run went wrong, pass revise: true and "why", what went wrong; read it first with evda_skills.`, "SKILL_EXISTS");
+  if (!exists && args.revise === true) throw refuse(`there is no skill named ${name} to revise. Write it without revise.`, "NO_SKILL");
+  if (args.revise === true && (typeof args.why !== "string" || args.why.trim() === "")) throw refuse(`a revision needs "why": what went wrong on the run that made it need one.`, "NO_WHY");
+  mkdirSync(folder, { recursive: true });
+  let revisions = null;
+  if (exists) {
+    const before = readFileSync(file, "utf8");
+    if (before === text) return { path: rel, action: "unchanged", name };
+    revisions = `${SKILLS_REL}/${name}/${REVISIONS_FILE}`;
+    const head = existsSync(join(folder, REVISIONS_FILE)) ? "" : `# Revisions of ${name}\n\nWhat each revision replaced, and why. Newest last.\n`;
+    appendFileSync(join(folder, REVISIONS_FILE), `${head}\n## ${localDate(now)}\n\n${args.why.trim()}\n\nThe text it replaced:\n\n\`\`\`\`markdown\n${before.trimEnd()}\n\`\`\`\`\n`);
+  }
+  writeFileSync(file, text);
+  return { path: rel, action: exists ? "revised" : "written", name, revisions };
+}
+
+// ---- noticing a repeated process ----
+
+// Tools that are how a session starts or keeps itself, never a step of a process the owner asked
+// for. And the plain read-and-file loop: search, read, write is the record's ordinary use, not a
+// process worth a skill, so a run made only of those is never pointed at.
+const META = new Set(["evda_operating_layer", "evda_skills", "evda_write_skill", "evda_check_update"]);
+const ORDINARY = new Set(["evda_recent", "evda_search", "evda_read", "evda_write", "evda_note", "evda_circles", "evda_presets"]);
+export const MIN_STEPS = 3;
+export const MAX_STEPS = 8;
+
+// Given the session's step list (tool names, oldest first) after a call, the repeated run it now
+// ends with, as a list of tool names, or null. A run is MIN_STEPS to MAX_STEPS calls long, holds at
+// least two different tools and one that is not ordinary, and ran before, ending before this one
+// started. The longest such run wins.
+export function repeatedRun(steps) {
+  const s = steps.filter((n) => !META.has(n));
+  const n = s.length;
+  for (let len = Math.min(MAX_STEPS, Math.floor(n / 2)); len >= MIN_STEPS; len--) {
+    const tail = s.slice(n - len);
+    if (new Set(tail).size < 2 || tail.every((t) => ORDINARY.has(t))) continue;
+    for (let start = n - 2 * len; start >= 0; start--) {
+      if (tail.every((t, i) => s[start + i] === t)) return tail;
+    }
+  }
+  return null;
+}
+
+export function repeatHint(run) {
+  return `These steps have now run twice in this conversation: ${run.join(", ")}. If that is one process, write it down once as a skill with evda_write_skill (a kebab-case name, a description saying when to use it, the steps), and tell the owner in one line that you did. If it is not a process, ignore this.`;
+}
+
+// Count one call for the hint. At most one hint per distinct run per session; never with no-hint.
+export function noticeRepeat(session, name, { env = process.env } = {}) {
+  (session.steps ??= []).push(name);
+  (session.hinted ??= new Set());
+  if (skillsFalsified("no-hint", env)) return null;
+  const run = repeatedRun(session.steps);
+  if (!run) return null;
+  const key = run.join(">");
+  if (session.hinted.has(key)) return null;
+  session.hinted.add(key);
+  return repeatHint(run);
+}