@ghostpaw/affinity 0.4.0 → 0.4.1

package/README.md

@@ -110,6 +110,12 @@ curl -fsSL https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.sh
 irm https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.ps1 | iex
 ```
 
+A session with the 0.4.0 linux-x64 binary against a fresh database (output piped through `jq` to keep it short):
+
+![ghostpaw-affinity 0.4.0: version, contact create, identity add, event and commitment record, search, review commitments.open and show contact_profile](https://raw.githubusercontent.com/GhostPawJS/affinity/main/docs/assets/cli.png)
+
+The same session as an [animated GIF](https://raw.githubusercontent.com/GhostPawJS/affinity/main/docs/assets/cli.gif).
+
 Other release installers:
 
 ```sh
@@ -163,7 +169,19 @@ download on macOS, remove quarantine with
 Linux binaries require glibc 2.28+; use npx on Alpine.
 See the [binary build workflow](.github/workflows/release-binaries.yml).
 
-<!-- sizes -->
+Sizes for 0.4.0 (Node 26.12.1 inside each binary):
+
+| Target | Archive | Binary |
+|---|---|---|
+| linux-x64 | 41.7 MB tar.gz | 117.6 MB |
+| linux-arm64 | 41.2 MB tar.gz | 115.3 MB |
+| darwin-arm64 | 44.9 MB tar.gz | 146.8 MB |
+| darwin-x64 | 46.4 MB tar.gz | 149.7 MB |
+| windows-x64 | 38.4 MB zip | 105.7 MB |
+
+The npm package is 2003 KB unpacked and needs Node 24+. Every release is
+installed and run on ubuntu-24.04, macos-15 and windows-2025 by the
+[install check](.github/workflows/install-check.yml).
 
 The install check runs on ubuntu-24.04, macos-15 and windows-2025.
 

package/dist/cli.js

@@ -23,7 +23,7 @@ var __export = (target, all) => {
 var affinityVersion;
 var init_version = __esm({
   "src/version.ts"() {
-    affinityVersion = "0.4.0";
+    affinityVersion = "0.4.1";
   }
 });
 
@@ -2492,21 +2492,6 @@ 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) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
@@ -2520,7 +2505,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 +2515,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" };
   }
 });
 
@@ -4296,13 +4298,20 @@ function createContact(db, input) {
     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 FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "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");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -7405,6 +7414,21 @@ var init_list_dismissed_duplicates = __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/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {
@@ -10107,7 +10131,7 @@ function parseCliArgs(argv, spec) {
       raw = negative ? "false" : "true";
     if (raw === void 0) {
       const next = argv[i + 1];
-      if (next === void 0 || next.startsWith("--"))
+      if (next === void 0 || /^--[a-z]/i.test(next))
         throw new CliUsageError(`Missing value: --${arg.name}`);
       raw = next;
       i++;

package/dist/index.cjs

@@ -788,13 +788,20 @@ function createContact(db, input) {
     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 FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "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");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -6453,17 +6460,6 @@ function unsetAttribute(db, target, name, removedAt) {
   });
 }
 
-// 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.`;
-}
-
 // src/tools/tool_mutation.ts
 function mutationToolResult(action, receipt, entitySummary) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
@@ -6477,7 +6473,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)
@@ -6487,6 +6483,23 @@ function mutationToolResult(action, receipt, entitySummary) {
     entities: toReceiptEntityRefs(receipt)
   });
 }
+var PLURALS = { identity: "identities" };
+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)}.`;
+}
 
 // src/tools/manage_attribute_tool.ts
 function contactLocatorSchema2(description) {
@@ -7868,6 +7881,17 @@ var recordEventTool = defineAffinityTool({
   handler: recordEventToolHandler
 });
 
+// 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.`;
+}
+
 // src/tools/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {

package/dist/index.js

@@ -786,13 +786,20 @@ function createContact(db, input) {
     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 FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "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");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -6451,17 +6458,6 @@ function unsetAttribute(db, target, name, removedAt) {
   });
 }
 
-// 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.`;
-}
-
 // src/tools/tool_mutation.ts
 function mutationToolResult(action, receipt, entitySummary) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
@@ -6475,7 +6471,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)
@@ -6485,6 +6481,23 @@ function mutationToolResult(action, receipt, entitySummary) {
     entities: toReceiptEntityRefs(receipt)
   });
 }
+var PLURALS = { identity: "identities" };
+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)}.`;
+}
 
 // src/tools/manage_attribute_tool.ts
 function contactLocatorSchema2(description) {
@@ -7866,6 +7879,17 @@ var recordEventTool = defineAffinityTool({
   handler: recordEventToolHandler
 });
 
+// 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.`;
+}
+
 // src/tools/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {

package/dist/mcp-server.js

@@ -285,7 +285,7 @@ var init_mcp_stdio = __esm({
 var affinityVersion;
 var init_version = __esm({
   "src/version.ts"() {
-    affinityVersion = "0.4.0";
+    affinityVersion = "0.4.1";
   }
 });
 
@@ -2762,21 +2762,6 @@ 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) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
@@ -2790,7 +2775,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)
@@ -2800,11 +2785,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" };
   }
 });
 
@@ -4566,13 +4568,20 @@ function createContact(db, input) {
     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 FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "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");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -7675,6 +7684,21 @@ var init_list_dismissed_duplicates = __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/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {

package/dist/mcp.cjs

@@ -5,7 +5,7 @@ var node_path = require('node:path');
 var node_os = require('node:os');
 
 // src/version.ts
-var affinityVersion = "0.4.0";
+var affinityVersion = "0.4.1";
 
 // src/surface/affinity_mcp_instructions.ts
 var affinityMcpInstructions = "Affinity is a local relationship model and social CRM. Search before creating contacts. Inspect before revising or merging. Record direct evidence honestly, keep identities and structural ties distinct from social links, and ask for clarification when a target is ambiguous. Review commitments and recurring dates regularly. Derived scores guide attention and do not prove relationship quality.";
@@ -2160,17 +2160,6 @@ function unsetAttribute(db, target, name, removedAt) {
   });
 }
 
-// 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.`;
-}
-
 // src/tools/tool_mutation.ts
 function mutationToolResult(action, receipt, entitySummary) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
@@ -2184,7 +2173,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)
@@ -2194,6 +2183,23 @@ function mutationToolResult(action, receipt, entitySummary) {
     entities: toReceiptEntityRefs(receipt)
   });
 }
+var PLURALS = { identity: "identities" };
+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)}.`;
+}
 
 // src/tools/manage_attribute_tool.ts
 function contactLocatorSchema2(description) {
@@ -3825,13 +3831,20 @@ function createContact(db, input) {
     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 FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "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");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -6451,6 +6464,17 @@ function listDismissedDuplicates(db, options) {
   }));
 }
 
+// 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.`;
+}
+
 // src/tools/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {

package/dist/mcp.js

@@ -3,7 +3,7 @@ import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
 // src/version.ts
-var affinityVersion = "0.4.0";
+var affinityVersion = "0.4.1";
 
 // src/surface/affinity_mcp_instructions.ts
 var affinityMcpInstructions = "Affinity is a local relationship model and social CRM. Search before creating contacts. Inspect before revising or merging. Record direct evidence honestly, keep identities and structural ties distinct from social links, and ask for clarification when a target is ambiguous. Review commitments and recurring dates regularly. Derived scores guide attention and do not prove relationship quality.";
@@ -2158,17 +2158,6 @@ function unsetAttribute(db, target, name, removedAt) {
   });
 }
 
-// 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.`;
-}
-
 // src/tools/tool_mutation.ts
 function mutationToolResult(action, receipt, entitySummary) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
@@ -2182,7 +2171,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)
@@ -2192,6 +2181,23 @@ function mutationToolResult(action, receipt, entitySummary) {
     entities: toReceiptEntityRefs(receipt)
   });
 }
+var PLURALS = { identity: "identities" };
+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)}.`;
+}
 
 // src/tools/manage_attribute_tool.ts
 function contactLocatorSchema2(description) {
@@ -3823,13 +3829,20 @@ function createContact(db, input) {
     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 FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "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");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -6449,6 +6462,17 @@ function listDismissedDuplicates(db, options) {
   }));
 }
 
+// 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.`;
+}
+
 // src/tools/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostpaw/affinity",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Relationship intelligence and social CRM model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
   "license": "MIT",
   "author": {