@ghostpaw/affinity 0.4.0 → 0.5.0

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { readFileSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { isSea } from 'node:sea';
 import { Writable } from 'node:stream';
 
 var __defProp = Object.defineProperty;
@@ -23,7 +24,122 @@ var __export = (target, all) => {
 var affinityVersion;
 var init_version = __esm({
   "src/version.ts"() {
-    affinityVersion = "0.4.0";
+    affinityVersion = "0.5.0";
+  }
+});
+function parseCliArgs(argv, spec) {
+  const values = {};
+  const positions = [];
+  const flags = spec.flags ?? [];
+  const convert = (raw, arg) => {
+    let value = raw;
+    if (raw.startsWith("@")) {
+      try {
+        value = readFileSync(raw.slice(1), "utf8");
+      } catch {
+        throw new CliUsageError(`Cannot read value file: ${raw.slice(1)}`);
+      }
+    }
+    let result = value;
+    if (arg.type === "number" || arg.type === "integer") {
+      result = Number(value);
+      if (!value.trim() || !Number.isFinite(result) || arg.type === "integer" && !Number.isInteger(result))
+        throw new CliUsageError(
+          `Expected ${arg.type} for ${arg.name}: ${value}`
+        );
+    } else if (arg.type === "boolean") {
+      if (!["true", "false"].includes(value))
+        throw new CliUsageError(`Expected boolean for ${arg.name}`);
+      result = value === "true";
+    } else if (arg.type === "json") {
+      try {
+        result = JSON.parse(value);
+      } catch {
+        throw new CliUsageError(`Invalid JSON for ${arg.name}`);
+      }
+    }
+    if (arg.enum && !arg.enum.includes(result))
+      throw new CliUsageError(
+        `${arg.name} must be one of: ${arg.enum.join(", ")}`
+      );
+    return result;
+  };
+  let ended = false;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!ended && token === "--") {
+      ended = true;
+      continue;
+    }
+    if (ended || token === "-" || !token.startsWith("-")) {
+      positions.push(token);
+      continue;
+    }
+    const [flag, inline] = token.split(/=(.*)/s);
+    const negative = flag?.startsWith("--no-");
+    const name = flag?.replace(/^--?/, "").replace(/^no-/, "");
+    const arg = flags.find(
+      (entry) => entry.name === name || keyOf(entry.name) === name || entry.short === name
+    );
+    if (!arg) {
+      const prefix = (name ?? "").slice(0, 3);
+      const suggestion = prefix ? flags.find((entry) => entry.name.startsWith(prefix)) : void 0;
+      throw new CliUsageError(
+        `Unknown flag: ${flag}${suggestion ? `; did you mean --${suggestion.name}?` : ""}`
+      );
+    }
+    if (negative && arg.type !== "boolean")
+      throw new CliUsageError(`--no-${arg.name} requires a boolean flag`);
+    let raw = inline;
+    if (arg.type === "boolean" && raw === void 0)
+      raw = negative ? "false" : "true";
+    if (raw === void 0) {
+      const next = argv[i + 1];
+      if (next === void 0 || /^--[a-z]/i.test(next))
+        throw new CliUsageError(`Missing value: --${arg.name}`);
+      raw = next;
+      i++;
+    }
+    const key = keyOf(arg.name);
+    if (arg.type === "array") {
+      const item = convert(raw, { ...arg, type: arg.itemType ?? "string" });
+      values[key] = [...values[key] ?? [], item];
+    } else values[key] = convert(raw, arg);
+  }
+  let index = 0;
+  for (const arg of spec.positionals ?? []) {
+    if (index >= positions.length) continue;
+    values[keyOf(arg.name)] = arg.variadic ? positions.slice(index).map(
+      (value) => convert(value, { ...arg, type: arg.itemType ?? arg.type })
+    ) : convert(positions[index], arg);
+    index = arg.variadic ? positions.length : index + 1;
+  }
+  if (index < positions.length)
+    throw new CliUsageError(`Unexpected positional: ${positions[index]}`);
+  for (const arg of [...flags, ...spec.positionals ?? []]) {
+    if (arg.required && values[keyOf(arg.name)] === void 0)
+      throw new CliUsageError(`Missing required argument: ${arg.name}`);
+  }
+  return values;
+}
+function renderCliHelp(spec) {
+  const describe = (arg) => `${arg.type}${arg.enum ? ` (${arg.enum.join("|")})` : ""}${arg.required ? " required" : ""}  ${arg.description ?? ""}`;
+  return `Usage: ${spec.command} ${(spec.positionals ?? []).map((arg) => `<${arg.name}${arg.variadic ? "..." : ""}>`).join(" ")} [flags]
+${spec.description ?? ""}
+
+Positionals:
+${(spec.positionals ?? []).map((arg) => `  ${arg.name}  ${describe(arg)}`).join("\n")}
+Flags:
+${(spec.flags ?? []).map((arg) => `  --${arg.name}${arg.short ? `, -${arg.short}` : ""}  ${describe(arg)}`).join("\n")}
+`;
+}
+var CliUsageError, keyOf;
+var init_cli_args = __esm({
+  "src/surfaces/cli_args.ts"() {
+    CliUsageError = class extends Error {
+      exitCode = 2;
+    };
+    keyOf = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
   }
 });
 
@@ -41,6 +157,78 @@ var init_affinity_error = __esm({
   }
 });
 
+// src/lib/errors/affinity_validation_error.ts
+var AffinityValidationError;
+var init_affinity_validation_error = __esm({
+  "src/lib/errors/affinity_validation_error.ts"() {
+    init_affinity_error();
+    AffinityValidationError = class extends AffinityError {
+      code = "VALIDATION";
+    };
+  }
+});
+
+// src/lib/read/assert_default_ordering.ts
+function assertDefaultOrdering(_readName, options) {
+  if (options?.sort !== void 0 || options?.descending !== void 0) {
+    throw new AffinityValidationError(
+      "This review does not support custom sort ordering"
+    );
+  }
+}
+var init_assert_default_ordering = __esm({
+  "src/lib/read/assert_default_ordering.ts"() {
+    init_affinity_validation_error();
+  }
+});
+
+// src/lib/types/read_list_options.ts
+var AFFINITY_DEFAULT_LIST_LIMIT, AFFINITY_MAX_LIST_LIMIT;
+var init_read_list_options = __esm({
+  "src/lib/types/read_list_options.ts"() {
+    AFFINITY_DEFAULT_LIST_LIMIT = 50;
+    AFFINITY_MAX_LIST_LIMIT = 250;
+  }
+});
+
+// src/lib/types/resolve_affinity_list_limit.ts
+function resolveAffinityListLimit(limit) {
+  if (limit === void 0) {
+    return AFFINITY_DEFAULT_LIST_LIMIT;
+  }
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new AffinityValidationError("limit must be a positive integer");
+  }
+  if (limit > AFFINITY_MAX_LIST_LIMIT) {
+    throw new AffinityValidationError(
+      `limit must be <= ${String(AFFINITY_MAX_LIST_LIMIT)}`
+    );
+  }
+  return limit;
+}
+var init_resolve_affinity_list_limit = __esm({
+  "src/lib/types/resolve_affinity_list_limit.ts"() {
+    init_affinity_validation_error();
+    init_read_list_options();
+  }
+});
+
+// src/lib/read/resolve_list_limit_offset.ts
+function resolveListLimitOffset(options) {
+  const limit = resolveAffinityListLimit(options?.limit);
+  const offset = options?.offset ?? 0;
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new AffinityValidationError("offset must be a non-negative integer");
+  }
+  return { limit, offset };
+}
+var init_resolve_list_limit_offset = __esm({
+  "src/lib/read/resolve_list_limit_offset.ts"() {
+    init_affinity_validation_error();
+    init_resolve_affinity_list_limit();
+  }
+});
+
 // src/lib/errors/affinity_invariant_error.ts
 var AffinityInvariantError;
 var init_affinity_invariant_error = __esm({
@@ -52,6 +240,17 @@ var init_affinity_invariant_error = __esm({
   }
 });
 
+// src/lib/errors/affinity_not_found_error.ts
+var AffinityNotFoundError;
+var init_affinity_not_found_error = __esm({
+  "src/lib/errors/affinity_not_found_error.ts"() {
+    init_affinity_error();
+    AffinityNotFoundError = class extends AffinityError {
+      code = "NOT_FOUND";
+    };
+  }
+});
+
 // src/contacts/queries.ts
 function getContactRowById(db, id) {
   const row = db.prepare(
@@ -88,17 +287,6 @@ var init_queries = __esm({
   }
 });
 
-// src/lib/errors/affinity_not_found_error.ts
-var AffinityNotFoundError;
-var init_affinity_not_found_error = __esm({
-  "src/lib/errors/affinity_not_found_error.ts"() {
-    init_affinity_error();
-    AffinityNotFoundError = class extends AffinityError {
-      code = "NOT_FOUND";
-    };
-  }
-});
-
 // src/lib/errors/affinity_state_error.ts
 var AffinityStateError;
 var init_affinity_state_error = __esm({
@@ -110,17 +298,6 @@ var init_affinity_state_error = __esm({
   }
 });
 
-// src/lib/errors/affinity_validation_error.ts
-var AffinityValidationError;
-var init_affinity_validation_error = __esm({
-  "src/lib/errors/affinity_validation_error.ts"() {
-    init_affinity_error();
-    AffinityValidationError = class extends AffinityError {
-      code = "VALIDATION";
-    };
-  }
-});
-
 // src/events/validators.ts
 function assertOwnerParticipates(ownerId, participantIds) {
   if (!participantIds.includes(ownerId)) {
@@ -134,7 +311,10 @@ function assertParticipantContactsLive(db, contactIds) {
       throw new AffinityNotFoundError("contact not found");
     }
     if (row.lifecycle_state === "merged") {
-      throw new AffinityStateError("merged contact is read-only");
+      const winner = row.merged_into_contact_id === null ? null : getContactRowById(db, row.merged_into_contact_id);
+      throw new AffinityStateError(
+        `Contact #${id} was merged into #${row.merged_into_contact_id} ${winner?.name ?? ""}; use contactId ${row.merged_into_contact_id}`
+      );
     }
   }
 }
@@ -345,29 +525,261 @@ var init_queries2 = __esm({
   }
 });
 
-// src/resolve_now.ts
-function resolveNow(now) {
-  if (now !== void 0) {
-    if (!Number.isFinite(now) || now < 0) {
-      throw new AffinityValidationError(
-        "now must be a finite non-negative number"
-      );
-    }
-    return now;
+// src/events/loaders.ts
+function loadEventParticipantViews(db, eventId) {
+  const rows = db.prepare(
+    `SELECT contact_id, role, directionality
+       FROM event_participants
+       WHERE event_id = ?`
+  ).all(eventId);
+  return rows.map((row) => ({
+    contactId: row.contact_id,
+    role: row.role,
+    ...row.directionality === null ? {} : { directionality: row.directionality }
+  }));
+}
+function loadEventRecord(db, eventId) {
+  const row = getEventRowById(db, eventId);
+  if (!row) {
+    throw new AffinityInvariantError("event not found");
   }
-  return Date.now();
+  const participants = loadEventParticipantViews(db, eventId);
+  return mapEventRowToEventRecord(row, participants);
 }
-var init_resolve_now = __esm({
-  "src/resolve_now.ts"() {
-    init_affinity_validation_error();
+function batchLoadEventRecords(db, eventIds) {
+  if (eventIds.length === 0) {
+    return [];
   }
-});
-
-// src/with_transaction.ts
-function withTransaction(db, fn) {
-  const depth = transactionDepth.get(db) ?? 0;
-  const savepoint = `affinity_${String(depth)}`;
-  if (depth === 0) {
+  const ph = eventIds.map(() => "?").join(", ");
+  const eventRows = db.prepare(
+    `SELECT id, type, occurred_at, summary, significance, moment_kind,
+              recurrence_kind, anchor_month, anchor_day,
+              anchor_contact_id, anchor_link_id,
+              created_at, updated_at, deleted_at
+       FROM events WHERE id IN (${ph}) AND deleted_at IS NULL`
+  ).all(...eventIds);
+  const partRows = db.prepare(
+    `SELECT event_id, contact_id, role, directionality
+       FROM event_participants WHERE event_id IN (${ph})`
+  ).all(...eventIds);
+  const partsByEvent = /* @__PURE__ */ new Map();
+  for (const p of partRows) {
+    let arr = partsByEvent.get(p.event_id);
+    if (!arr) {
+      arr = [];
+      partsByEvent.set(p.event_id, arr);
+    }
+    arr.push({
+      contactId: p.contact_id,
+      role: p.role,
+      ...p.directionality === null ? {} : { directionality: p.directionality }
+    });
+  }
+  const rowById = new Map(eventRows.map((r) => [r.id, r]));
+  const out = [];
+  for (const id of eventIds) {
+    const row = rowById.get(id);
+    if (row) {
+      out.push(mapEventRowToEventRecord(row, partsByEvent.get(id) ?? []));
+    }
+  }
+  return out;
+}
+function batchLoadEventParticipantViews(db, eventIds) {
+  const result = /* @__PURE__ */ new Map();
+  if (eventIds.length === 0) {
+    return result;
+  }
+  const ph = eventIds.map(() => "?").join(", ");
+  const rows = db.prepare(
+    `SELECT event_id, contact_id, role, directionality
+       FROM event_participants WHERE event_id IN (${ph})`
+  ).all(...eventIds);
+  for (const row of rows) {
+    let arr = result.get(row.event_id);
+    if (!arr) {
+      arr = [];
+      result.set(row.event_id, arr);
+    }
+    arr.push({
+      contactId: row.contact_id,
+      role: row.role,
+      ...row.directionality === null ? {} : { directionality: row.directionality }
+    });
+  }
+  return result;
+}
+function requireDateAnchorEvent(db, eventId) {
+  const row = getEventRowById(db, eventId);
+  if (!row) {
+    throw new AffinityNotFoundError("event not found");
+  }
+  if (row.type !== "date_anchor") {
+    throw new AffinityInvariantError("not a date anchor");
+  }
+  return row;
+}
+var init_loaders = __esm({
+  "src/events/loaders.ts"() {
+    init_affinity_invariant_error();
+    init_affinity_not_found_error();
+    init_mappers();
+    init_queries2();
+  }
+});
+
+// src/events/get_contact_journal.ts
+function getContactJournal(db, contactId, options) {
+  assertDefaultOrdering("getContactJournal", options);
+  const { limit, offset } = resolveListLimitOffset(options);
+  const clauses = ["e.deleted_at IS NULL", "ep.contact_id = ?"];
+  const params = [contactId];
+  if (options?.since !== void 0) {
+    clauses.push("e.occurred_at >= ?");
+    params.push(options.since);
+  }
+  if (options?.until !== void 0) {
+    clauses.push("e.occurred_at <= ?");
+    params.push(options.until);
+  }
+  if (options?.eventTypes !== void 0 && options.eventTypes.length > 0) {
+    const ph = options.eventTypes.map(() => "?").join(", ");
+    clauses.push(`e.type IN (${ph})`);
+    params.push(...options.eventTypes);
+  }
+  const where = clauses.join(" AND ");
+  const rows = db.prepare(
+    `SELECT e.id FROM events e
+       INNER JOIN event_participants ep ON ep.event_id = e.id
+       WHERE ${where}
+       ORDER BY e.occurred_at DESC, e.id DESC
+       LIMIT ? OFFSET ?`
+  ).all(...params, limit, offset);
+  return batchLoadEventRecords(
+    db,
+    rows.map((r) => r.id)
+  );
+}
+var init_get_contact_journal = __esm({
+  "src/events/get_contact_journal.ts"() {
+    init_assert_default_ordering();
+    init_resolve_list_limit_offset();
+    init_loaders();
+  }
+});
+
+// src/resolve_now.ts
+function resolveNow(now) {
+  if (now !== void 0) {
+    if (!Number.isFinite(now) || now < 0) {
+      throw new AffinityValidationError(
+        "now must be a finite non-negative number"
+      );
+    }
+    return now;
+  }
+  return Date.now();
+}
+var init_resolve_now = __esm({
+  "src/resolve_now.ts"() {
+    init_affinity_validation_error();
+  }
+});
+
+// src/events/list_open_commitments.ts
+function mapResolution(resolvedAt, resolution) {
+  if (resolvedAt === null) {
+    return "open";
+  }
+  if (resolution === "cancelled") {
+    return "cancelled";
+  }
+  return "resolved";
+}
+function listOpenCommitments(db, filters, options) {
+  assertDefaultOrdering("listOpenCommitments", options);
+  const now = resolveNow(options?.now);
+  const { limit, offset } = resolveListLimitOffset(options);
+  const clauses = ["e.deleted_at IS NULL", "oc.resolved_at IS NULL"];
+  const params = [];
+  if (options?.since !== void 0) {
+    clauses.push("e.occurred_at >= ?");
+    params.push(options.since);
+  }
+  if (options?.until !== void 0) {
+    clauses.push("e.occurred_at <= ?");
+    params.push(options.until);
+  }
+  if (filters?.commitmentType !== void 0) {
+    if (filters.commitmentType !== "promise" && filters.commitmentType !== "agreement") {
+      throw new AffinityValidationError("invalid commitmentType filter");
+    }
+    clauses.push("oc.commitment_type = ?");
+    params.push(filters.commitmentType);
+  }
+  if (filters?.contactId !== void 0) {
+    clauses.push(
+      "EXISTS (SELECT 1 FROM event_participants ep WHERE ep.event_id = oc.event_id AND ep.contact_id = ?)"
+    );
+    params.push(filters.contactId);
+  }
+  if (filters?.linkId !== void 0) {
+    clauses.push(
+      "EXISTS (SELECT 1 FROM link_event_effects le WHERE le.event_id = oc.event_id AND le.link_id = ?)"
+    );
+    params.push(filters.linkId);
+  }
+  if (filters?.horizonDays !== void 0) {
+    if (!Number.isInteger(filters.horizonDays) || filters.horizonDays < 0) {
+      throw new AffinityValidationError(
+        "horizonDays must be a non-negative integer"
+      );
+    }
+    const anchor = options?.since ?? now;
+    clauses.push("oc.due_at IS NOT NULL");
+    clauses.push("oc.due_at <= ?");
+    params.push(anchor + filters.horizonDays * DAY_MS);
+  }
+  const where = clauses.join(" AND ");
+  const rows = db.prepare(
+    `SELECT oc.event_id, oc.commitment_type, oc.due_at, oc.resolved_at, oc.resolution,
+              e.type, e.summary
+       FROM open_commitments oc
+       INNER JOIN events e ON e.id = oc.event_id
+       WHERE ${where}
+       ORDER BY oc.due_at IS NULL, oc.due_at ASC, oc.created_at ASC
+       LIMIT ? OFFSET ?`
+  ).all(...params, limit, offset);
+  const eventIds = rows.map((r) => r.event_id);
+  const partsByEvent = batchLoadEventParticipantViews(db, eventIds);
+  return rows.map((r) => ({
+    eventId: r.event_id,
+    type: r.type,
+    summary: r.summary,
+    participants: partsByEvent.get(r.event_id) ?? [],
+    dueAt: r.due_at,
+    dueAtIso: r.due_at === null ? null : new Date(r.due_at).toISOString(),
+    overdue: r.due_at !== null && r.due_at < now,
+    resolutionState: mapResolution(r.resolved_at, r.resolution)
+  }));
+}
+var DAY_MS;
+var init_list_open_commitments = __esm({
+  "src/events/list_open_commitments.ts"() {
+    init_affinity_validation_error();
+    init_assert_default_ordering();
+    init_resolve_list_limit_offset();
+    init_resolve_now();
+    init_loaders();
+    DAY_MS = 864e5;
+  }
+});
+
+// src/with_transaction.ts
+function withTransaction(db, fn) {
+  const depth = transactionDepth.get(db) ?? 0;
+  const savepoint = `affinity_${String(depth)}`;
+  if (depth === 0) {
     db.exec("BEGIN IMMEDIATE");
   } else {
     db.exec(`SAVEPOINT ${savepoint}`);
@@ -667,13 +1079,20 @@ function loadContactProfileRecord(db, contactId, topLinksLimit) {
   const topLinks = linkRows.map((l) => mapLinkRowToLinkListItem(l));
   const activeDates = loadActiveDatesForContact(db, contactId);
   const contactRollup = loadContactRollup(db, contactId);
+  const winner = row.merged_into_contact_id === null ? null : getContactRowById(db, row.merged_into_contact_id);
   return {
+    ...winner ? { mergedInto: { id: winner.id, name: winner.name } } : {},
     contact: mapContactRowToContactCore(row),
     identities,
     attributes,
     topLinks,
     activeDates,
-    warnings: contactRollup?.warnings ?? [],
+    warnings: [
+      ...contactRollup?.warnings ?? [],
+      ...winner ? [
+        `Contact #${row.id} was merged into #${winner.id} ${winner.name}; use contactId ${winner.id}`
+      ] : []
+    ],
     rollups: contactRollup?.rollup ?? null
   };
 }
@@ -691,10 +1110,32 @@ var init_load_contact_profile_record = __esm({
 // src/contacts/get_contact_profile.ts
 function getContactProfile(db, contactId, options) {
   const t = options?.topLinksLimit ?? 8;
-  return loadContactProfileRecord(db, contactId, t);
+  const profile = loadContactProfileRecord(db, contactId, t);
+  if (!profile) return null;
+  const ties = db.prepare(`SELECT l.id, l.kind, l.role, c.id AS contactId, c.name
+    FROM links l JOIN contacts c ON c.id = CASE WHEN l.from_contact_id = ? THEN l.to_contact_id ELSE l.from_contact_id END
+    WHERE l.is_structural = 1 AND l.removed_at IS NULL AND (l.from_contact_id = ? OR l.to_contact_id = ?)
+    AND c.deleted_at IS NULL ORDER BY l.id`).all(contactId, contactId, contactId);
+  return {
+    ...profile,
+    recentEvents: getContactJournal(db, contactId, {
+      limit: options?.recentEventsLimit ?? 5
+    }).map((event) => ({
+      ...event,
+      occurredAtIso: new Date(event.occurredAt).toISOString()
+    })),
+    openCommitments: listOpenCommitments(
+      db,
+      { contactId },
+      options?.now === void 0 ? void 0 : { now: options.now }
+    ),
+    ties
+  };
 }
 var init_get_contact_profile = __esm({
   "src/contacts/get_contact_profile.ts"() {
+    init_get_contact_journal();
+    init_list_open_commitments();
     init_load_contact_profile_record();
   }
 });
@@ -715,83 +1156,22 @@ var init_get_owner_profile = __esm({
   }
 });
 
-// src/lib/read/assert_default_ordering.ts
-function assertDefaultOrdering(readName, options) {
-  if (options?.sort !== void 0 || options?.descending !== void 0) {
-    throw new AffinityValidationError(
-      `${readName} does not support custom sort ordering`
-    );
+// src/events/list_moments.ts
+function listMoments(db, filters, options) {
+  assertDefaultOrdering("listMoments", options);
+  const { limit, offset } = resolveListLimitOffset(options);
+  const clauses = [
+    "e.deleted_at IS NULL",
+    "le.moment_kind IS NOT NULL"
+  ];
+  const params = [];
+  if (options?.since !== void 0) {
+    clauses.push("le.occurred_at >= ?");
+    params.push(options.since);
   }
-}
-var init_assert_default_ordering = __esm({
-  "src/lib/read/assert_default_ordering.ts"() {
-    init_affinity_validation_error();
-  }
-});
-
-// src/lib/types/read_list_options.ts
-var AFFINITY_DEFAULT_LIST_LIMIT, AFFINITY_MAX_LIST_LIMIT;
-var init_read_list_options = __esm({
-  "src/lib/types/read_list_options.ts"() {
-    AFFINITY_DEFAULT_LIST_LIMIT = 50;
-    AFFINITY_MAX_LIST_LIMIT = 250;
-  }
-});
-
-// src/lib/types/resolve_affinity_list_limit.ts
-function resolveAffinityListLimit(limit) {
-  if (limit === void 0) {
-    return AFFINITY_DEFAULT_LIST_LIMIT;
-  }
-  if (!Number.isInteger(limit) || limit < 1) {
-    throw new AffinityValidationError("limit must be a positive integer");
-  }
-  if (limit > AFFINITY_MAX_LIST_LIMIT) {
-    throw new AffinityValidationError(
-      `limit must be <= ${String(AFFINITY_MAX_LIST_LIMIT)}`
-    );
-  }
-  return limit;
-}
-var init_resolve_affinity_list_limit = __esm({
-  "src/lib/types/resolve_affinity_list_limit.ts"() {
-    init_affinity_validation_error();
-    init_read_list_options();
-  }
-});
-
-// src/lib/read/resolve_list_limit_offset.ts
-function resolveListLimitOffset(options) {
-  const limit = resolveAffinityListLimit(options?.limit);
-  const offset = options?.offset ?? 0;
-  if (!Number.isInteger(offset) || offset < 0) {
-    throw new AffinityValidationError("offset must be a non-negative integer");
-  }
-  return { limit, offset };
-}
-var init_resolve_list_limit_offset = __esm({
-  "src/lib/read/resolve_list_limit_offset.ts"() {
-    init_affinity_validation_error();
-    init_resolve_affinity_list_limit();
-  }
-});
-
-// src/events/list_moments.ts
-function listMoments(db, filters, options) {
-  assertDefaultOrdering("listMoments", options);
-  const { limit, offset } = resolveListLimitOffset(options);
-  const clauses = [
-    "e.deleted_at IS NULL",
-    "le.moment_kind IS NOT NULL"
-  ];
-  const params = [];
-  if (options?.since !== void 0) {
-    clauses.push("le.occurred_at >= ?");
-    params.push(options.since);
-  }
-  if (options?.until !== void 0) {
-    clauses.push("le.occurred_at <= ?");
-    params.push(options.until);
+  if (options?.until !== void 0) {
+    clauses.push("le.occurred_at <= ?");
+    params.push(options.until);
   }
   if (filters?.contactId !== void 0) {
     clauses.push(
@@ -837,109 +1217,6 @@ var init_list_moments = __esm({
   }
 });
 
-// src/events/loaders.ts
-function loadEventParticipantViews(db, eventId) {
-  const rows = db.prepare(
-    `SELECT contact_id, role, directionality
-       FROM event_participants
-       WHERE event_id = ?`
-  ).all(eventId);
-  return rows.map((row) => ({
-    contactId: row.contact_id,
-    role: row.role,
-    ...row.directionality === null ? {} : { directionality: row.directionality }
-  }));
-}
-function loadEventRecord(db, eventId) {
-  const row = getEventRowById(db, eventId);
-  if (!row) {
-    throw new AffinityInvariantError("event not found");
-  }
-  const participants = loadEventParticipantViews(db, eventId);
-  return mapEventRowToEventRecord(row, participants);
-}
-function batchLoadEventRecords(db, eventIds) {
-  if (eventIds.length === 0) {
-    return [];
-  }
-  const ph = eventIds.map(() => "?").join(", ");
-  const eventRows = db.prepare(
-    `SELECT id, type, occurred_at, summary, significance, moment_kind,
-              recurrence_kind, anchor_month, anchor_day,
-              anchor_contact_id, anchor_link_id,
-              created_at, updated_at, deleted_at
-       FROM events WHERE id IN (${ph}) AND deleted_at IS NULL`
-  ).all(...eventIds);
-  const partRows = db.prepare(
-    `SELECT event_id, contact_id, role, directionality
-       FROM event_participants WHERE event_id IN (${ph})`
-  ).all(...eventIds);
-  const partsByEvent = /* @__PURE__ */ new Map();
-  for (const p of partRows) {
-    let arr = partsByEvent.get(p.event_id);
-    if (!arr) {
-      arr = [];
-      partsByEvent.set(p.event_id, arr);
-    }
-    arr.push({
-      contactId: p.contact_id,
-      role: p.role,
-      ...p.directionality === null ? {} : { directionality: p.directionality }
-    });
-  }
-  const rowById = new Map(eventRows.map((r) => [r.id, r]));
-  const out = [];
-  for (const id of eventIds) {
-    const row = rowById.get(id);
-    if (row) {
-      out.push(mapEventRowToEventRecord(row, partsByEvent.get(id) ?? []));
-    }
-  }
-  return out;
-}
-function batchLoadEventParticipantViews(db, eventIds) {
-  const result = /* @__PURE__ */ new Map();
-  if (eventIds.length === 0) {
-    return result;
-  }
-  const ph = eventIds.map(() => "?").join(", ");
-  const rows = db.prepare(
-    `SELECT event_id, contact_id, role, directionality
-       FROM event_participants WHERE event_id IN (${ph})`
-  ).all(...eventIds);
-  for (const row of rows) {
-    let arr = result.get(row.event_id);
-    if (!arr) {
-      arr = [];
-      result.set(row.event_id, arr);
-    }
-    arr.push({
-      contactId: row.contact_id,
-      role: row.role,
-      ...row.directionality === null ? {} : { directionality: row.directionality }
-    });
-  }
-  return result;
-}
-function requireDateAnchorEvent(db, eventId) {
-  const row = getEventRowById(db, eventId);
-  if (!row) {
-    throw new AffinityNotFoundError("event not found");
-  }
-  if (row.type !== "date_anchor") {
-    throw new AffinityInvariantError("not a date anchor");
-  }
-  return row;
-}
-var init_loaders = __esm({
-  "src/events/loaders.ts"() {
-    init_affinity_invariant_error();
-    init_affinity_not_found_error();
-    init_mappers();
-    init_queries2();
-  }
-});
-
 // src/links/queries.ts
 function getLinkRowById(db, id) {
   const row = db.prepare(
@@ -1212,7 +1489,7 @@ function recencyScore(occurredAt, cadenceDays, now) {
     return 0;
   }
   const cadence = Math.max(cadenceDays ?? 0, 1);
-  const daysSince = Math.max(0, (now - occurredAt) / DAY_MS);
+  const daysSince = Math.max(0, (now - occurredAt) / DAY_MS2);
   return Math.max(0, 1 - daysSince / cadence);
 }
 function refreshLinkRollup(db, linkId, now) {
@@ -1223,15 +1500,15 @@ function refreshLinkRollup(db, linkId, now) {
   const latest = db.prepare(
     `SELECT event_id, occurred_at
        FROM link_event_effects
-       WHERE link_id = ?
+       WHERE link_id = ? AND counts_for_recency = 1
        ORDER BY occurred_at DESC, event_id DESC
        LIMIT 1`
   ).get(linkId);
-  const trailingWindowStart = now - 180 * DAY_MS;
+  const trailingWindowStart = now - 180 * DAY_MS2;
   const counts = db.prepare(
     `SELECT
          COUNT(*) AS total_meaningful_events,
-         SUM(CASE WHEN affinity_delta > 0 OR trust_delta > 0 THEN 1 ELSE 0 END) AS positive_meaningful_events
+         SUM(CASE WHEN counts_for_recency = 1 AND (affinity_delta > 0 OR trust_delta > 0) THEN 1 ELSE 0 END) AS positive_meaningful_events
        FROM link_event_effects
        WHERE link_id = ? AND occurred_at >= ?`
   ).get(linkId, trailingWindowStart);
@@ -1239,7 +1516,7 @@ function refreshLinkRollup(db, linkId, now) {
     `SELECT ep.directionality
        FROM link_event_effects le
        INNER JOIN event_participants ep ON ep.event_id = le.event_id
-       WHERE le.link_id = ? AND ep.contact_id = ?
+       WHERE le.link_id = ? AND le.counts_for_recency = 1 AND ep.contact_id = ?
          AND ep.directionality IS NOT NULL
          AND le.occurred_at >= ?`
   ).all(linkId, link.from_contact_id, trailingWindowStart);
@@ -1265,7 +1542,7 @@ function refreshLinkRollup(db, linkId, now) {
     link.cadence_days,
     now
   );
-  const daysSinceLastMeaningfulEvent = latest === void 0 ? 0 : Math.max(0, (now - latest.occurred_at) / DAY_MS);
+  const daysSinceLastMeaningfulEvent = latest === void 0 ? 0 : Math.max(0, (now - latest.occurred_at) / DAY_MS2);
   const driftPriorityValue = driftPriority({
     daysSinceLastMeaningfulEvent,
     cadenceDays: link.cadence_days ?? 1,
@@ -1348,13 +1625,13 @@ function refreshLinkRollup(db, linkId, now) {
   refreshContactRollup(db, link.from_contact_id, now);
   refreshContactRollup(db, link.to_contact_id, now);
 }
-var DAY_MS;
+var DAY_MS2;
 var init_rollups2 = __esm({
   "src/links/rollups.ts"() {
     init_rollups();
     init_mechanics();
     init_queries3();
-    DAY_MS = 864e5;
+    DAY_MS2 = 864e5;
   }
 });
 
@@ -1412,8 +1689,61 @@ var init_get_link_detail = __esm({
   }
 });
 
+// src/tools/parse_time_input.ts
+function parseTimeInput(value, field = "time", now = Date.now()) {
+  const fail = () => {
+    throw new AffinityValidationError(`${field}: expected ${timeInputForms}`);
+  };
+  if (typeof value === "number")
+    return Number.isSafeInteger(value) && Number.isFinite(new Date(value).getTime()) ? value : fail();
+  if (typeof value !== "string") return fail();
+  const text = value.trim();
+  const relative = /^(?:today|tomorrow|yesterday|[+-]\d+d)$/.test(text);
+  let day;
+  if (relative) {
+    const offset = text === "today" ? 0 : text === "tomorrow" ? 1 : text === "yesterday" ? -1 : Number(text.slice(0, -1));
+    day = Math.floor(now / 864e5) * 864e5 + offset * 864e5;
+  } else if (/^\d{4}-\d{2}-\d{2}$/.test(text)) {
+    day = Date.parse(`${text}T00:00:00.000Z`);
+    if (!Number.isFinite(day) || new Date(day).toISOString().slice(0, 10) !== text)
+      return fail();
+  } else {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      text
+    ))
+      return fail();
+    const calendar = Date.parse(`${text.slice(0, 10)}T00:00:00Z`);
+    if (!Number.isFinite(calendar) || new Date(calendar).toISOString().slice(0, 10) !== text.slice(0, 10))
+      return fail();
+    const parsed = Date.parse(text);
+    return Number.isFinite(parsed) ? parsed : fail();
+  }
+  const result = day + (field.split(".").at(-1) === "dueAt" ? 86399999 : 0);
+  return Number.isSafeInteger(result) && Number.isFinite(new Date(result).getTime()) ? result : fail();
+}
+var timeInputForms;
+var init_parse_time_input = __esm({
+  "src/tools/parse_time_input.ts"() {
+    init_affinity_validation_error();
+    timeInputForms = "epoch milliseconds integer, ISO 8601 date-time with Z/offset, YYYY-MM-DD, today, tomorrow, yesterday, +3d or -2d";
+  }
+});
+
 // src/tools/tool_metadata.ts
 function defineAffinityTool(definition) {
+  const visit = (schema) => {
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if ((key.endsWith("At") || ["now", "asOf", "since", "until"].includes(key)) && child.type === "integer") {
+        child.type = void 0;
+        child.oneOf = [{ type: "integer" }, { type: "string" }];
+        child.description = `${child.description ?? "Time."} Accepts ${timeInputForms}. UTC midnight for dates; dueAt uses UTC end of day.`;
+      }
+      visit(child);
+    }
+    if (schema.items) visit(schema.items);
+    for (const child of schema.oneOf ?? schema.anyOf ?? []) visit(child);
+  };
+  visit(definition.inputSchema);
   return definition;
 }
 function stringSchema(description, options = {}) {
@@ -1460,8 +1790,15 @@ function objectSchema(properties, required, description) {
 function nullableStringSchema(description) {
   return { anyOf: [{ type: "string" }, { type: "null" }], description };
 }
+function oneOfSchema(schemas, description) {
+  const schema = {
+    oneOf: schemas
+  };
+  return schema;
+}
 var init_tool_metadata = __esm({
   "src/tools/tool_metadata.ts"() {
+    init_parse_time_input();
   }
 });
 
@@ -1502,6 +1839,7 @@ function toContactEntityRef(value) {
 function toContactListToolItem(value) {
   return {
     ...toContactEntityRef(value),
+    ..."matchedOn" in value ? { matchedOn: value.matchedOn } : {},
     subtitle: "kind" in value ? value.kind : void 0
   };
 }
@@ -1533,7 +1871,9 @@ function toEventEntityRef(value) {
 }
 function toEventListToolItem(value) {
   return {
+    ...value,
     ...toEventEntityRef(value),
+    occurredAtIso: new Date(value.occurredAt).toISOString(),
     snippet: `${value.participants.length} participant(s)`
   };
 }
@@ -1595,7 +1935,7 @@ function withOptionalFields(result, options) {
   if (options.warnings && options.warnings.length > 0) {
     result.warnings = options.warnings;
   }
-  return result;
+  return roundToolValues(result);
 }
 function toolWarning(code, message) {
   return { code, message };
@@ -1659,13 +1999,35 @@ function toolFailure(kind, code, summary, message, options = {}) {
     options
   );
 }
+function roundToolValues(value) {
+  if (typeof value === "number")
+    return Number.isInteger(value) ? value : Math.round(value * 1e3) / 1e3;
+  if (Array.isArray(value)) return value.map(roundToolValues);
+  if (value !== null && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [
+        key,
+        roundToolValues(child)
+      ])
+    );
+  return value;
+}
 var init_tool_types = __esm({
   "src/tools/tool_types.ts"() {
   }
 });
 
 // src/tools/tool_resolvers.ts
-function resolveContactLocator(db, locator, field = "contact") {
+function resolveContactLocator(db, locator, field = "contact", allowMerged = false) {
+  if (!locator || typeof locator !== "object")
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field} locator.`,
+        [field]
+      )
+    };
   if ("contactId" in locator) {
     const row2 = getContactRowById(db, locator.contactId);
     if (!row2) {
@@ -1679,8 +2041,25 @@ function resolveContactLocator(db, locator, field = "contact") {
         )
       };
     }
+    if (!allowMerged && row2.merged_into_contact_id !== null) {
+      const winner = getContactRowById(db, row2.merged_into_contact_id);
+      const message = `Contact #${row2.id} was merged into #${row2.merged_into_contact_id} ${winner?.name ?? ""}; use contactId ${row2.merged_into_contact_id}`;
+      return {
+        ok: false,
+        result: toolFailure("domain", "invalid_state", message, message)
+      };
+    }
     return { ok: true, value: row2 };
   }
+  if (!("identity" in locator) || !locator.identity)
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field}.contactId or identity.`,
+        [field]
+      )
+    };
   const normalizedKey = normalizeIdentityKey(
     locator.identity.type,
     locator.identity.value
@@ -1738,6 +2117,15 @@ function resolveContactLocator(db, locator, field = "contact") {
   return { ok: true, value: matchedContact };
 }
 function resolveLinkLocator(db, locator, field = "link") {
+  if (!locator || typeof locator !== "object")
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field} locator.`,
+        [field]
+      )
+    };
   if ("linkId" in locator) {
     const row = getLinkRowById(db, locator.linkId);
     if (!row) {
@@ -1753,6 +2141,15 @@ function resolveLinkLocator(db, locator, field = "link") {
     }
     return { ok: true, value: row };
   }
+  if (!("endpoints" in locator) || !locator.endpoints)
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field}.linkId or endpoints.`,
+        [field]
+      )
+    };
   const { endpoints } = locator;
   const clauses = [
     "removed_at IS NULL",
@@ -1881,6 +2278,97 @@ var init_tool_resolvers = __esm({
   }
 });
 
+// src/tools/validate_tool_input.ts
+function validateToolInput(schema, value, path = "input", injectedNow = Date.now()) {
+  if (schema.anyOf || schema.oneOf) {
+    const choices = schema.anyOf ?? schema.oneOf ?? [];
+    return choices.some(
+      (choice) => validateToolInput(choice, value, path, injectedNow) === null
+    ) ? null : `${path}: invalid value`;
+  }
+  if (schema.type === "object") {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+      return `${path}: missing input or expected object`;
+    const object = value;
+    if (path.endsWith(".patch") && schema.additionalProperties === false) {
+      for (const key of Object.keys(object)) {
+        if (!Object.hasOwn(schema.properties ?? {}, key))
+          return key === "kind" && "name" in (schema.properties ?? {}) ? "kind cannot be changed after creation" : `${path}.${key}: unknown patch key; allowed keys: ${Object.keys(schema.properties ?? {}).join(", ")}`;
+      }
+    }
+    if (object.action === "revise" && schema.properties?.patch && object.patch === void 0)
+      return `${path}.patch: missing required field`;
+    if (object.patch !== void 0 && !schema.properties?.patch)
+      return `${path}.patch: unknown patch key; allowed keys: none (use the action's named fields)`;
+    const referenceNow = object.now === void 0 ? injectedNow : (() => {
+      try {
+        return parseTimeInput(
+          object.now,
+          `${path}.now`,
+          injectedNow
+        );
+      } catch {
+        return Date.now();
+      }
+    })();
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (object[key] !== void 0 && (key.endsWith("At") || ["now", "asOf", "since", "until"].includes(key)) && child.oneOf?.some((choice) => choice.type === "integer")) {
+        try {
+          object[key] = parseTimeInput(
+            object[key],
+            `${path}.${key}`,
+            referenceNow
+          );
+        } catch (error) {
+          return error.message;
+        }
+      }
+    }
+    for (const key of schema.required ?? []) {
+      if (object[key] === void 0)
+        return `${path}.${key}: missing required field`;
+    }
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (object[key] === void 0) continue;
+      const error = validateToolInput(
+        child,
+        object[key],
+        `${path}.${key}`,
+        referenceNow
+      );
+      if (error) return error;
+    }
+    return null;
+  }
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) return `${path}: expected array`;
+    for (const [index, item] of value.entries()) {
+      const error = validateToolInput(
+        schema.items ?? {},
+        item,
+        `${path}[${index}]`,
+        injectedNow
+      );
+      if (error) return error;
+    }
+    return null;
+  }
+  if (schema.enum && !schema.enum.includes(value))
+    return `${path}: expected ${schema.enum.join(", ")}`;
+  if (schema.type === "null")
+    return value === null ? null : `${path}: expected null`;
+  if (schema.type === "integer")
+    return Number.isInteger(value) ? null : `${path}: expected integer`;
+  const valid = schema.type === void 0 || schema.type === "string" && typeof value === "string" || schema.type === "number" && typeof value === "number" && Number.isFinite(value) || schema.type === "boolean" && typeof value === "boolean";
+  if (!valid) return `${path}: expected ${schema.type}`;
+  return null;
+}
+var init_validate_tool_input = __esm({
+  "src/tools/validate_tool_input.ts"() {
+    init_parse_time_input();
+  }
+});
+
 // src/tools/inspect_affinity_item_tool.ts
 function contactLocatorSchema(description) {
   return {
@@ -1916,7 +2404,19 @@ function linkLocatorSchema(description) {
     description
   };
 }
-function inspectAffinityItemToolHandler(db, input) {
+function inspectAffinityItemToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(
+    inspectAffinityItemTool.inputSchema,
+    input
+  );
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     if (input.kind === "owner_profile") {
       const detail2 = getOwnerProfile(
@@ -1934,19 +2434,21 @@ function inspectAffinityItemToolHandler(db, input) {
       return toolSuccess(
         `Loaded owner profile for ${detail2.contact.name}.`,
         { kind: input.kind, detail: detail2 },
-        { entities: [toContactEntityRef(detail2.contact)] }
+        {
+          entities: [toContactEntityRef(detail2.contact)],
+          warnings: detail2.mergedInto ? [{ code: "partial_match", message: detail2.warnings.join("; ") }] : void 0
+        }
       );
     }
     if (input.kind === "contact_profile") {
-      const contact = resolveContactLocator(db, input.contact, "contact");
+      const contact = resolveContactLocator(db, input.contact, "contact", true);
       if (!contact.ok) {
         return contact.result;
       }
-      const detail2 = getContactProfile(
-        db,
-        contact.value.id,
-        input.topLinksLimit === void 0 ? void 0 : { topLinksLimit: input.topLinksLimit }
-      );
+      const detail2 = getContactProfile(db, contact.value.id, {
+        ...input.topLinksLimit === void 0 ? {} : { topLinksLimit: input.topLinksLimit },
+        ...input.recentEventsLimit === void 0 ? {} : { recentEventsLimit: input.recentEventsLimit }
+      });
       if (!detail2) {
         return toolFailure(
           "domain",
@@ -1958,8 +2460,11 @@ function inspectAffinityItemToolHandler(db, input) {
       return toolSuccess(
         `Loaded contact profile for ${detail2.contact.name}.`,
         { kind: input.kind, detail: detail2 },
-        { entities: [toContactEntityRef(detail2.contact)] }
-      );
+        {
+          entities: [toContactEntityRef(detail2.contact)],
+          warnings: detail2.mergedInto ? [{ code: "partial_match", message: detail2.warnings.join("; ") }] : void 0
+        }
+      );
     }
     const link = resolveLinkLocator(db, input.link, "link");
     if (!link.ok) {
@@ -2001,6 +2506,8 @@ var init_inspect_affinity_item_tool = __esm({
     init_tool_ref();
     init_tool_resolvers();
     init_tool_types();
+    init_tool_types();
+    init_validate_tool_input();
     inspectAffinityItemTool = defineAffinityTool({
       name: inspectAffinityItemToolName,
       description: "Inspect one exact affinity item such as the owner profile, a contact profile, or one link detail.",
@@ -2492,25 +2999,18 @@ var init_unset_attribute = __esm({
   }
 });
 
-// src/tools/tool_summary.ts
-function summarizeCount(count, singular) {
-  if (count === 0) {
-    return `No ${singular}s found.`;
-  }
-  if (count === 1) {
-    return `Found 1 ${singular}.`;
-  }
-  return `Found ${count} ${singular}s.`;
-}
-var init_tool_summary = __esm({
-  "src/tools/tool_summary.ts"() {
-  }
-});
-
 // src/tools/tool_mutation.ts
-function mutationToolResult(action, receipt, entitySummary) {
+function mutationToolResult(action, receipt, entitySummary, fields) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
   const data = {
+    changes: ["created", "updated", "archived", "removed"].flatMap(
+      (verb) => receipt[verb].map((ref) => ({
+        entity: ref.kind,
+        id: ref.id,
+        action: verb,
+        ...verb === "updated" && fields ? { fields } : {}
+      }))
+    ),
     action,
     primary: receipt.primary,
     created: receipt.created,
@@ -2520,7 +3020,7 @@ function mutationToolResult(action, receipt, entitySummary) {
     affectedLinks: receipt.affectedLinks,
     derivedEffects: receipt.derivedEffects
   };
-  const summary = changedCount === 0 ? `No ${entitySummary} changes were needed.` : summarizeCount(changedCount, `${entitySummary} change`);
+  const summary = changedCount === 0 ? `No ${entitySummary} changes were needed.` : describeChanges(receipt);
   if (changedCount === 0) {
     return toolNoOp(summary, data, {
       entities: toReceiptEntityRefs(receipt)
@@ -2530,11 +3030,28 @@ function mutationToolResult(action, receipt, entitySummary) {
     entities: toReceiptEntityRefs(receipt)
   });
 }
+function describeChanges(receipt) {
+  const parts = [];
+  for (const verb of ["created", "updated", "archived", "removed"]) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const ref of receipt[verb]) {
+      counts.set(ref.kind, (counts.get(ref.kind) ?? 0) + 1);
+    }
+    if (counts.size === 0) continue;
+    const items = [...counts].map(
+      ([kind, n]) => `${n} ${n === 1 ? kind : PLURALS[kind] ?? `${kind}s`}`
+    );
+    parts.push(`${verb} ${items.join(", ")}`);
+  }
+  const text = parts.join("; ");
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}.`;
+}
+var PLURALS;
 var init_tool_mutation = __esm({
   "src/tools/tool_mutation.ts"() {
     init_tool_ref();
-    init_tool_summary();
     init_tool_types();
+    PLURALS = { identity: "identities" };
   }
 });
 
@@ -2587,7 +3104,23 @@ function resolveAttributeTarget(db, target) {
   }
   return { kind: "ok", target: { kind: "link", id: link.value.id } };
 }
-function manageAttributeToolHandler(db, input) {
+function manageAttributeToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageAttributeTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
+  if (!input.target)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Missing target.",
+      "target is required."
+    );
   return withToolHandling(() => {
     const resolved = resolveAttributeTarget(db, input.target);
     if (resolved.kind === "error") {
@@ -2625,6 +3158,8 @@ var init_manage_attribute_tool = __esm({
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_validate_tool_input();
     manageAttributeTool = defineAffinityTool({
       name: manageAttributeToolName,
       description: "Set, unset, or replace custom metadata attributes on contacts and links. For emails, phones, handles, and URLs use manage_identity instead \u2014 those are routing keys, not attributes.",
@@ -3257,7 +3792,7 @@ function clamp3(value, min, max) {
 }
 function countSameDaySimilarEvents(db, linkId, eventType, occurredAt) {
   const dayStart = utcStartOfDayMs(occurredAt);
-  const dayEnd = dayStart + DAY_MS2;
+  const dayEnd = dayStart + DAY_MS3;
   const row = db.prepare(
     `SELECT COUNT(*) AS c
        FROM link_event_effects le
@@ -3270,7 +3805,7 @@ function countSameDaySimilarEvents(db, linkId, eventType, occurredAt) {
   return Number(row.c ?? 0);
 }
 function weeklyPositiveBaseWeight(db, linkId, occurredAt) {
-  const weekStart = occurredAt - 7 * DAY_MS2;
+  const weekStart = occurredAt - 7 * DAY_MS3;
   const row = db.prepare(
     `SELECT SUM(base_weight) AS total
        FROM link_event_effects
@@ -3282,7 +3817,7 @@ function weeklyPositiveBaseWeight(db, linkId, occurredAt) {
   return Number(row.total ?? 0);
 }
 function countRepairContext(db, linkId, occurredAt) {
-  const thirtyDaysAgo = occurredAt - 30 * DAY_MS2;
+  const thirtyDaysAgo = occurredAt - 30 * DAY_MS3;
   const hasPriorDamage = db.prepare(
     `SELECT 1 FROM link_event_effects
        WHERE link_id = ? AND trust_delta < 0
@@ -3357,8 +3892,8 @@ function computePreferenceMatch(db, linkId, contactId, eventType, provenance) {
   return preferenceMatch(liked, disliked);
 }
 function computeDateSalienceMultiplier(db, contactId, occurredAt, significance) {
-  const windowBefore = 7 * DAY_MS2;
-  const windowAfter = 2 * DAY_MS2;
+  const windowBefore = 7 * DAY_MS3;
+  const windowAfter = 2 * DAY_MS3;
   const row = db.prepare(
     `SELECT 1 FROM upcoming_occurrences uo
        JOIN events e ON e.id = uo.event_id
@@ -3525,9 +4060,9 @@ function applyEventEffectToLink(db, params) {
   ).get(params.linkId);
   const gapDays = latest === void 0 ? cadenceBefore : Math.max(
     1,
-    Math.round((params.occurredAt - latest.occurred_at) / DAY_MS2)
+    Math.round((params.occurredAt - latest.occurred_at) / DAY_MS3)
   );
-  const cadenceAfter = nextCadenceDays({
+  const cadenceAfter = commitmentResolution === "broken" || commitmentResolution === "cancelled" ? cadenceBefore : nextCadenceDays({
     kind: linkKind,
     currentCadenceDays: cadenceBefore,
     gapDays
@@ -3590,6 +4125,11 @@ function applyEventEffectToLink(db, params) {
     params.now,
     params.now
   );
+  if (commitmentResolution === "broken" || commitmentResolution === "cancelled") {
+    db.prepare(
+      "UPDATE link_event_effects SET counts_for_recency = 0 WHERE event_id = ? AND link_id = ?"
+    ).run(params.eventId, params.linkId);
+  }
   refreshLinkRollup(db, params.linkId, params.now);
   return {
     linkId: params.linkId,
@@ -3613,7 +4153,7 @@ function applyEventEffectToLink(db, params) {
     momentKind
   };
 }
-var DAY_MS2;
+var DAY_MS3;
 var init_effects = __esm({
   "src/links/effects.ts"() {
     init_calendar();
@@ -3623,7 +4163,7 @@ var init_effects = __esm({
     init_queries3();
     init_rollups2();
     init_validators2();
-    DAY_MS2 = 864e5;
+    DAY_MS3 = 864e5;
   }
 });
 
@@ -4004,12 +4544,16 @@ function resolveCommitment(db, commitmentEventId, resolution, options) {
     if (row.type !== "promise" && row.type !== "agreement") {
       throw new AffinityInvariantError("not a commitment event");
     }
-    const open = db.prepare("SELECT resolved_at FROM open_commitments WHERE event_id = ?").get(commitmentEventId);
+    const open = db.prepare(
+      "SELECT resolved_at, resolution FROM open_commitments WHERE event_id = ?"
+    ).get(commitmentEventId);
     if (!open) {
       throw new AffinityNotFoundError("open commitment not found");
     }
     if (open.resolved_at !== null) {
-      throw new AffinityStateError("commitment already resolved");
+      throw new AffinityConflictError(
+        `Commitment #${commitmentEventId} is already resolved (${open.resolution})`
+      );
     }
     const now = resolveNow(options?.now);
     const originalParticipants = loadEventParticipantViews(
@@ -4022,7 +4566,9 @@ function resolveCommitment(db, commitmentEventId, resolution, options) {
          WHERE event_id = ? AND resolved_at IS NULL`
     ).run(resolution, now, now, commitmentEventId);
     if (Number(result.changes ?? 0) === 0) {
-      throw new AffinityStateError("commitment already resolved");
+      throw new AffinityConflictError(
+        `Commitment #${commitmentEventId} is already resolved (${open.resolution})`
+      );
     }
     const shouldCreateResolvingEvent = options?.resolvingEvent !== void 0 || resolution === "broken";
     const created = [];
@@ -4092,9 +4638,9 @@ var init_resolve_commitment = __esm({
     init_queries2();
     init_receipts2();
     init_validators();
+    init_affinity_conflict_error();
     init_affinity_invariant_error();
     init_affinity_not_found_error();
-    init_affinity_state_error();
     init_affinity_validation_error();
     init_resolve_now();
     init_with_transaction();
@@ -4127,9 +4673,25 @@ function ensureOwnerParticipates(db, participants) {
 function prepareParticipants(db, raw) {
   return ensureOwnerParticipates(db, raw.map(normalizeParticipant));
 }
-function manageCommitmentToolHandler(db, input) {
+function manageCommitmentToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageCommitmentTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     if (input.action === "record") {
+      if (!input.input)
+        return toolFailure(
+          "protocol",
+          "invalid_input",
+          "Missing input.",
+          "input is required for record."
+        );
       const patched = {
         ...input.input,
         participants: prepareParticipants(
@@ -4165,6 +4727,8 @@ var init_manage_commitment_tool = __esm({
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_validate_tool_input();
     manageCommitmentTool = defineAffinityTool({
       name: manageCommitmentToolName,
       description: "Record or resolve one commitment such as a promise or agreement. The owner contact is auto-injected into participants if missing.",
@@ -4206,7 +4770,7 @@ var init_manage_commitment_tool = __esm({
                     role: stringSchema("Participant role."),
                     directionality: stringSchema("Optional directionality.")
                   },
-                  ["contactId", "role"]
+                  ["role"]
                 ),
                 "Participant list. Must be non-empty and include the owner contact."
               ),
@@ -4255,6 +4819,163 @@ var init_manage_commitment_tool = __esm({
   }
 });
 
+// src/contacts/delete_contact.ts
+function deleteContact(db, locatorId, options) {
+  return withTransaction(db, () => {
+    const contact = db.prepare("SELECT is_owner FROM contacts WHERE id = ?").get(locatorId);
+    if (!contact) throw new AffinityNotFoundError("contact not found");
+    if (contact.is_owner)
+      throw new AffinityStateError("The owner contact cannot be deleted");
+    const tables = [
+      "contacts",
+      "identities",
+      "attributes",
+      "links",
+      "events",
+      "event_participants",
+      "open_commitments",
+      "contact_merges",
+      "dismissed_duplicates",
+      "link_event_effects",
+      "upcoming_occurrences",
+      "link_rollups",
+      "contact_rollups"
+    ];
+    const before = new Map(
+      tables.map((table) => [
+        table,
+        db.prepare(`SELECT rowid AS row_id, * FROM ${table}`).all()
+      ])
+    );
+    db.prepare(
+      "DELETE FROM events WHERE id IN (SELECT p.event_id FROM event_participants p WHERE p.contact_id = ? AND NOT EXISTS (SELECT 1 FROM event_participants q JOIN contacts c ON c.id = q.contact_id WHERE q.event_id = p.event_id AND q.contact_id != ? AND c.is_owner = 0))"
+    ).run(locatorId, locatorId);
+    db.prepare(
+      "DELETE FROM contact_merges WHERE winner_contact_id = ? OR loser_contact_id = ?"
+    ).run(locatorId, locatorId);
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
+    ).run(locatorId, locatorId);
+    db.prepare(
+      "UPDATE contacts SET merged_into_contact_id = NULL WHERE merged_into_contact_id = ?"
+    ).run(locatorId);
+    db.prepare("DELETE FROM contacts WHERE id = ?").run(locatorId);
+    const now = Date.now();
+    const affectedLinks = db.prepare(
+      "SELECT id FROM links WHERE removed_at IS NULL AND is_structural = 0"
+    ).all().map((row) => row.id);
+    refreshAllBridgeScores(db, now);
+    for (const id of affectedLinks) refreshLinkRollup(db, id, now);
+    for (const row of db.prepare("SELECT id FROM contacts").all())
+      refreshContactRollup(db, Number(row.id), now);
+    const removed = tables.map((table) => {
+      const remaining = new Set(
+        db.prepare(`SELECT rowid AS row_id FROM ${table}`).all().map((row) => row.row_id)
+      );
+      const ids = (before.get(table) ?? []).filter((row) => !remaining.has(row.row_id)).map((row) => Number(row.id ?? row.event_id ?? row.row_id));
+      return { entity: table, count: ids.length, ids };
+    }).filter((item) => item.count > 0);
+    return { contactId: locatorId, removed, affectedLinks };
+  });
+}
+var init_delete_contact = __esm({
+  "src/contacts/delete_contact.ts"() {
+    init_bridge_scores();
+    init_affinity_not_found_error();
+    init_affinity_state_error();
+    init_affinity_validation_error();
+    init_rollups2();
+    init_with_transaction();
+    init_rollups();
+  }
+});
+
+// src/contacts/export_contact.ts
+function exportContact(db, id) {
+  const query = (sql, ...params) => db.prepare(sql).all(...params).map((row) => {
+    const result = {};
+    for (const [key, value] of Object.entries(row)) {
+      const name = key.replace(
+        /_([a-z])/g,
+        (_, letter) => letter.toUpperCase()
+      );
+      result[name] = value;
+      if ((name.endsWith("At") || name === "dueAt") && typeof value === "number")
+        result[`${name}Iso`] = new Date(value).toISOString();
+      if (key.endsWith("_json") && typeof value === "string")
+        result[name] = JSON.parse(value);
+    }
+    return result;
+  });
+  const contact = query("SELECT * FROM contacts WHERE id = ?", id)[0];
+  if (!contact) throw new AffinityNotFoundError("contact not found");
+  const events = query(
+    "SELECT DISTINCT e.* FROM events e JOIN event_participants p ON p.event_id = e.id WHERE p.contact_id = ? ORDER BY e.id",
+    id
+  ).map((event) => ({
+    ...event,
+    participants: query(
+      "SELECT p.*, c.name AS contact_name FROM event_participants p JOIN contacts c ON c.id = p.contact_id WHERE event_id = ? ORDER BY p.contact_id",
+      event.id
+    )
+  }));
+  return {
+    contact,
+    identities: query(
+      "SELECT * FROM identities WHERE contact_id = ? ORDER BY id",
+      id
+    ),
+    attributes: query(
+      "SELECT * FROM attributes WHERE contact_id = ? OR link_id IN (SELECT id FROM links WHERE from_contact_id = ? OR to_contact_id = ?) ORDER BY id",
+      id,
+      id,
+      id
+    ),
+    links: query(
+      "SELECT l.*, f.name AS from_contact_name, t.name AS to_contact_name FROM links l JOIN contacts f ON f.id = l.from_contact_id JOIN contacts t ON t.id = l.to_contact_id WHERE from_contact_id = ? OR to_contact_id = ? ORDER BY l.id",
+      id,
+      id
+    ),
+    events,
+    commitments: query(
+      "SELECT o.* FROM open_commitments o JOIN event_participants p ON p.event_id = o.event_id WHERE p.contact_id = ? ORDER BY o.event_id",
+      id
+    ),
+    dates: query(
+      "SELECT * FROM events WHERE anchor_contact_id = ? OR anchor_link_id IN (SELECT id FROM links WHERE from_contact_id = ? OR to_contact_id = ?) ORDER BY id",
+      id,
+      id,
+      id
+    ),
+    mergeHistory: query(
+      "SELECT * FROM contact_merges WHERE winner_contact_id = ? OR loser_contact_id = ? ORDER BY id",
+      id,
+      id
+    )
+  };
+}
+var init_export_contact = __esm({
+  "src/contacts/export_contact.ts"() {
+    init_affinity_not_found_error();
+  }
+});
+
+// src/contacts/export_affinity.ts
+function exportAffinity(db) {
+  const now = Date.now();
+  return {
+    version: 1,
+    exportedAt: now,
+    exportedAtIso: new Date(now).toISOString(),
+    contacts: db.prepare("SELECT id FROM contacts ORDER BY id").all().map((row) => exportContact(db, row.id))
+  };
+}
+var init_export_affinity = __esm({
+  "src/contacts/export_affinity.ts"() {
+    init_export_contact();
+  }
+});
+
 // src/contacts/receipts.ts
 function buildContactMutationReceipt(primary, partial) {
   const normalized = normalizeMutationReceiptPartial(partial);
@@ -4286,66 +5007,6 @@ var init_receipts4 = __esm({
   }
 });
 
-// src/contacts/create_contact.ts
-function createContact(db, input) {
-  return withTransaction(db, () => {
-    const name = input.name.trim();
-    if (name.length === 0) {
-      throw new AffinityValidationError("name must be non-empty");
-    }
-    if (!KINDS.has(input.kind)) {
-      throw new AffinityValidationError("invalid contact kind");
-    }
-    const now = resolveNow(input.now);
-    if (input.bootstrapOwner) {
-      const existing = db.prepare(
-        "SELECT id FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
-      ).get();
-      if (existing !== void 0) {
-        throw new AffinityConflictError("owner already exists");
-      }
-    }
-    const isOwner = input.bootstrapOwner ? 1 : 0;
-    const result = db.prepare(
-      `INSERT INTO contacts (name, kind, lifecycle_state, is_owner, created_at, updated_at)
-         VALUES (?, ?, 'active', ?, ?, ?)`
-    ).run(name, input.kind, isOwner, now, now);
-    const id = Number(result.lastInsertRowid);
-    const row = getContactRowById(db, id);
-    if (!row) {
-      throw new AffinityInvariantError("inserted contact row not found");
-    }
-    refreshContactRollup(db, id, now);
-    const primary = mapContactRowToContactListItem(row);
-    return buildContactMutationReceipt(primary, {
-      created: [{ kind: "contact", id }]
-    });
-  });
-}
-var KINDS;
-var init_create_contact = __esm({
-  "src/contacts/create_contact.ts"() {
-    init_mappers4();
-    init_queries();
-    init_receipts4();
-    init_rollups();
-    init_affinity_conflict_error();
-    init_affinity_invariant_error();
-    init_affinity_validation_error();
-    init_resolve_now();
-    init_with_transaction();
-    KINDS = /* @__PURE__ */ new Set([
-      "human",
-      "group",
-      "company",
-      "team",
-      "pet",
-      "service",
-      "other"
-    ]);
-  }
-});
-
 // src/contacts/revise_contact.ts
 function reviseContact(db, contactId, patch) {
   return withTransaction(db, () => {
@@ -4401,7 +5062,9 @@ function assertValidLifecycleTransition(from, to) {
     throw new AffinityStateError("merged contact is read-only");
   }
   if (to === "merged") {
-    throw new AffinityInvariantError("use mergeContacts to reach merged state");
+    throw new AffinityInvariantError(
+      "use manage_contact merge (CLI: contact merge) to reach merged state"
+    );
   }
   if (from === to) {
     return;
@@ -4434,42 +5097,360 @@ function setContactLifecycle(db, contactId, lifecycleState, options) {
     }
     const row = getContactRowById(db, contactId);
     if (!row) {
-      throw new AffinityNotFoundError("contact not found");
-    }
-    const from = row.lifecycle_state;
-    assertValidLifecycleTransition(from, lifecycleState);
-    const now = resolveNow(options?.now);
-    if (from === lifecycleState) {
-      return buildContactMutationReceipt(mapContactRowToContactListItem(row), {
-        updated: []
-      });
+      throw new AffinityNotFoundError("contact not found");
+    }
+    const from = row.lifecycle_state;
+    assertValidLifecycleTransition(from, lifecycleState);
+    const now = resolveNow(options?.now);
+    if (from === lifecycleState) {
+      return buildContactMutationReceipt(mapContactRowToContactListItem(row), {
+        updated: []
+      });
+    }
+    db.prepare(
+      "UPDATE contacts SET lifecycle_state = ?, updated_at = ? WHERE id = ?"
+    ).run(lifecycleState, now, contactId);
+    refreshContactRollup(db, contactId, now);
+    const next = getContactRowById(db, contactId);
+    if (!next) {
+      throw new AffinityNotFoundError("contact not found");
+    }
+    return buildContactMutationReceipt(mapContactRowToContactListItem(next), {
+      updated: [{ kind: "contact", id: contactId }]
+    });
+  });
+}
+var STATES2;
+var init_set_contact_lifecycle = __esm({
+  "src/contacts/set_contact_lifecycle.ts"() {
+    init_mappers4();
+    init_queries();
+    init_receipts4();
+    init_rollups();
+    init_validators4();
+    init_affinity_not_found_error();
+    init_affinity_validation_error();
+    init_resolve_now();
+    init_with_transaction();
+    STATES2 = /* @__PURE__ */ new Set(["active", "dormant", "merged", "lost"]);
+  }
+});
+
+// src/contacts/create_contact.ts
+function createContact(db, input) {
+  return withTransaction(db, () => {
+    const name = input.name.trim();
+    if (name.length === 0) {
+      throw new AffinityValidationError("name must be non-empty");
+    }
+    if (!KINDS.has(input.kind)) {
+      throw new AffinityValidationError("invalid contact kind");
+    }
+    if (input.isOwner !== void 0) {
+      throw new AffinityValidationError(
+        "isOwner is read-only; pass bootstrapOwner: true to create the owner contact"
+      );
+    }
+    const now = resolveNow(input.now);
+    if (input.bootstrapOwner) {
+      const existing = db.prepare(
+        "SELECT id, name FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+      ).get();
+      if (existing !== void 0) {
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
+      }
+    }
+    const isOwner = input.bootstrapOwner ? 1 : 0;
+    const result = db.prepare(
+      `INSERT INTO contacts (name, kind, lifecycle_state, is_owner, created_at, updated_at)
+         VALUES (?, ?, 'active', ?, ?, ?)`
+    ).run(name, input.kind, isOwner, now, now);
+    const id = Number(result.lastInsertRowid);
+    const row = getContactRowById(db, id);
+    if (!row) {
+      throw new AffinityInvariantError("inserted contact row not found");
+    }
+    refreshContactRollup(db, id, now);
+    const primary = mapContactRowToContactListItem(row);
+    return buildContactMutationReceipt(primary, {
+      created: [{ kind: "contact", id }]
+    });
+  });
+}
+var KINDS;
+var init_create_contact = __esm({
+  "src/contacts/create_contact.ts"() {
+    init_mappers4();
+    init_queries();
+    init_receipts4();
+    init_rollups();
+    init_affinity_conflict_error();
+    init_affinity_invariant_error();
+    init_affinity_validation_error();
+    init_resolve_now();
+    init_with_transaction();
+    KINDS = /* @__PURE__ */ new Set([
+      "human",
+      "group",
+      "company",
+      "team",
+      "pet",
+      "service",
+      "other"
+    ]);
+  }
+});
+
+// src/contacts/fold_search_text.ts
+function foldSearchText(value) {
+  let folded = value.toLowerCase();
+  if (/[^\u0020-\u007e]/.test(folded))
+    folded = folded.replace(/ß/g, "ss").normalize("NFKD").replace(new RegExp("\\p{M}", "gu"), "");
+  return folded.replace(/ae/g, "a").replace(/oe/g, "o").replace(/ue/g, "u");
+}
+var init_fold_search_text = __esm({
+  "src/contacts/fold_search_text.ts"() {
+  }
+});
+
+// src/identities/queries.ts
+function getIdentityRowById(db, id) {
+  const row = db.prepare(
+    `SELECT id, contact_id, type, value, label, normalized_key, verified, verified_at,
+              created_at, updated_at, removed_at
+       FROM identities
+       WHERE id = ? AND removed_at IS NULL`
+  ).get(id);
+  if (row === void 0) {
+    return null;
+  }
+  return row;
+}
+var init_queries5 = __esm({
+  "src/identities/queries.ts"() {
+  }
+});
+
+// src/identities/receipts.ts
+function buildIdentityMutationReceipt(primary, partial) {
+  const normalized = normalizeMutationReceiptPartial(partial);
+  return {
+    primary,
+    created: normalized.created,
+    updated: normalized.updated,
+    archived: normalized.archived,
+    removed: normalized.removed,
+    affectedLinks: normalized.affectedLinks,
+    derivedEffects: normalized.derivedEffects
+  };
+}
+var init_receipts5 = __esm({
+  "src/identities/receipts.ts"() {
+    init_normalize_mutation_receipt();
+  }
+});
+
+// src/identities/validators.ts
+function assertNoIdentityCollision(db, normalizedKey, excludeIdentityId) {
+  const row = excludeIdentityId === void 0 ? db.prepare(
+    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL"
+  ).get(normalizedKey) : db.prepare(
+    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL AND id != ?"
+  ).get(normalizedKey, excludeIdentityId);
+  if (row !== void 0) {
+    const owner = db.prepare(
+      "SELECT c.id, c.name FROM contacts c JOIN identities i ON i.contact_id = c.id WHERE i.normalized_key = ? AND i.removed_at IS NULL"
+    ).get(normalizedKey);
+    throw new AffinityConflictError(
+      `${normalizedKey.replace(":", " ")} already belongs to #${owner?.id} ${owner?.name}`
+    );
+  }
+}
+var init_validators5 = __esm({
+  "src/identities/validators.ts"() {
+    init_affinity_conflict_error();
+  }
+});
+
+// src/identities/validate_identity_input.ts
+function validateIdentityInput(type, value) {
+  const kind = type.toLowerCase();
+  if (!identityTypes.includes(kind) && !/^custom:[a-z0-9_-]+$/.test(type))
+    throw new AffinityValidationError(
+      `identity type must be one of ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen)`
+    );
+  if (!value.trim())
+    throw new AffinityValidationError("identity value must be non-empty");
+  if (kind === "email" && !/^[^\s@]+@[^\s@.]+(?:\.[^\s@.]+)+$/.test(value))
+    throw new AffinityValidationError(
+      "email value must match local@domain.tld"
+    );
+  if (kind === "phone" && value.replace(/\D/g, "").length < 5)
+    throw new AffinityValidationError(
+      "phone value must contain at least 5 digits"
+    );
+  if (kind === "url" || kind === "website") {
+    try {
+      const url = new URL(value.includes("://") ? value : `https://${value}`);
+      if (!["http:", "https:"].includes(url.protocol) || !url.hostname || /\s/.test(value))
+        throw new Error();
+    } catch {
+      throw new AffinityValidationError(
+        "url/website value must be an http/https URL or bare domain"
+      );
+    }
+  }
+}
+var identityTypes;
+var init_validate_identity_input = __esm({
+  "src/identities/validate_identity_input.ts"() {
+    init_affinity_validation_error();
+    identityTypes = [
+      "email",
+      "phone",
+      "url",
+      "website",
+      "handle",
+      "x",
+      "twitter",
+      "linkedin",
+      "github",
+      "mastodon",
+      "bluesky",
+      "telegram",
+      "whatsapp",
+      "signal",
+      "matrix",
+      "discord",
+      "slack",
+      "instagram",
+      "facebook",
+      "youtube",
+      "tiktok",
+      "address",
+      "other",
+      "account_id",
+      "alias"
+    ];
+  }
+});
+
+// src/identities/add_identity.ts
+function addIdentity(db, contactId, input) {
+  return withTransaction(db, () => {
+    const contact = getContactRowById(db, contactId);
+    if (!contact) {
+      throw new AffinityNotFoundError("contact not found");
+    }
+    if (contact.lifecycle_state === "merged") {
+      throw new AffinityStateError("merged contact is read-only");
+    }
+    const type = input.type.trim();
+    const value = input.value.trim();
+    if (type.length === 0 || value.length === 0) {
+      throw new AffinityValidationError("type and value must be non-empty");
+    }
+    validateIdentityInput(type, value);
+    const nk = normalizeIdentityKey(type, value);
+    assertNoIdentityCollision(db, nk);
+    const now = resolveNow(input.now);
+    const verified = input.verified ? 1 : 0;
+    const verifiedAt = verified === 1 ? now : null;
+    const result = db.prepare(
+      `INSERT INTO identities (contact_id, type, value, label, normalized_key, verified, verified_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      contactId,
+      type,
+      value,
+      input.label ?? null,
+      nk,
+      verified,
+      verifiedAt,
+      now,
+      now
+    );
+    const id = Number(result.lastInsertRowid);
+    const row = getIdentityRowById(db, id);
+    if (!row) {
+      throw new AffinityInvariantError("inserted identity not found");
     }
-    db.prepare(
-      "UPDATE contacts SET lifecycle_state = ?, updated_at = ? WHERE id = ?"
-    ).run(lifecycleState, now, contactId);
     refreshContactRollup(db, contactId, now);
-    const next = getContactRowById(db, contactId);
-    if (!next) {
-      throw new AffinityNotFoundError("contact not found");
-    }
-    return buildContactMutationReceipt(mapContactRowToContactListItem(next), {
-      updated: [{ kind: "contact", id: contactId }]
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
+    ).run(contactId, contactId);
+    return buildIdentityMutationReceipt(mapIdentityRowToIdentityRecord(row), {
+      created: [{ kind: "identity", id }]
     });
   });
 }
-var STATES2;
-var init_set_contact_lifecycle = __esm({
-  "src/contacts/set_contact_lifecycle.ts"() {
-    init_mappers4();
+var init_add_identity = __esm({
+  "src/identities/add_identity.ts"() {
     init_queries();
-    init_receipts4();
     init_rollups();
-    init_validators4();
+    init_mappers2();
+    init_normalize();
+    init_queries5();
+    init_receipts5();
+    init_validators5();
+    init_affinity_invariant_error();
     init_affinity_not_found_error();
+    init_affinity_state_error();
     init_affinity_validation_error();
     init_resolve_now();
     init_with_transaction();
-    STATES2 = /* @__PURE__ */ new Set(["active", "dormant", "merged", "lost"]);
+    init_validate_identity_input();
+  }
+});
+
+// src/tools/create_contact_tool_result.ts
+function createContactToolResult(db, input) {
+  return withTransaction(db, () => {
+    const receipt = createContact(db, input);
+    const identityOwners = /* @__PURE__ */ new Set();
+    for (const identity of input.identities ?? []) {
+      validateIdentityInput(identity.type.trim(), identity.value.trim());
+      const existing = db.prepare(
+        "SELECT contact_id FROM identities WHERE normalized_key = ? AND removed_at IS NULL"
+      ).get(normalizeIdentityKey(identity.type, identity.value));
+      if (existing) {
+        if (Number(existing.contact_id) !== receipt.primary.id)
+          identityOwners.add(Number(existing.contact_id));
+        continue;
+      }
+      const added = addIdentity(db, receipt.primary.id, identity);
+      receipt.created.push(...added.created);
+    }
+    const result = mutationToolResult("create", receipt, "contact");
+    const fold = (name) => foldSearchText(name).trim().replace(/\s+/g, " ");
+    const warnings = db.prepare(
+      "SELECT id, name FROM contacts WHERE id != ? AND deleted_at IS NULL AND lifecycle_state IN ('active', 'dormant')"
+    ).all(receipt.primary.id).flatMap((row) => {
+      const score = identityOwners.has(row.id) ? 1 : fold(row.name) === fold(input.name) ? 0.92 : void 0;
+      return score === void 0 ? [] : [
+        {
+          code: "possible_duplicate",
+          message: `Possible duplicate of #${row.id} ${row.name} (score ${score})`,
+          contactId: row.id,
+          score
+        }
+      ];
+    });
+    if (warnings.length) result.warnings = warnings;
+    return result;
+  });
+}
+var init_create_contact_tool_result = __esm({
+  "src/tools/create_contact_tool_result.ts"() {
+    init_create_contact();
+    init_fold_search_text();
+    init_add_identity();
+    init_normalize();
+    init_validate_identity_input();
+    init_with_transaction();
+    init_tool_mutation();
   }
 });
 
@@ -4491,24 +5472,76 @@ function contactLocatorSchema3(description) {
     description
   };
 }
-function manageContactToolHandler(db, input) {
+function manageContactToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageContactTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
-    if (input.action === "create") {
-      return mutationToolResult(
-        "create",
-        createContact(db, input.input),
-        "contact"
+    if (input.action === "export") {
+      if (!input.contact)
+        return toolSuccess("Exported Affinity.", {
+          action: "export",
+          export: exportAffinity(db)
+        });
+      const target = resolveContactLocator(db, input.contact, "contact", true);
+      if (!target.ok) return target.result;
+      return toolSuccess("Exported contact.", {
+        action: "export",
+        export: exportContact(db, target.value.id)
+      });
+    }
+    if (input.action === "delete" && input.confirm !== true)
+      return toolFailure(
+        "protocol",
+        "invalid_input",
+        "Delete requires confirmation.",
+        "delete is permanent; pass confirm: true (CLI: --confirm)"
       );
+    if (input.action === "create") {
+      if (!input.input)
+        return toolFailure(
+          "protocol",
+          "invalid_input",
+          "Missing input.",
+          "input is required for create."
+        );
+      return createContactToolResult(db, input.input);
     }
-    const contact = resolveContactLocator(db, input.contact, "contact");
+    const contact = resolveContactLocator(
+      db,
+      input.contact,
+      "contact",
+      input.action === "delete"
+    );
     if (!contact.ok) {
       return contact.result;
     }
+    if (input.action === "delete") {
+      const deletion = deleteContact(db, contact.value.id, { confirm: true });
+      return toolSuccess("Permanently deleted contact.", {
+        action: "delete",
+        deletion,
+        changes: deletion.removed.flatMap(
+          (item) => item.ids.map((id) => ({
+            entity: item.entity,
+            id,
+            action: "removed"
+          }))
+        )
+      });
+    }
     if (input.action === "revise") {
       return mutationToolResult(
         "revise",
         reviseContact(db, contact.value.id, input.patch),
-        "contact"
+        "contact",
+        Object.keys(input.patch)
       );
     }
     return mutationToolResult(
@@ -4526,16 +5559,22 @@ function manageContactToolHandler(db, input) {
 var manageContactTool;
 var init_manage_contact_tool = __esm({
   "src/tools/manage_contact_tool.ts"() {
-    init_create_contact();
+    init_delete_contact();
+    init_export_affinity();
+    init_export_contact();
     init_revise_contact();
     init_set_contact_lifecycle();
+    init_create_contact_tool_result();
     init_tool_metadata();
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_tool_types();
+    init_validate_tool_input();
     manageContactTool = defineAffinityTool({
       name: manageContactToolName,
-      description: "Create a contact, revise one contact's core fields, or change lifecycle state. ALWAYS search_affinity first before creating \u2014 duplicates corrupt the graph.",
+      description: "Create, revise, export or permanently delete a contact (confirm: true required; owner cannot be deleted). Export without contact exports the whole database. Lifecycle lost is soft delete. ALWAYS search_affinity first before creating \u2014 duplicates corrupt the graph.",
       whenToUse: "Use this for contact creation and lifecycle-safe contact maintenance.",
       whenNotToUse: "Do not use this for identities, links, attributes, or merges.",
       sideEffects: "writes_state",
@@ -4556,10 +5595,25 @@ var init_manage_contact_tool = __esm({
           action: enumSchema("Operation to perform.", [
             "create",
             "revise",
-            "set_lifecycle"
+            "set_lifecycle",
+            "export",
+            "delete"
           ]),
           input: objectSchema(
             {
+              identities: arraySchema(
+                objectSchema(
+                  {
+                    type: stringSchema("Identity type."),
+                    value: stringSchema("Identity value."),
+                    label: stringSchema("Optional label."),
+                    verified: booleanSchema("Verified identity."),
+                    now: integerSchema("Optional timestamp.")
+                  },
+                  ["type", "value"]
+                ),
+                "Optional identities to attach. Identities already owned by another contact are left with that owner and reported as possible duplicates."
+              ),
               name: stringSchema("Contact name."),
               kind: enumSchema("Contact kind.", [
                 "human",
@@ -4578,6 +5632,7 @@ var init_manage_contact_tool = __esm({
             ["name", "kind"],
             "New contact payload. Required when action=create."
           ),
+          confirm: booleanSchema("Required true for permanent deletion."),
           contact: contactLocatorSchema3(
             "Target contact. Required when action=revise or set_lifecycle. Provide contactId or identity."
           ),
@@ -4847,9 +5902,32 @@ function resolveDateAnchorTarget(db, target) {
   }
   return { kind: "ok", target: { kind: "link", linkId: link.value.id } };
 }
-function manageDateAnchorToolHandler(db, input) {
+function manageDateAnchorToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageDateAnchorTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
+  if (input.action !== "add" && input.anchorEventId === void 0)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Missing anchorEventId.",
+      "anchorEventId is required."
+    );
   return withToolHandling(() => {
     if (input.action === "add") {
+      if (!input.input)
+        return toolFailure(
+          "protocol",
+          "invalid_input",
+          "Missing input.",
+          "input is required for add."
+        );
       const resolved = resolveDateAnchorTarget(db, input.input.target);
       if (resolved.kind === "error") {
         return resolved.result;
@@ -4864,7 +5942,8 @@ function manageDateAnchorToolHandler(db, input) {
       return mutationToolResult(
         "revise",
         reviseDateAnchor(db, input.anchorEventId, input.patch, input.options),
-        "date anchor"
+        "date anchor",
+        Object.keys(input.patch)
       );
     }
     return mutationToolResult(
@@ -4884,6 +5963,8 @@ var init_manage_date_anchor_tool = __esm({
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_validate_tool_input();
     manageDateAnchorTool = defineAffinityTool({
       name: manageDateAnchorToolName,
       description: "Add, revise, or remove recurring date anchors on contacts or links. Use this for birthdays, anniversaries, and yearly events \u2014 not manage_attribute.",
@@ -4997,7 +6078,7 @@ function buildDismissalMutationReceipt(primary, partial) {
     derivedEffects: normalized.derivedEffects
   };
 }
-var init_receipts5 = __esm({
+var init_receipts6 = __esm({
   "src/merges/receipts.ts"() {
     init_normalize_mutation_receipt();
   }
@@ -5059,7 +6140,7 @@ var init_dismiss_duplicate = __esm({
     init_affinity_validation_error();
     init_resolve_now();
     init_with_transaction();
-    init_receipts5();
+    init_receipts6();
   }
 });
 
@@ -5098,7 +6179,7 @@ var init_undismiss_duplicate = __esm({
     init_affinity_not_found_error();
     init_affinity_validation_error();
     init_with_transaction();
-    init_receipts5();
+    init_receipts6();
   }
 });
 
@@ -5120,7 +6201,19 @@ function contactLocatorSchema5(description) {
     description
   };
 }
-function manageDuplicateDismissalToolHandler(db, input) {
+function manageDuplicateDismissalToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(
+    manageDuplicateDismissalTool.inputSchema,
+    input
+  );
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const left = resolveContactLocator(db, input.left, "left");
     if (!left.ok) {
@@ -5130,6 +6223,11 @@ function manageDuplicateDismissalToolHandler(db, input) {
     if (!right.ok) {
       return right.result;
     }
+    const leftContactId = Math.min(left.value.id, right.value.id);
+    const rightContactId = Math.max(left.value.id, right.value.id);
+    const existed = db.prepare(
+      "SELECT 1 FROM dismissed_duplicates WHERE left_id = ? AND right_id = ?"
+    ).get(leftContactId, rightContactId) !== void 0;
     if (input.action === "dismiss") {
       const receipt2 = dismissDuplicate(
         db,
@@ -5139,13 +6237,35 @@ function manageDuplicateDismissalToolHandler(db, input) {
       );
       return toolSuccess(
         `Dismissed pair #${receipt2.primary.leftContactId} / #${receipt2.primary.rightContactId}.`,
-        { action: "dismiss", primary: receipt2.primary }
+        {
+          ...receipt2,
+          action: "dismiss",
+          changes: [
+            {
+              entity: "duplicate_dismissal",
+              leftContactId,
+              rightContactId,
+              action: existed ? "updated" : "created"
+            }
+          ]
+        }
       );
     }
     const receipt = undismissDuplicate(db, left.value.id, right.value.id);
     return toolSuccess(
       `Un-dismissed pair #${receipt.primary.leftContactId} / #${receipt.primary.rightContactId}.`,
-      { action: "undismiss", primary: receipt.primary }
+      {
+        ...receipt,
+        action: "undismiss",
+        changes: existed ? [
+          {
+            entity: "duplicate_dismissal",
+            leftContactId,
+            rightContactId,
+            action: "removed"
+          }
+        ] : []
+      }
     );
   }, "Duplicate dismissal failed.");
 }
@@ -5158,9 +6278,11 @@ var init_manage_duplicate_dismissal_tool = __esm({
     init_tool_names();
     init_tool_resolvers();
     init_tool_types();
+    init_tool_types();
+    init_validate_tool_input();
     manageDuplicateDismissalTool = defineAffinityTool({
       name: manageDuplicateDismissalToolName,
-      description: "Dismiss or un-dismiss a duplicate candidate pair so it does not resurface in listDuplicateCandidates.",
+      description: "Dismiss or un-dismiss a duplicate candidate pair so it does not resurface in review_affinity contacts.duplicates.",
       whenToUse: "Use dismiss after confirming two contacts are different people (not duplicates). Use undismiss to re-surface a pair for re-evaluation.",
       whenNotToUse: "Do not use this to merge contacts \u2014 use merge_contacts for confirmed duplicates.",
       sideEffects: "writes_state",
@@ -5176,142 +6298,20 @@ var init_manage_duplicate_dismissal_tool = __esm({
       outputDescription: "Returns the dismissal receipt with the canonical pair identifiers.",
       inputSchema: objectSchema(
         {
-          action: enumSchema("Action to perform.", ["dismiss", "undismiss"]),
-          left: contactLocatorSchema5(
-            "Left contact. Provide contactId or identity."
-          ),
-          right: contactLocatorSchema5(
-            "Right contact. Provide contactId or identity."
-          ),
-          reason: nullableStringSchema("Optional reason for the dismissal.")
-        },
-        ["action", "left", "right"],
-        "Dismiss or un-dismiss a duplicate candidate pair."
-      ),
-      handler: manageDuplicateDismissalToolHandler
-    });
-  }
-});
-
-// src/identities/queries.ts
-function getIdentityRowById(db, id) {
-  const row = db.prepare(
-    `SELECT id, contact_id, type, value, label, normalized_key, verified, verified_at,
-              created_at, updated_at, removed_at
-       FROM identities
-       WHERE id = ? AND removed_at IS NULL`
-  ).get(id);
-  if (row === void 0) {
-    return null;
-  }
-  return row;
-}
-var init_queries5 = __esm({
-  "src/identities/queries.ts"() {
-  }
-});
-
-// src/identities/receipts.ts
-function buildIdentityMutationReceipt(primary, partial) {
-  const normalized = normalizeMutationReceiptPartial(partial);
-  return {
-    primary,
-    created: normalized.created,
-    updated: normalized.updated,
-    archived: normalized.archived,
-    removed: normalized.removed,
-    affectedLinks: normalized.affectedLinks,
-    derivedEffects: normalized.derivedEffects
-  };
-}
-var init_receipts6 = __esm({
-  "src/identities/receipts.ts"() {
-    init_normalize_mutation_receipt();
-  }
-});
-
-// src/identities/validators.ts
-function assertNoIdentityCollision(db, normalizedKey, excludeIdentityId) {
-  const row = excludeIdentityId === void 0 ? db.prepare(
-    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL"
-  ).get(normalizedKey) : db.prepare(
-    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL AND id != ?"
-  ).get(normalizedKey, excludeIdentityId);
-  if (row !== void 0) {
-    throw new AffinityConflictError(
-      "another contact already owns this normalized identity"
-    );
-  }
-}
-var init_validators5 = __esm({
-  "src/identities/validators.ts"() {
-    init_affinity_conflict_error();
-  }
-});
-
-// src/identities/add_identity.ts
-function addIdentity(db, contactId, input) {
-  return withTransaction(db, () => {
-    const contact = getContactRowById(db, contactId);
-    if (!contact) {
-      throw new AffinityNotFoundError("contact not found");
-    }
-    if (contact.lifecycle_state === "merged") {
-      throw new AffinityStateError("merged contact is read-only");
-    }
-    const type = input.type.trim();
-    const value = input.value.trim();
-    if (type.length === 0 || value.length === 0) {
-      throw new AffinityValidationError("type and value must be non-empty");
-    }
-    const nk = normalizeIdentityKey(type, value);
-    assertNoIdentityCollision(db, nk);
-    const now = resolveNow(input.now);
-    const verified = input.verified ? 1 : 0;
-    const verifiedAt = verified === 1 ? now : null;
-    const result = db.prepare(
-      `INSERT INTO identities (contact_id, type, value, label, normalized_key, verified, verified_at, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
-    ).run(
-      contactId,
-      type,
-      value,
-      input.label ?? null,
-      nk,
-      verified,
-      verifiedAt,
-      now,
-      now
-    );
-    const id = Number(result.lastInsertRowid);
-    const row = getIdentityRowById(db, id);
-    if (!row) {
-      throw new AffinityInvariantError("inserted identity not found");
-    }
-    refreshContactRollup(db, contactId, now);
-    db.prepare(
-      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
-    ).run(contactId, contactId);
-    return buildIdentityMutationReceipt(mapIdentityRowToIdentityRecord(row), {
-      created: [{ kind: "identity", id }]
-    });
-  });
-}
-var init_add_identity = __esm({
-  "src/identities/add_identity.ts"() {
-    init_queries();
-    init_rollups();
-    init_mappers2();
-    init_normalize();
-    init_queries5();
-    init_receipts6();
-    init_validators5();
-    init_affinity_invariant_error();
-    init_affinity_not_found_error();
-    init_affinity_state_error();
-    init_affinity_validation_error();
-    init_resolve_now();
-    init_with_transaction();
+          action: enumSchema("Action to perform.", ["dismiss", "undismiss"]),
+          left: contactLocatorSchema5(
+            "Left contact. Provide contactId or identity."
+          ),
+          right: contactLocatorSchema5(
+            "Right contact. Provide contactId or identity."
+          ),
+          reason: nullableStringSchema("Optional reason for the dismissal.")
+        },
+        ["action", "left", "right"],
+        "Dismiss or un-dismiss a duplicate candidate pair."
+      ),
+      handler: manageDuplicateDismissalToolHandler
+    });
   }
 });
 
@@ -5346,7 +6346,7 @@ var init_remove_identity = __esm({
     init_rollups();
     init_mappers2();
     init_queries5();
-    init_receipts6();
+    init_receipts5();
     init_affinity_not_found_error();
     init_affinity_state_error();
     init_resolve_now();
@@ -5379,6 +6379,7 @@ function reviseIdentity(db, identityId, patch) {
     if (nextType.length === 0 || nextValue.length === 0) {
       throw new AffinityValidationError("type and value must be non-empty");
     }
+    validateIdentityInput(nextType, nextValue);
     const nextLabel = patch.label !== void 0 ? patch.label : row.label;
     const nkNext = normalizeIdentityKey(nextType, nextValue);
     if (nkNext !== row.normalized_key) {
@@ -5404,13 +6405,14 @@ var init_revise_identity = __esm({
     init_mappers2();
     init_normalize();
     init_queries5();
-    init_receipts6();
+    init_receipts5();
     init_validators5();
     init_affinity_not_found_error();
     init_affinity_state_error();
     init_affinity_validation_error();
     init_resolve_now();
     init_with_transaction();
+    init_validate_identity_input();
   }
 });
 
@@ -5444,7 +6446,7 @@ var init_verify_identity = __esm({
     init_queries();
     init_mappers2();
     init_queries5();
-    init_receipts6();
+    init_receipts5();
     init_affinity_not_found_error();
     init_affinity_state_error();
     init_resolve_now();
@@ -5460,7 +6462,9 @@ function contactLocatorSchema6(description) {
       contactId: integerSchema("Exact contact id."),
       identity: objectSchema(
         {
-          type: stringSchema("Identity type."),
+          type: stringSchema(
+            `Identity type: ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen).`
+          ),
           value: stringSchema("Identity value.")
         },
         ["type", "value"],
@@ -5470,7 +6474,23 @@ function contactLocatorSchema6(description) {
     description
   };
 }
-function manageIdentityToolHandler(db, input) {
+function manageIdentityToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageIdentityTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
+  if (input.action !== "add" && input.identityId === void 0)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Missing identityId.",
+      "identityId is required."
+    );
   return withToolHandling(() => {
     switch (input.action) {
       case "add": {
@@ -5488,7 +6508,8 @@ function manageIdentityToolHandler(db, input) {
         return mutationToolResult(
           "revise",
           reviseIdentity(db, input.identityId, input.patch),
-          "identity"
+          "identity",
+          Object.keys(input.patch)
         );
       case "verify":
         return mutationToolResult(
@@ -5511,11 +6532,14 @@ var init_manage_identity_tool = __esm({
     init_add_identity();
     init_remove_identity();
     init_revise_identity();
+    init_validate_identity_input();
     init_verify_identity();
     init_tool_metadata();
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_validate_tool_input();
     manageIdentityTool = defineAffinityTool({
       name: manageIdentityToolName,
       description: "Add, revise, verify, or remove one routing identity on a contact. Use this for emails, phone numbers, social handles, and URLs \u2014 anything that could locate a person. Do not use manage_attribute for these.",
@@ -5548,7 +6572,9 @@ var init_manage_identity_tool = __esm({
           ),
           input: objectSchema(
             {
-              type: stringSchema("Identity type."),
+              type: stringSchema(
+                `Identity type: ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen).`
+              ),
               value: stringSchema("Identity value."),
               label: stringSchema("Optional label."),
               verified: booleanSchema("Whether the identity starts verified."),
@@ -5562,7 +6588,9 @@ var init_manage_identity_tool = __esm({
           ),
           patch: objectSchema(
             {
-              type: stringSchema("Optional identity type."),
+              type: stringSchema(
+                `Optional identity type: ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen).`
+              ),
               value: stringSchema("Optional identity value."),
               label: stringSchema("Optional label.")
             },
@@ -5833,7 +6861,19 @@ function linkLocatorSchema4(description) {
     description
   };
 }
-function manageRelationshipToolHandler(db, input) {
+function manageRelationshipToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(
+    manageRelationshipTool.inputSchema,
+    input
+  );
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     switch (input.action) {
       case "seed_social_link": {
@@ -5932,6 +6972,8 @@ var init_manage_relationship_tool = __esm({
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_validate_tool_input();
     manageRelationshipTool = defineAffinityTool({
       name: manageRelationshipToolName,
       description: "Seed social links, revise bond and state, and manage structural ties. Seed a link as soon as a relationship is mentioned \u2014 do not wait for repeated evidence.",
@@ -6237,7 +7279,16 @@ function contactLocatorSchema8(description) {
     description
   };
 }
-function mergeContactsToolHandler(db, input) {
+function mergeContactsToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(mergeContactsTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const winner = resolveContactLocator(db, input.winner, "winner");
     if (!winner.ok) {
@@ -6267,6 +7318,8 @@ var init_merge_contacts_tool = __esm({
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_validate_tool_input();
     mergeContactsTool = defineAffinityTool({
       name: mergeContactsToolName,
       description: "Merge one loser contact into one winner contact using explicit contact locators.",
@@ -6526,7 +7579,16 @@ function prepareParticipants2(db, raw, injectOwner) {
   const normalized = raw.map(normalizeParticipant2);
   return injectOwner ? ensureOwnerParticipates2(db, normalized) : normalized;
 }
-function recordEventToolHandler(db, input) {
+function recordEventToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(recordEventTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const patched = {
       ...input.input,
@@ -6576,6 +7638,8 @@ var init_record_event_tool = __esm({
     init_tool_mutation();
     init_tool_names();
     init_tool_resolvers();
+    init_tool_types();
+    init_validate_tool_input();
     recordEventTool = defineAffinityTool({
       name: recordEventToolName,
       description: "Record one social event such as an interaction, observation, milestone, or transaction. For interactions, milestones, and transactions the owner contact is auto-injected into participants if missing. Observations may omit the owner when recording third-party evidence.",
@@ -6636,7 +7700,7 @@ var init_record_event_tool = __esm({
                       "observed"
                     ])
                   },
-                  ["contactId", "role"]
+                  ["role"]
                 ),
                 "Participant list. Must be non-empty and include the owner contact."
               ),
@@ -6654,6 +7718,27 @@ var init_record_event_tool = __esm({
   }
 });
 
+// src/contacts/contact_attribute_clauses.ts
+function contactAttributeClauses(filters) {
+  const clauses = [];
+  const params = [];
+  const attributes = filters?.attribute === void 0 ? [] : [filters.attribute].flat();
+  const tags = filters?.tag === void 0 ? [] : [filters.tag].flat();
+  for (const filter of [...attributes, ...tags.map((tag) => `tag:${tag}`)]) {
+    const separator = filter.indexOf("=");
+    const name = separator < 0 ? filter : filter.slice(0, separator);
+    clauses.push(`EXISTS (SELECT 1 FROM attributes a WHERE a.contact_id = contacts.id
+      AND a.deleted_at IS NULL AND lower(a.name) = lower(?)${separator < 0 ? "" : " AND lower(CAST(CASE WHEN json_valid(a.value) THEN json_extract(a.value, '$') ELSE a.value END AS TEXT)) = lower(?)"})`);
+    params.push(name);
+    if (separator >= 0) params.push(filter.slice(separator + 1));
+  }
+  return { clauses, params };
+}
+var init_contact_attribute_clauses = __esm({
+  "src/contacts/contact_attribute_clauses.ts"() {
+  }
+});
+
 // src/contacts/list_contacts.ts
 function listContacts(db, filters, options) {
   assertDefaultOrdering("listContacts", options);
@@ -6677,6 +7762,9 @@ function listContacts(db, filters, options) {
   if (filters?.includeDormant === false || options?.includeDormant === false) {
     clauses.push("lifecycle_state != 'dormant'");
   }
+  const attributeFilters = contactAttributeClauses(filters);
+  clauses.push(...attributeFilters.clauses);
+  params.push(...attributeFilters.params);
   const where = clauses.join(" AND ");
   const rows = db.prepare(
     `SELECT id, name, kind, lifecycle_state, is_owner, merged_into_contact_id,
@@ -6705,6 +7793,7 @@ var init_list_contacts = __esm({
   "src/contacts/list_contacts.ts"() {
     init_assert_default_ordering();
     init_resolve_list_limit_offset();
+    init_contact_attribute_clauses();
     init_mappers4();
   }
 });
@@ -6932,131 +8021,6 @@ var init_list_upcoming_dates = __esm({
   }
 });
 
-// src/events/get_contact_journal.ts
-function getContactJournal(db, contactId, options) {
-  assertDefaultOrdering("getContactJournal", options);
-  const { limit, offset } = resolveListLimitOffset(options);
-  const clauses = ["e.deleted_at IS NULL", "ep.contact_id = ?"];
-  const params = [contactId];
-  if (options?.since !== void 0) {
-    clauses.push("e.occurred_at >= ?");
-    params.push(options.since);
-  }
-  if (options?.until !== void 0) {
-    clauses.push("e.occurred_at <= ?");
-    params.push(options.until);
-  }
-  if (options?.eventTypes !== void 0 && options.eventTypes.length > 0) {
-    const ph = options.eventTypes.map(() => "?").join(", ");
-    clauses.push(`e.type IN (${ph})`);
-    params.push(...options.eventTypes);
-  }
-  const where = clauses.join(" AND ");
-  const rows = db.prepare(
-    `SELECT e.id FROM events e
-       INNER JOIN event_participants ep ON ep.event_id = e.id
-       WHERE ${where}
-       ORDER BY e.occurred_at DESC, e.id DESC
-       LIMIT ? OFFSET ?`
-  ).all(...params, limit, offset);
-  return batchLoadEventRecords(
-    db,
-    rows.map((r) => r.id)
-  );
-}
-var init_get_contact_journal = __esm({
-  "src/events/get_contact_journal.ts"() {
-    init_assert_default_ordering();
-    init_resolve_list_limit_offset();
-    init_loaders();
-  }
-});
-
-// src/events/list_open_commitments.ts
-function mapResolution(resolvedAt, resolution) {
-  if (resolvedAt === null) {
-    return "open";
-  }
-  if (resolution === "cancelled") {
-    return "cancelled";
-  }
-  return "resolved";
-}
-function listOpenCommitments(db, filters, options) {
-  assertDefaultOrdering("listOpenCommitments", options);
-  const { limit, offset } = resolveListLimitOffset(options);
-  const clauses = ["e.deleted_at IS NULL", "oc.resolved_at IS NULL"];
-  const params = [];
-  if (options?.since !== void 0) {
-    clauses.push("e.occurred_at >= ?");
-    params.push(options.since);
-  }
-  if (options?.until !== void 0) {
-    clauses.push("e.occurred_at <= ?");
-    params.push(options.until);
-  }
-  if (filters?.commitmentType !== void 0) {
-    if (filters.commitmentType !== "promise" && filters.commitmentType !== "agreement") {
-      throw new AffinityValidationError("invalid commitmentType filter");
-    }
-    clauses.push("oc.commitment_type = ?");
-    params.push(filters.commitmentType);
-  }
-  if (filters?.contactId !== void 0) {
-    clauses.push(
-      "EXISTS (SELECT 1 FROM event_participants ep WHERE ep.event_id = oc.event_id AND ep.contact_id = ?)"
-    );
-    params.push(filters.contactId);
-  }
-  if (filters?.linkId !== void 0) {
-    clauses.push(
-      "EXISTS (SELECT 1 FROM link_event_effects le WHERE le.event_id = oc.event_id AND le.link_id = ?)"
-    );
-    params.push(filters.linkId);
-  }
-  if (filters?.horizonDays !== void 0) {
-    if (!Number.isInteger(filters.horizonDays) || filters.horizonDays < 0) {
-      throw new AffinityValidationError(
-        "horizonDays must be a non-negative integer"
-      );
-    }
-    const anchor = options?.since ?? Date.now();
-    clauses.push("oc.due_at IS NOT NULL");
-    clauses.push("oc.due_at <= ?");
-    params.push(anchor + filters.horizonDays * DAY_MS3);
-  }
-  const where = clauses.join(" AND ");
-  const rows = db.prepare(
-    `SELECT oc.event_id, oc.commitment_type, oc.due_at, oc.resolved_at, oc.resolution,
-              e.type, e.summary
-       FROM open_commitments oc
-       INNER JOIN events e ON e.id = oc.event_id
-       WHERE ${where}
-       ORDER BY oc.due_at IS NULL, oc.due_at ASC, oc.created_at ASC
-       LIMIT ? OFFSET ?`
-  ).all(...params, limit, offset);
-  const eventIds = rows.map((r) => r.event_id);
-  const partsByEvent = batchLoadEventParticipantViews(db, eventIds);
-  return rows.map((r) => ({
-    eventId: r.event_id,
-    type: r.type,
-    summary: r.summary,
-    participants: partsByEvent.get(r.event_id) ?? [],
-    dueAt: r.due_at,
-    resolutionState: mapResolution(r.resolved_at, r.resolution)
-  }));
-}
-var DAY_MS3;
-var init_list_open_commitments = __esm({
-  "src/events/list_open_commitments.ts"() {
-    init_affinity_validation_error();
-    init_assert_default_ordering();
-    init_resolve_list_limit_offset();
-    init_loaders();
-    DAY_MS3 = 864e5;
-  }
-});
-
 // src/graph/get_affinity_chart.ts
 function getAffinityChart(db, options) {
   const contactClauses = [
@@ -7290,13 +8254,15 @@ function listRadar(db, filters, options) {
   if (ownerId === null) {
     return [];
   }
+  const now = resolveNow(options?.now);
+  const overdue = `EXISTS (SELECT 1 FROM open_commitments oc JOIN events e ON e.id = oc.event_id JOIN event_participants ep ON ep.event_id = e.id WHERE ep.contact_id = CASE WHEN l.from_contact_id = ${ownerId} THEN l.to_contact_id ELSE l.from_contact_id END AND e.deleted_at IS NULL AND oc.resolved_at IS NULL AND oc.due_at < ${now})`;
   const { limit, offset } = resolveListLimitOffset(options);
   const clauses = [
     "l.removed_at IS NULL",
     "l.is_structural = 0",
-    "l.from_contact_id = ?"
+    "(l.from_contact_id = ? OR l.to_contact_id = ?)"
   ];
-  const params = [ownerId];
+  const params = [ownerId, ownerId];
   if (filters?.kind !== void 0) {
     clauses.push("l.kind = ?");
     params.push(filters.kind);
@@ -7318,6 +8284,7 @@ function listRadar(db, filters, options) {
   const rows = db.prepare(
     `SELECT
          l.id,
+         ${overdue} AS overdue_commitment,
          l.from_contact_id,
          l.to_contact_id,
          l.trust,
@@ -7326,17 +8293,18 @@ function listRadar(db, filters, options) {
          lr.recency_score,
          lr.normalized_rank
        FROM links l
-       INNER JOIN contacts c_to ON c_to.id = l.to_contact_id
+       INNER JOIN contacts c_to ON c_to.id = CASE WHEN l.from_contact_id = ${ownerId} THEN l.to_contact_id ELSE l.from_contact_id END
          AND c_to.deleted_at IS NULL AND c_to.lifecycle_state != 'merged'
        LEFT JOIN link_rollups lr ON lr.link_id = l.id
        WHERE ${where}
-       ORDER BY COALESCE(lr.radar_score, 0) DESC
+       ORDER BY ${overdue} DESC, COALESCE(lr.radar_score, 0) DESC
        LIMIT ? OFFSET ?`
   ).all(...params, limit, offset);
   return rows.map((row) => ({
     linkId: row.id,
     contactId: row.from_contact_id === ownerId ? row.to_contact_id : row.from_contact_id,
-    driftPriority: row.drift_priority ?? 0,
+    reasons: row.overdue_commitment ? ["overdue_commitment"] : [],
+    driftPriority: row.overdue_commitment ? Math.max(1, row.drift_priority ?? 0) : row.drift_priority ?? 0,
     recencyScore: row.recency_score ?? 0,
     normalizedRank: row.normalized_rank ?? 0,
     trust: row.trust ?? 0,
@@ -7352,6 +8320,7 @@ var init_list_radar = __esm({
     init_queries();
     init_assert_default_ordering();
     init_resolve_list_limit_offset();
+    init_resolve_now();
   }
 });
 
@@ -7405,9 +8374,79 @@ var init_list_dismissed_duplicates = __esm({
   }
 });
 
+// src/tools/enrich_review_item.ts
+function enrichReviewItem(db, item) {
+  const name = (id) => {
+    if (typeof id !== "number") return "";
+    return db.prepare("SELECT name FROM contacts WHERE id = ?").get(id)?.name ?? `Contact #${id}`;
+  };
+  const result = { ...item };
+  if (item.kind === "link") {
+    const link = db.prepare(`SELECT l.*, a.name AS from_name, b.name AS to_name, a.is_owner AS from_owner, b.is_owner AS to_owner,
+      lr.recency_score, lr.drift_priority, lr.readiness_score, lr.normalized_rank, lr.reciprocity_score, lr.radar_score FROM links l JOIN contacts a ON a.id = l.from_contact_id JOIN contacts b ON b.id = l.to_contact_id LEFT JOIN link_rollups lr ON lr.link_id = l.id WHERE l.id = ?`).get(item.id);
+    if (link) {
+      result.title = link.from_owner ? String(link.to_name) : link.to_owner ? String(link.from_name) : `${link.from_name} \xB7 ${link.to_name}`;
+      result.subtitle = [link.kind, link.role].filter(Boolean).join(" \xB7 ");
+      for (const key of ["affinity", "trust", "rank"])
+        if (typeof link[key] === "number") result[key] = link[key];
+      result.recencyScore ??= link.recency_score;
+      result.driftPriority ??= link.drift_priority;
+      result.readinessScore = link.readiness_score;
+      result.normalizedRank ??= link.normalized_rank;
+      result.reciprocityScore = link.reciprocity_score;
+      result.radarScore = link.radar_score;
+    }
+  }
+  if (item.kind === "event" && typeof item.linkId === "number" && !Array.isArray(item.participants)) {
+    const link = db.prepare("SELECT from_contact_id, to_contact_id FROM links WHERE id = ?").get(item.linkId);
+    if (link)
+      result.subtitle = `${item.subtitle} \xB7 ${name(link.from_contact_id)} \xB7 ${name(link.to_contact_id)}`;
+  }
+  if (Array.isArray(item.participants)) {
+    result.counterpartyNames = item.participants.map(
+      (p) => name(p.contactId)
+    );
+    result.subtitle = [
+      item.subtitle,
+      result.counterpartyNames.join(", ")
+    ].filter(Boolean).join(" \xB7 ");
+  }
+  if (typeof item.leftContactId === "number")
+    result.title = `${name(item.leftContactId)} \xB7 ${name(item.rightContactId)}`;
+  if (typeof item.winnerContactId === "number")
+    result.title = `Merged ${name(item.loserContactId)} into ${name(item.winnerContactId)}`;
+  if (item.occursAt !== void 0 && item.kind === "contact")
+    result.title = `${name(item.id)} \xB7 ${item.title}`;
+  for (const [key, value] of Object.entries(result)) {
+    if (typeof value === "number" && /score|priority|affinity|trust|rank/i.test(key))
+      result[key] = Math.round(value * 1e3) / 1e3;
+  }
+  return result;
+}
+var init_enrich_review_item = __esm({
+  "src/tools/enrich_review_item.ts"() {
+  }
+});
+
+// src/tools/tool_summary.ts
+function summarizeCount(count, singular) {
+  if (count === 0) {
+    return `No ${singular}s found.`;
+  }
+  if (count === 1) {
+    return `Found 1 ${singular}.`;
+  }
+  return `Found ${count} ${singular}s.`;
+}
+var init_tool_summary = __esm({
+  "src/tools/tool_summary.ts"() {
+  }
+});
+
 // src/tools/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {
+    ...input.now === void 0 ? {} : { now: input.now },
     ...input.limit === void 0 ? {} : { limit: input.limit },
     ...input.offset === void 0 ? {} : { offset: input.offset },
     ...input.includeArchived === void 0 ? {} : { includeArchived: input.includeArchived },
@@ -7527,6 +8566,7 @@ function validateReviewInput(input) {
 }
 function duplicateCandidateItem(candidate) {
   return {
+    ...candidate,
     kind: "contact",
     id: candidate.leftContactId,
     title: `Possible duplicate: #${candidate.leftContactId} and #${candidate.rightContactId}`,
@@ -7536,24 +8576,28 @@ function duplicateCandidateItem(candidate) {
 }
 function momentItem(moment) {
   return {
+    ...moment,
+    occurredAtIso: new Date(moment.occurredAt).toISOString(),
     kind: "event",
     id: moment.eventId,
     title: moment.summary,
     subtitle: moment.momentKind,
-    snippet: `link #${moment.linkId} at ${moment.occurredAt}`
+    snippet: new Date(moment.occurredAt).toISOString().slice(0, 10)
   };
 }
 function commitmentItem(commitment) {
   return {
+    ...commitment,
     kind: "event",
     id: commitment.eventId,
     title: commitment.summary,
     subtitle: commitment.type,
-    snippet: `state ${commitment.resolutionState}; participants ${commitment.participants.length}; due ${commitment.dueAt ?? "none"}`
+    snippet: `state ${commitment.resolutionState}; participants ${commitment.participants.length}; due ${commitment.dueAt == null ? "none" : new Date(commitment.dueAt).toISOString().slice(0, 10)}`
   };
 }
 function radarItem(radar) {
   return {
+    ...radar,
     kind: "link",
     id: radar.linkId,
     title: `Link #${radar.linkId}`,
@@ -7563,29 +8607,34 @@ function radarItem(radar) {
 }
 function upcomingDateItem(date) {
   return {
+    ...date,
+    occursAt: date.occursOn,
+    occursAtIso: new Date(date.occursOn).toISOString(),
     kind: date.targetRef.kind,
     id: date.targetRef.id,
     title: date.summary,
     subtitle: date.recurrenceKind,
-    snippet: `occurs ${date.occursOn}`
+    snippet: `occurs ${new Date(date.occursOn).toISOString().slice(0, 10)}`
   };
 }
 function mergeHistoryItem(record) {
   return {
+    ...record,
     kind: "contact",
     id: record.winnerContactId,
     title: `Merged #${record.loserContactId} into #${record.winnerContactId}`,
-    subtitle: `at ${record.mergedAt}`,
+    subtitle: new Date(record.mergedAt).toISOString().slice(0, 10),
     snippet: record.reasonSummary ?? void 0
   };
 }
 function dismissedPairItem(record) {
   return {
+    ...record,
     kind: "contact",
     id: record.leftContactId,
     title: `Dismissed pair: #${record.leftContactId} and #${record.rightContactId}`,
     subtitle: record.reason ?? "no reason given",
-    snippet: `dismissed at ${record.dismissedAt}`
+    snippet: `dismissed at ${new Date(record.dismissedAt).toISOString().slice(0, 10)}`
   };
 }
 function compactFilters(input) {
@@ -7595,7 +8644,16 @@ function compactFilters(input) {
     )
   );
 }
-function reviewAffinityToolHandler(db, input) {
+function reviewAffinityToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(reviewAffinityTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const invalid = validateReviewInput(input);
     if (invalid) {
@@ -7609,6 +8667,9 @@ function reviewAffinityToolHandler(db, input) {
         items = listContacts(
           db,
           {
+            ...input.attribute === void 0 ? {} : { attribute: input.attribute },
+            ...input.tag === void 0 ? {} : { tag: input.tag },
+            ...input.includeLost === void 0 ? {} : { includeLost: input.includeLost },
             ...input.kind === void 0 ? {} : { kind: input.kind },
             ...input.lifecycleState === void 0 ? {} : { lifecycleState: input.lifecycleState },
             ...input.includeOwner === void 0 ? {} : { includeOwner: input.includeOwner },
@@ -7639,7 +8700,7 @@ function reviewAffinityToolHandler(db, input) {
             "Provide `contact` when `view` is `events.contact_journal`."
           );
         }
-        const contact = resolveContactLocator(db, locator, "contact");
+        const contact = resolveContactLocator(db, locator, "contact", true);
         if (!contact.ok) {
           return contact.result;
         }
@@ -7674,7 +8735,12 @@ function reviewAffinityToolHandler(db, input) {
           let contactId;
           let linkId;
           if (input.contact !== void 0) {
-            const contact = resolveContactLocator(db, input.contact, "contact");
+            const contact = resolveContactLocator(
+              db,
+              input.contact,
+              "contact",
+              true
+            );
             if (!contact.ok) {
               return contact.result;
             }
@@ -7703,7 +8769,12 @@ function reviewAffinityToolHandler(db, input) {
           let contactId;
           let linkId;
           if (input.contact !== void 0) {
-            const contact = resolveContactLocator(db, input.contact, "contact");
+            const contact = resolveContactLocator(
+              db,
+              input.contact,
+              "contact",
+              true
+            );
             if (!contact.ok) {
               return contact.result;
             }
@@ -7796,7 +8867,7 @@ function reviewAffinityToolHandler(db, input) {
             "Provide `contact` when `view` is `merges.history`."
           );
         }
-        const contact = resolveContactLocator(db, locator, "contact");
+        const contact = resolveContactLocator(db, locator, "contact", true);
         if (!contact.ok) {
           return contact.result;
         }
@@ -7809,6 +8880,7 @@ function reviewAffinityToolHandler(db, input) {
         items = listDismissedDuplicates(db, options).map(dismissedPairItem);
         break;
     }
+    items = items.map((item) => enrichReviewItem(db, item));
     return toolSuccess(
       summarizeCount(items.length, "item"),
       {
@@ -7847,12 +8919,15 @@ var init_review_affinity_tool = __esm({
     init_list_radar();
     init_get_merge_history();
     init_list_dismissed_duplicates();
+    init_enrich_review_item();
     init_tool_metadata();
     init_tool_names();
     init_tool_ref();
     init_tool_resolvers();
     init_tool_summary();
     init_tool_types();
+    init_tool_types();
+    init_validate_tool_input();
     reviewAffinityTool = defineAffinityTool({
       name: reviewAffinityToolName,
       description: "Review one affinity surface such as contacts, journals, link queues, commitments, dates, graph state, or merge history.",
@@ -7864,12 +8939,16 @@ var init_review_affinity_tool = __esm({
       targetKinds: ["contact", "link", "event"],
       inputDescriptions: {
         view: "Which review surface to return.",
+        now: "Optional current timestamp for overdue calculations.",
         contact: "Target contact locator for views that require one.",
         link: "Target link locator for views that require one.",
         contactIds: "Optional contact id subset for duplicate review or graph review.",
         kind: "Optional contact kind or link kind filter, depending on the view.",
         lifecycleState: "Optional contact lifecycle filter for the contact list view.",
         linkState: "Optional link state filter for link review views.",
+        attribute: "Attribute name or name=value; arrays require all filters.",
+        tag: "Tag name; arrays require all tags.",
+        includeLost: "Whether lost contacts are included.",
         includeOwner: "Whether owner contacts should be included in contact review.",
         includeDormant: "Whether dormant links or contacts should be included where supported.",
         includeArchived: "Whether archived links should be included where supported.",
@@ -7906,6 +8985,9 @@ var init_review_affinity_tool = __esm({
             "merges.history",
             "merges.dismissed"
           ]),
+          now: integerSchema(
+            "Optional current timestamp for overdue calculations."
+          ),
           contact: contactLocatorSchema9("Optional target contact locator."),
           link: linkLocatorSchema5("Optional target link locator."),
           contactIds: arraySchema(
@@ -7928,6 +9010,17 @@ var init_review_affinity_tool = __esm({
             "broken",
             "archived"
           ]),
+          attribute: oneOfSchema([
+            stringSchema("Attribute filter."),
+            arraySchema(stringSchema("Attribute filter."), "AND filters.")
+          ]),
+          tag: oneOfSchema([
+            stringSchema("Tag filter."),
+            arraySchema(stringSchema("Tag filter."), "AND tags.")
+          ]),
+          includeLost: booleanSchema(
+            "Include lost contacts (search excludes them by default)."
+          ),
           includeOwner: booleanSchema("Whether owner contacts are included."),
           includeDormant: booleanSchema("Whether dormant rows are included."),
           includeArchived: booleanSchema("Whether archived links are included."),
@@ -7974,99 +9067,110 @@ var init_review_affinity_tool = __esm({
 });
 
 // src/contacts/search_contacts.ts
-function relevanceScore(name, queryLower, matchedName, matchedNormalizedIdentity) {
-  const nl = name.toLowerCase();
-  if (matchedNormalizedIdentity) return 1.1;
-  if (nl.startsWith(queryLower)) return 1;
-  if (matchedName) return 0.85;
-  return 0.7;
-}
 function searchContacts(db, query, filters, options) {
-  const q = query.trim();
-  if (q.length === 0) {
-    return [];
-  }
+  const q = foldSearchText(query.trim());
+  if (!q) return [];
   assertDefaultOrdering("searchContacts", options);
   const { limit, offset } = resolveListLimitOffset(options);
-  const queryLower = q.toLowerCase();
-  const pattern = `%${q.replace(/%/g, "").replace(/_/g, "")}%`;
-  const normalizedPattern = `%${queryLower}%`;
+  const fields = /* @__PURE__ */ new Map();
+  const rows = db.prepare(`
+    SELECT contact_id, value || ' ' || normalized_key AS text, 'identity:' || type AS source FROM identities WHERE removed_at IS NULL
+    UNION ALL SELECT contact_id, name || ' ' || COALESCE(value, ''), 'attribute:' || name FROM attributes WHERE deleted_at IS NULL AND contact_id IS NOT NULL
+    UNION ALL SELECT from_contact_id, COALESCE(role, '') || ' ' || COALESCE(bond, ''), 'link_role' FROM links WHERE removed_at IS NULL
+    UNION ALL SELECT to_contact_id, COALESCE(role, '') || ' ' || COALESCE(bond, ''), 'link_role' FROM links WHERE removed_at IS NULL
+    UNION ALL SELECT ep.contact_id, e.summary, 'event' FROM event_participants ep JOIN events e ON e.id = ep.event_id WHERE e.deleted_at IS NULL
+  `).all();
+  for (const row of rows) {
+    const values = fields.get(row.contact_id) ?? [];
+    values.push({ text: foldSearchText(row.text), source: row.source });
+    fields.set(row.contact_id, values);
+  }
+  const tokens = q.split(/\s+/);
+  const phone = /^[+\d()\-/.\s]+$/.test(q) && q.replace(/\D/g, "").length >= 3;
+  const digits = q.replace(/\D/g, "").replace(/^00/, "");
+  const attributeFilters = contactAttributeClauses(filters);
   const clauses = [
-    "c.deleted_at IS NULL",
-    "c.lifecycle_state != 'merged'"
+    "deleted_at IS NULL",
+    "lifecycle_state != 'merged'",
+    ...attributeFilters.clauses
   ];
-  const params = [];
+  const params = [...attributeFilters.params];
   if (filters?.kind !== void 0) {
-    clauses.push("c.kind = ?");
+    clauses.push("kind = ?");
     params.push(filters.kind);
   }
   if (filters?.lifecycleState !== void 0) {
-    clauses.push("c.lifecycle_state = ?");
+    clauses.push("lifecycle_state = ?");
     params.push(filters.lifecycleState);
   }
-  if (filters?.includeOwner === false) {
-    clauses.push("c.is_owner = 0");
-  }
-  if (filters?.includeDormant === false || options?.includeDormant === false) {
-    clauses.push("c.lifecycle_state != 'dormant'");
-  }
-  const where = clauses.join(" AND ");
-  const sql = `
-    SELECT c.id, c.name, c.kind, c.lifecycle_state, c.is_owner, c.merged_into_contact_id,
-           c.created_at, c.updated_at, c.deleted_at,
-           (
-             SELECT value
-             FROM identities primary_i
-             WHERE primary_i.contact_id = c.id AND primary_i.removed_at IS NULL
-             ORDER BY primary_i.id
-             LIMIT 1
-           ) AS primary_identity,
-           MAX(CASE WHEN i.normalized_key LIKE ? THEN 1 ELSE 0 END) AS matched_normalized_identity
-    FROM contacts c
-    LEFT JOIN identities i ON i.contact_id = c.id AND i.removed_at IS NULL
-    WHERE ${where}
-      AND (c.name LIKE ? OR i.value LIKE ? OR i.normalized_key LIKE ?)
-    GROUP BY c.id
-  `;
-  const rows = db.prepare(sql).all(
-    normalizedPattern,
-    ...params,
-    pattern,
-    pattern,
-    normalizedPattern
-  );
-  const scored = rows.map((r) => {
-    const item = mapContactRowToContactListItem(r);
-    const matchedName = r.name.toLowerCase().includes(queryLower);
-    const score = relevanceScore(
-      r.name,
-      queryLower,
-      matchedName,
-      Number(
-        r.matched_normalized_identity ?? 0
-      ) > 0
+  if (filters?.includeOwner === false) clauses.push("is_owner = 0");
+  const contacts = db.prepare(
+    `SELECT id, name, kind, lifecycle_state, is_owner, (SELECT value FROM identities i WHERE i.contact_id = contacts.id AND i.removed_at IS NULL ORDER BY i.id LIMIT 1) AS primary_identity FROM contacts WHERE ${clauses.join(" AND ")}`
+  ).all(...params).map((row) => ({
+    ...mapContactRowToContactListItem(row),
+    primaryIdentity: row.primary_identity
+  }));
+  const scored = [];
+  for (const contact of contacts) {
+    if (contact.lifecycleState === "dormant" && !(filters?.includeDormant ?? options?.includeDormant))
+      continue;
+    if (contact.lifecycleState === "lost" && !filters?.includeLost) continue;
+    const name = foldSearchText(contact.name);
+    const values = [
+      { text: name, source: "name" },
+      ...(fields.get(contact.id) ?? []).filter(
+        (field) => !contact.isOwner || field.source !== "event" && field.source !== "link_role"
+      )
+    ];
+    const phoneFields = phone ? values.filter(
+      (field) => field.source === "identity:phone" && field.text.split(" ").join("").replace(/[^\d]/g, "").replace(/^00/, "").includes(digits)
+    ) : [];
+    if (!phoneFields.length && !tokens.every(
+      (token) => values.some((field) => field.text.includes(token))
+    ))
+      continue;
+    const matchedOn = [
+      ...new Set(
+        [
+          ...values.filter(
+            (field) => tokens.some((token) => field.text.includes(token))
+          ),
+          ...phoneFields
+        ].map((field) => field.source)
+      )
+    ];
+    const identities = values.filter(
+      (field) => field.source.startsWith("identity:")
     );
-    return {
-      item: {
-        ...item,
-        primaryIdentity: r.primary_identity ?? null
-      },
-      score
-    };
-  });
-  scored.sort((a, b) => b.score - a.score);
-  return scored.slice(offset, offset + limit).map((s) => s.item);
+    const score = name === q ? 5 : name.startsWith(q) || tokens.every((token) => name.includes(token)) ? 4 : phoneFields.length || identities.some((field) => field.text.split(" ").includes(q)) ? 3 : identities.some(
+      (field) => tokens.every((token) => field.text.includes(token))
+    ) ? 2 : 1;
+    scored.push({ item: { ...contact, matchedOn }, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.item.id - b.item.id);
+  return scored.slice(offset, offset + limit).map(({ item }) => item);
 }
 var init_search_contacts = __esm({
   "src/contacts/search_contacts.ts"() {
     init_assert_default_ordering();
     init_resolve_list_limit_offset();
+    init_contact_attribute_clauses();
+    init_fold_search_text();
     init_mappers4();
   }
 });
 
 // src/tools/search_affinity_tool.ts
-function searchAffinityToolHandler(db, input) {
+function searchAffinityToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(searchAffinityTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const options = {
       ...input.limit === void 0 ? {} : { limit: input.limit },
@@ -8076,6 +9180,9 @@ function searchAffinityToolHandler(db, input) {
       db,
       input.query,
       {
+        ...input.attribute === void 0 ? {} : { attribute: input.attribute },
+        ...input.tag === void 0 ? {} : { tag: input.tag },
+        ...input.includeLost === void 0 ? {} : { includeLost: input.includeLost },
         ...input.kind === void 0 ? {} : { kind: input.kind },
         ...input.lifecycleState === void 0 ? {} : { lifecycleState: input.lifecycleState },
         ...input.includeOwner === void 0 ? {} : { includeOwner: input.includeOwner },
@@ -8107,9 +9214,11 @@ var init_search_affinity_tool = __esm({
     init_tool_resolvers();
     init_tool_summary();
     init_tool_types();
+    init_tool_types();
+    init_validate_tool_input();
     searchAffinityTool = defineAffinityTool({
       name: searchAffinityToolName,
-      description: "Search contacts by name or identity, including exact natural-key lookups like email-style identifiers.",
+      description: "Search contacts by name, identity, attributes, link roles, bonds and event text. All whitespace tokens must match. Dormant and lost contacts are excluded by default; use includeDormant and includeLost to include them.",
       whenToUse: "Use this when you want to find contacts from free text or a known routing identity such as an email or URL-like handle.",
       whenNotToUse: "Do not use this when you already know the exact contact you want to inspect in depth.",
       sideEffects: "none",
@@ -8120,6 +9229,9 @@ var init_search_affinity_tool = __esm({
         query: "Free-text or natural-key search text.",
         kind: "Optional contact kind filter.",
         lifecycleState: "Optional lifecycle state filter.",
+        attribute: "Attribute name or name=value; arrays require all filters.",
+        tag: "Tag name; arrays require all tags.",
+        includeLost: "Whether lost contacts are included in search.",
         includeOwner: "Whether owner contacts are eligible for results.",
         includeDormant: "Whether dormant contacts should be eligible for results.",
         limit: "Optional result limit.",
@@ -8144,6 +9256,17 @@ var init_search_affinity_tool = __esm({
             "merged",
             "lost"
           ]),
+          attribute: oneOfSchema([
+            stringSchema("Attribute filter."),
+            arraySchema(stringSchema("Attribute filter."), "AND filters.")
+          ]),
+          tag: oneOfSchema([
+            stringSchema("Tag filter."),
+            arraySchema(stringSchema("Tag filter."), "AND tags.")
+          ]),
+          includeLost: booleanSchema(
+            "Include lost contacts (search excludes them by default)."
+          ),
           includeOwner: booleanSchema("Whether owner contacts are included."),
           includeDormant: booleanSchema("Whether dormant contacts are included."),
           limit: integerSchema("Optional result limit."),
@@ -8190,11 +9313,112 @@ var init_tool_registry = __esm({
   }
 });
 
+// src/surface/plain_dates.ts
+function parsePlainDue(raw, now = Date.now(), endOfDay = true) {
+  const invalid = () => new CliUsageError(
+    `Invalid timestamp "${raw}". Use YYYY-MM-DD, DD.MM.YYYY, today, tomorrow, yesterday, +3d, -2d or an ISO date-time.`
+  );
+  if (/^-?\d+$/.test(raw)) {
+    const value = Number(raw);
+    if (Number.isSafeInteger(value) && Number.isFinite(new Date(value).getTime()))
+      return value;
+    throw invalid();
+  }
+  const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
+  const european = /^(\d{2})\.(\d{2})\.(\d{4})$/.exec(raw);
+  let date;
+  if (iso || european) {
+    const year = Number(iso?.[1] ?? european?.[3]);
+    const month = Number(iso?.[2] ?? european?.[2]);
+    const day = Number(iso?.[3] ?? european?.[1]);
+    date = /* @__PURE__ */ new Date(0);
+    date.setFullYear(year, month - 1, day);
+    date.setHours(
+      endOfDay ? 23 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 999 : 0
+    );
+    if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day)
+      throw invalid();
+  } else if (raw === "today" || raw === "tomorrow" || raw === "yesterday" || /^[+-]\d+d$/.test(raw)) {
+    date = new Date(now);
+    date.setDate(
+      date.getDate() + (raw === "today" ? 0 : raw === "tomorrow" ? 1 : raw === "yesterday" ? -1 : Number(raw.slice(0, -1)))
+    );
+    date.setHours(
+      endOfDay ? 23 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 999 : 0
+    );
+  } else {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      raw
+    ))
+      throw invalid();
+    parsePlainDue(raw.slice(0, 10), now);
+    date = new Date(raw);
+  }
+  if (!Number.isFinite(date.getTime())) throw invalid();
+  return date.getTime();
+}
+function parsePlainStart(raw, now = Date.now()) {
+  return parsePlainDue(raw, now, false);
+}
+function normalizeTimeInputs(value, now = Date.now()) {
+  if (Array.isArray(value))
+    return value.map((item) => normalizeTimeInputs(item, now));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      typeof item === "string" && (key.endsWith("At") || ["asOf", "now"].includes(key)) ? key === "dueAt" ? parsePlainDue(item, now) : parsePlainStart(item, now) : normalizeTimeInputs(item, now)
+    ])
+  );
+}
+var init_plain_dates = __esm({
+  "src/surface/plain_dates.ts"() {
+    init_cli_args();
+  }
+});
+
+// src/surface/timestamp_schema.ts
+function acceptsString(schema) {
+  return schema.type === "string" || Array.isArray(schema.type) && schema.type.includes("string") || (schema.oneOf?.some(acceptsString) ?? false);
+}
+function timestampSchema(schema) {
+  return {
+    ...schema,
+    ...schema.properties ? {
+      properties: Object.fromEntries(
+        Object.entries(schema.properties).map(([key, value]) => [
+          key,
+          key.endsWith("At") || ["asOf", "now"].includes(key) ? acceptsString(value) ? value : {
+            description: value.description,
+            oneOf: [value, { type: "string" }]
+          } : timestampSchema(value)
+        ])
+      )
+    } : {},
+    ...schema.items ? { items: timestampSchema(schema.items) } : {},
+    ...schema.oneOf ? { oneOf: schema.oneOf.map(timestampSchema) } : {}
+  };
+}
+var init_timestamp_schema = __esm({
+  "src/surface/timestamp_schema.ts"() {
+  }
+});
+
 // src/surface/affinity_surface_tools.ts
 var affinitySurfaceTools, mapping, affinityCliSurfaceTools;
 var init_affinity_surface_tools = __esm({
   "src/surface/affinity_surface_tools.ts"() {
+    init_cli_args();
     init_tool_registry();
+    init_tool_types();
+    init_plain_dates();
+    init_timestamp_schema();
     affinitySurfaceTools = affinityTools.map((tool) => ({
       name: tool.name,
       description: tool.description,
@@ -8202,8 +9426,24 @@ var init_affinity_surface_tools = __esm({
       ...tool.whenNotToUse === void 0 ? {} : { whenNotToUse: tool.whenNotToUse },
       readOnly: tool.readOnly,
       sideEffects: tool.sideEffects,
-      inputSchema: { ...tool.inputSchema, type: "object" },
-      handler: tool.handler
+      inputSchema: {
+        ...timestampSchema({ ...tool.inputSchema, type: "object" }),
+        type: "object"
+      },
+      handler: (db, input) => {
+        try {
+          return tool.handler(db, normalizeTimeInputs(input));
+        } catch (error) {
+          if (error instanceof CliUsageError)
+            return toolFailure(
+              "protocol",
+              "invalid_input",
+              "Invalid input.",
+              error.message
+            );
+          throw error;
+        }
+      }
     }));
     mapping = {
       search_affinity: { verb: "search", positionals: ["query"] },
@@ -8264,10 +9504,22 @@ var init_affinity_surface_tools = __esm({
     };
     affinityCliSurfaceTools = /* @__PURE__ */ affinitySurfaceTools.map((tool) => ({
       ...tool,
+      inputSchema: {
+        ...affinityTools.find((original) => original.name === tool.name)?.inputSchema,
+        type: "object"
+      },
       ...mapping[tool.name] ? { cli: mapping[tool.name] } : {}
     }));
   }
 });
+function resolveAffinityDbPath(options = {}) {
+  const path = options.flag ?? ((options.env ?? process.env).GHOSTPAW_AFFINITY_DB || join(homedir(), ".ghostpaw", "affinity.db"));
+  return path === ":memory:" ? path : resolve(path);
+}
+var init_resolve_affinity_db_path = __esm({
+  "src/surface/resolve_affinity_db_path.ts"() {
+  }
+});
 
 // src/attributes/init_attributes_tables.ts
 function initAttributesTables(db) {
@@ -8560,6 +9812,12 @@ function initLinkEventEffectsTables(db) {
       )
     )
   `);
+  const columns = db.prepare("PRAGMA table_info(link_event_effects)").all();
+  if (!columns.some((column) => column.name === "counts_for_recency")) {
+    db.exec(
+      "ALTER TABLE link_event_effects ADD COLUMN counts_for_recency INTEGER NOT NULL DEFAULT 1"
+    );
+  }
   db.exec(
     "CREATE INDEX IF NOT EXISTS idx_link_event_effects_link_time ON link_event_effects(link_id, occurred_at DESC, event_id DESC)"
   );
@@ -8797,19 +10055,6 @@ var init_open_affinity_db = __esm({
   }
 });
 
-// src/surface/resolve_affinity_db_path.ts
-var resolve_affinity_db_path_exports = {};
-__export(resolve_affinity_db_path_exports, {
-  resolveAffinityDbPath: () => resolveAffinityDbPath
-});
-function resolveAffinityDbPath(options = {}) {
-  return options.flag ?? ((options.env ?? process.env).GHOSTPAW_AFFINITY_DB || join(homedir(), ".ghostpaw", "affinity.db"));
-}
-var init_resolve_affinity_db_path = __esm({
-  "src/surface/resolve_affinity_db_path.ts"() {
-  }
-});
-
 // src/surfaces/surface_types.ts
 function isErrorResult(result) {
   return typeof result === "object" && result !== null && "ok" in result && result.ok === false;
@@ -9049,10 +10294,10 @@ async function serveMcpStdio(server, options = {}) {
     const response = await server.handleLine(line.replace(/\r$/, ""));
     if (response !== void 0)
       await new Promise(
-        (resolve, reject) => output.write(
+        (resolve2, reject) => output.write(
           `${response}
 `,
-          (error) => error ? reject(error) : resolve()
+          (error) => error ? reject(error) : resolve2()
         )
       );
   };
@@ -9142,11 +10387,165 @@ var init_serve_affinity_mcp = __esm({
   }
 });
 
-// src/surfaces/skill_markdown.ts
-var skill_markdown_exports = {};
-__export(skill_markdown_exports, {
-  renderSkillMarkdown: () => renderSkillMarkdown
+// src/surfaces/cli_output.ts
+function enrichPlainJson(value) {
+  if (Array.isArray(value)) return value.map(enrichPlainJson);
+  if (value === null || typeof value !== "object")
+    return typeof value === "number" && !Number.isInteger(value) ? Math.round(value * 1e3) / 1e3 : value;
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    result[key] = enrichPlainJson(entry);
+    if (key.endsWith("At") && typeof entry === "number" && Number.isFinite(new Date(entry).getTime()))
+      result[`${key}Iso`] = new Date(entry).toISOString();
+  }
+  return result;
+}
+function suggestCommand(input, names) {
+  let best;
+  let distance = 3;
+  for (const name of names) {
+    let row = Array.from({ length: name.length + 1 }, (_, i) => i);
+    for (let i = 0; i < input.length; i++) {
+      const next = [i + 1];
+      for (let j = 0; j < name.length; j++)
+        next.push(
+          Math.min(
+            (next[j] ?? 0) + 1,
+            (row[j + 1] ?? 0) + 1,
+            (row[j] ?? 0) + (input[i] === name[j] ? 0 : 1)
+          )
+        );
+      row = next;
+    }
+    const current = row[name.length] ?? 3;
+    if (current < distance) {
+      best = name;
+      distance = current;
+    }
+  }
+  return best;
+}
+function cliExitCode(value) {
+  const r = value;
+  const code = r.error?.code ?? "";
+  if (r.outcome === "needs_clarification" || code === "not_found") return 3;
+  if ([
+    "conflict",
+    "version_mismatch",
+    "already_resolved",
+    "already_in_state"
+  ].includes(code) || /already resolved/i.test(r.error?.message ?? ""))
+    return 4;
+  if (["invalid_input", "validation_error"].includes(code)) return 2;
+  if (["system_error", "internal_error"].includes(code)) return 70;
+  return r.ok === false ? 1 : 0;
+}
+function plainJson(value, compact = false, formatError) {
+  const result = enrichPlainJson(value);
+  if (!result || typeof result !== "object") return result;
+  if (formatError && result.error && typeof result.error === "object") {
+    result.error = Object.fromEntries(
+      Object.entries(result.error).map(([key, value2]) => [
+        key,
+        typeof value2 === "string" && ["message", "recovery"].includes(key) ? formatError(value2) : value2
+      ])
+    );
+  }
+  const data = result.data;
+  if (data?.items && JSON.stringify(result.entities) === JSON.stringify(data.items))
+    result.entities = void 0;
+  const trim = (v) => {
+    if (Array.isArray(v)) return v.map(trim);
+    if (!v || typeof v !== "object") return v;
+    return Object.fromEntries(
+      Object.entries(v).filter(
+        ([k, x]) => !([
+          "created",
+          "updated",
+          "archived",
+          "removed",
+          "affectedLinks",
+          "derivedEffects"
+        ].includes(k) && Array.isArray(x) && !x.length)
+      ).map(([k, x]) => [k, trim(x)])
+    );
+  };
+  return compact ? trim(result) : result;
+}
+function formatLocalTime(ms) {
+  const d = new Date(ms);
+  const pad = (n) => String(n).padStart(2, "0");
+  const day = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+  const hm = `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  return hm === "00:00" || hm === "23:59" ? day : `${day} ${hm}`;
+}
+function humanResult(value) {
+  const r = value;
+  const items = r.data?.items;
+  if (Array.isArray(items)) {
+    if (!items.length) return `${r.summary ?? "No results."}
+`;
+    return `${items.map((item) => {
+      const dates = Object.entries(item).filter(([k, v]) => k in DATE_LABELS && typeof v === "number").map(
+        ([k, v]) => `${DATE_LABELS[k]} ${// Recurring dates are stored as UTC calendar days.
+        k === "occursAt" ? new Date(v).toISOString().slice(0, 10) : formatLocalTime(v)}`
+      );
+      if (Array.isArray(item.reasons) && item.reasons.length)
+        dates.push(item.reasons.join(", ").replaceAll("_", " "));
+      const subtitle = item.subtitle ? ` \u2014 ${item.subtitle}` : "";
+      const tail = dates.length ? ` \xB7 ${dates.join(" \xB7 ")}` : "";
+      return `#${item.id ?? item.entityId ?? "?"} ${item.title ?? item.name ?? ""}${subtitle}${tail}${item.overdue ? " \xB7 OVERDUE" : ""}`.trim();
+    }).join("\n")}
+`;
+  }
+  const primary = r.data?.primary;
+  if (primary)
+    return `${r.summary ?? "Done"}${primary.id === void 0 ? "" : ` (id ${primary.id})`}
+`;
+  if (r.data) {
+    const fields = [];
+    const display = (entry) => {
+      if (entry === null) return "\u2014";
+      if (Array.isArray(entry)) return entry.map(display).join(", ") || "\u2014";
+      if (typeof entry === "object") {
+        const item = entry;
+        return String(
+          item.title ?? item.name ?? item.summary ?? item.value ?? (item.id === void 0 ? JSON.stringify(item) : `#${item.id}`)
+        );
+      }
+      return String(entry);
+    };
+    const flatten = (value2, prefix = "") => {
+      if (!value2 || typeof value2 !== "object") return;
+      for (const [key, entry] of Object.entries(value2)) {
+        const label = `${prefix}${key}`;
+        if (entry && typeof entry === "object" && !Array.isArray(entry))
+          flatten(entry, `${label}.`);
+        else fields.push([label, display(entry)]);
+      }
+    };
+    flatten(enrichPlainJson(r.data.detail ?? r.data));
+    const width = Math.max(0, ...fields.map(([label]) => label.length));
+    return `${fields.map(([label, value2]) => `${label.padEnd(width)}: ${value2}`).join("\n")}
+`;
+  }
+  return `${r.summary ?? ""}
+`;
+}
+var DATE_LABELS;
+var init_cli_output = __esm({
+  "src/surfaces/cli_output.ts"() {
+    DATE_LABELS = {
+      occurredAt: "on",
+      dueAt: "due",
+      occursAt: "next",
+      resolvedAt: "resolved",
+      lastMeaningfulInteractionAt: "last"
+    };
+  }
 });
+
+// src/surfaces/skill_markdown.ts
 function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(spec.name) || spec.name.length > 64)
     throw new Error("Invalid skill name");
@@ -9205,6 +10604,25 @@ function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
       lines.push(
         `| ${name} | ${property.type ?? property.oneOf?.map((branch) => branch.type).join(" / ") ?? "any"} | ${tool.inputSchema.required?.includes(name) ? "yes" : "no"} | ${(property.enum ? `${property.enum.join(", ")}. ` : "") + (property.description ?? "").replaceAll("|", "\\|").replaceAll("\n", " ")} |`
       );
+    if (spec.cheatSheet) {
+      for (const [parent, property] of Object.entries(
+        tool.inputSchema.properties ?? {}
+      )) {
+        const nested = property.items ?? property;
+        const branches = [nested, ...nested.oneOf ?? []];
+        const seen = /* @__PURE__ */ new Set();
+        for (const branch of branches)
+          for (const [key, child] of Object.entries(branch.properties ?? {})) {
+            if (seen.has(key)) continue;
+            seen.add(key);
+            lines.push(
+              `| ${parent}.${key} | ${child.type ?? "oneOf"} | ${branch.required?.includes(key) ? "yes" : "no"} | ${(child.description ?? "").replaceAll("|", "\\|").replaceAll("\n", " ")} |`
+            );
+          }
+      }
+      if (spec.examples?.[tool.name])
+        lines.push("", "```sh", spec.examples[tool.name] ?? "", "```");
+    }
     lines.push("");
   }
   lines.push(
@@ -9219,13 +10637,38 @@ function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
     ...spec.principles.map((principle) => `- ${principle}`),
     ""
   );
-  return lines.join("\n");
+  const output = lines.join("\n");
+  if (!spec.cheatSheet) return output;
+  const title = `# ${spec.name}
+
+`;
+  const start = output.indexOf(title) + title.length;
+  const appendix = output.slice(start).replace(/ \(without a global install:.*?\)/g, "").replace(/^## /gm, "### ");
+  return `${output.slice(0, start)}${spec.cheatSheet}
+
+## Appendix: MCP and tool calls
+
+${appendix}
+From the binary: \`${spec.bin} skill <guide>\`.
+${spec.packageName ? `
+## Without the binary
+
+Use \`npx -y ${spec.packageName} ...\` (Node.js 24 or newer), or import \`${spec.packageName}\` as a library.
+` : ""}`;
 }
 var init_skill_markdown = __esm({
   "src/surfaces/skill_markdown.ts"() {
   }
 });
 
+// src/surface/affinity_skill_references.ts
+var affinitySkillReferences;
+var init_affinity_skill_references = __esm({
+  "src/surface/affinity_skill_references.ts"() {
+    affinitySkillReferences = { "bootstrap-and-cold-start": { "description": "Establish a clean Affinity baseline with one owner, one verified identity, and the minimum structure needed for later evidence and review work.", "content": '# Bootstrap And Cold Start\n\nPrimary tools:\n- `manage_contact`\n- `manage_identity`\n- `inspect_affinity_item`\n- `review_affinity`\n\nGoal:\n- Establish one clean owner record, make it reachable, and verify the system is ready for later relationship work.\n\nWhen to use:\n- The database is new or logically empty.\n- A harness needs to initialize its own operator profile before doing anything else.\n\nWhen not to use:\n- The owner already exists and you only need to update profile fields.\n- You are importing historical relationships; use the import-focused skill after bootstrap.\n\nStep-by-step sequence:\n1. Assume the schema is already initialized and the database is live before using any tool.\n2. Use `manage_contact` with `action: "create"` and `bootstrapOwner: true` exactly once for the operator.\n3. Immediately attach at least one routing identity with `manage_identity` so future lookups can use a stable natural key.\n4. Use `inspect_affinity_item` with `kind: "owner_profile"` to confirm that the owner profile exists and reads back cleanly.\n5. Use `review_affinity` with `view: "contacts.list"` to confirm that the portfolio is still minimal and no duplicate owner-like records were created during setup.\n\nValidation checks:\n- The owner profile loads successfully.\n- The owner has at least one live identity.\n- The contact list shows exactly the records you expect at this early stage.\n\nPitfalls:\n- Do not create a non-owner placeholder and plan to convert it later if the harness can bootstrap the real owner immediately.\n- Do not skip identity attachment, or later natural-key lookup will be weaker and duplicate-prone.\n- Do not seed relationships before the owner exists if later evidence is meant to be owner-facing.\n\nTips and tricks:\n- Prefer an identity that is stable across sessions, such as a primary email or canonical profile URL.\n- Keep the first dataset tiny. Bootstrap is for a trustworthy base, not a full import.\n- If setup feels ambiguous, inspect first and add less rather than more.\n\nTool calls to prefer:\n- `manage_contact` for owner creation\n- `manage_identity` for first routing key\n- `inspect_affinity_item` for confirmation\n- `review_affinity` for early portfolio sanity checks\n\nRelated skills:\n- `identify-and-locate-contacts`\n- `import-history-without-faking-evidence`' }, "identify-and-locate-contacts": { "description": "Find the right contact reliably, prefer stable natural keys when possible, and avoid creating duplicates through weak lookup discipline.", "content": "# Identify And Locate Contacts\n\nPrimary tools:\n- `search_affinity`\n- `inspect_affinity_item`\n- `manage_identity`\n- `manage_contact`\n\nGoal:\n- Resolve the right contact before mutating anything, using the strongest available locator.\n\nWhen to use:\n- A harness receives a name, email, phone number, URL, or ambiguous reference to a person or organization.\n- You need to confirm whether a contact already exists before creating a new one.\n\nWhen not to use:\n- You already have one exact internal id from a prior successful tool result.\n- You are reviewing a list surface rather than identifying one exact target.\n\nStep-by-step sequence:\n1. Start with `search_affinity` whenever the target might already exist.\n2. If you have a strong natural key such as email, phone, or URL-like handle, use that query first rather than a vague display name.\n3. If search returns one strong candidate, use `inspect_affinity_item` to confirm the profile before mutating.\n4. If the target does not exist, create it with `manage_contact`.\n5. Immediately add the best routing key with `manage_identity` so future lookup becomes exact rather than fuzzy.\n6. If the system returns ambiguity, stop and clarify instead of guessing.\n\nValidation checks:\n- The inspected profile matches the intended person or organization.\n- The best known routing identity is attached and, when appropriate, verified.\n- Later searches by that identity return the same contact cleanly.\n\nPitfalls:\n- Do not trust names alone when a natural key is available.\n- Do not create a second contact just because search returned multiple plausible matches.\n- Do not remove or revise identities casually; they are your best future locator surface.\n\nTips and tricks:\n- Prefer exact identities over integer ids when the harness needs to survive across sessions or partial memory loss.\n- After creating a contact from a vague mention, upgrade it with a real identity as soon as possible.\n- If multiple weak matches appear, inspect before mutating.\n\nTool calls to prefer:\n- `search_affinity` for candidate discovery\n- `inspect_affinity_item` for exact confirmation\n- `manage_identity` for routing-key upgrades\n- `manage_contact` only after lookup fails honestly\n\nRelated skills:\n- `bootstrap-and-cold-start`\n- `reconcile-duplicates-and-merge-safely`" }, "import-history-without-faking-evidence": { "description": "Import pre-existing relationship state honestly, using seeded links for known history instead of inventing fake journal evidence.", "content": '# Import History Without Faking Evidence\n\nPrimary tools:\n- `manage_contact`\n- `manage_identity`\n- `manage_relationship`\n- `inspect_affinity_item`\n\nGoal:\n- Represent real pre-system relationship state without fabricating a timeline of events that never existed inside Affinity.\n\nWhen to use:\n- You are migrating from another CRM, notes system, or memory set.\n- You already know a relationship exists and roughly how strong or active it is, but you do not want to reconstruct every past interaction.\n\nWhen not to use:\n- A new event just happened and should affect mechanics now.\n- You are recording a specific conversation, milestone, transaction, or observation.\n\nStep-by-step sequence:\n1. Create or locate the relevant contacts first.\n2. Add the strongest identities you know so the imported graph stays addressable later.\n3. Use `manage_relationship` with `action: "seed_social_link"` to establish a relational link that already existed before the system.\n4. Set only the fields you can justify: kind, rough rank, trust, cadence, state, and optional bond.\n5. Inspect the result with `inspect_affinity_item` if you need to verify the exact post-import state.\n6. From that point forward, switch to evidence tools for all new real-world activity.\n\nValidation checks:\n- The imported contact pair now has the expected relational link.\n- The seeded state looks plausible when inspected.\n- Later direct events continue progression from the seeded baseline rather than from zero.\n\nPitfalls:\n- Do not backfill dozens of fake conversations just to reach a desired rank.\n- Do not use import seeding for ordinary day-to-day relationship maintenance.\n- Do not overstate confidence on rank or trust when the historical truth is actually vague.\n\nTips and tricks:\n- Seed conservatively if you are unsure. It is safer to underclaim and let real future evidence move the link.\n- Use bond text sparingly as a narrative reminder of why the imported state is what it is.\n- Prefer one honest seed over many synthetic event reconstructions.\n\nTool calls to prefer:\n- `manage_relationship` with `seed_social_link`\n- `manage_contact` and `manage_identity` before seeding\n- `inspect_affinity_item` for post-import verification\n\nRelated skills:\n- `bootstrap-and-cold-start`\n- `record-direct-evidence-well`' }, "model-structure-orgs-and-households": { "description": "Model factual structure such as employment, membership, hierarchy, and household ties without confusing it with live relational mechanics.", "content": '# Model Structure, Orgs, And Households\n\nPrimary tools:\n- `manage_contact`\n- `manage_relationship`\n- `inspect_affinity_item`\n- `review_affinity`\n\nGoal:\n- Capture the stable factual skeleton of the world: who belongs where, who reports to whom, and what entities are structurally connected.\n\nWhen to use:\n- You need to represent employment, family structure, team membership, households, or service affiliation.\n- The fact should exist even if no emotional or operational relationship score is implied.\n\nWhen not to use:\n- You want to express how strong, strained, warm, or active a relationship feels.\n- You are recording something that happened in time.\n\nStep-by-step sequence:\n1. Create or locate the entities involved.\n2. Decide whether the fact is structural rather than relational. If the answer survives even with zero interaction history, it is usually structural.\n3. Use `manage_relationship` with `action: "set_structural_tie"` to record the factual tie.\n4. Include a role when the role clarifies the structure, such as job title or household role.\n5. Inspect relevant profiles or review lists after large structural batches to confirm the world model is clean.\n6. Remove or replace outdated ties when the world changes, such as a job move or team change.\n\nValidation checks:\n- The structural tie is visible and stable.\n- No fake progression fields were introduced just to represent a factual tie.\n- The chart and review surfaces now reflect the world structure you expect.\n\nPitfalls:\n- Do not use structural ties to stand in for closeness, trust, or cadence.\n- Do not seed social links just because a structural tie exists; only do that if a live relational track also matters.\n- Do not leave outdated structural ties hanging after the factual world changes.\n\nTips and tricks:\n- Structural and relational links can coexist. Use both when both truths matter.\n- Groups, households, companies, teams, and services often deserve their own contacts.\n- If you are unsure, ask whether the statement is about belonging or about lived relationship quality.\n\nTool calls to prefer:\n- `manage_relationship` with `set_structural_tie`\n- `inspect_affinity_item` to verify exact targets\n- `review_affinity` for broader structural review\n\nRelated skills:\n- `identify-and-locate-contacts`\n- `record-direct-evidence-well`' }, "record-direct-evidence-well": { "description": "Record direct owner-facing social evidence in a way that produces truthful mechanics, good moments, and useful future review surfaces.", "content": "# Record Direct Evidence Well\n\nPrimary tools:\n- `record_event`\n- `inspect_affinity_item`\n- `review_affinity`\n- `manage_relationship`\n\nGoal:\n- Capture what really happened between the owner and other contacts so Affinity can derive progression, trust, cadence, and moments cleanly.\n\nWhen to use:\n- A conversation, activity, support exchange, conflict, correction, milestone, or direct operational interaction just happened.\n- You want future radar, progression, journal, and chart views to reflect the event truthfully.\n\nWhen not to use:\n- You are importing pre-system history.\n- You only observed third parties and were not directly part of the relationship evidence.\n\nStep-by-step sequence:\n1. Confirm the participants first. Use exact contacts whenever possible.\n2. Use `record_event` with the smallest honest event family: `interaction` for ordinary direct evidence, `milestone` when the event is truly milestone-shaped, or another event family only when it better matches reality.\n3. Set significance conservatively. Use high significance only when the event genuinely changed the relationship.\n4. Let the system auto-create owner-facing links when appropriate instead of manually seeding a link just because a direct event happened.\n5. Review the receipt or inspect the resulting profile when you need to understand the effect.\n6. Use `review_affinity` on journal, timeline, moments, or readiness views when you need context after a sequence of events.\n\nValidation checks:\n- The right contacts were involved.\n- The event family matches what really happened.\n- The resulting mechanics feel plausible when reviewed.\n\nPitfalls:\n- Do not inflate significance to force a rank-up.\n- Do not turn ordinary direct evidence into a milestone just to get a dramatic moment.\n- Do not use bond text as evidence. If the bond changed but no event happened, revise the bond separately.\n- Do not guess through ambiguity; clarify the target first.\n\nTips and tricks:\n- Conflict and correction are both first-class direct evidence. Use them honestly rather than hiding them inside generic summaries.\n- Multi-participant owner events can refresh multiple links at once. That is a feature, not a bug.\n- If you need to label the current narrative reading without changing mechanics, use `manage_relationship` with `revise_bond` after the evidence is recorded.\n\nTool calls to prefer:\n- `record_event` for the evidence itself\n- `inspect_affinity_item` for exact read-back\n- `review_affinity` for journals, timelines, moments, and readiness\n- `manage_relationship` only for bond interpretation after the fact\n\nRelated skills:\n- `record-observations-and-referrals`\n- `review-radar-progression-and-graph`" }, "record-observations-and-referrals": { "description": "Capture third-party and referral truth without overclaiming intimacy, directness, or trust that the operator did not actually earn.", "content": '# Record Observations And Referrals\n\nPrimary tools:\n- `record_event`\n- `review_affinity`\n- `inspect_affinity_item`\n\nGoal:\n- Add truthful third-party graph information while keeping observational evidence weaker than direct relationship evidence.\n\nWhen to use:\n- You learned that two people know each other, one person referred another, or you observed a third-party relationship pattern.\n- You want the graph to reflect world truth without pretending you had the direct interaction yourself.\n\nWhen not to use:\n- The owner directly participated in the event and should record direct evidence instead.\n- You merely suspect a relationship with no strong enough fact to justify recording it.\n\nStep-by-step sequence:\n1. Confirm the third-party contacts you are referring to.\n2. Use `record_event` with `kind: "observation"` when the truth is observational rather than direct.\n3. Keep significance modest unless the observed fact is genuinely consequential.\n4. After recording, use `review_affinity` to inspect observed-link or graph views and verify the resulting topology.\n5. If later direct evidence exists, record that separately rather than expecting the observation to do all the work.\n\nValidation checks:\n- The graph now reflects the third-party fact you meant to capture.\n- Observed links stay appropriately weaker than direct links.\n- No accidental owner-facing intimacy was invented.\n\nPitfalls:\n- Do not use observations to fake deep trust or rank.\n- Do not create a clique from vague group knowledge when the system only has justified pairwise facts.\n- Do not promote a rumor to structure or direct evidence without better confirmation.\n\nTips and tricks:\n- Referral chains are excellent observational facts because they help later review and graph interpretation.\n- Use chart and observed-link review views together after batches of observation work.\n- Observations are often better than silence, but they should remain humble.\n\nTool calls to prefer:\n- `record_event` with `observation`\n- `review_affinity` with observed-link and graph views\n- `inspect_affinity_item` if you need exact follow-up on one target\n\nRelated skills:\n- `record-direct-evidence-well`\n- `review-radar-progression-and-graph`' }, "capture-transactions-and-commercial-events": { "description": "Capture commercially meaningful interactions as transactions so operational and service relationships accumulate the right evidence shape.", "content": '# Capture Transactions And Commercial Events\n\nPrimary tools:\n- `record_event`\n- `inspect_affinity_item`\n- `review_affinity`\n\nGoal:\n- Represent deals, placements, closings, sponsorships, and operationally meaningful exchanges as transactions instead of flattening them into generic social notes.\n\nWhen to use:\n- Money, deliverables, placements, closings, or other commercially meaningful exchanges just occurred.\n- The relationship is service-oriented, professional, or business-critical.\n\nWhen not to use:\n- The main truth is a personal conversation or ordinary activity.\n- The important action is really a promise or agreement that still needs later resolution.\n\nStep-by-step sequence:\n1. Confirm the right counterparties first.\n2. Use `record_event` with `kind: "transaction"` for the commercial event itself.\n3. Keep the summary concrete enough that future review explains what was exchanged and why it mattered.\n4. Use significance according to the real business weight, not just enthusiasm.\n5. Review the affected relationship if the commercial event should meaningfully change trust, cadence, or graph visibility.\n\nValidation checks:\n- The transaction now appears in the relevant timeline or journal views.\n- The resulting relationship effect matches the commercial importance of the event.\n- Later maintenance views now have the right recency signal.\n\nPitfalls:\n- Do not bury closings, placements, or sponsorship deliveries inside generic conversations.\n- Do not record a transaction when the truth is still only a pending agreement.\n- Do not expect transactions to create the same kind of affinity movement as rich direct social evidence.\n\nTips and tricks:\n- A relationship can be commercially strong and emotionally shallow. That is normal.\n- Use transactions to preserve crisp operational history for later portfolio review.\n- Follow major transactions with review views to confirm the graph and maintenance surfaces updated as expected.\n\nTool calls to prefer:\n- `record_event` with `transaction`\n- `inspect_affinity_item` for exact relationship read-back\n- `review_affinity` for owner-link portfolio review\n\nRelated skills:\n- `manage-promises-and-agreements`\n- `review-radar-progression-and-graph`' }, "manage-promises-and-agreements": { "description": "Track obligations explicitly from creation to resolution so open commitments remain actionable and trust consequences stay honest.", "content": '# Manage Promises And Agreements\n\nPrimary tools:\n- `manage_commitment`\n- `review_affinity`\n- `inspect_affinity_item`\n\nGoal:\n- Keep promises and agreements visible, resolvable, and mechanically meaningful instead of letting them disappear into narrative history.\n\nWhen to use:\n- Someone committed to doing something later.\n- A promise, agreement, or operational obligation needs follow-through.\n\nWhen not to use:\n- The event is complete already and no unresolved obligation exists.\n- A date is recurring and belongs in the date-anchor surface instead.\n\nStep-by-step sequence:\n1. When the commitment is made, use `manage_commitment` with `action: "record"`.\n2. Choose `promise` vs `agreement` honestly rather than treating them as stylistic synonyms.\n3. Include a due time when the obligation has a meaningful time boundary.\n4. Use `review_affinity` with the open-commitment view during regular review cycles.\n5. When the outcome is known, resolve it with `manage_commitment` as `kept`, `cancelled`, or `broken`.\n6. Inspect the relevant profile or review the relevant queue again if you need to confirm closure.\n\nValidation checks:\n- Open commitments appear when they should and disappear when resolved.\n- Resolution state matches real-world truth.\n- Trust effects feel consistent with whether the promise was kept or broken.\n\nPitfalls:\n- Do not hide real obligations inside ordinary event summaries.\n- Do not resolve a commitment optimistically before the outcome is actually known.\n- Do not misuse `cancelled` when the truth is actually `broken`.\n\nTips and tricks:\n- If an obligation matters enough to disappoint someone when missed, record it.\n- Review open commitments regularly; the value of the system drops fast if this queue goes stale.\n- When a commitment resolution also deserves narrative context, pair the resolution with an appropriate event in the surrounding workflow.\n\nTool calls to prefer:\n- `manage_commitment` for record and resolve\n- `review_affinity` for the open-commitment queue\n- `inspect_affinity_item` when you need exact context on the affected relationship\n\nRelated skills:\n- `capture-transactions-and-commercial-events`\n- `manage-recurring-dates-and-reminders`' }, "manage-recurring-dates-and-reminders": { "description": "Use date anchors for recurring salience so important birthdays, anniversaries, renewals, and memorials feed review surfaces cleanly.", "content": '# Manage Recurring Dates And Reminders\n\nPrimary tools:\n- `manage_date_anchor`\n- `review_affinity`\n- `inspect_affinity_item`\n\nGoal:\n- Materialize recurring important dates into a durable reminder surface that later review and relationship maintenance can trust.\n\nWhen to use:\n- A date recurs yearly and matters to a contact or link.\n- You want reminders for birthdays, anniversaries, renewals, memorials, or other yearly anchors.\n\nWhen not to use:\n- The date is a one-off event.\n- The fact is a preference or metadata note rather than a recurring anchor.\n\nStep-by-step sequence:\n1. Confirm the target contact or link first.\n2. Use `manage_date_anchor` with `action: "add"` and the right recurrence kind.\n3. Keep the summary operator-friendly so future reminders are immediately understandable.\n4. Use `review_affinity` with the upcoming-dates view and an explicit horizon during regular review work.\n5. Revise anchors when recurrence details change.\n6. Remove anchors when the reminder surface should no longer treat the date as active.\n\nValidation checks:\n- The anchor appears in upcoming-date review when it falls within the chosen horizon.\n- Duplicate anchors are not silently piling up.\n- The summary and significance are still meaningful for later action.\n\nPitfalls:\n- Do not store important recurring dates only as loose attributes.\n- Do not create duplicate yearly anchors for the same target and meaning.\n- Do not use recurring anchors for commitments; those belong in the commitment flow.\n\nTips and tricks:\n- Tune horizons by workflow: short for weekly review, longer for quarterly planning.\n- Use significance to help order upcoming-date review meaningfully.\n- Link-level anchors are valuable when the date belongs to a relationship rather than one person.\n\nTool calls to prefer:\n- `manage_date_anchor` for add, revise, and remove\n- `review_affinity` with the upcoming-dates view\n- `inspect_affinity_item` when you need exact context on the target\n\nRelated skills:\n- `manage-promises-and-agreements`\n- `review-radar-progression-and-graph`' }, "review-radar-progression-and-graph": { "description": "Use the review surfaces to prioritize maintenance, understand progression readiness, and read the shape of the relationship graph without guessing from raw rows.", "content": "# Review Radar, Progression, And Graph\n\nPrimary tools:\n- `review_affinity`\n- `inspect_affinity_item`\n\nGoal:\n- Turn review surfaces into a disciplined operating loop for outreach, prioritization, and graph understanding.\n\nWhen to use:\n- You need a daily or weekly maintenance pass.\n- You want to know who is drifting, who is ready for deeper investment, or how the network is structured.\n\nWhen not to use:\n- You already know the one exact item you need to inspect in depth.\n- You are mutating state and only need confirmation of a single write result.\n\nStep-by-step sequence:\n1. Start with `review_affinity` on the highest-level view that matches the question: radar, owner links, progression readiness, graph, moments, or a timeline view.\n2. Use radar when the question is who needs attention now.\n3. Use progression readiness when the question is where additional positive investment is most likely to deepen a relationship.\n4. Use graph review when the question is network shape, bridges, clusters, or hidden centrality.\n5. Use journal or timeline views when a score needs narrative context before action.\n6. Escalate to `inspect_affinity_item` only after the review surface identifies the exact target worth opening deeply.\n\nValidation checks:\n- The chosen review surface actually matches the decision you are trying to make.\n- You inspected context before acting on a surprising score.\n- Follow-up work targets the right contact or link rather than the loudest metric.\n\nPitfalls:\n- Do not treat radar as a command to act blindly without context.\n- Do not confuse progression readiness with relationship importance; they answer different questions.\n- Do not rely on one score when a timeline or graph view would explain the situation better.\n\nTips and tricks:\n- Review flows are strongest when used rhythmically rather than sporadically.\n- Use graph review to understand bridges and clusters, then use timeline or profile inspection for the exact story behind them.\n- Empty results can still be informative: they may confirm that maintenance debt is currently low.\n\nTool calls to prefer:\n- `review_affinity` for all dashboard-style surfaces\n- `inspect_affinity_item` for exact deep follow-up\n\nRelated skills:\n- `record-direct-evidence-well`\n- `manage-recurring-dates-and-reminders`\n- `reconcile-duplicates-and-merge-safely`" }, "reconcile-duplicates-and-merge-safely": { "description": "Review duplicate candidates carefully and merge only after the identity, history, and structural consequences are understood.", "content": "# Reconcile Duplicates And Merge Safely\n\nPrimary tools:\n- `review_affinity`\n- `inspect_affinity_item`\n- `merge_contacts`\n\nGoal:\n- Collapse true duplicates without losing lineage, identities, participants, or relationship truth.\n\nWhen to use:\n- Duplicate-candidate review surfaces indicate a likely duplicate.\n- A harness or operator has strong evidence that two contacts are the same real entity.\n\nWhen not to use:\n- The match is still speculative and unresolved.\n- The real need is just better identities or labels rather than an actual merge.\n\nStep-by-step sequence:\n1. Start with `review_affinity` on the duplicate-candidate view.\n2. Inspect both candidate contacts before merging.\n3. Confirm the winner explicitly rather than letting recency or convenience decide by accident.\n4. Use `merge_contacts` only when the identity and history picture is clear.\n5. Inspect the surviving contact after the merge to confirm the merged state looks right.\n6. Review merge history when you need lineage confirmation later.\n\nValidation checks:\n- The surviving contact now contains the expected identities and visible history.\n- The loser is no longer treated as a live normal contact.\n- The merge reason is still understandable when reviewed later.\n\nPitfalls:\n- Do not merge on a weak fuzzy-name match alone.\n- Do not skip inspection of both sides before merging.\n- Do not assume merges are easy to conceptually undo just because the system preserves lineage.\n\nTips and tricks:\n- Prefer a winner that already carries the stronger routing identity and richer history unless another reason dominates.\n- If the system is uncertain, clarify first instead of forcing a merge.\n- Review merge history after sensitive merges to confirm the lineage chain is clean.\n\nTool calls to prefer:\n- `review_affinity` for duplicate-candidate discovery and merge-history review\n- `inspect_affinity_item` for both candidate contacts\n- `merge_contacts` only after confirmation\n\nRelated skills:\n- `identify-and-locate-contacts`\n- `import-history-without-faking-evidence`" } };
+  }
+});
+
 // src/skills/skill_types.ts
 function defineAffinitySkill(skill) {
   return skill;
@@ -9976,22 +11419,76 @@ var init_soul = __esm({
 });
 
 // src/surface/affinity_skill_spec.ts
-var affinity_skill_spec_exports = {};
-__export(affinity_skill_spec_exports, {
-  affinitySkillSpec: () => affinitySkillSpec
-});
-var affinitySkillSpec;
+var affinityCliExamples, affinityCheatSheet, affinitySkillSpec;
 var init_affinity_skill_spec = __esm({
   "src/surface/affinity_skill_spec.ts"() {
     init_skill_registry();
     init_soul();
     init_affinity_mcp_instructions();
     init_affinity_surface_tools();
+    affinityCliExamples = {
+      search_affinity: 'ghostpaw-affinity search "Jana"',
+      review_affinity: `ghostpaw-affinity review events.contact_journal --contact '{"contactId":2}'`,
+      inspect_affinity_item: `ghostpaw-affinity show contact_profile --contact '{"contactId":2}'`,
+      manage_contact: `ghostpaw-affinity contact create '{"name":"Fox","kind":"human","bootstrapOwner":true}'`,
+      merge_contacts: `ghostpaw-affinity contact merge --winner '{"contactId":2}' --loser '{"contactId":8}' --reason-summary "same person"`,
+      manage_duplicate_dismissal: `ghostpaw-affinity duplicate dismiss --left '{"contactId":5}' --right '{"contactId":10}' --reason '"different people"'`,
+      manage_identity: `ghostpaw-affinity identity add --contact '{"contactId":2}' --input '{"type":"email","value":"jana@x.de"}'`,
+      manage_relationship: `ghostpaw-affinity relationship tie --from '{"contactId":2}' --to '{"contactId":3}' --kind works_at --role Founder`,
+      record_event: `ghostpaw-affinity event record --kind interaction --input '{"type":"conversation","occurredAt":"today","summary":"Call re pilot","significance":6,"participants":[{"contactId":2,"role":"recipient","directionality":"mutual"}]}'`,
+      manage_commitment: `ghostpaw-affinity commitment record --input '{"commitmentType":"promise","occurredAt":"today","dueAt":"+3d","summary":"Send proposal","significance":6,"participants":[{"contactId":2,"role":"recipient"}]}'`,
+      manage_date_anchor: `ghostpaw-affinity date add --input '{"target":{"kind":"contact","contact":{"contactId":2}},"recurrenceKind":"birthday","anchorMonth":11,"anchorDay":3,"summary":"Jana bday","significance":4}'`,
+      manage_attribute: `ghostpaw-affinity attribute set --target '{"kind":"contact","contact":{"contactId":2}}' --name pipeline_stage --value '"proposal"'`
+    };
+    affinityCheatSheet = `## CLI cheat sheet
+
+Install: \`curl -fsSL https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.sh | sh\`
+Windows: \`irm https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.ps1 | iex\`
+
+\`\`\`sh
+export GHOSTPAW_AFFINITY_DB=/abs/path/affinity.db
+# Or --db; default ~/.ghostpaw/affinity.db. Piped output is JSON; --compact omits empty receipt arrays.
+# Exit: 0 ok/no_op, 1 tool error, 2 usage/invalid input, 3 not found/clarification, 4 conflict, 70 internal.
+# Dates: epoch ms, ISO with offset/Z, YYYY-MM-DD, DD.MM.YYYY, today, tomorrow, +3d, -2d.
+# Date-only occurredAt uses local midnight; dueAt uses local end of day.
+ghostpaw-affinity contact create '{"name":"Fox","kind":"human","bootstrapOwner":true}'
+ghostpaw-affinity search "Jana" # Search names, identities, tags, attributes, roles and events before creating.
+ghostpaw-affinity contact create '{"name":"Jana Petersen","kind":"human"}'
+ghostpaw-affinity identity add --contact '{"contactId":2}' --input '{"type":"email","value":"jana@x.de"}'
+ghostpaw-affinity relationship tie --from '{"contactId":2}' --to '{"contactId":3}' --kind works_at --role Founder
+ghostpaw-affinity relationship add --from '{"contactId":1}' --to '{"contactId":2}' --kind professional --role lead
+ghostpaw-affinity event record --kind interaction --input '{"type":"conversation","occurredAt":"today","summary":"Call re pilot","significance":6,"participants":[{"contactId":2,"role":"recipient","directionality":"mutual"}]}'
+ghostpaw-affinity commitment record --input '{"commitmentType":"promise","occurredAt":"today","dueAt":"+3d","summary":"Send proposal","significance":6,"participants":[{"contactId":2,"role":"recipient"}]}'
+ghostpaw-affinity commitment resolve --commitment-event-id 6 --resolution kept
+ghostpaw-affinity date add --input '{"target":{"kind":"contact","contact":{"contactId":2}},"recurrenceKind":"birthday","anchorMonth":11,"anchorDay":3,"summary":"Jana bday","significance":4}'
+ghostpaw-affinity attribute set --target '{"kind":"contact","contact":{"contactId":2}}' --name pipeline_stage --value '"proposal"'
+ghostpaw-affinity attribute set --target '{"kind":"contact","contact":{"contactId":2}}' --name tag:gastro-radar --value null
+ghostpaw-affinity show contact_profile --contact '{"contactId":2}'
+ghostpaw-affinity review events.contact_journal --contact '{"contactId":2}'
+ghostpaw-affinity review links.radar
+ghostpaw-affinity review commitments.open
+ghostpaw-affinity review dates.upcoming --horizon-days 14
+ghostpaw-affinity review contacts.list --tag gastro-radar
+ghostpaw-affinity review contacts.list --attribute pipeline_stage=proposal
+ghostpaw-affinity review contacts.duplicates
+ghostpaw-affinity contact merge --winner '{"contactId":2}' --loser '{"contactId":8}' --reason-summary "same person"
+ghostpaw-affinity duplicate dismiss --left '{"contactId":5}' --right '{"contactId":10}' --reason '"different people"'
+ghostpaw-affinity contact revise '{"contactId":3}' --patch '{"name":"New Name"}'
+ghostpaw-affinity contact lifecycle '{"contactId":9}' dormant
+ghostpaw-affinity relationship state --link '{"linkId":7}' --state dormant
+ghostpaw-affinity contact export --contact '{"contactId":2}'
+ghostpaw-affinity contact delete --contact '{"contactId":2}' --confirm
+\`\`\`
+
+For bots and agents: run \`ghostpaw-affinity mcp\` for MCP stdio, or use this CLI with \`--json\`. Read a guide with \`ghostpaw-affinity skill <guide>\`.
+`;
     affinitySkillSpec = {
+      cheatSheet: affinityCheatSheet,
+      examples: affinityCliExamples,
       name: "affinity",
       description: "Search and maintain local contacts, identities, relationships, events, commitments, and recurring dates. Use when recording relationship evidence or reviewing a social CRM.",
       license: "MIT",
-      compatibility: "Node.js 24 or newer. MCP stdio or ghostpaw-affinity CLI.",
+      compatibility: "The release binary needs no runtime. MCP stdio or ghostpaw-affinity CLI.",
       bin: "ghostpaw-affinity",
       packageName: "@ghostpaw/affinity",
       server: "ghostpaw-affinity",
@@ -10003,22 +11500,98 @@ var init_affinity_skill_spec = __esm({
   }
 });
 
+// src/surface/affinity_skill_command.ts
+var affinity_skill_command_exports = {};
+__export(affinity_skill_command_exports, {
+  affinitySkillCommand: () => affinitySkillCommand
+});
+function affinitySkillCommand(args) {
+  if (args.includes("--help") || args.includes("-h"))
+    return "Usage: ghostpaw-affinity skill [<guide>|--list|--help]\n";
+  if (args.length > 1) throw new CliUsageError("Expected one skill guide");
+  const guide = args[0];
+  if (guide === "--list")
+    return `${Object.entries(affinitySkillReferences).map(([name, entry]) => `${name}	${entry.description}`).join("\n")}
+`;
+  if (!guide) return renderSkillMarkdown(affinitySkillSpec);
+  const found = affinitySkillReferences[guide];
+  if (found) return found.content;
+  const suggestion = suggestCommand(
+    guide,
+    Object.keys(affinitySkillReferences)
+  );
+  throw new CliUsageError(
+    `Unknown guide: ${guide}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`
+  );
+}
+var init_affinity_skill_command = __esm({
+  "src/surface/affinity_skill_command.ts"() {
+    init_cli_args();
+    init_cli_output();
+    init_skill_markdown();
+    init_affinity_skill_references();
+    init_affinity_skill_spec();
+  }
+});
+
 // src/surface/affinity_cli_options.ts
 init_version();
+
+// src/surface/affinity_cli_errors.ts
+var commands = {
+  mergeContacts: "ghostpaw-affinity contact merge"
+};
+function affinityCliError(message) {
+  let result = message;
+  for (const [source, command] of Object.entries(commands))
+    result = result.replaceAll(`use ${source}`, `use: ${command}`);
+  return result;
+}
+
+// src/surface/affinity_cli_options.ts
 init_affinity_surface_tools();
+var npmEntry = false;
+function markNpmEntry() {
+  npmEntry = true;
+}
+function cliVersion(version, {
+  sea = isSea,
+  npm = npmEntry,
+  platform = process.platform,
+  arch = process.arch
+} = {}) {
+  let binary = false;
+  try {
+    binary = sea();
+  } catch {
+  }
+  const target = `${platform === "win32" ? "windows" : platform}-${arch}`;
+  return `affinity ${version} (${binary ? `binary, ${target}` : npm ? "npm" : "library"})`;
+}
+
+// src/surface/affinity_cli_options.ts
+init_plain_dates();
+init_resolve_affinity_db_path();
 var affinityCliOptions = {
+  reportCreation: true,
+  transformInput: normalizeTimeInputs,
+  versionLine: () => cliVersion(affinityVersion),
+  describeDb: (db) => resolveAffinityDbPath(db === void 0 ? {} : { flag: db }),
+  formatError: affinityCliError,
   bin: "ghostpaw-affinity",
   version: affinityVersion,
   description: "Local relationship model and social CRM",
   tools: affinityCliSurfaceTools,
   openContext: async (options) => {
     const { openAffinityDb: openAffinityDb2 } = await Promise.resolve().then(() => (init_open_affinity_db(), open_affinity_db_exports));
-    const { resolveAffinityDbPath: resolveAffinityDbPath2 } = await Promise.resolve().then(() => (init_resolve_affinity_db_path(), resolve_affinity_db_path_exports));
-    return openAffinityDb2(
-      resolveAffinityDbPath2(
-        options.db === void 0 ? {} : { flag: options.db }
-      )
+    const path = resolveAffinityDbPath(
+      options.db === void 0 ? {} : { flag: options.db }
     );
+    const created = path !== ":memory:" && !existsSync(path);
+    const db = await openAffinityDb2(path);
+    if (created) (options.stderr ?? process.stderr).write(`created ${path}
+`);
+    return db;
   },
   closeContext: (db) => db.close(),
   commands: {
@@ -10028,125 +11601,19 @@ var affinityCliOptions = {
         options.db === void 0 ? {} : { dbPath: options.db }
       );
     },
-    skill: async () => {
-      const { renderSkillMarkdown: renderSkillMarkdown2 } = await Promise.resolve().then(() => (init_skill_markdown(), skill_markdown_exports));
-      const { affinitySkillSpec: affinitySkillSpec2 } = await Promise.resolve().then(() => (init_affinity_skill_spec(), affinity_skill_spec_exports));
-      return renderSkillMarkdown2(affinitySkillSpec2);
+    skill: async (args = []) => {
+      const { affinitySkillCommand: affinitySkillCommand2 } = await Promise.resolve().then(() => (init_affinity_skill_command(), affinity_skill_command_exports));
+      return affinitySkillCommand2(args);
     }
   }
 };
-var CliUsageError = class extends Error {
-  exitCode = 2;
-};
-var keyOf = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-function parseCliArgs(argv, spec) {
-  const values = {};
-  const positions = [];
-  const flags = spec.flags ?? [];
-  const convert = (raw, arg) => {
-    let value = raw;
-    if (raw.startsWith("@")) {
-      try {
-        value = readFileSync(raw.slice(1), "utf8");
-      } catch {
-        throw new CliUsageError(`Cannot read value file: ${raw.slice(1)}`);
-      }
-    }
-    let result = value;
-    if (arg.type === "number" || arg.type === "integer") {
-      result = Number(value);
-      if (!value.trim() || !Number.isFinite(result) || arg.type === "integer" && !Number.isInteger(result))
-        throw new CliUsageError(
-          `Expected ${arg.type} for ${arg.name}: ${value}`
-        );
-    } else if (arg.type === "boolean") {
-      if (!["true", "false"].includes(value))
-        throw new CliUsageError(`Expected boolean for ${arg.name}`);
-      result = value === "true";
-    } else if (arg.type === "json") {
-      try {
-        result = JSON.parse(value);
-      } catch {
-        throw new CliUsageError(`Invalid JSON for ${arg.name}`);
-      }
-    }
-    if (arg.enum && !arg.enum.includes(result))
-      throw new CliUsageError(
-        `${arg.name} must be one of: ${arg.enum.join(", ")}`
-      );
-    return result;
-  };
-  let ended = false;
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    if (!ended && token === "--") {
-      ended = true;
-      continue;
-    }
-    if (ended || token === "-" || !token.startsWith("-")) {
-      positions.push(token);
-      continue;
-    }
-    const [flag, inline] = token.split(/=(.*)/s);
-    const negative = flag?.startsWith("--no-");
-    const name = flag?.replace(/^--?/, "").replace(/^no-/, "");
-    const arg = flags.find(
-      (entry) => entry.name === name || keyOf(entry.name) === name || entry.short === name
-    );
-    if (!arg) {
-      const prefix = (name ?? "").slice(0, 3);
-      const suggestion = prefix ? flags.find((entry) => entry.name.startsWith(prefix)) : void 0;
-      throw new CliUsageError(
-        `Unknown flag: ${flag}${suggestion ? `; did you mean --${suggestion.name}?` : ""}`
-      );
-    }
-    if (negative && arg.type !== "boolean")
-      throw new CliUsageError(`--no-${arg.name} requires a boolean flag`);
-    let raw = inline;
-    if (arg.type === "boolean" && raw === void 0)
-      raw = negative ? "false" : "true";
-    if (raw === void 0) {
-      const next = argv[i + 1];
-      if (next === void 0 || next.startsWith("--"))
-        throw new CliUsageError(`Missing value: --${arg.name}`);
-      raw = next;
-      i++;
-    }
-    const key = keyOf(arg.name);
-    if (arg.type === "array") {
-      const item = convert(raw, { ...arg, type: arg.itemType ?? "string" });
-      values[key] = [...values[key] ?? [], item];
-    } else values[key] = convert(raw, arg);
-  }
-  let index = 0;
-  for (const arg of spec.positionals ?? []) {
-    if (index >= positions.length) continue;
-    values[keyOf(arg.name)] = arg.variadic ? positions.slice(index).map(
-      (value) => convert(value, { ...arg, type: arg.itemType ?? arg.type })
-    ) : convert(positions[index], arg);
-    index = arg.variadic ? positions.length : index + 1;
-  }
-  if (index < positions.length)
-    throw new CliUsageError(`Unexpected positional: ${positions[index]}`);
-  for (const arg of [...flags, ...spec.positionals ?? []]) {
-    if (arg.required && values[keyOf(arg.name)] === void 0)
-      throw new CliUsageError(`Missing required argument: ${arg.name}`);
-  }
-  return values;
-}
-function renderCliHelp(spec) {
-  const describe = (arg) => `${arg.type}${arg.enum ? ` (${arg.enum.join("|")})` : ""}${arg.required ? " required" : ""}  ${arg.description ?? ""}`;
-  return `Usage: ${spec.command} ${(spec.positionals ?? []).map((arg) => `<${arg.name}${arg.variadic ? "..." : ""}>`).join(" ")} [flags]
-${spec.description ?? ""}
 
-Positionals:
-${(spec.positionals ?? []).map((arg) => `  ${arg.name}  ${describe(arg)}`).join("\n")}
-Flags:
-${(spec.flags ?? []).map((arg) => `  --${arg.name}${arg.short ? `, -${arg.short}` : ""}  ${describe(arg)}`).join("\n")}
-`;
-}
+// src/surfaces/cli.ts
+init_cli_args();
 
 // src/surfaces/cli_commands.ts
+init_cli_args();
+init_cli_output();
 init_validate_input();
 function cliCommands(tools) {
   return tools.flatMap((tool) => {
@@ -10218,14 +11685,16 @@ async function runCliCommand(argv, options) {
       else if (flag === "--compact") compact = true;
       else if (flag === "--help" || flag === "-h") help = true;
       else if (["--version", "-V", "-v"].includes(flag ?? "")) {
-        if (!quiet) stdout.write(`${options.version}
+        if (!quiet)
+          stdout.write(`${options.versionLine?.() ?? options.version}
 `);
         return 0;
       } else if (flag !== "--no-color") continue;
       args.splice(i--, 1);
     }
     if (args[0] === "version") {
-      if (!quiet) stdout.write(`${options.version}
+      if (!quiet)
+        stdout.write(`${options.versionLine?.() ?? options.version}
 `);
       return 0;
     }
@@ -10240,10 +11709,12 @@ async function runCliCommand(argv, options) {
     const specFor = (command) => {
       const argument = (name, schema) => ({
         name,
-        type: schema.type === "object" || !schema.type ? "json" : schema.type,
+        type: options.transformInput && /(?:At|-at)$|^(asOf|as-of|now)$/.test(name) ? "string" : schema.type === "object" || !schema.type && !schema.oneOf?.some((branch) => branch.type === "string") ? "json" : schema.type ?? "string",
         description: schema.description,
         enum: schema.enum,
-        ...schema.items?.type ? { itemType: schema.items.type } : {}
+        ...schema.items?.type ? {
+          itemType: schema.items.type === "object" || schema.items.type === "array" ? "json" : schema.items.type
+        } : {}
       });
       const properties = command.tool.inputSchema.properties ?? {};
       return {
@@ -10274,7 +11745,7 @@ async function runCliCommand(argv, options) {
         throw new CliUsageError(`Unknown command: ${args.join(" ")}`);
       if (!quiet)
         stdout.write(
-          entry ? renderCliHelp(specFor(entry)) : `${options.bin} ${options.version}
+          entry ? renderCliHelp(specFor(entry)) : `${options.versionLine?.() ?? `${options.bin} ${options.version}`}
 ${options.description}
 
 Commands:
@@ -10283,6 +11754,9 @@ ${matches.map((command) => `  ${command.path}`).join("\n")}
 Global flags: --db <path>, --json, --quiet, --compact, --help/-h, --version/-V/-v, --no-color
 `
         );
+      if (options.describeDb && !quiet)
+        stdout.write(`Database: ${options.describeDb(db)}
+`);
       return 0;
     }
     if (args[0] === "completions") {
@@ -10317,7 +11791,16 @@ _arguments '*:command:(${words.join(" ")})'
         throw new CliUsageError("Expected completion shell: bash, zsh or fish");
       return 0;
     }
-    if (!entry) throw new CliUsageError(`Unknown command: ${args.join(" ")}`);
+    if (!entry) {
+      const path = args.filter((x) => !x.startsWith("--")).slice(0, 2).join(" ");
+      const suggestion = suggestCommand(
+        path,
+        tree.map((c) => c.path)
+      );
+      throw new CliUsageError(
+        `Unknown command: ${path}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`
+      );
+    }
     const rest = args.slice(entry.path.split(" ").length);
     let base = {};
     const spec = specFor(entry);
@@ -10347,29 +11830,42 @@ _arguments '*:command:(${words.join(" ")})'
       if (!base || typeof base !== "object" || Array.isArray(base))
         throw new CliUsageError("Expected stdin JSON object");
     }
-    const input = {
+    const objectPositions = entry.positionals.filter(
+      (name) => entry.tool.inputSchema.properties?.[name]?.type === "object"
+    );
+    if (objectPositions.length === 1 && base && typeof base === "object" && Object.keys(base).length && !(objectPositions[0] in base))
+      base = { [objectPositions[0]]: base };
+    let input = {
       ...base,
       ...parseCliArgs(rest, spec),
       ...entry.fixed
     };
+    for (const [key, schema] of Object.entries(
+      entry.tool.inputSchema.properties ?? {}
+    )) {
+      if (schema.type === "array" && schema.items?.type === "object" && Array.isArray(input[key]))
+        input[key] = input[key].flat();
+    }
+    input = options.transformInput?.(input) ?? input;
     const errors = validateInput(entry.tool.inputSchema, input);
     if (errors.length) throw new CliUsageError(errors.join("\n"));
-    const context = await options.openContext(db === void 0 ? {} : { db });
+    const context = await options.openContext({
+      ...db === void 0 ? {} : { db },
+      ...options.reportCreation ? { stderr } : {}
+    });
     try {
       const result = await entry.tool.handler(context, input);
       const record = result;
-      const code = record.outcome === "needs_clarification" || record.error?.code === "not_found" ? 3 : ["conflict", "version_mismatch"].includes(record.error?.code ?? "") ? 4 : record.ok === false ? 1 : 0;
+      const code = cliExitCode(result);
       if (code)
         stderr.write(
-          `${record.error?.message ?? record.summary ?? "Tool failed"}
+          `${code === 70 ? "internal error: " : ""}${options.formatError?.(record.error?.message ?? record.summary ?? "Tool failed") ?? record.error?.message ?? record.summary ?? "Tool failed"}
 `
         );
       if (!quiet)
         stdout.write(
-          json || !stdout.isTTY ? `${JSON.stringify(result, null, compact ? void 0 : 2)}
-` : `${record.summary ?? ""}
-${JSON.stringify(record.data ?? {}, null, 2)}
-`
+          json || !stdout.isTTY ? `${JSON.stringify(plainJson(result, compact, options.formatError), null, compact ? void 0 : 2)}
+` : humanResult(result)
         );
       return code;
     } finally {
@@ -10377,22 +11873,24 @@ ${JSON.stringify(record.data ?? {}, null, 2)}
     }
   } catch (error) {
     return fail(
-      error instanceof Error ? error.message : String(error),
+      `${error instanceof CliUsageError ? "" : "internal error: "}${error instanceof Error ? error.message : String(error)}`,
       error instanceof CliUsageError ? 2 : 70
     );
   }
 }
 
 // src/surfaces/cli.ts
-init_surface_types();
+init_cli_output();
 init_validate_input();
-async function runToolCli(argv, providedOptions) {
+async function runToolCliInternal(argv, providedOptions) {
   let options = providedOptions;
   const end = argv.indexOf("--");
   if (argv.slice(0, end < 0 ? argv.length : end).some((arg) => ["--version", "-V", "-v"].includes(arg))) {
     if (!argv.includes("--quiet"))
-      (options.stdout ?? process.stdout).write(`${options.version}
-`);
+      (options.stdout ?? process.stdout).write(
+        `${options.versionLine?.() ?? options.version}
+`
+      );
     return 0;
   }
   const modern = await runCliCommand(argv, options);
@@ -10444,7 +11942,7 @@ async function runToolCli(argv, providedOptions) {
   const normalize = (name2) => name2.replace(/[-_]/g, "").toLowerCase();
   if (["help", "--help", "-h"].includes(command)) {
     stdout.write(
-      `${options.bin} ${options.version}
+      `${options.versionLine?.() ?? `${options.bin} ${options.version}`}
 ${options.description}
 
 Usage: ${options.bin} [--db path] <command>
@@ -10457,7 +11955,7 @@ ${options.tools.map((tool2) => `${tool2.name}  ${tool2.description}`).join("\n")
     return 0;
   }
   if (["--version", "-V", "-v", "version"].includes(command)) {
-    stdout.write(`${options.version}
+    stdout.write(`${options.versionLine?.() ?? options.version}
 `);
     return 0;
   }
@@ -10477,7 +11975,14 @@ ${options.tools.map((tool2) => `${tool2.name}  ${tool2.description}`).join("\n")
   }
   if (command === "skill") {
     if (!options.commands?.skill) return fail("skill command unavailable");
-    stdout.write(await options.commands.skill());
+    try {
+      stdout.write(await options.commands.skill(args));
+    } catch (error) {
+      return fail(
+        `${error instanceof CliUsageError ? "" : "internal error: "}${error instanceof Error ? error.message : String(error)}`,
+        error instanceof CliUsageError ? 2 : 70
+      );
+    }
     return 0;
   }
   if (command === "mcp") {
@@ -10521,7 +12026,7 @@ ${JSON.stringify(tool.inputSchema, null, 2)}
       if (args.length > 1) return fail("Expected a single JSON argument");
       const raw = args[0];
       input = JSON.parse(
-        raw === "-" || raw === void 0 && !stdin.isTTY ? await readStdin() : raw ?? "{}"
+        raw === "-" || raw === void 0 && !stdin.isTTY ? await readStdin() : raw?.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw ?? "{}"
       );
     } else {
       const values = {};
@@ -10565,40 +12070,79 @@ ${JSON.stringify(tool.inputSchema, null, 2)}
             ...Array.isArray(prior) ? prior : [],
             coerce(raw, schema.items ?? {})
           ];
-        } else values[property] = coerce(raw, schema);
+        } else
+          values[property] = options.transformInput && /At$|^(asOf|now)$/.test(property) ? raw : coerce(raw, schema);
       }
       input = values;
     }
   } catch (cause) {
     return fail(
       `Invalid input: ${cause instanceof Error ? cause.message : String(cause)}`,
-      1
+      2
     );
   }
+  try {
+    input = options.transformInput?.(input) ?? input;
+  } catch (cause) {
+    return fail(cause instanceof Error ? cause.message : String(cause), 2);
+  }
   const errors = validateInput(tool.inputSchema, input);
-  if (errors.length) return fail(errors.join("\n"), 1);
+  if (errors.length) return fail(errors.join("\n"), 2);
   let context;
   try {
-    context = await options.openContext(ctxOptions);
+    context = await options.openContext(
+      options.reportCreation ? { ...ctxOptions, stderr } : ctxOptions
+    );
   } catch (cause) {
-    return fail(String(cause), 1);
+    return fail(
+      `internal error: ${cause instanceof Error ? cause.message : String(cause)}`,
+      70
+    );
   }
   try {
     const result = await tool.handler(
       context,
       input
     );
-    stdout.write(`${JSON.stringify(result, null, compact ? void 0 : 2)}
-`);
-    if (typeof result === "object" && result !== null && "outcome" in result && result.outcome === "needs_clarification")
-      return 3;
-    return isErrorResult(result) ? 1 : 0;
+    stdout.write(
+      explicitJson || !stdout.isTTY ? `${JSON.stringify(plainJson(result, compact, options.formatError), null, compact ? void 0 : 2)}
+` : humanResult(result)
+    );
+    const code = cliExitCode(result);
+    if (code) {
+      const r = result;
+      const message = r.error?.message ?? r.summary ?? "Tool failed";
+      stderr.write(
+        `${code === 70 ? "internal error: " : ""}${options.formatError?.(message) ?? message}
+`
+      );
+    }
+    return code;
   } catch (cause) {
-    return fail(String(cause), 1);
+    return fail(
+      `internal error: ${cause instanceof Error ? cause.message : String(cause)}`,
+      70
+    );
   } finally {
     await options.closeContext?.(context);
   }
 }
+async function runToolCli(argv, options) {
+  try {
+    return await runToolCliInternal(argv, options);
+  } catch (error) {
+    const message = `internal error: ${error instanceof Error ? error.message : String(error)}`;
+    (options.stderr ?? process.stderr).write(`${message}
+`);
+    if (argv.includes("--json") && !argv.includes("--quiet"))
+      (options.stdout ?? process.stdout).write(
+        `${JSON.stringify({ ok: false, error: { code: "internal_error", message } })}
+`
+      );
+    return 70;
+  }
+}
 
 // src/cli.ts
+markNpmEntry();
 process.exitCode = await runToolCli(process.argv.slice(2), affinityCliOptions);