@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,27 @@
+---
+name: linkedin-import
+description: "Import a LinkedIn Basic Data Export into the Maxy Neo4j graph. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default."
+tools: []
+always: false
+embed: false
+specialist: database-operator
+metadata: {"platform":{"optional":true,"pluginKey":"linkedin-import"}}
+---
+
+# LinkedIn Import
+
+Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirectories) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `specialists:database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
+
+## When this applies
+
+The admin agent delegates to `specialists:database-operator` when the operator drops a `Basic_LinkedInDataExport_*` directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any CSV is read, then ingests the CSVs the skill has references for.
+
+## Intra-plugin growth
+
+A LinkedIn export contains ~20 CSVs. The skill ships references for `Profile.csv` and `Connections.csv` today — additional CSVs (Messages, Positions, Skills, Endorsements, Recommendations, Articles, Education, Certifications, Invitations, etc.) land as **new reference files inside this same plugin** under `skills/linkedin-import/references/` as each is authored. They do not become new plugins.
+
+## Relationship to other plugins
+
+- **contacts** — waitlist-shaped CRM surface. LinkedIn-imported `:Person` nodes are visible via `contact-list`, but ingestion does not go through contact tools.
+- **memory** — the underlying Cypher-write surface used by the skill (`memory-write`, `memory-update`). The skill is parameterised so all writes carry `source='linkedin'` + `createdByAgent='linkedin-import'` for provenance.
+- **database-operator specialist** — owns execution. See [admin/IDENTITY.md](../../../platform/templates/agents/admin/IDENTITY.md) delegation clause.

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

@@ -0,0 +1,142 @@
+---
+name: linkedin-import
+description: Import a LinkedIn Basic Data Export into a {{productName}} Neo4j graph. Triggers when the user asks to import a LinkedIn archive, ingest LinkedIn connections/messages/positions into the graph, or mentions a `Basic_LinkedInDataExport_*.zip` folder. One reference per CSV under `references/`; edges come from what each CSV naturally encodes, never from synthetic "anchor" patterns.
+---
+
+# LinkedIn Import
+
+Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirs) into a {{productName}} Neo4j graph. Every edge written corresponds to a real relationship expressed by the data — not a convenience anchor.
+
+## Archive-owner confirmation (mandatory first step)
+
+A LinkedIn archive belongs to exactly one person — the user whose LinkedIn account produced the export. That person is the subject of every row in the archive: every `CONNECTED_ON_LINKEDIN` edge points from them to a contact, every `WORKS_FOR` edge on `Positions.csv` belongs to them, every `HAS_SKILL` edge on `Skills.csv` is theirs.
+
+**Who the archive belongs to is not inferred from who runs the skill.** Joel may be ingesting his own archive today, a business partner's archive next week, or both side-by-side. The skill takes the archive owner as an explicit input and refuses to proceed until it is confirmed.
+
+The confirmation flow:
+
+1. List every `:AdminUser` in the graph and display each as `{userId, name, createdAt, accountId(s) via ADMIN_OF}`.
+2. Ask the operator to name the archive owner. Accept one of:
+   - An existing AdminUser userId from the list (typical — Joel's own archive, or a partner who is already a {{productName}} operator).
+   - A new external Person identity (not-yet-an-AdminUser) — create a fresh `:Person` with `givenName`, `familyName`, `email`/`telephone` (at least one) and use its `elementId` as the owner anchor. This path covers ingesting a non-operator's archive for reference.
+3. Echo the chosen owner back verbatim (`userId=<id> name=<name>`) and require explicit yes/no confirmation before any CSV is touched.
+4. Persist the confirmed owner as `$ownerUserId` (for AdminUser-type owners) or `$ownerPersonId` (for external Person owners) — this parameter flows into every reference.
+
+Refusing to assume is load-bearing: a hard-coded "it's whoever's running this" would misattribute a partner's connections to the operator on first re-use.
+
+## Anchor shape
+
+When the owner is an AdminUser (the common case):
+
+```
+(:AdminUser {userId: $ownerUserId}) -[:HAS_PROFILE]-> (:UserProfile {accountId, userId})
+```
+
+Both nodes already exist for any {{productName}} operator — the HAS_PROFILE edge is MERGEd by [`platform/ui/app/lib/neo4j-store.ts`](../../../../ui/app/lib/neo4j-store.ts) at session start. The LinkedIn import updates these existing nodes; it does not create parallel operator identities.
+
+- **Identity + account-scoped behaviour** → `:AdminUser` and `:UserProfile` (existing, unchanged).
+- **LinkedIn profile enrichment** (headline, summary, websites, industry, geoLocation) → property updates on `:UserProfile`.
+- **LinkedIn activity edges** (`CONNECTED_ON_LINKEDIN`, `WORKS_FOR`, `ATTENDED`, `HAS_SKILL`, `HOLDS_CREDENTIAL`, `FOLLOWS`, `AUTHORED`, `PARTICIPANT_IN`) → subjects are the `:AdminUser` (device-level facts: "I know this person") or `:UserProfile` (account-scoped facts: "in this brand I am skilled at X"). Each reference states which and why.
+
+When the owner is an external Person (non-operator archive), the anchor is the confirmed `:Person` node instead — same edges, different anchor.
+
+## 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. 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 {{productName}} labels.** Schema-extension is last resort. The LinkedIn set maps onto existing labels wherever semantics align:
+   - LinkedIn companies → `:Organization` (existing, memory-write registered).
+   - LinkedIn schools → `:Organization` with `organizationCategory: 'educational'`.
+   - LinkedIn skills → `:DefinedTerm` with `category: 'linkedin-skill'`.
+   - LinkedIn articles → `:CreativeWork` with `category: 'linkedin-article'`.
+   - LinkedIn recommendations → `:Review`.
+   - LinkedIn DMs → `:Message:LinkedInMessage` + `:Conversation:LinkedInConversation` (sublabels on the existing labels).
+   - Certifications → `:Credential` (genuinely new — no existing {{productName}} label fits `schema:EducationalOccupationalCredential`).
+5. **Schema-base property names.** `givenName` / `familyName` / `telephone` / `dateSent` — not `firstName` / `phone` / `sentAt`. See [`platform/plugins/memory/references/schema-base.md`](../../../../plugins/memory/references/schema-base.md).
+6. **Schema-base edge names.** `(:Person)-[:WORKS_FOR]->(:Organization)` for positions. Custom LinkedIn edges (`CONNECTED_ON_LINKEDIN`, `ENDORSED`) only where schema-base has no canonical name.
+7. **Provenance stamp.** Every new node: `createdByAgent='linkedin-import'`, `createdBySource='linkedin-import'`, `createdBySession=$sessionId` (UUID per skill run), `createdAt=datetime()`, plus `source='linkedin'` as the data-origin marker.
+8. **Idempotent MERGE.** Re-running any reference after a fresh export updates properties without duplicating nodes.
+
+## Execution model
+
+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).
+
+**LOUD-FAIL on parse errors (structurally enforced).** When LinkedIn parser tools land that follow the `mcp__*__*-import-parse` naming convention, the harness-level `platform/plugins/admin/hooks/archive-ingest-gate.sh` will record an `isError: true` response and block every subsequent tool call this turn until the operator submits the next prompt. The hook also denies edits to `platform/plugins/*/lib/*` and JavaScript test runners (`vitest`, `bun test`, `npm test`, `npx jest`) unconditionally. The skill's "no Bash improvisation" doctrine above is the contract; the hook is the enforcement. See [.docs/hooks.md](../../../../../.docs/hooks.md) for the full gate surface.
+
+## 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
+
+Each entry maps to exactly one reference. Order reflects when a reference's edges first become meaningful — `profile.md` enriches the owner's UserProfile and runs before any file that queries it.
+
+| Order | File | Reference | Edges produced |
+|-------|------|-----------|----------------|
+| 1 | `Profile.csv` | [profile.md](references/profile.md) | enrichment on `:UserProfile` (no new nodes) |
+| 2 | `Email Addresses.csv` | _pending_ | `:UserProfile` ← `.email` / `:AdminUser.emails` array enrichment |
+| 2 | `PhoneNumbers.csv` | _pending_ | `:UserProfile.telephone` enrichment |
+| 2 | `Whatsapp Phone Numbers.csv` | _pending_ | `:UserProfile.whatsappTelephone` enrichment |
+| 3 | `Positions.csv` | _pending_ | `(:UserProfile)-[:WORKS_FOR {title,startDate,endDate}]->(:Organization)` |
+| 3 | `Education.csv` | _pending_ | `(:UserProfile)-[:ATTENDED {degree,startDate,endDate}]->(:Organization {organizationCategory:'educational'})` |
+| 3 | `Certifications.csv` | _pending_ | `(:UserProfile)-[:HOLDS]->(:Credential)` |
+| 3 | `Languages.csv` | _pending_ | `(:UserProfile)-[:SPEAKS {proficiency}]->(:DefinedTerm {category:'language'})` |
+| 3 | `Skills.csv` | _pending_ | `(:UserProfile)-[:HAS_SKILL]->(:DefinedTerm {category:'linkedin-skill'})` |
+| 4 | `Connections.csv` | [connections.md](references/connections.md) | `(:AdminUser)-[:CONNECTED_ON_LINKEDIN {connectedOn}]->(:Person)` + `(:Person)-[:WORKS_FOR {title}]->(:Organization)` |
+| 5 | `Invitations.csv` | _pending_ | `(:AdminUser)-[:INVITED / :INVITED_BY]->(:Person)` |
+| 5 | `Endorsement_Given_Info.csv` | _pending_ | `(:AdminUser)-[:ENDORSED {date}]->(:Person)-[:FOR_SKILL]->(:DefinedTerm)` |
+| 5 | `Endorsement_Received_Info.csv` | _pending_ | `(:Person)-[:ENDORSED {date}]->(:AdminUser)-[:FOR_SKILL]->(:DefinedTerm)` |
+| 5 | `Recommendations_Given.csv` | _pending_ | `(:Review)-[:ABOUT]->(:Person)`, `(:AdminUser)-[:AUTHORED]->(:Review)` |
+| 5 | `Recommendations_Received.csv` | _pending_ | `(:Review)-[:ABOUT]->(:AdminUser)`, `(:Person)-[:AUTHORED]->(:Review)` |
+| 6 | `Company Follows.csv` | _pending_ | `(:AdminUser)-[:FOLLOWS {since}]->(:Organization)` |
+| 6 | `Causes You Care About.csv` | _pending_ | `(:UserProfile)-[:SUPPORTS]->(:DefinedTerm {category:'cause'})` |
+| 6 | `Events.csv` | _pending_ | `(:AdminUser)-[:ATTENDED_EVENT]->(:Event)` |
+| 7 | `messages.csv` | _pending_ | `:Conversation:LinkedInConversation` + threaded `:Message:LinkedInMessage` + `(:Person)-[:PARTICIPANT_IN]->(conv)` |
+| 7 | `guide_messages.csv` | _pending_ | same (likely empty) |
+| 7 | `learning_coach_messages.csv` | _pending_ | same (likely empty) |
+| 7 | `learning_role_play_messages.csv` | _pending_ | same (likely empty) |
+| 8 | `Articles/` | _pending_ | `(:AdminUser)-[:AUTHORED]->(:CreativeWork {category:'linkedin-article'})` |
+| 8 | `Learning.csv` | _pending_ | `(:UserProfile)-[:COMPLETED]->(:Credential)` (LinkedIn Learning courses) |
+| 9 | `Jobs/Job Applications.csv` | _pending_ | `(:AdminUser)-[:APPLIED_TO {date}]->(:Organization)` via job-posting text on the edge |
+| 9 | `Jobs/Saved Jobs.csv` | _pending_ | `(:AdminUser)-[:SAVED_JOB]->(:Organization)` |
+| 9 | `Jobs/Job Seeker Preferences.csv` | _pending_ | `:UserProfile.jobSeekerPreferences` property blob |
+| 9 | `Jobs/Online Job Postings.csv` | _pending_ | `(:AdminUser)-[:POSTED]->(:JobPosting)` (only rows where the operator authored the posting) |
+| 9 | `SavedJobAlerts.csv` | _pending_ | `:UserProfile.savedJobAlerts` property blob |
+| 10 | `Services Marketplace/Providers.csv` | _pending_ | `:UserProfile.servicesOffered` property blob |
+| 10 | `Receipts_v2.csv` | _pending_ | `(:AdminUser)-[:PAID]->(:Invoice)` (LinkedIn subscriptions) |
+| 10 | `Registration.csv` | _pending_ | `:UserProfile.linkedinRegisteredAt` property enrichment |
+
+## Explicitly out of scope
+
+- `Ad_Targeting.csv` — LinkedIn-inferred ad segments, no graph value.
+- `Rich_Media.csv` — time-limited signed LinkedIn CDN URLs; files 404 after expiry.
+- `Private_identity_asset.csv` — duplicates `Profile.csv` summary text.
+- `Profile Summary.csv` — empty in this export.
+- `Job Applicant Saved Screening Question Responses.csv` — ephemeral Q&A, no stable identity.
+
+Add a new reference if any of these later become useful — nothing silently flows in.
+
+## Natural-edge discipline (why this matters)
+
+The rule isn't "every node must have an edge". The rule is "every node must have the edges its source data actually describes, and no synthetic ones bolted on to satisfy a check." A LinkedIn archive satisfies the orphan doctrine trivially: every row expresses a relationship between the archive owner and someone or something else. If a future file turns out to describe entities with no relationship to the owner (an endorsement between two third parties, say), the reference for that file writes the entities with their natural edges and doesn't fabricate a connection to the owner just because the owner supplied the file.

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

@@ -0,0 +1,135 @@
+# Reference: Connections.csv
+
+Creates a `:Person` for every LinkedIn connection, a `:Organization` for every company named on those rows, `[:WORKS_FOR {title}]` edges from connections to their current employer, and `[:CONNECTED_ON_LINKEDIN {connectedOn}]` edges from the archive owner to every connection.
+
+Every edge in this reference is expressed by the source CSV: connections are explicitly labelled as "connected to the archive owner", and each connection row explicitly names a current position. Nothing synthetic.
+
+## Source
+
+`Connections.csv`.
+
+**Parser note — skip the header preamble.** The file begins with three lines LinkedIn injects:
+
+```
+Notes:
+"When exporting your connection data, …"
+<blank line>
+First Name,Last Name,URL,Email Address,Company,Position,Connected On
+```
+
+The real column header is **line 4**. Either skip the first three lines before parsing, or parse with no header and align columns from row 4 onward.
+
+## Columns → properties and edges
+
+| CSV column | Maps to |
+|------------|---------|
+| First Name | `Person.givenName` |
+| Last Name | `Person.familyName` |
+| URL | `Person.linkedinUrl` (natural key) |
+| Email Address | `Person.email` (only when non-empty) |
+| Company | `Organization.name` |
+| Position | `[:WORKS_FOR].title` AND `Person.currentTitle` (denormalised) |
+| Connected On | `[:CONNECTED_ON_LINKEDIN].connectedOn` (ISO 8601) |
+
+The `Position` column is written **twice**: once on the `[:WORKS_FOR]` edge as the source of truth (preserves the per-employer history when a connection later moves), and again as `Person.currentTitle` so Neo4j's `entity_search` BM25 index reaches it. Edge properties are invisible to a node-only fulltext index, so without the denormalisation an operator searching "director" against 5K connections returns near-zero hits regardless of how many directors are in the graph. The SET is unconditional — re-importing a row with an empty Position clears `currentTitle`, matching the LinkedIn export's "current snapshot" semantics. To filter your import to a specific role before writing, use the [Selective-ingest threshold](#selective-ingest-threshold) gate.
+
+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
+
+| Entity | Key | Why |
+|--------|-----|-----|
+| `:Person` | `linkedinUrl` (indexed in `platform/neo4j/schema.cypher`) | Stable across exports; display-name collisions are frequent |
+| `:Organization` | `(accountId, name)` | Matches existing `memory-write` convention. Schema-base.md requires `accountId` + `name` on every Organization |
+
+## Anchor
+
+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.
+
+## Selective-ingest threshold
+
+**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.
+
+## 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.
+- **`(:Person)-[:WORKS_FOR]->(:Organization)`** — each row's Company/Position columns state where the connection currently works. That's the edge. Schema-base calls this `WORKS_FOR`.
+
+Rows missing a company produce a Person with a `CONNECTED_ON_LINKEDIN` edge and no WORKS_FOR — because the row didn't express a WORKS_FOR relationship. No placeholder Organization gets minted.
+
+Rows missing a position but present with a company produce a `WORKS_FOR` edge with null `title` — the connection works there, we just don't know their role.
+
+## Date parsing
+
+`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. 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 (operator-side, not agent-side)
+
+After ingest, the operator can verify counts via the `specialists: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
+MATCH (owner:AdminUser {userId: $ownerUserId})-[:CONNECTED_ON_LINKEDIN]->(p:Person)
+RETURN count(p) AS connections;
+
+// LinkedIn-origin organizations count
+MATCH (o:Organization {accountId: $accountId, source: 'linkedin'})
+RETURN count(o) AS organizations;
+```
+
+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 |
+| 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 | `specialists: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

@@ -0,0 +1,95 @@
+# 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 {{productName}} 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 search.
+
+## Source
+
+`Profile.csv` — single data row.
+
+## Columns → UserProfile properties
+
+Schema.org camelCase per `platform/plugins/memory/references/schema-base.md`.
+
+| CSV column | Property on `:UserProfile` |
+|------------|----------------------------|
+| First Name | `givenName` |
+| Last Name | `familyName` |
+| Maiden Name | `additionalName` (nullable) |
+| Address | `address` (nullable) |
+| Birth Date | `birthDate` (nullable, ISO 8601) |
+| Headline | `headline` |
+| Summary | `description` |
+| Industry | `industry` (nullable) |
+| Zip Code | `postalCode` (nullable) |
+| Geo Location | `addressLocality` (nullable) |
+| Twitter Handles | `twitterHandles` — array, split on `,` |
+| Websites | `websites` — array, split on `,` |
+| Instant Messengers | `instantMessengers` — array, split on `,` |
+
+## 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 {{productName}} …",
+    "industry": "Software",
+    "postalCode": null,
+    "addressLocality": "London, UK",
+    "twitterHandles": ["@joelsmalley"],
+    "websites": ["https://getmaxy.com"],
+    "instantMessengers": [],
+    "linkedinProfileUpdatedAt": "<ISO 8601 timestamp>",
+    "source": "linkedin"
+  }
+}
+```
+
+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 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.
+- Zero new edges.
+- One existing `:UserProfile` enriched with 10–13 new properties.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 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 |
+| 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)
+
+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)
+RETURN
+  au.name, au.userId,
+  up.givenName, up.familyName, up.headline, up.description,
+  up.websites, up.linkedinProfileUpdatedAt
+```
+
+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

@@ -0,0 +1,146 @@
+---
+name: memory
+description: "Graph memory plugin. Provides memory-search, memory-rank, memory-write, and memory-update tools for reading from, writing to, and updating the Neo4j knowledge graph. Includes conversational memory — organic preference learning, evidence-backed recall, and transparent 'what do you know about me?' responses. Document ingestion (memory-classify + memory-ingest) supports two modes: `document` (default) for unstructured PDF/web content → KnowledgeDocument + Section, and `chat` for conversation transcripts → ConversationArchive + Section:Conversation chunks. Conversation-archive Phase 2 (`conversation-archive-derive-insights`) walks chunks of one named archive and emits per-row claim proposals for operator-gated wiring; `conversation-archive-enrich-rejection` records (or undoes) durable per-row rejections so already-triaged claims do not re-surface on re-runs. Ships four skills: `conversational-memory`, `document-ingest`, `conversation-archive` (source-agnostic transcript ingest for WhatsApp, Telegram, Signal, LinkedIn DMs, Zoom, meeting minutes, iMessage, Slack), and `conversation-archive-enrich` (per-row operator-gated insight derivation over a named archive's chunks)."
+tools:
+  - memory-search
+  - memory-rank
+  - memory-write
+  - memory-update
+  - memory-reindex
+  - memory-ingest
+  - memory-ingest-extract
+  - memory-ingest-web
+  - memory-classify
+  - memory-find-candidates
+  - memory-delete
+  - memory-restore
+  - memory-empty-trash
+  - memory-list-attachments
+  - memory-read-attachment
+  - memory-edit-attachment
+  - memory-rename-attachment
+  - memory-archive-write
+  - conversation-archive-derive-insights
+  - conversation-archive-enrich-rejection
+  - conversation-list
+  - conversation-search
+  - profile-read
+  - profile-update
+  - profile-delete
+  - graph-prune-denylist-add
+  - graph-prune-denylist-list
+  - graph-prune-denylist-remove
+  - conversation-memory-expunge
+hidden:
+  - session-compact
+  - session-compact-status
+skills:
+  - skills/conversational-memory/SKILL.md
+  - skills/document-ingest/SKILL.md
+  - skills/conversation-archive/SKILL.md
+  - skills/conversation-archive-enrich/SKILL.md
+always: true
+embed: false
+---
+
+# Memory
+
+Provides read and write access to the Neo4j knowledge graph — search, structured writes, document ingestion, attachment management, conversation history, and user profiles. Tool routing is each agent's IDENTITY.md responsibility; this plugin describes what tools are available, not when to use them. The admin agent and specialist subagents call these tools directly via MCP. The public agent has no MCP tools — its knowledge is assembled server-side from the graph into the system prompt.
+
+Tools are available via the `memory` MCP server.
+
+## LLM-Reasoned Ranking
+
+`memory-rank` is a ranking tool built on top of `memory-search`. It retrieves a candidate pool from the graph using the same hybrid vector+BM25 pipeline, then passes the candidates to Claude Haiku along with a natural-language ranking criterion. The response is an ordered list with a short reasoning string per item explaining why each candidate landed where it did.
+
+Ranking is ephemeral and contextual — nothing is written back to the graph. When the Anthropic API key is unavailable or the model call fails, the tool returns the unranked memory-search results with a visible `[Ranking unavailable: <reason>]` notice so the agent can tell the user that ranking did not run. The ranking criterion is sandboxed as a directive inside the user message; imperative instructions embedded in it are treated as data, not control flow.
+
+## Search Output Size
+
+`memory-search` enforces an output character budget. When the formatted output exceeds the budget, it degrades gracefully: related nodes are stripped from the lowest-scored results first, then entire results are dropped from the tail. A truncation notice at the end states what was trimmed.
+
+Use `expandHops: 0` for listing and inventory queries (returns node properties only — compact output). Use `expandHops: 1` (default) for deep context queries where related nodes add value. Queries that combine a high `limit` with `expandHops: 1` on node types that have many relationships (e.g. KnowledgeDocument with HAS_SECTION) are most likely to trigger trimming.
+
+## Anchoring writes to provenance — `producedByTaskId` and the conversation env-stamp
+
+Writes targeting `:Person`, `:UserProfile`, `:AdminUser`, `:Organization`, `:LocalBusiness`, `:CloudflareTunnel`, or `:CloudflareHostname` require an inbound `:PRODUCED` edge whose source is one of `:Task`, `:Conversation`, or `:Message` (deterministic bootstrap paths run as `createdBy.agent === 'system'` and are exempt). Two surfaces feed the gate:
+
+- **Workflow path — `producedByTaskId`.** `memory-write` accepts an optional `producedByTaskId` parameter. When set, the platform composes an inbound `:PRODUCED` edge from that `:Task` node into the write's `relationships` array before the write runs. The Task and the new node must share the same `accountId`; mismatch is rejected loud. The typical pattern: call `task-create` at the start of an autonomous flow (onboarding skill, cloudflare tunnel-login) with `kind` and `raisedDuringConversationKey`; capture the returned `taskId`; pass it as `producedByTaskId` on every subsequent `memory-write` for one of the gated labels.
+
+- **Direct-ask path — `CONVERSATION_NODE_ID` env-stamp.** When `producedByTaskId` is not provided (typical of direct admin asks like "add Anneke as person"), `memory-write` falls back to the `CONVERSATION_NODE_ID` env var that the admin server stamps at MCP spawn time. The value is the elementId of the active `:AdminConversation`. The wrapper verifies `accountId` parity before injecting the synthetic `:PRODUCED` edge — `accountId` mismatch is logged as `[mcp:memory] [provenance-missing] reason=account-mismatch` and the gate then fires `missing-provenance`. The env-stamp is invisible to the agent (no schema field changes); the LLM never decides whether to use it.
+
+## Graph Hygiene
+
+Graph hygiene is **agent-directed, case by case** — no autonomous rule engine, no cron. The Neo4j graph degrades into a landfill if pollution from prior agent errors (wrong-account hostnames, fabricated identifiers, raw monologue dumps) is allowed to compound. Cleanup happens when the admin agent observes a match against the operator-curated deny-list (or the user directly asks) and applies discretion using `memory-update`, `memory-delete`, or `conversation-memory-expunge`.
+
+**Operator-curated deny-list.** Stored signal, not an automatic hit list. The admin agent reads this list and uses it as advisory context when deciding what to scrub.
+- `graph-prune-denylist-add` — append substrings you want the agent to watch for (retired domains, decommissioned account ids, fabricated identifiers).
+- `graph-prune-denylist-list` — read the current list.
+- `graph-prune-denylist-remove` — drop substrings. Previously-nulled property values are not restored; audit entries on affected nodes remain for forensic review.
+
+**Conversation-level expunge.**
+- `conversation-memory-expunge` — agent-invoked, scoped to one conversation. Scrubs a specified substring from every linked `:Memory` node's string properties with audit. Transcript Message nodes are immutable history and are never modified — only the derived `:Memory` payload that subsequent `memory-search` would re-surface.
+
+**Single-node removal.** Use `memory-delete` by `elementId`. The node is marked `:Trashed` (relationships preserved, invisible to `memory-search` and any read filtered via `notTrashed`). For `KnowledgeDocument`, the trash cascades to linked `Section` and `Chunk` children. Restore via `memory-restore` (fails loudly when an active node already holds a unique slot the trashed one needs back). Hard removal happens later via `memory-empty-trash` after the grace period (default 30 days). GDPR cascades go through `contact-erase` (per Art. 17) — that bypasses the trash primitive deliberately. There is no bulk delete-by-shape.
+
+**Why soft-delete.** On 2026-04-20 an autonomous orphan-delete rule wiped the sole `OnboardingState` node plus 18 unrelated nodes in one `graph-prune-run` call; properties were unrecoverable (Neo4j Community has no PITR, no APOC). The cron, the `graph-prune-run` tool, and the rule engine have been removed. An earlier fix added the `:Trashed` label primitive so every soft-delete caller (`memory-delete`, `contact-delete`, the admin `/graph` page's trash button) runs the same shared `trashNode` helper — relationships preserved, unique keys snapshotted into `_trashedKeys`, audit lines `[trash:marked] by=<surface>` for cross-cut provenance.
+
+## Conversational Memory
+
+The owner's profile and preferences accumulate organically from conversation — never from questionnaires. Run `skill-load skillName=conversational-memory` for full guidance on when to observe preferences, how to handle remember/forget requests, and how to answer "what do you know about me?" transparently with confidence scores and evidence trail.
+
+## UserProfile + Person Field Management
+
+`profile-update` serves three purposes: managing Preference nodes (category/key/value), setting top-level UserProfile node properties via `profileFields`, and setting Person properties on the operator's personal-profile Person via `personFields`.
+
+Settable UserProfile fields: `timezone` (IANA format, e.g. `Europe/London`), `locale`, `givenName`, `role`, `expertise`. These are account metadata stored directly on the UserProfile node — distinct from Preference nodes, which represent learned behavioural patterns.
+
+Example — setting a user's timezone:
+```json
+{ "category": "scheduling", "key": "timezone_set", "value": "User requested timezone configuration", "profileFields": { "timezone": "Europe/London" } }
+```
+
+Restricted fields (`accountId`, `embedding`, `profileVersion`) cannot be set via `profileFields`.
+
+**Personal-profile Person via `personFields`.** The personal-profile Person is open by default — the agent decides which Person properties best help it serve this operator (identity, contact, context); the central schema validator enforces synonym + Forbidden Properties rejection (per `references/schema-base.md`). Writes route to the personal-profile Person via the OWNS edge from the AdminUser. Validation runs in `mode: "update"` so the required-property loop is skipped on partial SET (givenName/familyName were established at PIN setup). Pass any Person properties the operator volunteers; the validator surfaces synonym (e.g. `phone`) and forbidden (e.g. `name`) errors with descriptive messages. No allow-list, no enumeration — see the schema-base.md Person row notes for the doctrine.
+
+## Schema References
+
+Before any structured write, load `references/schema-base.md` via `plugin-read`. This defines property naming rules, required-property groups for documented types, forbidden-property rules, and relationship patterns. If the `LocalBusiness` node has a `businessType` property, also load the matching vertical schema (`references/schema-{businessType}.md`) — it extends the base with vertical-specific types. Confirm which schemas were consulted before writing.
+
+**Validation surface.** `memory-write` validates labels against `db.labels` ∪ `schema.cypher` declarations — not against this markdown. A label is recognised if it appears in either set. The markdown defines property *shape* (required-property groups, naming rules, forbidden-property rules) for documented labels only; recognised-but-undocumented labels (e.g. `LocalBusiness`, `AdminUser`, `KnowledgeDocument`) accept any property shape and emit `[schema-validator] markdown-undocumented label=<X>` so the doc gap is visible to operators. If `memory-write` rejects a label as unknown, the rejection lists both source sets — the agent can call `maxy-graph-get_neo4j_schema` to refresh its view.
+
+**Forbidden properties.** A "Forbidden Properties" table in any schema markdown file declares per-label deny-listed property keys. The validator rejects writes that include a forbidden key for the matching primary label and emits `[schema-validator] outcome=rejected label=<X> property=<Y> reason=forbidden writer=<agentName>`. The first row is `Person | name` — use `givenName` + `familyName` (rendered display name composed at read time). The check fires after the synonym pass, so `firstName → givenName` rewrites still happen first.
+
+## Document Ingestion
+
+Document ingestion of any kind — PDFs, text, transcripts, web pages, single files — routes to the `specialists:database-operator` specialist, which loads the universal `document-ingest` skill at `skills/document-ingest/SKILL.md`. The admin agent never calls `memory-ingest` directly; it dispatches with the document path, the document subject (the anchor node), and the visibility scope.
+
+### Pipeline
+
+The skill drives a three-tool pipeline:
+
+1. **`memory-ingest-extract`** — pulls text from PDF/markdown/plain-text and caches it under the `attachmentId`. No chunking — the chunker has moved upstream into LLM-driven section classification.
+2. **`memory-classify`** — calls Claude Haiku with the loaded ontology and the cached text; returns typed sections (`{kind, title, body, properties, anchorEdge, related}`). Every returned `kind` is verified against the live ontology label set; invalid labels become `UNMAPPED` so a hallucination never reaches the writer.
+3. **`memory-ingest`** — writes typed graph nodes (Position, Service, Credential, etc.) anchored to `UserProfile` / `LocalBusiness` / `Person` / `Organization` via natural ontology edges, plus `(KnowledgeDocument)-[:REFERENCES]->(typed)` links. UNMAPPED sections become generic `:Section` nodes hanging off the document via `HAS_SECTION` (legacy fallback) so free-form prose retrieval still works.
+
+### Scope
+
+`memory-ingest` requires a `scope` value on every call. The admin agent confirms the scope with the operator before dispatching:
+
+- **public** — visible to public agents and the admin. Use for business knowledge that customers or visitors should be able to ask about.
+- **shared** — visible to all agents on the account but not surfaced to unauthenticated public visitors.
+- **admin** — visible only to the admin agent. Use for sensitive content (contracts, credentials, internal processes).
+
+If the user's intent is unambiguous from context — e.g., "save this for the sales agent" implies public, "this is just for my reference" implies admin — confirm the inferred scope rather than asking.
+
+### Keywords
+
+The classifier extracts topic keywords as `documentKeywords`; the user can supply their own as `userKeywords`. Both are merged additively (lowercase, trimmed, deduplicated) and stored on the `KnowledgeDocument.keywords` array. User-supplied keywords appear first.
+
+After a successful `memory-ingest` call, the dispatching admin agent should:
+1. Display the document summary and the extracted keywords to the user.
+2. Prompt for user keywords if none were supplied with the brief.
+3. If the user provides additional keywords post-ingest, call `memory-update` on the `documentNodeId` with the merged array.
+
+Keywords support user-defined collections via naming convention (e.g., `["reports", "reports/quarterly", "reports/quarterly/q1-2026"]`).