@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,267 @@
+---
+name: document-ingest
+description: Universal document ingestion — maps any unstructured document (PDF, text, transcript, web page) OR chat archive (WhatsApp `_chat.txt`) to ontologically-grounded graph nodes via Haiku-driven classification. Triggers when the operator uploads or fetches a document or chat export for ingestion. One skill for every input shape — no per-doctype, no per-channel branching.
+---
+
+# Document Ingest
+
+Ingests any unstructured input — documents (PDF, text, transcript, web page) and chat archives (WhatsApp `_chat.txt`) — into the graph. Every classified section becomes one `:Section` node. **Two parent shapes, one pipeline:**
+
+| Input shape | Parent label | Section secondary label | Identity property | mode |
+|---|---|---|---|---|
+| PDF / text / web (default) | `:KnowledgeDocument` | `:Section:<Kind>` from closed enumeration (`Position`, `Chapter`, `Parties`, …) | `attachmentId` | `document` |
+| Chat archive (`_chat.txt`) | `:ConversationArchive` | `:Section:Conversation` | `conversationIdentity` | `chat` |
+
+The classifier in `memory-classify` decides which section kinds each section maps to (document mode) or chunks the archive into topic-bounded `:Section:Conversation` nodes (chat mode). The skill orchestrates the pipeline; the classifier reads the loaded ontology; the writer enforces the validator. **Classifier failure is terminal — the ingest aborts entirely; nothing is written. Loud failures, never silent landfill.**
+
+## Routing — chat vs document (mandatory first decision)
+
+Before anchor confirmation, decide the parent shape from the input:
+
+- **Chat archive** — input filename ends in `_chat.txt`, the dispatch brief names the input as a WhatsApp chat / messaging-channel export, or the operator labels it as such. Set `mode='chat'` and `parentLabel='ConversationArchive'`. Skip anchor confirmation; run participant confirmation instead (see § Participant confirmation). The classifier produces `:Section:Conversation` chunks; no anchor edges, no related entities.
+- **Document** — everything else. Set `mode='document'` and `parentLabel='KnowledgeDocument'` (or omit — these are the defaults). Run the anchor confirmation flow below.
+
+Both branches go through the same three tools (`memory-ingest-extract` → `memory-classify` → `memory-ingest`); only the parameters differ.
+
+## Anchor confirmation (mandatory first step)
+
+Every document has a subject — the node every identity-kind section attaches to. Anchors are parameter input, never inferred from "who uploaded the file". The dispatch brief from the admin agent names the anchor explicitly. If the brief is ambiguous, ask the operator before any read.
+
+The four common shapes:
+
+| Document | Anchor | Anchor label |
+|---|---|---|
+| Owner CV / personal-profile content | `:UserProfile` (or `:Person {role: 'admin-personal'}`) | `UserProfile` (or `Person`) |
+| Business pricing guide / policy / brochure | `:LocalBusiness` for this account | `LocalBusiness` |
+| Contract or document about a third party | `:Person` or `:Organization` (named in brief) | `Person` or `Organization` |
+| Reference document with no natural subject (industry overview, generic FAQ) | `:LocalBusiness` (default) | `LocalBusiness` |
+
+The confirmation flow:
+
+1. Read the dispatch brief. Extract the document path and the named subject.
+2. If the subject is not named, or is ambiguous, ask the operator in one sentence: "I'm about to ingest `<filename>`. Anchor it to the account owner's UserProfile, the business (`<LocalBusiness.name>`), or a third party — which?". Wait for the answer.
+3. Run a one-shot graph read to resolve the anchor's element ID. For UserProfile: `MATCH (u:UserProfile {accountId: $accountId}) RETURN elementId(u) AS anchorId, 'UserProfile' AS anchorLabel`. For LocalBusiness: `MATCH (b:LocalBusiness {accountId: $accountId}) RETURN elementId(b) AS anchorId, 'LocalBusiness' AS anchorLabel`. For a third party: search by name via `memory-search` and pick the matching node.
+4. Persist `$anchorNodeId` and `$anchorLabel` for the rest of the run. These flow into both `memory-classify` (as part of the `anchorDescription`) and `memory-ingest` (as the `anchorNodeId` + `anchorLabel` parameters).
+
+## Participant confirmation (chat mode only)
+
+Chat archives are multi-party — no single subject anchor. Instead, every distinct sender name in the archive must resolve to an existing `:AdminUser` or `:Person` elementId before any classify or ingest call. No auto-creation; missing participants are blockers, not silent skips.
+
+The confirmation flow:
+
+1. Read the dispatch brief. Extract the archive path and any operator-stated participant identities.
+2. Read a small sample of the archive (head ~50 lines) via the `Read` tool to discover the distinct sender names that appear at line starts after the bracketed-timestamp prefix.
+3. For every distinct senderName, search the graph via `memory-search` (or a one-shot `MATCH (n) WHERE (n:Person OR n:AdminUser) AND n.accountId = $accountId AND (n.name = $name OR (n.givenName + ' ' + n.familyName) = $name) RETURN elementId(n)`).
+4. **Resolved fully** — every senderName mapped to exactly one elementId. Capture the owner's elementId (the operator who exported the archive — usually the `:AdminUser` for this account; ask if ambiguous) and the comma-separated list of remaining participant elementIds.
+5. **Unresolved** — at least one senderName has no matching node. Surface to the operator: *"Archive `<filename>` mentions sender `<name>` but no `:Person` / `:AdminUser` matches. Create the contact first or correct the name, then re-dispatch."* Do NOT proceed.
+6. **Ambiguous** — a senderName matches multiple nodes. Ask the operator which one. Do NOT proceed until disambiguated.
+
+Persist `$ownerElementId` and `$participantElementIds` (array, owner excluded) for the run. These flow into `memory-ingest` as the `participantElementIds` parameter (owner + others, deduped).
+
+Compute archive metadata before classify:
+- `archiveSha256` — `bash sha256sum "<file>" | cut -d' ' -f1`. Stamped on the parent + every chunk.
+- `archiveSourceFile` — the basename (e.g. `_chat.txt`).
+- `conversationIdentity` — pass as the `attachmentId` parameter to `memory-ingest`. Format: `chat:<sha256(accountId + ":" + sortedParticipantElementIds)>` where `sortedParticipantElementIds` is the sorted-then-comma-joined list of `[owner, ...participants]`. Same conversation across re-exports → same identity → idempotent MERGE on the `:ConversationArchive`.
+
+## Pipeline
+
+Four steps in order. Steps 1–3 are deterministic tool calls (the agent does not classify; the agent calls the classifier tool). Step 4 is agent-driven graph writes against the existing graph, gated by the dispatch brief's named entity list. Hallucination defence and ontology validation stay server-side in `memory-classify` and the `memory-write` validator.
+
+```
+EXTRACT  --> CLASSIFY  --> INGEST  --> WIRE-BRIEF-ENTITIES
+   │            │             │              │
+   v            v             v              v
+ text        sections      one :Section    KD-level edges from
+ cached      + KD-level    per semantic   the new KnowledgeDocument
+ by id       edges         boundary +     to each entity the
+             + orphans     NEXT chain +   dispatch brief named
+                           anchor edges   (Person / Organization /
+                           + related      Service / Task / Event /
+                           entities +     KnowledgeDocument /
+                           classifier-    BrandingData) — plus an
+                           emitted KD-    orphan list for brief-
+                           level edges    named entities not found
+                           (PARTY /       in the graph.
+                           PARTICIPANT /
+                           FROM/TO/CC /
+                           SPEAKER)
+```
+
+### 1. `memory-ingest-extract`
+
+Pulls text from the file and caches it under the `attachmentId`. Inputs: `storagePath`, `filename`, `mimeType`, `attachmentId` (all from the attachment metadata block in your brief). Returns metadata + a 240-char preview. The full text lives in the in-process cache.
+
+After extract returns, look at the document's char count and emit a one-line size→latency estimate in chat **before** calling `memory-classify`, so the operator knows whether to expect a 10s turnaround or a 90–180s wait. The `memory-classify` server enforces a 180s ceiling on the Haiku call — anything above the >20K band may push toward that ceiling and time out loudly.
+
+| chars | estimate |
+|---|---|
+| <5K | ~10s |
+| 5K–10K | ~20s |
+| 10K–20K | ~45–90s |
+| 20K–525K | ~90–180s (single-shot) |
+| >525K | chunked: ~90–180s × ⌈chars / 525K⌉ |
+
+For inputs >525K chars memory-classify enters the chunked path automatically: deterministic 525K-char chunks with 17.5K-char overlap, one Haiku call per chunk, server-side merge of same-kind boundary straddlers. Inputs >682K chars in chat mode loud-fail with `cause:"input-too-large"` — the chat path must keep sessions under the per-call ceiling via sessionize.
+
+Form: "Classifying `<filename>` (`<N>` chars) — expect ~`<estimate>`."
+
+### 2. `memory-classify`
+
+Calls Haiku with the loaded ontology and the cached text.
+
+**Document mode (default).** Inputs: `attachmentId` (same one), `anchorDescription` (a short sentence built from the confirmed anchor — e.g. `"subject = UserProfile (the account owner); edges from UserProfile."` or `"subject = LocalBusiness {name: 'Acme Roofing'} (the operator's business); edges from LocalBusiness."`).
+
+**Chat mode.** Inputs: `attachmentId` (same one), `mode='chat'`, `anchorDescription` (a short sentence naming the conversation — e.g. `"WhatsApp conversation between Joel and Adam (2 participants)"`). The chat prompt drops the natural-edge map, the closed enumeration, and the orphan logic — Haiku produces topic-bounded `:Section:Conversation` chunks with `summary`, `keywords`, `firstMessageAt`, `lastMessageAt`, `participantNames`, `messageCount` per chunk. The whole archive may produce one chunk (short conversation) or many (long chat with topic transitions); chunks cover every message in chronological order with no gaps.
+
+Returns:
+
+- `documentSummary` — 1-3 sentences for the KnowledgeDocument node
+- `documentKeywords` — 3-10 lowercase topic keywords
+- `sections` — section-shaped output, each with `kind` (from the closed enumeration), `title`, `body` (server-reconstructed via `documentText.slice(sourceStart, sourceEnd)` — the LLM emits offsets, not body text), `summary` (≤500 chars, server-validated), `sourceStart`/`sourceEnd` (whole-document char offsets — translated by the chunked-classify path so the writer always sees whole-doc coordinates), `properties`, `anchorEdge` (or null), optional `related`, optional `classifierReason` (when `kind === "Other"`)
+- `documentEdges` — optional. Document-level edges off the KnowledgeDocument, picked by document shape: `PARTY` for contract parties (Person/Organization); `PARTICIPANT` for meeting/call attendees (Person/Organization); `FROM`/`TO`/`CC` for email header parties (Person, plus Organization for `TO`/`CC`); `SPEAKER` for voice-note/single-speaker transcript speakers (Person). Anchor stays the document subject from step 1; these edges are additional document→party links the writer applies off the KnowledgeDocument, not off any Section
+- `orphanCandidates` — nodes the classifier wanted to emit but could not natural-edge. Surfaced loudly to the operator (see Output contract below)
+- `hallucinatedRelated` — diagnostic count of related-kind values dropped server-side as ontology misses
+
+**Failure is terminal.** If the call returns `{kind: "fallback", reason}`, the LLM was unavailable, malformed, or otherwise unusable. **Do not call `memory-ingest`. Do not write anything.** Return to the dispatching agent immediately with a structured blocker: `Classifier unavailable — <reason>. Document not ingested. Operator must <remediation>.` The dispatching agent surfaces this to the operator in plain English. There is no "fallback-to-UNMAPPED-section" write path — that fallback was removed by design.
+
+After step 2 succeeds, emit a chat message before step 3 naming what the classifier produced: **"Classified into N sections, covering: <topic keywords>."** This is step 2 of the four-step narrative the operator sees per ingest.
+
+### 3. `memory-ingest`
+
+Writes the classified document or chat archive.
+
+**Document mode (default).** Inputs: `attachmentId`, `documentSummary`, `anchorNodeId`, `anchorLabel`, `sections`, `documentEdges` (pass through if present), `orphanCandidates` (pass through if present), `scope` (from the brief — confirm with the operator if absent), optional `documentKeywords`, `userKeywords`, `sourceUrl`, `sourceType`.
+
+**Chat mode.** Inputs: `attachmentId` (set to `conversationIdentity`), `parentLabel='ConversationArchive'`, `documentSummary`, `sections` (the chunks from chat-mode classify), `scope`, plus the chat-archive metadata: `archiveSha256` (cleanup discriminator), `archiveSourceFile` (audit), `participantElementIds` (owner + others, for `:PARTICIPANT_IN` edges). Pass `anchorNodeId` and `anchorLabel` as any non-empty placeholder (e.g. the owner's elementId + `'AdminUser'`) — they are unused on the chat path but the parameter is non-optional. The writer MERGEs `:ConversationArchive { conversationIdentity }`, drops any chunks stamped with this `archiveSha256` (idempotent re-ingest), CREATEs new chunks chained by `:NEXT`, and MERGEs `:PARTICIPANT_IN` edges from each participant.
+
+Returns:
+
+- `documentNodeId`, `sectionCount`
+- `kindBreakdown` — per-kind count, e.g. `{"Position": 4, "Chapter": 12, "Other": 1}`
+- `edgeBreakdown` — per-edge-type count, e.g. `{"HAS_SECTION": 17, "NEXT": 16, "HAS_POSITION": 4, "ATTENDED": 1, "AT": 4}`
+- `relatedCount` — Organizations/Persons/DefinedTerms created or merged
+- `standaloneCount` — `:Project` nodes created
+- `orphanCandidates` — passed through from the classifier so the agent can surface them in the post-write narrative
+- `documentSummary`, `keywords`
+
+After step 3 succeeds, emit the third chat message naming everything the writer created or connected (see "Four-step operator narrative" below). Continue to step 4 (`wire-brief-entities`) before the final fourth chat message.
+
+Re-ingesting the same `attachmentId` is safe — the writer drops prior `:Section` children (any secondary label), prior `:Project` standalone nodes, and prior KD-level edges (every edge stamped `sourceDocumentId=<this attachmentId>` plus the legacy `PARTY` edge type by name — covers classifier-emitted PARTICIPANT/FROM/TO/CC/SPEAKER and agent-emitted brief-wired edges) before re-creating. Shared related entities (Organizations, Persons MERGEd by identifying property) are spared.
+
+### 4. `wire-brief-entities`
+
+**Skipped in chat mode** — `:ConversationArchive` does not carry KD-level brief-wired edges; participants are already attached via `:PARTICIPANT_IN` and message bodies stay verbatim inside chunk text (mention extraction is deferred to a separate insight-derivation task). Document mode only.
+
+After `memory-ingest` returns the new KnowledgeDocument's `documentNodeId`, this step iterates the entities the dispatch brief named and connects each to the new document with the natural KD-level edge.
+
+**Entity sources.** The dispatch brief's "key entities to connect" list. Brief shape: prose names of Persons, Organizations, Services, Tasks, Events, KnowledgeDocuments, BrandingData that the document describes or references. Example: *"Person nodes for Joel Smalley, Adam Mackay, Dan McLeod; LocalBusiness / Organization nodes for Real Agent / Real Agency; Any existing Task nodes related to Real Agent Lettings."* Extract every named entity from the brief before any `memory-write`.
+
+**Resolution.** For each named entity:
+1. Resolve the elementId via `memory-search` (preferred — handles fuzzy name matching against existing graph nodes) or a single-shot `MATCH (n:<Label> { <identifying-prop>: $value, accountId: $accountId }) RETURN elementId(n)` via `mcp__graph__maxy-graph-read_neo4j_cypher` for exact-match lookups.
+2. If the entity resolves to exactly one node, write the edge from KD to that node (see edge-type table below).
+3. If the entity resolves to zero nodes, append it to the orphan list (do NOT create a placeholder Person/Organization — that's classifier-emitted `documentEdges` territory, not brief-wiring).
+4. If the entity resolves to multiple nodes (ambiguity — two Persons named "Joel"), pick the one whose context best fits the brief and document (e.g. last-mentioned-recently, or matching account). Surface the choice in the operator narrative so it can be corrected.
+
+**Edge-type table.** Edge depends on entity kind and document shape:
+
+| Entity kind | Document shape | Edge | Direction |
+|---|---|---|---|
+| Person | meeting / call (notes or transcript) | `PARTICIPANT` | KD → Person |
+| Person | email | `FROM` (sender) / `TO` (direct recipient) / `CC` (carbon copy) | KD → Person |
+| Person | voice-note / single-speaker transcript | `SPEAKER` | KD → Person |
+| Person | contract / agreement | `PARTY` | KD → Person |
+| Person | other (report, brief, generic notes) | `MENTIONS` | KD → Person |
+| Organization | meeting / call | `PARTICIPANT` | KD → Organization |
+| Organization | email | `TO` / `CC` | KD → Organization |
+| Organization | contract | `PARTY` | KD → Organization |
+| Organization | other | `MENTIONS` | KD → Organization |
+| Task | any | `REFERENCES` | KD → Task |
+| Event | any | `REFERENCES` | KD → Event |
+| Service | any | `REFERENCES` | KD → Service |
+| KnowledgeDocument (cross-link) | any | `REFERENCES` | KD → KnowledgeDocument |
+| BrandingData | any | `REFERENCES` | KD → BrandingData |
+
+When the classifier already emitted a `documentEdges` entry for the same (KD, target) pair (because the document body itself names the party — common for emails and contracts), the brief-wiring step is redundant for that party — `memory-search` for `elementId(n)` will find the just-written party and the second `memory-write` would create a duplicate edge. Skip the brief entry whose target was already wired by the classifier.
+
+**Provenance discipline.** Every brief-wired edge carries `sourceDocumentId=<attachmentId>` and `createdByAgent='document-ingest'` in its edge properties. The `memory-ingest` writer's re-ingest cleanup matches edges by `sourceDocumentId`, so a re-ingest of the same `attachmentId` drops them deterministically — without these stamps, brief-wired edges would accumulate on every re-ingest. This is load-bearing: forgetting the stamp leaks edges silently. Pass them on every `memory-write` `relationships` entry's properties block.
+
+**Operator narrative line.** Emit one chat line after the loop completes:
+
+```
+[document-ingest] wire-brief-entities resolved=<N> orphans=<M> edges=<K> — Persons via PARTICIPANT/FROM/TO/CC/SPEAKER/PARTY/MENTIONS, Organizations via PARTICIPANT/TO/CC/PARTY/MENTIONS, Tasks via REFERENCES, Events via REFERENCES, Services via REFERENCES. Not found in graph: <comma-separated brief names>.
+```
+
+The leading `[document-ingest] wire-brief-entities` token is grep-able from the agent's stream log so `edges=0` while the brief listed entities is the regression metric.
+
+If the brief lists no entities (single-author personal CV, generic FAQ, etc.), this step is a no-op: emit `[document-ingest] wire-brief-entities resolved=0 orphans=0 edges=0` and continue. The four-step narrative reverts to three lines for downstream chat (no fourth narrative line is emitted when this step does nothing).
+
+## Four-step operator narrative
+
+Each ingest produces up to four chat messages, each at the moment it happens. Failures replace the relevant step's message with a blocker. Step 4 collapses to nothing visible when the brief named no entities (the agent still emits the `[document-ingest] wire-brief-entities resolved=0 orphans=0 edges=0` log line for grep-ability, but no fourth chat message).
+
+| Step | Emitted by | Trigger | Content |
+|---|---|---|---|
+| 1 | Admin agent | On dispatch to database-operator | "Sending `<filename>` to database-operator for ingest." |
+| 2 | Database-operator (this skill) | After `memory-classify` returns ok | "Classified `<filename>` into `<N>` sections, covering: `<topicKeyword1>, <topicKeyword2>, …`." |
+| 3 | Database-operator (this skill) | After `memory-ingest` returns | "Created/connected: `<kind: count via edgeType to anchor>` for each kind; `<orphan-candidates: label and reason>` for any orphans; `<related entities created or merged: kind: count>`." |
+| 4 | Database-operator (this skill) | After `wire-brief-entities` step completes AND the brief named at least one entity | "Wired `<N>` brief entities: `<K>` Persons via `<edge>`, `<M>` Organizations via `<edge>`, `<T>` Tasks via `REFERENCES`. `<P>` entities not found in graph: `<comma-separated names>`." |
+
+**Step 2 failure form:** "Classifier unavailable — `<reason>`. `<filename>` not ingested. `<remediation>`." Do not call step 3.
+
+**Step 3 failure form:** "`<n>` sections classified but write failed at `<stage>` — `<reason>`. `<filename>` not in graph." Do not call step 4.
+
+**Step 4 partial form:** "Wired `<N>` brief entities; `<P>` not found: `<list>`." If every brief-named entity resolved, drop the "not found" clause. If zero brief entities were named, suppress the chat message entirely (the log line still fires).
+
+The operator always sees what was attempted and where it stopped.
+
+## Web-page ingestion
+
+For URL-based ingestion, run `memory-ingest-web` first with the URL and the WebFetch result. It writes the content to a temp file and routes through `memory-ingest-extract`, returning a fresh `attachmentId`. The rest of the pipeline (classify + ingest) is identical to a file upload. Pass `sourceUrl` and `sourceType: 'web'` to `memory-ingest`.
+
+## Attachment metadata format
+
+Your task description contains attachment metadata in this format:
+
+```
+1. report.pdf  application/pdf  1,234,567 bytes
+   ID: 04caba6b-...  Path: /home/admin/.maxy/data/uploads/...
+```
+
+Extract:
+- **filename** = the text BEFORE the MIME type on the FIRST line. Always the human-readable name; never a UUID.
+- **mimeType** = the MIME type on the first line.
+- **attachmentId** = the UUID after `ID:` on the SECOND line.
+- **storagePath** = the absolute path after `Path:` on the second line.
+
+Process each text-based attachment (PDF, plain text, markdown). Skip images — they have no text to ingest.
+
+## Visibility scope
+
+`memory-ingest` requires `scope`. The brief specifies it; if not, ask the operator before ingesting.
+
+- **public** — visible to public agents and admin. For business knowledge customers should access (products, services, FAQs, policies).
+- **shared** — visible to all account agents but not public visitors. Internal operational knowledge.
+- **admin** — admin agent only. Sensitive content (contracts, credentials, internal processes).
+
+CV / personal-profile content defaults to `admin`. Pricing guides, services, FAQs default to `public`. When uncertain, ask in one sentence.
+
+## Discipline (load-bearing)
+
+1. **Anchor confirmed first.** No extract / classify / ingest until `$anchorNodeId` and `$anchorLabel` are persisted and echo-confirmed.
+2. **Generic skill — no document-type branching.** The classifier maps sections to the closed enumeration. The writer applies the classifier's edges; never invents its own.
+3. **Schema-base property names.** The classifier emits `givenName` / `familyName` / `telephone` / `dateSent` — not `firstName` / `phone` / `sentAt`. The `memory-write` validator enforces this via the synonym map.
+4. **Closed enumeration of section kinds.** Identity, structural, contract-clause, plus standalone `Project` and label-fallback `Other`. The classifier never invents a new kind. `Other` collapses unrecognised content with a `classifierReason`; the operator runs `MATCH (s:Section:Other) WHERE s.accountId = $acc RETURN s.title, s.classifierReason, count(*) AS occurrences ORDER BY occurrences DESC` to surface ontology-growth candidates.
+5. **Provenance stamp.** Every section, standalone, and edge gets `createdByAgent='document-ingest'`, `createdBySession=<sessionId>`, `source='document'`, `sourceDocumentId=<attachmentId>`. Stamped automatically by `memory-ingest` for everything it writes; **also stamped by every `memory-write` call in step 4** (`wire-brief-entities`) on the edge properties — without these stamps, brief-wired edges leak on re-ingest.
+6. **Idempotent re-ingest.** `memory-ingest` is safe to re-run with the same `attachmentId`. Prior `:Section` children (any secondary label) and `:Project` standalones are deleted; prior KD-level edges are deleted by **provenance match** — every edge stamped `sourceDocumentId=<this attachmentId>` is dropped, regardless of edge type. The legacy `PARTY` edge type is also matched by name as a belt-and-braces for pre-stamping data. Any KD-level edge that this pipeline writes (classifier-emitted PARTY/PARTICIPANT/FROM/TO/CC/SPEAKER and agent-emitted brief-wired MENTIONS/REFERENCES/etc.) MUST carry the stamp — without it, the edge persists across re-ingests as a duplicate. MERGEd shared entities (Organizations, Persons referenced by other docs) are spared.
+7. **Loud failure, never silent landfill.** Classifier failure aborts the ingest; nothing is written. Edge orphans are surfaced via `orphanCandidates`; the writer never synthesises edges to "fix" them.
+8. **Brief is a deliverable, not a hint.** Step 4 is mandatory whenever the dispatch brief named entities. Returning *"document ingested as a KnowledgeDocument anchored to <X>"* without listing wired/unresolved brief entities is a silent failure — the document becomes an island anchored to one node while the named Persons/Organizations/Tasks stay disconnected, defeating adjacency-ranked `memory-search`. The `[document-ingest] wire-brief-entities` log line is the verification surface; `edges=0` while the brief listed entities is a regression.
+
+## Output contract
+
+Return to the admin agent:
+- **What you did** — filename, anchor (`UserProfile` / `LocalBusiness` / etc.), scope.
+- **Outcome** — `documentNodeId`, `sectionCount`, `kindBreakdown`, `edgeBreakdown`, `relatedCount`, `standaloneCount`. Surface the document summary and extracted keywords so the admin can echo them back to the operator.
+- **Brief-entity wiring** — list of brief-named entities resolved (with elementId + edge type written) and not-found (orphans). Empty when the brief named no entities. Never elide; absence is silently broken adjacency.
+- **Orphan candidates** — for each entry the classifier flagged: kind, label, reason. The admin agent reads these to decide whether the orphan is intentional (rare, valid) or a classifier miss (bug). Never silently skip.
+- **Ontology gaps** — list any `:Section:Other` titles + classifierReasons. The admin agent reads these to decide whether to extend the ontology in a follow-up task.
+- **Blockers** — anchor unconfirmed, classifier failure (Haiku unavailable, malformed JSON, etc.), schema validator rejection, write failure mid-ingest.

package/payload/platform/plugins/outlook/PLUGIN.md

@@ -0,0 +1,48 @@
+---
+name: outlook
+description: Microsoft 365 / Outlook.com via Microsoft Graph (read-only first cut). Per-account OAuth Auth Code + PKCE; no client secret. Tools — outlook-account-register: PKCE register; outlook-mail-list / outlook-mail-search: inbox; outlook-calendar-list / outlook-calendar-event: calendar; outlook-contacts-list: contacts; outlook-mailbox-info: auth state + folder count.
+tools:
+  - outlook-account-register
+  - outlook-mail-list
+  - outlook-mail-search
+  - outlook-calendar-list
+  - outlook-calendar-event
+  - outlook-contacts-list
+  - outlook-mailbox-info
+always: false
+embed: ["admin"]
+metadata: {"platform":{"optional":true}}
+---
+
+# Outlook
+
+Read-only Microsoft Graph access for Outlook.com / Microsoft 365 mailboxes. Admin agent only — public agent surface is explicitly excluded.
+
+## Capabilities
+
+- **Register:** `outlook-account-register` — initiates OAuth Auth Code + PKCE flow against the operator's Entra app. Returns an authorization URL the operator opens in the VNC browser to consent. Tokens persist per-account, encrypted on disk (AES-256-CBC).
+- **Mail (read-only):** `outlook-mail-list` returns recent messages; `outlook-mail-search` runs a Graph `$search` query.
+- **Calendar (read-only):** `outlook-calendar-list` returns events in a future range; `outlook-calendar-event` returns a single event with full body + attendees.
+- **Contacts (read-only):** `outlook-contacts-list` returns contacts.
+- **Health:** `outlook-mailbox-info` reports auth state, refresh-window status, and top-level folder count. Use this to answer "did account X auth?" without grepping logs.
+
+## Out of scope
+
+- Send / draft / move / flag — write surfaces are deferred to a follow-up task.
+- OneDrive, Files, Sites — separate plugin; different endpoints.
+- Push notifications via `/subscriptions` — first cut polls.
+- On-premises Exchange — Microsoft Graph deprecated hybrid REST 2023-07. The plugin detects on-prem mailboxes and routes the operator to the IMAP path (`email` plugin).
+- M365 admin scopes (`User.Read.All`, `AuditLog.Read.All`) — separate plugin.
+
+## References
+
+| Reference | Topics |
+|-----------|--------|
+| [auth.md](references/auth.md) | Entra app registration, PKCE flow, vendored upstream SHA, re-vendor procedure |
+| [graph-surfaces.md](references/graph-surfaces.md) | Graph endpoint and response shape per tool |
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| [outlook](skills/outlook/SKILL.md) | When to activate; how to register a new Outlook account |

package/payload/platform/plugins/outlook/mcp/dist/__tests__/graph-client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=graph-client.test.d.ts.map

package/payload/platform/plugins/outlook/mcp/dist/__tests__/graph-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/graph-client.test.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/outlook/mcp/dist/__tests__/graph-client.test.js

@@ -0,0 +1,94 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { classifyGraphError } from "../lib/graph-client.js";
+test("classifyGraphError 401 → auth", () => {
+    const cls = classifyGraphError({
+        statusCode: 401,
+        code: "InvalidAuthenticationToken",
+        body: '{"error":{"code":"InvalidAuthenticationToken"}}',
+    });
+    assert.equal(cls.kind, "auth");
+    assert.equal(cls.statusCode, 401);
+});
+test("classifyGraphError 429 with Retry-After → rate-limit-recoverable", () => {
+    const cls = classifyGraphError({
+        statusCode: 429,
+        headers: { "Retry-After": "30" },
+    });
+    assert.equal(cls.kind, "rate-limit-recoverable");
+    if (cls.kind === "rate-limit-recoverable") {
+        assert.equal(cls.retryAfterMs, 30000);
+    }
+});
+test("classifyGraphError 429 lowercase Retry-After header still parsed", () => {
+    const cls = classifyGraphError({
+        statusCode: 429,
+        headers: { "retry-after": "5" },
+    });
+    assert.equal(cls.kind, "rate-limit-recoverable");
+    if (cls.kind === "rate-limit-recoverable") {
+        assert.equal(cls.retryAfterMs, 5000);
+    }
+});
+test("classifyGraphError 429 without Retry-After → rate-limit-terminal", () => {
+    const cls = classifyGraphError({
+        statusCode: 429,
+        headers: {},
+    });
+    assert.equal(cls.kind, "rate-limit-terminal");
+});
+test("classifyGraphError 503 + MailboxNotEnabledForRESTAPI → on-prem", () => {
+    const cls = classifyGraphError({
+        statusCode: 503,
+        code: "MailboxNotEnabledForRESTAPI",
+        body: '{"error":{"code":"MailboxNotEnabledForRESTAPI","message":"REST API is not yet supported for this mailbox."}}',
+        headers: { "x-mailbox-server": "ex2019.acme.local" },
+    });
+    assert.equal(cls.kind, "on-prem");
+    if (cls.kind === "on-prem") {
+        assert.equal(cls.statusCode, 503);
+        assert.equal(cls.mailServer, "ex2019.acme.local");
+    }
+});
+test("classifyGraphError 503 without MailboxNotEnabledForRESTAPI → 5xx (NOT on-prem)", () => {
+    // Critical: on-prem detection keys off the structured code field, not body
+    // prose. A generic 503 must NOT be misclassified as on-prem.
+    const cls = classifyGraphError({
+        statusCode: 503,
+        code: "ServiceUnavailable",
+        body: '{"error":{"code":"ServiceUnavailable","message":"REST API on-premises mailboxes are temporarily unavailable for everyone, somehow"}}',
+    });
+    assert.equal(cls.kind, "5xx", "must not infer on-prem from prose body");
+});
+test("classifyGraphError parses code from body when not on top-level", () => {
+    const cls = classifyGraphError({
+        statusCode: 503,
+        body: '{"error":{"code":"MailboxNotEnabledForRESTAPI","message":"foo"}}',
+    });
+    assert.equal(cls.kind, "on-prem");
+});
+test("classifyGraphError 500 → 5xx", () => {
+    const cls = classifyGraphError({ statusCode: 500, code: "InternalServerError" });
+    assert.equal(cls.kind, "5xx");
+});
+test("classifyGraphError 404 → other", () => {
+    const cls = classifyGraphError({ statusCode: 404, code: "ItemNotFound" });
+    assert.equal(cls.kind, "other");
+    if (cls.kind === "other") {
+        assert.equal(cls.statusCode, 404);
+        assert.equal(cls.code, "ItemNotFound");
+    }
+});
+test("classifyGraphError reads Retry-After via fetch-style response.headers.get", () => {
+    const cls = classifyGraphError({
+        statusCode: 429,
+        response: {
+            headers: { get: (h) => (h.toLowerCase() === "retry-after" ? "10" : null) },
+        },
+    });
+    assert.equal(cls.kind, "rate-limit-recoverable");
+    if (cls.kind === "rate-limit-recoverable") {
+        assert.equal(cls.retryAfterMs, 10000);
+    }
+});
+//# sourceMappingURL=graph-client.test.js.map

package/payload/platform/plugins/outlook/mcp/dist/__tests__/graph-client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-client.test.js","sourceRoot":"","sources":["../../src/__tests__/graph-client.test.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/outlook/mcp/dist/__tests__/log.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=log.test.d.ts.map

package/payload/platform/plugins/outlook/mcp/dist/__tests__/log.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/log.test.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/outlook/mcp/dist/__tests__/log.test.js

@@ -0,0 +1,31 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { redact, trunc } from "../lib/log.js";
+test("redact masks Bearer tokens", () => {
+    const input = "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.payload.signature";
+    assert.match(redact(input), /Bearer <REDACTED>/);
+    assert.doesNotMatch(redact(input), /eyJhbGciOiJIUzI1NiJ9/);
+});
+test("redact masks access_token query strings", () => {
+    const input = "https://login.microsoftonline.com/cb?access_token=abc123_secret&state=xyz";
+    const out = redact(input);
+    assert.match(out, /access_token=<REDACTED>/);
+    assert.doesNotMatch(out, /abc123_secret/);
+    // Other query params survive.
+    assert.match(out, /state=xyz/);
+});
+test("redact is a no-op on safe text", () => {
+    assert.equal(redact("user logged in account=abc count=5"), "user logged in account=abc count=5");
+});
+test("redact handles multiple Bearer tokens in one string", () => {
+    const input = "first Bearer aaaaa second Bearer bbbbb";
+    const out = redact(input);
+    assert.match(out, /first Bearer <REDACTED> second Bearer <REDACTED>/);
+});
+test("trunc preserves short values verbatim", () => {
+    assert.equal(trunc("short", 10), "short");
+});
+test("trunc shortens long values with ellipsis", () => {
+    assert.equal(trunc("abcdefghijklmnop", 10), "abcdefghi…");
+});
+//# sourceMappingURL=log.test.js.map

package/payload/platform/plugins/outlook/mcp/dist/__tests__/log.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.test.js","sourceRoot":"","sources":["../../src/__tests__/log.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE9C,IAAI,CAAC,4BAA4B,EAAE,GAAG,EAAE;IACtC,MAAM,KAAK,GAAG,8DAA8D,CAAC;IAC7E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC;IACjD,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC,CAAC;AAC7D,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,yCAAyC,EAAE,GAAG,EAAE;IACnD,MAAM,KAAK,GAAG,2EAA2E,CAAC;IAC1F,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;IAC7C,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAC1C,8BAA8B;IAC9B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;AACjC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,gCAAgC,EAAE,GAAG,EAAE;IAC1C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,oCAAoC,CAAC,EAAE,oCAAoC,CAAC,CAAC;AACnG,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;IAC/D,MAAM,KAAK,GAAG,wCAAwC,CAAC;IACvD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,kDAAkD,CAAC,CAAC;AACxE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,uCAAuC,EAAE,GAAG,EAAE;IACjD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,0CAA0C,EAAE,GAAG,EAAE;IACpD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,kBAAkB,EAAE,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;AAC5D,CAAC,CAAC,CAAC"}

package/payload/platform/plugins/outlook/mcp/dist/__tests__/pkce-flow.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pkce-flow.test.d.ts.map

package/payload/platform/plugins/outlook/mcp/dist/__tests__/pkce-flow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce-flow.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/pkce-flow.test.ts"],"names":[],"mappings":""}