@neuctra/notlix-mcp 1.0.0 → 2.0.1

package/src/server.js

@@ -1,98 +1,185 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
-import { InboxError } from "./inbox.js";
+import { AuthixError } from "./authix.js";
+import {
+  ContentError,
+  DIAGRAM_SHAPE_IDS,
+  DOCUMENT_CATEGORIES,
+  NOTE_CATEGORIES,
+  TYPES,
+  TYPE_LABELS,
+  checkSize,
+  editRecord,
+  newRecord,
+  readableContent,
+  searchableText,
+} from "./content.js";
 
 // The Notlix MCP tools. Used by the local stdio command (bin/notlix-mcp.js) and
-// by the remote Worker (neuctra-notlix-mcp-http). Items are encrypted here,
-// before they leave, so the Notlix server never sees the text. The write token
-// can add items and queue text edits for items the user turned AI editing on
-// for. It can't read anything.
-
-export const VERSION = "1.0.0";
-
-const TOOL_DESCRIPTION = `Save something to the user's Neuctra Notlix account so it isn't lost when this chat ends.
-
-Use this when the user asks you to save, remember or store something in Notlix. Write a clear title and a self-contained document that makes sense without this chat. Use type "knowledge" (markdown) for reference material, decisions and project context, type "document" (markdown) for finished, formatted writing the user will read, edit or export, such as reports, proposals and letters, type "presentation" for slide decks, and type "note" (plain text) for quick notes.
-
-For a presentation, write markdown with --- on its own line between slides. Start each slide with a # heading, follow it with short - bullets, and add a line starting with Notes: at the end of a slide for speaker notes. Keep each slide to about six short bullets. Images are not supported.
-
-Never save passwords, API keys, tokens or other secrets: Knowledge, Documents, Presentations and Notes are not encrypted in the account. This tool can only add new items. To change an item that already exists, use edit_in_notlix with the reference the user gives you. Nothing here can read or search Notlix.`;
-
-const EDIT_DESCRIPTION = `Edit an item in the user's Neuctra Notlix account that the user chose to share with you: fix typos, reword, or add more content at the end, such as new research.
-
-You can only edit an item the user gave you a Notlix reference for. It looks like ntx-doc-3f9a1c2b7d4e5f60, and the user copies it from Notlix together with the item's current text. Without a reference, ask the user to open the item in Notlix, choose "Edit with AI" and paste what it copies. Never make up a reference: edits with any other reference are refused.
-
-- edits: each find is copied exactly from the item's current text and replaced with replace. Every occurrence is replaced, so include enough surrounding words to match only the place you mean. For documents, copy the words as they read, without markdown symbols such as ** or #, and keep each find inside one paragraph and one style (a find can't cross bold or a link). For presentations and diagrams, keep each find inside one bullet, table cell, notes field, shape or connector label. replace is plain text.
-- append: new content added at the end. Markdown for knowledge (ntx-kn) and documents (ntx-doc), plain text for notes (ntx-note), and for presentations (ntx-ppt) new slides written as markdown with --- between slides, a # title and - bullets. Diagrams (ntx-dgm) can't take appended content.
-
-You can't delete items, rename them, or edit the encrypted vault. Edits are applied the next time the user opens Notlix. If a find doesn't match, that edit is skipped and the user is told, so you won't see an error here.`;
-
-// Matches newAiEditRef in the client. The prefix says what kind of item it is.
-const EDIT_REF = /^ntx-(kn|doc|ppt|dgm|note)-[0-9a-f]{16}$/;
-
-const DESTINATIONS = {
-  knowledge: "Knowledge",
-  document: "Documents",
-  presentation: "Presentations",
-  note: "Notes",
-};
-
-/** Sends an item. Returns a tool error result when it couldn't, or null. */
-async function send(inbox, item) {
+// the remote Worker (neuctra-notlix-mcp-http). Every call acts as the signed-in
+// user through Authix. Nothing can be deleted, and the vault is out of reach.
+
+export const VERSION = "2.0.0";
+
+const type = z.enum(TYPES).describe('"note", "knowledge", "document", "presentation" or "diagram".');
+const id = z.string().trim().min(1).max(100).describe("The item's id, from list_notlix_items.");
+const title = z.string().trim().min(1).max(200);
+
+const diagramNode = z.object({
+  id: z.string().trim().min(1).max(60).describe("Your own key for this node, used by connectors."),
+  text: z.string().max(500).describe("The text in the box."),
+  shape: z.enum(DIAGRAM_SHAPE_IDS).optional().describe(`Default "rect". Flowchart: rect, terminator, diamond, parallelogram, documentShape, subroutine, hexagon. Others: roundRect, ellipse, triangle, note, text, cylinder (database), cloud, container.`),
+});
+const diagramEdge = z.object({
+  from: z.string().trim().min(1).max(60).describe("A node key, or an existing node id when editing."),
+  to: z.string().trim().min(1).max(60),
+  label: z.string().max(200).optional(),
+});
+const diagramInput = z
+  .object({
+    nodes: z.array(diagramNode).max(150).default([]),
+    edges: z.array(diagramEdge).max(300).default([]),
+  })
+  .describe("Diagrams only: boxes and the connectors between them. They're laid out top to bottom for you.");
+
+const FORMATS = `Formats by type:
+- note: plain text.
+- knowledge: markdown. [[Title]] links to another Knowledge item.
+- document: markdown, turned into a formatted document. Raw HTML is shown as text.
+- presentation: markdown with --- on its own line between slides. Start each slide with a # title, then short - bullets (about six per slide), and end a slide with a line starting Notes: for speaker notes. Images aren't supported.
+- diagram: no content; use diagram.nodes and diagram.edges.`;
+
+const ok = (text) => ({ content: [{ type: "text", text }] });
+const refuse = (text) => ({ isError: true, content: [{ type: "text", text }] });
+
+/** Turns expected failures into tool errors the AI can pass on. */
+const guarded = (handler) => async (args) => {
   try {
-    await inbox.add(item);
-    return null;
+    return await handler(args);
   } catch (err) {
-    if (!(err instanceof InboxError)) throw err;
-    return { isError: true, content: [{ type: "text", text: err.message }] };
+    if (err instanceof AuthixError || err instanceof ContentError) return refuse(err.message);
+    throw err;
   }
-}
+};
+
+const day = (value) => (value ? String(value).slice(0, 10) : "unknown");
+const shorten = (text, max) => (text.length > max ? `${text.slice(0, max).trimEnd()}…` : text);
 
-/** An MCP server with save_to_notlix and edit_in_notlix. `inbox` comes from createInboxClient. */
-export function createNotlixServer(inbox) {
+/** An MCP server for one signed-in user. `authix` is an AuthixClient with a session. */
+export function createNotlixServer(authix) {
   const server = new McpServer({ name: "neuctra-notlix", version: VERSION });
 
+  async function findItem(itemType, itemId) {
+    const record = (await authix.list(itemType)).find((item) => item.id === itemId);
+    if (!record) {
+      throw new ContentError(`No ${itemType} with id ${itemId} in ${TYPE_LABELS[itemType]}. Use list_notlix_items to find it.`);
+    }
+    return record;
+  }
+
   server.registerTool(
-    "save_to_notlix",
+    "list_notlix_items",
     {
-      title: "Save to Notlix",
-      description: TOOL_DESCRIPTION,
+      title: "List Notlix items",
+      description:
+        "List or search the user's Notes, Knowledge, Documents, Presentations and Diagrams in Neuctra Notlix. Returns ids, titles and dates, newest first. Use read_notlix_item to read one. The vault (passwords, secure notes, API keys, files) isn't available.",
       inputSchema: {
-        title: z.string().trim().min(1).max(200).describe("Short, descriptive title."),
-        content: z.string().min(1).max(200_000).describe("The full text to save."),
-        type: z
-          .enum(["knowledge", "document", "presentation", "note"])
-          .default("knowledge")
-          .describe('"knowledge" for markdown reference material, "document" for formatted markdown writing, "presentation" for slides written as markdown split by ---, "note" for plain text.'),
+        type: type.optional().describe("Only this type. Leave out for all five."),
+        query: z.string().trim().max(200).optional().describe("Words that must all appear in the title or text."),
+        limit: z.number().int().min(1).max(200).default(50),
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      annotations: { readOnlyHint: true, openWorldHint: false },
     },
-    async ({ title, content, type }) => {
-      const failed = await send(inbox, { title, content, type });
-      if (failed) return failed;
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Saved "${title}". It will appear in ${DESTINATIONS[type]} the next time the user opens Notlix.`,
-          },
-        ],
-      };
+    guarded(async ({ type: only, query, limit }) => {
+      const types = only ? [only] : TYPES;
+      const words = (query || "").toLowerCase().split(/\s+/).filter(Boolean);
+      const found = [];
+      for (const itemType of types) {
+        for (const record of await authix.list(itemType)) {
+          const text = searchableText(itemType, record);
+          if (words.every((word) => text.includes(word))) found.push({ itemType, record });
+        }
+      }
+      found.sort(
+        (a, b) =>
+          Number(Boolean(b.record.isPinned)) - Number(Boolean(a.record.isPinned)) ||
+          String(b.record.updatedAt || "").localeCompare(String(a.record.updatedAt || "")),
+      );
+
+      if (found.length === 0) return ok(query ? `Nothing matches "${query}".` : "No items yet.");
+      const lines = found.slice(0, limit).map(({ itemType, record }) => {
+        const pin = record.isPinned ? " (pinned)" : "";
+        return `- ${itemType} ${record.id}: "${record.title || "Untitled"}"${pin}, updated ${day(record.updatedAt)}`;
+      });
+      const more = found.length > limit ? `\n${found.length - limit} more. Narrow it with type or query.` : "";
+      return ok(`${found.length} ${found.length === 1 ? "item" : "items"}:\n${lines.join("\n")}${more}`);
+    }),
+  );
+
+  server.registerTool(
+    "read_notlix_item",
+    {
+      title: "Read a Notlix item",
+      description:
+        "Read one item from Neuctra Notlix in full. Documents and presentations are shown as markdown-like text: # marks headings and slide titles, - marks bullets, and --- separates slides. Diagrams list their nodes and connectors with ids.",
+      inputSchema: { type, id },
+      annotations: { readOnlyHint: true, openWorldHint: false },
     },
+    guarded(async ({ type: itemType, id: itemId }) => {
+      const record = await findItem(itemType, itemId);
+      const meta = [`Type: ${itemType}`, `Id: ${record.id}`, `Updated: ${day(record.updatedAt)}`];
+      if (record.category) meta.push(`Category: ${record.category}`);
+      return ok(`# ${record.title || "Untitled"}\n${meta.join(" · ")}\n\n${readableContent(itemType, record)}`);
+    }),
   );
 
   server.registerTool(
-    "edit_in_notlix",
+    "create_notlix_item",
     {
-      title: "Edit in Notlix",
-      description: EDIT_DESCRIPTION,
+      title: "Create a Notlix item",
+      description: `Create a new Note, Knowledge item, Document, Presentation or Diagram in the user's Neuctra Notlix account. Write a clear title and content that makes sense on its own, without this chat.
+
+${FORMATS}
+
+Never save passwords, API keys or other secrets: these items aren't encrypted. Secrets belong in the Notlix vault, which this can't reach.`,
       inputSchema: {
-        ref: z
+        type,
+        title: title.describe("Short, descriptive title."),
+        content: z.string().max(200_000).default("").describe("The body, in the format for its type."),
+        category: z
           .string()
-          .trim()
-          .regex(EDIT_REF, "Not a Notlix reference. Ask the user to copy one with Edit with AI in Notlix.")
-          .describe("The Notlix reference the user gave you, such as ntx-doc-3f9a1c2b7d4e5f60."),
+          .optional()
+          .describe(`Notes: ${NOTE_CATEGORIES.join(", ")}. Documents: ${DOCUMENT_CATEGORIES.join(", ")}. Default "general".`),
+        diagram: diagramInput.optional(),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    guarded(async (args) => {
+      if (args.type !== "diagram" && !args.content.trim()) return refuse("Give some content to save.");
+      const record = newRecord(args.type, args);
+      checkSize(record);
+      const saved = await authix.add(args.type, record);
+      const savedId = saved?.id ? ` Its id is ${saved.id}.` : "";
+      return ok(`Created "${record.title}" in ${TYPE_LABELS[args.type]}.${savedId}`);
+    }),
+  );
+
+  server.registerTool(
+    "edit_notlix_item",
+    {
+      title: "Edit a Notlix item",
+      description: `Change an existing item in Neuctra Notlix: rename it, fix or reword text, add content at the end, or add to a diagram. Read it first with read_notlix_item. Items can't be deleted.
+
+- edits: each find is copied exactly from the item's current text and replaced with replace. Every occurrence is replaced, so include enough words to match only the place you mean. For documents, copy words as they read, without # or - markers, and keep each find inside one paragraph and one style (a find can't cross bold or a link). For presentations, keep each find inside one bullet, table cell or notes field; for diagrams, inside one node or connector label. replace is plain text.
+- append: new content at the end, in the format for the type (see create_notlix_item). Presentations get new slides. Diagrams can't take append; use diagram instead.
+- diagram: new nodes and connectors to add. Connectors can name existing node ids from read_notlix_item.
+
+Finds that don't match are listed in the answer, and nothing else is guessed.`,
+      inputSchema: {
+        type,
+        id,
+        title: title.optional().describe("A new title."),
         edits: z
           .array(
             z.object({
@@ -101,40 +188,41 @@ export function createNotlixServer(inbox) {
             }),
           )
           .max(50)
-          .optional()
-          .describe("Find-and-replace changes, such as typo fixes or rewording."),
+          .optional(),
         append: z.string().max(200_000).optional().describe("New content to add at the end."),
+        diagram: diagramInput.optional(),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     },
-    async ({ ref, edits = [], append = "" }) => {
-      const refuse = (text) => ({ isError: true, content: [{ type: "text", text }] });
-
-      if (edits.length === 0 && !append.trim()) {
-        return refuse("Nothing to change. Give at least one edit or some text to append.");
-      }
-      if (ref.startsWith("ntx-dgm-") && append.trim()) {
-        return refuse("Diagrams can't take appended content. Use edits to change the text in shapes and connector labels.");
+    guarded(async ({ type: itemType, id: itemId, title: newTitle, edits = [], append = "", diagram }) => {
+      const addsToDiagram = Boolean(diagram?.nodes?.length || diagram?.edges?.length);
+      if (!newTitle && edits.length === 0 && !append.trim() && !addsToDiagram) {
+        return refuse("Nothing to change. Give a title, edits, append or diagram.");
       }
       if (edits.some(({ find, replace }) => find === replace)) {
         return refuse("An edit's find and replace are the same, so it wouldn't change anything.");
       }
+      if (diagram && itemType !== "diagram") return refuse("diagram only works on diagrams.");
 
-      const failed = await send(inbox, { action: "edit", ref, edits, append });
-      if (failed) return failed;
-
-      const parts = [];
-      if (edits.length) parts.push(`${edits.length} ${edits.length === 1 ? "edit" : "edits"}`);
-      if (append.trim()) parts.push("new content at the end");
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Queued ${parts.join(" and ")} for ${ref}. They will be applied the next time the user opens Notlix, if that item still allows AI edits. Any edit whose text doesn't match is skipped, and the user is told.`,
-          },
-        ],
-      };
-    },
+      const record = await findItem(itemType, itemId);
+      const { changes, missed } = editRecord(itemType, record, { title: newTitle, edits, append, diagram });
+      if (missed.length === edits.length && edits.length > 0 && !newTitle && !append.trim() && !addsToDiagram) {
+        return refuse(`None of the finds matched the text of "${record.title}": ${missed.map((find) => `"${shorten(find, 60)}"`).join(", ")}. Read the item again and copy the text exactly.`);
+      }
+
+      checkSize({ ...record, ...changes });
+      await authix.update(record.id, changes);
+
+      const done = [];
+      if (newTitle) done.push("renamed it");
+      if (edits.length > missed.length) done.push(`applied ${edits.length - missed.length} of ${edits.length} ${edits.length === 1 ? "edit" : "edits"}`);
+      if (append.trim()) done.push("added content at the end");
+      if (addsToDiagram) done.push(`added ${diagram.nodes?.length || 0} nodes and ${diagram.edges?.length || 0} connectors`);
+      const skipped = missed.length
+        ? ` These finds didn't match and were skipped: ${missed.map((find) => `"${shorten(find, 60)}"`).join(", ")}.`
+        : "";
+      return ok(`Updated "${changes.title || record.title}": ${done.join(", ")}.${skipped}`);
+    }),
   );
 
   return server;

package/src/shared/aiEdits.js

@@ -0,0 +1,142 @@
+// Copied from neuctra-notlix-client/lib/workspace/aiEdits.js by scripts/sync.mjs. Don't edit here.
+
+// Applies text edits an AI sent through edit_in_notlix. The AI can't read the
+// account, so each edit names exact text, and edits whose text isn't there are
+// reported back to the user instead of guessed at.
+//
+// An AI can only edit an item the user turned AI editing on for. That gives the
+// item a random reference, which the user hands to the AI. Edits carrying any
+// other reference are refused, so an AI can't reach the user's other items.
+//
+// Every edit function returns the changed fields and the finds that didn't match.
+
+import { markdownToSlides, normalizeSlides } from "./presentations.js";
+
+// The prefix names the type, so the reference is the only thing the AI needs.
+const REF_PREFIXES = {
+  knowledge: "kn",
+  document: "doc",
+  presentation: "ppt",
+  diagram: "dgm",
+  note: "note",
+};
+
+export const AI_EDIT_REF_PATTERN = /^ntx-(kn|doc|ppt|dgm|note)-[0-9a-f]{16}$/;
+
+export function newAiEditRef(type) {
+  const bytes = crypto.getRandomValues(new Uint8Array(8));
+  return `ntx-${REF_PREFIXES[type]}-${[...bytes].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+export function typeOfAiEditRef(ref) {
+  const match = AI_EDIT_REF_PATTERN.exec(String(ref));
+  return match ? Object.keys(REF_PREFIXES).find((type) => REF_PREFIXES[type] === match[1]) : null;
+}
+
+const replaceAll = (text, find, replace) => text.split(find).join(replace);
+
+/**
+ * Runs each edit over a list of text fields. `fields` holds { get, set } pairs,
+ * so the same logic works for strings, note blocks, slide elements and shapes.
+ */
+function applyToFields(fields, edits) {
+  const missed = [];
+  for (const { find, replace } of edits) {
+    let found = false;
+    for (const field of fields) {
+      const text = field.get();
+      if (typeof text === "string" && text.includes(find)) {
+        field.set(replaceAll(text, find, replace));
+        found = true;
+      }
+    }
+    if (!found) missed.push(find);
+  }
+  return missed;
+}
+
+const joinBlocks = (before, after) => (before.trim() ? `${before.trimEnd()}\n\n${after}` : after);
+
+export function editKnowledge(record, { edits, append }) {
+  const doc = { content: typeof record.content === "string" ? record.content : "" };
+  const missed = applyToFields([{ get: () => doc.content, set: (v) => { doc.content = v; } }], edits);
+  if (append.trim()) doc.content = joinBlocks(doc.content, append.trim());
+  return { changes: { content: doc.content }, missed };
+}
+
+export function editNote(record, { edits, append }) {
+  let blocks;
+  if (Array.isArray(record.content)) blocks = record.content.map((block) => ({ ...block }));
+  else if (typeof record.content === "string" && record.content.trim()) {
+    blocks = [{ id: `blk_${Date.now()}`, type: "text", content: record.content }];
+  } else blocks = [];
+
+  const missed = applyToFields(
+    blocks.map((block) => ({ get: () => block.content, set: (v) => { block.content = v; } })),
+    edits,
+  );
+
+  if (append.trim()) {
+    const last = [...blocks].reverse().find((block) => typeof block.content === "string");
+    if (last) last.content = joinBlocks(last.content, append.trim());
+    else blocks.push({ id: `blk_${Date.now()}`, type: "text", content: append.trim() });
+  }
+  return { changes: { content: blocks }, missed };
+}
+
+export function editPresentation(record, { edits, append }) {
+  const slides = normalizeSlides(structuredClone(record.slides));
+  const fields = [];
+  for (const slide of slides) {
+    fields.push({ get: () => slide.notes, set: (v) => { slide.notes = v; } });
+    for (const element of slide.elements) {
+      if (typeof element.text === "string") {
+        fields.push({ get: () => element.text, set: (v) => { element.text = v; } });
+      }
+      for (const row of element.rows ?? []) {
+        row.forEach((_, i) => fields.push({ get: () => row[i], set: (v) => { row[i] = v; } }));
+      }
+    }
+  }
+
+  const missed = applyToFields(fields, edits);
+  if (append.trim()) slides.push(...markdownToSlides(append));
+  return { changes: { slides }, missed };
+}
+
+export function editDiagram(record, { edits }) {
+  const nodes = (Array.isArray(record.nodes) ? record.nodes : []).map((node) => ({ ...node }));
+  const edges = (Array.isArray(record.edges) ? record.edges : []).map((edge) => ({ ...edge }));
+  const missed = applyToFields(
+    [
+      ...nodes.map((node) => ({ get: () => node.text, set: (v) => { node.text = v; } })),
+      ...edges.map((edge) => ({ get: () => edge.label, set: (v) => { edge.label = v; } })),
+    ],
+    edits,
+  );
+  return { changes: { nodes, edges }, missed };
+}
+
+/**
+ * Documents are HTML. Edits only touch text nodes, so the AI's text can't add
+ * markup, and a find that crosses formatting such as bold doesn't match.
+ * `toHtml` turns appended markdown into clean HTML (markdownToDocument).
+ */
+export async function editDocument(record, { edits, append }, toHtml) {
+  const { body } = new DOMParser().parseFromString(String(record.html || ""), "text/html");
+
+  const textNodes = [];
+  const walker = body.ownerDocument.createTreeWalker(body, NodeFilter.SHOW_TEXT);
+  while (walker.nextNode()) textNodes.push(walker.currentNode);
+
+  const missed = applyToFields(
+    textNodes.map((node) => ({ get: () => node.nodeValue, set: (v) => { node.nodeValue = v; } })),
+    edits,
+  );
+
+  let html = body.innerHTML;
+  if (append.trim()) html += (await toHtml(append)).html;
+
+  const { body: finalBody } = new DOMParser().parseFromString(html, "text/html");
+  return { changes: { html, text: finalBody.textContent }, missed };
+}

package/src/shared/contextPacks.js

@@ -0,0 +1,133 @@
+// Copied from neuctra-notlix-client/lib/workspace/contextPacks.js by scripts/sync.mjs. Don't edit here.
+
+// AI Briefs (stored as `contextpack`): saved, reusable bundles of notes and knowledge for any AI.
+//
+// A pack stores references (source ids), not copies, so compiling one always
+// uses the newest version of each document. Everything here is pure, so it
+// runs the same in the app, in tests, and when syncing to the extension.
+
+// Rough rule of thumb across models: about 4 characters per token.
+const CHARS_PER_TOKEN = 4;
+
+export const CONTEXT_LIMITS = [
+  { max: 8000, label: "Fits any AI chat", tone: "success" },
+  { max: 32000, label: "Fits most AI chats", tone: "info" },
+  { max: 128000, label: "Large. Some AI chats may cut it off", tone: "warning" },
+  { max: Infinity, label: "Too large for most AI chats. Remove some sources", tone: "destructive" },
+];
+
+export function estimateTokens(text) {
+  return Math.ceil((text || "").length / CHARS_PER_TOKEN);
+}
+
+export function contextFit(tokens) {
+  return CONTEXT_LIMITS.find((limit) => tokens <= limit.max);
+}
+
+/** Flattens a Notes record's block content into markdown. */
+export function noteBody(note) {
+  const blocks = Array.isArray(note?.content) ? note.content : [];
+  const body = blocks
+    .map((block) => (typeof block === "string" ? block : block?.content || ""))
+    .filter(Boolean)
+    .join("\n\n");
+  return body || (typeof note?.content === "string" ? note.content : "") || "";
+}
+
+/** Names used as {{blanks}}, in first-seen order. */
+export function extractVariables(text) {
+  const names = [];
+  const pattern = /\{\{\s*([\w][\w -]*?)\s*\}\}/g;
+  let match;
+  while ((match = pattern.exec(text || ""))) {
+    if (!names.includes(match[1])) names.push(match[1]);
+  }
+  return names;
+}
+
+/** Fills {{blanks}}. A blank with no value is left visible, never erased. */
+export function fillVariables(text, values = {}) {
+  return (text || "").replace(/\{\{\s*([\w][\w -]*?)\s*\}\}/g, (whole, name) => {
+    const value = values[name];
+    return typeof value === "string" && value.trim() ? value.trim() : whole;
+  });
+}
+
+const PROFILE_FIELDS = [
+  ["name", "Name"],
+  ["role", "Role"],
+  ["about", "About me"],
+  ["tone", "Preferred tone"],
+  ["language", "Language"],
+  ["rules", "Always follow"],
+];
+
+export function profileToMarkdown(profile) {
+  const lines = PROFILE_FIELDS.filter(([key]) => profile?.[key]?.trim()).map(
+    ([key, label]) => `- **${label}:** ${profile[key].trim()}`,
+  );
+  return lines.length ? `## About me\n\n${lines.join("\n")}` : "";
+}
+
+/** Resolves a pack's source references against the loaded documents. */
+export function resolveSources(pack, library) {
+  const byKey = new Map(library.map((doc) => [`${doc.type}:${doc.id}`, doc]));
+  const docs = [];
+  let missing = 0;
+  (pack?.sources || []).forEach((source) => {
+    const doc = byKey.get(`${source.type}:${source.id}`);
+    if (doc) docs.push(doc);
+    else missing += 1;
+  });
+  return { docs, missing };
+}
+
+/** Compiles a pack into one markdown document, ready for any AI. */
+export function compilePack(pack, { library = [], profile = null, values = {} } = {}) {
+  const { docs, missing } = resolveSources(pack, library);
+  const parts = [`# ${pack?.name || "Context"}`];
+
+  const profileText = pack?.includeProfile ? profileToMarkdown(profile) : "";
+  if (profileText) parts.push(profileText);
+  if (pack?.instructions?.trim()) parts.push(`## Instructions\n\n${pack.instructions.trim()}`);
+  docs.forEach((doc) => parts.push(`## ${doc.title || "Untitled"}\n\n${doc.body || ""}`.trimEnd()));
+
+  const template = parts.join("\n\n---\n\n");
+  const markdown = fillVariables(template, values);
+  return { template, markdown, missing, variables: extractVariables(template) };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Secret check                                                               */
+/* -------------------------------------------------------------------------- */
+
+const SECRET_PATTERNS = [
+  ["AWS access key", /\bAKIA[0-9A-Z]{16}\b/g],
+  ["GitHub token", /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g],
+  ["GitHub token", /\bgithub_pat_[A-Za-z0-9_]{22,}\b/g],
+  ["Slack token", /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g],
+  ["Google API key", /\bAIza[0-9A-Za-z_-]{35}\b/g],
+  ["Stripe key", /\b[sr]k_live_[0-9A-Za-z]{16,}\b/g],
+  ["Authix secret key", /\b(?:sk|ak)_live_[0-9a-f]{8}_[0-9a-f]{32,}\b/g],
+  ["AI provider key", /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}\b/g],
+  ["Private key", /-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----/g],
+  ["JSON web token", /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g],
+  ["Database URL with password", /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s:/@]+@[^\s/]+/gi],
+  ["Password or secret", /\b(?:password|passwd|pwd|secret|api[_ -]?key|access[_ -]?token)\s*[:=]\s*["']?[^\s"']{6,}/gi],
+];
+
+function mask(value) {
+  if (value.length <= 8) return "•".repeat(value.length);
+  return `${value.slice(0, 4)}${"•".repeat(6)}`;
+}
+
+/** Finds likely secrets, deduplicated. Returns masked previews only. */
+export function scanSecrets(text) {
+  const found = new Map();
+  SECRET_PATTERNS.forEach(([label, pattern]) => {
+    for (const match of (text || "").matchAll(pattern)) {
+      if (!found.has(match[0])) found.set(match[0], { label, preview: mask(match[0]) });
+    }
+  });
+  return [...found.values()];
+}