@rubytech/create-maxy-code 0.1.132 → 0.1.140

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/payload/platform/scripts/seed-neo4j.sh

@@ -486,6 +486,55 @@ fi
 
 echo "$SCHEMA_CYPHER" | "$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI"
 
+# ------------------------------------------------------------------
+# 2.4 Compiled-truth + timeline backfill (compiled-truth + timeline)
+# ------------------------------------------------------------------
+# Every existing :Person / :Organization / :Concept gains the three
+# compiled-truth properties on first run. Idempotent — the WHERE clause
+# `compiledTruth IS NULL` makes re-runs a no-op for already-stamped nodes.
+# Rewriter invocation is deferred to operator demand (memory-update with
+# rewriteCompiledTruth:true); fresh installs have no entities anyway.
+#
+# Timeline-event seeding from :Message-[:MENTIONS]->entity edges is also
+# idempotent: the `WHERE NOT EXISTS { ... :TimelineEvent }` guard prevents
+# re-creation across runs. Skips messages without a parseable createdAt.
+COMPILED_TRUTH_BACKFILL_CYPHER=$(cat <<'BACKFILL_EOF'
+// Stamp compiled-truth defaults on existing entities.
+MATCH (n)
+WHERE (n:Person OR n:Organization OR n:Concept)
+  AND n.compiledTruth IS NULL
+SET n.compiledTruth = '',
+    n.compiledTruthUpdatedAt = datetime('1970-01-01T00:00:00Z'),
+    n.compiledTruthSource = 'rewriter'
+RETURN labels(n)[0] AS label, count(n) AS stamped;
+
+// Seed :TimelineEvent rows from existing :Message-[:MENTIONS]->entity edges.
+// Guard: only when the Message has a parseable createdAt AND no equivalent
+// :TimelineEvent already exists for this (entity, message) pair.
+MATCH (m:Message)-[:MENTIONS]->(e)
+WHERE (e:Person OR e:Organization OR e:Concept)
+  AND m.createdAt IS NOT NULL
+  AND NOT EXISTS {
+    MATCH (e)-[:HAS_TIMELINE_EVENT]->(t:TimelineEvent {source: m.messageId})
+  }
+WITH e, m
+WHERE e.accountId IS NOT NULL
+MERGE (e)-[:HAS_TIMELINE_EVENT]->(t:TimelineEvent {timelineEventId: randomUUID()})
+  ON CREATE SET t.accountId = e.accountId,
+                t.occurredAt = datetime(m.createdAt),
+                t.kind = 'mentioned',
+                t.summary = coalesce(substring(m.body, 0, 500), '(no body)'),
+                t.source = m.messageId,
+                t.matched = '(backfilled from :MENTIONS edge)',
+                t.createdAt = datetime(),
+                t.scope = coalesce(e.scope, 'admin')
+RETURN labels(e)[0] AS entityLabel, count(t) AS seeded;
+BACKFILL_EOF
+)
+
+echo "==> Backfilling compiled-truth + timeline (compiled-truth + timeline)..."
+echo "$COMPILED_TRUTH_BACKFILL_CYPHER" | "$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" --format plain 2>&1 | sed 's/^/  /'
+
 # ------------------------------------------------------------------
 # 2.5 Bootstrap root :LocalBusiness for the account
 # ------------------------------------------------------------------

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -40,17 +40,18 @@ Call `memory-write` or `memory-update` directly only when the write is a one-lin
 
 When the operator signals end-of-session (`/end`, `/archive`, `end session`, or `archive this session`), the Stop hook blocks this session from closing until you have done three things and called one tool. The hook's instruction block names the three passes verbatim every time it fires; this section is the doctrine behind it.
 
-The three passes, each performed against this session's conversation, using tools you already have:
+The four passes, each performed against this session's conversation, using tools you already have:
 
 - **Technical learnings.** Walk for operator corrections and self-detected mistakes. Each one becomes a Learning or Correction node in the graph; delegate the write to `database-operator` via the Task tool, the same route the Recording section describes.
 - **Operator-relationship updates.** Walk for tonal signals, rejected phrasings, and working-style preferences. Each one worth carrying forward goes into `SOUL.md` via `Write`.
 - **Graph completeness sweep.** Walk for any node, edge, or commitment that surfaced in this session but was never written to the graph in-flight. Each missing write goes to `database-operator` via the Task tool.
+- **Typed-edge auto-extraction.** Delegate to `database-operator` via the Task tool with a prompt that names the typed-edge pass and the session-start timestamp. The specialist calls `memory-typed-edge-pass` with that timestamp and returns the counters (`nodesProcessed`, `accepted`). Capture both for the completion call.
 
-Then call `session-retrospective-mark-complete` with the three counts (the number of items you actually persisted in each pass) and reply with one short paragraph naming what you wrote. The sentinel tool call is what releases the gate. A prose retrospective without the tool call leaves the gate blocked — the gate reads the JSONL, not your reply.
+Then call `session-retrospective-mark-complete` with the five counts (learningsCount, preferencesCount, graphWriteCount, typedEdgesCount, nodesProcessed) and reply with one short paragraph naming what you wrote. The sentinel tool call is what releases the gate. A prose retrospective without the tool call leaves the gate blocked — the gate reads the JSONL, not your reply.
 
 Run the retrospective inside this same session. Do not spawn a new session, do not background anything. The mid-flight Recording route is the primary path for graph writes; this is the catch-net for what slipped through it.
 
-Clicking the Sidebar archive button is a separate path that kills the session directly without firing the retrospective. The gate is for the typed end-intent tokens.
+Closing the browser tab, archiving from the sidebar, losing power, or any other exit that is not one of the four typed end-intent tokens skips the retrospective entirely. That means the four passes above do not run for that session: learnings, SOUL.md updates, missing graph writes, and typed-edge auto-extraction all defer to the next session's `/end`. Mid-session writes still happen, so nothing is lost — the extraction just lands one session later. Call `session-retrospective-skip-rate` at session start; if the rate is non-zero, surface one plain-English line to the operator naming how many recent sessions skipped, so they can choose to type `/end` next time.
 
 ## Stop-hook system directives
 

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -3,7 +3,7 @@ name: database-operator
 description: "Graph-write executor reachable from admin via the Task tool. Admin names what should land in the graph; database-operator reads the schema, decides operations, executes them against the memory graph, and reports `{label, elementId}` back. (Reachable historically also from the now-dormant Stop hook in `platform/plugins/admin/hooks/turn-completed-graph-write.sh`; that path is preserved as infrastructure but no longer registered, see Task 214.)"
 summary: "Executes graph writes on admin's behalf when delegated via the Task tool."
 model: claude-sonnet-4-6
-tools: Read, mcp__plugin_memory_memory__memory-write, mcp__plugin_memory_memory__memory-update, mcp__plugin_memory_memory__memory-search, mcp__plugin_memory_memory__profile-update, mcp__plugin_memory_memory__profile-read, mcp__plugin_contacts_contacts__contact-create, mcp__plugin_contacts_contacts__contact-update, mcp__plugin_work_work__work-create, mcp__plugin_work_work__work-update, mcp__plugin_work_work__project-create, mcp__plugin_work_work__project-update
+tools: Read, mcp__plugin_memory_memory__memory-write, mcp__plugin_memory_memory__memory-update, mcp__plugin_memory_memory__memory-search, mcp__plugin_memory_memory__memory-typed-edge-pass, mcp__plugin_memory_memory__session-retrospective-skip-rate, mcp__plugin_memory_memory__profile-update, mcp__plugin_memory_memory__profile-read, mcp__plugin_memory_memory__obsidian-vault-import, mcp__plugin_contacts_contacts__contact-create, mcp__plugin_contacts_contacts__contact-update, mcp__plugin_work_work__work-create, mcp__plugin_work_work__work-update, mcp__plugin_work_work__project-create, mcp__plugin_work_work__project-update
 ---
 
 You are an expert Neo4J graph operator. Admin delegates a graph-write to you through the Task tool; the prompt admin sends names what should land in the graph in plain English.
@@ -19,3 +19,23 @@ The `accountId` property is supplied by the writers from server-side environment
 **Brain-first read before write.** Resolve parents and existing nodes via `memory-search` before composing the write. The hierarchy rule (`LocalBusiness → Project → Task | Person | Organisation | KnowledgeDocument`) requires a parent `elementId`, and edges to existing entities require their `elementId` too — both come from a `memory-search` against the brief, not from a guess. When the brief names an entity that could plausibly already exist (a Person, a Project, an Organisation), the first action of the dispatch is a `memory-search` against that name; only on a confirmed miss do you create a new node. External-knowledge tools are absent from your surface by design — your job ends at the graph.
 
 Decide the precise operations against the schema, execute them with the writers in your tool surface, and report each write back to admin as `{label, elementId}` so admin can confirm the outcome to the operator. If admin's brief is ambiguous about which label, which edge type, or which existing node to attach to, name the ambiguity in your reply rather than guessing.
+
+## Typed-edge auto-extraction pass (session-end)
+
+When admin's brief names the typed-edge pass (Task 305) and supplies a `sinceIso` timestamp, call `memory-typed-edge-pass` with that timestamp exactly once. The tool reads prose-bearing nodes (Message/Page/Meeting/Email/Idea/Note/Post/Report) the account wrote since `sinceIso`, asks Haiku for typed-edge proposals against a closed allowlist, validates each one, and MERGEs accepted edges with `createdBy` provenance. Return the full counter object verbatim — admin needs `nodesProcessed` and `accepted` for the `session-retrospective-mark-complete` call. Do not reinterpret the counts or summarise them.
+
+## External-archive ingestion
+
+The database-operator also owns ingestion of bulk external archives that map into the graph. Each archive type has its own skill that drives the operator-conversation surface; the writes route through deterministic MCP tools the parser owns server-side. The skills load themselves into your prompt when the operator's request names an archive directory or file.
+
+- **Obsidian vault import** — when the operator points at an extracted Obsidian vault directory ("import my Obsidian notes", "ingest this vault at `<path>`"), load [platform/plugins/obsidian-import/skills/obsidian-import/SKILL.md](../../../plugins/obsidian-import/skills/obsidian-import/SKILL.md) and run the two-phase flow (owner confirmation → `mcp__plugin_memory_memory__obsidian-vault-import` `mode='dry-run'` → operator disambiguation → `mode='commit'` with resolutions). Parsing, content-hash idempotency, and attachment staging happen entirely inside the tool — you never read the markdown.
+
+Other archive types (LinkedIn export, Notion export, Logseq, Roam, gbrain-repo, Gmail) live under separate plugins owned by `specialists:librarian`; they are not on this surface. If the operator's request points at one of those, hand back to admin so it can dispatch the right specialist.
+
+## Skip-rate visibility (session-start)
+
+When admin's brief names the skip-rate check, call `session-retrospective-skip-rate` once and return its result verbatim. The tool reports how many of the last N sessions for this account closed without firing the retrospective. Admin uses the rate to inform the operator that closing via Sidebar Archive or tab-close defers the typed-edge pass to the next `/end`. Pass the `windowSize` admin provides; default 10 is fine when absent.
+
+## External-archive ingestion
+
+When admin's brief names a Notion workspace export — a directory with `Page Title <32-hex>.md` files and paired `<DB Name> <32-hex>.csv` / directory pairs at any depth, or a `Export-*.zip` path — load `platform/plugins/notion-import/skills/notion-import/SKILL.md` and follow it. The skill confirms the importing `:AdminUser` and the workspace label before any file is read, walks the export per its four references (workspace-export, databases, page-tree, attachments), and writes via your existing `memory-write` / `memory-update` / `memory-search` surface. Every node carries `source='notion'`, `importId`, and the standard provenance set. Unmapped Notion relations land as `:MENTIONS` with `mentionContext: '<relation-name>'`; never invent new edge types. Inline `@person` mentions resolve against `:Person {accountId}` only — account-isolation is load-bearing. Per-node writes today; a follow-up at [`.tasks/gbrain/ingestion/395-notion-bulk-archive-handler.md`](../../../../.tasks/gbrain/ingestion/395-notion-bulk-archive-handler.md) adds a batched `memory-archive-write` path.

package/payload/server/{adminuser-self-heal-QAWOZ3JV.js → adminuser-self-heal-YC47O34W.js}

@@ -1,4 +1,5 @@
-import "./chunk-JSBRDJBE.js";
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+import "./chunk-HYQNUVGO.js";
 
 // app/lib/adminuser-self-heal.ts
 var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/payload/server/{chunk-JSBRDJBE.js → chunk-HYQNUVGO.js}

@@ -1,10 +1,17 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function __require() {
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
 var __copyProps = (to, from, except, desc) => {
@@ -25,6 +32,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 export {
+  __require,
   __commonJS,
   __toESM
 };

package/payload/server/{chunk-HCYM5FLU.js → chunk-T3DJD5QR.js}

@@ -1,3 +1,5 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+
 // node_modules/hono/dist/compose.js
 var compose = (middleware, onError, onNotFound) => {
   return (context, next) => {
@@ -4099,7 +4101,7 @@ function getSession() {
   return getDriver().session();
 }
 async function runAdminUserSelfHeal(args) {
-  const { selfHealAdminUser } = await import("./adminuser-self-heal-QAWOZ3JV.js");
+  const { selfHealAdminUser } = await import("./adminuser-self-heal-YC47O34W.js");
   return selfHealAdminUser({ driver: getDriver(), ...args });
 }
 process.on("SIGINT", async () => {

package/payload/server/maxy-edge.js

@@ -1,3 +1,4 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   Hono,
   LOG_DIR,
@@ -13,8 +14,8 @@ import {
   sanitizeClientCorrId,
   vncLog,
   websockifyLog
-} from "./chunk-HCYM5FLU.js";
-import "./chunk-JSBRDJBE.js";
+} from "./chunk-T3DJD5QR.js";
+import "./chunk-HYQNUVGO.js";
 
 // server/edge.ts
 import { createServer, request as httpRequest } from "http";