@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/workflows/mcp/test-workflows.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Workflow MCP tool test suite.
+#
+# Exercises all 8 workflow tools via the MCP protocol to verify:
+#   - Creation: valid, missing plugin (draft), cycle detection, step limit
+#   - Type enforcement: "skill" and "subagent" rejected at schema level
+#   - Timeout validation: boundary checks (0, 120, 121, omitted)
+#   - Get / List / Update / Delete
+#   - Validation: re-validate draft workflows
+#   - Execution: draft/paused rejection
+#   - Run history queries
+#
+# Prerequisites: Neo4j running, Ollama running (for embeddings).
+# Uses the MCP SDK Client to communicate with the server — same protocol
+# path production uses.
+#
+# Usage: bash test-workflows.sh
+# Exit 0 = all tests pass, exit 1 = failure
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "=== Workflow Test Suite ==="
+echo ""
+
+# ── Check prerequisites ──────────────────────────────────────
+
+# Neo4j connectivity check
+echo -n "Checking Neo4j... "
+# NEO4J_URI is hard-required. No default — set explicitly before running tests.
+if [ -z "${NEO4J_URI:-}" ]; then
+  echo "Error: NEO4J_URI required (no default)" >&2
+  exit 1
+fi
+if ! nc -z "$(echo "$NEO4J_URI" | sed 's|.*://||;s|:.*||')" "$(echo "$NEO4J_URI" | sed 's|.*:||')" 2>/dev/null; then
+  echo "SKIP — Neo4j not reachable at $NEO4J_URI"
+  echo "Tests require Neo4j. Run on the Pi or start Neo4j locally."
+  exit 0
+fi
+echo "OK"
+
+# Ollama check (needed for embeddings at workflow creation time)
+OLLAMA_URL="${OLLAMA_URL:-http://localhost:11434}"
+echo -n "Checking Ollama... "
+if ! curl -sf "$OLLAMA_URL/api/tags" >/dev/null 2>&1; then
+  echo "SKIP — Ollama not reachable at $OLLAMA_URL"
+  echo "Tests require Ollama for embedding generation."
+  exit 0
+fi
+echo "OK"
+
+# Build check
+echo -n "Checking build... "
+if [ ! -f "$SCRIPT_DIR/dist/index.js" ]; then
+  echo "not built — building now..."
+  (cd "$SCRIPT_DIR" && npm run build 2>&1) || {
+    echo "Build failed"
+    exit 1
+  }
+  echo "  Build complete"
+else
+  echo "OK"
+fi
+
+# PLATFORM_ROOT must be set
+if [ -z "${PLATFORM_ROOT:-}" ]; then
+  # Derive from script location: mcp/ → workflows/ → plugins/ → platform/
+  export PLATFORM_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+  echo "PLATFORM_ROOT set to: $PLATFORM_ROOT"
+fi
+
+echo ""
+
+# ── Run tests ─────────────────────────────────────────────────
+
+node "$SCRIPT_DIR/test-runner.mjs"

package/payload/platform/plugins/workflows/skills/workflow-manager/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: workflow-manager
+description: "Create, test, and diagnose persistent workflows that automate recurring multi-step processes spanning different plugin tools. Use when the user describes a recurring multi-step process to automate."
+---
+
+# Workflow Manager
+
+Create, test, and diagnose persistent workflows that automate recurring multi-step processes.
+
+## When to Suggest a Workflow
+
+The user describes a recurring process with two or more steps that involve different plugin tools. Examples: "every time a new contact signs up, send them a welcome message and schedule a follow-up", "when I get a new lead, create a contact, log it, and send a Telegram notification".
+
+Do not suggest workflows for single-tool operations or one-off tasks.
+
+## Gathering Requirements
+
+Ask the user conversationally:
+
+1. **What triggers this workflow?** Manual execution, scheduled (cron via scheduling plugin), or conversational ("run the follow-up workflow").
+2. **What are the steps?** Each step is a single MCP tool call on a specific plugin. Identify the plugin name and tool name for each step.
+3. **How do steps connect?** Which steps depend on output from earlier steps? Identify the `outputKey` for steps that produce data and the `{{outputKey.field}}` template variables for steps that consume it.
+4. **What happens on failure?** For each step: abort the workflow, skip and continue, or retry (up to 3 times)?
+5. **Any slow steps?** Steps calling tools that may take longer than 30 seconds (knowledge ingestion, external API calls) need an explicit `timeout` value (max 120 seconds).
+
+## Presenting for Review
+
+Before creating, show the user the planned workflow structure:
+
+- Workflow name and description
+- Each step numbered, showing: label, plugin/tool, parameters (with template variables highlighted), failure policy, and timeout if non-default
+- Dependency chain (which steps must complete before which)
+- Template variable flow (where data passes between steps)
+
+Wait for the user's confirmation before calling `workflow-create`.
+
+## Creating a Workflow
+
+Use `workflow-create` with these parameters:
+- `name` — short descriptive name (e.g. "New lead follow-up")
+- `description` — what the workflow does, used for semantic discovery
+- `steps` — array of step objects, each with:
+  - `type`: `"tool"` (the only supported type)
+  - `plugin`: plugin name (e.g. `"contacts"`, `"telegram"`, `"scheduling"`)
+  - `tool`: tool name within the plugin (e.g. `"contact-create"`, `"message"`)
+  - `params`: parameter object — use `{{outputKey.field}}` for values from prior steps
+  - `label`: human-readable description
+  - `dependsOn`: array of position indexes (as strings) for steps that must complete first — e.g. `["0"]` means "after step 0"
+  - `onFailure`: `"abort"` (default), `"skip"`, or `"retry"`
+  - `retryLimit`: 1-3, only when onFailure is `"retry"`
+  - `outputKey`: name to store this step's output under
+  - `timeout`: execution timeout in seconds (1-120, default 30)
+
+If creation returns `status: "draft"`, tell the user which plugin capabilities are missing and that the workflow will activate automatically once those plugins are installed and built.
+
+## Testing a Workflow
+
+After creation, verify the workflow works:
+
+1. Use `workflow-execute` with a test `context` object containing sample values for any runtime variables the workflow expects.
+2. Check the result: `status`, `stepsCompleted`, `stepsSkipped`, `stepsFailed`.
+3. If any steps failed, use `workflow-runs` to get the detailed run history, then examine per-step results to identify which step failed and why.
+
+## Diagnosing Failures
+
+When the user reports a workflow isn't working:
+
+1. Use `workflow-get` with the `workflowId` to check the workflow's current status and step configuration.
+2. If status is `"draft"` — missing plugins. Use `workflow-validate` to see which capabilities are unavailable.
+3. If status is `"paused"` — the user or the system paused it. Use `workflow-update` with `status: "active"` to resume (this re-validates capabilities first).
+4. If status is `"active"` but execution fails — use `workflow-runs` to find recent runs, then examine per-step errors:
+   - Template variable errors: a step references `{{outputKey.field}}` but the prior step didn't produce that output key or field
+   - Tool errors: the underlying MCP tool returned an error (check the step result's error message)
+   - Timeout errors: the step exceeded its timeout — consider increasing the `timeout` field via `workflow-update`
+
+## Managing Existing Workflows
+
+- **List**: `workflow-list` — optionally filter by `status` (`"active"`, `"paused"`, `"draft"`)
+- **View details**: `workflow-get` with `workflowId`
+- **Edit**: `workflow-update` — can change `name`, `description`, `steps` (full replacement), or `status`
+- **Pause/resume**: `workflow-update` with `status: "paused"` or `status: "active"`
+- **Re-validate**: `workflow-validate` — checks if draft workflows can now activate after plugin changes
+- **Delete**: `workflow-delete` — cascades to all steps, runs, and step results. Confirm with the user first.
+- **Run history**: `workflow-runs` — optionally filter by `workflowId` or `status`
+
+## Schedule Integration
+
+To run a workflow on a schedule, create a scheduling event with action dispatch:
+- Plugin: `scheduling`
+- Tool: `schedule-event`
+- Action: `{ plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }`
+
+The `check-due-events` dispatcher (currently unwired — see `maxy-code-prd.md` §Scheduled tasks) is the surface that will fire the workflow at the scheduled time. The WorkflowRun captures `trigger: "schedule"` when the dispatcher fires.

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

@@ -0,0 +1,8 @@
+{
+  "name": "x-import",
+  "description": "Import an X (Twitter) archive 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/x-import/PLUGIN.md

@@ -0,0 +1,33 @@
+---
+name: x-import
+description: "Import an X (Twitter) archive 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":"x-import"}}
+---
+
+# X Import
+
+Ingests an X (formerly Twitter) Basic Data Export (extracted ZIP — a directory of `.js` shims plus media subdirectories) 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 bulk external-archive ingestion.
+
+## When this applies
+
+The admin agent delegates to `specialists:database-operator` when the operator drops an extracted X archive directory (or a `twitter-<handle>-archive.zip` reference) into chat. The specialist runs the skill's owner + participant confirmation flow before any `.js` shim is read, then dispatches the two existing ingestion surfaces:
+
+- **Tweet stream** → `document-ingest` produces one `:KnowledgeDocument` with `source='x'` whose body is the verbatim chronological transcript of the operator's own tweets, replies, and quote-tweet authorship. `:Section` chunking is owned by `memory-classify` (document mode).
+- **Direct messages** → `conversation-archive-ingest.sh --source x-dm` once per distinct `dmConversation`, producing one `:ConversationArchive` per participant set (keyed on `conversationIdentity`). Senders confirm to existing `:AdminUser` / `:Person` nodes — never auto-created.
+
+## What this plugin is not
+
+- **Not a new graph writer.** Every write routes through the existing `memory-ingest` surface — the document path keyed on `attachmentId` (tweet stream) writes `:KnowledgeDocument`, or the conversation-archive path keyed on `conversationIdentity` (DMs) writes `:ConversationArchive` (Task 397). Both attach `:Section` children. No bespoke `:Post`, `:DirectMessage`, `:DMThread`, `:Attachment`, or `:Thread` label is introduced; per-thread KD granularity is explicitly rejected.
+- **Not a live X API client.** Archive-only — the X API is rate-limited and paid.
+- **Not a retweet importer.** Retweets-without-comment are not persisted reliably in X archives; the skill drops them.
+
+## Relationship to other plugins
+
+- **memory** — the underlying graph-write surface used by the skill (`mcp__plugin_memory_memory__memory-write` etc.). The skill passes `source='x'` / `source='x-dm'` and `createdByAgent='x-import'` for provenance on every write.
+- **document-ingest** (memory skill) — owns the tweet-stream KnowledgeDocument writes. `:Section` classification is its responsibility, not this plugin's.
+- **conversation-archive** (memory skill) — owns the DM transcript writes (`:ConversationArchive` keyed on `conversationIdentity` — Task 397). The `x-dm` enum entry on `CONVERSATION_SOURCES` and the sibling normaliser in `platform/plugins/memory/mcp/src/lib/conversation-normalisers/x-dm.ts` are the only new code outside this plugin.
+- **database-operator specialist** — owns execution. See [platform/templates/specialists/agents/database-operator.md](../../templates/specialists/agents/database-operator.md) external-archive ingestion clause.

package/payload/platform/plugins/x-import/references/archive-shape.md

@@ -0,0 +1,124 @@
+# X archive shape
+
+The X (Twitter) Basic Data Export is a ZIP whose extracted layout looks like:
+
+```
+Archive of <handle>/
+├── Your archive.html         (UI entrypoint — ignored)
+├── data/
+│   ├── account.js            (owner identity: accountId, username, displayName)
+│   ├── tweets.js             (operator-authored tweets, replies, quote-tweet authorship)
+│   ├── tweet-headers.js      (tweet metadata including deletions)
+│   ├── direct-messages.js    (1:1 DMs)
+│   ├── direct-messages-group.js  (group DMs; absent if none)
+│   ├── profile.js            (operator profile metadata — bio, location)
+│   ├── tweet_media/          (images, videos, GIFs attached to tweets)
+│   ├── direct_messages_media/  (images, videos attached to DMs)
+│   └── ... (many other .js files — ignored unless this skill adopts them)
+└── assets/                   (frontend bundle — ignored)
+```
+
+## `.js` wrapper grammar
+
+Every data file ships as a JSONP-style shim — a single assignment to a global, then a JSON value:
+
+```
+window.YTD.<feed>.part<N> = <json>
+```
+
+Where:
+
+- `<feed>` is a stable token per file (`account`, `tweet`, `tweet_headers`, `direct_messages`, `direct_messages_group`, `profile`, …).
+- `<N>` is the partition index — single-part archives use `0`; very large archives may split into `part0`, `part1`, …
+- `<json>` is the post-assignment payload — always an array at the top level for the files this skill reads (`tweet`, `tweet_headers`, `direct_messages`, `direct_messages_group`); an array containing one entry for the single-record files (`account`, `profile`).
+
+The wrapper is fixed and verifiable. The skill MUST verify it before stripping:
+
+```js
+const WRAPPER_RE = /^\s*window\.YTD\.([a-z_]+)\.part(\d+)\s*=\s*/;
+```
+
+A file whose first non-whitespace bytes do not match `window.YTD.<feed>.part<N> = ` is a defective input. The parser MUST loud-fail with `phase=parse reason="missing window.YTD wrapper on <filename>"` rather than attempt JSON.parse on the raw bytes — the failure mode the task spec calls out is silent zero-tweet imports on unwrapped-JSON input.
+
+## Top-level shapes (read by this skill)
+
+### `data/account.js`
+
+```json
+[
+  { "account": {
+      "accountId": "1234567890",
+      "username": "joelsmalley",
+      "displayName": "Joel Smalley",
+      "createdAt": "2009-...",
+      "email": "..."
+  } }
+]
+```
+
+The skill reads `account.accountId` (the X numeric id of the operator), `account.username` (the handle without the `@`), and `account.displayName`. `email` is ignored.
+
+### `data/tweets.js`
+
+```json
+[
+  { "tweet": {
+      "id_str": "1700000000000000000",
+      "full_text": "<verbatim tweet text>",
+      "created_at": "Wed Jul 03 14:23:01 +0000 2024",
+      "in_reply_to_status_id_str": "169...",
+      "in_reply_to_screen_name": "adamlangley",
+      "entities": {
+        "user_mentions": [ { "screen_name": "adamlangley", "name": "...", "id_str": "..." } ],
+        "urls": [ { "expanded_url": "https://...", "display_url": "..." } ],
+        "media": [ { "media_url_https": "...", "type": "photo|video|animated_gif", "id_str": "..." } ]
+      },
+      "quoted_status_id_str": "169..."
+  } }
+]
+```
+
+The skill reads the documented fields and ignores everything else. `created_at` is a Twitter-flavoured RFC 2822 string; convert to ISO 8601 with UTC offset before rendering.
+
+### `data/tweet-headers.js`
+
+```json
+[
+  { "tweet": {
+      "tweet_id": "1700000000000000000",
+      "user_id": "1234567890",
+      "created_at": "Wed Jul 03 14:23:01 +0000 2024"
+  } }
+]
+```
+
+Used for deletion detection: any `tweet.tweet_id` in `tweet-headers.js` with no matching entry in `tweets.js` is a deleted tweet — render it in the transcript as `[deleted on <iso>]`.
+
+### `data/direct-messages.js` and `data/direct-messages-group.js`
+
+```json
+[
+  { "dmConversation": {
+      "sessionId": "1234567890-9876543210",
+      "messages": [
+        { "messageCreate": {
+            "id": "170...",
+            "senderId": "1234567890",
+            "recipientId": "9876543210",
+            "text": "Hello",
+            "createdAt": "2024-09-12T14:32:01.000Z",
+            "mediaUrls": []
+        } },
+        { "reactionCreate": { ... } }
+      ]
+  } }
+]
+```
+
+For 1:1 DMs the `sessionId` is `<id1>-<id2>` (numeric senderIds joined with `-`, lexicographic order). For group DMs the sessionId is opaque. Only `messageCreate` envelopes are message turns; `reactionCreate`, `joinConversation`, `leaveConversation` are skipped at the normaliser (counted under `systemSkipped`).
+
+## What this skill ignores
+
+- `profile.js` (bio, location) — outside scope; the operator profile is already captured in `:AdminUser`.
+- `following.js`, `followers.js`, `mute.js`, `block.js` — relationship graphs flatten cleanly into `:Person` natural-key MERGEs; out of scope for this task.
+- All other `.js` files (`like.js`, `bookmark.js`, etc.) — out of scope until a future task adopts them.

package/payload/platform/plugins/x-import/references/transcript-shape.md

@@ -0,0 +1,121 @@
+# Tweet-stream transcript rendering
+
+The X tweet stream becomes one `:KnowledgeDocument` whose body is a verbatim chronological transcript of every operator-authored tweet, reply, and quote-tweet. The classifier (`memory-classify`, document mode) splits this body into `:Section` children — threading and topic boundaries live as section boundaries inside the body, never as separate graph nodes.
+
+The transcript is plain UTF-8 markdown, oldest tweet first, designed so the classifier reads sections as topic-bounded runs of related tweets.
+
+## Separator and header
+
+Each tweet entry starts with a separator line, then a header line, then a blank line, then the body, then a blank line:
+
+```
+---
+@<handle> | <iso-8601 instant>
+
+<tweet body verbatim>
+
+```
+
+- `<handle>` is the operator's `username` (the archive owner) for every entry — the tweet stream is operator-authored content only.
+- `<iso-8601 instant>` is the parsed `created_at` rendered as `YYYY-MM-DDTHH:MM:SS+00:00`. Always UTC offset (the archive's `created_at` is UTC-fixed).
+- `<tweet body verbatim>` is the `full_text` field verbatim — no entity expansion, no URL shortening, no truncation. Entity references (mentions, URLs) appear inline as they did in the original tweet.
+
+## Reply context
+
+When `in_reply_to_status_id_str` is set, the header gets a suffix:
+
+```
+---
+@<handle> | <iso> | replying to @<in_reply_to_screen_name>
+
+<tweet body verbatim>
+
+```
+
+The skill does not attempt to render the parent tweet body — operator replies that quote the parent verbatim do so naturally inside `full_text`.
+
+## Quote-tweet context
+
+When `quoted_status_id_str` is set, the quoted tweet's text is rendered inline beneath the operator's text, indented as a markdown blockquote prefixed by author and timestamp. The quoted tweet's body comes from the archive when present (`data/tweets.js` may contain quoted tweets the operator authored themselves) or from the entity-expansion URL when not.
+
+```
+---
+@<handle> | <iso>
+
+<operator's tweet body verbatim>
+
+> @<quoted-author> | <quoted iso>: <quoted body>
+
+```
+
+When the quoted tweet text is not available in the archive (third-party quoted tweet), render:
+
+```
+> @<quoted-author>: <quoted-status-url>
+```
+
+## Deletion markers
+
+Any tweet referenced in `data/tweet-headers.js` with no matching body in `data/tweets.js` is a deleted tweet. Render in the chronological slot:
+
+```
+---
+@<handle> | <iso>
+
+[deleted on <iso>]
+
+```
+
+Deletion bodies preserve chronological context for the classifier (a topic-bounded section may include a "deleted" marker between two surviving tweets without the section boundary being broken).
+
+## Media references
+
+Embedded media gets one inline reference per attachment, immediately after the tweet body and before the trailing blank line:
+
+```
+---
+@<handle> | <iso>
+
+<tweet body verbatim>
+
+[media: photo — <sha256>-<filename>]
+[media: video — <sha256>-<filename>]
+
+```
+
+The actual bytes are staged under `{accountDir}/archive/x/<importId>/media/`; the reference token names the file the classifier can read if needed. Binary-only media (video) is referenced but not ingested as a child KD. Document-shaped media (OCR-able images, archived PDFs) recurses through `document-ingest` to land a child KD, attached via `HAS_ENCLOSURE` from the tweet-stream KD.
+
+## Ordering and stability
+
+- Tweets sort by `created_at` ascending — chronological, oldest first.
+- Two tweets with identical `created_at` sort by `id_str` ascending (X tweet IDs are time-ordered snowflakes; lexicographic order on the string form is equivalent to numeric order within a millisecond).
+- Re-rendering the same archive bytes produces byte-identical output — the `attachmentId = sha256(transcript-bytes)` idempotency contract depends on this.
+
+## Worked example
+
+```
+---
+@joelsmalley | 2024-07-03T14:23:01+00:00
+
+Just published a piece on retail flows. Curious what @adamlangley thinks.
+
+---
+@joelsmalley | 2024-07-03T14:31:22+00:00 | replying to @adamlangley
+
+Fair pushback. The chart on page 4 covers exactly that case.
+
+---
+@joelsmalley | 2024-07-03T18:02:00+00:00
+
+QT: this matches my intuition.
+
+> @danmcleod | 2024-07-03T17:45:11+00:00: New data on the Q3 inflow pattern — see thread.
+
+---
+@joelsmalley | 2024-07-04T09:00:00+00:00
+
+[deleted on 2024-07-04T09:00:00+00:00]
+
+```
+
+The classifier sees four chronological entries with stable boundaries — a retail-flows topic, a reply continuation, a QT response, then a deletion gap. Whether those become one section or several is the classifier's decision, not this plugin's.

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

@@ -0,0 +1,123 @@
+---
+name: x-import
+description: Ingest an extracted X (Twitter) archive directory into the graph as one :KnowledgeDocument (tweet stream) plus one :ConversationArchive per DM participant set. Triggers when the operator drops an `Archive of <handle>` directory or `twitter-<handle>-archive.zip` path into chat. Owner + every distinct participant confirms against existing `:AdminUser` / `:Person` nodes before any write. Idempotent on archive content hash.
+---
+
+# X Import
+
+**Invoked from `specialists:archive-ingest-operator`** — the admin agent dispatches the archive-ingest-operator when the operator hands over an X archive, and the archive-ingest-operator loads this skill. The admin agent never calls this skill directly.
+
+One X archive becomes:
+
+- **One `:KnowledgeDocument`** (`source='x'`) carrying the verbatim chronological transcript of the operator's authored content — root tweets, replies, quote-tweet authorship, deletion markers. `memory-classify` (document mode) splits the body into topic-bounded `:Section` children. Threading is a within-body concept rendered in the transcript; per-thread KDs are explicitly rejected.
+- **N `:ConversationArchive` nodes** (`source='x-dm'`) — one per distinct DM participant set, MERGEd on the existing `conversationIdentity = sha256(accountId + ":" + sortedParticipantElementIds)` key. DM media attaches to the archive node via `HAS_ENCLOSURE`.
+- **Person resolution** — every `@handle` mentioned, replied-to, or quoted in the tweet stream MERGEs against `:Person` on lowercased `xHandle` scoped by `accountId`. Existing `:Person` nodes gain `xHandle` on `ON CREATE SET` without overwriting operator edits.
+
+## Archive shape
+
+See [archive-shape.md](../../references/archive-shape.md) for the `.js` wrapper grammar and which files in the archive carry which data. The grammar is verified at parse — unwrapped JSON or a missing `window.YTD.*.partN = ` prefix errors loudly, never silently zero-tweets.
+
+## Transcript rendering
+
+See [transcript-shape.md](../../references/transcript-shape.md) for the exact rendering of the tweet-stream KD body — chronological separators, quote-tweet indentation, deletion markers, media references.
+
+## Pipeline (deterministic, four phases)
+
+### Phase 0 — Owner + participant confirmation
+
+Before any classify or ingest call:
+
+1. **Identify the owner.** Read `data/account.js` to extract the archive owner's `accountId`, `username` (the handle), and `displayName`. Surface to the operator: `"X archive owner: @<handle> (<displayName>). Confirm this maps to :AdminUser <name> ({userId})."`. Refuse to proceed without confirmation.
+
+2. **Enumerate distinct participants from the tweet stream.** Read `data/tweets.js` and `data/tweet-headers.js`. Extract every `@handle` that appears as a mention, reply target (`in_reply_to_screen_name`), or quote-tweet author. Emit a single-line histogram per distinct handle: `Handle '@<handle>' (<mentions> mentions, <replies> replies, <quotes> quotes)`.
+
+3. **Enumerate distinct DM participants.** Read `data/direct-messages.js` and `data/direct-messages-group.js` (when present). For each `dmConversation`, extract the distinct senderIds. Senders map to existing `:Person` / `:AdminUser` by either prior `xUserId` property or operator confirmation against numeric ID + recent-message preview.
+
+4. **One operator question per distinct handle / senderId.** Mirror the conversation-archive flow: `"Handle '@<h>' (<n> mentions) — pick existing :Person/:AdminUser or block?"`. The operator either picks an elementId or names "block" (refuses to map). **Never auto-create a `:Person`** — the operator must confirm a canonical node.
+
+5. **Persist resolved IDs.** Build two maps: `handleToElementId` (handle → :Person elementId, for the tweet-stream KD edges) and `senderIdToElementId` (numeric senderId → :Person/:AdminUser elementId, for DM participant lists). Both maps are passed to the writers in subsequent phases.
+
+### Phase 1 — Tweet-stream transcript + media staging
+
+1. **Walk the tweet stream chronologically.** Merge `data/tweets.js` (operator-authored tweets) and `data/tweet-headers.js` (metadata). For each tweet: extract `id_str`, `created_at`, `full_text`, `in_reply_to_status_id_str`, `in_reply_to_screen_name`, `entities.user_mentions`, `entities.urls`, `entities.media`, `quoted_status_id_str`. Sort by `created_at` ascending.
+
+2. **Render the transcript.** Apply the rules in [transcript-shape.md](../../references/transcript-shape.md). The output is a single UTF-8 text file written to `{accountDir}/archive/x/<importId>/tweet-stream.md`, where `importId = sha256(archive bytes)` truncated to 16 hex chars.
+
+3. **Stage media enclosures.** For each `entities.media` entry: copy from `data/tweet_media/<filename>` to `{accountDir}/archive/x/<importId>/media/<sha256>-<filename>` (perms 0o600). Same for DM media (`data/direct_messages_media/`) — staged into the same `media/` dir with the same hash-prefixed naming so re-import is content-addressed.
+
+4. **Render deletion markers.** When `tweet-headers.js` references an id that has no body in `tweets.js`, render the slot in the transcript as `[deleted on <iso>]` so context boundaries survive classification.
+
+### Phase 2 — Tweet-stream :KnowledgeDocument ingest
+
+Dispatch the existing librarian / document-ingest pipeline against the rendered transcript file. The attachment metadata block is constructed deterministically:
+
+- `filename = "tweet-stream-@<handle>.md"`
+- `attachmentId = sha256(transcript-bytes)` — guarantees idempotency on identical content
+- `storagePath = {accountDir}/archive/x/<importId>/tweet-stream.md`
+- `mimeType = "text/markdown"`
+
+The dispatch brief names:
+- **Anchor:** `:AdminUser` (the confirmed owner from Phase 0). Adam Mackay / Joel Smalley etc. resolved in Phase 0 appear in the **key entities to connect** list — `wire-brief-entities` writes the `MENTIONED` / `REPLIED_TO` / `QUOTED` edges from the new KD to each `:Person`.
+- **`sourceUrl`:** `https://x.com/<handle>`
+- **`sourceType`:** `'x'` (carried into `:KnowledgeDocument.source`)
+- **`scope`:** `'admin'` (the tweet stream is the operator's authored content)
+
+After document-ingest returns, write the inverse `REPLIED_TO` edges from each inbound-reply author (`:Person`) to the tweet-stream KD — one Cypher MERGE per distinct inbound-replier resolved in Phase 0. Edges carry `accountId`, `sourceDocumentId = attachmentId`, and `createdByAgent = 'x-import'` so re-ingest cleans them up.
+
+### Phase 3 — DM `:ConversationArchive` ingests (one per dmConversation)
+
+For each `dmConversation` in `data/direct-messages.js` (and `data/direct-messages-group.js` when present):
+
+1. **Split.** Write a per-conversation slice file at `{accountDir}/archive/x/<importId>/dm-<sessionId>.json` — a wrapper-stripped JSON array of length 1 whose single element is the dmConversation envelope. This is the file the x-dm normaliser reads.
+
+2. **Resolve participants.** Take the `senderIdToElementId` map from Phase 0; the participant set for this conversation is the distinct senderIds in the slice. The owner is the operator's confirmed `:AdminUser` elementId.
+
+3. **Invoke the bash.** Run in the background (heartbeat protocol per `conversation-archive` SKILL.md):
+
+   ```bash
+   bash platform/plugins/memory/bin/conversation-archive-ingest.sh \
+     {accountDir}/archive/x/<importId>/dm-<sessionId>.json \
+     --source x-dm \
+     --participant-person-ids <ownerEid>,<otherEid>,... \
+     --scope admin \
+     --session-id x-import-<importId>-dm-<sessionId>
+   ```
+
+4. **Surface the three operator messages** (parse → classify → write) from each invocation per the existing conversation-archive contract.
+
+### Phase 4 — Media enclosures
+
+After both the KD and all `:ConversationArchive` writes complete:
+
+- For each tweet-media file, write `(:KnowledgeDocument {tweetStreamKd})-[:HAS_ENCLOSURE]->(:ImageObject)` (image media) or write `(:KnowledgeDocument)-[:HAS_ENCLOSURE { contentUrl }]->(...)` skipping body ingest for binary-only video.
+- Document-shaped media (OCR-able images, PDFs from quote-tweeted articles when archived) recurse through `document-ingest` to land a child `:KnowledgeDocument`, attached via `HAS_ENCLOSURE` from the parent tweet-stream KD.
+- DM media: same `HAS_ENCLOSURE` shape but attaches from the relevant `:ConversationArchive`.
+
+## Diagnostic line
+
+After the full ingest completes, emit a single grep-able line:
+
+```
+[x-import] importId=<id16> tweets=<n> kdCreated=<0|1> kdUpdated=<0|1> people=<p> enclosures=<e> dmConversations=<d> ms=<ms>
+```
+
+Surfaces to the operator as one chat line. `kdCreated + kdUpdated == 1` per tweet-stream ingest (one or the other, never both, never zero on a valid archive).
+
+## Idempotency
+
+- Re-running the same archive bytes is a no-op for the tweet-stream KD — `attachmentId = sha256(transcript-bytes)` matches the prior write; `document-ingest` skips on identical `attachmentId`.
+- A newer archive containing additional tweets produces a different transcript and therefore a different `attachmentId` — the prior KD is replaced (sections regenerated under the same `sourceDocumentId`).
+- DM `:ConversationArchive` re-ingest follows the conversation-archive cursor model: same `conversationIdentity` → delta-append. No `--rebuild` is ever issued autonomously.
+- Person `xHandle` writes are `ON CREATE SET` — re-import never overwrites operator edits.
+
+## Wrapper-grammar defence
+
+Every `.js` shim read by this skill is gated through the wrapper regex documented in [archive-shape.md](../../references/archive-shape.md). Unwrapped-JSON input (missing the `window.YTD.<feed>.part0 = ` prefix on `tweets.js`, `direct-messages.js`, or `tweet-headers.js`) errors at parse with `phase=parse reason="missing window.YTD wrapper on <filename>"`. Silent zero-tweet imports are the failure mode this defence exists to prevent.
+
+## What this skill does not do
+
+- **Per-thread KDs.** One archive = one tweet-stream KD. Thread boundaries are section boundaries the classifier owns, not graph objects.
+- **Bespoke labels.** No `:Post`, `:Tweet`, `:DirectMessage`, `:DMThread`, `:Attachment`. Everything maps to the existing `:KnowledgeDocument` + `:ConversationArchive` + `:ImageObject` shapes.
+- **Tweet-level typed edges.** `:REPLIES_TO` / `:QUOTES` as graph edges off individual tweets are rejected; document-level `REPLIED_TO` / `QUOTED` from the KD to each `:Person` covers the same traversals at the right granularity. The Task 305 typed-edge pass enumerates the new KD and writes any further `COMMITTED_TO` / `MENTIONS` / `REFERENCES` edges from in-body references.
+- **Retweets-without-comment.** Not persisted reliably in X archives; dropped at parse.
+- **Live X API.** Archive-only.