@rubytech/create-maxy 1.0.799 → 1.0.801

package/payload/server/public/index.html

@@ -5,7 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Maxy</title>
   <link rel="icon" href="/favicon.ico">
-  <script type="module" crossorigin src="/assets/admin-C0lKk6WM.js"></script>
+  <script type="module" crossorigin src="/assets/admin-Sa301b8q.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/chunk-DD-I1_y5.js">
   <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-DJER3a7U.js">
   <link rel="modulepreload" crossorigin href="/assets/preload-helper-qlgyTAkD.js">

package/payload/platform/plugins/admin/hooks/__tests__/archive-ingest-gate.test.sh

@@ -1,166 +0,0 @@
-#!/usr/bin/env bash
-# Regression test for archive-ingest-gate.sh (Task 846).
-#
-# Six cases cover the contract:
-#   1. Edit on /platform/plugins/<x>/lib/* is BLOCKED (exit 2).
-#   2. Edit on a benign path is ALLOWED (exit 0).
-#   3. Bash with `npx vitest` is BLOCKED.
-#   4. PostToolUse on whatsapp-export-parse with isError:true sets the flag.
-#   5. Subsequent PreToolUse on ANY tool is BLOCKED (post-parse-error gate).
-#   6. UserPromptSubmit clears the flag, restoring normal allow behavior.
-#
-# Tests use ARCHIVE_INGEST_GATE_STATE_DIR to point at a tmp dir so they run
-# without a real account layout.
-
-set -u
-
-HOOK="$(cd "$(dirname "$0")/.." && pwd)/archive-ingest-gate.sh"
-if [[ ! -x "$HOOK" ]]; then
-  echo "FAIL: $HOOK not executable" >&2
-  exit 1
-fi
-
-# Per-run isolated state dir
-STATE_DIR=$(mktemp -d)
-export ARCHIVE_INGEST_GATE_STATE_DIR="$STATE_DIR"
-FLAG_FILE="$STATE_DIR/archive-ingest-parse-error.flag"
-
-cleanup() { rm -rf "$STATE_DIR"; }
-trap cleanup EXIT
-
-PASS=0
-FAIL=0
-
-run_case() {
-  local name="$1" stdin="$2" expected_exit="$3"
-  local actual_exit
-  printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null
-  actual_exit=$?
-  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
-    echo "PASS: $name (exit=$actual_exit)"
-    PASS=$((PASS + 1))
-  else
-    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2
-    FAIL=$((FAIL + 1))
-  fi
-}
-
-# Case 1 — Edit on plugin lib path: BLOCKED
-run_case "Edit on platform/plugins/whatsapp-import/lib/src/parse-export.ts → BLOCKED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/platform/plugins/whatsapp-import/lib/src/parse-export.ts","old_string":"a","new_string":"b"}}' \
-  2
-
-# Case 2 — Edit on a benign path: ALLOWED
-run_case "Edit on README.md → ALLOWED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/README.md","old_string":"a","new_string":"b"}}' \
-  0
-
-# Case 3 — Bash with `npx vitest`: BLOCKED
-run_case "Bash 'npx vitest run parse-export.test.ts' → BLOCKED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npx vitest run parse-export.test.ts"}}' \
-  2
-
-# Case 3b — Bash with benign command: ALLOWED
-run_case "Bash 'ls -la' → ALLOWED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
-  0
-
-# Case 3c — Bash with `bun test`: BLOCKED
-run_case "Bash 'bun test' → BLOCKED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bun test"}}' \
-  2
-
-# Case 3d — Bash with `npm test`: BLOCKED
-run_case "Bash 'npm test' → BLOCKED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' \
-  2
-
-# Make sure flag is absent before parse-error simulation
-rm -f "$FLAG_FILE"
-
-# Case 4 — PostToolUse on whatsapp-export-parse with isError:true sets flag
-run_case "PostToolUse parse-error sets flag (exit 0, flag side-effect)" \
-  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":true,"content":[{"type":"text","text":"parse-error file=_chat.txt line=1 reason=not-a-_chat.txt"}]}}' \
-  0
-
-if [[ -f "$FLAG_FILE" ]]; then
-  echo "PASS: parse-error flag created at $FLAG_FILE"
-  PASS=$((PASS + 1))
-else
-  echo "FAIL: parse-error flag NOT created at $FLAG_FILE" >&2
-  FAIL=$((FAIL + 1))
-fi
-
-# Case 5 — Subsequent PreToolUse on ANY tool BLOCKED while flag is fresh
-run_case "PreToolUse Read after parse-error → BLOCKED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
-  2
-
-run_case "PreToolUse Bash after parse-error → BLOCKED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"}}' \
-  2
-
-# Case 6 — UserPromptSubmit clears flag
-run_case "UserPromptSubmit clears flag (exit 0)" \
-  '{"hook_event_name":"UserPromptSubmit","prompt":"retry"}' \
-  0
-
-if [[ ! -f "$FLAG_FILE" ]]; then
-  echo "PASS: UserPromptSubmit cleared flag"
-  PASS=$((PASS + 1))
-else
-  echo "FAIL: UserPromptSubmit did NOT clear flag" >&2
-  FAIL=$((FAIL + 1))
-fi
-
-# Case 7 — After clearance, normal allow resumes
-run_case "PreToolUse Read after clearance → ALLOWED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
-  0
-
-# Case 8 — PostToolUse with isError:false does NOT set flag
-rm -f "$FLAG_FILE"
-run_case "PostToolUse parse-success (isError:false) does NOT set flag" \
-  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":false,"content":[{"type":"text","text":"{\"parsedLines\":[]}"}]}}' \
-  0
-
-if [[ ! -f "$FLAG_FILE" ]]; then
-  echo "PASS: parse-success leaves flag absent"
-  PASS=$((PASS + 1))
-else
-  echo "FAIL: parse-success incorrectly created flag" >&2
-  FAIL=$((FAIL + 1))
-fi
-
-# Case 9 — Stale flag (>600s) auto-clears + allows
-PAST=$(( $(date -u +%s) - 700 ))
-echo "$PAST" > "$FLAG_FILE"
-run_case "Stale flag auto-clears, PreToolUse Read → ALLOWED" \
-  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
-  0
-
-# Case 10 — No stdin (terminal) fails closed
-echo "Probing fail-closed behaviour (no stdin)..."
-bash "$HOOK" </dev/null >/dev/null 2>/dev/null
-ACTUAL=$?
-# /dev/null IS a stdin — the `[ -t 0 ]` check tests for terminal, not file.
-# A file/pipe stdin reads as empty, which produces empty hook_event_name and
-# falls through to default `exit 0` (allow). The terminal-only fail-closed
-# branch can't be tested non-interactively; verify the script reads `[ -t 0 ]`.
-if grep -q '\[ -t 0 \]' "$HOOK"; then
-  echo "PASS: fail-closed terminal check is present"
-  PASS=$((PASS + 1))
-else
-  echo "FAIL: fail-closed terminal check missing" >&2
-  FAIL=$((FAIL + 1))
-fi
-
-echo
-echo "──────── archive-ingest-gate test summary ────────"
-echo "PASS: $PASS"
-echo "FAIL: $FAIL"
-
-if [[ "$FAIL" -gt 0 ]]; then
-  exit 1
-fi
-exit 0

package/payload/platform/plugins/admin/hooks/archive-ingest-gate.sh

@@ -1,147 +0,0 @@
-#!/usr/bin/env bash
-# Archive-ingest gate (Task 846).
-#
-# Three enforcements, one script — phase decided by `hook_event_name` on stdin:
-#
-# 1. PreToolUse Edit/Write/NotebookEdit: deny writes under
-#    `*platform/plugins/*/lib/*` (parser/CSV-shape source for any *-import or
-#    *-export plugin). The database-operator subagent has Read+Bash but not
-#    Edit/Write per its `tools:` frontmatter — yet it can still mutate files
-#    via Bash heredoc. The path block applies to every tool that takes a
-#    `file_path` and has been observed as the improvisation surface.
-#
-# 2. PreToolUse Bash: deny commands invoking JavaScript test runners
-#    (vitest|bun test|npm test|npx jest|node .*vitest). The reproducer
-#    incident (conv 47c6a590) saw the operator run all four variants in
-#    sequence after parse-export returned isError.
-#
-# 3. Parse-error gate: PostToolUse on any `mcp__*__*-export-parse` /
-#    `mcp__*__*-import-parse` tool whose `tool_response.isError == true`
-#    writes a flag file. Subsequent PreToolUse on ANY tool blocks until
-#    UserPromptSubmit clears the flag (semantics: "subagent's next action
-#    must be a user-facing message; further tool calls blocked"). A 600s
-#    TTL is the cross-session safety net.
-#
-# Exit codes follow Claude Code hook protocol: 0 = allow, 2 = block (stderr
-# message shown to the agent). Fail-closed on stdin read failure to match
-# pre-tool-use.sh.
-
-set -uo pipefail
-
-# Read stdin — fail closed if unavailable
-if [ -t 0 ]; then
-  echo "Blocked: archive-ingest-gate received no stdin (cannot inspect tool call). Failing closed." >&2
-  exit 2
-fi
-INPUT=$(cat)
-
-# ----- Resolve account dir for state file ----------------------------------
-# Mirrors pre-tool-use.sh lines 100-107: walk from this hook's location to
-# platform/, then `../data/accounts/<single-account>/`. Phase 0 has exactly
-# one account directory.
-HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
-PLATFORM_ROOT_RESOLVED="${HOOK_DIR}/../../.."
-ACCOUNTS_DIR="${PLATFORM_ROOT_RESOLVED}/../data/accounts"
-ACCOUNT_DIR=""
-if [ -d "$ACCOUNTS_DIR" ]; then
-  ACCOUNT_DIR=$(find "$ACCOUNTS_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | head -1)
-fi
-# Test harness override — tests pass `ARCHIVE_INGEST_GATE_STATE_DIR` to point
-# at a tmp dir without needing a real account layout.
-STATE_DIR="${ARCHIVE_INGEST_GATE_STATE_DIR:-${ACCOUNT_DIR}/state}"
-FLAG_FILE="${STATE_DIR}/archive-ingest-parse-error.flag"
-TTL_SECONDS=600
-
-# ----- Parse fields from stdin ---------------------------------------------
-# Hook protocol: every event includes `hook_event_name`. PreToolUse +
-# PostToolUse include `tool_name`. PostToolUse adds `tool_response`.
-# UserPromptSubmit has neither. Use grep/sed against the JSON envelope —
-# no jq dependency to match the rest of the hook fleet.
-HOOK_EVENT=$(printf '%s' "$INPUT" | grep -o '"hook_event_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
-TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
-
-# ============================================================================
-# UserPromptSubmit — clear the parse-error flag.
-# ============================================================================
-if [ "$HOOK_EVENT" = "UserPromptSubmit" ]; then
-  if [ -f "$FLAG_FILE" ]; then
-    rm -f "$FLAG_FILE" 2>/dev/null
-    echo "[archive-ingest-gate] cleared reason=user-prompt-submit" >&2
-  fi
-  exit 0
-fi
-
-# ============================================================================
-# PostToolUse — record parse-error from any *-export-parse / *-import-parse.
-# ============================================================================
-if [ "$HOOK_EVENT" = "PostToolUse" ]; then
-  case "$TOOL_NAME" in
-    mcp__*__*-export-parse|mcp__*__*-import-parse)
-      # Inspect tool_response for isError true. Body is a JSON object; match
-      # `"isError":true` with optional whitespace.
-      if printf '%s' "$INPUT" | grep -Eq '"isError"[[:space:]]*:[[:space:]]*true'; then
-        mkdir -p "$STATE_DIR" 2>/dev/null
-        date -u +%s > "$FLAG_FILE" 2>/dev/null
-        echo "[archive-ingest-gate] surfaced reason=parse-error tool=${TOOL_NAME}" >&2
-      fi
-      ;;
-  esac
-  # PostToolUse must always allow the tool result through.
-  exit 0
-fi
-
-# ============================================================================
-# PreToolUse — three independent blocks.
-# ============================================================================
-if [ "$HOOK_EVENT" != "PreToolUse" ]; then
-  # Unknown event, or hook fired in a context without an event name. Allow.
-  exit 0
-fi
-
-# --- Block 1: post-parse-error gate (applies to ALL tools) -----------------
-if [ -f "$FLAG_FILE" ]; then
-  FLAG_TS=$(cat "$FLAG_FILE" 2>/dev/null | head -1)
-  NOW=$(date -u +%s)
-  if [ -n "$FLAG_TS" ] && [ "$FLAG_TS" -gt 0 ] 2>/dev/null; then
-    AGE=$(( NOW - FLAG_TS ))
-    if [ "$AGE" -lt "$TTL_SECONDS" ]; then
-      echo "[archive-ingest-gate] block tool=${TOOL_NAME} reason=post-parse-error age_s=${AGE}" >&2
-      echo "Blocked: an archive-parser MCP tool returned isError=true earlier in this turn. The subagent's next action must be a user-facing message naming the parse-error and yielding back to the operator. Further tool calls are blocked until the operator submits a new prompt." >&2
-      exit 2
-    fi
-    # Stale flag — clean up so we don't keep blocking on a corpse.
-    rm -f "$FLAG_FILE" 2>/dev/null
-  else
-    # Unparseable flag — remove rather than block on garbage.
-    rm -f "$FLAG_FILE" 2>/dev/null
-  fi
-fi
-
-# --- Block 2: plugin-source path block (Edit/Write/NotebookEdit) -----------
-case "$TOOL_NAME" in
-  Edit|Write|NotebookEdit)
-    FILE_PATH=$(printf '%s' "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
-    case "$FILE_PATH" in
-      */platform/plugins/*/lib/*|platform/plugins/*/lib/*)
-        echo "[archive-ingest-gate] block tool=${TOOL_NAME} reason=plugin-source-edit path=${FILE_PATH}" >&2
-        echo "Blocked: ${TOOL_NAME} on ${FILE_PATH} is a platform plugin lib/ path. The database-operator subagent does not own plugin source; if a parser is broken, surface the parse-error to the operator and let them dispatch a code-edit task instead." >&2
-        exit 2
-        ;;
-    esac
-    ;;
-esac
-
-# --- Block 3: shell test-runner block (Bash) -------------------------------
-if [ "$TOOL_NAME" = "Bash" ]; then
-  COMMAND=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
-  # Match any of: `vitest`, `bun test`, `npm test`, `npx jest`, `node ... vitest`.
-  # Word-boundary checks via grep -E with explicit token boundaries — POSIX
-  # `[[:space:]]` covers leading-token edge cases, end-of-string covers tail.
-  if printf '%s' "$COMMAND" | grep -Eq '(^|[[:space:]/])vitest($|[[:space:]])|(^|[[:space:]])bun[[:space:]]+test($|[[:space:]])|(^|[[:space:]])npm[[:space:]]+test($|[[:space:]])|(^|[[:space:]])npx[[:space:]]+jest($|[[:space:]])|node[[:space:]].*vitest'; then
-    echo "[archive-ingest-gate] block tool=Bash reason=test-runner command=${COMMAND}" >&2
-    echo "Blocked: Bash command invokes a JavaScript test runner (vitest/bun test/npm test/npx jest). The database-operator subagent does not run plugin tests; surface the parse-error to the operator." >&2
-    exit 2
-  fi
-fi
-
-exit 0

package/payload/platform/plugins/whatsapp-import/skills/whatsapp-import/references/conversation-and-messages.md

@@ -1,99 +0,0 @@
-# Reference: Conversation + Messages row schema
-
-This reference defines the `archiveType='whatsapp-export'` row + conversation block + participantNodeIds shapes that the [SKILL.md](../SKILL.md) passes to `mcp__memory__memory-archive-write`. The Cypher body is fixed server-side in [`platform/plugins/memory/mcp/src/tools/memory-archive-write.ts`](../../../../memory/mcp/src/tools/memory-archive-write.ts); the agent's responsibility ends at producing valid input.
-
-## Tool input shape
-
-```json
-{
-  "archiveType": "whatsapp-export",
-  "ownerNodeId": "<elementId of :AdminUser or :Person — operator who exported the chat>",
-  "sessionId": "<UUID — generated once per skill run>",
-  "conversation": {
-    "conversationId": "whatsapp-export:<sha256(file)>:<accountId>",
-    "archiveSourceFile": "<sha256(file)>",
-    "firstMessageAt": "2026-03-14T10:15:23Z",
-    "lastMessageAt": "2026-04-21T18:42:11Z",
-    "participantCount": 2,
-    "messageCount": 174
-  },
-  "participantNodeIds": ["<elemId-Joel>", "<elemId-Sarah>"],
-  "rows": [
-    {
-      "messageId": "whatsapp-export:<conversationId>:<lineHash>",
-      "conversationId": "<same as conversation.conversationId>",
-      "senderNodeId": "<elemId — operator-confirmed>",
-      "senderName": "Joel",
-      "dateSent": "2026-03-14T10:15:23Z",
-      "body": "Quick question about the deck —\ndo you have the v3 PDF anywhere?",
-      "sequenceIndex": 0
-    },
-    ...
-  ]
-}
-```
-
-## What the server does (informational, not the agent's responsibility)
-
-Each batch (max 500 rows) runs in one `executeWrite` transaction:
-
-1. **MERGE Conversation** — `(:Conversation:WhatsAppConversation {conversationId})`. ON CREATE stamps full provenance + scalar metadata (firstMessageAt, lastMessageAt, participantCount, messageCount, archiveSourceFile). ON MATCH refreshes the moving scalars (`lastMessageAt`, `messageCount`, `participantCount`) plus `lastImportedAt` / `lastImportedBySession` for re-import audit; createdBy* stamps stay frozen.
-2. **MATCH sender by elementId** — `WHERE elementId(sender) = row.senderNodeId`. The verifyParticipants preflight already confirmed every senderNodeId resolves; this MATCH never fails at runtime.
-3. **MERGE Message** — `(:Message:WhatsAppMessage {messageId})`. ON CREATE stamps provenance, body, dateSent, senderName (raw, audit-only), sequenceIndex.
-4. **MERGE PART_OF** — `(m)-[:PART_OF]->(c)`.
-5. **MERGE SENT** — `(sender)-[:SENT]->(m)`. Per-row, idempotent.
-6. **MERGE PARTICIPANT_IN** — `(sender)-[:PARTICIPANT_IN]->(c)`. Per-row, but rolls up across rows because MERGE on the same edge between the same pair is idempotent — a 200-message conversation with 2 participants ends with 2 PARTICIPANT_IN edges, not 200.
-
-After all batches, the **finalize** hook runs one additional `executeWrite` transaction:
-
-7. **MERGE NEXT chain** — `MATCH (m:Message)-[:PART_OF]->(c {conversationId})` ordered by `dateSent ASC, sequenceIndex ASC`, then UNWIND consecutive pairs, MERGE `(prev)-[:NEXT]->(next)`. Idempotent on MERGE — re-imports add only the new tail edges. Returns `nextEdges` count for the per-call log line.
-
-## Natural keys + provenance
-
-| Entity | Key | Provenance fields stamped |
-|---|---|---|
-| `:Conversation:WhatsAppConversation` | `conversationId` | `accountId, source='whatsapp', createdByAgent='whatsapp-import', createdBySource='whatsapp-import', createdBySession, createdAt=datetime(), scope='admin', agentType='admin', archiveSourceFile`. ON re-import, also: `lastImportedAt, lastImportedBySession`. |
-| `:Message:WhatsAppMessage` | `messageId` | Same provenance set + `conversationId, dateSent, body, senderName, sequenceIndex, scope='admin'`. |
-| `[:SENT]` | (sender, message) pair | `source='whatsapp', createdAt=datetime()`. |
-| `[:PARTICIPANT_IN]` | (sender, conversation) pair | `source='whatsapp', createdAt=datetime()`. |
-| `[:PART_OF]` | (message, conversation) pair | (no edge properties needed; the edge type is the signal). |
-| `[:NEXT]` | (prev message, next message) pair | `source='whatsapp', createdAt=datetime()`. |
-
-## Edges this reference does NOT mint
-
-- `(:AdminUser)-[:OWNS]->(:Conversation)` — explicitly NOT created. The exporter is metadata-on-Conversation provenance, not a graph relationship. A `:Conversation` is owned by its `accountId`, the same way other account-scoped nodes are. Adding an OWNS edge would duplicate property-based scope with edge-based scope (anti-pattern; see `feedback_account_scope_is_a_property.md`).
-- `(:Conversation)-[:OCCURRED_AT]->(:Date)` — date is a scalar property on the Conversation, not a separate node. Querying by date uses the property, not an edge traversal.
-- `(:Message)-[:HAS_BODY]->(:Text)` — the body is a property on the Message; no separate Text node.
-
-If a future query pattern reveals one of these is genuinely useful, file a separate task — never add them ad-hoc here.
-
-## Divergence from live-channel `persistMessage`
-
-The live `whatsapp` plugin's `persistMessage` in [`platform/ui/app/lib/neo4j-store.ts`](../../../../../ui/app/lib/neo4j-store.ts) holds a per-conversation lock when chaining NEXT — concurrent inbound messages to the same conversation would otherwise race to insert NEXT pointers. Bulk import does **not** need that lock because:
-
-1. The whole import runs in one `database-operator` turn, no concurrency.
-2. The finalize step runs ONE Cypher statement that scopes to a single `conversationId` and rebuilds the chain in `dateSent ASC` order. MERGE is idempotent; concurrent re-runs (which can't happen in one turn) would converge regardless.
-
-If a future change runs imports in parallel across conversations, that's still safe — each conversationId's NEXT chain is rebuilt independently. If two parallel imports targeted the same conversationId (operator scripting error), MERGE-on-NEXT idempotency saves the graph; the latest write wins on edge properties.
-
-## Counter shape returned to the agent
-
-```json
-{
-  "archiveType": "whatsapp-export",
-  "processedRows": 174,
-  "counters": {
-    "createdMessages": 174,
-    "relationshipsCreated": 524,
-    "labelsAdded": 348,
-    "nextEdgesProcessed": 173,
-    "nextEdgesCreated": 173
-  },
-  "errors": [],
-  "nextChainStatus": "ok"
-}
-```
-
-The skill displays the counts to the operator in chat and emits the `[whatsapp-import] file=...` log line using `processedRows`, `nextEdgesCreated`, and the elapsed time. The exact counter keys evolve (per-handler), so the skill should iterate the `counters` map rather than destructure specific names.
-
-When a batch errors, `errors[]` contains `{rowIndex, reason}`; `nextChainStatus` becomes `"partial"` (finalize still runs over whatever messages did land); the skill's chat output names the failed offset and the operator decides whether to re-import.

package/payload/platform/plugins/whatsapp-import/skills/whatsapp-import/references/insight-extraction.md

@@ -1,121 +0,0 @@
-# Reference: Insight extraction (pass 2)
-
-After the deterministic ingest completes, the [SKILL.md](../SKILL.md) runs a second pass that emits **first-class graph entities** capturing what the conversation is *about*. Insights are not summaries; they are typed nodes and edges the operator's queries can traverse.
-
-This pass runs INLINE in the database-operator specialist's own LLM turn — Sonnet — calling existing memory tools. There is no separate insight-extraction MCP tool. Reuse-over-invent: each observation maps onto an existing graph label or edge type wherever possible. `:Insight` is the last resort.
-
-## Reuse-over-invent — the six observation kinds
-
-| Kind | Maps to | Edge from | Edge to | Edge type | Notes |
-|---|---|---|---|---|---|
-| Third-party mention | `:Person` (existing) | `:Message` | `:Person` | `:MENTIONS` | Hallucination gate: see below. |
-| Recurring topic (≥3 mentions) | `:DefinedTerm` (existing) with `category:'topic'` | `:Conversation` | `:DefinedTerm` | `:DISCUSSES` (with `frequency` property) | Surface as a topic only if the term recurs ≥3 distinct messages. |
-| Expressed preference | `:Preference` (existing, see [schema.cypher:588](../../../../../neo4j/schema.cypher#L588-L595)) | `:Person` or `:AdminUser` | `:Preference` | `:HAS_PREFERENCE` + `(:Preference)-[:OBSERVED_IN]->(:Conversation)` | Preference text is a single observation, not a paragraph. |
-| Commitment / action item | `:Task` (existing) | `:Person` or `:AdminUser` | `:Task` | `:OWNS` | Set `dueDate` only when explicitly named ("by Friday", "next week"). Skip for vague "soon". |
-| Inter-person relationship | (matched `:Person` nodes) | `:Person` | `:Person` | `:RELATED_TO` (with `kind`, `evidenceMessageIds[]`) | Operator-confirmation gate before write — see below. |
-| Genuinely novel finding | `:Insight` (new label, last resort only) | `:Insight` | `:Message` | `:DERIVED_FROM` | Only when reuse-over-invent fails for every existing label. Self-rated `confidence` 0–1. |
-
-## Anti-hallucination gates — server-enforced (Task 805)
-
-The biggest risk in this pass is Sonnet writing edges to wrong-Person nodes. **Three gates protect the graph and they live in code, not prose.** `mcp__memory__whatsapp-export-insight-write` enforces all of them server-side; the agent cannot bypass them by skipping this section. This file describes how the gates work and what the agent must supply to pass them; the [tool source](../../../../memory/mcp/src/tools/whatsapp-export-insight-write.ts) is the canonical contract.
-
-`:MENTIONS` and `:RELATED_TO` writes ROUTE THROUGH this tool. Other observation kinds (`:Preference`, `:Task`, `:DefinedTerm`, `:Insight`) keep using `memory-write` because their adjacency is not subject to wrong-Person ambiguity.
-
-### Gate 1: candidate-overlap (re-run `memory-search` before every `:MENTIONS` write)
-
-For every `:MENTIONS` edge candidate the agent runs `memory-search(query=<mentioned-name>, labels=['Person','AdminUser'])` first, then calls `whatsapp-export-insight-write` with the resulting candidate `nodeId`s in `candidateElementIds`. **The server re-runs the same search and asserts at least one of those IDs appears in the live result.** Mismatch → `gate-rejected reason=candidate-mismatch`.
-
-- **0 hits** — the mentioned name doesn't exist in the graph. Don't write — the server would reject with `candidate-mismatch` because there is nothing to overlap. Do not auto-mint a `:Person` from a chat-mention alone.
-- **1+ hits** — supply the `nodeId`(s) the agent expects to be the referent. Server confirms by re-running the search.
-
-### Gate 2: first-name-only rejection (independent of hit count)
-
-Single-token names ("Sarah") without an explicit disambiguator are rejected at the tool boundary regardless of memory-search hit count — that one match might be the wrong Sarah. The rule lives in code: if `name` lacks whitespace AND lacks digits AND `disambiguatorOk` is not `true`, the tool returns `gate-rejected reason=first-name-only` and writes nothing.
-
-- The mention has a **disambiguator** (full name "Sarah Chen", phone, email, role context "Sarah at Acme") → set `disambiguatorOk: true` in the tool call, gate passes if Gate 1 also passes.
-- The mention is a **first-name only** without disambiguator → omit `disambiguatorOk` (or set `false`); the tool refuses the write. The agent surfaces this to the operator as ambiguous and asks for confirmation before retrying with `disambiguatorOk: true`.
-
-Surface format when the operator must disambiguate:
-
-```
-[whatsapp-import] mention-ambiguous name="Sarah" reason=first-name-only candidates=1 awaiting-operator-resolution
-```
-
-Followed by a chat prompt: `"Sarah" mentioned in message <messageId>. Found 1 :Person candidate: Sarah Chen (sarah@acme.com). Confirm? Yes / No / Pick another.`
-
-### Gate 3: `:RELATED_TO` requires `operatorConfirmed: true`
-
-When the second pass infers a relationship between two `:Person` nodes who both already exist in the graph (e.g., chat says "Joel and Sarah are working on Q3 together" → `(joel)-[:RELATED_TO {kind:'collaborator'}]->(sarah)`), the agent surfaces the inferred edge with both endpoints' names + supporting message excerpts. On operator yes, the agent calls `whatsapp-export-insight-write(kind='RELATED_TO', operatorConfirmed: true, evidenceMessageIds: [...])`. **Without `operatorConfirmed=true` the tool returns `gate-rejected reason=relationship-needs-confirm` and writes nothing.**
-
-The default for this gate is conservative — when in doubt, surface. False-positive RELATED_TO edges are graph noise; false-negative skips can be re-run.
-
-### Endpoint label + accountId checks (free with the tool)
-
-`whatsapp-export-insight-write` also rejects writes whose endpoints are missing, cross-account, or wrong-labelled (a MENTIONS source must be a :Message; the target must be :Person/:AdminUser; RELATED_TO requires both endpoints to be :Person/:AdminUser). These are tool-level invariants — the agent does not need to re-check them in skill code.
-
-## Chunking strategy
-
-For conversations with 100+ messages, chunk the input to the inline LLM turn at ~50 messages per chunk. The classifier processes each chunk independently; the skill aggregates observations across chunks before writing. Aggregation deduplicates (the same `:MENTIONS` edge would otherwise be proposed once per chunk that referenced the same person).
-
-Per-chunk processing emits one log line for grep-ability:
-
-```
-[whatsapp-import] insight-pass-chunk index=<i> messages=<n> mentions-proposed=<n> preferences-proposed=<n> tasks-proposed=<n>
-```
-
-After all chunks complete and observations are written, the per-pass summary log line fires:
-
-```
-[whatsapp-import] insight-pass model=sonnet chunks=<n> mentions=<n> preferences=<n> tasks=<n> observed-relationships=<n> novel-insights=<n> ms=<elapsed>
-```
-
-The numbers in the summary line are **edges actually written**, not edges proposed. Proposed-but-skipped (zero hits, ambiguous-skipped, operator-rejected) don't count.
-
-## When to mint `:Insight`
-
-Only when **every** of the six observation kinds above fails to fit. Examples that DO fit existing labels:
-
-- "I prefer dark roast" → `:Preference`
-- "Send the deck Friday" → `:Task` with `dueDate`
-- "Sarah keeps mentioning Q3 reporting" → `:DefinedTerm{category:'topic', name:'Q3 reporting'}` + `:DISCUSSES`
-- "Joel works with Sarah" → `:RELATED_TO`
-
-Examples that genuinely warrant `:Insight`:
-
-- "The team's morale dropped after the office move" — observation about a state change with no entity it cleanly attaches to.
-- "There's a recurring tension between sales and ops on lead-handoff timing" — meta-observation about an organisational dynamic.
-- "Joel's writing style shifts to formal English when discussing legal matters" — a behavioural pattern that doesn't fit `:Preference`.
-
-Each `:Insight` carries `summary` (one sentence, ≤200 chars), `kind` (free-text classifier label), `confidence` (Sonnet self-rated 0–1), plus the standard provenance stamps. `:DERIVED_FROM` edges link to the SPECIFIC messages that supported the insight (not the entire conversation).
-
-```cypher
-MERGE (i:Insight {insightId: $insightId})
-  ON CREATE SET
-    i.summary         = $summary,
-    i.kind            = $kind,
-    i.confidence      = $confidence,
-    i.accountId       = $accountId,
-    i.source          = 'whatsapp',
-    i.createdByAgent  = 'whatsapp-import',
-    i.createdBySession = $sessionId,
-    i.createdAt       = datetime(),
-    i.scope           = 'admin'
-WITH i, $messageIds AS mids
-UNWIND mids AS mid
-MATCH (m:Message {messageId: mid})
-MERGE (i)-[d:DERIVED_FROM]->(m)
-  ON CREATE SET d.createdAt = datetime()
-```
-
-This Cypher runs through `mcp__memory__memory-write` (single-node + relationships payload), not through `memory-archive-write`. The agent does not author this Cypher directly — the schema-aware writer translates the structured payload.
-
-## What pass 2 does NOT do
-
-- **Does not summarise the conversation.** A `:KnowledgeDocument` summary is the wrong shape per `feedback_archives_are_not_documents.md`.
-- **Does not score sentiment** per message. Sentiment is noise at the per-message level. Conversation-level emotional tone may show up as a `:Insight` if genuinely interesting.
-- **Does not aggregate across conversations.** Each export ingests in isolation. Cross-conversation patterns are a query-time concern using the `createdBySession` provenance index.
-- **Does not invent identifiers.** A `:MENTIONS` candidate without a `memory-search` hit is dropped, never auto-minted as a placeholder Person.
-
-## Operator-side discipline
-
-The operator may interrupt at any prompt during pass 2 and ask "skip the insight pass, just commit the messages." The skill obeys — no retroactive insight scan, no "let me extract a few quick ones first." Pass 1's Conversation+Messages is independent and complete on its own. The insight pass is opt-out at any prompt.