mojulo 0.0.0 → 0.1.1

package/lib/mcp/catalysts/loader.js

@@ -0,0 +1,144 @@
+/**
+ * Skill catalyst loader.
+ *
+ * Skill catalysts are curated workflow patterns shipped with the control
+ * plane. They live as .md files in this directory and are exposed via the MCP
+ * server so the user's Claude can pull one, read the bot's shape via existing
+ * operate tools, and **catalyze** the synthesis of a concrete local skill into
+ * the user's `.claude/skills/`.
+ *
+ * The "catalyst" framing is literal: each file enables one phase transition
+ * from a vague user intent + a bot's shape + a destination MCP into a
+ * structured skill artifact. The catalyst is not consumed (the file persists
+ * and can catalyze again for the next bot) and does not appear in the
+ * resulting skill — it's the nucleation point that lets the skill crystallize
+ * out.
+ *
+ * Mojulo only ships the canonical library — there is no user-writable
+ * catalyst directory. Custom or one-off patterns are Claude Code's
+ * responsibility: a user wanting a bespoke workflow either lets Claude
+ * synthesize from scratch or maintains their own catalyst-shaped markdown
+ * locally.
+ *
+ * File format — JSON frontmatter between two `---` fences, then markdown body:
+ *
+ *   ---
+ *   { "id": "...", "name": "...", ... }
+ *   ---
+ *
+ *   # Body markdown the model reads at synthesis time.
+ *
+ * Frontmatter is JSON (not YAML) to keep the loader dep-free and the parse
+ * unambiguous. The body is the value — it's the prompt Claude reads to write
+ * the user's skill, so it carries the workflow reasoning, mapping intent, and
+ * pitfalls.
+ *
+ * Validation faults are loader bugs (the library is curated, not user input)
+ * — we throw with a clear file + field reference so a bad PR fails loudly.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CATALYST_DIR = dirname(fileURLToPath(import.meta.url));
+
+// `valueHook` is required: it's the consultation-mode sentence we read aloud
+// to position the catalyst when surfacing it via `recommend_catalysts` — one
+// sentence in user-outcome terms ("turn yesterday's submissions into qualified
+// CRM contacts"). Without it, the agent has only the `summary` (which is
+// implementation-shaped) and consultation suggestions sound bureaucratic.
+const REQUIRED_FIELDS = ['id', 'name', 'summary', 'valueHook'];
+const FRONTMATTER_FENCE = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
+
+let _catalog = null;
+
+function parseCatalystFile(filePath, raw) {
+  const match = raw.match(FRONTMATTER_FENCE);
+  if (!match) {
+    throw new Error(
+      `Catalyst ${filePath} is missing JSON frontmatter (expected '---' fences).`
+    );
+  }
+  let meta;
+  try {
+    meta = JSON.parse(match[1]);
+  } catch (err) {
+    throw new Error(`Catalyst ${filePath} has invalid JSON frontmatter: ${err.message}`);
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (!meta[field] || typeof meta[field] !== 'string') {
+      throw new Error(`Catalyst ${filePath} is missing required string field '${field}'.`);
+    }
+  }
+  const body = raw.slice(match[0].length).trim();
+  if (!body) {
+    throw new Error(`Catalyst ${filePath} has an empty body — the prose is the catalyst's value.`);
+  }
+  return {
+    id: meta.id,
+    name: meta.name,
+    summary: meta.summary,
+    valueHook: meta.valueHook,
+    version: meta.version ?? 1,
+    category: meta.category || null,
+    requires: meta.requires || {},
+    parameters: Array.isArray(meta.parameters) ? meta.parameters : [],
+    mcpTools: meta.mcpTools || {},
+    body,
+  };
+}
+
+function loadCatalog() {
+  const files = readdirSync(CATALYST_DIR).filter((f) => f.endsWith('.md'));
+  const catalysts = new Map();
+  for (const file of files) {
+    const filePath = join(CATALYST_DIR, file);
+    const raw = readFileSync(filePath, 'utf8');
+    const catalyst = parseCatalystFile(filePath, raw);
+    if (catalysts.has(catalyst.id)) {
+      throw new Error(
+        `Catalyst id collision: '${catalyst.id}' is declared in both ${catalysts.get(catalyst.id)._file} and ${file}.`
+      );
+    }
+    catalyst._file = file;
+    catalysts.set(catalyst.id, catalyst);
+  }
+  return catalysts;
+}
+
+export function getCatalystCatalog() {
+  if (!_catalog) _catalog = loadCatalog();
+  return _catalog;
+}
+
+export function listCatalysts({ category } = {}) {
+  const catalog = getCatalystCatalog();
+  const out = [];
+  for (const catalyst of catalog.values()) {
+    if (category && catalyst.category !== category) continue;
+    out.push({
+      id: catalyst.id,
+      name: catalyst.name,
+      summary: catalyst.summary,
+      valueHook: catalyst.valueHook,
+      category: catalyst.category,
+      requires: catalyst.requires,
+    });
+  }
+  return out;
+}
+
+export function getCatalyst(id) {
+  const catalyst = getCatalystCatalog().get(id);
+  if (!catalyst) return null;
+  const { _file, ...rest } = catalyst;
+  return rest;
+}
+
+// Test seam — let the test suite point at a fixture directory.
+export function _resetCatalogForTests(catalog) {
+  _catalog = catalog || null;
+}
+
+export { CATALYST_DIR as _CATALYST_DIR_FOR_TESTS, parseCatalystFile as _parseCatalystFileForTests };

package/lib/mcp/catalysts/qualify-lead-to-crm.md

@@ -0,0 +1,83 @@
+---
+{
+  "id": "qualify-lead-to-crm",
+  "name": "Qualify lead and sync to CRM",
+  "summary": "Score new submissions against the user's rubric and create matching CRM records, skipping low-quality leads.",
+  "valueHook": "Turn yesterday's intake submissions into qualified CRM contacts overnight, deduped and scored.",
+  "version": 1,
+  "category": "crm-sync",
+  "requires": {
+    "protocols": ["formGathering"],
+    "destinationMcpCategory": "crm-like",
+    "destinationExamples": ["HubSpot", "Salesforce", "Pipedrive", "Attio", "Close"]
+  },
+  "parameters": [
+    {
+      "name": "qualifyingCriteria",
+      "prompt": "What makes a 'qualified' submission for your business? (rubric in plain English — e.g., specific industries, geographic area, deal size signals, accepted insurance carriers)"
+    },
+    {
+      "name": "scoreThreshold",
+      "prompt": "Minimum qualifying score (0-100) below which a submission is skipped?",
+      "default": 60
+    },
+    {
+      "name": "dedupeKey",
+      "prompt": "Which submission field detects duplicate contacts in the CRM? (typically email or phone)"
+    }
+  ],
+  "mcpTools": {
+    "mojulo": ["query_submissions", "get_deployment"],
+    "destination": {
+      "description": "A CRM-like MCP exposing search-by-property + contact/deal create. Examples: HubSpot, Salesforce, Pipedrive, Attio."
+    }
+  }
+}
+---
+
+# Qualify lead and sync to CRM
+
+This catalyst turns a `formGathering` mojulo bot into a CRM intake pipeline. You score each new submission against the user's rubric, dedupe against existing CRM records, and create a contact (and optionally a deal) for the qualified ones.
+
+## How to synthesize the skill
+
+1. Call `get_deployment(deploymentId)` to read the bot's form schema. The synthesized skill's mapping is **derived from this schema** — never guess field names.
+2. Ask the user the three `parameters` questions in one round.
+3. Inspect the bound destination MCP to learn its contact-create surface (field names, required props, search-by-property tool). Field mapping is the catalyst's value-add — don't assume it's `name`/`email`/`phone` everywhere; HubSpot uses `firstname`/`lastname`/`email`, Salesforce uses `FirstName`/`LastName`/`Email`, Attio uses object/attribute pairs.
+4. Write `.claude/skills/<bot-slug>-crm-sync/SKILL.md` with the synthesized workflow. The skill takes `deploymentId` and `since` as inputs.
+
+## Mapping intent
+
+The mojulo submission JSON has one entry per form field. Map by **field semantics**, not by position:
+
+- Identity fields (email, phone, name) → CRM contact identity props. Use the configured `dedupeKey` to search-before-create.
+- Categorical fields (industry, plan interest, source) → CRM contact properties or pipeline/stage tags on the created deal.
+- Free-text fields (chief complaint, message, notes) → CRM contact `notes` or a follow-up activity log entry. Do **not** create a deal from free-text alone — these are the noisiest fields.
+- Timestamp + submission id → store as `mojulo_submission_id` + `mojulo_captured_at` on the contact for traceability.
+
+When the bot's form schema has a field that doesn't fit any CRM property, **ask the user** during synthesis where it should go. Don't silently drop fields.
+
+## Qualifying logic
+
+Run each submission through a single LLM judgement against `qualifyingCriteria`. Return a score 0-100 and a one-sentence reason. The skill stores the score + reason on the CRM contact (a `mojulo_qualifying_score` property) so the user can audit why something was kept or skipped without re-running the classifier.
+
+Submissions below `scoreThreshold` are logged but not pushed. The skill emits a decision log per run.
+
+## Idempotency
+
+Use `since` as a high-water cursor on the submission timestamp. Each run pulls only submissions newer than `since`. The synthesized skill should print the new cursor at end of run so the user can pass it back next time — or wire it through a scheduler.
+
+Independent of the cursor, **always search-before-create** on the `dedupeKey`. Two failure modes the cursor doesn't cover: a user re-runs an old window, or the same person submits twice. Search-before-create is the durable defense.
+
+## Pitfalls — surface these to the user
+
+- **PII back through the LLM.** Form-gathering's design point is that PII bypasses the LLM at capture time. This skill deliberately reintroduces PII at routing time, since qualifying needs to read fields like email or chief complaint. Worth confirming the user is OK with this against the data-handling posture they advertised to end users.
+- **Irreversible writes.** CRM contact creates are visible to sales reps and trigger downstream automations (welcome sequences, lead-rotation rules). Default the synthesized skill to a `--dry-run` mode that prints decisions without writing. The user explicitly opts into live writes per run.
+- **Rate limits.** CRMs throttle aggressively. Process submissions serially with a small inter-call delay rather than parallelizing.
+- **Field-mapping drift.** If the user later edits the bot's form schema, the skill's mapping goes stale silently. Recommend the user re-run the catalyst flow to regenerate the skill when they change the form.
+
+## Skill behavior contract
+
+- **Inputs:** `deploymentId` (string, required), `since` (ISO timestamp, optional — defaults to last-cursor or 24h ago), `dryRun` (bool, default true)
+- **Outputs:** a per-submission decision log: `{ submissionId, score, reason, action: 'created' | 'updated' | 'skipped-low-score' | 'skipped-duplicate', crmRecordId? }`
+- **Side effects (live mode only):** CRM contact create/update via the bound MCP. No mojulo-side writes.

package/lib/mcp/catalysts/scan-conversations-for-signal.md

@@ -0,0 +1,92 @@
+---
+{
+  "id": "scan-conversations-for-signal",
+  "name": "Scan conversations for a signal",
+  "summary": "Sample recent bot conversations, scan each for a user-defined signal (churn intent, competitor mentions, recurring complaints), and route matches to an actuator MCP.",
+  "valueHook": "Sample recent conversations for a signal you care about — churn intent, competitor mentions, recurring complaints — and route matches where the team can act.",
+  "version": 1,
+  "category": "analysis",
+  "requires": {
+    "protocols": [],
+    "destinationMcpCategory": "actuator-like",
+    "destinationExamples": ["Linear", "Slack", "Notion", "Google Sheets"]
+  },
+  "parameters": [
+    {
+      "name": "signalDefinition",
+      "prompt": "What signal are you scanning for? (e.g., 'mentions of competitor X', 'churn intent or cancellation language', 'accessibility complaints', 'recurring feature requests')"
+    },
+    {
+      "name": "sampleSize",
+      "prompt": "How many recent conversations to scan per run?",
+      "default": 30
+    },
+    {
+      "name": "matchAction",
+      "prompt": "What should happen when the signal fires? (e.g., 'file a Linear ticket tagged voice-of-customer', 'post a Slack message to #cs-insights', 'append a row to a Notion database')"
+    }
+  ],
+  "mcpTools": {
+    "mojulo": ["query_conversations", "get_conversation", "get_deployment"],
+    "destination": {
+      "description": "Any MCP that can perform the configured matchAction. Examples: Linear (issue_create), Slack (post_message), Notion (append_block), Sheets (append_row)."
+    }
+  }
+}
+---
+
+# Scan conversations for a signal
+
+This is the analytical counterpart to the write-side catalysts. Rather than acting on every submission, it samples conversations, looks for a specific signal in the turn text, and only acts when the signal fires. The point is **sampling, not sweeping** — a bounded scan lets the user tune their signal prompt against real conversations before scaling up.
+
+This catalyst formalizes a recipe already documented in [docs/mcp-integration.md](docs/mcp-integration.md#recipes) §4 — the formal version adds parameterization and a behavior contract.
+
+## How to synthesize the skill
+
+1. `get_deployment(deploymentId)` — read the bot's protocols and identity. The signal prompt benefits from knowing what the bot is *for*; "churn intent" means different things on a support bot vs. a sales bot.
+2. Ask the user the three `parameters` questions.
+3. Inspect the destination MCP for the actuator surface implied by `matchAction`. The mapping from signal-match to action payload is the catalyst's value-add.
+4. Write `.claude/skills/<bot-slug>-scan-<signal-slug>/SKILL.md`. Naming includes the signal so multiple signal scans on the same bot don't collide.
+
+## Scan logic
+
+1. `query_conversations(deploymentId, since?)` to get summaries — already sorted by recency.
+2. Take the top `sampleSize`. For each, `get_conversation(deploymentId, conversationId)` to pull the turn list.
+3. Run a single LLM judgement per conversation against `signalDefinition`. Return: `{ matched: bool, evidence: '<quoted snippet, ≤200 chars>', confidence: 'low' | 'medium' | 'high' }`.
+4. For matches, fire `matchAction` with a payload that includes the conversation id, the evidence snippet, and a link/path back to the source.
+
+## Action payload composition
+
+The synthesized skill should produce one action per match (not one batched action per run). The payload structure:
+
+- A title or summary derived from `signalDefinition` and the matched conversation
+- The evidence snippet **with surrounding context** (1 turn before, 1 turn after) — quoting in isolation loses meaning
+- Conversation id + deployment id + bot name (mojulo trace)
+- The chain verification URL `<bot-url>/verify/<conversationId>` so the reviewer can confirm authenticity
+
+## Sampling discipline
+
+`sampleSize` defaults to 30 for a reason — it keeps each run's LLM cost predictable and bounded. The user can scale up once they've validated the signal definition holds up. Recommend the synthesized skill default to a small sample for the first few runs, then graduate.
+
+For continuous monitoring, the right pattern is to combine this skill with `/schedule` so it runs on a cadence. Avoid trying to do "watch all conversations always" — there's no event surface for that, and the polling cost would be silly.
+
+## Multiple signals on one bot
+
+Don't synthesize a multi-signal skill. Each signal gets its own skill instance. Reasons:
+
+- The signal prompt is the brittle part — tuning one signal shouldn't risk regressing another.
+- Sampling overlap is fine: two skills both scanning the recent 30 cost roughly twice as much, which is fine.
+- Action targets often differ per signal (churn → CS Slack; competitor → product Notion; feature request → product backlog).
+
+## Pitfalls
+
+- **False positives flood the actuator.** A loose signal definition fires on too many conversations and floods the destination. The first run with a new signal should default to `--dry-run` so the user sees what would have fired before they wire it live.
+- **Confidence calibration.** "High confidence" from the model doesn't mean the signal is real — it means the model is sure of its own judgement. Recommend the user spot-check 10-20 matches early on to calibrate.
+- **PII through the LLM.** Conversation turns can contain sensitive content. Scanning by definition reads them. Same caveat as the other catalysts — confirm against the bot's data-handling posture.
+- **Stale conversations.** `query_conversations` is unbounded by default. With no `since`, the sample drifts toward the oldest conversations. Always pass `since` (default: 7d).
+
+## Skill behavior contract
+
+- **Inputs:** `deploymentId` (required), `sampleSize` (default 30), `since` (default 7d ago, ISO), `dryRun` (default true)
+- **Outputs:** per-conversation scan log `{ conversationId, matched, confidence, evidence?, actionResult? }`
+- **Side effects (live mode):** one destination-MCP action per match.

package/lib/mcp/catalysts/submission-to-ticket.md

@@ -0,0 +1,83 @@
+---
+{
+  "id": "submission-to-ticket",
+  "name": "Submission to ITSM ticket",
+  "summary": "Turn new submissions (or triaged conversations) into tickets in Linear/Jira/ServiceNow with routing, priority, and assignment.",
+  "valueHook": "Bot intake becomes routed, prioritized tickets in your team's tracker — no manual triage step.",
+  "version": 1,
+  "category": "itsm",
+  "requires": {
+    "protocols": ["formGathering"],
+    "optionalProtocols": ["triage"],
+    "destinationMcpCategory": "ticketing-like",
+    "destinationExamples": ["Linear", "Jira", "ServiceNow", "GitHub Issues"]
+  },
+  "parameters": [
+    {
+      "name": "routingRules",
+      "prompt": "How should submissions route to teams/projects/assignment groups? (e.g., 'urgent complaints → on-call coordinator; billing issues → finance queue; general → support backlog')"
+    },
+    {
+      "name": "priorityRules",
+      "prompt": "What signals priority? (e.g., 'words like emergency/urgent → high; missed-appointment forms → high; everything else → normal')"
+    },
+    {
+      "name": "titleTemplate",
+      "prompt": "How should the ticket title be composed? (e.g., '[chief_complaint] — [name] ([conversation_id])')"
+    }
+  ],
+  "mcpTools": {
+    "mojulo": ["query_submissions", "get_conversation", "get_deployment"],
+    "destination": {
+      "description": "A ticketing-like MCP exposing issue/ticket create with title, body, priority, project/queue, and assignee fields. Examples: Linear, Jira, ServiceNow, GitHub Issues."
+    }
+  }
+}
+---
+
+# Submission to ITSM ticket
+
+This catalyst wires a mojulo bot's submissions (and, when the `triage` protocol is enabled, the routing decision) into a ticketing system. Each submission becomes one ticket with derived priority, project/queue assignment, and a description rich enough that the assignee doesn't need to come back and read the original conversation.
+
+## How to synthesize the skill
+
+1. `get_deployment(deploymentId)` — read the form schema. If the bot has `triage` enabled, note the routes; they're hints for `routingRules`.
+2. Ask the user the three `parameters` questions.
+3. Inspect the destination MCP to learn its ticket-create surface — particularly the **project/queue identifier shape** (Linear team id, Jira project key, ServiceNow assignment group sys_id) and the **priority enum** (Linear: 1-4, Jira: P0-P5, ServiceNow: 1-5).
+4. Write `.claude/skills/<bot-slug>-ticket-sync/SKILL.md`.
+
+## Routing logic
+
+Apply `routingRules` as a single classification step per submission. The skill picks one project/queue per submission. If the rules don't match cleanly, default to a configured fallback queue rather than guessing — silent misrouting is worse than a clear "unsorted" pile a human can clear.
+
+When the bot has `triage` enabled, **prefer the bot's own triage decision over re-classifying**. The triage protocol has already routed the conversation against the vector store; re-doing that work risks divergence. Use the triage label as the queue assignment; only apply `routingRules` for priority and any secondary routing axis.
+
+## Priority logic
+
+Same shape: one LLM judgement per submission, returns a priority + one-sentence reason. The reason goes into the ticket body so reviewers see why something was tagged P0 vs P3.
+
+## Ticket body composition
+
+The synthesized skill should build the body from:
+
+1. **Submission fields** rendered as a clean key/value list (use the form schema field labels, not raw keys).
+2. **Conversation excerpt** — pull the conversation via `get_conversation(deploymentId, conversationId)` and include the last 4-6 turns. Don't dump the whole thing; reviewers will skim.
+3. **Mojulo trace** — submission id, conversation id, deployment id, captured-at timestamp. Critical for incident response — the reviewer needs to be able to walk back to the source.
+4. **Verification link** — if the conversation has a `chain_hash`, include the bot's `/verify/<conversationId>` URL so the reviewer can confirm tamper-evidence on dispute.
+
+## Idempotency
+
+`since` cursor + a `mojulo_submission_id` field on the ticket (most ticketing systems support custom fields or labels). Search-before-create to avoid double-filing on re-runs. If the system has no custom-field surface, append the submission id to the ticket title as `[sub:...]` and grep on retry.
+
+## Pitfalls
+
+- **Triage-vs-rules conflict.** If both the bot's triage and the skill's `routingRules` apply, the user needs to know which wins. Default to triage. Make the synthesized skill comment this clearly.
+- **PII in ticket bodies.** Tickets are often visible to wider teams than the form submission was intended for. If the bot collects SSN/DOB/financial info, ask the user during synthesis whether to redact those fields from the ticket body (store identifiers only) and link to the bot's submission view for the full record.
+- **Alert fatigue.** A new bot may have a backlog of historical submissions. The first run with a wide `since` window can flood a queue. Recommend the user start with a narrow window or pipe the first batch into a triage project for review.
+- **Closing the loop.** This skill creates tickets; it doesn't close them. Ticket lifecycle stays in the ITSM. If the user later wants the bot to know "this issue was resolved," that's a separate skill in the other direction (and not currently exposed).
+
+## Skill behavior contract
+
+- **Inputs:** `deploymentId` (required), `since` (optional ISO), `dryRun` (default true), `fallbackQueue` (required for live mode — the queue used when routing fails)
+- **Outputs:** per-submission decision log `{ submissionId, priority, queue, ticketId? }`
+- **Side effects (live mode only):** ticket create via destination MCP. No mojulo-side writes.

package/lib/mcp/catalysts/submissions-to-warehouse.md

@@ -0,0 +1,103 @@
+---
+{
+  "id": "submissions-to-warehouse",
+  "name": "Submissions to data warehouse",
+  "summary": "Append form submissions to an analytical warehouse table (BigQuery/Snowflake/Postgres/Redshift) with stable schema and incremental cursor — append-only, no qualifying logic, ready for SQL analysis downstream.",
+  "valueHook": "Submissions land in your analytics warehouse with a stable schema, ready for SQL analysis and dashboards downstream.",
+  "version": 1,
+  "category": "warehouse",
+  "requires": {
+    "protocols": ["formGathering"],
+    "destinationMcpCategory": "warehouse-like",
+    "destinationExamples": ["BigQuery", "Snowflake", "Postgres", "Redshift", "DuckDB"]
+  },
+  "parameters": [
+    {
+      "name": "targetTable",
+      "prompt": "Fully-qualified target table name (e.g., 'analytics.mojulo_submissions', 'PROD.RAW.BOT_INTAKES'). Will be created if absent and the destination MCP supports DDL; otherwise the user creates it from the schema you propose."
+    },
+    {
+      "name": "columnMapping",
+      "prompt": "How should form fields map to warehouse columns? Provide field-name → column-name pairs plus the SQL type each column should use (STRING, TIMESTAMP, NUMERIC, BOOLEAN, JSON). For fields that aren't a clean fit, propose a JSON column and pack them there."
+    },
+    {
+      "name": "partitionStrategy",
+      "prompt": "How should the table be partitioned for query performance? (e.g., 'daily by captured_at', 'by deployment_id', 'none — small volume'). Defaults to daily if the warehouse supports time-partitioned tables.",
+      "default": "daily by captured_at"
+    },
+    {
+      "name": "backfillOnFirstRun",
+      "prompt": "On the first run, should the skill backfill all historical submissions, or start from now-forward only? Backfill is fine for low-volume bots; bounded windows are safer for high-volume.",
+      "default": "now-forward only"
+    }
+  ],
+  "mcpTools": {
+    "mojulo": ["query_submissions", "get_deployment"],
+    "destination": {
+      "description": "A warehouse-like MCP that exposes table create (optional) and row append/insert with named columns and types. Examples: BigQuery, Snowflake, Postgres, Redshift, DuckDB. The destination must support either bulk insert (preferred) or single-row insert. Streaming inserts are nice-to-have."
+    }
+  }
+}
+---
+
+# Submissions to data warehouse
+
+This is the analytical-pipeline counterpart to `qualify-lead-to-crm`. Where that catalyst is **opinionated** (scoring, branching, dedupe-as-update), this one is **mechanical** (append-only, schema-of-record, no qualifying judgments). The output is a warehouse table that downstream analysts can SQL against without knowing anything about mojulo's internals.
+
+If you find yourself wanting "qualify the row before inserting" or "update an existing record on second submission" — that's the `qualify-lead-to-crm` catalyst, not this one. This catalyst's value is exactly its lack of opinions; every submission goes through, with the same shape, every time.
+
+## How to synthesize the skill
+
+1. `get_deployment(deploymentId)` — read the form schema. The schema **is** the source-of-truth for `columnMapping`. Never invent columns the bot's form doesn't produce; never silently drop form fields without surfacing them as candidates for a JSON column.
+2. Ask the user the four `parameters` questions, batched. Propose a default `columnMapping` derived from the form schema (best-guess types per field name) and let the user adjust — don't make them type the whole mapping from scratch.
+3. Inspect the destination MCP. Confirm it supports the insert path you need (bulk preferred, single-row acceptable). If the user's warehouse MCP only exposes query/read (no write), this catalyst doesn't apply — say so plainly rather than trying to force a path.
+4. Write `.claude/skills/<bot-slug>-warehouse-sync/SKILL.md`. The skill takes `deploymentId` and `since` as inputs.
+
+## Schema design
+
+Every row in the target table has the same shape, regardless of which form was submitted. The columns:
+
+- **Universal trace columns** — `submission_id` (PRIMARY KEY), `deployment_id`, `conversation_id`, `captured_at` (TIMESTAMP), `ingested_at` (TIMESTAMP — when this skill ran). These are non-negotiable. They're what makes the warehouse rows joinable to other systems and analyzable over time.
+- **Mapped form columns** — one column per form field, per `columnMapping`. Types chosen to match analytical use (TIMESTAMP for dates, NUMERIC for currency, STRING for free text, BOOLEAN for yes/no, JSON for nested).
+- **Fallback `raw_extras` JSON column** — any form field the user didn't explicitly map lands here. Better to capture-and-defer than to drop. Analysts can JSON-extract later if a field turns out to matter.
+- **Optional partition column** — typically `captured_at` derived to a date for daily partition pruning. Some warehouses (BigQuery) have explicit partition syntax; others (Snowflake) use clustering keys.
+
+The schema should be **additive-friendly** — when the bot's form grows new fields, the synthesized skill should detect the unmapped field, route it to `raw_extras`, and emit a clear log line. The user can later promote it to a typed column with an ALTER + a one-time backfill from `raw_extras`. Don't try to auto-ALTER the schema from the skill; warehouse DDL is operator territory.
+
+## Incremental cursor
+
+`since` cursor on `captured_at` is the primary mechanism. Each run:
+
+1. Read the table's `MAX(captured_at)` (or accept `since` as input override).
+2. `query_submissions(deploymentId, since=...)` to pull only newer rows.
+3. Bulk-insert the batch.
+4. Print the new high-water timestamp so the user can pass it back or wire it to a scheduler.
+
+The synthesized skill should NOT rely on `submission_id` for incremental cursoring — IDs aren't guaranteed monotonic over time in the bot's SQLite. Always use timestamp.
+
+## Idempotency
+
+Two layers of defense, both important:
+
+- **Cursor-based dedup (primary):** the `since` cursor advances past already-loaded rows. Re-running with the same `since` is a no-op when no new submissions exist.
+- **`submission_id` PRIMARY KEY (safety net):** because cursor logic can fail (operator manually re-runs an old window, clock skew), the destination table's primary key on `submission_id` ensures double-inserts fail loudly rather than silently duplicate. Use `INSERT ... ON CONFLICT DO NOTHING` (Postgres) / `MERGE ... WHEN NOT MATCHED` (BigQuery/Snowflake) so re-runs degrade to no-ops instead of errors.
+
+## Bulk vs. streaming
+
+Default to **bulk inserts** (one statement per run, all rows in one batch). Reasons: cheaper per-row, atomic from the warehouse's perspective, easier to reason about for incremental loads. Streaming inserts are tempting for "near-real-time" but introduce per-row cost and break the idempotency story when retries land.
+
+If the user's volume is high enough to need streaming (>~1000 submissions/hour sustained), this catalyst isn't the right tool — the bot's webhook ([server.js](../../lite-template/server.js)'s `/api/send-webhook`) is the architecturally-correct path for event-driven warehouse loading, and the skill becomes "drain the webhook DLQ" rather than "scan the bot's SQLite." Surface this distinction to the user if their submission rate is in that range.
+
+## Pitfalls
+
+- **PII in the warehouse.** Warehouses are typically more broadly accessible than the bot's SQLite — analysts, BI tools, downstream pipelines, sometimes vendors. If the form captures sensitive fields (DOB, SSN, financial, medical), the synthesized skill should default to **excluding** those columns from the mapping and pointing the user at column-level encryption or a separate restricted-access table. The user can override, but the question must be asked explicitly during synthesis.
+- **Schema drift.** When the bot's form gains/renames/drops fields, the warehouse columns silently misalign. The skill must detect unmapped fields each run and emit a log line; recommend the user re-run the catalyst flow when they change the form.
+- **Type coercion silently lies.** If a form field is "free text" but most rows look numeric, the user might map it to NUMERIC. The day a row arrives with `'N/A'` in that field, the insert fails or the value goes NULL. Default to STRING for any free-text field and let the user explicitly promote to a typed column only when they're certain of the data.
+- **Backfill stampedes.** A `backfillOnFirstRun=true` against a bot with months of submissions will hammer both the bot proxy and the destination warehouse. Recommend chunking the backfill into 7-day windows with a delay between, and surface progress (`backfilled 2026-01-01..2026-01-07: 312 rows`).
+- **Bot-proxy load.** `query_submissions` proxies through to the bot. For very large windows, the proxy can timeout or the bot can be slow to serialize. Recommend keeping per-run windows bounded (≤30 days) and chaining if a larger backfill is needed.
+
+## Skill behavior contract
+
+- **Inputs:** `deploymentId` (required), `since` (optional ISO — defaults to MAX(captured_at) from the destination table, falling back to 24h ago on first run), `dryRun` (default true)
+- **Outputs:** per-run summary: `{ deploymentId, windowStart, windowEnd, rowsInserted, rowsSkippedDuplicate, unmappedFields: [...], newHighWaterMark }`
+- **Side effects (live mode):** bulk insert / merge to the destination warehouse table. No mojulo-side writes. No bot-side writes.

package/lib/mcp/catalysts/weekly-submissions-digest.md

@@ -0,0 +1,82 @@
+---
+{
+  "id": "weekly-submissions-digest",
+  "name": "Periodic submissions digest",
+  "summary": "Produce a recurring digest of recent bot submissions (counts, trends, notable items) and post it to a doc, channel, or email.",
+  "valueHook": "A recurring summary of recent submissions — counts, trends, notable items — posted where stakeholders see it.",
+  "version": 1,
+  "category": "digest",
+  "requires": {
+    "protocols": ["formGathering"],
+    "destinationMcpCategory": "doc-or-channel-like",
+    "destinationExamples": ["Notion", "Slack", "Gmail", "Google Docs"]
+  },
+  "parameters": [
+    {
+      "name": "cadenceDescription",
+      "prompt": "How often will this run, and what window should each digest cover? (e.g., 'weekly, covering the prior 7 days')"
+    },
+    {
+      "name": "groupBy",
+      "prompt": "What dimensions should the digest break submissions down by? (e.g., 'source channel, lead type, urgency tag' — pick fields from the bot's form schema)"
+    },
+    {
+      "name": "notableThreshold",
+      "prompt": "What qualifies as a 'notable' submission worth calling out individually in the digest? (e.g., 'high-priority complaints, deals > $10k, returning customer issues')"
+    },
+    {
+      "name": "outputFormat",
+      "prompt": "Where does this land, and what format? (e.g., 'Notion page in workspace X', 'Slack message to #bot-digest', 'email to team@example.com')"
+    }
+  ],
+  "mcpTools": {
+    "mojulo": ["query_submissions", "get_deployment"],
+    "destination": {
+      "description": "Any MCP that can write a document or post a message. Examples: Notion (create_page), Slack (post_message), Gmail (send_email), Google Docs (create_document)."
+    }
+  }
+}
+---
+
+# Periodic submissions digest
+
+A digest skill is a low-cost way for a team to stay aware of what a bot is collecting without anyone manually clicking through the dashboard. The synthesis goal is a skill that, run on a cadence (manually or via scheduler), summarizes the recent submission window into the user's chosen output surface.
+
+## How to synthesize the skill
+
+1. `get_deployment(deploymentId)` — read the form schema. The fields listed in `groupBy` must exist; if not, ask the user to pick others.
+2. Ask the user the four `parameters` questions in one round.
+3. Inspect the destination MCP's write surface — markdown support, length limits, attachment support. The digest format adapts to what the destination accepts.
+4. Write `.claude/skills/<bot-slug>-digest/SKILL.md`.
+
+## Digest composition
+
+A good digest has four sections, in this order:
+
+1. **Header:** bot name, window covered, total submissions.
+2. **Counts:** breakdown by each `groupBy` dimension. Tables or bullet lists depending on destination capability.
+3. **Trends:** week-over-week deltas if a prior digest exists. The synthesized skill should optionally read the prior digest from the destination to compute deltas; if the destination doesn't support read, skip trends.
+4. **Notable items:** 3-10 submissions matching `notableThreshold`, each with a one-line summary and a link/id back to the source. Keep this section bounded — the digest loses value when it tries to surface everything.
+
+## Sampling vs full scan
+
+For low-volume bots (<200 submissions/window) the skill processes every submission. For higher volume, the skill samples notable items and counts via lightweight aggregation rather than LLM-classifying every row. Set the threshold at synthesis time based on the bot's observed volume — `query_submissions` with a recent window tells you roughly what to expect.
+
+## Idempotency
+
+Less critical here than for write-side catalysts — re-running the digest just overwrites or re-posts. But:
+
+- For Notion/Doc destinations: search-before-create on the page title to update an existing digest rather than spawn duplicates per run.
+- For Slack/email destinations: there's no idempotency — re-running re-sends. Default the synthesized skill to `--dry-run` mode that prints the digest to stdout, with `--send` required for live.
+
+## Pitfalls
+
+- **Stale notable threshold.** The threshold "high-priority complaints" depends on the form having a `priority` or equivalent field. If the form changes, the digest silently goes empty. Recommend the user re-run the catalyst flow when form fields they reference change.
+- **PII in digests.** Digests are often shared more broadly than the form submission was. Default to summarizing identity (count + role + general region) rather than dumping names/emails into the digest body. The user can override if their team needs identity.
+- **Empty windows.** A bot with no submissions in the window shouldn't produce a noisy "0 submissions" digest every week. Default the synthesized skill to skip-when-empty unless the user explicitly wants the heartbeat.
+
+## Skill behavior contract
+
+- **Inputs:** `deploymentId` (required), `windowStart` and `windowEnd` (optional ISO — defaults derived from cadence), `dryRun` (default true)
+- **Outputs:** the rendered digest (printed in dry-run mode, posted otherwise)
+- **Side effects (live mode):** one document/message create or update via destination MCP.