@rubytech/create-maxy-code 0.1.138 → 0.1.142

package/payload/platform/plugins/memory/references/schema-base.md

@@ -40,7 +40,7 @@ When loading this reference, confirm which schema files were consulted by noting
 | WhatsApp Conversation (legacy) | `WhatsAppConversation` | extends `schema:Conversation` | — | `accountId`, `conversationId`, `archiveSourceFile`, `firstMessageAt`, `lastMessageAt`, `participantCount`, `messageCount`, `scope`, `createdByAgent`, `createdBySession`, `createdAt` |
 | WhatsApp Message (legacy) | `WhatsAppMessage` | extends `schema:Message` | — | `accountId`, `conversationId`, `messageId`, `dateSent`, `body`, `senderName`, `sequenceIndex`, `scope`, `createdByAgent`, `createdBySession`, `createdAt` |
 | ConversationArchive | `ConversationArchive` | platform-native (chunked conversation archive parent) | — | `accountId`, `conversationIdentity`, `archiveSourceFile`, `summary`, `keywords`, `lastIngestedMessageHash`, `lastIngestedMessageAt`, `lastIngestedArchiveSha256`, `scope`, `createdByAgent`, `createdBySession`, `createdAt` |
-| Email | `Email` | extends `schema:Message` | RFC 5322 | `accountId`, `messageId`, `dateSent`, `sender`, `recipient`, `subject`, `body`, `authorshipMode` |
+| Email thread | `KnowledgeDocument {source:'email'}` | Per-thread document (Task 321 retired the `:Email` label) | RFC 5322 | `accountId`, `attachmentId`, `subject`, `body` (chronological transcript), `messageIds` (array), `messages` (JSON-serialized per-message envelopes), `firstReceivedAt`, `lastReceivedAt`, `direction`, `authorshipMode` |
 | SocialPost | `SocialPost` | `schema:SocialMediaPosting` | — | `accountId`, `platform` (linkedin/twitter/instagram/…), `body`, `datePublished`, `authorshipMode` |
 | VoiceProfile | `VoiceProfile` | platform-native (Task 356 — authorial-voice style card) | — | `accountId`, `adminUserId`, `styleCard`, `generatedAt`, `corpusSize`, `feedbackEntries` |
 | VoiceEdit | `VoiceEdit` | platform-native (Task 356 — operator edit on an agent draft) | — | `accountId`, `adminUserId`, `originalText`, `editedText`, `intent`, `occurredAt` |
@@ -62,9 +62,9 @@ When loading this reference, confirm which schema files were consulted by noting
 
 **Position** carries a single role held by a `UserProfile` at an `Organization` — its title, dates, and per-role properties (e.g. achievement bullets in `description`, `endDate` for a finished role). Each role is its own node so it can carry its own structure; multiple Positions per UserProfile (career history); one Organization may host many Positions across many UserProfiles. Written by the `document-ingest` skill when a CV section classifies as `Position`. The natural pattern is `(:UserProfile)-[:HAS_POSITION]->(:Position)-[:AT]->(:Organization)` — never set the employer name as a property on Position; always create the AT edge to the (MERGEd) Organization.
 
-**`authorshipMode` on content labels (Task 356).** Every `:KnowledgeDocument`, `:Email`, `:Message`, `:SocialPost`, and `:Section:Conversation` write carries an `authorshipMode` enum drawn from `human-only | human-led-agent-assisted | agent-led-human-reviewed | agent-only | unknown`. The value records who actually wrote the content body, not who triggered the write. `human-only` means every word of the body came from the operator; `human-led-agent-assisted` is operator-authored with light agent polish (the operator chose every claim and structure); `agent-led-human-reviewed` is agent-drafted then operator-edited before send; `agent-only` is pure agent output the operator did not touch. The voice-mirror distillation walks the corpus where `authorshipMode IN ['human-only', 'human-led-agent-assisted']` — both modes carry voice signal. `:Section:Conversation` chat-archive chunks (WhatsApp / Telegram / Signal exports ingested under `:ConversationArchive`-[:HAS_SECTION]->`) are first-class voice corpus and the highest-leverage signal source because chat captures the unguarded voice in a way email rarely does. Legacy nodes default to `unknown` until reclassified via the voice-mirror backfill flow. The per-label authorshipMode index makes the distillation walk filter cheap; the `:Section` index covers `:Section:Conversation` via the base label. Writers that cannot determine the mode (e.g. bulk archive imports) write `unknown` rather than guessing.
+**`authorshipMode` on content labels (Task 356).** Every `:KnowledgeDocument` (including email-source threads), `:Message`, `:SocialPost`, and `:Section:Conversation` write carries an `authorshipMode` enum drawn from `human-only | human-led-agent-assisted | agent-led-human-reviewed | agent-only | unknown`. The value records who actually wrote the content body, not who triggered the write. `human-only` means every word of the body came from the operator; `human-led-agent-assisted` is operator-authored with light agent polish (the operator chose every claim and structure); `agent-led-human-reviewed` is agent-drafted then operator-edited before send; `agent-only` is pure agent output the operator did not touch. The voice-mirror distillation walks the corpus where `authorshipMode IN ['human-only', 'human-led-agent-assisted']` — both modes carry voice signal. `:Section:Conversation` chat-archive chunks (WhatsApp / Telegram / Signal exports ingested under `:ConversationArchive`-[:HAS_SECTION]->`) are first-class voice corpus and the highest-leverage signal source because chat captures the unguarded voice in a way email rarely does. Legacy nodes default to `unknown` until reclassified via the voice-mirror backfill flow. The per-label authorshipMode index makes the distillation walk filter cheap; the `:Section` index covers `:Section:Conversation` via the base label. Writers that cannot determine the mode (e.g. bulk archive imports) write `unknown` rather than guessing.
 
-**Voice profile pattern (Task 356).** `(:AdminUser)-[:HAS_VOICE_PROFILE]->(:VoiceProfile)`. The styleCard is YAML serialized to a string property containing sentence-length distribution, register, favoured/avoided constructions and words, taboos, opening/closing patterns, and exemplar sentences. `(:VoiceProfile)-[:LEARNED_FROM]->(:KnowledgeDocument|:Email|:Message|:SocialPost|:Section)` links the profile to every node in its source corpus so the operator can audit what drove the distillation. Each operator edit on an agent draft becomes `(:VoiceEdit)-[:FEEDBACK_FOR]->(:VoiceProfile)` with the original/edited bodies plus a Haiku-summarised `intent` so the next distillation knows what to adjust.
+**Voice profile pattern (Task 356).** `(:AdminUser)-[:HAS_VOICE_PROFILE]->(:VoiceProfile)`. The styleCard is YAML serialized to a string property containing sentence-length distribution, register, favoured/avoided constructions and words, taboos, opening/closing patterns, and exemplar sentences. `(:VoiceProfile)-[:LEARNED_FROM]->(:KnowledgeDocument|:Message|:SocialPost|:Section)` links the profile to every node in its source corpus so the operator can audit what drove the distillation. Each operator edit on an agent draft becomes `(:VoiceEdit)-[:FEEDBACK_FOR]->(:VoiceProfile)` with the original/edited bodies plus a Haiku-summarised `intent` so the next distillation knows what to adjust.
 
 **Idea** is a forward-only write surface for original-thinking candidates extracted from admin-side conversations by the `signal-detector` specialist (dispatched only by the admin agent's Stop hook). `body` is the verbatim operator statement; `conversationId` denormalises the source conversation; `scope` is always `"admin"`. Never written by any other path. No dedup or clustering at write time — let the brain accumulate first.
 
@@ -189,7 +189,7 @@ Do not write placeholder values ("TBD", "unknown", empty strings) for properties
 (:KnowledgeDocument)-[:REFERENCES]->(:*)
 (:KnowledgeDocument)-[:HAS_SECTION]->(:Section)
 (:AdminUser)-[:HAS_VOICE_PROFILE]->(:VoiceProfile)
-(:VoiceProfile)-[:LEARNED_FROM]->(:KnowledgeDocument|:Email|:Message|:SocialPost|:Section)
+(:VoiceProfile)-[:LEARNED_FROM]->(:KnowledgeDocument|:Message|:SocialPost|:Section)
 (:VoiceEdit)-[:FEEDBACK_FOR]->(:VoiceProfile)
 (:KnowledgeDocument)-[:HAS_AEO_AUDIT]->(:AEOAudit)
 (:Message)-[:PART_OF]->(:Conversation)

package/payload/platform/plugins/memory/skills/conversation-archive/SKILL.md

@@ -13,7 +13,7 @@ One skill, one bash entry, one writer. The pipeline is identical for every conve
 
 ## Confirmed sources (Phase 0)
 
-`whatsapp` ships today (relocated grammar from the retired `whatsapp-import` plugin). Other sources land as needed:
+`whatsapp` ships today (relocated grammar from the retired `whatsapp-import` plugin). `x-dm` ships alongside the `x-import` plugin (Task 323) — driven by the x-import skill, one invocation per dmConversation slice. Other sources land as needed:
 - `telegram` — Telegram JSON export
 - `signal` — Signal text export
 - `linkedin-messages` — LinkedIn DM thread export (LinkedIn *connections* stay flat-dataset; only DMs route here)
@@ -21,6 +21,7 @@ One skill, one bash entry, one writer. The pipeline is identical for every conve
 - `meeting-minutes` — operator-supplied meeting notes
 - `imessage` — iMessage backup export
 - `slack` — Slack channel export
+- `x-dm` — X (Twitter) Direct Messages, dispatched by the `x-import` skill from `data/direct-messages.js` / `data/direct-messages-group.js` — one bash invocation per dmConversation slice; senders carry numeric X senderIds resolved to `:Person` / `:AdminUser` upstream in the x-import skill
 
 Until a normaliser ships, the bash entry loud-fails with the implemented set listed in the error.
 

package/payload/platform/plugins/memory/skills/document-ingest/SKILL.md

@@ -15,6 +15,7 @@ Ingests any unstructured input — documents (PDF, text, transcript, web page) a
 |---|---|---|---|---|
 | PDF / text / web (default) | `:KnowledgeDocument` | `:Section:<Kind>` from closed enumeration (`Position`, `Chapter`, `Parties`, …) | `attachmentId` | `document` |
 | Chat archive (`_chat.txt`) | `:ConversationArchive` | `:Section:Conversation` | `conversationIdentity` | `chat` |
+| X (Twitter) tweet-stream transcript (rendered by `x-import`) | `:KnowledgeDocument` (`source='x'`) | `:Section:<Kind>` from closed enumeration | `attachmentId` | `document` |
 
 The classifier in `memory-classify` decides which section kinds each section maps to (document mode) or chunks the archive into topic-bounded `:Section:Conversation` nodes (chat mode). The skill orchestrates the pipeline; the classifier reads the loaded ontology; the writer enforces the validator. **Classifier failure is terminal — the ingest aborts entirely; nothing is written. Loud failures, never silent landfill.**
 

package/payload/platform/plugins/notion-import/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "notion-import",
+  "description": "Import a Notion workspace export (markdown + CSV directory) into the Maxy Neo4j graph. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

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

@@ -0,0 +1,27 @@
+---
+name: notion-import
+description: "Import a Notion workspace export (markdown + CSV directory) 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":"notion-import"}}
+---
+
+# Notion Import
+
+Ingests a Notion workspace export (the native "Export all workspace content" markdown + CSV dump) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under `specialists:database-operator`, which owns graph-write delegation from admin.
+
+## When this applies
+
+The admin agent delegates to `specialists:database-operator` when the operator drops a Notion export directory (or zip path) into chat and asks to import it. The specialist runs the skill's import-provenance confirmation flow before any page or row is read, then walks the export.
+
+## Intra-plugin growth
+
+A Notion export contains pages (`.md`), databases (CSV pairs — schema CSV plus rows CSV), nested page subdirectories, and an `attachments/` tree. The skill ships four references covering the four shapes the export expresses — workspace traversal, database parsing, page-tree hierarchy, attachment copy. Per-database-type references land here as new files under `references/` as operators surface new shapes; they do not become new plugins.
+
+## Relationship to other plugins
+
+- **memory** — the underlying Cypher-write surface used by the skill (`memory-write`, `memory-update`, `memory-search`). Every node carries `source='notion'` + `createdByAgent='notion-import'` for provenance.
+- **database-operator specialist** — owns execution. See the delegation clause in [database-operator.md](../../templates/specialists/agents/database-operator.md).
+- **linkedin-import** — sibling skill-only import plugin (different specialist owner — `librarian` predates the database-operator delegation doctrine). The two plugins share no code.

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

@@ -0,0 +1,114 @@
+---
+name: notion-import
+description: Import a Notion workspace export (markdown + CSV) into a {{productName}} Neo4j graph. Triggers when the user asks to import a Notion workspace, ingest a Notion export, or mentions a `Export-*.zip` / unzipped Notion export directory. Pages become `:KnowledgeDocument` nodes, database rows become typed entities (or `:KnowledgeDocument` if no schema mapping fits), database schemas become `:KnowledgeDocument` siblings, hierarchy is preserved via `:HAS_SECTION`, attachments are copied locally and written as `:DigitalDocument`.
+---
+
+# Notion Import
+
+**Invoked from `specialists:database-operator`** when the operator drops a Notion workspace export directory (or `Export-*.zip` path) and asks to import it. The admin agent dispatches the database-operator; the database-operator loads this skill.
+
+**Anchor model.** A Notion export does not have a single subject the way a LinkedIn archive does — pages have multiple authors, databases are shared workspaces, mentions span the whole org. The skill anchors **import provenance** on the importing `:AdminUser` via `IMPORTED_BY` (so every node in the import can be traced back to who pushed the button); page authorship is captured separately via `AUTHORED` when the export records an author. The `:AdminUser` is identity, not subject — pages are not "owned" by the importer.
+
+Every node this skill writes carries an `importId` property (UUID per skill run) so a future dream-cycle pass can detect orphans or selectively re-ingest.
+
+## Import-provenance confirmation (mandatory first step)
+
+A Notion export is dropped by one operator on behalf of one workspace. Before any file is read, the skill confirms two things:
+
+1. **Importing AdminUser.** The `:AdminUser` who pushed the button. Default is the live operator (the session's userId); confirm by echoing `userId=<id> name=<name>` and accepting yes/no. If the operator is importing on behalf of someone else — a partner, a client whose workspace they're staging — accept either an existing AdminUser userId or a new `:Person` natural-key (`givenName` + `familyName` + at least one of `email` / `telephone`) as the importing identity. Persist as `$importerNodeId`.
+2. **Workspace label.** A short human label (`"Joel's personal workspace"`, `"Rubytech ops"`) used as the value of `:NotionWorkspace.name`. One `:NotionWorkspace` node is MERGEd per `(accountId, name)` natural key; re-imports of the same workspace match it.
+
+The skill refuses to read the export directory until both values are echo-confirmed.
+
+## Anchor shape
+
+```
+(:AdminUser {userId: $importerUserId})
+  -[:IMPORTED { importId, source: 'notion', startedAt }]->
+    (:NotionWorkspace { accountId, name })
+      -[:HAS_SECTION]-> (:KnowledgeDocument { kind: 'notion-page', notionId, importId })
+      -[:HAS_SECTION]-> (:KnowledgeDocument { kind: 'notion-database', notionId, importId })
+```
+
+`:NotionWorkspace` is the only new label the skill needs; everything below it reuses {{productName}} canonical labels (`:KnowledgeDocument`, `:Person`, `:Organization`, `:DigitalDocument`). Page hierarchy from Notion's parent-child relation is written as `:HAS_SECTION` between `:KnowledgeDocument` pages.
+
+## Invariants
+
+1. **Schema first.** No new constraints or indexes are required; the canonical schema in [`platform/plugins/memory/references/schema-base.md`](../../../../plugins/memory/references/schema-base.md) covers every label this skill writes. If the operator's workspace surfaces a database shape no canonical label fits, the rows are written as `:KnowledgeDocument` with `kind: 'notion-row'` and the gap is reported to admin — the skill does not mint new labels at runtime.
+2. **Provenance confirmed first.** No file is read until `$importerNodeId` (AdminUser or external Person) and `$workspaceName` are persisted and echo-confirmed.
+3. **Closed edge vocabulary.** Edges written are drawn from `schema-base.md` only. Unmapped Notion relations (a custom DB-to-DB link the operator named `sponsored_by`, say) land as `:MENTIONS` from the source page's `:KnowledgeDocument`, with the Notion relation label stored as a property (`mentionContext: '<relation-name>'`). `RELATES_TO` is **not** a schema edge and is not used.
+4. **Account isolation on fuzzy resolves.** Every inline `@person` mention resolves against `:Person {accountId: $accountId}` — never label-only. A "John Smith" mention in the importing account never matches a `:Person` in another account, even if the names are identical. When no in-account match is found, the mention is written as a new `:Person` with `givenName` / `familyName` parsed from the mention text and `source='notion'`.
+5. **Idempotent MERGE on Notion IDs.** Every Notion page and row carries a stable Notion UUID. Pages MERGE on `(accountId, notionId)`; database rows MERGE on `(accountId, notionId)`; attachments MERGE on `(accountId, sha256)`. Re-import of the same export is a property-update no-op on existing nodes — `skipped` counter advances, no duplicates.
+6. **Provenance stamps.** Every new node: `createdByAgent='notion-import'`, `createdBySource='notion'`, `createdBySession=$sessionId` (UUID per skill run), `createdAt=datetime()`, `importId=$importId`, plus `source='notion'`.
+7. **Bulk writes route through `memory-archive-write`; per-node `memory-write` is only used for the workspace anchor.** The walk produces three buffered payloads (pages, database rows per label, deferred relations), each submitted as one `mcp__plugin_memory_memory__memory-archive-write` call with the matching `archiveType`. The server batches 500 rows per transaction, returns aggregate counters, and gives the import per-chunk atomicity. `mcp__plugin_memory_memory__memory-search` is still used for inline-mention and author resolution (per-mention lookup happens during the walk, before any write). No raw Cypher, no Bash improvisation. If a write shape the skill needs is missing from the archive-write surface, the gap is filed as a follow-up task — never improvised.
+
+## Execution model
+
+1. Run the provenance-confirmation flow. Persist `$importerNodeId`, `$workspaceName`, `$importId` (fresh UUID), `$sessionId`.
+2. MERGE the `:NotionWorkspace { accountId, name }` and the `(:AdminUser)-[:IMPORTED]->(:NotionWorkspace)` edge via `memory-write`. Persist the resulting `:NotionWorkspace` `elementId` as `$workspaceNodeId` — every subsequent archive-write call passes it as `ownerNodeId`.
+3. Walk the export directory per [workspace-export.md](references/workspace-export.md) — classify each entry as page (`.md`), database schema (`<db-name>.csv` paired with row CSVs), database rows, attachment subdirectory, or nested page subdirectory. The walk **buffers** parsed output into three lists: `pageBuffer`, `dbRowBufferByLabel` (keyed by canonical label + databaseNotionId), and `deferredRelations`. No writes are issued during the walk except inline-mention `memory-search` lookups.
+4. For each shape, follow the matching reference to fill the buffers:
+   - Pages → [page-tree.md](references/page-tree.md). Each parsed page becomes one `NotionPageRow` in `pageBuffer`. Top-level pages set `parentNotionId: null`; nested pages keep the enclosing page's `notionId`. Inline `@person` mentions resolved per Invariant 4 — each match appends a `MENTIONS` entry to `deferredRelations`. Page-to-page `HAS_SECTION` (every non-workspace parent) is appended to `deferredRelations` with `edgeType: 'HAS_SECTION'`, regardless of in-batch ordering — the server resolves them once every node is MERGEd in pass-2.
+   - Databases → [databases.md](references/databases.md). The database itself is MERGEd via `memory-write` as `:KnowledgeDocument {kind: 'notion-database', notionId}` before any rows are queued (the row handler verifies the parent exists). Each row joins `dbRowBufferByLabel[label][databaseNotionId]`. Notion's typed relation columns become entries in `deferredRelations` (canonical edge type when the schema maps, `MENTIONS` with `mentionContext` otherwise).
+   - Attachments → [attachments.md](references/attachments.md). Copied to `{accountDir}/archive/notion/<importId>/`, content-hashed, written as `:DigitalDocument {kind: 'notion-attachment', sha256}` via `memory-write` (one per attachment — attachments are not bulk-batched because the file copy itself is the long pole). Each attachment appends a `MENTIONS` or canonical `HAS_ATTACHMENT` entry to `deferredRelations` when wired into the typed-edge schema.
+5. **Flush phase — three batched archive-write calls.** After the walk completes:
+   1. `memory-archive-write archiveType='notion-pages' ownerNodeId=$workspaceNodeId importId=$importId rows=pageBuffer` — server MERGEs every page and attaches workspace-root `HAS_SECTION` for `parentNotionId: null` rows. Optional `AUTHORED` edges write when `authorPersonNodeId` is set.
+   2. For each `(label, databaseNotionId)` key: `memory-archive-write archiveType='notion-database-rows' ownerNodeId=$workspaceNodeId importId=$importId databaseNotionId=<…> label=<…> rows=<bufferedRows>`.
+   3. `memory-archive-write archiveType='notion-relations-pass-2' ownerNodeId=$workspaceNodeId rows=deferredRelations` — server buckets relations by `edgeType` from the closed allowlist (`MENTIONS`, `WORKS_FOR`, `OWNS`, `ASSIGNED_TO`, `PART_OF`, `ATTENDED`, `HAS_SECTION`, `AUTHORED`). Unknown edge types and missing endpoints are counted, not thrown.
+6. Emit `[notion-import] importId=<id> pages=<n> rows=<n> relations=<n> mentions=<n> attachments=<n> skipped=<n> ms=<elapsed>` at completion, aggregating the counters returned by each archive-write call. Per-file errors emit `[notion-import:error] file=<path> reason=<…>` during the walk; the skill continues past parse failures so a single bad file does not abort the entire import. Per-batch transaction failures surface in the archive-write `errors[]` array — log each as `[notion-import:batch-error] archiveType=<…> offset=<…> reason=<…>` and continue with subsequent batches; the same `importId` re-run is idempotent and replays only the chunks that did not commit.
+
+## Selective-ingest gate (bulk imports)
+
+A Notion workspace typically contains 200–5,000 pages. Writing all of them in one shot defeats compression-on-write — most pages will never be queried, and the noise compounds with every subsequent import.
+
+**Threshold:** when the export walk discovers more than **200 pages or 500 database rows**, pause and ask the operator to filter before any write begins. Natural filter axes for Notion:
+
+- **Top-level page subtree** — "only pages under `Engineering/`", "only `Personal/Journal/`".
+- **Database name** — "only the `People` and `Projects` DBs", "skip the `Daily Standup` DB".
+- **Last-edited date** — "only pages edited since 2024-01-01".
+
+The operator picks one axis or a combination. The skill applies the filter to the walk's candidate set before issuing any write. Re-importing later with a wider filter hits the same `(accountId, notionId)` natural keys; existing nodes are property-updated, only the new-only delta is created.
+
+## File-shape roster
+
+The Notion export is a directory of:
+
+| Shape | Detection | Reference |
+|-------|-----------|-----------|
+| Page (markdown) | `*.md` file at any depth, with a Notion UUID suffix in the filename | [page-tree.md](references/page-tree.md) |
+| Database schema | `<name>.csv` with a sibling directory of the same name containing per-row `.md` files | [databases.md](references/databases.md) |
+| Database row | `<row-name>.md` inside a database subdirectory, with the parent CSV's column set as front-matter properties | [databases.md](references/databases.md) |
+| Attachment | Any file under an `<image>/`, `<pdf>/`, or other media-bearing subdirectory adjacent to its referencing page | [attachments.md](references/attachments.md) |
+| Nested workspace subtree | A directory whose name carries a Notion UUID and contains both `.md` pages and CSV databases | [workspace-export.md](references/workspace-export.md) |
+
+## Explicitly out of scope
+
+- **Notion API live sync.** This is one-shot from a manual export only. Live API sync (incremental delta, webhook listening, two-way write-back) is a separate task if commissioned.
+- **Formulas, rollups, synced blocks.** The export materialises computed values as text; the skill imports the materialised text but not the formula source. Re-computing rollups against the graph is downstream work.
+- **Notion Web Clipper saved pages.** Clipper pages live in a different export shape (HTML, not markdown) and have different semantics (third-party source ingest). They land in a future task, not here.
+- **Back-sync to Notion.** Writing changes from the graph back into the Notion workspace is not in scope.
+- **Streaming progress events from the archive-write server.** Counters are returned only at completion of each archive-write call; per-row progress is a separate observability task if commissioned.
+
+## Schema-mapping table
+
+The skill maps Notion shapes to canonical {{productName}} labels and edges. Schema additions are last resort — every row below uses an existing label from `schema-base.md`.
+
+| Notion shape | Canonical label | Notes |
+|--------------|-----------------|-------|
+| Workspace | `:NotionWorkspace` | New label, single property `name` plus `accountId`. Only new label introduced by this skill. |
+| Page | `:KnowledgeDocument { kind: 'notion-page' }` | Body markdown stored as `text`. Hierarchy via `:HAS_SECTION`. |
+| Page authored-by | `(:Person)-[:AUTHORED]->(:KnowledgeDocument)` | When the export records an author, resolve to in-account `:Person`. |
+| Database (the table itself) | `:KnowledgeDocument { kind: 'notion-database' }` | Schema preserved as `schema` (JSON-stringified property list). |
+| Database row, canonical-fit | `:Person`, `:Organization`, `:Project`, `:Task`, `:Event` | Database name + columns drive label selection. A "People" DB with `email`/`telephone` columns → `:Person`. |
+| Database row, no fit | `:KnowledgeDocument { kind: 'notion-row' }` | Properties preserved on the node; surface to admin in the completion log if any DB lands here entirely. |
+| Notion relation, schema-mapped | Canonical edge from `schema-base.md` | A relation column named `works_at` between People and Companies → `(:Person)-[:WORKS_FOR]->(:Organization)`. |
+| Notion relation, unmapped | `:MENTIONS { mentionContext: '<relation-name>' }` | Source page `:KnowledgeDocument` → target. Preserves the Notion relation name for later audit. |
+| Inline `@person` mention | `(:KnowledgeDocument)-[:MENTIONS]->(:Person)` | Account-filtered fuzzy resolve per Invariant 4. |
+| Attachment | `:DigitalDocument { kind: 'notion-attachment', sha256 }` | Files copied to `{accountDir}/archive/notion/<importId>/`. |
+| Page hierarchy | `(:KnowledgeDocument)-[:HAS_SECTION]->(:KnowledgeDocument)` | Parent-of-child per Notion's nesting. |
+
+If the operator's workspace introduces a database that fits none of the canonical labels and is not satisfied by the `:KnowledgeDocument` fallback, surface the gap to admin in the completion summary — never mint a new label at runtime.
+
+## Natural-edge discipline (why this matters)
+
+Every edge written corresponds to a relationship the Notion export actually expresses. `:HAS_SECTION` is real — Notion explicitly records page parents. `:AUTHORED` is real when the export records it. `:WORKS_FOR` is real when a People DB has a Companies-relation column. Synthetic "attach-everything-to-the-importer" edges are forbidden — the importer is provenance (via `IMPORTED`), not the subject of every page. A workspace with thousands of unrelated pages does not get thousands of edges manufactured to "make it reachable"; the workspace-level `IMPORTED` edge already makes them reachable through the importer.

package/payload/platform/plugins/notion-import/skills/notion-import/references/attachments.md

@@ -0,0 +1,55 @@
+# attachments
+
+Reference for copying Notion attachments — images, PDFs, and other media — into the account's local archive and recording them as graph nodes.
+
+## Shape on disk
+
+Notion exports media files alongside the page that references them. The export's directory layout varies — small media may live in the same directory as the referencing `.md`, larger media in a sibling subdirectory named after the page. The skill does not assume a single layout; it follows attachment references **from the page markdown**, not by enumerating media files.
+
+Referenced shapes:
+
+- `![alt](Image%20Name%20<32-hex-notionId>.png)` — image embed.
+- `[Doc](Doc%20Name%20<32-hex-notionId>.pdf)` — file link.
+- HTML `<img src="...">` tags inside the markdown (older exports) — also captured.
+
+The referenced filename is URL-decoded to get the relative path on disk.
+
+## Where they go
+
+Attachments copy to `{accountDir}/archive/notion/<importId>/<sha256>.<ext>`:
+
+- `{accountDir}` is the account's directory (the same directory that holds `account.json`), resolved per the platform's existing `accountDir` convention used by `platform/lib/admins-write` and elsewhere.
+- `<importId>` is the UUID for this skill run — keeps a single import's attachments grouped on disk.
+- `<sha256>` is the content hash of the file, computed at copy time. Filename collisions on the same hash skip the copy (already present from a prior import of the same file).
+- `<ext>` is the original extension preserved from the source filename.
+
+The path scheme is deliberately content-hash-keyed so multiple pages referencing the same file (a logo embedded across many pages, say) share one copy on disk and one `:DigitalDocument` node in the graph.
+
+## What each attachment becomes
+
+One `:DigitalDocument { kind: 'notion-attachment' }` node per content hash:
+
+- `sha256` — the content hash; the MERGE natural key together with `accountId`.
+- `name` — original filename (without the Notion ID suffix where present).
+- `mimeType` — inferred from extension.
+- `bytes` — file size in bytes.
+- `localPath` — absolute path under `{accountDir}/archive/notion/<importId>/`.
+- `accountId`, `importId`, `source='notion'`, plus standard provenance per SKILL invariant 6.
+
+Page-to-attachment edge: `(:KnowledgeDocument)-[:HAS_ATTACHMENT]->(:DigitalDocument)`. One edge per referencing page; if a single page references the same attachment three times, one edge is MERGEd (idempotent).
+
+## Idempotency
+
+`:DigitalDocument` MERGEs on `(accountId, sha256)`. Re-import of the same file by content hash matches the existing node — `localPath` updates if the file was copied into a fresh `<importId>` directory, every other property stays. The `:HAS_ATTACHMENT` edge also MERGEs, so re-imports do not duplicate.
+
+## What the attachment step does NOT do
+
+- **Does not** OCR scanned PDFs or extract text from images. That belongs to a separate ingest step (a future task can chain `memory-ingest` to derive text from `:DigitalDocument` nodes by mime type).
+- **Does not** fetch from Notion's CDN. Notion exports are self-contained — every referenced file is in the zip. If a markdown reference points at an absolute Notion URL (not a relative export path), it is treated as an external link and a `:MENTIONS` edge to a `:KnowledgeDocument { kind: 'external-link', url }` is written instead, with no file copy.
+- **Does not** delete attachments on re-import when the page no longer references the file. Orphan attachment detection is a graph-prune concern, not an importer concern.
+
+## Failure modes
+
+- `[notion-import:error] reason=attachment-not-on-disk path=<rel-path>` — the page markdown references a file the walker cannot locate. Skip the copy, skip the edge, log.
+- `[notion-import:error] reason=copy-failed path=<rel-path> errno=<…>` — filesystem error during copy. Log and continue; the page itself is still written, only the attachment is missing.
+- `[notion-import:error] reason=hash-collision-different-content sha256=<hash>` — two files in the same import produced the same hash but the filenames disagree on extension. Should be impossible in practice; if observed, log and write both as separate `:DigitalDocument` nodes with disambiguated extensions.

package/payload/platform/plugins/notion-import/skills/notion-import/references/databases.md

@@ -0,0 +1,83 @@
+# databases
+
+Reference for ingesting Notion databases — both the database (schema) and its rows.
+
+## Shape on disk
+
+A Notion database lands as a `.csv` file plus a sibling directory of the same basename. The CSV is the table-view export; the directory contains one `.md` per row, with the row's properties as YAML front-matter and the row body as markdown below.
+
+```
+Projects 7a1b2c…/
+  Projects 7a1b2c….csv        ← schema + row table
+  Projects 7a1b2c…/             ← row markdowns
+    Phoenix Migration 9f3a…md
+    Q3 Strategy d4e5…md
+```
+
+The CSV columns are the database's properties. Column types are not encoded in the CSV directly — they are inferred from the values (date-shaped, URL-shaped, person-mention-shaped, relation-shaped). A relation column's cells contain the human title plus Notion ID of the linked row.
+
+## What the database itself becomes
+
+Each Notion database is written as one `:KnowledgeDocument { kind: 'notion-database' }` node:
+
+- `notionId` — the 32-hex ID from the CSV basename.
+- `name` — human title from the CSV basename.
+- `schema` — JSON-stringified list of `{ name, inferredType }` per column.
+- `parentPageNotionId` — the page that contains the database, if any.
+
+The database is attached to the workspace root via `(:NotionWorkspace)-[:HAS_SECTION]->(:KnowledgeDocument)` and, when nested under a page, also via `(:KnowledgeDocument {page-parent})-[:HAS_SECTION]->(:KnowledgeDocument {database})`.
+
+## Label selection for rows
+
+Per-row label is decided by the database's name and column set together — not by either alone.
+
+- **`:Person`** when the database name matches `^(people|contacts|crm|team|members?)$` (case-insensitive) AND the columns contain at least one of `email`, `phone`, `telephone`, `linkedin`. Properties map onto schema-base camelCase: `givenName` / `familyName` from a single `name` column split on first space (preserve `name` only if no canonical Person property fits); `email`, `telephone`, `jobTitle`, etc.
+- **`:Organization`** when the name matches `^(companies|orgs|organizations?|accounts)$` AND the columns contain `website` or `domain`.
+- **`:Project`** when the name matches `^projects?$` AND the columns contain at least one of `status`, `startDate`, `dueDate`, `owner`.
+- **`:Task`** when the name matches `^(tasks?|todo|to-?dos?|action items?)$` AND the columns contain at least one of `done`, `status`, `assignee`, `dueDate`.
+- **`:Event`** when the name matches `^(events?|meetings?|calendar)$` AND the columns contain `startDate` / `start` / `date`.
+- **`:KnowledgeDocument { kind: 'notion-row' }`** — fallback. The CSV columns are preserved on the node as properties. Surface to admin in the completion log if any database falls entirely into this bucket — it usually means the workspace has a custom DB shape worth handling explicitly in a future iteration.
+
+When admin's brief is ambiguous about which label a database should land in, the database-operator's `{ambiguity, proposed}` protocol applies — ask, don't guess.
+
+## Row write recipe
+
+For each row in the parsed CSV:
+
+1. **Confirm the parent database exists.** The database itself (`:KnowledgeDocument { kind: 'notion-database', notionId }`) is MERGEd via `memory-write` once, before any of its rows are queued. The `notion-database-rows` handler refuses the batch if the parent is missing.
+2. **Select the label** per the rules above. Allowlist: `Person`, `Organization`, `Project`, `Task`, `Event`, `KnowledgeDocument`.
+3. **Map CSV columns to schema-base properties.** Use canonical camelCase. Unknown columns land as properties on the node with their original column name preserved.
+4. **Buffer the row.** Append `{ notionId, properties }` to `dbRowBufferByLabel[label][databaseNotionId]`. The row carries node properties only; the HAS_SECTION edge to the parent database is written server-side at flush time.
+5. **Bucket relation columns into `deferredRelations`.** A relation column cell is `"Linked Row Title <32-hex-notionId>"`. For each cell, append a relation entry with `sourceNotionId` = this row's `notionId`, `targetNotionId` = the linked row's `notionId`. When the relation name maps to a canonical edge (table below), set `edgeType` accordingly; otherwise set `edgeType: 'MENTIONS'` and `properties: { mentionContext: '<relation-column-name>' }`. Pass-2 resolves targets — links to rows outside the import set are counted as `skippedUnknownTarget`, not errors.
+
+The actual writes happen at flush time: one `memory-archive-write` call per `(label, databaseNotionId)` key, then one final `memory-archive-write archiveType='notion-relations-pass-2'` call carrying every relation across all databases and pages.
+
+## Notion-relation → canonical-edge map
+
+Examples — the table is extensible per workspace, but the principle is fixed: a relation maps to a canonical edge only when the schema vocabulary in `schema-base.md` (Relationship Patterns + Edges introduced by document-ingest, plus any vertical-schema edges loaded at runtime) names a matching one.
+
+| Notion relation column name | Canonical edge |
+|-----------------------------|----------------|
+| `works_at`, `company`, `employer` | `(:Person)-[:WORKS_FOR]->(:Organization)` |
+| `assignee`, `owner` | `(:Person)-[:OWNS]->(:Project)` / `(:Person)-[:ASSIGNED_TO]->(:Task)` per row label |
+| `project`, `belongs_to_project` | `(:Task)-[:PART_OF]->(:Project)` |
+| `attended`, `participants` | `(:Person)-[:ATTENDED]->(:Event)` |
+| `mentions` (Notion's own typed mention relation) | `:MENTIONS` |
+| anything else | `:MENTIONS { mentionContext: '<relation-column-name>' }` |
+
+The mapping table lives in this reference — not in a server-side enum — so a workspace with custom relation names is handled by extending this file, not by code change.
+
+## Forward-reference resolution
+
+A row's relation column may point at a row not yet written (later in the walk or in a later batch). The buffered execution model handles this naturally:
+
+- **Pass 1 — node writes.** Pages flush via `notion-pages`; database rows flush via one `notion-database-rows` call per `(label, databaseNotionId)` key. No relations are written in pass 1.
+- **Pass 2 — relations.** Once every page and row is MERGEd, `notion-relations-pass-2` flushes `deferredRelations`. Source and target are located by `(accountId, notionId)`; missing endpoints are counted as `skippedUnknownTarget`, not errors.
+
+Two passes are deterministic and keep every write idempotent. The completion log reports the `relationsCreated` / `relationsMatched` counters from pass 2.
+
+## Failure modes
+
+- `[notion-import:error] reason=row-schema-mismatch file=<path>` — the row's front-matter has properties not in the parent CSV's schema. Write the row with the union of properties; log the mismatch; continue.
+- `[notion-import:error] reason=relation-target-not-found notionId=<id>` — pass 2 reported `skippedUnknownTarget > 0` (a row outside the operator's filter, or an externally-linked workspace row). The pass-2 counter captures the total; per-edge detail is not logged because the server only sees the bucketed list, not the source manifest.
+- `[notion-import:error] reason=label-ambiguous db=<name>` — the name + column heuristic matched no canonical label and the operator's brief did not specify. Fall back to `:KnowledgeDocument { kind: 'notion-row' }` and surface the gap in the completion log.

package/payload/platform/plugins/notion-import/skills/notion-import/references/page-tree.md

@@ -0,0 +1,61 @@
+# page-tree
+
+Reference for ingesting Notion pages — the `.md` files at every depth of the export.
+
+## Shape on disk
+
+A Notion page is a markdown file with a 32-hex Notion ID suffix in its basename. Front-matter at the top (when present) carries page-level properties: `Created`, `Created by`, `Last edited`, `Last edited by`, tags. The body is markdown — headings, paragraphs, lists, embedded media references, inline `@person` mentions, and inline `@page` mentions (page-to-page links).
+
+A page with children lives alongside a directory of the same basename containing the child pages and their own subdirectories.
+
+## What each page becomes
+
+One `NotionPageRow` appended to `pageBuffer`; the server-side `notion-pages` handler MERGEs it as a `:KnowledgeDocument { kind: 'notion-page' }` at flush time. Row fields:
+
+- `notionId` — 32-hex from the basename.
+- `title` — human title from the basename.
+- `text` — full markdown body (front-matter stripped; the front-matter fields are mapped to row fields below).
+- `parentNotionId` — `null` for workspace-root pages; otherwise the basename `notionId` of the enclosing directory.
+- `notionCreatedAt`, `notionLastEditedAt` — ISO 8601 strings from front-matter `Created` / `Last edited`, or `null`.
+- `authorPersonNodeId` — elementId of an in-account `:Person` resolved per the Authorship section below, or `null`.
+
+Provenance (`accountId`, `importId`, `source='notion'`, `createdByAgent='notion-import'`, `createdBySession`, `createdAt`) is stamped server-side; the row does not carry it.
+
+## Hierarchy
+
+Page hierarchy is written as `:HAS_SECTION` between `:KnowledgeDocument` nodes:
+
+- **Top-level pages** — `parentNotionId: null` in the row. The `notion-pages` handler attaches `(:NotionWorkspace)-[:HAS_SECTION]->(:KnowledgeDocument)` at insert time.
+- **Nested pages** — every non-null `parentNotionId` is appended to `deferredRelations` with `edgeType: 'HAS_SECTION'`. The `notion-relations-pass-2` flush resolves them once every page is MERGEd, including parents that land in a later batch than their children.
+
+The parent's `notionId` is the basename of the enclosing directory.
+
+## Authorship
+
+When the front-matter records `Created by` (or `Author`), resolve the named user against in-account `:Person` per SKILL invariant 4 (account-filtered fuzzy match on `givenName + familyName`). Write `(:Person)-[:AUTHORED]->(:KnowledgeDocument)` when a match is found or a new `:Person` is created. If the front-matter only carries a Notion display name that resolves to no in-account `:Person` and the import flow already created a `:Person` for an earlier mention with the same display name, MERGE on `(accountId, displayName)` so a Notion user named once in front-matter and once inline becomes one node, not two.
+
+`Last edited by` is not currently written as an edge — page-level edit provenance is downstream work (a future task can add `:LAST_EDITED_BY` if needed).
+
+## Inline `@person` mentions
+
+Notion exports inline person mentions as plain text in the markdown body — typically the user's display name without an `@` prefix in the markdown source, but operators sometimes preserve `@`-prefixed text. The skill matches both shapes:
+
+1. Detect candidate mentions — bracketed names from Notion's link syntax `[Person Name](https://www.notion.so/...)`, plain `@`-prefixed tokens, and front-matter `Mentioned` lists (when present).
+2. For each candidate, run `mcp__plugin_memory_memory__memory-search` with `accountId` filter and the candidate's display name as the search term. Use the search's existing fuzzy semantics — do not invent a new matcher.
+3. On match, append a `MENTIONS` entry to `deferredRelations` (`sourceNotionId` = the page's `notionId`, `targetNotionId` requires the matched `:Person` to itself carry a `notionId` — if the `:Person` was created by this import the skill assigns one; if the match is an existing in-account `:Person` without a `notionId`, the mention is written via `memory-write` at walk time instead, because pass-2 endpoint resolution is by `(accountId, notionId)` only). On miss, the new `:Person { givenName, familyName, notionId: <fresh-uuid>, source='notion', accountId }` is created via `memory-write` immediately and the mention queued to pass-2 — the mention is preserved either way.
+
+The account-filter step is load-bearing. A "John Smith" mention in the importing account never matches a `:Person` in another account, even if the names collide. See SKILL invariant 4.
+
+## Inline `@page` mentions (page-to-page links)
+
+A page-to-page link in Notion exports as `[Other Page Title](Other%20Page%20Title%20<32-hex-notionId>.md)`. Append a `MENTIONS` entry to `deferredRelations` with `sourceNotionId` = the current page, `targetNotionId` = the linked page, and `properties: { mentionContext: 'page-link' }`. Pass-2 handles resolution — links to pages outside the import set are counted as `skippedUnknownTarget` in the pass-2 counters, not errors.
+
+## Idempotency
+
+Pages MERGE on `(accountId, notionId)`. Re-importing the same export with no changes is a no-op — every property update writes the same value back, every edge MERGE matches existing. The `skipped` counter advances on each unchanged page. Property-level updates (a page edited in Notion between exports) overwrite without versioning; the previous body is lost. A future task could write `:KnowledgeDocumentRevision` audit nodes if version history becomes a need.
+
+## Failure modes
+
+- `[notion-import:error] reason=front-matter-parse file=<path>` — front-matter is malformed YAML. Treat as no front-matter; write the page with body-only.
+- `[notion-import:error] reason=mention-search-failed name=<name>` — `memory-search` raised. Log and continue; the mention is dropped (no fallback Person creation when the search itself failed, only when it returned no match).
+- `[notion-import:error] reason=parent-not-found notionId=<id>` — the enclosing directory's `notionId` did not resolve to a `:KnowledgeDocument`. Anchor the orphan page to the `:NotionWorkspace` and log.

package/payload/platform/plugins/notion-import/skills/notion-import/references/workspace-export.md

@@ -0,0 +1,41 @@
+# workspace-export
+
+Reference for walking a Notion "Export all workspace content" directory.
+
+## What a Notion export looks like
+
+Notion's native export ("Settings → Workspace → Export all workspace content" with "Everything", "Markdown & CSV" format) produces a zip. Unzipped, the top level is a single directory named after the workspace plus a Notion UUID; nested inside is the page tree as the operator structured it.
+
+Two file shapes occur at every depth:
+
+- **Pages** — `Page Title <32-hex-notionId>.md`. The basename is the human title followed by the 32-character hex Notion ID (no dashes). The file body is markdown.
+- **Databases** — `Database Name <32-hex-notionId>.csv` paired with `Database Name <32-hex-notionId>/` directory. The CSV is the table view; the directory contains one `.md` per row plus an attachments tree.
+
+Nested page subtrees: a page with children becomes a directory `Page Title <notionId>/` alongside its `.md` file; the directory holds the child pages and their own subdirectories recursively.
+
+## What the walker does
+
+1. **Read the root.** First-level entries are the top-level pages and databases of the workspace.
+2. **Recurse depth-first** into each subdirectory, classifying entries on each pass.
+3. **Build the candidate manifest** — a flat list of `{kind, path, notionId, parentNotionId, depth}` records, one per page or row. This is the manifest the selective-ingest gate runs against, and the manifest the write loop consumes.
+4. **Apply the operator's filter** (top-level subtree, database name, last-edited date) by predicate-matching the manifest before any write begins.
+5. **Hand off** the filtered manifest to [page-tree.md](page-tree.md) for pages and [databases.md](databases.md) for database tables and rows. Attachments are handed off as referenced from pages, not walked separately — see [attachments.md](attachments.md).
+
+## Notion ID extraction
+
+The Notion ID is the last 32 hex characters of the basename, after the trailing space. Strip the `.md` / `.csv` suffix and the trailing space, then take the last 32 chars; the remainder is the human title. Notion IDs are stable across exports; they are the natural key the skill MERGEs on.
+
+## What the walker does NOT do
+
+- **Does not** read page or row body content. That happens at write time, per the page/database references.
+- **Does not** decide labels. Label selection happens in [databases.md](databases.md).
+- **Does not** open attachments. Hashing happens at the attachment-copy step.
+- **Does not** retry on partial exports. If a referenced child directory is missing, the parent page is still imported and the gap is logged.
+
+## Failure modes
+
+- `[notion-import:error] reason=basename-no-notion-id file=<path>` — basename does not end in a 32-hex Notion ID. Skip the file, continue the walk.
+- `[notion-import:error] reason=orphan-row file=<path>` — a row markdown lives inside a directory whose parent CSV is missing. Skip; the row cannot be typed without the schema.
+- `[notion-import:error] reason=zip-not-extracted path=<path>` — the operator pointed at a `.zip`. Unzip first; the skill does not call `unzip`.
+
+The walker never aborts on a single file's failure. Counts of skipped files appear in the completion log.

package/payload/platform/plugins/obsidian-import/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "obsidian-import",
+  "description": "Import an Obsidian vault (extracted directory of markdown notes + assets) into the Maxy Neo4j graph. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

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

@@ -0,0 +1,39 @@
+---
+name: obsidian-import
+description: "Import an Obsidian vault (extracted directory of markdown notes + assets) 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":"obsidian-import"}}
+---
+
+# Obsidian Import
+
+Ingests an extracted Obsidian vault (a directory tree of `.md` notes, frontmatter, wikilinks, tags, and embedded attachments) 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.
+
+## When this applies
+
+The admin agent delegates to `specialists:database-operator` when the operator drops an extracted Obsidian vault directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any markdown is read, then orchestrates the two-phase server-side import (dry-run → operator disambiguation → commit).
+
+## How parsing happens
+
+The skill does not parse markdown. Vault traversal, frontmatter YAML, wikilink regex, tag scanning, daily-notes detection, and attachment resolution all happen server-side inside `mcp__memory__obsidian-vault-import` (memory plugin). The skill is the operator-facing conversation surface only: confirm owner → select filters → invoke the tool with `mode='dry-run'` → present ambiguities → invoke with `mode='commit'` and the operator's resolutions.
+
+## Intra-plugin growth
+
+Reference docs land here as the parser surface grows — Canvas, Bases, Dataview queries each get a reference file when the parser supports them. They are not separate plugins.
+
+## Relationship to other plugins
+
+- **memory** — owns the parser (`platform/lib/obsidian-parser/`), the `obsidian-vault-import` MCP tool, and the `obsidian-vault` archiveType handler inside `memory-archive-write`. All graph writes happen through that surface.
+- **database-operator specialist** — owns execution. See [database-operator.md](../../templates/specialists/agents/database-operator.md) delegation clause.
+
+## Out of scope
+
+- Obsidian plugins, Dataview queries, Canvas, and Bases — text markdown only.
+- Realtime vault sync. One-shot import per upload.
+- Reverse export back to Obsidian.
+- Automatic compiled-truth backfill on imported entities — that happens via subsequent `memory-update` calls, not at import time.
+
+Each of the above can be added later as its own reference inside this plugin once a parser extension lands. Nothing silently flows in.