@ghostpaw/affinity 0.2.4 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostpaw/affinity",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "Relationship intelligence and social CRM model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
   "license": "MIT",
   "author": {
@@ -15,7 +15,7 @@
   "bugs": {
     "url": "https://github.com/GhostPawJS/affinity/issues"
   },
-  "homepage": "https://github.com/GhostPawJS/affinity",
+  "homepage": "https://affinity.ghostpaw.dev/",
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/Anonyfox"
@@ -45,9 +45,19 @@
     "agent",
     "tools",
     "typescript",
-    "zero-dependencies"
+    "zero-dependencies",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "agent-skills",
+    "cli",
+    "ghostpaw",
+    "ai-agents",
+    "llm-tools",
+    "node-sqlite",
+    "local-first"
   ],
-  "files": ["dist"],
+  "files": ["dist", "skills", "SKILL.md"],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -61,7 +71,18 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
-    }
+    },
+    "./mcp": {
+      "import": {
+        "types": "./dist/mcp.d.ts",
+        "default": "./dist/mcp.js"
+      },
+      "require": {
+        "types": "./dist/mcp.d.cts",
+        "default": "./dist/mcp.cjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "build": "tsup",
@@ -74,22 +95,46 @@
     "lint:fix": "biome check --fix",
     "format": "biome format --write",
     "typecheck": "tsc --noEmit",
-    "check": "biome check && tsc --noEmit",
+    "check": "npm run check:types && npm run check:lint && npm test && npm run build && npm run check:deps && npm run check:surfaces && npm run check:size && npm run check:api && npm run check:consumer && npm run check:startup && npm run check:ratchet",
+    "check:deps": "node scripts/check-zero-deps.mjs",
     "clean": "rm -rf dist demo",
-    "version": "biome format --write package.json package-lock.json && git add package.json package-lock.json",
-    "prepublishOnly": "npm run check && npm run build",
+    "version": "node scripts/sync_version.mjs && npm run surfaces && git add src/version.ts SKILL.md skills plugin.json mcp.json server.json .claude-plugin mcpb && biome format --write package.json package-lock.json && git add package.json package-lock.json",
+    "prepublishOnly": "npm run check",
     "release:patch": "npm version patch && git push && git push --tags",
     "release:minor": "npm version minor && git push && git push --tags",
-    "release:major": "npm version major && git push && git push --tags"
+    "release:major": "npm version major && git push && git push --tags",
+    "surfaces": "node --experimental-strip-types scripts/surfaces/generate.mjs",
+    "check:surfaces": "node --experimental-strip-types scripts/surfaces/generate.mjs --check",
+    "check:types": "tsc --noEmit",
+    "check:lint": "biome check",
+    "check:ratchet": "node --test scripts/guard/*.test.mjs && node scripts/guard/ratchet.mjs",
+    "budgets:update": "npm run build && node scripts/guard/size.mjs --update && node scripts/guard/api.mjs --update && node scripts/guard/startup.mjs --update",
+    "bench": "npm run build && node scripts/bench/bench.mjs",
+    "check:size": "node scripts/guard/size.mjs",
+    "check:api": "node scripts/guard/api.mjs",
+    "check:consumer": "node scripts/guard/consumer.mjs",
+    "check:startup": "node scripts/guard/startup.mjs",
+    "mcpb": "node scripts/mcpb/build.mjs",
+    "sea": "node scripts/sea/build.mjs",
+    "sea:smoke": "node scripts/sea/smoke.mjs",
+    "sea:bench": "node scripts/sea/bench.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/node": "^24.12.0",
     "@types/sql.js": "^1.4.10",
-    "esbuild": "^0.27.4",
+    "esbuild": "^0.28.1",
+    "fflate": "0.8.3",
     "preact": "^10.29.0",
     "sql.js": "^1.14.1",
     "tsup": "^8.4.0",
     "typescript": "^5.8.2"
+  },
+  "bin": {
+    "ghostpaw-affinity": "./dist/cli.js"
+  },
+  "mcpName": "io.github.GhostPawJS/affinity",
+  "overrides": {
+    "esbuild": "$esbuild"
   }
 }

package/skills/affinity/SKILL.md

@@ -0,0 +1,283 @@
+---
+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."
+---
+
+# affinity
+
+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.
+
+## Calling tools
+
+MCP: connect to ghostpaw-affinity, then call a tool by name with its JSON arguments.
+
+CLI: `ghostpaw-affinity call <tool> '<JSON object>'` or `ghostpaw-affinity <tool> --parameter value` (without a global install: `npx -y @ghostpaw/affinity <tool> ...`).
+
+Inspect schemas with `ghostpaw-affinity describe <tool>`. Use `--db <path>` to select a database.
+
+## search_affinity
+
+Search contacts by name or identity, including exact natural-key lookups like email-style identifiers.
+
+Use when: Use this when you want to find contacts from free text or a known routing identity such as an email or URL-like handle.
+
+Not for: Do not use this when you already know the exact contact you want to inspect in depth.
+
+Read-only.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| query | string | yes | Free-text or natural-key query. |
+| kind | string | no | human, group, company, team, pet, service, other. Optional contact kind filter. |
+| lifecycleState | string | no | active, dormant, merged, lost. Optional lifecycle state filter. |
+| includeOwner | boolean | no | Whether owner contacts are included. |
+| includeDormant | boolean | no | Whether dormant contacts are included. |
+| limit | integer | no | Optional result limit. |
+| offset | integer | no | Optional result offset. |
+
+## review_affinity
+
+Review one affinity surface such as contacts, journals, link queues, commitments, dates, graph state, or merge history.
+
+Use when: Use this when you want a dashboard-style list or review view instead of inspecting one exact item.
+
+Not for: Do not use this when you already know the exact contact or link you want to inspect in depth.
+
+Read-only.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| view | string | yes | contacts.list, contacts.duplicates, events.contact_journal, events.link_timeline, events.moments, commitments.open, links.owner, links.observed, links.progression_readiness, links.radar, dates.upcoming, graph.chart, merges.history, merges.dismissed. Which review surface to return. |
+| contact | object | no | Optional target contact locator. |
+| link | object | no | Optional target link locator. |
+| contactIds | array | no | Optional contact-id subset. |
+| kind | string | no | Optional contact kind or link kind filter, depending on the view. |
+| lifecycleState | string | no | active, dormant, merged, lost. Optional contact lifecycle-state filter. |
+| linkState | string | no | active, dormant, strained, broken, archived. Optional link state filter. |
+| includeOwner | boolean | no | Whether owner contacts are included. |
+| includeDormant | boolean | no | Whether dormant rows are included. |
+| includeArchived | boolean | no | Whether archived links are included. |
+| includeObserved | boolean | no | Whether observed links are included. |
+| eventTypes | array | no | Optional event-type filter. |
+| momentKind | string | no | breakthrough, rupture, reconciliation, milestone, turning_point. Optional moment kind filter. |
+| commitmentType | string | no | promise, agreement. Optional commitment type filter. |
+| recurrenceKind | string | no | birthday, anniversary, renewal, memorial, custom_yearly. Optional recurrence-kind filter. |
+| horizonDays | integer | no | Optional horizon-days filter. |
+| exactOnly | boolean | no | Whether duplicate review is exact-only. |
+| minScore | number | no | Optional duplicate minimum score. |
+| includeDismissed | boolean | no | Whether dismissed pairs are included in duplicate review (marked with dismissed flag). |
+| since | integer | no | Optional lower timestamp bound. |
+| until | integer | no | Optional upper timestamp bound. |
+| limit | integer | no | Optional result limit. |
+| offset | integer | no | Optional result offset. |
+
+## inspect_affinity_item
+
+Inspect one exact affinity item such as the owner profile, a contact profile, or one link detail.
+
+Use when: Use this when you already know the exact item you want to inspect in depth.
+
+Not for: Do not use this for search-style discovery or dashboard-like list reviews.
+
+Read-only.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| kind | string | yes | owner_profile, contact_profile, link. What to inspect. |
+| contact | object | no | Target contact. Required when kind=contact_profile. Provide contactId or identity. |
+| link | object | no | Target link. Required when kind=link. Provide linkId or endpoints. |
+| topLinksLimit | integer | no | Optional top-links cap. |
+| recentEventsLimit | integer | no | Optional recent-events cap. |
+
+## manage_contact
+
+Create a contact, revise one contact's core fields, or change lifecycle state. ALWAYS search_affinity first before creating — duplicates corrupt the graph.
+
+Use when: Use this for contact creation and lifecycle-safe contact maintenance.
+
+Not for: Do not use this for identities, links, attributes, or merges.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | create, revise, set_lifecycle. Operation to perform. |
+| input | object | no | New contact payload. Required when action=create. |
+| contact | object | no | Target contact. Required when action=revise or set_lifecycle. Provide contactId or identity. |
+| patch | object | no | Allowed contact patch. Required when action=revise. |
+| lifecycleState | string | no | active, dormant, merged, lost. Target lifecycle state. Required when action=set_lifecycle. |
+| options | object | no | Optional lifecycle metadata. |
+
+## merge_contacts
+
+Merge one loser contact into one winner contact using explicit contact locators.
+
+Use when: Use this only when two contacts are confirmed duplicates and the system should consolidate them.
+
+Not for: Do not use this for routine contact edits or identity cleanup.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| winner | object | yes | Winner contact. Provide contactId or identity. |
+| loser | object | yes | Loser contact. Provide contactId or identity. |
+| reasonSummary | string | no | Optional merge reason. |
+| now | integer | no | Optional merge timestamp. |
+
+## manage_duplicate_dismissal
+
+Dismiss or un-dismiss a duplicate candidate pair so it does not resurface in listDuplicateCandidates.
+
+Use when: Use dismiss after confirming two contacts are different people (not duplicates). Use undismiss to re-surface a pair for re-evaluation.
+
+Not for: Do not use this to merge contacts — use merge_contacts for confirmed duplicates.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | dismiss, undismiss. Action to perform. |
+| left | object | yes | Left contact. Provide contactId or identity. |
+| right | object | yes | Right contact. Provide contactId or identity. |
+| reason | any | no | Optional reason for the dismissal. |
+
+## manage_identity
+
+Add, revise, verify, or remove one routing identity on a contact. Use this for emails, phone numbers, social handles, and URLs — anything that could locate a person. Do not use manage_attribute for these.
+
+Use when: Use this for contact identity management such as email, handle, or phone routing keys.
+
+Not for: Do not use this for contact core fields, links, or attributes.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | add, revise, verify, remove. Operation to perform. |
+| contact | object | no | Target contact. Required when action=add. Provide contactId or identity. |
+| input | object | no | New identity payload. Required when action=add. |
+| identityId | integer | no | Identity id. Required when action=revise, verify, or remove. |
+| patch | object | no | Identity patch. Required when action=revise. |
+| verifiedAt | integer | no | Verification timestamp. Optional for action=verify. |
+| removedAt | integer | no | Removal timestamp. Optional for action=remove. |
+
+## manage_relationship
+
+Seed social links, revise bond and state, and manage structural ties. Seed a link as soon as a relationship is mentioned — do not wait for repeated evidence.
+
+Use when: Use this for direct relationship modeling and link-state changes.
+
+Not for: Do not use this for recording social evidence or resolving commitments.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | seed_social_link, revise_bond, override_state, set_structural_tie, remove_structural_tie. Operation to perform. |
+| from | object | no | Source contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity. |
+| to | object | no | Target contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity. |
+| kind | string | no | Link kind. Required for seed_social_link and set_structural_tie. Can be passed here or inside input. For seed_social_link: personal, family, professional, romantic, care, service, observed, other_relational. For set_structural_tie: works_at, manages, member_of, married_to, partner_of, parent_of, child_of, sibling_of, friend_of, client_of, vendor_of, reports_to, belongs_to, other_structural. |
+| role | string | no | Optional role for seed_social_link or set_structural_tie. Can be passed here or inside input. |
+| input | object | no | Full payload for seed_social_link or set_structural_tie. Alternative to top-level kind/role. |
+| link | object | no | Target link. Required when action=revise_bond, override_state, or remove_structural_tie. Provide linkId or endpoints. |
+| bond | any | no | Bond text. Required when action=revise_bond. Null to clear. |
+| state | string | no | active, dormant, strained, broken, archived. Link state. Required when action=override_state. |
+| options | object | no | Optional metadata. |
+| removedAt | integer | no | Removal timestamp. Optional for action=remove_structural_tie. |
+
+## record_event
+
+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.
+
+Use when: Use this when you are capturing something that happened in the relationship graph.
+
+Not for: Do not use this for commitments, date anchors, or direct relationship state overrides.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| kind | string | yes | interaction, observation, milestone, transaction. Event kind. |
+| input | object | yes | Event payload. Always required. Interaction events also require `type`. |
+
+## manage_commitment
+
+Record or resolve one commitment such as a promise or agreement. The owner contact is auto-injected into participants if missing.
+
+Use when: Use this when the work is specifically about a commitment lifecycle rather than a general event.
+
+Not for: Do not use this for ordinary interactions or direct relationship state changes.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | record, resolve. Operation to perform. |
+| input | object | no | Commitment payload. Required when action=record. |
+| commitmentEventId | integer | no | Commitment event id. Required when action=resolve. |
+| resolution | string | no | kept, cancelled, broken. How the commitment was resolved. Required when action=resolve. |
+| options | object | no | Optional metadata. |
+
+## manage_date_anchor
+
+Add, revise, or remove recurring date anchors on contacts or links. Use this for birthdays, anniversaries, and yearly events — not manage_attribute.
+
+Use when: Use this for birthdays, anniversaries, renewals, memorials, and other recurring anchors.
+
+Not for: Do not use this for one-off events or relationship state changes.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | add, revise, remove. Operation to perform. |
+| input | object | no | Date anchor payload. Required when action=add. |
+| anchorEventId | integer | no | Anchor event id. Required when action=revise or remove. |
+| patch | object | no | Anchor patch. Required when action=revise. |
+| options | object | no | Optional metadata. |
+| removedAt | integer | no | Removal timestamp. Optional for action=remove. |
+
+## manage_attribute
+
+Set, unset, or replace custom metadata attributes on contacts and links. For emails, phones, handles, and URLs use manage_identity instead — those are routing keys, not attributes.
+
+Use when: Use this for metadata such as tags, notes, or small labeled facts attached to a contact or link.
+
+Not for: Do not use this for core contact fields, identities, or direct relationship mechanics.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | set, unset, replace. Operation to perform. |
+| target | object | no | Attribute target. Always required. |
+| name | string | no | Attribute name. Required when action=set or unset. |
+| value | any | no | Attribute value. Required when action=set. Null for presence/tag semantics. |
+| entries | array | no | Key-value map to replace all attributes. Required when action=replace. |
+| removedAt | integer | no | Removal timestamp. Optional for action=unset. |
+
+## Workflow guides
+
+- [bootstrap-and-cold-start](references/bootstrap-and-cold-start.md): Establish a clean Affinity baseline with one owner, one verified identity, and the minimum structure needed for later evidence and review work.
+- [identify-and-locate-contacts](references/identify-and-locate-contacts.md): Find the right contact reliably, prefer stable natural keys when possible, and avoid creating duplicates through weak lookup discipline.
+- [import-history-without-faking-evidence](references/import-history-without-faking-evidence.md): Import pre-existing relationship state honestly, using seeded links for known history instead of inventing fake journal evidence.
+- [model-structure-orgs-and-households](references/model-structure-orgs-and-households.md): Model factual structure such as employment, membership, hierarchy, and household ties without confusing it with live relational mechanics.
+- [record-direct-evidence-well](references/record-direct-evidence-well.md): Record direct owner-facing social evidence in a way that produces truthful mechanics, good moments, and useful future review surfaces.
+- [record-observations-and-referrals](references/record-observations-and-referrals.md): Capture third-party and referral truth without overclaiming intimacy, directness, or trust that the operator did not actually earn.
+- [capture-transactions-and-commercial-events](references/capture-transactions-and-commercial-events.md): Capture commercially meaningful interactions as transactions so operational and service relationships accumulate the right evidence shape.
+- [manage-promises-and-agreements](references/manage-promises-and-agreements.md): Track obligations explicitly from creation to resolution so open commitments remain actionable and trust consequences stay honest.
+- [manage-recurring-dates-and-reminders](references/manage-recurring-dates-and-reminders.md): Use date anchors for recurring salience so important birthdays, anniversaries, renewals, and memorials feed review surfaces cleanly.
+- [review-radar-progression-and-graph](references/review-radar-progression-and-graph.md): Use the review surfaces to prioritize maintenance, understand progression readiness, and read the shape of the relationship graph without guessing from raw rows.
+- [reconcile-duplicates-and-merge-safely](references/reconcile-duplicates-and-merge-safely.md): Review duplicate candidates carefully and merge only after the identity, history, and structural consequences are understood.
+
+## Principles
+
+- Honor evidence before narrative.
+- Clarify before you act.
+- Keep truths in their proper layer.
+- Read derived signals with judgment.
+- Protect relationship integrity over time.
+- Follow the operational protocol.

package/skills/affinity/references/bootstrap-and-cold-start.md

@@ -0,0 +1,50 @@
+# Bootstrap And Cold Start
+
+Primary tools:
+- `manage_contact`
+- `manage_identity`
+- `inspect_affinity_item`
+- `review_affinity`
+
+Goal:
+- Establish one clean owner record, make it reachable, and verify the system is ready for later relationship work.
+
+When to use:
+- The database is new or logically empty.
+- A harness needs to initialize its own operator profile before doing anything else.
+
+When not to use:
+- The owner already exists and you only need to update profile fields.
+- You are importing historical relationships; use the import-focused skill after bootstrap.
+
+Step-by-step sequence:
+1. Assume the schema is already initialized and the database is live before using any tool.
+2. Use `manage_contact` with `action: "create"` and `bootstrapOwner: true` exactly once for the operator.
+3. Immediately attach at least one routing identity with `manage_identity` so future lookups can use a stable natural key.
+4. Use `inspect_affinity_item` with `kind: "owner_profile"` to confirm that the owner profile exists and reads back cleanly.
+5. 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.
+
+Validation checks:
+- The owner profile loads successfully.
+- The owner has at least one live identity.
+- The contact list shows exactly the records you expect at this early stage.
+
+Pitfalls:
+- Do not create a non-owner placeholder and plan to convert it later if the harness can bootstrap the real owner immediately.
+- Do not skip identity attachment, or later natural-key lookup will be weaker and duplicate-prone.
+- Do not seed relationships before the owner exists if later evidence is meant to be owner-facing.
+
+Tips and tricks:
+- Prefer an identity that is stable across sessions, such as a primary email or canonical profile URL.
+- Keep the first dataset tiny. Bootstrap is for a trustworthy base, not a full import.
+- If setup feels ambiguous, inspect first and add less rather than more.
+
+Tool calls to prefer:
+- `manage_contact` for owner creation
+- `manage_identity` for first routing key
+- `inspect_affinity_item` for confirmation
+- `review_affinity` for early portfolio sanity checks
+
+Related skills:
+- `identify-and-locate-contacts`
+- `import-history-without-faking-evidence`

package/skills/affinity/references/capture-transactions-and-commercial-events.md

@@ -0,0 +1,48 @@
+# Capture Transactions And Commercial Events
+
+Primary tools:
+- `record_event`
+- `inspect_affinity_item`
+- `review_affinity`
+
+Goal:
+- Represent deals, placements, closings, sponsorships, and operationally meaningful exchanges as transactions instead of flattening them into generic social notes.
+
+When to use:
+- Money, deliverables, placements, closings, or other commercially meaningful exchanges just occurred.
+- The relationship is service-oriented, professional, or business-critical.
+
+When not to use:
+- The main truth is a personal conversation or ordinary activity.
+- The important action is really a promise or agreement that still needs later resolution.
+
+Step-by-step sequence:
+1. Confirm the right counterparties first.
+2. Use `record_event` with `kind: "transaction"` for the commercial event itself.
+3. Keep the summary concrete enough that future review explains what was exchanged and why it mattered.
+4. Use significance according to the real business weight, not just enthusiasm.
+5. Review the affected relationship if the commercial event should meaningfully change trust, cadence, or graph visibility.
+
+Validation checks:
+- The transaction now appears in the relevant timeline or journal views.
+- The resulting relationship effect matches the commercial importance of the event.
+- Later maintenance views now have the right recency signal.
+
+Pitfalls:
+- Do not bury closings, placements, or sponsorship deliveries inside generic conversations.
+- Do not record a transaction when the truth is still only a pending agreement.
+- Do not expect transactions to create the same kind of affinity movement as rich direct social evidence.
+
+Tips and tricks:
+- A relationship can be commercially strong and emotionally shallow. That is normal.
+- Use transactions to preserve crisp operational history for later portfolio review.
+- Follow major transactions with review views to confirm the graph and maintenance surfaces updated as expected.
+
+Tool calls to prefer:
+- `record_event` with `transaction`
+- `inspect_affinity_item` for exact relationship read-back
+- `review_affinity` for owner-link portfolio review
+
+Related skills:
+- `manage-promises-and-agreements`
+- `review-radar-progression-and-graph`

package/skills/affinity/references/identify-and-locate-contacts.md

@@ -0,0 +1,51 @@
+# Identify And Locate Contacts
+
+Primary tools:
+- `search_affinity`
+- `inspect_affinity_item`
+- `manage_identity`
+- `manage_contact`
+
+Goal:
+- Resolve the right contact before mutating anything, using the strongest available locator.
+
+When to use:
+- A harness receives a name, email, phone number, URL, or ambiguous reference to a person or organization.
+- You need to confirm whether a contact already exists before creating a new one.
+
+When not to use:
+- You already have one exact internal id from a prior successful tool result.
+- You are reviewing a list surface rather than identifying one exact target.
+
+Step-by-step sequence:
+1. Start with `search_affinity` whenever the target might already exist.
+2. 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.
+3. If search returns one strong candidate, use `inspect_affinity_item` to confirm the profile before mutating.
+4. If the target does not exist, create it with `manage_contact`.
+5. Immediately add the best routing key with `manage_identity` so future lookup becomes exact rather than fuzzy.
+6. If the system returns ambiguity, stop and clarify instead of guessing.
+
+Validation checks:
+- The inspected profile matches the intended person or organization.
+- The best known routing identity is attached and, when appropriate, verified.
+- Later searches by that identity return the same contact cleanly.
+
+Pitfalls:
+- Do not trust names alone when a natural key is available.
+- Do not create a second contact just because search returned multiple plausible matches.
+- Do not remove or revise identities casually; they are your best future locator surface.
+
+Tips and tricks:
+- Prefer exact identities over integer ids when the harness needs to survive across sessions or partial memory loss.
+- After creating a contact from a vague mention, upgrade it with a real identity as soon as possible.
+- If multiple weak matches appear, inspect before mutating.
+
+Tool calls to prefer:
+- `search_affinity` for candidate discovery
+- `inspect_affinity_item` for exact confirmation
+- `manage_identity` for routing-key upgrades
+- `manage_contact` only after lookup fails honestly
+
+Related skills:
+- `bootstrap-and-cold-start`
+- `reconcile-duplicates-and-merge-safely`

package/skills/affinity/references/import-history-without-faking-evidence.md

@@ -0,0 +1,50 @@
+# Import History Without Faking Evidence
+
+Primary tools:
+- `manage_contact`
+- `manage_identity`
+- `manage_relationship`
+- `inspect_affinity_item`
+
+Goal:
+- Represent real pre-system relationship state without fabricating a timeline of events that never existed inside Affinity.
+
+When to use:
+- You are migrating from another CRM, notes system, or memory set.
+- You already know a relationship exists and roughly how strong or active it is, but you do not want to reconstruct every past interaction.
+
+When not to use:
+- A new event just happened and should affect mechanics now.
+- You are recording a specific conversation, milestone, transaction, or observation.
+
+Step-by-step sequence:
+1. Create or locate the relevant contacts first.
+2. Add the strongest identities you know so the imported graph stays addressable later.
+3. Use `manage_relationship` with `action: "seed_social_link"` to establish a relational link that already existed before the system.
+4. Set only the fields you can justify: kind, rough rank, trust, cadence, state, and optional bond.
+5. Inspect the result with `inspect_affinity_item` if you need to verify the exact post-import state.
+6. From that point forward, switch to evidence tools for all new real-world activity.
+
+Validation checks:
+- The imported contact pair now has the expected relational link.
+- The seeded state looks plausible when inspected.
+- Later direct events continue progression from the seeded baseline rather than from zero.
+
+Pitfalls:
+- Do not backfill dozens of fake conversations just to reach a desired rank.
+- Do not use import seeding for ordinary day-to-day relationship maintenance.
+- Do not overstate confidence on rank or trust when the historical truth is actually vague.
+
+Tips and tricks:
+- Seed conservatively if you are unsure. It is safer to underclaim and let real future evidence move the link.
+- Use bond text sparingly as a narrative reminder of why the imported state is what it is.
+- Prefer one honest seed over many synthetic event reconstructions.
+
+Tool calls to prefer:
+- `manage_relationship` with `seed_social_link`
+- `manage_contact` and `manage_identity` before seeding
+- `inspect_affinity_item` for post-import verification
+
+Related skills:
+- `bootstrap-and-cold-start`
+- `record-direct-evidence-well`

package/skills/affinity/references/manage-promises-and-agreements.md

@@ -0,0 +1,49 @@
+# Manage Promises And Agreements
+
+Primary tools:
+- `manage_commitment`
+- `review_affinity`
+- `inspect_affinity_item`
+
+Goal:
+- Keep promises and agreements visible, resolvable, and mechanically meaningful instead of letting them disappear into narrative history.
+
+When to use:
+- Someone committed to doing something later.
+- A promise, agreement, or operational obligation needs follow-through.
+
+When not to use:
+- The event is complete already and no unresolved obligation exists.
+- A date is recurring and belongs in the date-anchor surface instead.
+
+Step-by-step sequence:
+1. When the commitment is made, use `manage_commitment` with `action: "record"`.
+2. Choose `promise` vs `agreement` honestly rather than treating them as stylistic synonyms.
+3. Include a due time when the obligation has a meaningful time boundary.
+4. Use `review_affinity` with the open-commitment view during regular review cycles.
+5. When the outcome is known, resolve it with `manage_commitment` as `kept`, `cancelled`, or `broken`.
+6. Inspect the relevant profile or review the relevant queue again if you need to confirm closure.
+
+Validation checks:
+- Open commitments appear when they should and disappear when resolved.
+- Resolution state matches real-world truth.
+- Trust effects feel consistent with whether the promise was kept or broken.
+
+Pitfalls:
+- Do not hide real obligations inside ordinary event summaries.
+- Do not resolve a commitment optimistically before the outcome is actually known.
+- Do not misuse `cancelled` when the truth is actually `broken`.
+
+Tips and tricks:
+- If an obligation matters enough to disappoint someone when missed, record it.
+- Review open commitments regularly; the value of the system drops fast if this queue goes stale.
+- When a commitment resolution also deserves narrative context, pair the resolution with an appropriate event in the surrounding workflow.
+
+Tool calls to prefer:
+- `manage_commitment` for record and resolve
+- `review_affinity` for the open-commitment queue
+- `inspect_affinity_item` when you need exact context on the affected relationship
+
+Related skills:
+- `capture-transactions-and-commercial-events`
+- `manage-recurring-dates-and-reminders`