@rubytech/create-maxy-code 0.1.167 → 0.1.170

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-distil-profile.ts

@@ -0,0 +1,303 @@
+/**
+ * voice-distil-profile — walk the operator's `human-only` corpus and
+ * persist a `:VoiceProfile` style card.
+ *
+ * Cadence guard: re-runs on ≥20% corpus growth since last profile, OR
+ * ≥30 days since `generatedAt`. `force: true` overrides both.
+ *
+ * Body-text sampling caps at ~120k chars (rough proxy for tokens at
+ * 4 chars/token = 30k tokens) — well inside Haiku's 200k context window
+ * with headroom for the system prompt + tool schema.
+ */
+import neo4j from "neo4j-driver";
+import { getSession } from "../lib/neo4j.js";
+import { VOICE_CORPUS_WHERE } from "../lib/voice-corpus.js";
+
+// Task 424 — the Haiku style-card composition moved into the calling agent's
+// turn. The agent reads the corpus exemplars and feedback intents (this tool
+// returns them when called with `mode='sample'`), composes the style-card YAML,
+// then calls this tool again with `mode='write'` + `styleCardYaml` set.
+
+/**
+ * Coerce a neo4j cypher RETURN value to a plain JS number.
+ *
+ * Neo4j-driver represents INTs as `Integer` objects (high/low 32-bit
+ * pair to safely carry int64). `Number()` *usually* works via valueOf()
+ * but the safe path is `Integer#toNumber()`. Returns null when the
+ * value is null/undefined so cadence-guard arithmetic stays explicit
+ * about the "no prior profile" case.
+ */
+function toJsNumber(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "number") return value;
+  if (neo4j.isInt(value)) return (value as { toNumber: () => number }).toNumber();
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+const SAMPLE_CHAR_CAP = 120_000;
+const RE_RUN_GROWTH_FRACTION = 0.2;
+const RE_RUN_AGE_DAYS = 30;
+
+export interface VoiceDistilProfileParams {
+  accountId: string;
+  adminUserId: string;
+  force?: boolean;
+  /**
+   * Operation mode (Task 424):
+   *   - `'sample'` (default) — read the corpus + feedback intents and return
+   *     them. No write. The calling agent composes the style-card YAML
+   *     in-turn from the returned exemplars.
+   *   - `'write'` — persist the style card the agent produced. Requires
+   *     `styleCardYaml`.
+   */
+  mode?: "sample" | "write";
+  /** Required when `mode='write'`. The style-card YAML produced by the agent. */
+  styleCardYaml?: string;
+}
+
+export interface VoiceCorpusExemplar {
+  id: string;
+  label: string;
+  body: string;
+}
+
+export interface VoiceDistilProfileResult {
+  profileId: string | null;
+  corpusSize: number;
+  generatedAt: string | null;
+  feedbackEntries: number;
+  skipped: boolean;
+  skipReason?: "below-threshold" | "recent" | "empty-corpus" | "missing-style-card";
+  errorReason?: string;
+  /** Present when `mode='sample'`: corpus exemplars for the agent to read. */
+  exemplars?: VoiceCorpusExemplar[];
+  /** Present when `mode='sample'`: operator-edit intents to fold into the style card. */
+  feedbackIntents?: string[];
+}
+
+// The agent produces a YAML style card with at minimum these keys:
+//   sentenceLengthDistribution, register, favoured, avoided, taboos,
+//   openingPattern, closingPattern, exemplarSentences
+// Exemplar sentences should be quoted verbatim from the returned corpus.
+
+export async function voiceDistilProfile(
+  params: VoiceDistilProfileParams,
+): Promise<VoiceDistilProfileResult> {
+  const { accountId, adminUserId, force = false } = params;
+  if (!accountId || !adminUserId) {
+    throw new Error("voice-distil-profile: accountId and adminUserId required");
+  }
+  const session = getSession();
+  const now = new Date();
+  const nowIso = now.toISOString();
+
+  try {
+    // 1. Read existing profile (if any) for cadence-guard comparison.
+    const existing = await session.run(
+      `MATCH (a:AdminUser {accountId: $accountId, adminUserId: $adminUserId})
+       OPTIONAL MATCH (a)-[:HAS_VOICE_PROFILE]->(p:VoiceProfile)
+       RETURN elementId(p) AS profileId, p.corpusSize AS corpusSize,
+              p.generatedAt AS generatedAt`,
+      { accountId, adminUserId },
+    );
+    const existingRow = existing.records[0];
+    const prevProfileId = (existingRow?.get("profileId") as string | null) ?? null;
+    const prevCorpusSize = toJsNumber(existingRow?.get("corpusSize"));
+    const prevGeneratedAt = (existingRow?.get("generatedAt") as string | null) ?? null;
+
+    // 2. Count corpus. Filter matches human-only + human-led-agent-assisted
+    //    across the four primary content labels plus conversation-document
+    //    :Section chunks (chat archives — children of a :KnowledgeDocument
+    //    with `conversationIdentity` set). See VOICE_CORPUS_WHERE above.
+    const countResult = await session.run(
+      `MATCH (n)
+       WHERE ${VOICE_CORPUS_WHERE}
+       RETURN count(n) AS c`,
+      { accountId },
+    );
+    const corpusSize = toJsNumber(countResult.records[0]?.get("c")) ?? 0;
+
+    if (corpusSize === 0) {
+      process.stderr.write(
+        `[voice-distil] adminUser=${adminUserId} skip reason=empty-corpus\n`,
+      );
+      return {
+        profileId: prevProfileId,
+        corpusSize: 0,
+        generatedAt: prevGeneratedAt,
+        feedbackEntries: 0,
+        skipped: true,
+        skipReason: "empty-corpus",
+      };
+    }
+
+    // 3. Cadence guard.
+    if (!force && prevProfileId && prevCorpusSize !== null && prevGeneratedAt) {
+      const ageMs = now.getTime() - new Date(prevGeneratedAt).getTime();
+      const ageDays = ageMs / (24 * 60 * 60 * 1000);
+      // prevCorpusSize is non-null here (the guard above checks). When it's
+      // zero we treat growth as infinite — first real corpus always triggers
+      // a re-run.
+      const growth =
+        prevCorpusSize > 0
+          ? (corpusSize - prevCorpusSize) / prevCorpusSize
+          : 1;
+      const ageTrigger = ageDays >= RE_RUN_AGE_DAYS;
+      const growthTrigger = growth >= RE_RUN_GROWTH_FRACTION;
+      if (!ageTrigger && !growthTrigger) {
+        const reason = ageDays < 1 ? "recent" : "below-threshold";
+        process.stderr.write(
+          `[voice-distil] adminUser=${adminUserId} skip reason=${reason} corpusSize=${corpusSize} prevCorpus=${prevCorpusSize} ageDays=${ageDays.toFixed(1)}\n`,
+        );
+        return {
+          profileId: prevProfileId,
+          corpusSize,
+          generatedAt: prevGeneratedAt,
+          feedbackEntries: 0,
+          skipped: true,
+          skipReason: reason,
+        };
+      }
+    }
+
+    // 4. Sample corpus bodies up to the char cap. Pick recent first.
+    //    Timestamp coalesces include `firstMessageAt` for conversation-document
+    //    :Section chunks so chat archives sort by when the conversation
+    //    actually happened.
+    const sampled = await session.run(
+      `MATCH (n)
+       WHERE ${VOICE_CORPUS_WHERE}
+       WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
+       OPTIONAL MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
+       WHERE 'Section' IN labels(n) AND parent.conversationIdentity IS NOT NULL
+       RETURN elementId(n) AS id,
+              labels(n) AS labels,
+              coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '') AS body,
+              parent.conversationIdentity IS NOT NULL AS isConversationChunk,
+              ts
+       ORDER BY ts DESC NULLS LAST
+       LIMIT 500`,
+      { accountId },
+    );
+    const samples: { id: string; label: string; body: string }[] = [];
+    let charBudget = SAMPLE_CHAR_CAP;
+    for (const r of sampled.records) {
+      const body = (r.get("body") as string | null) ?? "";
+      const labels = (r.get("labels") as string[]) ?? [];
+      // Conversation-document sections carry `:Section` only after the Task
+      // 324 collapse; surface "Conversation" via the parent's
+      // `conversationIdentity` so the LLM exemplar header still says "this
+      // is chat" rather than the bare base label.
+      const isConversationChunk = Boolean(r.get("isConversationChunk"));
+      const label = isConversationChunk
+        ? "Conversation"
+        : (labels.find((l) =>
+            ["KnowledgeDocument", "Message", "SocialPost"].includes(l),
+          ) ?? labels[0] ?? "Unknown");
+      if (body.length === 0) continue;
+      const trimmed = body.length > charBudget ? body.slice(0, charBudget) : body;
+      samples.push({ id: r.get("id") as string, label, body: trimmed });
+      charBudget -= trimmed.length;
+      if (charBudget <= 0) break;
+    }
+
+    // 5. Pull feedback intents from existing :VoiceEdit nodes for this operator.
+    const feedback = await session.run(
+      `MATCH (a:AdminUser {accountId: $accountId, adminUserId: $adminUserId})
+       MATCH (e:VoiceEdit {adminUserId: $adminUserId, accountId: $accountId})
+       RETURN e.intent AS intent ORDER BY e.occurredAt DESC LIMIT 50`,
+      { accountId, adminUserId },
+    );
+    const feedbackIntents = feedback.records
+      .map((r) => r.get("intent") as string | null)
+      .filter((x): x is string => typeof x === "string" && x.length > 0);
+
+    // 6. Mode branch (Task 424).
+    //   - `sample` (default): return the exemplars + feedback intents to the
+    //     calling agent. The agent composes the YAML style card in its own
+    //     turn and re-invokes with mode='write'.
+    //   - `write`: persist the agent-produced style card.
+    const mode = params.mode ?? "sample";
+    if (mode === "sample") {
+      process.stderr.write(
+        `[voice-distil] adminUser=${adminUserId} mode=sample corpusSize=${corpusSize} ` +
+          `exemplars=${samples.length} feedbackEntries=${feedbackIntents.length}\n`,
+      );
+      return {
+        profileId: prevProfileId,
+        corpusSize,
+        generatedAt: prevGeneratedAt,
+        feedbackEntries: feedbackIntents.length,
+        skipped: true,
+        skipReason: "missing-style-card",
+        exemplars: samples,
+        feedbackIntents,
+      };
+    }
+
+    const styleCardYaml = (params.styleCardYaml ?? "").trim();
+    if (!styleCardYaml) {
+      throw new Error(
+        "voice-distil-profile: mode='write' requires styleCardYaml (the YAML you composed from the sample-mode response).",
+      );
+    }
+
+    // 7. Write the :VoiceProfile node + LEARNED_FROM edges to every sampled node.
+    //
+    //    The :AdminUser must already exist (onboarding/auth is the only
+    //    legitimate origin for :AdminUser). MATCH not MERGE: a typo in
+    //    adminUserId, an env mismatch, or a dropped credential surfaces
+    //    here as a typed error rather than silently minting an orphan
+    //    AdminUser that bypasses the platform's label-origin protection.
+    const writeResult = await session.run(
+      `MATCH (a:AdminUser {accountId: $accountId, adminUserId: $adminUserId})
+       MERGE (a)-[:HAS_VOICE_PROFILE]->(p:VoiceProfile {accountId: $accountId, adminUserId: $adminUserId})
+         ON CREATE SET p.createdAt = $now
+       SET p.styleCard = $styleCard,
+           p.generatedAt = $now,
+           p.corpusSize = $corpusSize,
+           p.feedbackEntries = $feedbackEntries,
+           p.updatedAt = $now
+       WITH p
+       UNWIND $sampleIds AS sid
+       MATCH (s) WHERE elementId(s) = sid
+       MERGE (p)-[:LEARNED_FROM]->(s)
+       RETURN elementId(p) AS profileId`,
+      {
+        accountId,
+        adminUserId,
+        styleCard: styleCardYaml,
+        now: nowIso,
+        corpusSize,
+        feedbackEntries: feedbackIntents.length,
+        sampleIds: samples.map((s) => s.id),
+      },
+    );
+    // MATCH-on-:AdminUser failure yields zero records. Throw the typed
+    // error here rather than returning a half-baked result.
+    if (writeResult.records.length === 0) {
+      throw new Error(
+        `voice-mirror: :AdminUser {accountId='${accountId}', adminUserId='${adminUserId}'} not found. Onboarding must promote the operator to :AdminUser before distillation.`,
+      );
+    }
+    const profileId = writeResult.records[0].get("profileId") as string;
+
+    process.stderr.write(
+      `[voice-distil] adminUser=${adminUserId} mode=write corpusSize=${corpusSize} generatedAt=${nowIso} feedbackEntries=${feedbackIntents.length}\n`,
+    );
+
+    return {
+      profileId,
+      corpusSize,
+      generatedAt: nowIso,
+      feedbackEntries: feedbackIntents.length,
+      skipped: false,
+    };
+  } finally {
+    await session.close();
+  }
+}

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-record-feedback.ts

@@ -0,0 +1,114 @@
+/**
+ * voice-record-feedback — capture an operator's edit on an agent draft
+ * as feedback for the next distillation.
+ *
+ * Task 424: the Haiku diff-intent summarisation moved into the calling
+ * agent's turn. The agent compares `originalText` to `editedText` itself
+ * and passes the resulting `intent` string as a required parameter. The
+ * tool now does the graph writes only.
+ *
+ * Side effects:
+ *   1. Write `(:VoiceEdit)-[:FEEDBACK_FOR]->(:VoiceProfile)` if the profile
+ *      exists; otherwise write the :VoiceEdit alone so the next distillation
+ *      back-fills the edge.
+ */
+import { randomUUID } from "node:crypto";
+import { getSession } from "../lib/neo4j.js";
+
+export interface VoiceRecordFeedbackParams {
+  accountId: string;
+  adminUserId: string;
+  originalText: string;
+  editedText: string;
+  /**
+   * One sentence describing what changed and what voice preference it reveals.
+   * The calling agent summarises this from `originalText` vs `editedText` in
+   * its own turn before invoking the tool (Task 424). Examples: "shorter and
+   * dropped the apology", "switched to first person", "removed corporate
+   * sign-off", "added a specific date".
+   */
+  intent: string;
+  context?: {
+    skill?: string;
+    brief?: string;
+  };
+}
+
+export interface VoiceRecordFeedbackResult {
+  editId: string;
+  intent: string;
+  occurredAt: string;
+  hadProfile: boolean;
+}
+
+export async function voiceRecordFeedback(
+  params: VoiceRecordFeedbackParams,
+): Promise<VoiceRecordFeedbackResult> {
+  const { accountId, adminUserId, originalText, editedText, intent: rawIntent, context } = params;
+  if (!accountId || !adminUserId) {
+    throw new Error("voice-record-feedback: accountId and adminUserId required");
+  }
+  if (!originalText || !editedText) {
+    throw new Error("voice-record-feedback: originalText and editedText required");
+  }
+  const intent = (rawIntent ?? "").trim();
+  if (!intent) {
+    throw new Error(
+      "voice-record-feedback: intent is required — summarise what the operator changed in-turn before calling this tool (Task 424).",
+    );
+  }
+
+  const editId = randomUUID();
+  const occurredAt = new Date().toISOString();
+  const cappedIntent = intent.slice(0, 500);
+
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (a:AdminUser {accountId: $accountId, adminUserId: $adminUserId})
+       CREATE (e:VoiceEdit {
+         editId: $editId,
+         accountId: $accountId,
+         adminUserId: $adminUserId,
+         originalText: $originalText,
+         editedText: $editedText,
+         intent: $intent,
+         occurredAt: $occurredAt,
+         skill: $skill,
+         brief: $brief
+       })
+       CREATE (a)-[:AUTHORED]->(e)
+       WITH e
+       OPTIONAL MATCH (:AdminUser {accountId: $accountId, adminUserId: $adminUserId})-[:HAS_VOICE_PROFILE]->(p:VoiceProfile)
+       FOREACH (_ IN CASE WHEN p IS NULL THEN [] ELSE [1] END |
+         MERGE (e)-[:FEEDBACK_FOR]->(p)
+       )
+       RETURN elementId(e) AS editId, (p IS NOT NULL) AS hadProfile`,
+      {
+        accountId,
+        adminUserId,
+        editId,
+        originalText,
+        editedText,
+        intent: cappedIntent,
+        occurredAt,
+        skill: context?.skill ?? null,
+        brief: context?.brief ?? null,
+      },
+    );
+    if (result.records.length === 0) {
+      throw new Error(
+        `voice-mirror: :AdminUser {accountId='${accountId}', adminUserId='${adminUserId}'} not found. Onboarding must promote the operator to :AdminUser before feedback can be recorded.`,
+      );
+    }
+    const hadProfile = result.records[0].get("hadProfile") === true;
+
+    process.stderr.write(
+      `[voice-record-feedback] adminUser=${adminUserId} intent="${cappedIntent.replace(/"/g, "'")}" diffBytes=${editedText.length - originalText.length}\n`,
+    );
+
+    return { editId, intent: cappedIntent, occurredAt, hadProfile };
+  } finally {
+    await session.close();
+  }
+}

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-retrieve-conditioning.ts

@@ -0,0 +1,145 @@
+/**
+ * voice-retrieve-conditioning — return the operator's style card plus K
+ * voice-matched exemplars for a drafting brief.
+ *
+ * Retrieval order (best to worst):
+ *   1. If brief.topic is provided AND keyword search on the human-only corpus
+ *      returns ≥K matches → use those (ordered by recency).
+ *   2. Otherwise, return the K most-recent human-only nodes.
+ *
+ * Embeddings are not used in v1: the corpus is small (single operator's
+ * personal writing — typically <500 docs), and recency-with-keyword-filter
+ * is both faster and more predictable than vector ANN at that scale.
+ * Vector-search is a Task 365-follow-up if the corpus grows beyond the
+ * 500-doc breakeven point.
+ *
+ * Graceful degradation: missing profile, empty corpus, and DB errors all
+ * return `{styleCard: null, exemplars: []}` rather than throwing — the
+ * calling drafting skill falls back to its existing default register.
+ */
+import { getSession } from "../lib/neo4j.js";
+import { VOICE_CORPUS_WHERE } from "../lib/voice-corpus.js";
+
+const DEFAULT_TOKEN_BUDGET_SHORT = 16_000;
+const DEFAULT_TOKEN_BUDGET_LONG = 96_000;
+const CHARS_PER_TOKEN = 4;
+
+export interface VoiceRetrieveConditioningParams {
+  accountId: string;
+  adminUserId: string;
+  brief: {
+    topic?: string;
+    format: "short" | "long";
+    register?: string;
+  };
+  tokenBudget?: number;
+}
+
+export interface VoiceExemplar {
+  nodeId: string;
+  label: string;
+  body: string;
+  source: string;
+}
+
+export interface VoiceRetrieveConditioningResult {
+  styleCard: string | null;
+  exemplars: VoiceExemplar[];
+}
+
+const EMPTY: VoiceRetrieveConditioningResult = { styleCard: null, exemplars: [] };
+
+export async function voiceRetrieveConditioning(
+  params: VoiceRetrieveConditioningParams,
+): Promise<VoiceRetrieveConditioningResult> {
+  const { accountId, adminUserId, brief } = params;
+  if (!accountId || !adminUserId) return EMPTY;
+
+  const k = brief.format === "long" ? 15 : 5;
+  const tokenBudget =
+    params.tokenBudget ??
+    (brief.format === "long" ? DEFAULT_TOKEN_BUDGET_LONG : DEFAULT_TOKEN_BUDGET_SHORT);
+  const charBudget = tokenBudget * CHARS_PER_TOKEN;
+
+  const session = getSession();
+  try {
+    // 1. Style card.
+    const profile = await session.run(
+      `MATCH (a:AdminUser {accountId: $accountId, adminUserId: $adminUserId})
+       OPTIONAL MATCH (a)-[:HAS_VOICE_PROFILE]->(p:VoiceProfile)
+       RETURN p.styleCard AS styleCard`,
+      { accountId, adminUserId },
+    );
+    const styleCard = (profile.records[0]?.get("styleCard") as string | null) ?? null;
+
+    // 2. Exemplars. Keyword-aware filter when brief.topic is set.
+    const topic = (brief.topic ?? "").trim();
+    const usesTopic = topic.length > 0;
+
+    const cypher = usesTopic
+      ? `MATCH (n)
+         WHERE ${VOICE_CORPUS_WHERE}
+           AND toLower(coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '')) CONTAINS toLower($topic)
+         WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
+         RETURN elementId(n) AS id,
+                labels(n) AS labels,
+                coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '') AS body,
+                coalesce(n.subject, n.title, n.name, '') AS source,
+                ts
+         ORDER BY ts DESC NULLS LAST
+         LIMIT $k`
+      : `MATCH (n)
+         WHERE ${VOICE_CORPUS_WHERE}
+         WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
+         RETURN elementId(n) AS id,
+                labels(n) AS labels,
+                coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '') AS body,
+                coalesce(n.subject, n.title, n.name, '') AS source,
+                ts
+         ORDER BY ts DESC NULLS LAST
+         LIMIT $k`;
+
+    const result = await session.run(cypher, {
+      accountId,
+      topic,
+      k,
+    });
+
+    let charsUsed = 0;
+    const exemplars: VoiceExemplar[] = [];
+    for (const r of result.records) {
+      const body = (r.get("body") as string | null) ?? "";
+      if (body.length === 0) continue;
+      const labels = (r.get("labels") as string[]) ?? [];
+      const label =
+        labels.find((l) =>
+          ["KnowledgeDocument", "Message", "SocialPost", "Conversation"].includes(l),
+        ) ?? labels[0] ?? "Unknown";
+      const remaining = charBudget - charsUsed;
+      if (remaining <= 0) break;
+      const truncated = body.length > remaining ? body.slice(0, remaining) : body;
+      exemplars.push({
+        nodeId: r.get("id") as string,
+        label,
+        body: truncated,
+        source: ((r.get("source") as string | null) ?? "").slice(0, 200),
+      });
+      charsUsed += truncated.length;
+    }
+
+    process.stderr.write(
+      `[voice-retrieve] task=${brief.topic ?? brief.format} styleCardBytes=${
+        styleCard?.length ?? 0
+      } exemplarCount=${exemplars.length} tokenBudget=${tokenBudget}\n`,
+    );
+
+    return { styleCard, exemplars };
+  } catch (err) {
+    process.stderr.write(
+      `[voice-retrieve] error: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return EMPTY;
+  } finally {
+    await session.close();
+  }
+}

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-tag-content.ts

@@ -0,0 +1,117 @@
+/**
+ * voice-tag-content — set `authorshipMode` on one or many content nodes.
+ *
+ * The tool routes through neo4j directly with an account-scoped MERGE so
+ * the operator can only mutate their own nodes. We do not go through
+ * `memory-update` because that tool re-embeds and re-validates on every
+ * call — overkill for a single-property authorship stamp.
+ */
+import { getSession } from "../lib/neo4j.js";
+import { TAGGABLE_PRIMARY_LABELS } from "../lib/voice-corpus.js";
+
+export type AuthorshipMode =
+  | "human-only"
+  | "human-led-agent-assisted"
+  | "agent-led-human-reviewed"
+  | "agent-only"
+  | "unknown";
+
+export const AUTHORSHIP_MODES: ReadonlySet<AuthorshipMode> = new Set([
+  "human-only",
+  "human-led-agent-assisted",
+  "agent-led-human-reviewed",
+  "agent-only",
+  "unknown",
+]);
+
+export interface VoiceTagContentParams {
+  nodeIds: string[];
+  mode: AuthorshipMode;
+  accountId: string;
+}
+
+export interface VoiceTagContentResult {
+  updated: number;
+  skipped: number;
+  skippedReasons: Record<string, number>;
+}
+
+export async function voiceTagContent(
+  params: VoiceTagContentParams,
+): Promise<VoiceTagContentResult> {
+  const { nodeIds, mode, accountId } = params;
+
+  if (!AUTHORSHIP_MODES.has(mode)) {
+    throw new Error(
+      `voice-tag-content: invalid authorshipMode '${mode}'. Valid values: ${[
+        ...AUTHORSHIP_MODES,
+      ].join(", ")}`,
+    );
+  }
+  if (!accountId) {
+    throw new Error("voice-tag-content: accountId is required");
+  }
+  if (!Array.isArray(nodeIds) || nodeIds.length === 0) {
+    return { updated: 0, skipped: 0, skippedReasons: {} };
+  }
+
+  const session = getSession();
+  const now = new Date().toISOString();
+  const skippedReasons: Record<string, number> = {};
+  let updated = 0;
+
+  try {
+    // Bulk update in batches of 50 to keep transaction latency bounded.
+    const BATCH = 50;
+    for (let i = 0; i < nodeIds.length; i += BATCH) {
+      const batch = nodeIds.slice(i, i + BATCH);
+      const result = await session.run(
+        // Tag any of the four primary content labels, or a conversation-
+        // document :Section chunk (parent :KnowledgeDocument carries
+        // `conversationIdentity`). The EXISTS sub-pattern guards against
+        // accidentally tagging document-path :Section rows AND parent
+        // `:Conversation` / `:AdminConversation` nodes (which are not
+        // body-bearing content).
+        `UNWIND $ids AS id
+         MATCH (n) WHERE elementId(n) = id AND n.accountId = $accountId
+         WITH n
+         WHERE any(lbl IN labels(n) WHERE lbl IN $primaryLabels)
+            OR ('Section' IN labels(n) AND EXISTS {
+                 MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
+                 WHERE parent.conversationIdentity IS NOT NULL
+               })
+         SET n.authorshipMode = $mode,
+             n.authorshipTaggedAt = $now
+         RETURN elementId(n) AS id`,
+        {
+          ids: batch,
+          accountId,
+          mode,
+          now,
+          primaryLabels: [...TAGGABLE_PRIMARY_LABELS],
+        },
+      );
+      const matched = new Set(result.records.map((r) => r.get("id") as string));
+      updated += matched.size;
+      for (const id of batch) {
+        if (matched.has(id)) continue;
+        const reason = "not-found-or-not-content-label";
+        skippedReasons[reason] = (skippedReasons[reason] ?? 0) + 1;
+      }
+    }
+  } finally {
+    await session.close();
+  }
+
+  process.stderr.write(
+    `[voice-tag] mode=${mode} accountId=${accountId} updated=${updated} skipped=${
+      nodeIds.length - updated
+    }\n`,
+  );
+
+  return {
+    updated,
+    skipped: nodeIds.length - updated,
+    skippedReasons,
+  };
+}

package/payload/premium-plugins/writer-craft/mcp/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../platform/tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}