@rubytech/create-sitedesk-code 0.1.340

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 librarian'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 SiteDesk Neo4j graph. Skill-only plugin owned by the librarian 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 SiteDesk Neo4j graph. Skill-only plugin owned by the librarian specialist. Opt-in per brand — not enabled by default."
+tools: []
+always: false
+embed: false
+specialist: librarian
+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 SiteDesk Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `specialists:librarian` specialist, which owns foreground ingest of documents, transcripts, LinkedIn, and every bulk external archive.
+
+## When this applies
+
+The admin agent delegates to `specialists:librarian` 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.
+- **librarian specialist** — owns execution. See [librarian.md](../../templates/specialists/agents/librarian.md) skill-routing table.
+
+## 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:librarian`** when the operator drops an extracted Obsidian vault directory (or references one by path) into chat. The admin agent dispatches the librarian; the librarian 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 SiteDesk 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 SiteDesk.
+
+## 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.

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

@@ -0,0 +1,31 @@
+# Daily Notes
+
+How the parser identifies date-stamped vault pages and what gets written for them.
+
+## Detection heuristic
+
+Three signals in priority order:
+
+1. **Frontmatter date.** If the page's YAML frontmatter contains `date:` or `created:` whose value starts with an ISO date (`YYYY-MM-DD…`), that date wins. This is the most explicit signal — operators who run Obsidian's Templater or Daily Notes core plugin typically stamp `date:` automatically.
+2. **Filename matches `YYYY-MM-DD.md`.** Any page whose basename matches exactly the ISO-date pattern is treated as a daily note regardless of folder. This is the default Obsidian Daily Notes naming convention.
+3. **Filename matches `YYYY-MM-DD` inside a known daily-notes folder.** Folder name (case-insensitive) is one of `daily`, `daily-notes`, `daily notes`, `journal`, `journals`. A bare `YYYY-MM-DD.md` is required; arbitrary content inside a journal folder is not auto-stamped.
+
+Signals are evaluated in that order; the first match wins. No signal → `noteDate` is null.
+
+## What gets written
+
+When `noteDate` is non-null, the page's `:KnowledgeDocument` carries `noteDate: date('YYYY-MM-DD')` as a typed Neo4j `date` value. This is queryable: `MATCH (k:KnowledgeDocument) WHERE k.noteDate >= date('2026-01-01') RETURN k` returns every daily note from this year, without needing a separate `:Day` label.
+
+No `:Day` node is created. The brief originally proposed `(:Page)-[:HAS_NOTE]->(:Day {date})`; the SiteDesk graph encodes the same information as a property on the page itself, mirroring `:Person.birthDate` and `:Event.eventDate`. Date-bearing event semantics live on `:TimelineEvent`, not here — a daily note is a document-at-a-date, not an event-on-a-date.
+
+## Folder semantics
+
+The known daily-notes folder names above are a parser-side fallback only. They are NOT used for filtering — the operator can still filter on `folderPrefixes: ["Daily Notes/"]` separately, which is independent of daily-note detection. A page in `Personal/Diary/2026-03-15.md` matches the filename pattern (signal 2) and gets `noteDate` set, even though `Personal/Diary/` is not in the known list.
+
+## False positives
+
+A non-journal page named `2026-03-15-meeting-with-adam.md` does NOT match — the filename must be exactly the ISO date with no suffix. The heuristic deliberately errs on the side of missing some daily notes rather than mis-labelling regular pages.
+
+## Repeating dates
+
+If two pages map to the same `noteDate` (e.g., `Personal/2026-03-15.md` and `Work/2026-03-15.md`), both are written with the same `noteDate` value. Querying `WHERE k.noteDate = date('2026-03-15')` returns both — they are separate atomic notes that happen to share a date.

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

@@ -0,0 +1,46 @@
+# Vault Structure
+
+How the parser discovers what to ingest from an extracted Obsidian vault.
+
+## Entry point
+
+The operator supplies an `extractedDir` — an absolute path to the root of an extracted vault. The vault zip is unpacked elsewhere (typically by `unzip-attachment` under `{accountDir}/extracted/<id>/`); this skill assumes the path already exists and is a directory.
+
+## What counts as a page
+
+A vault page is any file under `extractedDir` ending in `.md` (case-insensitive) that is **not** under a hidden directory. Hidden directories — names starting with `.` (`.obsidian/`, `.trash/`, `.git/`) — are skipped at walk time. The `.obsidian/` config tree is metadata about the vault, not vault content.
+
+Symlinks pointing outside the vault root, and any path containing a `..` segment, are rejected at the parser boundary as a defence-in-depth measure on top of the unzip sandboxing.
+
+## What counts as a folder
+
+Every directory under `extractedDir` is walked depth-first. Empty folders are silently skipped. The parser does not infer "this is a Daily Notes folder, this is People" — folder semantics come from filters the operator supplies (see [daily-notes.md](daily-notes.md) for the one exception, where the parser uses folder names as a fallback signal for daily-note detection).
+
+## Frontmatter format
+
+The parser recognises YAML frontmatter delimited by `---` on the first line. The frontmatter block:
+
+- Must start at byte 0 of the file (no BOM, no preceding blank lines).
+- Must close with a line that is exactly `---`.
+- Is parsed as a minimal YAML subset — top-level `key: value` pairs and `key:` followed by `- item` block sequences, plus flow-style `key: [a, b, c]` arrays.
+- Recognised keys: `aliases`, `tags`, `date`, `created`. Other keys are read but ignored.
+- A malformed frontmatter block does NOT abort parsing — the parser falls back to "no frontmatter" and uses the file body verbatim. This is by design: a single broken page does not break the batch.
+
+Pages without frontmatter are ingested with empty `aliases` and `tags` fields; their body is the entire file.
+
+## Title
+
+Title is the filename without `.md`, normalised to NFC unicode form. Folder path is NOT part of the title — only the basename. Two pages can share a title (`Projects/SiteDesk.md` and `People/Adam.md/SiteDesk.md`); they MERGE separately because the natural key is the full `obsidianPath`, not the title.
+
+## Content hash
+
+Every page contributes a SHA-256 hash of its on-disk bytes. The hash is the idempotency key on re-import: a page whose hash matches the existing graph's `:KnowledgeDocument.contentHash` is skipped during commit. Re-importing the exact same vault is a no-op write.
+
+## Out-of-scope file types
+
+- `.canvas` files — Obsidian Canvas graphs are JSON, not markdown. Not ingested.
+- `.base` files — Obsidian Bases are not ingested.
+- Loose attachment files (`.png`, `.pdf`, …) not referenced by any `.md` page are not ingested. They're only picked up via the embed syntax in [attachments.md](attachments.md).
+- `.obsidian/` config files — never ingested.
+
+Adding any of these means extending the parser library (`platform/lib/obsidian-parser/`); file a task before improvising.

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

@@ -0,0 +1,70 @@
+# Wikilinks
+
+How `[[…]]` text inside an Obsidian note becomes a graph edge.
+
+## Syntax surface
+
+The parser recognises four forms:
+
+| Form | Components | Example |
+|------|-----------|---------|
+| Bare | target | `[[Adam]]` |
+| With anchor | target, anchor | `[[Project SiteDesk#Goals]]` |
+| With alias | target, alias | `[[Adam Langley\|Adam]]` |
+| Embed | target (routed to attachments OR page-embed) | `![[Diagram.png]]` |
+
+`anchor` is the heading slug after `#`; `alias` is the display text after `|`. The parser records both alongside the resolved target so the resulting edge carries the original linkText, alias, and anchor as properties.
+
+## Code-fence isolation
+
+`[[…]]` inside fenced code blocks (` ``` ` or `~~~`) is NOT parsed. Operators paste code samples into notes; markdown inside those samples should not become graph edges. The fence-aware scan splits the body into code and non-code segments before regex matching.
+
+## Resolution priority
+
+For every wikilink, the parser computes two candidate sets and chooses by these rules:
+
+1. **Intra-vault page candidates.** Match the target text against (a) page titles (basename without `.md`) and (b) declared aliases (frontmatter `aliases:`). Both lookups are case-insensitive after NFC normalisation. A path-form target (`Folder/Sub/Page` or `Folder/Page.md`) bypasses title/alias lookup and resolves directly to that exact path if it exists.
+2. **Existing entity candidates.** Query `:Person`, `:Organization`, `:Concept` nodes scoped to the account where `name = target` (exact, distance 0) or where `levenshtein(name, target) ≤ 2` (fuzzy fallback). The entity index is built once per dry-run from the live graph state.
+
+Decision matrix:
+
+| Page hits | Exact entity hits | Fuzzy entity hits | Outcome |
+|-----------|-------------------|-------------------|---------|
+| 1 | 0 | 0 | Resolved: page |
+| 0 | 1 | — | Resolved: entity (exact) |
+| 0 | 0 | 1 | Resolved: entity (fuzzy) |
+| 0 | 0 | 0 | Resolved: stub (`:Concept`) |
+| ≥1 | ≥1 | — | **Ambiguous** — operator decides |
+| ≥2 | 0 | — | **Ambiguous** — operator decides |
+| 0 | ≥2 | — | **Ambiguous** — operator decides |
+| 0 | 0 | ≥2 | **Ambiguous** — operator decides |
+
+Ambiguities surface in the dry-run plan with a stable `id`. The operator picks one outcome per ambiguity; that decision flows into the commit phase via the `resolutions` map.
+
+## Edge kinds
+
+| Resolved kind | Edge | Cypher target |
+|---------------|------|---------------|
+| Page | `:WIKILINKS_TO` | `(:KnowledgeDocument)-[:WIKILINKS_TO]->(:KnowledgeDocument)` |
+| Entity | `:MENTIONS` | `(:KnowledgeDocument)-[:MENTIONS]->(:Person\|:Organization\|:Concept)` |
+| Stub | `:MENTIONS` | `(:KnowledgeDocument)-[:MENTIONS]->(:Concept {source:'obsidian-stub'})` |
+
+Every edge carries `linkText`, `alias`, `anchor` (page edges only), `source='obsidian'`, `createdAt`.
+
+## Why stubs exist
+
+A wikilink to "Aaron" where no vault page and no graph entity matches still represents the operator's intent: this note is about Aaron, whoever Aaron is. Dropping the edge would lose information; demanding a hard match would force the operator to pre-populate the graph before importing.
+
+Stubs are explicitly distinguishable: `:Concept {source:'obsidian-stub'}`. A later session can promote a stub to a typed `:Person` or `:Organization` via `memory-update`, at which point the `:MENTIONS` edge remains pointed at the same node and the stub flag is removed.
+
+## Self-references
+
+`[[Self]]` inside `Self.md` produces a self-edge. Obsidian treats it as valid; the parser preserves it.
+
+## Anchors
+
+`[[Page#section]]` resolves on `Page` only — the `section` portion is stored on the edge as `anchor`. The parser does not create per-heading nodes; section decomposition is out of scope for vault pages (they are atomic notes).
+
+## Embeds vs wikilinks
+
+`![[file]]` with an attachment extension (`.png`, `.pdf`, `.mp3`, etc.) is treated as an attachment, not a wikilink. `![[Another Note]]` (no attachment extension) is treated as a wikilink — Obsidian renders it as a transclusion, and the cross-reference is preserved as a `:WIKILINKS_TO` / `:MENTIONS` edge depending on resolution.