@rubytech/create-maxy 1.0.743 → 1.0.745

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/deployment.md

@@ -100,7 +100,8 @@ systemctl --user daemon-reload
 A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.
 
 - **Separate:** each brand has its own install folder (`~/maxy/`, `~/realagent/`), its own config folder (`~/.maxy/`, `~/.realagent/`), its own web port, its own Cloudflare tunnel state, its own edge systemd unit (`maxy-edge.service` vs `realagent-edge.service`), and by default its own Neo4j database (Maxy on bolt port 7687, Real Agent on 7688). Action runner units are transient and per-invocation, not per-brand, so no naming conflict is possible.
-- **Brand-isolated Neo4j (Task 787):** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so re-running another brand's installer never touches a peer brand's `neo4j-{brand}.service`.
+- **Brand-isolated Neo4j (Task 787):** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so peer brands running their own `neo4j-{brand}.service` are unaffected.
+- **Multi-brand-host caveat (Task 800):** on a host where the default brand keeps using the shared system `neo4j.service` per Task 659 V3 (e.g. a laptop running Maxy on default port 7687 alongside a branded build on a dedicated port), the Task 787 disable above kills the default brand's database when a branded installer runs. Symptom: default-brand admin server keeps running but bolt port 7687 has no listener; the branded install log contains `[neo4j] disabling system unit (brand-dedicated active on port <branded-port>)` immediately followed by `Stopping neo4j.service` in the systemd journal. Data on disk is intact (`disable` only removes the WantedBy symlink); recovery is `sudo systemctl enable neo4j && sudo systemctl start neo4j`. Task 800 adds a peer-brand guard so the disable is skipped when any `~/.<brand>/.env` pins `NEO4J_URI=bolt://localhost:7687`. Until Task 800 lands, repeat the recovery after each branded `create-{brand}` upgrade on a multi-brand host.
 - **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
 
 To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation:

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,20 @@ 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
+
+Two rules govern every raw Cypher write you author. They require LLM judgement — the structural gate cannot make these calls for you. Two further rules (provenance, orphan-prevention) are now structurally enforced by the shim and need no prose discipline.
+
+**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.
+
+**Structural enforcement (Task 797).** The shim auto-stamps `createdAt`, `createdByAgent`, `createdByTool`, `createdBySession` on every `CREATE`/`MERGE` alias before forwarding to Neo4j — you do not write these properties yourself. The shim runs the cypher inside a managed `executeWrite` and self-audits for unattached nodes before committing; if any node you created has zero edges in the same transaction, the entire transaction rolls back and you receive a structured error naming the orphan label(s). Treat the rollback as a hard failure (do not retry the same cypher); your job is to author atomic CREATE/MERGE-with-edge statements per Rule 1, not to write defensive WITH/MATCH/RETURN audits or hand-written SET clauses for `createdBy*` fields. The `[graph-cypher-write]` audit lines (`auto-stamp applied`, `accepted`, `orphan-rollback`, `orphan-warning`, `missing-provenance-warning`, `unknown-type-warning`) name what the structural enforcement saw — they are observation surfaces, not duties.
+
+The two 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.
+
 ### 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 +162,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.
 
 ---