@rubytech/create-maxy 1.0.743 → 1.0.744

package/payload/platform/lib/graph-write/src/audit.ts

@@ -0,0 +1,182 @@
+/**
+ * Post-write audit for the database-operator's raw `write_neo4j_cypher` tool
+ * (Task 796). Sibling to `[graph-write] accepted` for the wrapped writers
+ * (`memory-write`, `contact-create`, etc. — Task 673) — same module so the
+ * `[graph-*]` log family stays uniform across both write surfaces.
+ *
+ * Design posture:
+ *   - Static parse first. Pre-flight regex on the cypher text catches missing
+ *     provenance stamps and unknown edge types cheaply, no driver round-trip.
+ *   - Dynamic orphan detection is the caller's responsibility — the graph-mcp
+ *     shim runs the detection query against Neo4j after the upstream commits
+ *     and passes the resulting elementId list as `orphanIds`. Keeping the
+ *     module pure (no neo4j-driver import) makes it unit-testable without a
+ *     live database.
+ *   - Audit is observational. Warnings never block the write. The
+ *     prompt-level Graph Stewardship Doctrine in
+ *     [database-operator.md](../../../templates/specialists/agents/database-operator.md)
+ *     names the discipline; the audit is the verification stream.
+ *
+ * String literals are stripped before pattern checks so that property values
+ * containing words like `'createdByAgent in my bio'` cannot trip a false
+ * provenance count, and edge-like patterns inside quoted strings cannot
+ * trip a false unknown-type warning. The regex shape is duplicated from
+ * [cypher-validate.ts](../../graph-mcp/src/cypher-validate.ts) intentionally:
+ * graph-write does not depend on graph-mcp, and a one-line regex helper
+ * doesn't justify a third package. Drift in either copy is a regression
+ * surfaced by both the validator tests and the audit tests.
+ */
+
+export interface SchemaSnapshot {
+  readonly labels: ReadonlySet<string>;
+  readonly relationshipTypes: ReadonlySet<string>;
+}
+
+export interface CypherWriteAuditInput {
+  cypher: string;
+  schema: SchemaSnapshot;
+  agentName: string;
+  sessionId: string;
+  /** Counter from upstream response — drives missing-provenance arithmetic. */
+  nodesCreated: number;
+  /** Counter from upstream response — informational only. */
+  relsCreated: number;
+  /**
+   * elementIds of nodes the post-write orphan query identified. Caller scopes
+   * the query to (createdBySession, createdAt >= writeStartTimestamp) so this
+   * list cannot include nodes from prior writes in the same session. Empty
+   * array = no orphans (or no scope to check).
+   */
+  orphanIds: string[];
+}
+
+export type AuditWarning =
+  | { kind: "orphan-warning"; orphanIds: string[] }
+  | { kind: "unknown-type-warning"; type: string }
+  | { kind: "missing-provenance-warning"; created: number; stamped: number };
+
+export type AuditLine =
+  | {
+      kind: "accepted";
+      cypherPrefix: string;
+      nodesCreated: number;
+      relsCreated: number;
+      agentName: string;
+      sessionId: string;
+    }
+  | { kind: "orphan-warning"; cypherPrefix: string; orphanIds: string[] }
+  | { kind: "unknown-type-warning"; cypherPrefix: string; type: string }
+  | {
+      kind: "missing-provenance-warning";
+      cypherPrefix: string;
+      created: number;
+      stamped: number;
+    };
+
+// Mirrors cypher-validate's pattern. Captures TYPE(|TYPE)* alternation; the
+// audit splits on `|` to enumerate every referenced type.
+const EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[^\]]*?\]/g;
+
+// Counts CREATE (n:Label) and MERGE (n:Label) statements that introduce a
+// node. The trailing `[A-Z]` requires at least one label (so `CREATE INDEX`
+// and bare `CREATE (a)-[:R]->(b)` shapes don't trip this — bare patterns
+// reference a previously-MATCHed alias and don't introduce new nodes).
+const CREATE_OR_MERGE_NODE = /\b(?:CREATE|MERGE)\s*\(\s*[A-Za-z_][A-Za-z0-9_]*\s*:\s*[A-Z]/g;
+
+// Stamp tokens — at least one of these MUST appear per created node for the
+// write to satisfy provenance discipline. The audit counts occurrences;
+// stamp-count >= node-count is the pass criterion.
+const PROVENANCE_TOKEN = /\bcreatedBy(?:Agent|Tool|Session|Source)\b/g;
+
+function stripStringLiterals(cypher: string): string {
+  // Identical regex to cypher-validate.ts. Replaces single- and double-
+  // quoted literals with empty quotes so e.g. 'CREATE (n:Person)' inside a
+  // property value cannot inflate the create-count.
+  return cypher.replace(/'[^']*'|"[^"]*"/g, '""');
+}
+
+function extractEdgeTypes(cleaned: string): Set<string> {
+  const out = new Set<string>();
+  // Use String.matchAll for stateless iteration — no shared regex lastIndex.
+  for (const m of cleaned.matchAll(EDGE_PATTERN)) {
+    for (const t of m[1].split("|")) {
+      const clean = t.trim();
+      if (clean) out.add(clean);
+    }
+  }
+  return out;
+}
+
+function countCreateOrMergeNodes(cleaned: string): number {
+  const matches = cleaned.match(CREATE_OR_MERGE_NODE);
+  return matches ? matches.length : 0;
+}
+
+function countProvenanceStamps(cleaned: string): number {
+  const matches = cleaned.match(PROVENANCE_TOKEN);
+  return matches ? matches.length : 0;
+}
+
+export function auditCypherWrite(input: CypherWriteAuditInput): AuditWarning[] {
+  const warnings: AuditWarning[] = [];
+  const cleaned = stripStringLiterals(input.cypher);
+
+  // 1. Unknown edge type — cypher names a type not in the live ontology.
+  //    Enumerate every referenced type; emit one warning per unknown.
+  const referencedTypes = extractEdgeTypes(cleaned);
+  for (const t of referencedTypes) {
+    if (!input.schema.relationshipTypes.has(t)) {
+      warnings.push({ kind: "unknown-type-warning", type: t });
+    }
+  }
+
+  // 2. Missing provenance — count CREATE/MERGE-with-label statements vs
+  //    `createdBy*` token occurrences. Stamps may live in inline maps
+  //    (`{createdByAgent: $agent}`) or SET clauses; both shapes contribute
+  //    to the token count. The arithmetic is precision-imprecise — a
+  //    multi-stamp single CREATE inflates `stamped`, a multi-CREATE single
+  //    SET undercounts — but the directional signal (zero stamps for many
+  //    creates) catches the failure mode this audit exists to surface.
+  //
+  //    nodesCreated=0 short-circuits the check: the upstream counter is
+  //    ground truth for whether any node was actually persisted. An
+  //    idempotent MERGE that matched an existing node has a static
+  //    create-count of 1 but contributed no new node — no provenance was
+  //    needed, and warning here would be a false positive.
+  if (input.nodesCreated > 0) {
+    const createOrMergeNodes = countCreateOrMergeNodes(cleaned);
+    if (createOrMergeNodes > 0) {
+      const stamps = countProvenanceStamps(cleaned);
+      if (stamps < createOrMergeNodes) {
+        warnings.push({
+          kind: "missing-provenance-warning",
+          created: createOrMergeNodes,
+          stamped: stamps,
+        });
+      }
+    }
+  }
+
+  // 3. Orphans — caller-supplied. The dynamic detection happens at the
+  //    graph-mcp shim layer (which has the Neo4j driver); the audit module
+  //    only renders the warning shape.
+  if (input.orphanIds.length > 0) {
+    warnings.push({ kind: "orphan-warning", orphanIds: input.orphanIds });
+  }
+
+  return warnings;
+}
+
+export function formatAuditLine(line: AuditLine): string {
+  const prefixField = `query="${line.cypherPrefix.replace(/"/g, "'")}"`;
+  switch (line.kind) {
+    case "accepted":
+      return `[graph-cypher-write] accepted ${prefixField} nodesCreated=${line.nodesCreated} relsCreated=${line.relsCreated} agentName=${line.agentName} sessionId=${line.sessionId}`;
+    case "orphan-warning":
+      return `[graph-cypher-write] orphan-warning ${prefixField} orphanIds=${line.orphanIds.join(",")}`;
+    case "unknown-type-warning":
+      return `[graph-cypher-write] unknown-type-warning ${prefixField} type=${line.type}`;
+    case "missing-provenance-warning":
+      return `[graph-cypher-write] missing-provenance-warning ${prefixField} created=${line.created} stamped=${line.stamped}`;
+  }
+}

package/payload/platform/lib/graph-write/src/index.ts

@@ -1,3 +1,8 @@
+// Task 796: re-export the post-write audit so consumers (graph-mcp shim)
+// import from the same package as `writeNodeWithEdges`. Keeps the
+// `[graph-*]` log family colocated.
+export * from "./audit.js";
+
 /**
  * Write doctrine (Task 673): a node without at least one adjacency is noise,
  * not knowledge. `writeNodeWithEdges` is the single primitive every graph

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "plugins/*/mcp"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

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

@@ -106,6 +106,8 @@ Every new node in {{productName}}'s graph is created with at least one connectio
 
 Every node also carries a provenance stamp — which agent wrote it, in which session, via which tool. You never see these fields, but they are how operators trace unusual growth back to the code path that produced it, and why your graph stays clean over time.
 
+**Two write surfaces, one substrate.** General agents write through schema-aware helpers — {{productName}} can record a new contact, a new commitment, a new preference without ever typing a database query, and the helper enforces the connection-and-provenance rule above structurally. The graph-steward role (the specialist {{productName}} dispatches when you ask for graph hygiene — "merge those two duplicate contacts," "wire those four tasks to the meeting," "rename the legacy label across the graph") additionally has a raw Cypher write tool for the multi-step operations the helpers cannot express. The steward role internalises the same connection-and-provenance discipline in its prompt; a post-write audit emits a warning on every breach so the same rules apply to both surfaces. Both paths feed the same hourly orphan trend and the same forensic provenance fields — read-side, you cannot tell the two apart, and that is the point.
+
 ## Privacy
 
 All memory is stored on your local Raspberry Pi. The Neo4j database never leaves your network. {{productName}} does not sync memory to any cloud service or third party.

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

@@ -121,6 +121,22 @@ If the initial Cloudflare login fails during setup, {{productName}} will fall ba
 
 ---
 
+## "Bad Gateway" or holding page during an upgrade
+
+Task 795 — `maxy-edge.service` (always-on front door) classifies upstream errors and serves a brand-aware response. There are two distinct user-visible shapes; the right one depends on what failed.
+
+**Branded holding page ("{{productName}} is starting") for ~10 s during an upgrade — this is expected and self-healing.** The edge process binds the public port immediately, but `maxy.service` (the upstream UI) takes ~10 s after restart to apply the neo4j schema and mount its 11 routes. Any browser navigation that lands during that window gets a self-contained HTML holding page that polls `/api/health` and reloads automatically once the upstream binds. No operator action required. The diagnostic line in `~/.maxy/logs/edge.log` is `[edge] upstream http error path=… err=connect ECONNREFUSED 127.0.0.1:<UPSTREAM_PORT> err-class=econnrefused-coldstart upstream=…` and disappears as soon as upstream binds.
+
+**Branded plain-text 502 ("Bad Gateway ({{productName}} unavailable)") — real upstream failure, not cold-start.** Any error class other than `ECONNREFUSED` (timeouts, resets, host-unreachable) returns the existing 502 path. The diagnostic line carries `err-class=other`. Read the log with `tail -200 ~/.maxy/logs/edge.log | rg 'err-class=other'` and check `~/.maxy/logs/server.log` for upstream stack traces — the upstream itself is the source.
+
+**Continuous `err-class=econnrefused-coldstart` for >30 s past the last `[edge] listening` line** indicates the upstream never binds — the upgrade or boot has stalled. Recover via `sudo systemctl --user status maxy.service` and check the action runner log per the next section. Permanent-failure UI escalation (turning the holding page into an error after N seconds) is intentionally deferred.
+
+**The literal string `maxy-ui` should never appear in `edge.log` or in any user-visible 502 body**, regardless of brand. If it does, the edge is running pre-Task-795 code — re-bundle and re-publish.
+
+**Verifying the holding page locally:** `curl -sS -H 'Accept: text/html' http://127.0.0.1:<EDGE_PORT>/` while `maxy.service` is stopped should return HTML containing the brand `productName`. The `Accept: text/html` header is required — non-html clients (default `curl`, `fetch()`, XHR) get the branded plain-text 502 instead, so the holding page's own `/api/health` polls don't break themselves during cold-start.
+
+---
+
 ## Action runner — upgrade or Cloudflare setup appears stuck
 
 Task 664 replaced the ttyd/xterm admin terminal with a detached action runner. Upgrades and Cloudflare setup now run under transient `systemd-run --user` units whose stdout+stderr land in a persisted per-action log, streamed to the browser via SSE. Task 666 moved the four routes that serve the modal (`/api/admin/actions/*`, `/api/admin/version`) onto `maxy-edge.service`, so the log panel's stream survives a mid-run restart of `maxy.service` without reconnecting.

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-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__admin__file-attach, mcp__admin__plugin-read
 ---
 
 # Database Operator
@@ -124,6 +124,39 @@ Future CRM-type seed plugins (HubSpot, Salesforce, Pipedrive, iCloud contacts, G
 
 When the admin delegates a graph operation — pruning, dedup, edge addition, label normalisation, schema-drift tidy — follow this discipline.
 
+You wield two write surfaces. Wrapped writers (`memory-write`, `memory-update`, `memory-delete`, `memory-find-candidates`, `contact-create`, etc.) are schema-aware helpers that enforce orphan-prevention and provenance structurally — the right surface for single-node creates, contact ingestion, soft-delete sweeps. Raw Cypher via `mcp__graph__maxy-graph-write_neo4j_cypher` is the right surface for the writes wrapped helpers cannot express: edges between two pre-existing nodes, multi-statement hygiene (`DETACH DELETE` orphans, `apoc.refactor.mergeNodes` duplicates, `REMOVE :OldLabel SET :NewLabel`), and any operation that scopes a transaction across multiple matched node sets. The graph is the account's knowledge substrate; raw Cypher is power tooling for the role responsible for that substrate.
+
+### Graph stewardship doctrine — raw Cypher writes
+
+Four rules govern every raw Cypher write. The wrapped writers enforce these structurally for general agents; you internalise them because your write surface has no equivalent gate. The post-write `[graph-cypher-write]` audit emits a warning per discipline breach (`unknown-type-warning`, `missing-provenance-warning`, `orphan-warning`), but the audit is observational — discipline is yours, not the audit's.
+
+**1. Every node has ≥1 typed edge in the same transaction.** A bare `CREATE (n:Person {name: 'Ian'})` is data, not knowledge — retrieval finds the node but it carries no context. Anchor every node creation to the relationship that explains it: `MATCH (anchor) WHERE … CREATE (anchor)-[:TYPE]->(n:Label {…})`, or `MERGE` the node and its edge in the same statement. *Why:* a graph that accumulates islands defeats relationship-traversal queries — the value of the graph is in the edges, not the rows.
+
+**2. Every edge type is in the live ontology.** Inventing types fragments retrieval — `KNOWS` ≠ `knows` ≠ `HAS_KNOWN`. Call `mcp__graph__maxy-graph-get_neo4j_schema` before authoring any write whose edge type you are not certain about; if no fitting type exists, stop and ask the admin agent for ontology guidance — never coin a synonym. *Why:* edge typology compounds over time. A synonym today blocks every future query that expected the canonical type, and the only fix is a label-rewrite Cypher pass that touches the same edge from both sides.
+
+**3. Every write carries provenance.** Stamp the same flattened fields the wrapped writers stamp on every node and every relationship the transaction creates:
+
+```cypher
+SET n.createdAt = datetime(),
+    n.createdByAgent = 'database-operator',
+    n.createdByTool = 'graph-cypher-write',
+    n.createdBySession = $sessionId
+```
+
+Apply the same SET to relationships (`SET r....`). The session id is the conversation correlation key; the admin dispatch passes it as a parameter. *Why:* a write without provenance cannot be attributed back to the dispatch that produced it. The post-write audit emits `missing-provenance-warning created=<n> stamped=<m>` when the static parser counts CREATE/MERGE statements that exceed the count of `createdBy*` tokens — this is the directional signal, not a structural gate.
+
+**4. Orphan prevention is your first-class duty.** Multi-statement transactions self-audit before completing. Capture the elementIds of every node the transaction creates, then run the orphan check inline:
+
+```cypher
+WITH collect(elementId(n)) AS writtenIds
+MATCH (n) WHERE elementId(n) IN writtenIds AND NOT (n)--()
+RETURN count(n) AS orphans
+```
+
+If `orphans > 0`, do not commit a "fix it up later" transaction — roll back, anchor the unattached nodes to their semantic parent, and re-run. *Why:* the hourly `[graph-health] orphans total=<N>` signal is your scorecard. A transaction that leaves orphans is a regression the role owns; the operator's stewardship is the primary defense against landfill.
+
+The four rules together replace the LOUD-FAIL improvisation pattern that prior versions of this prompt prescribed when a wrapped writer lacked an edge-between-existing-nodes path. You no longer loud-fail on missing graph-write tools — you have them. You loud-fail on credentials, on out-of-surface tools (a skill prescribing a non-graph MCP token you do not hold), and on dispatched skills whose prerequisites are unmet — exactly as the LOUD-FAIL prerogative names. Discipline failures within the graph-write surface produce audit warnings, not blockers; the role's prompt-internalised doctrine is the contract.
+
 ### Before writing any Cypher
 
 1. **Consult the SCHEMA block.** Your MCP tool set includes `maxy-graph-get_neo4j_schema` for live schema snapshots. Call it before authoring any write Cypher you are not certain about. The upstream cypher-mcp validator rejects writes with unknown labels or edges; catch the mismatch upfront, not at the rejection.
@@ -148,14 +181,14 @@ When two nodes represent the same real-world entity (two `:Person` rows for the
 
 1. Read both via `memory-search` or direct `maxy-graph-read_neo4j_cypher`.
 2. Decide which is the survivor (usually the older `createdAt`, or the one with richer properties). State the choice.
-3. Copy missing properties from the duplicate onto the survivor via `memory-update`.
-4. Re-point every edge from the duplicate onto the survivor via `memory-update` (or a targeted `memory-write` with the new relationship and a follow-up `memory-delete` of the old one).
-5. `memory-delete` the duplicate with a single-node call — the operator named this merge explicitly, no filter-token needed.
+3. Property reconciliation: `memory-update` for property copies, or `write_neo4j_cypher` with `apoc.refactor.mergeNodes([survivor, duplicate])` when the merge is multi-edge (apoc reparents every relationship onto the survivor in one transaction). Stamp `mergedAt`, `mergedFromAgent`, `mergedFromSession` per the stewardship doctrine.
+4. For property-only merges that leave edges unchanged, follow up with `memory-update` on the survivor and `memory-delete` on the duplicate. The duplicate delete is single-node, no filter-token needed (the operator named this merge explicitly).
 
 ### Edge addition, label normalisation, prune-denylist
 
-- **Edge addition** — `memory-write` with a `relationships` payload naming the exact edge type from the schema. Validator rejects unknown edge types; re-read the schema before authoring.
-- **Label normalisation** — call `memory-update` with the new label set. Never rename a label across the whole graph without a named owner asking for it — label renames are schema changes.
+- **Edge addition between two existing nodes** — raw Cypher via `mcp__graph__maxy-graph-write_neo4j_cypher`: `MATCH (a:LabelA {…}), (b:LabelB {…}) MERGE (a)-[r:TYPE]->(b) SET r.createdAt = datetime(), r.createdByAgent = $agent, r.createdByTool = 'graph-cypher-write', r.createdBySession = $sessionId`. The wrapped `memory-write` requires a new node payload — for edge-only writes, raw Cypher is the surface.
+- **Edge addition that creates a new node** — `memory-write` with a `relationships` payload naming the exact edge type. Validator rejects unknown edge types structurally; re-read the schema before authoring.
+- **Label normalisation** — `write_neo4j_cypher` with `MATCH (n:OldLabel) WHERE … REMOVE n:OldLabel SET n:NewLabel SET n.relabelledAt = datetime(), n.relabelledByAgent = $agent`. Bulk renames are schema changes — always confirm the owner / scope with the admin before executing across the whole graph.
 - **Prune denylist** — when the operator wants to preserve specific nodes from future prune passes (current or scheduled-autonomous), use `graph-prune-denylist-add/remove/list` to manage the registry.
 
 ---