@rubytech/create-maxy 1.0.711 → 1.0.712

package/dist/index.js

@@ -125,7 +125,15 @@ function shell(command, args, options) {
     const cmd = options?.sudo ? "sudo" : command;
     const cmdArgs = options?.sudo ? [command, ...args] : args;
     const start = Date.now();
-    logFile(`> ${cmd} ${cmdArgs.join(" ")}${options?.cwd ? ` [cwd: ${options.cwd}]` : ""}`);
+    // Redaction (Task 744): callers handling secrets pass redact: true so the
+    // wrapper records the command name only, not the secret-bearing args. The
+    // child process still receives the real args via spawnSync below; only the
+    // install log line is sanitised. The grep-able audit shape stays:
+    //   > sudo neo4j-admin dbms set-initial-password [REDACTED]
+    const loggedArgs = options?.redact
+        ? `${cmdArgs.slice(0, options?.sudo ? 4 : 3).join(" ")} [REDACTED]`
+        : cmdArgs.join(" ");
+    logFile(`> ${cmd} ${loggedArgs}${options?.cwd ? ` [cwd: ${options.cwd}]` : ""}`);
     const result = spawnSync(cmd, cmdArgs, {
         stdio: "inherit",
         timeout: options?.timeout ?? 300_000,
@@ -690,7 +698,7 @@ function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j") {
     }
     else {
         console.log("  [privileged] neo4j-admin dbms");
-        shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true });
+        shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true, redact: true });
     }
     console.log("  [privileged] systemctl start");
     shell("systemctl", ["start", serviceName], { sudo: true });
@@ -707,6 +715,29 @@ function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j") {
     }
     return password;
 }
+/**
+ * Task 744 — scrub plaintext neo4j passwords from pre-fix install-*.log files.
+ * Calls platform/scripts/redact-install-logs.sh against the installer's LOG_DIR.
+ * The script is idempotent; re-running on clean logs is a no-op. Failures here
+ * are non-fatal — credential redaction is best-effort cleanup, not a blocker
+ * for installation.
+ */
+function redactInstallLogs() {
+    const script = resolve(INSTALL_DIR, "platform/scripts/redact-install-logs.sh");
+    if (!existsSync(script)) {
+        logFile("[redact-install-logs] script not found at " + script + " — skipping");
+        return;
+    }
+    const r = spawnSync("bash", [script, "--dir", LOG_DIR], {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 30_000,
+    });
+    if (r.stdout)
+        logFile(r.stdout.trim());
+    if (r.status !== 0 && r.stderr)
+        logFile("[redact-install-logs] WARN " + r.stderr.trim());
+}
 /** Check Neo4j has a working password. Called AFTER deploy so config is in place. */
 function ensureNeo4jPassword() {
     const passwordFile = join(INSTALL_DIR, "platform/config/.neo4j-password");
@@ -794,7 +825,7 @@ function installNeo4j() {
     mkdirSync(configDir, { recursive: true });
     writeFileSync(join(configDir, ".neo4j-password"), password, { mode: 0o600 });
     console.log("  [privileged] neo4j-admin dbms");
-    shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true });
+    shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true, redact: true });
     console.log("  [privileged] systemctl enable");
     shell("systemctl", ["enable", "neo4j"], { sudo: true });
     console.log("  [privileged] systemctl start");
@@ -2148,6 +2179,10 @@ try {
     installCloudflared();
     installWhisperCpp();
     deployPayload(); // Must happen before ensureNeo4jPassword — restores config backup
+    // Task 744: scrub plaintext neo4j passwords from any pre-fix install-*.log.
+    // Idempotent — re-running on already-redacted logs is a no-op. Runs after
+    // payload deploy so the bundled redact-install-logs.sh is on disk.
+    redactInstallLogs();
     ensureNeo4jPassword(); // Now config/.neo4j-password is available if it existed before
     provisionRemoteSessionSecret(); // Task 653: shared HMAC key readable by maxy-edge + maxy-ui
     buildPlatform();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.711",
+  "version": "1.0.712",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"
@@ -10,7 +10,7 @@
     "build": "tsc",
     "bundle": "node scripts/bundle.js",
     "test": "npm run build && node --test 'dist/__tests__/*.test.js'",
-    "prepublishOnly": "node ../../platform/ui/scripts/check-route-wiring.mjs && node ../../platform/ui/scripts/check-edge-admin-routes.mjs && npm run build && node --test 'dist/__tests__/*.test.js' && chmod +x dist/index.js && npm run bundle && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
+    "prepublishOnly": "bash ../../platform/scripts/verify-skill-tool-surface.sh && node ../../platform/ui/scripts/check-route-wiring.mjs && node ../../platform/ui/scripts/check-edge-admin-routes.mjs && npm run build && node --test 'dist/__tests__/*.test.js' && chmod +x dist/index.js && npm run bundle && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
   },
   "files": [
     "dist",

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

@@ -4,6 +4,7 @@ description: "Import a LinkedIn Basic Data Export into the Maxy Neo4j graph. Ski
 tools: []
 always: false
 embed: false
+specialist: database-operator
 metadata: {"platform":{"optional":true,"pluginKey":"linkedin-import"}}
 ---
 

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

@@ -42,7 +42,7 @@ When the owner is an external Person (non-operator archive), the anchor is the c
 
 ## Invariants
 
-1. **Schema first.** The LinkedIn additions (`person_linkedin_url` index, `:Credential` constraint) live in [`platform/neo4j/schema.cypher`](../../../../neo4j/schema.cypher) and are applied by `platform/scripts/seed-neo4j.sh` on every install / upgrade. If running against a Neo4j that hasn't been reseeded since shipping, pipe `schema.cypher` into `cypher-shell` once before starting — every statement is `IF NOT EXISTS`.
+1. **Schema first.** The LinkedIn additions (`person_linkedin_url` index, `:Credential` constraint) live in [`platform/neo4j/schema.cypher`](../../../../neo4j/schema.cypher) and are applied by `platform/scripts/seed-neo4j.sh` on every install / upgrade. The skill assumes the schema has been seeded; it does not bootstrap schema itself. If a constraint or index is missing, the operator re-runs `seed-neo4j.sh` from the installer — schema-bootstrap is installer-side, never agent-side.
 2. **Owner confirmed first.** No reference runs until `$ownerUserId` (or `$ownerPersonId`) is persisted and echo-confirmed. The reference set is parameterised — no hard-coded owner.
 3. **Natural edges only.** Every edge written is one the CSV actually expresses. `Connections.csv` encodes "I am connected on LinkedIn to this person" — that becomes `CONNECTED_ON_LINKEDIN`. No synthetic attach-to-owner pattern bolted onto rows that don't describe a relationship to the owner.
 4. **Reuse Maxy labels.** Schema-extension is last resort. The LinkedIn set maps onto existing labels wherever semantics align:
@@ -60,10 +60,31 @@ When the owner is an external Person (non-operator archive), the anchor is the c
 
 ## Execution model
 
-1. Confirm `schema.cypher` is applied (one-liner: `cypher-shell ... < platform/neo4j/schema.cypher`; safe to re-run).
-2. Run the owner-confirmation flow, persist `$ownerUserId` / `$ownerPersonId`.
-3. For each file the operator approves, load its reference, parse the CSV, batch rows (default 500 per tx), execute the reference's Cypher with `$rows` + owner parameter.
-4. After each file emit `[linkedin-import] file=<name> rows=<n> created=<n> matched=<n> ms=<elapsed>`.
+1. Run the owner-confirmation flow, persist `$ownerUserId` / `$ownerPersonId`. The owner identity resolves to a single `ownerNodeId` (elementId of the AdminUser or external Person) used in every write call.
+2. For each file the operator approves, load its reference, parse the CSV into typed `rows[]` matching the reference's row schema.
+3. **Selective-ingest gate.** Before invoking any write tool, check the parsed row count against the reference's `selectiveIngestThreshold`. If the count exceeds the threshold, pause and ask the operator to filter the import along the natural axes named in the reference (for `Connections.csv`: Company, Position, Connected On). Apply the filter to `rows[]` before continuing. Compress on write, never after — a 5,000-row blanket import is a landfill, a 200-row filtered import is signal. See [§Selective-ingest](#selective-ingest-threshold-bulk-archives).
+4. Invoke the deterministic write tool the reference names. For all archive references this is `mcp__memory__memory-archive-write` with `{archiveType, ownerNodeId, rows}` — the Cypher body is fixed server-side per `archiveType`, so the agent supplies parsed rows, never Cypher. The tool batches rows at 500 per transaction internally.
+5. After each file emit `[linkedin-import] file=<name> rows=<n> created=<n> matched=<n> ms=<elapsed>` using the counters returned by the write tool.
+
+**Doctrine:** raw Cypher and `cypher-shell` invocations are forbidden in this skill and its references. Writes route through `mcp__memory__memory-archive-write` (bulk archives) or `mcp__memory__memory-write` / `mcp__memory__memory-update` (single-node enrichments like `profile.md`). If a CSV needs a write shape no current MCP tool supports, file a task to extend `memory-archive-write` with a new `archiveType` handler — never improvise via Bash. See [database-operator's LOUD-FAIL prerogative](../../../../templates/specialists/agents/database-operator.md#prerogatives).
+
+## Selective-ingest threshold (bulk archives)
+
+A LinkedIn export typically contains 3,000–10,000 connections. Writing all of them in one shot defeats compression-on-write — most rows will never be queried, and the noise compounds with every subsequent ingest. The skill compresses by interrogating the operator before bulk writes.
+
+**Threshold:** when a parsed reference's `rows[]` exceeds **100 rows**, pause and ask the operator to filter along the reference's natural axes before invoking the write tool.
+
+For `Connections.csv` the natural filter axes are:
+
+- **Company** — "only people at LargeCorp", "only Female Founders Fund alumni"
+- **Position** — "only Partners", "only Engineering Managers"
+- **Connected On** (date range) — "only my last two years", "since 2024-01-01"
+
+The operator picks one axis or a combination. The agent applies the filter to `rows[]` and writes only the filtered subset.
+
+**Re-importing is idempotent.** Coming back later with a wider filter (`"add anyone at LargeCorp"`, `"include 2022 too"`) hits the same `linkedinUrl` natural key — existing `:Person` nodes are matched and updated; only the new-only delta is created. The operator can grow the slice over time without dedup work.
+
+**Why the threshold lives in the skill, not the server.** Different archive types have different "interesting" thresholds — 100 LinkedIn connections is a lot; 100 LinkedIn skills is small. The MCP tool accepts whatever rows are passed; the conversational gate is the skill's responsibility.
 
 ## File roster
 

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/references/connections.md

@@ -31,7 +31,7 @@ The real column header is **line 4**. Either skip the first three lines before p
 | Position | `[:WORKS_FOR].title` |
 | Connected On | `[:CONNECTED_ON_LINKEDIN].connectedOn` (ISO 8601) |
 
-LinkedIn only emits email for connections who opted in, so most rows have a blank email. Write `email` only when non-empty — avoids colliding with `person_email_unique` on empty strings.
+LinkedIn only emits email for connections who opted in, so most rows have a blank email. The MCP tool writes `email` only when non-empty — avoids colliding with `person_email_unique` on empty strings.
 
 ## Natural keys
 
@@ -42,81 +42,52 @@ LinkedIn only emits email for connections who opted in, so most rows have a blan
 
 ## Anchor
 
-```cypher
-MATCH (owner:AdminUser {userId: $ownerUserId})
-```
+Resolved at skill start via the owner-confirmation flow. The owner is either an `:AdminUser` (the operator's own archive — the common case) or a confirmed `:Person` (an external archive ingested for reference). Both flow through the same write tool — `memory-archive-write` matches by `elementId(owner)` and accepts either label set.
 
-Resolved at skill start via the owner-confirmation flow. The owner could instead be a `:Person` if the operator confirmed an external-Person anchor; in that case swap the MATCH to `MATCH (owner:Person) WHERE elementId(owner) = $ownerPersonId` and keep the rest identical — the edges are the same regardless.
+## Selective-ingest threshold
 
-## Cypher
+**100 rows.** When the parsed `rows[]` count exceeds this, the skill pauses before the write call and asks the operator to filter by Company, Position, or Connected On range. See [SKILL.md § Selective-ingest threshold](../SKILL.md#selective-ingest-threshold-bulk-archives) for the doctrine. The MCP tool accepts whatever rows are passed; this gate is conversational.
 
-```cypher
-// Parameters:
-//   $ownerUserId — AdminUser.userId of the confirmed archive owner
-//   $accountId   — Organization accountId scope for this import
-//   $sessionId   — UUID generated once per skill run
-//   $rows        — array of objects:
-//     {
-//       givenName:   "Dee",
-//       familyName:  "Odus",
-//       linkedinUrl: "https://www.linkedin.com/in/deeodus",
-//       email:       null | "someone@example.com",
-//       company:     null | "Female Founders Fund",
-//       title:       null | "Partner",
-//       connectedOn: "2026-04-23"   // ISO 8601, parsed from "23 Apr 2026"
-//     }
-
-MATCH (owner:AdminUser {userId: $ownerUserId})
-UNWIND $rows AS row
-
-// 1. Upsert the connection Person. linkedinUrl is the natural key.
-MERGE (p:Person {linkedinUrl: row.linkedinUrl})
-  ON CREATE SET
-    p.accountId       = $accountId,
-    p.source          = 'linkedin',
-    p.createdByAgent  = 'linkedin-import',
-    p.createdBySource = 'linkedin-import',
-    p.createdBySession= $sessionId,
-    p.createdAt       = datetime()
-SET
-    p.givenName = row.givenName,
-    p.familyName= row.familyName,
-    p.name      = trim(coalesce(row.givenName,'') + ' ' + coalesce(row.familyName,''))
-
-// 1a. Email only when non-empty (avoids person_email_unique collisions on empty strings)
-FOREACH (_ IN CASE WHEN row.email IS NOT NULL AND row.email <> '' THEN [1] ELSE [] END |
-  SET p.email = row.email
-)
-
-// 2. The CONNECTED_ON_LINKEDIN edge is what this CSV means.
-MERGE (owner)-[c:CONNECTED_ON_LINKEDIN]->(p)
-  ON CREATE SET
-    c.connectedOn = date(row.connectedOn),
-    c.source      = 'linkedin',
-    c.createdAt   = datetime()
-
-// 3. If the row names a current employer, create the Organization and WORKS_FOR edge.
-//    If no company is named, this block no-ops — we do not synthesise one.
-WITH p, row
-WHERE row.company IS NOT NULL AND row.company <> ''
-MERGE (o:Organization {accountId: $accountId, name: trim(row.company)})
-  ON CREATE SET
-    o.source          = 'linkedin',
-    o.createdByAgent  = 'linkedin-import',
-    o.createdBySource = 'linkedin-import',
-    o.createdBySession= $sessionId,
-    o.createdAt       = datetime()
-
-MERGE (p)-[w:WORKS_FOR]->(o)
-  ON CREATE SET
-    w.title     = row.title,
-    w.source    = 'linkedin',
-    w.current   = true,
-    w.createdAt = datetime()
-  ON MATCH SET
-    w.title     = coalesce(row.title, w.title)
+## Write surface
+
+This reference invokes a single MCP tool: `mcp__memory__memory-archive-write` with `archiveType: "linkedin-connections"`. The Cypher body — Person upsert by `linkedinUrl`, `CONNECTED_ON_LINKEDIN` edge from owner, optional `:Organization` + `WORKS_FOR` when company is non-empty — lives server-side in [`platform/plugins/memory/mcp/src/tools/memory-archive-write.ts`](../../../../memory/mcp/src/tools/memory-archive-write.ts). The agent does not author or pipe Cypher; it parses CSV rows into the tool's row schema and dispatches one (or more, for filtered re-imports) tool call.
+
+### Tool input shape
+
+```json
+{
+  "archiveType": "linkedin-connections",
+  "ownerNodeId": "<elementId of :AdminUser or :Person — from owner-confirmation flow>",
+  "rows": [
+    {
+      "givenName": "Dee",
+      "familyName": "Odus",
+      "linkedinUrl": "https://www.linkedin.com/in/deeodus",
+      "email": null,
+      "company": "Female Founders Fund",
+      "title": "Partner",
+      "connectedOn": "2026-04-23"
+    }
+  ],
+  "sessionId": "<UUID generated once per skill run>"
+}
 ```
 
+The parser converts:
+- Blank cells → `null` (especially `email`, `company`, `title`).
+- `Connected On` from `"23 Apr 2026"` → ISO 8601 `"2026-04-23"`. The tool rejects rows with non-ISO dates loudly — never let the agent paper over a parser bug.
+
+### What the server does (informational, not the agent's responsibility)
+
+Per 500-row batch the handler runs one transaction with two phases:
+
+1. Upsert each row's `:Person` (natural key `linkedinUrl`), stamp provenance + email when present, then upsert the owner→Person `CONNECTED_ON_LINKEDIN` edge with `connectedOn` on the edge.
+2. For rows whose `company` is non-empty, upsert the `:Organization` (natural key `accountId + name`), then upsert the Person→Organization `WORKS_FOR` edge with `title` on the edge.
+
+Provenance stamped on every node: `source='linkedin'`, `createdByAgent='linkedin-import'`, `createdBySource='linkedin-import'`, `createdBySession=<sessionId>`, `createdAt=<now>`.
+
+Counters come from the Neo4j driver's per-statement summary (`nodesCreated`, `relationshipsCreated`). The tool returns `{processedRows, createdPersons, mergedPersons, createdOrganizations, createdEdges, errors[]}`.
+
 ## Edge semantics — why these and no others
 
 - **`(owner)-[:CONNECTED_ON_LINKEDIN]->(:Person)`** — each row of Connections.csv is a declaration that the archive owner and this person are LinkedIn connections. That's the edge.
@@ -128,14 +99,16 @@ Rows missing a position but present with a company produce a `WORKS_FOR` edge wi
 
 ## Date parsing
 
-`Connected On` arrives as `"23 Apr 2026"`. Convert to ISO 8601 (`2026-04-23`) in the parser before passing to Cypher — `date("2026-04-23")` is Neo4j-native.
+`Connected On` arrives as `"23 Apr 2026"`. Convert to ISO 8601 (`2026-04-23`) in the parser before passing to the tool. The server converts to Neo4j `date()` internally — the agent never invokes Cypher functions.
 
 ## Expected shape
 
-- ~3,000–10,000 rows typical for a long-running account.
-- 500 rows per transaction. Single UNWIND handles this; `apoc.periodic.iterate` not required.
+- ~3,000–10,000 rows typical for a long-running account. The selective-ingest gate (above) keeps a typical write at well under 1,000 rows.
+- 500 rows per transaction. The MCP tool handles batching internally; the agent passes the full filtered `rows[]` in one call.
 
-## Post-import verification
+## Post-import verification (operator-side, not agent-side)
+
+After ingest, the operator can verify counts via the `database-operator` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
 
 ```cypher
 // Owner → connections count
@@ -145,18 +118,16 @@ RETURN count(p) AS connections;
 // LinkedIn-origin organizations count
 MATCH (o:Organization {accountId: $accountId, source: 'linkedin'})
 RETURN count(o) AS organizations;
-
-// Spot-check: who works at Female Founders Fund?
-MATCH (o:Organization {accountId: $accountId, name: 'Female Founders Fund'})
-      <-[:WORKS_FOR]-(p:Person)
-RETURN p.name, p.linkedinUrl;
 ```
 
+These are **read queries**, not writes. Cypher writes from the agent are forbidden.
+
 ## Failure modes
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
 | Every row parsed as "Notes:,NaN,…" | Header preamble not skipped | Skip first 3 lines before the CSV parser |
-| Constraint violation on `person_email_unique` | Empty email cells treated as `""` instead of `null` | Ensure the parser converts blanks to `null` |
-| `MATCH (owner …)` returns zero rows | `$ownerUserId` invalid — owner-confirmation not run, or operator typed the wrong id | Re-run owner confirmation |
+| Tool error "row connectedOn is not ISO 8601" | Parser left `Connected On` in `"23 Apr 2026"` form | Convert to `YYYY-MM-DD` before passing to the tool |
+| Tool error "ownerNodeId not found" | Owner-confirmation flow not run, or operator typed the wrong id | Re-run owner confirmation; pass the resulting `elementId` as `ownerNodeId` |
 | `WORKS_FOR` count « connection count | Many rows have blank company | Expected — LinkedIn doesn't force connections to list a current employer |
+| Tool not present in `init` frame | `database-operator` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per database-operator's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/references/profile.md

@@ -1,8 +1,8 @@
 # Reference: Profile.csv
 
-Enriches the confirmed archive owner's `:UserProfile` with the LinkedIn profile fields. No new nodes, no new edges — `:AdminUser` and `:UserProfile` already exist for any Maxy operator and are linked by `[:HAS_PROFILE]` at session start.
+Enriches the confirmed archive owner's `:UserProfile` with the LinkedIn profile fields. No new nodes, no new edges — `:AdminUser` and `:UserProfile` already exist for any Maxy operator and are linked by `[:HAS_PROFILE]` at session start (neo4j-store handles that on session boot, not this skill).
 
-Runs before every other reference because later files display LinkedIn profile fields (headline, summary) on the owner node they MATCH.
+Runs before every other reference because later files display LinkedIn profile fields (headline, summary) on the owner node they search.
 
 ## Source
 
@@ -30,66 +30,59 @@ Schema.org camelCase per `platform/plugins/memory/references/schema-base.md`.
 
 ## Anchor
 
+The owner-confirmation flow at the start of the skill resolves the operator's `:UserProfile` elementId — not just the `:AdminUser` userId. That elementId (`$ownerProfileElementId`) is the input to this reference. The `[:HAS_PROFILE]` edge between `:AdminUser` and `:UserProfile` is created by `platform/ui/app/lib/neo4j-store.ts` on every session start; it pre-exists by the time any skill runs.
+
+## Write surface
+
+This reference invokes `mcp__memory__memory-update` once with the parsed row's properties:
+
+```json
+{
+  "nodeId": "<elementId of :UserProfile from owner-confirmation>",
+  "properties": {
+    "givenName": "Joel",
+    "familyName": "Smalley",
+    "additionalName": null,
+    "address": null,
+    "birthDate": null,
+    "headline": "Founder, Rubytech",
+    "description": "Building Maxy …",
+    "industry": "Software",
+    "postalCode": null,
+    "addressLocality": "London, UK",
+    "twitterHandles": ["@joelsmalley"],
+    "websites": ["https://getmaxy.com"],
+    "instantMessengers": [],
+    "linkedinProfileUpdatedAt": "<ISO 8601 timestamp>",
+    "source": "linkedin"
+  }
+}
 ```
-(:AdminUser {userId: $ownerUserId}) -[:HAS_PROFILE]-> (:UserProfile {accountId, userId})
-```
-
-The skill run has already persisted `$ownerUserId` (and its resolved `$accountId`) from the owner-confirmation flow. This reference trusts those parameters.
-
-## Cypher
 
-```cypher
-// Parameters:
-//   $ownerUserId — AdminUser.userId of the confirmed archive owner
-//   $accountId   — the UserProfile accountId resolved alongside $ownerUserId
-//   $sessionId   — UUID generated once per skill run
-//   $row         — parsed object with the columns above
-
-MATCH (au:AdminUser {userId: $ownerUserId})
-MERGE (au)-[:HAS_PROFILE]->(up:UserProfile {accountId: $accountId, userId: $ownerUserId})
-  ON CREATE SET
-    up.createdAt       = datetime(),
-    up.createdByAgent  = 'linkedin-import',
-    up.createdBySource = 'linkedin-import',
-    up.createdBySession= $sessionId
-SET
-    up.givenName          = $row.givenName,
-    up.familyName         = $row.familyName,
-    up.additionalName     = $row.additionalName,
-    up.address            = $row.address,
-    up.birthDate          = $row.birthDate,
-    up.headline           = $row.headline,
-    up.description        = $row.description,
-    up.industry           = $row.industry,
-    up.postalCode         = $row.postalCode,
-    up.addressLocality    = $row.addressLocality,
-    up.twitterHandles     = $row.twitterHandles,
-    up.websites           = $row.websites,
-    up.instantMessengers  = $row.instantMessengers,
-    up.linkedinProfileUpdatedAt = datetime(),
-    up.source             = coalesce(up.source, 'linkedin')
-
-RETURN elementId(up) AS ownerProfileElementId
-```
+The `memory-update` tool ignores restricted keys (`embedding`, `accountId`, `createdAt`) and recomputes the embedding from the new property set. No raw Cypher, no `MERGE`, no Bash.
 
-The `MERGE (au)-[:HAS_PROFILE]->(up)` is idempotent: for any operator whose session has already run, `(au)-[:HAS_PROFILE]->(up)` already exists — this statement simply matches it and SETs properties. If the operator has never opened a Maxy session for this account (rare; the UserProfile normally exists before any skill runs), it is created here.
+The parser converts:
+- Blank cells → `null`.
+- `Twitter Handles`, `Websites`, `Instant Messengers` from comma-delimited strings → arrays.
+- `Birth Date` to ISO 8601 if present.
 
 ## Expected outcome
 
-- Zero new nodes (typical case).
-- Zero new edges (typical case).
+- Zero new nodes.
+- Zero new edges.
 - One existing `:UserProfile` enriched with 10–13 new properties.
-- `ownerProfileElementId` returned for downstream references that want to cache the anchor.
 
 ## Failure modes
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| Zero rows returned from `MATCH (au:AdminUser {userId: $ownerUserId})` | `$ownerUserId` doesn't resolve — operator typo in confirmation, or AdminUser missing | Re-run the owner-confirmation flow; verify `platform/config/users.json` contains the expected userId |
+| Tool error "node not found" | `$ownerProfileElementId` invalid — owner-confirmation flow did not return a UserProfile | Re-run the owner-confirmation flow; verify `:AdminUser`-`HAS_PROFILE`->`:UserProfile` exists for the confirmed userId |
 | `up.websites` written as a single string not an array | Parser didn't split on `,` | Fix parser — LinkedIn comma-delimits these fields |
-| Constraint violation on `user_profile_account_user_unique` | Shouldn't happen — MERGE uses the composite key | Indicates a pre-existing duplicate; investigate with `MATCH (up:UserProfile {accountId: $accountId, userId: $ownerUserId}) RETURN count(up)` |
+| Restricted property silently ignored | `memory-update` rejects `embedding` / `accountId` / `createdAt` overrides | Expected — those fields are managed by the server |
+
+## Post-import verification (operator-side, read-only)
 
-## Post-import verification
+A direct read query through `mcp__memory__memory-search` (`labels: ["UserProfile"]`) or `mcp__graph__maxy-graph-read_neo4j_cypher`:
 
 ```cypher
 MATCH (au:AdminUser {userId: $ownerUserId})-[:HAS_PROFILE]->(up:UserProfile)
@@ -99,4 +92,4 @@ RETURN
   up.websites, up.linkedinProfileUpdatedAt
 ```
 
-Exactly one row. If zero, either the AdminUser doesn't exist or the HAS_PROFILE edge wasn't MERGEd — investigate before running any subsequent reference.
+Exactly one row. If zero, the owner-confirmation flow returned the wrong elementId — investigate before running any subsequent reference.

package/payload/platform/plugins/memory/PLUGIN.md

@@ -19,6 +19,7 @@ tools:
   - memory-read-attachment
   - memory-edit-attachment
   - memory-rename-attachment
+  - memory-archive-write
   - conversation-list
   - conversation-search
   - profile-read

package/payload/platform/plugins/memory/mcp/dist/index.js

@@ -12,6 +12,7 @@ import { buildLiveSchemaSource, defaultSchemaCypherPath, } from "./lib/live-sche
 import { memoryReindex } from "./tools/memory-reindex.js";
 import { memoryIngestExtract } from "./tools/memory-ingest-extract.js";
 import { memoryIngest } from "./tools/memory-ingest.js";
+import { memoryArchiveWrite } from "./tools/memory-archive-write.js";
 import { memoryIngestWeb } from "./tools/memory-ingest-web.js";
 import { memoryClassify } from "./tools/memory-classify.js";
 import { memoryUpdate } from "./tools/memory-update.js";
@@ -769,6 +770,53 @@ if (!readOnly) {
             };
         }
     });
+    server.tool("memory-archive-write", "Bulk-archive write surface (Task 744). Writes a flat dataset (typed entities + natural edges) into the graph " +
+        "in 500-row UNWIND batches. The Cypher body is fixed server-side per `archiveType`; the agent supplies parsed " +
+        "rows + the discriminant, never raw Cypher. Use ONLY for first-class entity exports (LinkedIn Connections, " +
+        "future CRM-type seed exports). Use memory-ingest for narrative documents (KnowledgeDocument + Section + NEXT) " +
+        "and memory-write for single-node operator-driven writes. Currently supported archiveType values: " +
+        "`linkedin-connections`.", {
+        archiveType: z
+            .enum(["linkedin-connections"])
+            .describe("Discriminant naming the per-source schema and Cypher body the server runs. Add a new value here only when the corresponding handler is added in memory-archive-write.ts."),
+        ownerNodeId: z
+            .string()
+            .min(1)
+            .describe("elementId of the archive owner — :AdminUser for an operator's own archive, or :Person for an external-archive owner. Confirmed during the skill's owner-confirmation flow before this tool is invoked."),
+        rows: z
+            .array(z.record(z.string(), z.unknown()))
+            .min(1)
+            .describe("Parsed rows. The skill's selective-ingest gate runs BEFORE this tool — large blanket archives get filtered (Company / Position / Connected On range for linkedin-connections) before the write call."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Skill-run UUID for provenance stamping. Falls back to SESSION_ID env var when absent."),
+    }, async ({ archiveType, ownerNodeId, rows, sessionId: sessionIdOverride }) => {
+        try {
+            const result = await memoryArchiveWrite({
+                archiveType,
+                ownerNodeId,
+                accountId,
+                rows: rows,
+                sessionId: resolveSessionId(sessionIdOverride),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(result),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-archive-write failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
     server.tool("memory-ingest-web", "Adapter for web-content ingestion (Task 737). Accepts a URL and its pre-fetched readable content " +
         "(the agent calls WebFetch first, then passes the text here), writes content to a temp file, and delegates " +
         "to memory-ingest-extract — caching the text under a freshly-generated attachmentId. The skill then drives " +