@rubytech/create-maxy-code 0.1.132 → 0.1.140

package/payload/platform/plugins/memory/mcp/dist/tools/session-retrospective-skip-rate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-retrospective-skip-rate.js","sourceRoot":"","sources":["../../src/tools/session-retrospective-skip-rate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgBH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,IAAyB,EACzB,OAAgB,EAChB,SAAiB;IAEjB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAErE,wEAAwE;IACxE,kEAAkE;IAClE,sEAAsE;IACtE,6BAA6B;IAC7B,wEAAwE;IACxE,wEAAwE;IACxE,mEAAmE;IACnE,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;GAuBd,CAAC;IAEF,4EAA4E;IAC5E,oDAAoD;IACpD,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;GAuBtB,CAAC;IAEF,MAAM,WAAW,GAAG;QAClB,SAAS;QACT,MAAM;QACN,SAAS;QACT,OAAO;QACP,MAAM;QACN,MAAM;QACN,MAAM;QACN,QAAQ;KACT,CAAC;IAEF,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;YACvC,SAAS;YACT,UAAU;YACV,WAAW;SACZ,CAAC,CAAC;QACH,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE;YAC/C,SAAS;YACT,UAAU;YACV,WAAW;SACZ,CAAC,CAAC;QACH,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,cAAc,EAAE,CAAC;YACjB,uBAAuB,EAAE,CAAC;YAC1B,QAAQ,EAAE,CAAC;YACX,qBAAqB,EAAE,IAAI;SAC5B,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,MAAM,uBAAuB,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9E,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,cAAc,GAAG,CAAC;QACjC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,GAAG,uBAAuB,CAAC,GAAG,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC,CAAC;IACN,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3C,MAAM,gBAAgB,GAAG,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAE9E,OAAO,CAAC,GAAG,CACT,+CAA+C,YAAY,YAAY,cAAc,cAAc,uBAAuB,cAAc,QAAQ,mBAAmB,gBAAgB,IAAI,MAAM,EAAE,CAChM,CAAC;IAEF,OAAO;QACL,cAAc;QACd,uBAAuB;QACvB,QAAQ;QACR,qBAAqB,EAAE,gBAAgB;KACxC,CAAC;AACJ,CAAC"}

package/payload/platform/plugins/memory/mcp/scripts/backfill-typed-edges.ts

@@ -0,0 +1,72 @@
+/**
+ * One-shot backfill of the typed-edge pass over every existing prose-bearing
+ * node for the current account. Idempotent — MERGE handles re-runs cleanly,
+ * so a second invocation accepts zero edges.
+ *
+ * Usage (admin-agent invokable via Bash):
+ *   cd platform/plugins/memory/mcp
+ *   node --loader ts-node/esm scripts/backfill-typed-edges.ts
+ *
+ * Reads ACCOUNT_ID from env (same convention as the MCP server). Loops
+ * `runTypedEdgePass` with `sinceIso: null` in 500-node pages until the
+ * page returns 0 nodes (exhausted). Logs per-batch progress with
+ * `[typed-edge-pass:backfill]`.
+ */
+
+import { getSession, closeDriver } from "../src/lib/neo4j.js";
+import { runTypedEdgePass } from "../src/lib/typed-edge-pass.js";
+
+const PAGE_SIZE = 500;
+
+async function main(): Promise<void> {
+  const accountId = process.env.ACCOUNT_ID;
+  if (!accountId) {
+    console.error("ACCOUNT_ID env var is required");
+    process.exit(1);
+  }
+
+  let batch = 0;
+  let totalNodes = 0;
+  let totalAccepted = 0;
+  let totalRejected = 0;
+  let totalFailed = 0;
+
+  while (true) {
+    const session = getSession();
+    try {
+      const result = await runTypedEdgePass({
+        session,
+        accountId,
+        sinceIso: null,
+        conversationId: null,
+        maxNodes: PAGE_SIZE,
+      });
+      batch += 1;
+      totalNodes += result.nodes;
+      totalAccepted += result.accepted;
+      totalRejected += result.rejected;
+      totalFailed += result.failed;
+      console.log(
+        `[typed-edge-pass:backfill] batch=${batch} done=${totalNodes} accepted=${result.accepted} rejected=${result.rejected} failed=${result.failed} ms=${result.ms}`,
+      );
+      if (result.nodes < PAGE_SIZE || result.accepted === 0) {
+        // Exhausted: either the page came back short, or a re-run page
+        // produced no new accepted edges (idempotency convergence).
+        break;
+      }
+    } finally {
+      await session.close();
+    }
+  }
+
+  console.log(
+    `[typed-edge-pass:backfill] complete batches=${batch} totalNodes=${totalNodes} totalAccepted=${totalAccepted} totalRejected=${totalRejected} totalFailed=${totalFailed}`,
+  );
+  await closeDriver();
+}
+
+main().catch(async (err) => {
+  console.error(`[typed-edge-pass:backfill] error: ${err instanceof Error ? err.message : String(err)}`);
+  await closeDriver();
+  process.exit(1);
+});

package/payload/platform/plugins/memory/mcp/scripts/generate-edge-docs.ts

@@ -0,0 +1,75 @@
+/**
+ * Emit the typed-edge enumeration into the public docs from the
+ * `TYPED_EDGE_ALLOWLIST` source of truth, so the prompt, the validator,
+ * and the docs cannot drift from each other.
+ *
+ * Targets:
+ *   - .docs/neo4j.md (parent maxy-code .docs surface)
+ *   - platform/plugins/docs/references/neo4j.md (bundled into the payload)
+ *
+ * Replaces the block delimited by:
+ *   <!-- TYPED-EDGE-TABLE:START -->
+ *   <!-- TYPED-EDGE-TABLE:END -->
+ *
+ * Usage:
+ *   node --loader ts-node/esm scripts/generate-edge-docs.ts
+ */
+
+import { writeFileSync, readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { TYPED_EDGE_ALLOWLIST } from "../src/lib/typed-edge-schema.js";
+
+const TARGET_PATHS = [
+  // maxy-code/.docs/neo4j.md — resolved relative to this script.
+  resolve(import.meta.dirname ?? __dirname, "../../../../../.docs/neo4j.md"),
+  // bundled docs twin
+  resolve(import.meta.dirname ?? __dirname, "../../../docs/references/neo4j.md"),
+];
+
+const START_MARKER = "<!-- TYPED-EDGE-TABLE:START -->";
+const END_MARKER = "<!-- TYPED-EDGE-TABLE:END -->";
+
+function buildTable(): string {
+  const rows = TYPED_EDGE_ALLOWLIST
+    .map(({ sourceLabel, edgeType, targetLabel }) => `| ${sourceLabel} | ${edgeType} | ${targetLabel} |`)
+    .join("\n");
+  return [
+    START_MARKER,
+    "",
+    "<!-- Generated by platform/plugins/memory/mcp/scripts/generate-edge-docs.ts from TYPED_EDGE_ALLOWLIST. Do not edit by hand. -->",
+    "",
+    "| Source label | Edge type | Target label |",
+    "|---|---|---|",
+    rows,
+    "",
+    END_MARKER,
+  ].join("\n");
+}
+
+function applyToFile(path: string, table: string): "wrote" | "missing" | "no-markers" {
+  if (!existsSync(path)) return "missing";
+  const current = readFileSync(path, "utf-8");
+  const startIdx = current.indexOf(START_MARKER);
+  const endIdx = current.indexOf(END_MARKER);
+  let next: string;
+  if (startIdx === -1 || endIdx === -1) {
+    // No markers — append the section under a clear heading rather than
+    // failing. Idempotent on subsequent runs because we add the markers.
+    next = `${current.trimEnd()}\n\n## Typed-edge allowlist (generated)\n\n${table}\n`;
+    writeFileSync(path, next);
+    return "wrote";
+  }
+  next = current.slice(0, startIdx) + table + current.slice(endIdx + END_MARKER.length);
+  writeFileSync(path, next);
+  return "wrote";
+}
+
+function main(): void {
+  const table = buildTable();
+  for (const path of TARGET_PATHS) {
+    const result = applyToFile(path, table);
+    console.log(`[generate-edge-docs] ${path} -> ${result}`);
+  }
+}
+
+main();

package/payload/platform/plugins/memory/mcp/vitest.config.ts

@@ -22,6 +22,11 @@ export default defineConfig({
       "src/lib/__tests__/schema-cypher-drift.test.ts",
       // Task 350 — label-origin gate (refuse agent-side LocalBusiness writes).
       "src/lib/__tests__/label-origin-gate.test.ts",
+      // Task 305 — typed-edge allowlist schema invariants.
+      "src/lib/__tests__/typed-edge-schema.test.ts",
+      // Task 306 — compiled-truth + timeline.
+      "src/lib/__tests__/timeline-extractor.test.ts",
+      "src/lib/__tests__/graph-write-gate-property.test.ts",
     ],
     testTimeout: 10_000,
   },

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

@@ -46,6 +46,7 @@ When loading this reference, confirm which schema files were consulted by noting
 | VoiceEdit | `VoiceEdit` | platform-native (Task 356 — operator edit on an agent draft) | — | `accountId`, `adminUserId`, `originalText`, `editedText`, `intent`, `occurredAt` |
 | AEO Audit | `AEOAudit` | platform-native (AEO audit history) | — | `accountId`, `auditId`, `target`, `score`, `heuristicsJson`, `runAt`, `createdByAgent`, `createdBySession`, `createdAt` |
 | Idea | `Idea` | platform-native (signal-detector original-thinking candidate) | — | `accountId`, `body`, `conversationId`, `scope`, `createdByAgent`, `createdBySession`, `createdAt` |
+| TimelineEvent | `TimelineEvent` | platform-native (Task 306 — compiled-truth + timeline doctrine) | — | `accountId`, `timelineEventId`, `occurredAt`, `kind`, `summary`, `source` |
 
 **Branding properties on LocalBusiness:** `primaryColor`, `accentColor`, `backgroundColor`, `tagline` — optional, used to brand the public chat endpoint. Hex color values must match `#[0-9a-fA-F]{3,8}`. Logo and icon are linked via `HAS_BRAND_ASSET → ImageObject` with `purpose: "logo"` or `"icon"`.
 
@@ -71,6 +72,49 @@ When loading this reference, confirm which schema files were consulted by noting
 
 ---
 
+## Compiled truth + timeline (Task 306)
+
+Every `:Person`, `:Organization`, and `:Concept` carries a two-part knowledge shape: a **compiled truth** above the rule (the agent's current best understanding of the subject, rewritten when evidence changes) and an **append-only timeline** below (dated events linked via `:HAS_TIMELINE_EVENT`, never edited).
+
+| Property | Type | Purpose |
+|---|---|---|
+| `compiledTruth` | string ≤2000 chars | The current summary. Empty on first write. |
+| `compiledTruthUpdatedAt` | datetime | Last rewriter or operator write. Epoch on first write. |
+| `compiledTruthSource` | `'rewriter' \| 'operator'` | Last writer. Operator edits get a 7-day cooldown that the rewriter respects unless `forceRewrite=true` is passed. |
+
+The compiled truth is system-managed: direct writes to any of the three properties via `memory-update` are **rejected loudly**. The only paths to mutate are:
+
+- `memory-update(nodeId, {}, rewriteCompiledTruth: true)` — invokes the OAuth-LLM rewriter against the most recent 10 `:TimelineEvent` rows.
+- `memory-update(nodeId, {}, rewriteCompiledTruth: true, forceRewrite: true)` — same, but bypasses the 7-day operator cooldown.
+- The graph UI's per-property edit surface — stamps `compiledTruthSource: 'operator'` so the rewriter honours the cooldown.
+
+### Timeline events
+
+`:TimelineEvent` is distinct from the scheduling plugin's `:Event` (which holds `eventId`-unique calendar/reminder rows). Naming chosen to avoid collision.
+
+`:HAS_TIMELINE_EVENT` is distinct from visitor-analytics' `:HAS_EVENT` (`Session → PageView/Click/ScrollMilestone`). Naming chosen to avoid collision.
+
+`kind` enum (5 values, no catch-all):
+
+```
+mentioned | met | quoted | attended | transacted
+```
+
+The extractor refuses on ambiguity rather than collapsing to "other". Default on write is `mentioned`; the typed-edge post-write hook (Task 305) upgrades the kind asynchronously when it can.
+
+### Write doctrine
+
+Path-anchored MERGE — never label-only:
+
+```cypher
+MATCH (e) WHERE elementId(e) = $entityId AND e.accountId = $accountId
+MERGE (e)-[:HAS_TIMELINE_EVENT]->(t:TimelineEvent {timelineEventId: $id})
+```
+
+`memory-write` runs the deterministic date extractor against the `body` property of any `:Person` / `:Organization` / `:Concept` write and creates one `:TimelineEvent` per parseable dated statement.
+
+---
+
 ## Forbidden Properties
 
 Properties listed here are **rejected at write-time** by the schema validator on the listed label. Rejection runs after the synonym pass, so a `firstName → givenName` rewrite still happens before the forbidden-property check. The rule is per-label: `name` is forbidden on `Person` only; `Organization`, `Event`, `Conversation`, `Service`, etc. retain `name` as a canonical property.

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

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

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

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

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

@@ -0,0 +1,110 @@
+---
+name: notion-import
+description: Import a Notion workspace export (markdown + CSV) into a {{productName}} Neo4j graph. Triggers when the user asks to import a Notion workspace, ingest a Notion export, or mentions a `Export-*.zip` / unzipped Notion export directory. Pages become `:KnowledgeDocument` nodes, database rows become typed entities (or `:KnowledgeDocument` if no schema mapping fits), database schemas become `:KnowledgeDocument` siblings, hierarchy is preserved via `:HAS_SECTION`, attachments are copied locally and written as `:DigitalDocument`.
+---
+
+# Notion Import
+
+**Invoked from `specialists:database-operator`** when the operator drops a Notion workspace export directory (or `Export-*.zip` path) and asks to import it. The admin agent dispatches the database-operator; the database-operator loads this skill.
+
+**Anchor model.** A Notion export does not have a single subject the way a LinkedIn archive does — pages have multiple authors, databases are shared workspaces, mentions span the whole org. The skill anchors **import provenance** on the importing `:AdminUser` via `IMPORTED_BY` (so every node in the import can be traced back to who pushed the button); page authorship is captured separately via `AUTHORED` when the export records an author. The `:AdminUser` is identity, not subject — pages are not "owned" by the importer.
+
+Every node this skill writes carries an `importId` property (UUID per skill run) so a future dream-cycle pass can detect orphans or selectively re-ingest.
+
+## Import-provenance confirmation (mandatory first step)
+
+A Notion export is dropped by one operator on behalf of one workspace. Before any file is read, the skill confirms two things:
+
+1. **Importing AdminUser.** The `:AdminUser` who pushed the button. Default is the live operator (the session's userId); confirm by echoing `userId=<id> name=<name>` and accepting yes/no. If the operator is importing on behalf of someone else — a partner, a client whose workspace they're staging — accept either an existing AdminUser userId or a new `:Person` natural-key (`givenName` + `familyName` + at least one of `email` / `telephone`) as the importing identity. Persist as `$importerNodeId`.
+2. **Workspace label.** A short human label (`"Joel's personal workspace"`, `"Rubytech ops"`) used as the value of `:NotionWorkspace.name`. One `:NotionWorkspace` node is MERGEd per `(accountId, name)` natural key; re-imports of the same workspace match it.
+
+The skill refuses to read the export directory until both values are echo-confirmed.
+
+## Anchor shape
+
+```
+(:AdminUser {userId: $importerUserId})
+  -[:IMPORTED { importId, source: 'notion', startedAt }]->
+    (:NotionWorkspace { accountId, name })
+      -[:HAS_SECTION]-> (:KnowledgeDocument { kind: 'notion-page', notionId, importId })
+      -[:HAS_SECTION]-> (:KnowledgeDocument { kind: 'notion-database', notionId, importId })
+```
+
+`:NotionWorkspace` is the only new label the skill needs; everything below it reuses {{productName}} canonical labels (`:KnowledgeDocument`, `:Person`, `:Organization`, `:DigitalDocument`). Page hierarchy from Notion's parent-child relation is written as `:HAS_SECTION` between `:KnowledgeDocument` pages.
+
+## Invariants
+
+1. **Schema first.** No new constraints or indexes are required; the canonical schema in [`platform/plugins/memory/references/schema-base.md`](../../../../plugins/memory/references/schema-base.md) covers every label this skill writes. If the operator's workspace surfaces a database shape no canonical label fits, the rows are written as `:KnowledgeDocument` with `kind: 'notion-row'` and the gap is reported to admin — the skill does not mint new labels at runtime.
+2. **Provenance confirmed first.** No file is read until `$importerNodeId` (AdminUser or external Person) and `$workspaceName` are persisted and echo-confirmed.
+3. **Closed edge vocabulary.** Edges written are drawn from `schema-base.md` only. Unmapped Notion relations (a custom DB-to-DB link the operator named `sponsored_by`, say) land as `:MENTIONS` from the source page's `:KnowledgeDocument`, with the Notion relation label stored as a property (`mentionContext: '<relation-name>'`). `RELATES_TO` is **not** a schema edge and is not used.
+4. **Account isolation on fuzzy resolves.** Every inline `@person` mention resolves against `:Person {accountId: $accountId}` — never label-only. A "John Smith" mention in the importing account never matches a `:Person` in another account, even if the names are identical. When no in-account match is found, the mention is written as a new `:Person` with `givenName` / `familyName` parsed from the mention text and `source='notion'`.
+5. **Idempotent MERGE on Notion IDs.** Every Notion page and row carries a stable Notion UUID. Pages MERGE on `(accountId, notionId)`; database rows MERGE on `(accountId, notionId)`; attachments MERGE on `(accountId, sha256)`. Re-import of the same export is a property-update no-op on existing nodes — `skipped` counter advances, no duplicates.
+6. **Provenance stamps.** Every new node: `createdByAgent='notion-import'`, `createdBySource='notion'`, `createdBySession=$sessionId` (UUID per skill run), `createdAt=datetime()`, `importId=$importId`, plus `source='notion'`.
+7. **No raw Cypher, no bash improvisation.** Writes route through `mcp__plugin_memory_memory__memory-write` and `mcp__plugin_memory_memory__memory-update` (per-node), plus `mcp__plugin_memory_memory__memory-search` for parent / mention resolution. If a write shape the skill needs is missing from the tool surface, the gap is filed as a follow-up task — never improvised via Bash.
+
+## 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.
+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.
+4. For each shape, follow the matching reference:
+   - Pages → [page-tree.md](references/page-tree.md). Resolves parent page, MERGEs the `:KnowledgeDocument`, writes `:HAS_SECTION` from parent. Inline `@person` mentions resolved per Invariant 4.
+   - Databases → [databases.md](references/databases.md). Database itself becomes a `:KnowledgeDocument {kind: 'notion-database'}`. Each row becomes a typed entity if the database's name + schema fits a canonical label (a "People" DB → `:Person`; a "Projects" DB → `:Project`); otherwise the row lands as `:KnowledgeDocument {kind: 'notion-row'}` with the schema properties preserved on the node. Notion's typed relation columns become canonical edges where schema allows; unmapped relations are `:MENTIONS`.
+   - Attachments → [attachments.md](references/attachments.md). Copied to `{accountDir}/archive/notion/<importId>/`, content-hashed, written as `:DigitalDocument {kind: 'notion-attachment', sha256}`. Referenced from pages via `:HAS_ATTACHMENT`.
+5. Emit `[notion-import] importId=<id> pages=<n> rows=<n> relations=<n> mentions=<n> attachments=<n> skipped=<n> ms=<elapsed>` at completion. Per-file errors emit `[notion-import:error] file=<path> reason=<…>`; the skill continues past parse failures so a single bad file does not abort the entire import.
+
+## 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.
+- **Bulk archiveType handler.** Per-node `memory-write` issues one Cypher transaction per node. For a 5,000-page workspace this is ~5,000 round-trips with no per-transaction atomicity. A `notion-pages` archiveType handler in `memory-archive-write` would batch this; the follow-up is tracked at `.tasks/395-notion-bulk-archive-handler.md`.
+
+## Schema-mapping table
+
+The skill maps Notion shapes to canonical {{productName}} labels and edges. Schema additions are last resort — every row below uses an existing label from `schema-base.md`.
+
+| Notion shape | Canonical label | Notes |
+|--------------|-----------------|-------|
+| Workspace | `:NotionWorkspace` | New label, single property `name` plus `accountId`. Only new label introduced by this skill. |
+| Page | `:KnowledgeDocument { kind: 'notion-page' }` | Body markdown stored as `text`. Hierarchy via `:HAS_SECTION`. |
+| Page authored-by | `(:Person)-[:AUTHORED]->(:KnowledgeDocument)` | When the export records an author, resolve to in-account `:Person`. |
+| Database (the table itself) | `:KnowledgeDocument { kind: 'notion-database' }` | Schema preserved as `schema` (JSON-stringified property list). |
+| Database row, canonical-fit | `:Person`, `:Organization`, `:Project`, `:Task`, `:Event` | Database name + columns drive label selection. A "People" DB with `email`/`telephone` columns → `:Person`. |
+| Database row, no fit | `:KnowledgeDocument { kind: 'notion-row' }` | Properties preserved on the node; surface to admin in the completion log if any DB lands here entirely. |
+| Notion relation, schema-mapped | Canonical edge from `schema-base.md` | A relation column named `works_at` between People and Companies → `(:Person)-[:WORKS_FOR]->(:Organization)`. |
+| Notion relation, unmapped | `:MENTIONS { mentionContext: '<relation-name>' }` | Source page `:KnowledgeDocument` → target. Preserves the Notion relation name for later audit. |
+| Inline `@person` mention | `(:KnowledgeDocument)-[:MENTIONS]->(:Person)` | Account-filtered fuzzy resolve per Invariant 4. |
+| Attachment | `:DigitalDocument { kind: 'notion-attachment', sha256 }` | Files copied to `{accountDir}/archive/notion/<importId>/`. |
+| Page hierarchy | `(:KnowledgeDocument)-[:HAS_SECTION]->(:KnowledgeDocument)` | Parent-of-child per Notion's nesting. |
+
+If the operator's workspace introduces a database that fits none of the canonical labels and is not satisfied by the `:KnowledgeDocument` fallback, surface the gap to admin in the completion summary — never mint a new label at runtime.
+
+## Natural-edge discipline (why this matters)
+
+Every edge written corresponds to a relationship the Notion export actually expresses. `:HAS_SECTION` is real — Notion explicitly records page parents. `:AUTHORED` is real when the export records it. `:WORKS_FOR` is real when a People DB has a Companies-relation column. Synthetic "attach-everything-to-the-importer" edges are forbidden — the importer is provenance (via `IMPORTED`), not the subject of every page. A workspace with thousands of unrelated pages does not get thousands of edges manufactured to "make it reachable"; the workspace-level `IMPORTED` edge already makes them reachable through the importer.

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

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

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

@@ -0,0 +1,81 @@
+# databases
+
+Reference for ingesting Notion databases — both the database (schema) and its rows.
+
+## Shape on disk
+
+A Notion database lands as a `.csv` file plus a sibling directory of the same basename. The CSV is the table-view export; the directory contains one `.md` per row, with the row's properties as YAML front-matter and the row body as markdown below.
+
+```
+Projects 7a1b2c…/
+  Projects 7a1b2c….csv        ← schema + row table
+  Projects 7a1b2c…/             ← row markdowns
+    Phoenix Migration 9f3a…md
+    Q3 Strategy d4e5…md
+```
+
+The CSV columns are the database's properties. Column types are not encoded in the CSV directly — they are inferred from the values (date-shaped, URL-shaped, person-mention-shaped, relation-shaped). A relation column's cells contain the human title plus Notion ID of the linked row.
+
+## What the database itself becomes
+
+Each Notion database is written as one `:KnowledgeDocument { kind: 'notion-database' }` node:
+
+- `notionId` — the 32-hex ID from the CSV basename.
+- `name` — human title from the CSV basename.
+- `schema` — JSON-stringified list of `{ name, inferredType }` per column.
+- `parentPageNotionId` — the page that contains the database, if any.
+
+The database is attached to the workspace root via `(:NotionWorkspace)-[:HAS_SECTION]->(:KnowledgeDocument)` and, when nested under a page, also via `(:KnowledgeDocument {page-parent})-[:HAS_SECTION]->(:KnowledgeDocument {database})`.
+
+## Label selection for rows
+
+Per-row label is decided by the database's name and column set together — not by either alone.
+
+- **`:Person`** when the database name matches `^(people|contacts|crm|team|members?)$` (case-insensitive) AND the columns contain at least one of `email`, `phone`, `telephone`, `linkedin`. Properties map onto schema-base camelCase: `givenName` / `familyName` from a single `name` column split on first space (preserve `name` only if no canonical Person property fits); `email`, `telephone`, `jobTitle`, etc.
+- **`:Organization`** when the name matches `^(companies|orgs|organizations?|accounts)$` AND the columns contain `website` or `domain`.
+- **`:Project`** when the name matches `^projects?$` AND the columns contain at least one of `status`, `startDate`, `dueDate`, `owner`.
+- **`:Task`** when the name matches `^(tasks?|todo|to-?dos?|action items?)$` AND the columns contain at least one of `done`, `status`, `assignee`, `dueDate`.
+- **`:Event`** when the name matches `^(events?|meetings?|calendar)$` AND the columns contain `startDate` / `start` / `date`.
+- **`:KnowledgeDocument { kind: 'notion-row' }`** — fallback. The CSV columns are preserved on the node as properties. Surface to admin in the completion log if any database falls entirely into this bucket — it usually means the workspace has a custom DB shape worth handling explicitly in a future iteration.
+
+When admin's brief is ambiguous about which label a database should land in, the database-operator's `{ambiguity, proposed}` protocol applies — ask, don't guess.
+
+## Row write recipe
+
+For each row in the parsed CSV:
+
+1. **Resolve the parent.** Every row's parent is its database (the `:KnowledgeDocument { kind: 'notion-database' }`). Edge: `(:KnowledgeDocument {database})-[:HAS_SECTION]->(row)`.
+2. **Select the label** per the rules above.
+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. **Resolve relation columns.** A relation column cell is `"Linked Row Title <32-hex-notionId>"`. Look up `:KnowledgeDocument {notionId}` (any kind — the linked row may have already been imported, or may land later in the same import). When the target is found and the relation name maps to a canonical edge (table below), write the canonical edge; otherwise write `:MENTIONS` with `mentionContext: '<relation-column-name>'`.
+5. **Issue the write** via `mcp__plugin_memory_memory__memory-write` with the selected label, properties, and edges.
+
+## 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). The write loop runs in two passes:
+
+- **Pass 1** — write every node, deferring relation columns. Skip the relation step but keep the relation cell text alongside the manifest entry.
+- **Pass 2** — walk the manifest again with every Notion node now MERGEd, resolve each deferred relation by `notionId`, write the edge.
+
+Two passes are deterministic and keep the per-row write idempotent. The completion log reports the `relations` count 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 saw a relation cell pointing at a Notion ID that is not in the import (a row outside the operator's filter, or an externally-linked workspace row). Skip the edge; log; continue.
+- `[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 `:KnowledgeDocument { kind: 'notion-page' }` node per page:
+
+- `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 properties below).
+- `notionCreatedAt`, `notionLastEditedAt` — front-matter date fields parsed to `datetime()`.
+- `accountId`, `importId`, `source='notion'`, `createdByAgent='notion-import'`, `createdBySession`, `createdAt` — standard provenance per SKILL invariant 6.
+
+## Hierarchy
+
+Page hierarchy is written as `:HAS_SECTION` between `:KnowledgeDocument` nodes:
+
+- **Top-level pages** — parent is the `:NotionWorkspace`. Edge: `(:NotionWorkspace)-[:HAS_SECTION]->(:KnowledgeDocument)`.
+- **Nested pages** — parent is the enclosing page's `:KnowledgeDocument`. Edge: `(:KnowledgeDocument {parent})-[:HAS_SECTION]->(:KnowledgeDocument {child})`.
+
+The parent's `notionId` is the basename of the enclosing directory; resolve via `mcp__plugin_memory_memory__memory-search` keyed on `(accountId, notionId)`.
+
+## 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, write `(:KnowledgeDocument)-[:MENTIONS]->(:Person)`. On miss, write a new `:Person { givenName, familyName, source='notion', accountId }` and the same edge — 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)`. Resolve by `notionId`:
+
+- If the target is in the current import (`:KnowledgeDocument {notionId}` exists or will exist after this pass), defer to pass 2 and write `(:KnowledgeDocument)-[:MENTIONS]->(:KnowledgeDocument)` with `mentionContext: 'page-link'`.
+- If the target is outside the import (an externally-linked page the operator's filter excluded, or a page in a different workspace), skip the edge and log `[notion-import:error] reason=page-link-target-not-found notionId=<id>`.
+
+## 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.