@rubytech/create-sitedesk-code 0.1.340

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

@@ -0,0 +1,331 @@
+---
+name: document-ingest
+description: Universal document ingestion — maps any unstructured document (PDF, text, transcript, web page) OR chat archive (WhatsApp `_chat.txt`) to ontologically-grounded graph nodes. The dispatched specialist reads the cached extract and produces typed-section JSON in-turn from the loaded ontology, then calls memory-ingest (the separate server-side memory-classify step was removed). Triggers when the operator uploads or fetches a document or chat export for ingestion. One skill for every input shape — no per-doctype, no per-channel branching.
+---
+
+# Document Ingest
+
+**Invoked from `specialists:librarian`** — the admin agent dispatches the librarian when the operator hands over a document or chat archive, and the librarian loads this skill. The admin agent never calls this skill directly.
+
+**Default parent.** Every `:KnowledgeDocument` (whether the document or the conversation-document writer wrote it) is anchored to a `:Project` when the dispatch brief names one, or to the account's `:LocalBusiness` when the document is account-scoped rather than project-scoped. The admin agent's brief carries the parent elementId; `memory-ingest` refuses the write if the parent is missing or does not exist. Brief-named entity wiring (Persons, Organizations, Tasks) creates cross-hierarchy edges from the document — never substitutes for the containment parent.
+
+Ingests any unstructured input — documents (PDF, text, transcript, web page) and chat archives (WhatsApp `_chat.txt`) — into the graph. Every classified section becomes one `:Section` node under a `:KnowledgeDocument` parent. **One parent label, two writer paths chosen by identity property:**
+
+| Input shape | Parent label | Identity property (dispatcher signal) | Section secondary label | mode |
+|---|---|---|---|---|
+| PDF / text / web (default) | `:KnowledgeDocument` | `attachmentId` | `:Section:<Kind>` from closed enumeration (`Position`, `Chapter`, `Parties`, …) | `document` |
+| Chat archive (`_chat.txt`, X DMs, Telegram, …) | `:KnowledgeDocument` | `conversationIdentity` | `:Section` (no secondary label — source distinguishes at the parent) | `chat` |
+| X (Twitter) tweet-stream transcript (rendered by `x-import`) | `:KnowledgeDocument` (`source='x'`) | `attachmentId` | `:Section:<Kind>` from closed enumeration | `document` |
+
+**You** (the dispatched specialist) decide which section kinds each section maps to (document mode) or chunk the archive into topic-bounded `:Section` nodes (chat mode). The skill drives the pipeline; you read the loaded ontology directly and produce the typed JSON in your turn; the writer enforces the validator. **Classification failure is terminal — the ingest aborts entirely; nothing is written. Loud failures, never silent landfill.**
+
+## Routing — chat vs document (mandatory first decision)
+
+Before anchor confirmation, decide which identity property to pass to `memory-ingest`:
+
+- **Chat archive** — input filename ends in `_chat.txt`, the dispatch brief names the input as a WhatsApp chat / messaging-channel export, or the operator labels it as such. Set `mode='chat'` and pass `conversationIdentity` (omit `attachmentId`). Skip anchor confirmation; run participant confirmation instead (see § Participant confirmation). The classifier produces `:Section` chunks; no anchor edges, no related entities.
+- **Document** — everything else. Set `mode='document'` and pass `attachmentId` (omit `conversationIdentity`). Run the anchor confirmation flow below.
+
+Both branches go through the same two tools (`memory-ingest-extract` → `memory-ingest`) with you producing typed-section JSON in between; only the parameters differ.
+
+## Anchor confirmation (mandatory first step)
+
+Every document has a subject — the node every identity-kind section attaches to. Anchors are parameter input, never inferred from "who uploaded the file". The dispatch brief from the admin agent names the anchor explicitly. If the brief is ambiguous, ask the operator before any read.
+
+The four common shapes:
+
+| Document | Anchor | Anchor label |
+|---|---|---|
+| Owner CV / personal-profile content | `:UserProfile` (or `:Person {role: 'admin-personal'}`) | `UserProfile` (or `Person`) |
+| Business pricing guide / policy / brochure | `:LocalBusiness` for this account | `LocalBusiness` |
+| Contract or document about a third party | `:Person` or `:Organization` (named in brief) | `Person` or `Organization` |
+| Reference document with no natural subject (industry overview, generic FAQ) | `:LocalBusiness` (default) | `LocalBusiness` |
+
+The confirmation flow:
+
+1. Read the dispatch brief. Extract the document path and the named subject.
+2. If the subject is not named, or is ambiguous, ask the operator in one sentence: "I'm about to ingest `<filename>`. Anchor it to the account owner's UserProfile, the business (`<LocalBusiness.name>`), or a third party — which?". Wait for the answer.
+3. Run a one-shot graph read to resolve the anchor's element ID. For UserProfile: `MATCH (u:UserProfile {accountId: $accountId}) RETURN elementId(u) AS anchorId, 'UserProfile' AS anchorLabel`. For LocalBusiness: `MATCH (b:LocalBusiness {accountId: $accountId}) RETURN elementId(b) AS anchorId, 'LocalBusiness' AS anchorLabel`. For a third party: search by name via `memory-search` and pick the matching node.
+4. Persist `$anchorNodeId` and `$anchorLabel` for the rest of the run. They flow into your in-turn classification (as the anchorDescription you reason against) and into `memory-ingest` (as the `anchorNodeId` + `anchorLabel` parameters).
+
+## Participant confirmation (chat mode only)
+
+Chat archives are multi-party — no single subject anchor. Instead, every distinct sender name in the archive must resolve to an existing `:AdminUser` or `:Person` elementId before any classify or ingest call. No auto-creation; missing participants are blockers, not silent skips.
+
+The confirmation flow:
+
+1. Read the dispatch brief. Extract the archive path and any operator-stated participant identities.
+2. Read a small sample of the archive (head ~50 lines) via the `Read` tool to discover the distinct sender names that appear at line starts after the bracketed-timestamp prefix.
+3. For every distinct senderName, search the graph via `memory-search` (or a one-shot `MATCH (n) WHERE (n:Person OR n:AdminUser) AND n.accountId = $accountId AND (n.name = $name OR (n.givenName + ' ' + n.familyName) = $name) RETURN elementId(n)`).
+4. **Resolved fully** — every senderName mapped to exactly one elementId. Capture the owner's elementId (the operator who exported the archive — usually the `:AdminUser` for this account; ask if ambiguous) and the comma-separated list of remaining participant elementIds.
+5. **Unresolved** — at least one senderName has no matching node. Surface to the operator: *"Archive `<filename>` mentions sender `<name>` but no `:Person` / `:AdminUser` matches. Create the contact first or correct the name, then re-dispatch."* Do NOT proceed.
+6. **Ambiguous** — a senderName matches multiple nodes. Ask the operator which one. Do NOT proceed until disambiguated.
+
+Persist `$ownerElementId` and `$participantElementIds` (array, owner excluded) for the run. These flow into `memory-ingest` as the `participantElementIds` parameter (owner + others, deduped).
+
+Compute archive metadata before classify:
+- `archiveSha256` — `bash sha256sum "<file>" | cut -d' ' -f1`. Stamped on the parent + every chunk.
+- `archiveSourceFile` — the basename (e.g. `_chat.txt`).
+- `conversationIdentity` — pass as the `conversationIdentity` parameter to `memory-ingest` (in place of `attachmentId`; the two are mutually exclusive). Format: `chat:<sha256(accountId + ":" + sortedParticipantElementIds)>` where `sortedParticipantElementIds` is the sorted-then-comma-joined list of `[owner, ...participants]`. Same conversation across re-exports → same identity → idempotent MERGE on the conversation-document `:KnowledgeDocument`.
+
+## Pipeline
+
+Four steps in order. Step 1 is a deterministic tool call. Step 2 is **your in-turn work**: you read the cached text plus the loaded ontology and produce typed-section JSON. Step 3 hands that JSON to `memory-ingest`. Step 4 is agent-driven graph writes against the existing graph, gated by the dispatch brief's named entity list. Ontology validation stays server-side in the `memory-ingest` writer (the writer rejects sections whose `kind` is outside the loaded label set).
+
+```
+EXTRACT  --> CLASSIFY (in-turn)  --> INGEST  --> WIRE-BRIEF-ENTITIES
+   │              │                     │              │
+   v              v                     v              v
+ text          sections             one :Section    KD-level edges from
+ cached        + KD-level           per semantic   the new KnowledgeDocument
+ by id         edges                boundary +     to each entity the
+               + orphans            NEXT chain +   dispatch brief named
+               (you produce         anchor edges   (Person / Organization /
+                this JSON           + related      Service / Task / Event /
+                yourself, from      entities +     KnowledgeDocument /
+                the ontology +      typed-edge     BrandingData) — plus an
+                the cached text)    KD-level       orphan list for brief-
+                                    edges          named entities not found
+                                    (PARTY /       in the graph.
+                                    PARTICIPANT /
+                                    FROM/TO/CC /
+                                    SPEAKER)
+```
+
+### 1. `memory-ingest-extract`
+
+Pulls text from the file and caches it under the `attachmentId`. Inputs: `storagePath`, `filename`, `mimeType`, `attachmentId` (all from the attachment metadata block in your brief). Returns metadata + a 240-char preview. The full text lives in the in-process cache.
+
+After extract returns, emit one line in chat: "Ingesting `<filename>` (`<N>` chars)." Documents > ~525K chars need chunked processing in step 2 — flag this in the line so the operator knows the turn will run long.
+
+### 2. Classify in-turn (your work)
+
+You produce typed-section JSON yourself from the cached text and the loaded ontology. There is no classifier tool — it was deleted. Read the relevant ontology references first (`platform/plugins/memory/references/schema-base.md` and, when `brand.json#vertical` is set, the matching `schema-<vertical>.md`) so every `kind` you emit is a label the writer will accept.
+
+**Document mode (default).** Build the JSON with this top-level shape:
+
+```
+{
+  "documentSummary": "<1-3 sentences>",
+  "documentKeywords": ["<3-10 lowercase topic keywords>"],
+  "sections": [
+    {
+      "kind": "<from closed enumeration>",
+      "title": "<short title>",
+      "summary": "<≤500 chars>",
+      "sourceStart": <int>,
+      "sourceEnd": <int>,
+      "properties": { ... },
+      "anchorEdge": { "type": "<edge>", "direction": "from-anchor", "properties": { ... } },
+      "related": [ ... ],
+      "classifierReason": "<only when kind === 'Other'>"
+    }
+  ],
+  "documentEdges": [ ... ],
+  "orphanCandidates": [ ... ]
+}
+```
+
+Use the natural-edge map below to pick `anchorEdge` per kind. The writer derives `:Section.body` from `cachedText.slice(sourceStart, sourceEnd)` — you emit offsets, not body text. Any `body` field you supply is logged and ignored. `summary` ≤ 500 chars.
+
+```
+Section kind                     | Anchor edge (direction = from-anchor unless noted)
+Position (identity)              | (anchor:UserProfile)-[:HAS_POSITION]->(:Section:Position); section -[:AT]-> related:Organization (merge:true)
+Education (identity)             | (anchor:UserProfile)-[:ATTENDED {degree, startDate, endDate}]->(:Section:Education); section -[:ATTENDED]-> related:Organization {organizationCategory:'educational'} (merge:true)
+Credential (identity)            | (anchor:UserProfile)-[:HOLDS]->(:Section:Credential)
+Skill (identity)                 | (anchor:UserProfile)-[:HAS_SKILL]->(:Section:Skill)
+Biography (identity)             | (anchor:UserProfile)-[:DESCRIBED_BY]->(:Section:Biography)
+Project (standalone, not :Section) | (anchor:UserProfile)-[:CREATED]->(:Project); optional (:Project)-[:UNDER]->related:Organization (merge:true)
+Preface, Abstract, Introduction, TableOfContents, Chapter, Conclusion, Appendix, Bibliography, Glossary, Acknowledgments (structural)
+                                 | anchorEdge: null — anchored only via (:KnowledgeDocument)-[:HAS_SECTION]->(:Section:<Kind>) + (:Section)-[:NEXT]->(:Section)
+Parties, Recitals, Definitions, Scope, Term, Payment, Confidentiality, IntellectualProperty, Warranties, Indemnification, Liability, Termination, GoverningLaw, ForceMajeure, Notices, EntireAgreement, Amendment, Assignment, Severability, Signatures (contract-clause)
+                                 | anchorEdge: null — anchored via HAS_SECTION + NEXT; for Parties section, additionally emit top-level documentEdges PARTY entries; for Definitions, emit related DefinedTerm nodes with edge type DEFINES (direction outgoing from the Definitions section).
+Other (label fallback)           | anchorEdge: null — section-kind closure miss; you MUST also include 'classifierReason' (one-line about-what)
+```
+
+`documentEdges` covers party-like links the document itself names: `PARTY` for contract parties, `PARTICIPANT` for meeting/call attendees, `FROM`/`TO`/`CC` for email-header parties, `SPEAKER` for transcript voices. The `memory-ingest` tool definition spells out the exact field shape.
+
+**Typed-entity edges target real entities, never `:Section`.** Edge types governed by the typed-edge allowlist — `FOUNDED`, `WORKS_AT`, `INVESTED_IN`, `ADVISES`, `MENTIONS`, `AUTHORED`, `ATTACHED_TO`, `REFERENCES`, `ATTENDED` — connect real entities (`Person`, `Organization`, etc.) per the (source, target) shapes declared in `platform/plugins/memory/mcp/src/lib/typed-edge-schema.ts`. They MUST NOT land on a `:Section` node as either endpoint. The writer rejects loud with the offending `(:Source)-[:EDGE]->(:Target)` triple if a classifier emission violates this.
+
+When a section names entities related to the **document anchor** (e.g. a Team section on a company-page document whose anchor is the `:Organization`), set `edge.targetMode = "anchor"` on the related entry. The writer connects the related entity to the anchor instead of the section node:
+
+```
+// Company website, anchor = :Organization "BioSymm Technologies Ltd"
+{ kind: "Other", title: "Team", anchorEdge: null, related: [
+  { kind: "Person",
+    properties: { name: "Ricky Du Plessis" },
+    merge: true,
+    edge: { type: "FOUNDED", direction: "incoming", targetMode: "anchor" } },
+  { kind: "Person",
+    properties: { name: "Clarence Bissessar" },
+    merge: true,
+    edge: { type: "FOUNDED", direction: "incoming", targetMode: "anchor" } }
+]}
+// Writer creates:
+//   (:Person {name:"Ricky Du Plessis"})-[:FOUNDED]->(:Organization {anchor})
+//   (:Person {name:"Clarence Bissessar"})-[:FOUNDED]->(:Organization {anchor})
+```
+
+The default `targetMode` is `"section"` (omit when the edge legitimately lives on the section, e.g. `:Section:Definitions -[:DEFINES]-> :DefinedTerm`). Anchor-routing is only meaningful when the document anchor is the natural endpoint per the typed-edge allowlist — emitting `targetMode: "anchor"` on a CV whose anchor is `:UserProfile` for a `:FOUNDED` edge is still a rejected shape (`:UserProfile` is not a valid FOUNDED target).
+
+`orphanCandidates` is the list of entities you wanted to emit but could not natural-edge. Surface them so the ontology can grow.
+
+**Chat mode.** Same top-level shape with every `sections[].kind = "Conversation"`. `summary` is the per-section top-level field (already required by the schema) — the writer reads it from there and stamps `:Section.summary`. The `properties` bag is for non-authoritative per-chunk metadata only: `keywords`, `firstMessageAt`, `lastMessageAt`, `participantNames`, `messageCount`. The writer strips reserved writer-owned keys (`summary`, `title`, `body`, `bodyPreview`, `embedding`, provenance fields, etc.) from `properties` and logs the attempt — so duplicating an authoritative field into `properties` is a noisy no-op. Cover every message in chronological order with no gaps. Drop `anchorEdge` (always null) and `related`. Use the participant elementIds from § Participant confirmation; do not invent new ones.
+
+**Chunking — long inputs.** For inputs > ~525K chars, work through the cached text in deterministic ~525K-char windows with ~17.5K-char overlap, emit sections per window, and merge same-kind boundary straddlers yourself before calling `memory-ingest`. Inputs > 682K chars in chat mode are too large to keep within one turn — abort with `cause:"input-too-large"` and ask the operator to sessionize the export before re-dispatch.
+
+**Failure is terminal.** If you cannot produce the JSON (the ontology you need isn't loaded, the extract is empty, the document is opaque), **do not call `memory-ingest`. Do not write anything.** Return to the dispatching agent immediately with a structured blocker: `Classifier unable to map document — <reason>. Document not ingested. Operator must <remediation>.` There is no "fallback-to-UNMAPPED-section" write path — that fallback was removed by design.
+
+After you've assembled the JSON, emit a chat message before step 3 naming what you produced: **"Classified into N sections, covering: <topic keywords>."** This is step 2 of the four-step narrative the operator sees per ingest.
+
+### 3. `memory-ingest`
+
+Writes the classified document or chat archive.
+
+**Document mode (default).** Inputs: `attachmentId`, `documentSummary`, `anchorNodeId`, `anchorLabel`, `sections`, `documentEdges` (pass through if present), `orphanCandidates` (pass through if present), `scope` (from the brief — confirm with the operator if absent), optional `documentKeywords`, `userKeywords`, `sourceUrl`, `sourceType`.
+
+**Chat mode.** Inputs: `conversationIdentity` (passed instead of `attachmentId` — the dispatcher signal), `documentSummary`, `sections` (the chunks from chat-mode classify), `scope`, plus the chat-archive metadata: `archiveSha256` (cleanup discriminator), `archiveSourceFile` (audit), `participantElementIds` (owner + others, for `:PARTICIPANT_IN` edges). Pass `anchorNodeId` and `anchorLabel` as any non-empty placeholder (e.g. the owner's elementId + `'AdminUser'`) — they are unused on the chat path but the parameter is non-optional. The writer MERGEs `:KnowledgeDocument { conversationIdentity }`, drops any chunks stamped with this `archiveSha256` (idempotent re-ingest), CREATEs new `:Section` chunks chained by `:NEXT`, and MERGEs `:PARTICIPANT_IN` edges from each participant.
+
+Returns:
+
+- `documentNodeId`, `sectionCount`
+- `kindBreakdown` — per-kind count, e.g. `{"Position": 4, "Chapter": 12, "Other": 1}`
+- `edgeBreakdown` — per-edge-type count, e.g. `{"HAS_SECTION": 17, "NEXT": 16, "HAS_POSITION": 4, "ATTENDED": 1, "AT": 4}`
+- `relatedCount` — Organizations/Persons/DefinedTerms created or merged
+- `standaloneCount` — `:Project` nodes created
+- `orphanCandidates` — passed through from the classifier so the agent can surface them in the post-write narrative
+- `documentSummary`, `keywords`
+
+After step 3 succeeds, emit the third chat message naming everything the writer created or connected (see "Four-step operator narrative" below). Continue to step 4 (`wire-brief-entities`) before the final fourth chat message.
+
+Re-ingesting the same `attachmentId` is safe — the writer drops prior `:Section` children (any secondary label), prior `:Project` standalone nodes, and prior KD-level edges (every edge stamped `sourceDocumentId=<this attachmentId>` plus the legacy `PARTY` edge type by name — covers classifier-emitted PARTICIPANT/FROM/TO/CC/SPEAKER and agent-emitted brief-wired edges) before re-creating. Shared related entities (Organizations, Persons MERGEd by identifying property) are spared.
+
+### 4. `wire-brief-entities`
+
+**Skipped in chat mode** — conversation-document parents do not carry KD-level brief-wired edges; participants are already attached via `:PARTICIPANT_IN` and message bodies stay verbatim inside chunk text (mention extraction is deferred to a separate insight-derivation task). Document mode only.
+
+After `memory-ingest` returns the new KnowledgeDocument's `documentNodeId`, this step iterates the entities the dispatch brief named and connects each to the new document with the natural KD-level edge.
+
+**Entity sources.** The dispatch brief's "key entities to connect" list. Brief shape: prose names of Persons, Organizations, Services, Tasks, Events, KnowledgeDocuments, BrandingData that the document describes or references. Example: *"Person nodes for Joel Smalley, Adam Mackay, Dan McLeod; LocalBusiness / Organization nodes for Real Agent / Real Agency; Any existing Task nodes related to Real Agent Lettings."* Extract every named entity from the brief before any `memory-write`.
+
+**Resolution.** For each named entity:
+2. If the entity resolves to exactly one node, write the edge from KD to that node (see edge-type table below).
+3. If the entity resolves to zero nodes, append it to the orphan list (do NOT create a placeholder Person/Organization — that's classifier-emitted `documentEdges` territory, not brief-wiring).
+4. If the entity resolves to multiple nodes (ambiguity — two Persons named "Joel"), pick the one whose context best fits the brief and document (e.g. last-mentioned-recently, or matching account). Surface the choice in the operator narrative so it can be corrected.
+
+**Edge-type table.** Edge depends on entity kind and document shape:
+
+| Entity kind | Document shape | Edge | Direction |
+|---|---|---|---|
+| Person | meeting / call (notes or transcript) | `PARTICIPANT` | KD → Person |
+| Person | email | `FROM` (sender) / `TO` (direct recipient) / `CC` (carbon copy) | KD → Person |
+| Person | voice-note / single-speaker transcript | `SPEAKER` | KD → Person |
+| Person | contract / agreement | `PARTY` | KD → Person |
+| Person | other (report, brief, generic notes) | `MENTIONS` | KD → Person |
+| Organization | meeting / call | `PARTICIPANT` | KD → Organization |
+| Organization | email | `TO` / `CC` | KD → Organization |
+| Organization | contract | `PARTY` | KD → Organization |
+| Organization | other | `MENTIONS` | KD → Organization |
+| Task | any | `REFERENCES` | KD → Task |
+| Event | any | `REFERENCES` | KD → Event |
+| Service | any | `REFERENCES` | KD → Service |
+| KnowledgeDocument (cross-link) | any | `REFERENCES` | KD → KnowledgeDocument |
+| BrandingData | any | `REFERENCES` | KD → BrandingData |
+
+When the classifier already emitted a `documentEdges` entry for the same (KD, target) pair (because the document body itself names the party — common for emails and contracts), the brief-wiring step is redundant for that party — `memory-search` for `elementId(n)` will find the just-written party and the second `memory-write` would create a duplicate edge. Skip the brief entry whose target was already wired by the classifier.
+
+**Provenance discipline.** Every brief-wired edge carries `sourceDocumentId=<attachmentId>` and `createdByAgent='document-ingest'` in its edge properties. The `memory-ingest` writer's re-ingest cleanup matches edges by `sourceDocumentId`, so a re-ingest of the same `attachmentId` drops them deterministically — without these stamps, brief-wired edges would accumulate on every re-ingest. This is load-bearing: forgetting the stamp leaks edges silently. Pass them on every `memory-write` `relationships` entry's properties block.
+
+**Operator narrative line.** Emit one chat line after the loop completes:
+
+```
+[document-ingest] wire-brief-entities resolved=<N> orphans=<M> edges=<K> — Persons via PARTICIPANT/FROM/TO/CC/SPEAKER/PARTY/MENTIONS, Organizations via PARTICIPANT/TO/CC/PARTY/MENTIONS, Tasks via REFERENCES, Events via REFERENCES, Services via REFERENCES. Not found in graph: <comma-separated brief names>.
+```
+
+The leading `[document-ingest] wire-brief-entities` token is grep-able from the agent's stream log so `edges=0` while the brief listed entities is the regression metric.
+
+If the brief lists no entities (single-author personal CV, generic FAQ, etc.), this step is a no-op: emit `[document-ingest] wire-brief-entities resolved=0 orphans=0 edges=0` and continue. The four-step narrative reverts to three lines for downstream chat (no fourth narrative line is emitted when this step does nothing).
+
+## Four-step operator narrative
+
+Each ingest produces up to four chat messages, each at the moment it happens. Failures replace the relevant step's message with a blocker. Step 4 collapses to nothing visible when the brief named no entities (the agent still emits the `[document-ingest] wire-brief-entities resolved=0 orphans=0 edges=0` log line for grep-ability, but no fourth chat message).
+
+| Step | Emitted by | Trigger | Content |
+|---|---|---|---|
+| 1 | Admin agent | On dispatch to librarian | "Sending `<filename>` to librarian for ingest." |
+| 2 | Librarian (this skill) | After you finish producing the typed-section JSON in-turn | "Classified `<filename>` into `<N>` sections, covering: `<topicKeyword1>, <topicKeyword2>, …`." |
+| 3 | Librarian (this skill) | After `memory-ingest` returns | "Created/connected: `<kind: count via edgeType to anchor>` for each kind; `<orphan-candidates: label and reason>` for any orphans; `<related entities created or merged: kind: count>`." |
+| 4 | Librarian (this skill) | After `wire-brief-entities` step completes AND the brief named at least one entity | "Wired `<N>` brief entities: `<K>` Persons via `<edge>`, `<M>` Organizations via `<edge>`, `<T>` Tasks via `REFERENCES`. `<P>` entities not found in graph: `<comma-separated names>`." |
+
+**Step 2 failure form:** "Classifier unavailable — `<reason>`. `<filename>` not ingested. `<remediation>`." Do not call step 3.
+
+**Step 3 failure form:** "`<n>` sections classified but write failed at `<stage>` — `<reason>`. `<filename>` not in graph." Do not call step 4.
+
+**Step 4 partial form:** "Wired `<N>` brief entities; `<P>` not found: `<list>`." If every brief-named entity resolved, drop the "not found" clause. If zero brief entities were named, suppress the chat message entirely (the log line still fires).
+
+The operator always sees what was attempted and where it stopped.
+
+## Web-page ingestion
+
+For URL-based ingestion, run `memory-ingest-web` first with the URL and the WebFetch result. It writes the content to a temp file and routes through `memory-ingest-extract`, returning a fresh `attachmentId`. The rest of the pipeline (classify + ingest) is identical to a file upload. Pass `sourceUrl` and `sourceType: 'web'` to `memory-ingest`.
+
+**Page title is mandatory input — parse it before the call.** `KnowledgeDocument.name` is what shows up everywhere the document is referenced (`pickShortLabel` / `pickDisplayName` check `name` first), so it must be an editorial title, never body prose. Before calling `memory-ingest-web`, scan the WebFetch result for the page's title and pass it as the `title` parameter:
+
+- The readability output often starts with the page's `<title>` or `og:title` as a literal H1 (e.g. `# I am no longer the Official Representative for Reform UK`). Use that line verbatim — strip the leading `# ` and any trailing site name suffix (e.g. ` - Substack`, ` | Medium`).
+- When the readability output strips the title entirely (rare; some publishers prefix the body with marketing chrome), look at the URL's final path segment — `…/i-am-no-longer-the-official-representative` is the slug the publisher chose for the article.
+- Never invent a title from the article's opening paragraph. Body prose is exactly what this parameter exists to avoid.
+
+The server's fallback chain when `title` is absent: markdown H1 in the cached text → URL-derived slug → the URL itself. The librarian's job is to make the `caller` branch the common case; the server-side fallbacks are last-resort, not the default path. The response includes `titleSource` (`caller` / `h1` / `url-slug` / `url`) so the operator can see which path fired.
+
+**WebFetch limitation — subscriber-gated and JS-rendered pages (Substack, Medium-locked, paywalled news, gated PDFs, single-page apps).** `WebFetch` retrieves only the public, server-rendered surface. For gated articles the return is the meta-description / preview blurb / third-person summary that the publisher exposes to scrapers — not the author's original prose. Verbatim text is unrecoverable through this path. **Detect this before ingesting:** if the WebFetch result looks like a third-person synopsis of an article whose author would have written in first person, or carries publisher-summary framing (`# <Title> - Full Article Text` headers, marketing blurbs, "Subscribe to read"), abort the ingest and surface the gap to the dispatching agent in one line: *"WebFetch for `<url>` returned a publisher summary, not the article body. Ask the operator for a different input shape — for a Substack URL on the operator's own publication, use the `substack-import` plugin's export-archive flow (Substack admin → 'Export your data' → drop the ZIP); otherwise paste the article text into chat or attach a PDF / .txt export."* The dispatching agent relays this to the operator and re-dispatches with the pasted text, uploaded file, or Substack archive as the input. Do NOT proceed to `memory-ingest-web` with the summary — `:Section.body` will faithfully reproduce that summary downstream, defeating the verbatim-prose contract.
+
+## Attachment metadata format
+
+Your task description contains attachment metadata in this format:
+
+```
+1. report.pdf  application/pdf  1,234,567 bytes
+   ID: 04caba6b-...  Path: /home/admin/.maxy/data/uploads/...
+```
+
+Extract:
+- **filename** = the text BEFORE the MIME type on the FIRST line. Always the human-readable name; never a UUID.
+- **mimeType** = the MIME type on the first line.
+- **attachmentId** = the UUID after `ID:` on the SECOND line.
+- **storagePath** = the absolute path after `Path:` on the second line.
+
+Process each text-based attachment (PDF, plain text, markdown). Skip images — they have no text to ingest.
+
+The `storagePath` you pass to `memory-ingest-extract` is threaded through to the writer automatically (via the extract cache) and persisted on the `:KnowledgeDocument` as `sourcePath`, so the sidebar download resolver can serve the real file later. You do not pass it to `memory-ingest` — the cache carries it. Web ingests are excepted: `memory-ingest-web`'s temp file is unlinked after extraction, so no `sourcePath` is persisted and the doc stays non-downloadable by design.
+
+## Visibility scope
+
+`memory-ingest` requires `scope`. The brief specifies it; if not, ask the operator before ingesting.
+
+- **public** — visible to public agents and admin. For business knowledge customers should access (products, services, FAQs, policies).
+- **shared** — visible to all account agents but not public visitors. Internal operational knowledge.
+- **admin** — admin agent only. Sensitive content (contracts, credentials, internal processes).
+
+CV / personal-profile content defaults to `admin`. Pricing guides, services, FAQs default to `public`. When uncertain, ask in one sentence.
+
+## Discipline (load-bearing)
+
+1. **Anchor confirmed first.** No extract / classify / ingest until `$anchorNodeId` and `$anchorLabel` are persisted and echo-confirmed.
+2. **Generic skill — no document-type branching.** The classifier maps sections to the closed enumeration. The writer applies the classifier's edges; never invents its own.
+3. **Schema-base property names.** The classifier emits `givenName` / `familyName` / `telephone` / `dateSent` — not `firstName` / `phone` / `sentAt`. The `memory-write` validator enforces this via the synonym map.
+4. **Closed enumeration of section kinds.** Identity, structural, contract-clause, plus standalone `Project` and label-fallback `Other`. The classifier never invents a new kind. `Other` collapses unrecognised content with a `classifierReason`; the operator runs `MATCH (s:Section:Other) WHERE s.accountId = $acc RETURN s.title, s.classifierReason, count(*) AS occurrences ORDER BY occurrences DESC` to surface ontology-growth candidates.
+5. **Provenance stamp.** Every section, standalone, and edge gets `createdByAgent='document-ingest'`, `createdBySession=<sessionId>`, `source='document'`, `sourceDocumentId=<attachmentId>`. Stamped automatically by `memory-ingest` for everything it writes; **also stamped by every `memory-write` call in step 4** (`wire-brief-entities`) on the edge properties — without these stamps, brief-wired edges leak on re-ingest.
+6. **Idempotent re-ingest.** `memory-ingest` is safe to re-run with the same `attachmentId`. Prior `:Section` children (any secondary label) and `:Project` standalones are deleted; prior KD-level edges are deleted by **provenance match** — every edge stamped `sourceDocumentId=<this attachmentId>` is dropped, regardless of edge type. The legacy `PARTY` edge type is also matched by name as a belt-and-braces for pre-stamping data. Any KD-level edge that this pipeline writes (classifier-emitted PARTY/PARTICIPANT/FROM/TO/CC/SPEAKER and agent-emitted brief-wired MENTIONS/REFERENCES/etc.) MUST carry the stamp — without it, the edge persists across re-ingests as a duplicate. MERGEd shared entities (Organizations, Persons referenced by other docs) are spared.
+7. **Loud failure, never silent landfill.** Classifier failure aborts the ingest; nothing is written. Edge orphans are surfaced via `orphanCandidates`; the writer never synthesises edges to "fix" them.
+8. **Brief is a deliverable, not a hint.** Step 4 is mandatory whenever the dispatch brief named entities. Returning *"document ingested as a KnowledgeDocument anchored to <X>"* without listing wired/unresolved brief entities is a silent failure — the document becomes an island anchored to one node while the named Persons/Organizations/Tasks stay disconnected, defeating adjacency-ranked `memory-search`. The `[document-ingest] wire-brief-entities` log line is the verification surface; `edges=0` while the brief listed entities is a regression.
+9. **Typed-entity edges never target a `:Section`.** Edge types declared in `TYPED_EDGE_ALLOWLIST` (`FOUNDED`, `WORKS_AT`, `INVESTED_IN`, `ADVISES`, `MENTIONS`, `AUTHORED`, `ATTACHED_TO`, `REFERENCES`, `ATTENDED`) must honour the (source, target) label shapes declared there. When the natural target is the document anchor (e.g. founders in a company-page Team section), set `edge.targetMode = "anchor"` on the related entry — the writer routes the edge to the anchor instead of the section. The writer rejects loud with the offending `(:Source)-[:EDGE]->(:Target)` triple on any classifier emission that violates the allowlist.
+
+## Output contract
+
+Return to the admin agent:
+- **What you did** — filename, anchor (`UserProfile` / `LocalBusiness` / etc.), scope.
+- **Outcome** — `documentNodeId`, `sectionCount`, `kindBreakdown`, `edgeBreakdown`, `relatedCount`, `standaloneCount`. Surface the document summary and extracted keywords so the admin can echo them back to the operator.
+- **Brief-entity wiring** — list of brief-named entities resolved (with elementId + edge type written) and not-found (orphans). Empty when the brief named no entities. Never elide; absence is silently broken adjacency.
+- **Orphan candidates** — for each entry the classifier flagged: kind, label, reason. The admin agent reads these to decide whether the orphan is intentional (rare, valid) or a classifier miss (bug). Never silently skip.
+- **Ontology gaps** — list any `:Section:Other` titles + classifierReasons. The admin agent reads these to decide whether to extend the ontology in a follow-up task.
+- **Blockers** — anchor unconfirmed, classifier failure (Haiku unavailable, malformed JSON, etc.), schema validator rejection, write failure mid-ingest.

package/payload/platform/plugins/memory/skills/emerge/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: emerge
+description: "Clusters KnowledgeDocument and Section nodes that have no Concept parent yet, names each cluster, and proposes a Concept node through the operator-approval write path. Run when the operator types `/emerge` or asks 'what themes are emerging in my notes', 'find unclustered knowledge', 'what haven't I connected yet'. Each proposal requires operator approval before any write."
+---
+
+# Emerge
+
+Invoked by the admin agent directly.
+
+This skill surfaces unnamed clusters of knowledge already in the operator's graph — documents and sections that share a theme but have no Concept node connecting them yet. For each cluster it proposes a name and routes the write through the operator-approval gate. It never writes without approval.
+
+## When to run
+
+Run when the operator wants to discover unclustered themes: `/emerge`, "what themes are emerging in my notes", "find unclustered knowledge", "what haven't I connected yet". Run on demand; do not run as a routine maintenance pass.
+
+## Method
+
+1. **Retrieve candidates.** Issue `memory-search` with a broad query ("recent knowledge notes"), `labels: ["KnowledgeDocument", "Section"]`, `limit=50, expandHops=0`. The `expandHops=0` keeps output compact — deep neighborhood context is not needed at retrieval time.
+
+2. **Filter already-clustered.** From the returned nodes, exclude any node that has a `:RELATES_TO` edge to a `:Concept` node visible in its neighborhood. If unsure whether a node is clustered, err on the side of inclusion — the operator will skip it in the approval step.
+
+3. **Group by similarity.** Cluster the remaining nodes by semantic similarity: nodes whose content shares a clear theme. Clusters of fewer than 3 nodes are set aside as "too small to cluster" and listed separately at the end.
+
+4. **Name each cluster.** Compose a short noun-phrase name (1–4 words) from the highest-weighted terms shared across the cluster's nodes. The name should generalise the cluster, not copy a document title.
+
+5. **Identify the parent.** For each cluster, identify the most likely `:Project` or `:LocalBusiness` parent — the entity most cluster members are already connected to. Name it in the proposal row. If no clear parent is identifiable, ask the operator before presenting the proposal.
+
+6. **Present proposals one at a time.** The operator picks one of three actions per proposal: **wire** (write the `:Concept` and edges), **skip**, or **rename** (operator supplies a new name; re-propose with the new name before proceeding).
+
+## Write shape (per approved cluster)
+
+```
+memory-write {
+  label: "Concept",
+  properties: {
+    name: "<cluster name>",
+    description: "<one-sentence description of what the cluster members share>",
+    accountId: "<accountId>",
+    createdByAgent: "emerge",
+    createdAt: datetime()
+  },
+  parent: { elementId: "<project-or-localbusiness-elementId>", edgeType: "PART_OF" },
+  relationships: [
+    { type: "RELATES_TO", direction: "out", target: "<member elementId>" }
+    ... one per cluster member
+  ]
+}
+```
+
+Apply each approved write before presenting the next proposal. Never batch-write.
+
+## Output
+
+Per proposal row:
+```
+**[N] <cluster name>**
+Members (<count>): <title-1> (ID: `<id>`), <title-2> (ID: `<id>`), ...
+Parent: <parent entity name>
+Description: <one-sentence>
+→ wire / skip / rename?
+```
+
+End-of-run summary (after all proposals are decided):
+```
+<K> clusters proposed, <A> wired, <S> skipped, <R> renamed.
+Too small to cluster: <title-1>, <title-2> (list of 1–2 node sets, if any)
+```
+
+## Failure modes
+
+- **All nodes already clustered.** Report "All retrieved knowledge is already connected to a Concept node. Nothing to propose." Do not re-run.
+- **No nodes retrieved.** Report "No KnowledgeDocument or Section nodes found. Nothing to cluster."
+- **`memory-write` failure mid-batch.** Stop. Report which clusters were wired before the failure and which were not.
+
+## Observability
+
+Emit one log line per proposed cluster:
+```
+[memory-thinking] skill=emerge clusterSize=<N> proposedConcept=<name> elapsedMs=<N>
+```
+
+`clusterSize` is the number of member nodes in that cluster. `elapsedMs` is measured from skill invocation to the moment the proposal is presented to the operator (not including operator decision time).
+
+If no clusters are proposed (all nodes already clustered, or no nodes retrieved), emit one line to mark the invocation:
+```
+[memory-thinking] skill=emerge clusterSize=0 proposedConcept=none elapsedMs=<N>
+```
+
+Absence of any `skill=emerge` log line means the skill was not invoked (operator typo or routing miss).

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

@@ -0,0 +1,8 @@
+{
+  "name": "notion-import",
+  "description": "Import a Notion workspace export (markdown + CSV directory) into the 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/notion-import/PLUGIN.md

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

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

@@ -0,0 +1,114 @@
+---
+name: notion-import
+description: Import a Notion workspace export (markdown + CSV) into a {{productName}} Neo4j graph. Triggers when the user asks to import a Notion workspace, ingest a Notion export, or mentions a `Export-*.zip` / unzipped Notion export directory. Pages become `:KnowledgeDocument` nodes, database rows become typed entities (or `:KnowledgeDocument` if no schema mapping fits), database schemas become `:KnowledgeDocument` siblings, hierarchy is preserved via `:HAS_SECTION`, attachments are copied locally and written as `:DigitalDocument`.
+---
+
+# Notion Import
+
+**Invoked from `specialists:librarian`** when the operator drops a Notion workspace export directory (or `Export-*.zip` path) and asks to import it. The admin agent dispatches the librarian; the librarian 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.