@rubytech/create-realagent 1.0.826 → 1.0.829

package/payload/platform/plugins/whatsapp-import/lib/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"],
-  "exclude": ["src/__tests__"]
-}

package/payload/platform/plugins/whatsapp-import/lib/vitest.config.ts

@@ -1,9 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "node",
-    globals: false,
-    include: ["src/__tests__/**/*.test.ts"],
-  },
-});

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

@@ -1,131 +0,0 @@
----
-name: whatsapp-import
-description: Phase 1 of the WhatsApp `_chat.txt` ingest contract — deterministic, LLM-free. Preview the archive (parsed counts, date range, sender histogram), confirm the owner + third-party `:Person`, ask the operator to choose a filter (`all`, `senders=<csv>`, `date-range=<isoFrom>..<isoTo>`), then write Conversation + Messages + NEXT chain via the single Bash entry `whatsapp-ingest.sh`. The writer binds participants to the owner + subject pair: any parsed senderName outside that closed set LOUD-FAILs. NO observations and NO LLM at this phase — semantic enrichment lives in the `whatsapp-import-enrich` skill (Phase 2). Triggers when the user asks to import a WhatsApp chat, ingest a `_chat.txt` file, or drops the contents of an "Export Chat" folder into chat. Distinct from the live `whatsapp` plugin (Baileys); this is import-from-export only.
----
-
-# WhatsApp Import — Phase 1 (Load)
-
-Phase 1 of the two-phase WhatsApp ingest contract. Deterministic only: parse → preview → operator-supplied filter → archive-write. NO LLM is invoked at this phase. The chunked Haiku insight pass moved to Phase 2 (`whatsapp-import-enrich` skill) so one ingest cannot blow the operator's context window with `:Observation` enumeration prose.
-
-## Owner + subject confirmation (mandatory first step)
-
-A WhatsApp DM has exactly two participants. The **owner** is the operator who exported the `_chat.txt`; the **subject** is the third party in the conversation. Both must resolve to existing graph nodes (`:AdminUser` or `:Person`) before the script runs — the writer is bound to that closed pair to prevent auto-creating phantom participants.
-
-1. List every `:AdminUser` and the senders surfaced by Step 1 preview via `mcp__graph__maxy-graph-read_neo4j_cypher`:
-   `MATCH (u:AdminUser) RETURN elementId(u) AS elementId, u.name AS name, u.userId AS userId, u.accountId AS accountId`
-2. Ask the operator: "Who exported this `_chat.txt`?" — accept either an existing `:AdminUser` elementId or, if the operator names someone not in the graph, surface that as a blocker (auto-creating an unknown owner is refused).
-3. Identify the third party from the preview's sender histogram. Look up the matching `:Person` (by name); if no match, ask the operator to confirm a `:Person` elementId or block until one exists. **Auto-creating the third-party `:Person` is forbidden** — the operator must confirm the canonical node.
-4. Echo both back verbatim and require explicit yes/no confirmation.
-5. Persist the owner's `elementId` as `--owner-element-id` and the subject's as `--subject-person-id`.
-
-## Step 1 — preview (mandatory before any write)
-
-Call `mcp__memory__whatsapp-export-preview` with the operator-supplied path:
-
-```json
-{
-  "filePath": "/abs/path/to/_chat.txt",
-  "timezone": "Europe/London"
-}
-```
-
-Returns: `{conversationSha256, archiveSourceFile, archiveBytes, parsed, mediaSkipped, systemSkipped, totalMessages, dateRange:{first,last}, senders:[{name,messageCount}, …]}`. No Cypher writes; the call is read-only and does NOT touch Neo4j.
-
-Surface to the operator as one chat message — counters and the histogram, no prose:
-
-> Preview of `<archive>`: `<parsed>` messages parsed, `<mediaSkipped>` media skipped, `<systemSkipped>` system skipped. Date range: `<first>` → `<last>`. Senders (top by count): `Joel (812), Adam (895)`. File hash: `<conversationSha256>` (`<archiveBytes>` bytes).
-
-## Step 2 — operator chooses a filter
-
-Ask exactly: "Filter to apply: `all`, `senders=<csv>`, or `date-range=<isoFrom>..<isoTo>`?" — no defaults, no menu of "or shall I just write everything". The operator picks one of the three forms verbatim:
-
-| Filter | Effect |
-|--------|--------|
-| `all` | Write every parsed row. Operator's explicit "I want the full archive" choice. |
-| `senders=Alice,Bob Carter` | Keep only rows whose senderName matches one of the comma-separated names exactly (whitespace trimmed). |
-| `date-range=2024-01-01..2024-06-30` | Keep only rows whose `dateSent` falls inside the inclusive range (date-only or full ISO 8601 endpoints both accepted). |
-
-Echo the chosen filter back; require explicit yes/no confirmation before the write.
-
-## Step 3 — archive-write
-
-Single Bash call:
-
-```bash
-bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive.zip|dir|_chat.txt> \
-  --owner-element-id <id> \
-  --subject-person-id <id> \
-  --scope <admin|public> \
-  --filter <all|senders=<csv>|date-range=<isoFrom>..<isoTo>>
-```
-
-Optional flags:
-- `--account-id <id>` — explicit account id when more than one exists under `data/accounts/` (Phase 0 has one).
-- `--timezone <iana>` — IANA zone for timestamps (default `Europe/London`).
-- `--date-format <DD/MM/YY|MM/DD/YY|DD/MM/YYYY|MM/DD/YYYY>` — override auto-detect for ambiguous locales.
-
-The script:
-- Unzips the archive if needed; locates `_chat.txt`.
-- Parses the file deterministically (year shape, sender/body grammar, timezone offset, U+200E/U+200F leading-bidi-strip).
-- Applies the operator-supplied filter to `parseResult.parsedLines` BEFORE archive-write.
-- Validates every distinct parsed senderName against the canonical-name candidates of `{owner, subject}` (NFKC-trim-lower normalisation). Any miss LOUD-FAILs with `[whatsapp-ingest] FAIL parser-miss reason="senderName=<verbatim> not in preview histogram (parser failure — re-export or report)"` and exits non-zero. **Never auto-creates a participant** — the fallback path was removed by design.
-- Writes the Conversation + Messages + edges + NEXT chronology via `memoryArchiveWrite` directly (no MCP envelope between steps).
-
-NO insight pass runs. The `--no-insight` flag of older releases is gone — Phase 1 always means parse + filter + archive-write, nothing else.
-
-## Phase 1 agent-return — counters only
-
-Stdout JSON shape (success — full diagnostic counters):
-
-```json
-{
-  "conversationElementId": "4:abcd…:42",
-  "conversationId": "whatsapp-export:<sha>:<accountId>",
-  "parsed": 1707,
-  "mediaSkipped": 0,
-  "systemSkipped": 0,
-  "filtered": 1707,
-  "written": 1707,
-  "messagesAlreadyExisted": 0,
-  "nextEdgesProcessed": 1706,
-  "nextEdgesCreated": 1706,
-  "participantsAlreadyExisted": 2,
-  "ms": 6800
-}
-```
-
-Surface to the admin agent as exactly one message (counters first, one sentence pointing at the Phase 2 surface):
-
-> Imported `<written>` messages from `<archive>` into conversation `<conversationElementId>` (`<conversationId>`); already existed: `<messagesAlreadyExisted>`; NEXT edges created: `<nextEdgesCreated>`. Use `mcp__memory__whatsapp-export-preview` for any future re-import preview; trigger semantic enrichment via the `whatsapp-import-enrich` skill ("enrich the `<chat-name>` chat") when ready.
-
-NO inline enumeration of mention/task/preference/relationship counts. NO multi-paragraph "ask to enrich" prose. The above shape is load-bearing — concision over completeness, because one prior ingest blew the operator's context with count enumeration.
-
-### Re-import signal
-
-A second invocation against the same archive should report `messagesAlreadyExisted > 0 AND written > 0` once the stable-messageId contract is in place. The subagent asserts both counters appear non-trivially before claiming a re-import landed cleanly.
-
-## Failure path — single FAIL line
-
-- **Exit non-zero** + one stderr line: `[whatsapp-ingest] FAIL phase=<argv|filter|parse|archive-write|import|uncaught> reason="<sanitised first 80c>" ...`. Surface this verbatim to the operator and yield. **Do not retry. Do not edit parser source.** The archive-ingest-surface-gate denies parser-source edits, JS test runners, and the legacy `whatsapp-export-parse` / `whatsapp-export-insight-write` / `memory-archive-write{archiveType:whatsapp-export}` MCP tools — none of those are escape hatches in your surface.
-
-Missing `--filter` emits the pinned line `[whatsapp-ingest] FAIL filter-required reason="bulk-archive-gate — operator must specify --filter (one of all, senders=<csv>, date-range=<isoFrom>..<isoTo>)"`. Re-invoke with the operator's chosen filter — never fabricate a default.
-
-## Idempotency
-
-Re-running with the same `<archive>` + `--filter` is a no-op once the stable-messageId contract is in place: `written: 0`, `nextEdgesCreated: 0`, conversation scalars refreshed via `lastImportedAt` / `lastImportedBySession`. Re-exports with appended messages add only the delta and extend the NEXT chain. Without a stable messageId (line-hash + array-position keying) re-imports double the message set — the natural-key fix is what makes the contract real.
-
-## Verification (post-write)
-
-Run via `mcp__graph__maxy-graph-read_neo4j_cypher`:
-
-- `MATCH (c:Conversation:WhatsAppConversation {conversationId: $cid}) RETURN c.messageCount, c.participantCount, c.firstMessageAt, c.lastMessageAt` — agrees with the JSON summary.
-- `MATCH (m:Message)-[:PART_OF]->(c {conversationId: $cid}) RETURN count(m)` — equals `written + messagesAlreadyExisted` (post-filter).
-- `MATCH p=(:Message {conversationId: $cid})-[:NEXT*]->() WITH max(length(p)) AS chain RETURN chain` — equals `messageCount - 1`.
-- Phase 1 wrote ZERO observations: `MATCH (o:Observation)-[:OBSERVED_IN]->(:Conversation {conversationId: $cid}) RETURN count(o)` — should be 0 immediately after Phase 1. Observations land only when the operator triggers Phase 2.
-
-## What this is not
-
-- **Not** the live `whatsapp` plugin. That plugin (Baileys QR pairing) holds messages in an in-memory store cleared on restart. This plugin imports historical exports into Neo4j as persistent graph nodes.
-- **Not** a media-transcription pipeline. Voice notes, photos, PDFs are skipped at parse with a counter logged.
-- **Not** the operator-level semantic enrichment pass. Auto-created participants and `:Observation` nodes are deliberately raw — Phase 2 (`whatsapp-import-enrich`) lays down the observations via `whatsapp-export-insight-pass` and walks them through operator-confirmed wiring.
-- **Not** an LLM entry. Phase 1 has no Haiku call, no OAuth call, no model surface. The single sanctioned LLM entry for WhatsApp ingest is `mcp__memory__whatsapp-export-insight-pass`, invoked by the Phase 2 skill.

package/payload/platform/plugins/whatsapp-import/skills/whatsapp-import/references/export-parse.md

@@ -1,109 +0,0 @@
-# Reference: `_chat.txt` parsing — implementation reference
-
-> **This is no longer operator instruction.** The agent does NOT walk this grammar in its own LLM turn. Parsing runs deterministically in [`platform/plugins/whatsapp-import/lib/src/parse-export.ts`](../../../lib/src/parse-export.ts), invoked in-process by [`bin/ingest.mjs`](../../../bin/ingest.mjs) (which the operator calls via [`bin/whatsapp-ingest.sh`](../../../bin/whatsapp-ingest.sh) — the single deterministic Bash entry). The legacy MCP wrapper is blocked at the harness gate. The vitest grid in [`lib/src/__tests__/parse-export.test.ts`](../../../lib/src/__tests__/parse-export.test.ts) is the executable contract; this prose is the human-readable companion. Extend the grammar by adding a failing test first.
-
-WhatsApp's "Export Chat" produces a UTF-8 text file with a deterministic line grammar. This reference describes what the parser library does when it converts that file into the `{senderName, dateSent, body, sequenceIndex}[]` structure the SKILL.md consumes.
-
-## File-open invariants
-
-1. **UTF-8 only.** Open the file with explicit UTF-8 decoding. On encoding error, abort the import with a named LOUD-FAIL — never silently substitute or corrupt bodies. WhatsApp's modern apps emit UTF-8 reliably; an encoding error usually means the operator manually edited the file with a tool that broke it. Surface the named error so they can re-export.
-2. **No size cap from the parser.** The parser handles arbitrarily large files; the [SKILL.md](../SKILL.md)'s 100-message selective-ingest gate is the operator-facing compression layer.
-3. **Compute `archiveSourceFile = sha256(file bytes)` first.** The hash drives `conversationId` and lets re-imports of the same archive land idempotently.
-
-## Line grammar
-
-Every message line begins with a square-bracketed timestamp prefix followed by `<Sender>: <body>`:
-
-```
-[DD/MM/YYYY, HH:MM:SS] <Sender>: <body>      ← modern WhatsApp default (4-digit year)
-[DD/MM/YY, HH:MM:SS] <Sender>: <body>        ← legacy exports (2-digit year)
-```
-
-- **Day/month ordering.** `DD/MM` is the WhatsApp default everywhere except US iOS, which emits `MM/DD`. The parser auto-detects from the first prefix-matching line when `dateFormat` is omitted: probe DD/MM first; if range-valid, lock DD/MM; otherwise lock MM/DD. The lock is per-file — a single export never mixes orderings (the locale is set by the device that generated the export). Manually concatenated multi-locale archives are an explicit out-of-scope: pass `dateFormat` to override.
-- **Year shape.** Both 2-digit (`\d{2}` → `2000+yy`) and 4-digit (`\d{4}` → as-is) years are accepted by the same regex (`\d{2,4}`). A single file may hold both shapes; year semantics are resolved per-line from the captured length, not per-file.
-- **Time.** `HH:MM:SS` 24-hour; older exports may emit `HH:MM` (no seconds — treat as `:00`).
-- **Sender.** Saved contact name, phone number with country code (`+44 7700 900123`), or `You` for legacy operator-sent messages.
-- **Body.** Message text, possibly multi-line.
-
-Trim trailing whitespace from each line before parsing.
-
-## Multi-line bodies
-
-A body that wraps to multiple lines continues onto subsequent lines that do **not** match the timestamp-prefix pattern. The parser must accumulate these continuation lines into the previous message's body, joining with `\n`. End-of-message is detected by the next timestamp prefix or end-of-file.
-
-```
-[14/03/26, 10:15:23] Joel: Quick question about the deck —
-do you have the v3 PDF anywhere?
-I checked Drive and only see v2.
-[14/03/26, 10:16:01] Sarah: Sec, will dig it out
-```
-
-Yields two messages:
-- `Joel: "Quick question about the deck —\ndo you have the v3 PDF anywhere?\nI checked Drive and only see v2."`
-- `Sarah: "Sec, will dig it out"`
-
-## System messages — skip with counter
-
-WhatsApp injects system-generated lines into the export for group events, contact changes, and security messages. These lines match the timestamp prefix but are **not** sent by a person and have no first-class graph value. Skip them at parse time, increment `systemSkipped`, and do not pass to `memory-archive-write`.
-
-Patterns to recognise (English; localisation expands the list):
-
-- `<Sender> created group "<name>"`
-- `<Sender> changed the subject from "<old>" to "<new>"`
-- `<Sender> changed this group's icon`
-- `<Sender> added <other>`
-- `<Sender> removed <other>`
-- `<Sender> left`
-- `<Sender>'s security code changed.`
-- `Messages and calls are end-to-end encrypted. ...` (the conversation header)
-- `You deleted this message.`
-- `This message was deleted.`
-
-Heuristic for the parser: if the body contains no spaces between `<Sender>` and a verb-phrase token, AND the body lacks a colon-after-sender separator, treat as a system message. Conservative — when uncertain, prefer to ingest as a message; the insight pass tolerates noisy bodies better than the parser would tolerate dropped real messages.
-
-## Media attachments — skip with counter
-
-Lines whose body indicates a media-only message (no text content) get skipped at parse time, increment `mediaSkipped`. Patterns:
-
-- `<Media omitted>` (when the operator chose "Without Media" on export)
-- `IMG-<digits>-<digits>.jpg (file attached)` / `.jpeg` / `.png` / `.heic` / `.gif`
-- `VID-<digits>-<digits>.mp4 (file attached)`
-- `PTT-<digits>-<digits>.opus (file attached)` (voice notes)
-- `AUD-<digits>-<digits>.opus (file attached)` (audio)
-- `STK-<digits>-<digits>.webp (file attached)` (stickers)
-- `<filename>.pdf (file attached)`
-- `<filename>.docx (file attached)`
-- `‎<...> attached: <filename>` (alternative format on some platforms)
-
-Mixed messages (text + media reference in one body) are kept as messages — only pure-media-only lines are skipped. The text body is retained.
-
-## Forwarded messages
-
-A forwarded message is prefixed with the invisible Unicode `‎` (U+200E LEFT-TO-RIGHT MARK) followed by metadata WhatsApp injects. Parse the body normally; the LRM character is preserved in `body` (the insight pass's classifier sees it as benign). Do not strip — the raw body's fidelity matters for downstream queries.
-
-## Edge cases
-
-- **Empty body** (timestamp prefix followed by sender colon but no text). Rare. Skip with `systemSkipped` increment — usually corresponds to a deleted message stub.
-- **Leading BOM** (U+FEFF at file start). Strip before parsing the first line.
-- **Mixed line endings** (`\r\n` vs `\n`). Normalise to `\n` before tokenisation.
-- **Sender containing a colon** (e.g., a contact named "Joel: Work"). The grammar splits on the FIRST `: ` (colon-space) after the timestamp prefix's closing `]`. Subsequent colons in the sender or body are preserved verbatim.
-
-## Parser output shape
-
-The parser returns `{conversationId, archiveSourceFile, parsedLines[], counters}` where:
-
-- `parsedLines[]: Array<{senderName: string, dateSent: string (ISO 8601 with operator-supplied timezone), body: string, sequenceIndex: number}>`
-- `counters: {parsed: n, systemSkipped: n, mediaSkipped: n, parseErrors: n}`
-
-The skill consumes this directly. The `messageId` is computed by the skill (not the parser) so the `lineHash` covers the original raw line, not the post-parse normalised body.
-
-## When to LOUD-FAIL
-
-The parser throws (and `whatsapp-export-parse` returns `isError: true`) on:
-
-- Encoding error at file open (UTF-8 decode fails — the parser uses `TextDecoder` with `fatal: true`, so any invalid byte sequence aborts loudly rather than silently substituting U+FFFD).
-- Empty file or zero parsed lines after walking the file (the file isn't a `_chat.txt`). The thrown error and the `[whatsapp-import] parse-grammar-miss first-line="<sample>"` stderr line both carry a sanitised first-line sample (control chars stripped, truncated to 80 chars) so the operator can recognise the offending header shape without re-running with a debugger.
-- A timestamp prefix matches but the body parse fails (no `: ` separator after the closing `]` AND no system-pattern match) — emits `parse-error file=<...> line=<n> reason=no-sender-body-separator content="<...>"`.
-- Missing required input (`accountId`, `timezone`).
-
-Never silently drop data the parser couldn't classify. The operator chooses to skip; the parser does not choose for them.

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

@@ -1,333 +0,0 @@
----
-name: whatsapp-import-enrich
-description: Operator-driven semantic enrichment pass over an already-loaded WhatsApp Conversation. Owns the LLM half of the WhatsApp ingest pipeline — first runs `mcp__memory__whatsapp-export-insight-pass` (chunkSize=50, overlap=5, server-side confidence>=0.8 gate) to lay down `:Observation {observationStatus:'auto-extracted'}` rows, then walks `:Person {participantStatus:'auto-created'}` and the auto-extracted observations, 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` Phase 1; never re-runs parse.
----
-
-# WhatsApp Import — Enrich
-
-Phase 2 of the two-phase WhatsApp ingest contract. Phase 1 (`whatsapp-import`) is the deterministic, LLM-FREE Bash entry that lands raw shape: Conversation + Messages + chronological NEXT chain + auto-created `:Person` participants. Phase 2 (this skill) owns the LLM half: it runs the chunked Haiku insight pass on demand to lay down `:Observation` nodes, then operator-driven semantic resolution disambiguates participants, wires observations to typed entities, and reattributes the operator's own messages from the auto-Person to their `:AdminUser`.
-
-The split exists because the inline insight pass on Phase 1 (1500 msgs/chunk, no operator gate) polluted the parent's tool_result with `:Observation` enumeration prose and blew operator context. Phase 1 is now mute on insights; this skill triggers them consciously with `mcp__memory__whatsapp-export-insight-pass` when the operator asks.
-
-## 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).
-
-## Step 0 — run the chunked Haiku insight pass (Phase 2a)
-
-Phase 1 writes ZERO `:Observation` rows. Before any walk, lay them down via `mcp__memory__whatsapp-export-insight-pass`:
-
-```json
-{ "conversationId": "whatsapp-export:<sha>:<accountId>" }
-```
-
-The tool walks the Messages of the conversation in chronological order, chunks them at **chunkSize=50** with **overlap=5** (the prior 1500 msgs/chunk implementation lost per-message attention), runs Haiku per chunk, applies a server-side `confidence>=0.8` gate, and MERGE-keys `:Observation` rows. Returns `{conversationId, chunks, chunkSize, overlap, confidenceThreshold, totals:{mentions, tasks, preferences, observedRelationships, rejectedLowConfidence, written}, ms}`.
-
-Surface to the operator as one chat message — counters only, no enumeration:
-
-> Insight pass complete on `<conversationId>`: `<chunks>` chunks at chunkSize=50 / overlap=5 / confidenceThreshold=0.8. Wrote `<written>` observations (`<mentions>` mentions, `<tasks>` tasks, `<preferences>` preferences, `<observedRelationships>` relationships); rejected `<rejectedLowConfidence>` low-confidence items.
-
-Idempotent — re-running collapses identical `(conversationId, sourceMessageRef, kind, contentHash)` tuples into one row. Re-runs are safe; the operator can tune the conversation by re-importing extra rows in Phase 1, then re-running the pass here.
-
-## 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` (the 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__memory__whatsapp-export-insight-pass` — Phase 2a chunked-Haiku insight extraction (chunkSize=50, overlap=5, confidence>=0.8). Lays down `:Observation` rows the rest of this skill walks. Owns the LLM half of WhatsApp ingest — Phase 1 has none.
-- `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 and archive-write live in `whatsapp-import` (the deterministic Bash entry, LLM-FREE). This skill never re-parses. The Haiku insight pass lives here — Step 0 above is the one sanctioned LLM entry for WhatsApp ingest, and it is invoked consciously by the operator, not silently on archive-write.
-- **Not** automatic. Every transition out of `auto-created` / `auto-extracted` requires an operator action — no auto-promotion, no auto-mention-acceptance, no batch confirmation. Compress-at-ingest doctrine 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. This skill assumes the Phase 1 contract and refuses to walk a conversation without `c.lastImportedAt`.