@rubytech/create-siteoffice-code 0.1.256

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:archive-ingest-operator`** when the operator drops a Notion workspace export directory (or `Export-*.zip` path) and asks to import it. The admin agent dispatches the archive-ingest-operator; the archive-ingest-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__plugin_memory_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.

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

@@ -0,0 +1,92 @@
+---
+name: obsidian-import
+description: Import an Obsidian vault (extracted directory of markdown notes, frontmatter, wikilinks, tags, embedded attachments) into a {{productName}} Neo4j graph. Triggers when the user asks to import an Obsidian vault, ingest Obsidian notes, or mentions an Obsidian export by path. Skill does not parse markdown — parsing is server-side inside `mcp__plugin_memory_memory__obsidian-vault-import`. The skill is the operator-conversation surface.
+---
+
+# Obsidian Import
+
+**Invoked from `specialists:archive-ingest-operator`** when the operator drops an extracted Obsidian vault directory (or references one by path) into chat. The admin agent dispatches the archive-ingest-operator; the archive-ingest-operator loads this skill.
+
+**Default parent.** Every `:KnowledgeDocument` (vault page), `:DefinedTerm` (tag), `:DigitalDocument` (attachment), and `:Concept` stub this skill writes is anchored to the vault-owner. That owner is either an existing `:AdminUser` (the operator's own vault, the common case) or an external `:Person` (a partner's vault ingested for reference). The skill refuses to start until the owner is confirmed — every `:HAS_NOTE` edge points from the owner to a page, and that containment is what keeps imported pages out of orphan territory.
+
+## Archive-owner confirmation (mandatory first step)
+
+A vault belongs to exactly one person — the user whose Obsidian app produced it. Every page, every wikilink that resolves to the owner's contacts, every embedded photo is theirs. The skill takes the 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 vault owner. Accept one of:
+   - An existing AdminUser userId from the list (typical — the operator's own vault).
+   - A new external Person identity (not yet an AdminUser) — create a fresh `:Person` with `givenName`, `familyName`, `email`/`telephone` (at least one) via `memory-write`, then use its `elementId` as the owner anchor.
+3. Echo the chosen owner back verbatim (`userId=<id> name=<name>` or `personId=<id> name=<name>`) and require explicit yes/no confirmation before the tool runs.
+4. Persist the confirmed owner as `$ownerNodeId` for the two tool invocations (dry-run + commit).
+
+Refusing to assume is load-bearing: a hard-coded "it's whoever's running this" would misattribute a partner's notes to the operator on first re-use.
+
+## Two-phase execution model
+
+Imports run in two MCP-tool calls with operator interaction between them. The phases are non-negotiable — there is no single-shot mode, because wikilink ambiguity resolution belongs to the operator and the parser refuses to guess.
+
+### Phase A — dry-run
+
+1. Invoke `mcp__plugin_memory_memory__obsidian-vault-import` with `mode='dry-run'`, the confirmed `ownerNodeId`, the absolute `extractedDir`, and the operator's selected `filters` (see [§Selective-ingest](#selective-ingest)).
+2. The tool walks the vault, parses everything server-side, classifies each wikilink (intra-vault page, fuzzy-matched existing entity, or stub), and returns:
+   - `importId` — quote this back in the commit call.
+   - `pagesDiscovered`, `pagesEligible`, `pagesUnchanged` — the operator sees the scope.
+   - `wikilinks.{page, entity, stub, ambiguous}` — distribution by resolution kind.
+   - `tagCount`, `attachmentCount`.
+   - `ambiguities[]` — each carries an `id`, the source page, the wikilink target text, and competing candidate sets (`pageCandidates`, `entityCandidates`). These are the only items the operator must adjudicate.
+   - `selectiveIngestSuggested` — true when `pagesEligible > selectiveIngestThreshold` and no filter was supplied. If true, go back to [§Selective-ingest](#selective-ingest) before continuing.
+3. Surface the summary to the operator. Show each ambiguity in plain English: "Page X has a wikilink `[[Y]]` that matches both vault note `Y.md` AND existing :Person {name:'Y Smith'} — which did you mean?" Accept three answers per ambiguity: page (and which one), entity (and which one), or stub (create a fresh :Concept node).
+
+### Phase B — commit
+
+1. Invoke `mcp__plugin_memory_memory__obsidian-vault-import` with `mode='commit'`, the same `ownerNodeId`, `extractedDir`, `filters`, the `importId` from Phase A, and a `resolutions` map keyed by each ambiguity `id` carrying the operator's decision.
+2. The tool re-walks the vault (parsing is deterministic + cheap), applies the resolutions, runs the content-hash idempotency filter against existing :KnowledgeDocument nodes (unchanged pages are skipped), copies embedded attachments to `{accountDir}/archive/obsidian/<importId>/`, then invokes `memory-archive-write` internally with `archiveType='obsidian-vault'`.
+3. The tool returns the same plan shape plus `written.{createdPages, mergedPages, createdTags, createdTagEdges, createdAttachments, createdAttachmentEdges, createdWikilinkEdges}`, `attachmentsCopied`, and any per-batch `errors`.
+
+After commit, surface counts in the chat: "Imported `N` new pages, updated `M` existing, created `K` wikilinks (`P` to vault pages, `E` to entities, `S` stub concepts), `T` tags, `A` attachments. Skipped `U` unchanged."
+
+## Selective-ingest
+
+The skill drives filter selection conversationally — not from a hardcoded list. Obsidian vaults vary too widely for a fixed filter axis. The natural axes are:
+
+- **Folder path prefix** — vaults typically organise into `Daily Notes/`, `People/`, `Projects/`, etc. Filter by one or more top-level folders.
+- **Frontmatter tags** — pages with `tags: [project, client]` in YAML can be picked by tag set.
+- **Modified-since** — incremental imports: "only pages updated since 2026-03-01".
+- **All of them** — combinations are additive (a page must satisfy every supplied filter).
+
+**Threshold (`selectiveIngestSuggested`).** When dry-run reports `pagesEligible > 100` and no filter was supplied, ask the operator before committing: "your vault has 1,247 pages — which slice should I import first?". Offer the axes above and accept the operator's combination. Re-run dry-run with those filters to confirm the trimmed scope, then commit.
+
+**Re-importing is idempotent.** Coming back later with a wider slice ("add Projects/ this time", "include the older notes too") hits the same `(accountId, obsidianPath)` MERGE — existing pages are matched and updated where content has changed; only the delta is new.
+
+## Doctrine
+
+- **Schema additions are last resort.** Vault pages reuse `:KnowledgeDocument` with `source='obsidian'`. Tags reuse `:DefinedTerm` with `category='obsidian-tag'`. Attachments reuse `:DigitalDocument`. Unresolved wikilink stubs reuse `:Concept` with `source='obsidian-stub'`. The only new schema is the `knowledge_doc_obsidian_path` index, which is part of `platform/neo4j/schema.cypher` and applied by `seed-neo4j.sh` at install time.
+- **Natural-edge discipline.** A wikilink `[[X]]` is the operator's statement "this note connects to X". That becomes either `:WIKILINKS_TO` (page-to-page within the vault) or `:MENTIONS` (page-to-entity). A tag `#foo` becomes `:TAGGED_WITH`. An embedded image becomes `:EMBEDDED_IN`. No synthetic edges; every edge corresponds to something the markdown actually expresses.
+- **No raw Cypher in this skill.** All writes route through `mcp__plugin_memory_memory__obsidian-vault-import`, which internally calls the `memory-archive-write` handler (the agent never invokes archive-write directly — `obsidian-vault-import` is the only tool the agent calls). Bash improvisation against `cypher-shell` is forbidden; if a vault structure the parser doesn't yet handle is needed, file a task to extend the parser library, never paper over it with a script.
+- **Provenance stamp.** Every node the handler creates carries `source='obsidian'`, `createdByAgent='obsidian-import'`, `createdBySource='obsidian-import'`, `createdBySession=<sessionId>`, `createdAt=datetime()`, plus `scope='admin'` for memory-visibility.
+- **Idempotency.** Same vault, same contents, same owner re-imported → `written.createdPages=0`, `mergedPages=0`, all `pagesUnchanged`. Changed pages update in place. No deletions on re-import (operator removes a note from the vault → the corresponding :KnowledgeDocument stays in Maxy until the operator explicitly trashes it).
+
+## File roster — references
+
+Each reference covers one parser surface inside this skill. The skill always loads these inline when the operator's question maps to one of them.
+
+| Reference | Covers |
+|-----------|--------|
+| [vault-structure.md](references/vault-structure.md) | Directory layout, `.md` discovery, hidden-folder skipping, frontmatter format. |
+| [wikilinks.md](references/wikilinks.md) | `[[Page]]`, `[[Page#anchor]]`, `[[Page\|Alias]]`, resolution priority, ambiguity handling. |
+| [daily-notes.md](references/daily-notes.md) | Detection heuristic (filename pattern + folder name), `noteDate` property. |
+| [attachments.md](references/attachments.md) | Embedded images and PDFs, archive directory layout, supported MIME types. |
+
+## Observability
+
+The tool emits these lines to `server.log`:
+
+- `[obsidian-import] event=dry-run-complete importId=<id> pages=<n> unchanged=<n> wikilinks-page=<n> wikilinks-entity=<n> wikilinks-stub=<n> wikilinks-ambiguous=<n> tags=<n> attachments=<n> ms=<n>` — Phase A finished.
+- `[obsidian-import] event=commit-complete importId=<id> pages=<n> written=<n> skipped=<n> wikilinks=<n> tags=<n> attachments=<n> errors=<n> ms=<n>` — Phase B finished.
+- `[obsidian-import] event=attachment-missing page=<path> path=<rawpath>` — per-page when an attachment file could not be located.
+- `[obsidian-parser] event=parse-failed file=<path> reason=<text>` — per-page when parsing threw; that page is skipped, the batch continues.
+
+Diagnostic path: `grep "obsidian-import" server.log | tail -30` shows recent imports. Join with `[memory-archive-write] archiveType=obsidian-vault` lines to see per-batch write decisions.

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

@@ -0,0 +1,80 @@
+# Attachments
+
+How embedded images, PDFs, and other binary assets in vault pages land in Maxy.
+
+## Syntax surface
+
+The parser recognises two embed forms:
+
+| Form | Example | Notes |
+|------|---------|-------|
+| Obsidian embed | `![[Diagram.png]]` | Default Obsidian image / PDF embed; routes to attachments only when the target has a supported extension. |
+| Markdown image | `![alt text](path/to/image.jpg)` | Standard CommonMark; `alt` is preserved on the `:DigitalDocument` node. Remote URLs (`http://`, `https://`) are ignored — only vault-local paths are ingested. |
+
+Embeds without a supported attachment extension (`![[Another Page]]`) are treated as wikilinks, not attachments — see [wikilinks.md](wikilinks.md).
+
+## Supported extensions
+
+The current parser pipeline copies files with these extensions and stamps the matching `encodingFormat` MIME on the `:DigitalDocument`:
+
+| Extension | MIME |
+|-----------|------|
+| `.png` | `image/png` |
+| `.jpg`, `.jpeg` | `image/jpeg` |
+| `.gif` | `image/gif` |
+| `.webp` | `image/webp` |
+| `.svg` | `image/svg+xml` |
+| `.pdf` | `application/pdf` |
+| `.mp3` | `audio/mpeg` |
+| `.mp4` | `video/mp4` |
+| `.mov` | `video/quicktime` |
+| `.wav` | `audio/wav` |
+| `.m4a` | `audio/mp4` |
+| `.webm` | `video/webm` |
+
+Anything else: the embed reference is parsed but the attachment is not copied and no `:DigitalDocument` is written. Add a new extension by extending `SUPPORTED_ATTACHMENT_MIME` in `obsidian-vault-import.ts` and the matching attachment-regex in the parser library.
+
+## Resolution
+
+For each embed, the parser searches in three places:
+
+1. **Vault-root-relative.** The path as written in the markdown, interpreted from the vault root.
+2. **Page-relative.** The same path joined to the page's directory.
+3. **Bare filename search.** A walk of the vault for an exact filename match. This covers Obsidian's default behaviour of placing attachments in a single attachments folder regardless of where the page lives.
+
+The first hit wins. A missed embed emits `[obsidian-import] event=attachment-missing page=<path> path=<rawPath>` to `server.log` and the wikilink/page write still proceeds — the missing attachment does not abort the import.
+
+## Archive layout
+
+Successfully resolved attachments are copied (not moved) to:
+
+```
+{accountDir}/archive/obsidian/<importId>/<vault-relative-path>
+```
+
+`<importId>` is the run identifier the dry-run returned. Two imports of overlapping vaults each get their own directory; the same file copied twice produces two on-disk copies under different importId directories. This is deliberate — content-hash idempotency lives at the page level, not the attachment level. If an operator wants to deduplicate attachments across imports, that's a separate maintenance task.
+
+The `:DigitalDocument.attachmentPath` property holds the absolute archive path. The MERGE key is `(accountId, attachmentPath)` so re-running the same import (same importId) updates the existing node rather than duplicating.
+
+## Graph shape
+
+```
+(:KnowledgeDocument {obsidianPath: 'People/Adam.md'})
+  <-[:EMBEDDED_IN]-
+(:DigitalDocument {
+  attachmentPath: '/data/accounts/<acct>/archive/obsidian/<importId>/People/adam-headshot.png',
+  encodingFormat: 'image/png',
+  alt: 'Adam at the conference',
+  source: 'obsidian'
+})
+```
+
+The `:EMBEDDED_IN` direction (`DigitalDocument -> KnowledgeDocument`) matches the convention used by `memory-ingest` for document attachments. Querying "which images live on this note" uses `MATCH (d:DigitalDocument)-[:EMBEDDED_IN]->(k:KnowledgeDocument {obsidianPath:$path}) RETURN d`.
+
+## Out of scope
+
+- Remote (HTTPS) images referenced in markdown — the parser intentionally skips them. Caching remote assets at import time would race with link rot and silently bloat the archive. If the operator wants a remote image preserved, they can save it into the vault locally first.
+- OCR / image content extraction. The image bytes are archived; no derived content is written.
+- Thumbnail generation. Operators view attachments via existing memory-list-attachments / memory-read-attachment surfaces.
+
+Each of the above can be added as a separate task — never silently inflated into this import.