@rubytech/create-realagent 1.0.805 → 1.0.806

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.805",
+  "version": "1.0.806",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/plugins/docs/references/cloudflare.md

@@ -29,7 +29,7 @@ When you submit, the `/api/admin/cloudflare/setup` endpoint runs — in strict o
 - **Zone pre-flight** — for every non-apex hostname the script queries `1.1.1.1` for the registrable parent's NS records and refuses the whole run if they don't point at Cloudflare. Stream log: `step=zone-preflight result=ok|error zones_on_account=… missing_parent_for=…`. Catches "domain not on Cloudflare"; does not catch "domain on a different Cloudflare account than `cert.pem` is bound to" — that case surfaces later via `tunnel-status`.
 - `cloudflared tunnel route dns` for each subdomain hostname. Apex hostnames cannot be routed this way — the script prints an **ACTION REQUIRED** block naming the exact dashboard record to add or edit. Stream log emits `step=route-dns hostname=… tunnel_id=…` before the call and `step=route-dns hostname=… result=ok|apex-skip|error` after; on error the bounded cloudflared stderr (≤400 chars) rides in the same phase line. **The script does not parse cloudflared's stdout** — exit code is the sole decision signal, so all three legitimate cloudflared output shapes (new record, overwrite, idempotent "already configured") are treated as success.
 - `config.yml` and `tunnel.state` written under `${CFG_DIR}`.
-- **Step-7 onboarding completion persisted** — the script writes `${ACCOUNT_DIR}/onboarding/step7-complete` (a JSON marker with the completion timestamp and tunnel ID) before arming the restart. Stream log: `step=onboarding-persist result=ok|error reason=<r>`. The marker is consumed by the next admin session's first state read and advances `OnboardingState.currentStep` to 7. Without this, the service restart below would SIGTERM the admin agent before it could persist step-7 completion, and the next session would re-ask the Cloudflare question you just finished.
+- **Step-7 onboarding completion persisted** — the script writes `${ACCOUNT_DIR}/onboarding/step7-complete` (a JSON marker with the completion timestamp and tunnel ID) before arming the restart. Stream log: `step=onboarding-persist result=ok|error reason=<r>`. The marker is consumed by the next admin session's first state read and advances `OnboardingState.currentStep` to 7. Without this, the service restart below would SIGTERM the admin agent before it could persist step-7 completion, and the next session would re-ask the Cloudflare question you just finished. Both invocation surfaces (the form-driven action and the agent-via-Bash path) declare `ACCOUNT_DIR` explicitly because `systemd-run --user` does not inherit parent env — when ACCOUNT_DIR isn't reaching the script you'll see `result=skipped reason=no-account-dir` in the stream log instead of `result=ok`.
 - `systemctl --user restart ${BRAND}.service` — restarts the platform service so the new tunnel spawns via the service's `ExecStartPre=resume-tunnel.sh`.
 - Post-restart verification — `ps -ef | grep '[c]loudflared'` confirms the connector is alive, then `curl -I https://<hostname>` against each subdomain (up to 60 s per host) confirms a non-530 response.
 

package/payload/platform/plugins/docs/references/internals.md

@@ -464,3 +464,11 @@ grep '[persist] tool-call persisted' server.log | tail -10
 ```
 
 Each log entry includes the tool name and a truncated conversation ID for correlation.
+
+## Context compaction
+
+When an admin turn crosses 75% of the model's context window, {{productName}} runs a silent compaction turn that asks the agent to call the `session-compact` MCP tool with a structured briefing (what you asked for, what was done, decisions made, work-in-progress, things you've shared about yourself). The briefing is written to Neo4j; the next admin turn injects it back into the system prompt, so continuity survives across the compaction boundary without re-sending the full transcript.
+
+The compaction runs against a transient one-shot pool entry separate from the long-lived admin Query (Task 784). Operator-visible side effects:
+- Compaction logs land in `claude-agent-compaction-stream-YYYY-MM-DD.log` alongside the main stream log. Look for `[compaction-start]`, `[compaction-summary-captured]`, `[compaction-failed]`, `[compaction-timeout]`, `[compaction-crashed]`, or `[compaction-spawn-error]` to triage. Subprocess stderr is captured inline as `[subproc-stderr] <line>` — there is no longer a separate `claude-agent-compaction-stderr-…log` file.
+- The one-shot pool entry's lifecycle is greppable as `[client-cold-create] reason=compaction-one-shot …` paired with `[client-evict] reason=compaction-one-shot …`, distinguishable from the regular admin pool's lifecycle tags.

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -40,7 +40,7 @@ These are enabled during onboarding and can be added or removed at any time. Som
 | `waitlist` | Waitlist lifecycle — extract sign-ups from conversations, review | — |
 | `replicate` | Image generation — three models for photorealistic, design, and fast draft images | Content producer, Research assistant |
 | `linkedin-import` | Import a LinkedIn Basic Data Export — Profile and Connections today, more CSVs as references land | Database operator |
-| `whatsapp-import` | Import a WhatsApp `_chat.txt` export as a Conversation + chronologically-chained Messages plus `:Observation` nodes for typed insights (mentions, tasks, preferences, observed relationships). Single Bash entry — `bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive> --owner-element-id <id> --scope <admin\|public>` runs parse → archive-write → Haiku insight in one process. Distinct from the live `whatsapp` plugin which is a Baileys QR-pairing channel. | Database operator |
+| `whatsapp-import` | Import a WhatsApp `_chat.txt` export. Two-phase contract: **Phase 1 (load)** is a single Bash entry — `bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive> --owner-element-id <id> --scope <admin\|public>` runs parse → archive-write → Haiku insight in one process, landing `:Conversation:WhatsAppConversation` + `:Message:WhatsAppMessage` with NEXT chain, auto-created `:Person {participantStatus:'auto-created'}` participants, and `:Observation {observationStatus:'auto-extracted'}` rows for mentions/tasks/preferences/observed-relationships. **Phase 2 (enrich)** is operator-driven: ask "enrich the X chat" / "wire observations from yesterday's import" and the database-operator runs the `whatsapp-import-enrich` skill — walks the auto-created participants and auto-extracted observations row-by-row, writes operator-confirmed wiring (participant promotion/merge via `apoc.refactor.mergeNodes`, `:MENTIONS`/`:RELATED_TO` edges with evidence, `:Task` and `:Preference` nodes). Idempotent — re-running enrichment surfaces only items still in the auto-* states. Distinct from the live `whatsapp` plugin which is a Baileys QR-pairing channel. | Database operator |
 
 ### Claude Official (marketplace)
 

package/payload/platform/plugins/whatsapp-import/PLUGIN.md

@@ -1,6 +1,6 @@
 ---
 name: whatsapp-import
-description: "Import a WhatsApp `_chat.txt` export (Conversation + Messages with chronological NEXT chain + analysis-derived insights) into the {{productName}} Neo4j graph. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default. Distinct from the live `whatsapp` plugin (Baileys QR pairing + in-memory store)."
+description: "Import a WhatsApp `_chat.txt` export (Conversation + Messages with chronological NEXT chain + analysis-derived insights) into the {{productName}} Neo4j graph as a two-phase contract: Phase 1 (`whatsapp-import` skill) lands raw shape via a deterministic Bash entry; Phase 2 (`whatsapp-import-enrich` skill) is operator-driven semantic resolution over the loaded conversation. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default. Distinct from the live `whatsapp` plugin (Baileys QR pairing + in-memory store)."
 tools: []
 always: false
 embed: false
@@ -12,9 +12,20 @@ metadata: {"platform":{"optional":true,"pluginKey":"whatsapp-import"}}
 
 Ingests a WhatsApp "Export Chat" archive (the `_chat.txt` file plus media attachments) into the {{productName}} Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
 
+## Two-phase contract (Task 855 + Task 859)
+
+The plugin ships two skills that pair as a contract: deterministic load first, then operator-driven semantic enrichment. Splitting them removes the orchestration loop a single bundled phase imposed (Task 804's 7h orchestration), and lets re-imports reuse the load phase without redoing the semantic walk.
+
+| Phase | Skill | What it does | Trigger phrase |
+|-------|-------|--------------|----------------|
+| 1 — load | [`whatsapp-import`](skills/whatsapp-import/SKILL.md) | Parses `_chat.txt`, writes `:Conversation:WhatsAppConversation` + `:Message:WhatsAppMessage` with NEXT chain, auto-creates one `:Person {participantStatus:'auto-created'}` per distinct senderName, lands `:Observation {observationStatus:'auto-extracted'}` rows from the chunked Haiku insight pass. Single Bash entry; no MCP envelope between steps. | Operator drops a `_chat.txt` file or its containing export folder into chat. |
+| 2 — enrich | [`whatsapp-import-enrich`](skills/whatsapp-import-enrich/SKILL.md) | Walks `participantStatus='auto-created'` and `observationStatus='auto-extracted'` rows scoped to a chosen conversation, surfaces evidence per row, writes operator-confirmed wiring: `apoc.refactor.mergeNodes` for participant promotion/merge, `:MENTIONS`/`:RELATED_TO` edges with `evidenceSnippet`, `:Task` via `task-create`, `:Preference` via `memory-write`. Idempotent — re-running surfaces only items still in `auto-created`/`auto-extracted`. | Operator asks to "enrich the X chat", "promote auto-created participants from Y", "wire observations from yesterday's import". |
+
+Phase 2 refuses to run against a Conversation whose `c.lastImportedAt` is null. Phase 1 always precedes Phase 2.
+
 ## When this applies
 
-The admin agent delegates to `database-operator` when the operator drops a `_chat.txt` (or its containing folder) into chat. The specialist runs the skill's archive-owner confirmation flow before any line is written, then invokes the deterministic Bash entry (`bin/whatsapp-ingest.sh`) once: parse, archive-write (via `memoryArchiveWrite` in-process), and Haiku insight all run in one Node process — no MCP envelope between steps (Task 855).
+The admin agent delegates to `database-operator` when the operator drops a `_chat.txt` (or its containing folder) into chat (→ Phase 1) or names enrichment of an already-loaded conversation (→ Phase 2). For Phase 1 the specialist runs the skill's archive-owner confirmation flow before any line is written, then invokes the deterministic Bash entry (`bin/whatsapp-ingest.sh`) once: parse, archive-write (via `memoryArchiveWrite` in-process), and Haiku insight all run in one Node process — no MCP envelope between steps (Task 855). For Phase 2 the specialist runs `whatsapp-import-enrich`'s bulk preview, asks the operator to confirm scope, then walks the rows with operator confirmation gates (Task 859).
 
 ## Accepted export shapes
 
@@ -28,6 +39,8 @@ WhatsApp's "Export Chat" emits `[DD/MM/YYYY, HH:MM:SS]` prefixes by default in m
 
 ## Relationship to other plugins
 
-- **memory** — the underlying write surface imported in-process by `bin/ingest.mjs` (`memoryArchiveWrite` for bulk Conversation+Messages; direct Cypher `:Observation` writes for the insight pass). All writes carry `source='whatsapp'` + `createdByAgent='whatsapp-import'` provenance. The legacy `mcp__memory__whatsapp-export-parse` / `whatsapp-export-insight-write` MCP tools and the direct `memory-archive-write` MCP path with `archiveType=whatsapp-export` are blocked at the harness — the Bash entry is the only supported invocation surface (Task 855).
-- **database-operator specialist** — owns execution. See [admin/IDENTITY.md](../../../platform/templates/agents/admin/IDENTITY.md) delegation clause and [database-operator.md](../../../platform/templates/specialists/agents/database-operator.md) per-source archive list.
-- **linkedin-import** — sister plugin under the same pattern (LinkedIn Basic Data Export). Reading [linkedin-import/PLUGIN.md](../linkedin-import/PLUGIN.md) is the fastest way to understand the shape this plugin follows.
+- **memory** — Phase 1's underlying write surface, imported in-process by `bin/ingest.mjs` (`memoryArchiveWrite` for bulk Conversation+Messages; direct Cypher `:Observation` writes for the insight pass). Phase 2's enrich skill writes `:Preference` nodes via `mcp__memory__memory-write` and uses `mcp__memory__memory-search` for entity disambiguation. All writes carry `source='whatsapp'` + `createdByAgent='whatsapp-import'` (Phase 1) or `createdByAgent='whatsapp-import-enrich'` (Phase 2) provenance. The legacy `mcp__memory__whatsapp-export-parse` / `whatsapp-export-insight-write` MCP tools and the direct `memory-archive-write` MCP path with `archiveType=whatsapp-export` are blocked at the harness — the Bash entry is the only supported invocation surface for Phase 1 (Task 855).
+- **tasks** — Phase 2's `:Task` writes go through `mcp__tasks__task-create` with `affects=$conversationElementId`. Database-operator's frontmatter `tools:` includes `mcp__tasks__task-create` for this path.
+- **contacts** — Phase 2's mint-new-Person path (an auto-created participant the operator wants to land as a fresh contact) goes through `mcp__contacts__contact-create`.
+- **database-operator specialist** — owns execution for both phases. See [admin/IDENTITY.md](../../../platform/templates/agents/admin/IDENTITY.md) delegation clause and [database-operator.md](../../../platform/templates/specialists/agents/database-operator.md) per-source archive list (which now names both phases under the WhatsApp entry).
+- **linkedin-import** — sister plugin under the same pattern (LinkedIn Basic Data Export). LinkedIn ingestion is single-phase today (no enrich pass) because CSV rows already encode entity types deterministically — no auto-created participants, no auto-extracted observations to walk. Reading [linkedin-import/PLUGIN.md](../linkedin-import/PLUGIN.md) is the fastest way to understand the load-phase shape this plugin's Phase 1 follows.

package/payload/platform/plugins/whatsapp-import/skills/whatsapp-import-enrich/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: whatsapp-import-enrich
+description: Operator-driven semantic enrichment pass over an already-loaded WhatsApp Conversation. Walks `:Person {participantStatus:'auto-created'}` and `:Observation {observationStatus:'auto-extracted'}` rows scoped to the chosen conversation, surfaces evidence per row, and writes operator-confirmed wiring (participant promotion/merge, `:MENTIONS` / `:RELATED_TO` edges, `:Task` and `:Preference` nodes). Triggers on operator phrases like "enrich the X chat", "promote the auto-created participants from Y", "wire the observations from yesterday's import". Runs against a Conversation already imported by `whatsapp-import` (Task 855); never re-runs parse.
+---
+
+# WhatsApp Import — Enrich
+
+Phase 2 of the two-phase WhatsApp ingest contract. Phase 1 (`whatsapp-import`) is the deterministic Bash entry that lands raw shape: Conversation + Messages + chronological NEXT chain + auto-created `:Person` participants + raw `:Observation` nodes. Phase 2 (this skill) is operator-driven semantic resolution: disambiguates participants against the live graph, wires observations to typed entities, and reattributes the operator's own messages from the auto-Person to their `:AdminUser`.
+
+## When this applies
+
+The operator triggers this skill against a single, already-loaded `:Conversation:WhatsAppConversation`. Acceptable phrases include any reference to enriching, promoting participants from, or wiring observations against a conversation the operator can name (display name, recent timestamp, conversationId). When the conversation reference is ambiguous, list the recent WhatsApp conversations and require operator selection before any walk begins. Never run against a conversation whose `whatsapp-import` Phase 1 has not completed (`MATCH (c:WhatsAppConversation {conversationId:$cid}) WHERE c.lastImportedAt IS NULL` is a blocker — surface "Phase 1 has not completed for <cid>; run whatsapp-import first" and yield).
+
+## Bulk preview (mandatory, before any walk)
+
+Before walking a single row, count the work and offer a yield. Two read-only Cyphers via `mcp__graph__maxy-graph-read_neo4j_cypher`:
+
+```cypher
+MATCH (p:Person {accountId:$acct, source:'whatsapp', participantStatus:'auto-created'})
+      -[:PARTICIPANT_IN]->(:Conversation {conversationId:$cid})
+RETURN count(p) AS autoParticipants
+```
+
+```cypher
+MATCH (o:Observation {accountId:$acct, observationStatus:'auto-extracted', insightPass:true})
+      -[:OBSERVED_IN]->(:Conversation {conversationId:$cid})
+RETURN count(o) AS autoObservations,
+       sum(CASE o.kind WHEN 'mention' THEN 1 ELSE 0 END)               AS mentions,
+       sum(CASE o.kind WHEN 'task' THEN 1 ELSE 0 END)                  AS tasks,
+       sum(CASE o.kind WHEN 'preference' THEN 1 ELSE 0 END)            AS preferences,
+       sum(CASE o.kind WHEN 'observed-relationship' THEN 1 ELSE 0 END) AS relationships
+```
+
+Surface one chat message: `"<N> auto-participants and <M> auto-observations to review (<a> mentions, <b> tasks, <c> preferences, <d> relationships). Proceed?"`. Yield on no. On yes, persist `$preParticipantCount` and per-kind `$preObservationCount` for post-walk verification (Cypher silent-no-op detection — see "Status-update verification").
+
+Emit one chat line: `[whatsapp-import-enrich] start conversationId=<cid> auto-participants=<N> auto-observations=<M>`.
+
+## Walk 1 — Auto-created participants
+
+For each `:Person {participantStatus:'auto-created'}` `PARTICIPANT_IN` the conversation, surface evidence and ask the operator to choose an action.
+
+Per-row evidence Cypher:
+
+```cypher
+MATCH (p:Person)-[:PARTICIPANT_IN]->(c:Conversation {conversationId:$cid})
+WHERE p.participantStatus = 'auto-created' AND p.accountId = $acct AND p.source = 'whatsapp'
+WITH p, c
+OPTIONAL MATCH (p)-[:SENT]->(m:Message {conversationId:$cid})
+WITH p, count(m) AS messageCount,
+     min(m.dateSent) AS firstSeenAt, max(m.dateSent) AS lastSeenAt,
+     [m IN collect(m)[..3] | substring(m.body, 0, 80)] AS bodySamples
+RETURN elementId(p) AS elemId, p.name AS displayName,
+       messageCount, firstSeenAt, lastSeenAt, bodySamples
+```
+
+Operator choices per row:
+
+| Action | Effect |
+|--------|--------|
+| **promote-to-existing** | Operator names an existing `:Person` or `:AdminUser` (resolved via `mcp__memory__memory-search` against `displayName`). Skill writes the merge below. |
+| **mint-new-Person** | Operator names a new contact identity. Skill calls `mcp__contacts__contact-create` with `givenName` / `familyName` / at least one of `email` / `telephone`, then merges the auto-Person into the new contact's `:Person` node. |
+| **merge-same-person** | Two auto-Persons that are the same person under different display names (e.g. phone-then-name). Operator names the survivor; skill merges the other into it. |
+| **skip** | Leave `participantStatus='auto-created'`. Re-running the skill surfaces it again. |
+
+### Merge Cypher (load-bearing — read carefully)
+
+Every promote-to-existing, mint-new, and merge-same-person uses `apoc.refactor.mergeNodes` with **non-default** property-merge mode:
+
+```cypher
+MATCH (survivor) WHERE elementId(survivor) = $survivorId
+MATCH (duplicate:Person) WHERE elementId(duplicate) = $autoPersonId
+CALL apoc.refactor.mergeNodes([survivor, duplicate], {properties:'discard', mergeRels:true})
+YIELD node
+SET node.participantStatus = 'operator-confirmed',
+    node.mergedFromAutoPerson = $autoPersonId,
+    node.mergedAt = datetime(),
+    node.mergedFromAgent = 'whatsapp-import-enrich',
+    node.mergedFromSession = $sessionId
+RETURN elementId(node) AS survivorId, count(node) AS affected
+```
+
+`{properties:'discard'}` keeps the survivor's value when both nodes have the same property — the survivor (first array element) wins on conflict. The duplicate's properties that the survivor does NOT have are still copied onto the survivor; this is desirable here (auto-Person's `firstSeenAt`/`lastSeenAt` enrich the `:AdminUser` if absent). **Do not switch to `'overwrite'`** — that mode hands the conflict to the duplicate, silently replacing `:AdminUser.name` (e.g. "Joel Smalley") with the auto-Person's WhatsApp display name (e.g. "Joel S."), which is identity corruption with no error. `'combine'` would coerce conflicting scalars into arrays (`name=["Joel Smalley","Joel S."]`), which breaks downstream callers that expect string scalars. **`discard` is the only safe mode here.**
+
+`mergeRels:true` reparents every `:SENT` / `:PARTICIPANT_IN` / `:MENTIONS` edge from the duplicate onto the survivor in the same transaction.
+
+### Owner reconciliation — first row of Walk 1
+
+Phase 1 takes `--owner-element-id` as argv but does not stamp it on the Conversation node — the owner pointer is implicit (the `:SENT` edges from `:AdminUser` → `:Message` are the only structural link). The skill therefore re-asks the operator who owns this conversation, the same way Phase 1's anchor-confirmation flow does. List candidate `:AdminUser` rows:
+
+```cypher
+MATCH (u:AdminUser)
+OPTIONAL MATCH (u)-[:SENT]->(m:Message {conversationId:$cid})
+WITH u, count(m) AS senderMessageCount
+RETURN elementId(u) AS elementId, u.name AS name, u.userId AS userId,
+       senderMessageCount
+ORDER BY senderMessageCount DESC, name
+```
+
+Surface: `"Who exported this conversation? Pick from: <:AdminUser rows with senderMessageCount>"`. The `senderMessageCount` is a hint — an :AdminUser already SENT-edged to messages in this conversation is the most likely owner — but the operator confirms verbatim. Echo the chosen owner back (`:AdminUser <name> (<elementId>) — confirm yes/no`) before any write.
+
+On confirm, find auto-Persons whose display name might match the owner. Surface ALL candidates — string equality alone is not safe (owner display names drift across re-exports):
+
+```cypher
+MATCH (auto:Person {participantStatus:'auto-created', accountId:$acct, source:'whatsapp'})
+      -[:PARTICIPANT_IN]->(:Conversation {conversationId:$cid})
+RETURN elementId(auto) AS elemId, auto.name AS displayName,
+       size([(auto)-[:SENT]->(:Message) | 1]) AS sentMessageCount
+ORDER BY sentMessageCount DESC
+```
+
+Operator picks zero or more auto-Persons to merge into the owner. For each picked auto-Person, run the merge Cypher above with `survivorId = ownerElementId` and `autoPersonId = picked-auto-elemId`. `mergeRels:true` reparents SENT and PARTICIPANT_IN onto the `:AdminUser`; the auto-Person is consumed.
+
+### After each row — emit one log line
+
+`[whatsapp-import-enrich] participant action=<promoted-existing|minted-new|merged-with-id|reattributed-to-owner|skipped> name=<displayName> elementId=<survivorId-or-autoId>`.
+
+## Walk 2 — Auto-extracted observations
+
+For each `:Observation {observationStatus:'auto-extracted', insightPass:true}` `OBSERVED_IN` the conversation, dispatch by `kind`. Field mapping is non-obvious (see ingest.mjs:459-505) — get this exactly right:
+
+| kind | entity name | evidence | from | to |
+|------|-------------|----------|------|-----|
+| `mention` | `o.summary` | `o.snippet` (≤80 chars verbatim) | — | — |
+| `task` | task body in `o.summary` | `o.snippet` | — | — |
+| `preference` | `o.summary` (preference statement) | — | — | — |
+|  | `o.subject` (whose preference) | | | |
+| `observed-relationship` | `o.summary` (verb) | — | `o.from` | `o.to` |
+
+`o.summary` is the load-bearing field for mention disambiguation — `o.subject` is `null` on mentions (verified ingest.mjs:462).
+
+### kind = 'mention'
+
+Run `mcp__memory__memory-search` against `o.summary` (the mention text — e.g. "Sarah", "Sarah Chen at Acme"). Three branches:
+
+1. **Single high-confidence match AND `o.summary` contains whitespace OR matches a unique disambiguator (email, phone, role context).** Wire the edge and mark wired.
+2. **Single match BUT `o.summary` is single-token (e.g. "Sarah") with no disambiguator.** Surface: `"Mention: 'Sarah' — found one :Person <fullName> (<elemId>). Confirm wire to this person?"` (mirrors the Gate 2 pattern in [whatsapp-export-insight-write.ts](../../../memory/mcp/src/tools/whatsapp-export-insight-write.ts) — operator IS the disambiguator). On yes wire; on no mark `observationStatus='rejected'`.
+3. **Multiple matches OR zero matches.** Surface candidates (or the absence) and let the operator pick or reject.
+
+### Wire Cypher — `:MENTIONS` edge with messageId recovery
+
+The load phase does NOT stamp `messageId` on `:Observation` (Task 855's chunked Haiku has no per-message provenance). To respect the `(:Message)-[:MENTIONS]->(:Person)` semantics, recover `messageId` from `snippet`:
+
+```cypher
+MATCH (m:Message {conversationId:$cid})
+WHERE m.body CONTAINS $snippet
+RETURN m.messageId AS messageId, m.dateSent AS sentAt
+ORDER BY m.dateSent ASC
+LIMIT 1
+```
+
+Three outcomes:
+
+- **Unique or first-by-chronology match** → write `(:Message)-[:MENTIONS]->(:Person|:AdminUser)`:
+
+  ```cypher
+  MATCH (m:Message {conversationId:$cid, messageId:$messageId})
+  MATCH (target) WHERE elementId(target) = $targetElementId AND (target:Person OR target:AdminUser)
+  MERGE (m)-[r:MENTIONS]->(target)
+  ON CREATE SET r.source='whatsapp', r.evidenceSnippet=$snippet,
+                r.createdByAgent='whatsapp-import-enrich', r.createdAt=datetime(),
+                r.createdBySession=$sessionId
+  WITH r
+  MATCH (o:Observation) WHERE elementId(o) = $observationElementId
+  SET o.observationStatus = 'wired', o.wiredEdgeKind = 'MENTIONS-from-Message',
+      o.wiredAt = datetime(), o.wiredBySession = $sessionId
+  RETURN elementId(r) AS edgeId, count(o) AS affected
+  ```
+
+- **Zero match** (snippet was paraphrased / normalised by Haiku) → fall back to `:Conversation`-anchored mention:
+
+  ```cypher
+  MATCH (c:Conversation {conversationId:$cid})
+  MATCH (target) WHERE elementId(target) = $targetElementId AND (target:Person OR target:AdminUser)
+  MERGE (c)-[r:MENTIONS]->(target)
+  ON CREATE SET r.source='whatsapp', r.evidenceSnippet=$snippet,
+                r.createdByAgent='whatsapp-import-enrich', r.createdAt=datetime(),
+                r.createdBySession=$sessionId
+  WITH r
+  MATCH (o:Observation) WHERE elementId(o) = $observationElementId
+  SET o.observationStatus = 'wired', o.wiredEdgeKind = 'MENTIONS-from-Conversation-fallback',
+      o.wiredAt = datetime(), o.wiredBySession = $sessionId
+  RETURN elementId(r) AS edgeId, count(o) AS affected
+  ```
+
+The `wiredEdgeKind` property is the audit anchor — operator can grep wired observations to see which path the skill took. Surface one chat line per wire: `[whatsapp-import-enrich] observation kind=mention action=wired-mention edge=<edgeKind> elementId=<observationElementId>`.
+
+### kind = 'task'
+
+Surface a one-line proposal: `"Task: '<o.summary>' — evidence: '<o.snippet>'. Mint as :Task affecting this conversation?"`. On yes, call `mcp__tasks__task-create` with the task text and `affects=$conversationElementId` (the conversation elementId is the required adjacency — `:Task` requires ≥1 typed edge at creation per project-manager.md:44). Then mark wired:
+
+```cypher
+MATCH (o:Observation) WHERE elementId(o) = $observationElementId
+SET o.observationStatus = 'wired', o.wiredEdgeKind = 'task-created',
+    o.wiredTaskElementId = $taskElementId,
+    o.wiredAt = datetime(), o.wiredBySession = $sessionId
+RETURN count(o) AS affected
+```
+
+On no, mark `observationStatus='rejected'`. Log line: `action=task-created` or `action=rejected`.
+
+### kind = 'preference'
+
+Write a `:Preference` node with `:OBSERVED_IN` edge to the conversation. The `mcp__memory__memory-write` tool is schema-aware and the wrapped writer enforces `≥1 typed edge`. Pass:
+
+```json
+{
+  "type": "Preference",
+  "properties": {
+    "subject": "<o.subject>",
+    "preference": "<o.summary>",
+    "source": "whatsapp",
+    "scope": "<conversation scope>"
+  },
+  "relationships": [
+    { "type": "OBSERVED_IN", "targetElementId": "<conversationElementId>" }
+  ]
+}
+```
+
+Then mark the observation wired (`wiredEdgeKind='preference-written', wiredPreferenceElementId=<id>`). Log line: `action=preference-written`.
+
+### kind = 'observed-relationship'
+
+Surface: `"Relationship: <o.from> --[<o.summary>]--> <o.to>. Confirm?"`. The endpoints (`o.from`, `o.to`) are participant display names from the chat — they may be auto-Persons (now possibly merged into existing `:Person` / `:AdminUser` after Walk 1). Resolve each endpoint via `mcp__memory__memory-search` against the display name AND scoped to participants of this conversation. Branches:
+
+1. **Both endpoints resolve uniquely.** Operator-confirms; write the edge:
+
+   ```cypher
+   MATCH (a) WHERE elementId(a) = $fromElementId
+   MATCH (b) WHERE elementId(b) = $toElementId
+   MERGE (a)-[r:RELATED_TO {relationship: $relationship}]->(b)
+   ON CREATE SET r.source='whatsapp', r.operatorConfirmed=true,
+                 r.evidenceMessageIds=$evidenceMessageIds,
+                 r.createdByAgent='whatsapp-import-enrich', r.createdAt=datetime(),
+                 r.createdBySession=$sessionId
+   WITH r
+   MATCH (o:Observation) WHERE elementId(o) = $observationElementId
+   SET o.observationStatus = 'wired', o.wiredEdgeKind='RELATED_TO',
+       o.wiredAt = datetime(), o.wiredBySession = $sessionId
+   RETURN elementId(r) AS edgeId, count(o) AS affected
+   ```
+
+   `evidenceMessageIds` is best-effort — recover via `MATCH (m:Message {conversationId:$cid}) WHERE m.body CONTAINS $relationship OR m.body CONTAINS $fromName OR m.body CONTAINS $toName RETURN collect(m.messageId)[..5]` (cap at 5).
+
+2. **Endpoint does not resolve.** Surface the candidate options or the missing-Person; operator decides whether to mint via `contact-create` first or reject the observation.
+
+3. **Operator answers no.** Mark `observationStatus='rejected'`. Log line: `action=rejected`.
+
+`operatorConfirmed=true` is mandatory for every `:RELATED_TO` write — the brief's anti-hallucination doctrine (mirrors [whatsapp-export-insight-write.ts](../../../memory/mcp/src/tools/whatsapp-export-insight-write.ts)). Never write `:RELATED_TO` without explicit operator yes.
+
+## Status-update verification (Cypher silent-no-op trap)
+
+`MATCH (n) WHERE elementId(n) = $id SET n.foo = $val` against a missing node returns zero rows and zero mutations, but the query SUCCEEDS — Neo4j Community read-committed isolation does not protect co-transactional writes. Every status-update Cypher in this skill ends `RETURN count(<bound-var>) AS affected`. The skill code path:
+
+- Captures pre-walk counts (`$preParticipantCount`, `$preObservationCount` per kind) from the bulk-preview Cyphers.
+- After each transition (`participantStatus='operator-confirmed'`, `observationStatus IN {'wired','rejected'}`) records `affected` from the result.
+- Post-walk re-runs the bulk-preview Cyphers. Asserts the new counts equal `pre - count(operations-that-claimed-affected=1)`. Mismatch is a hard blocker — surface `"Status-update silent-no-op detected: pre=<n> ops=<n> post=<n>; aborting before further writes"` and yield. Never claim done with a count mismatch.
+
+## Idempotency
+
+The walk filters on `participantStatus='auto-created'` and `observationStatus='auto-extracted'`. Re-running surfaces only items still in those states. Already-wired observations (`'wired'` / `'rejected'`) and operator-confirmed participants are skipped naturally — no skill-side bookkeeping needed.
+
+This means the skill is safe to re-run at any time. Operators can enrich incrementally (one ten-row session, then another) and re-imports of the same archive (which add only the message delta per Phase 1's idempotency contract) leave existing wired state untouched.
+
+## Done — emit one chat line
+
+After both walks complete, emit `[whatsapp-import-enrich] done conversationId=<cid> wired=<n> skipped=<n> rejected=<n> ms=<n>` and return a structured summary to the admin agent in the database-operator output contract shape (see [database-operator.md](../../../../templates/specialists/agents/database-operator.md#output-contract)):
+
+> WhatsApp enrichment complete for conversation `<displayName>` (`<cid>`):
+> Participants: `<promoted>` promoted to existing, `<minted>` minted new, `<merged>` cross-displayname merged, `<reattributed>` reattributed to operator, `<skipped>` left as auto-created.
+> Observations: `<wiredMentions>` mentions wired (`<msgEdge>` from :Message, `<convoEdge>` from :Conversation fallback), `<wiredTasks>` tasks created, `<wiredPrefs>` preferences written, `<wiredRels>` relationships confirmed, `<rejected>` rejected.
+> Status-update verification: pre=`<preCount>` ops=`<opCount>` post=`<postCount>` (mismatch=`<0|N>`).
+
+## Verification (post-write — for operator audit)
+
+Run via `mcp__graph__maxy-graph-read_neo4j_cypher`:
+
+- `MATCH (o:Observation {accountId:$acct, observationStatus:'auto-extracted'})-[:OBSERVED_IN]->(c:Conversation {conversationId:$cid}) RETURN count(o)` — should be 0 after a complete enrich.
+- `MATCH (p:Person {participantStatus:'auto-created', accountId:$acct, source:'whatsapp'})-[:PARTICIPANT_IN]->(c:Conversation {conversationId:$cid}) RETURN count(p)` — equals the count of skipped rows from the chat summary.
+- `MATCH ()-[r:MENTIONS {createdByAgent:'whatsapp-import-enrich'}]->() WHERE r.evidenceSnippet IS NOT NULL RETURN count(r)` — equals `wiredMentions` from the chat summary.
+- Re-run the skill against the same conversation immediately. Bulk preview should report `auto-participants=<skippedCount>` and `auto-observations=<rejectedAndUnwiredCount>` — never duplicate edges, never duplicate `:Task`/`:Preference`.
+
+## Observability — log lines
+
+Every line emitted to chat is mirrored into the per-conversation agent-stream log (greppable via `ssh neo@<host> "grep -nE '\[whatsapp-import-enrich\]' ~/<install>/data/accounts/<accountId>/logs/<conversationId>-claude-agent-stream.log"`):
+
+- `[whatsapp-import-enrich] start conversationId=<id> auto-participants=<n> auto-observations=<n>`
+- `[whatsapp-import-enrich] participant action=<promoted-existing|minted-new|merged-with-id|reattributed-to-owner|skipped> name=<name> elementId=<id>`
+- `[whatsapp-import-enrich] observation kind=<mention|task|preference|observed-relationship> action=<wired-mention|task-created|preference-written|relationship-confirmed|rejected> elementId=<id>` (mention rows append `edge=MENTIONS-from-Message` or `edge=MENTIONS-from-Conversation-fallback`)
+- `[whatsapp-import-enrich] done conversationId=<id> wired=<n> skipped=<n> rejected=<n> ms=<n>`
+
+**Confirms correct behaviour:** one `start … done` pair per enrich run; every `:Observation` row transitions out of `auto-extracted`; every `participant` log line cites a real `elementId`; the `done` line's wired/skipped/rejected sum equals the `start` line's `auto-observations` count.
+
+**Indicates failure:** post-run grep `'observationStatus="auto-extracted"'` non-zero (silent SET no-op); duplicate `participant action=promoted-existing` for the same elementId across reruns (idempotency violation); `done` line missing from a run that emitted `start` (mid-walk crash, no rollback).
+
+## Tools this skill uses
+
+Every prescribed tool resolves on database-operator's frontmatter `tools:` list. The pre-publish gate `platform/scripts/verify-skill-tool-surface.sh` asserts this statically:
+
+- `mcp__graph__maxy-graph-read_neo4j_cypher` — bulk preview, evidence reads, messageId recovery, owner-reconciliation lookup.
+- `mcp__graph__maxy-graph-write_neo4j_cypher` — `apoc.refactor.mergeNodes`, `:MENTIONS` and `:RELATED_TO` MERGEs, status-update SETs.
+- `mcp__memory__memory-search` — entity disambiguation for mentions and observed-relationship endpoints.
+- `mcp__memory__memory-write` — `:Preference` node creation with `:OBSERVED_IN` edge.
+- `mcp__contacts__contact-create` — mint-new-Person path.
+- `mcp__tasks__task-create` — `:Task` node creation with `affects=$conversationElementId`.
+
+Raw Cypher and `cypher-shell` are forbidden in this skill (per [database-operator's LOUD-FAIL prerogative](../../../../templates/specialists/agents/database-operator.md#prerogatives)). Every write goes through the MCP tool surface above. If a wrapped writer cannot express a needed shape, file a task — never improvise via Bash.
+
+## What this is not
+
+- **Not** Phase 1. Parse, archive-write, and the chunked Haiku insight pass live in `whatsapp-import` (the deterministic Bash entry). This skill never re-parses; it only transitions already-loaded state.
+- **Not** automatic. Every transition out of `auto-created` / `auto-extracted` requires an operator action — no auto-promotion, no auto-mention-acceptance, no batch confirmation. Compression-on-write doctrine ([feedback_compress_at_ingest_for_bulk_archives.md](../../../../../.claude/projects/-Users-neo-getmaxy/memory/feedback_compress_at_ingest_for_bulk_archives.md)) requires per-row operator judgement.
+- **Not** cross-conversation. The walk is scoped to one Conversation. Cross-conversation participant deduplication (the same person under two conversations) is operator-driven graph hygiene via [database-operator.md §Dedup merges](../../../../templates/specialists/agents/database-operator.md#dedup-merges), not this skill.
+- **Not** a backfill tool. Pre-Task-855 `:Observation` nodes do not exist; this skill assumes the Phase 1 contract and refuses to walk a conversation without `c.lastImportedAt`.

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -3,7 +3,7 @@ name: database-operator
 description: "Document and archive ingestion and ad-hoc graph operations — running the universal `document-ingest` skill for any unstructured document (PDF, text, transcript, web page, audio, video) and per-source archive-import skills (LinkedIn Basic Data Export today; CRM-type seed archives as each plugin ships), plus operator-driven graph hygiene (prune orphans, deduplicate entities, add edges, normalise labels). Delegate when the operator uploads any document, drops an archive directory into chat, or asks for any graph operation that is not a routine per-turn write."
 summary: "Ingests every unstructured document and external archive into your graph (LinkedIn today; other CRM sources in future) and handles ad-hoc graph tidy-ups on request. For example, when you upload a CV, a pricing guide, or a contract; when you drop a LinkedIn export folder into chat; or when you ask to prune orphan nodes, merge duplicate people, or add edges between entities."
 model: claude-sonnet-4-6
-tools: Read, Bash, Glob, Grep, mcp__graph__maxy-graph-read_neo4j_cypher, mcp__graph__maxy-graph-write_neo4j_cypher, mcp__graph__maxy-graph-get_neo4j_schema, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-delete, mcp__memory__memory-search, mcp__memory__memory-rank, mcp__memory__memory-reindex, mcp__memory__memory-find-candidates, mcp__memory__memory-ingest, mcp__memory__memory-ingest-extract, mcp__memory__memory-ingest-web, mcp__memory__memory-classify, mcp__memory__memory-archive-write, mcp__memory__graph-prune-denylist-list, mcp__memory__graph-prune-denylist-add, mcp__memory__graph-prune-denylist-remove, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__contacts__contact-lookup, mcp__contacts__contact-list, mcp__admin__file-attach, mcp__admin__plugin-read
+tools: Read, Bash, Glob, Grep, mcp__graph__maxy-graph-read_neo4j_cypher, mcp__graph__maxy-graph-write_neo4j_cypher, mcp__graph__maxy-graph-get_neo4j_schema, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-delete, mcp__memory__memory-search, mcp__memory__memory-rank, mcp__memory__memory-reindex, mcp__memory__memory-find-candidates, mcp__memory__memory-ingest, mcp__memory__memory-ingest-extract, mcp__memory__memory-ingest-web, mcp__memory__memory-classify, mcp__memory__memory-archive-write, mcp__memory__graph-prune-denylist-list, mcp__memory__graph-prune-denylist-add, mcp__memory__graph-prune-denylist-remove, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__contacts__contact-lookup, mcp__contacts__contact-list, mcp__tasks__task-create, mcp__admin__file-attach, mcp__admin__plugin-read
 ---
 
 # Database Operator
@@ -119,7 +119,10 @@ The classifier maps document sections to typed ontology labels. It does not inve
 Per-source archive imports keep their own skill because their CSVs already encode entity types deterministically and need no LLM classifier. Currently shipped:
 
 - **linkedin-import** — LinkedIn Basic Data Export. Ships with references for `Profile.csv` and `Connections.csv`; additional CSVs land as new references inside the same plugin over time. Path: `platform/plugins/linkedin-import/skills/linkedin-import/SKILL.md`. Load via `plugin-read` before any ingestion.
-- **whatsapp-import** — WhatsApp `_chat.txt` export ingestion. Imports historical Conversation + Messages with chronological NEXT chain plus typed insights (mentions, tasks, preferences, observed relationships) via the single deterministic Bash entry at `platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh` — parse, archive-write, and Haiku insight all run in-process; no MCP envelope between steps (Task 855). The legacy `mcp__memory__whatsapp-export-parse` / `whatsapp-export-insight-write` / `memory-archive-write{archiveType:whatsapp-export}` MCP tools are blocked at the harness; the Bash script is the only supported path. Distinct from the live `whatsapp` plugin (Baileys QR pairing, in-memory store). SKILL: `platform/plugins/whatsapp-import/skills/whatsapp-import/SKILL.md`. Load via `plugin-read` before any ingestion.
+- **whatsapp-import** — WhatsApp `_chat.txt` export ingestion. **Two-phase contract** (Task 855 + Task 859):
+  - **Phase 1 — load** (`whatsapp-import` skill). The single deterministic Bash entry at `platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh` parses the archive, writes Conversation + Messages with chronological NEXT chain, auto-creates one `:Person {participantStatus:'auto-created'}` per distinct senderName, and runs the chunked Haiku insight pass that lands `:Observation {observationStatus:'auto-extracted'}` rows connected `:OBSERVED_IN`→Conversation. Parse, archive-write, and insight all run in-process; no MCP envelope between steps. The legacy `mcp__memory__whatsapp-export-parse` / `whatsapp-export-insight-write` / `memory-archive-write{archiveType:whatsapp-export}` MCP tools are blocked at the harness; the Bash script is the only supported invocation. SKILL: `platform/plugins/whatsapp-import/skills/whatsapp-import/SKILL.md`.
+  - **Phase 2 — enrich** (`whatsapp-import-enrich` skill). Operator-driven semantic resolution against an already-loaded Conversation: walks the `auto-created` participants and `auto-extracted` observations, surfaces evidence per row, and writes operator-confirmed wiring (`apoc.refactor.mergeNodes` for participant promotion/merge, `:MENTIONS` and `:RELATED_TO` edges with `evidenceSnippet`/`evidenceMessageIds`, `:Task` via `mcp__tasks__task-create`, `:Preference` via `memory-write`). Idempotent — re-running surfaces only items still in `auto-created`/`auto-extracted` state. SKILL: `platform/plugins/whatsapp-import/skills/whatsapp-import-enrich/SKILL.md`.
+  - Distinct from the live `whatsapp` plugin (Baileys QR pairing, in-memory store). Load both SKILLs via `plugin-read` before invocation; the trigger phrase decides which phase the operator is asking for ("import this chat" → Phase 1; "enrich the X chat" / "promote auto-created participants from Y" / "wire observations from yesterday's import" → Phase 2). Phase 2 refuses to run against a Conversation whose `c.lastImportedAt` is null (Phase 1 never completed).
 
 Future CRM-type seed plugins (HubSpot, Salesforce, Pipedrive, iCloud contacts, Gmail CSV, etc.) will ship under the same pattern — each as its own opt-in plugin, each with its own `SKILL.md` path under `platform/plugins/<name>/skills/`. When the admin adds a new archive-import skill, its PLUGIN.md will name itself here and in the admin's `<plugin-manifest>`. No prompt change required.