brains-mcp 1.61.2

package/dist/tools/exportWiki.js

@@ -0,0 +1,233 @@
+import fs from "fs/promises";
+import path from "path";
+import AdmZip from "adm-zip";
+import { z } from "zod";
+import matter from "gray-matter";
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+import { listActiveGrantsForGrantee } from "../access/projectShares.js";
+// Concurrency for parallel Supabase reads during export. Tunable via env var.
+export const READ_CONCURRENCY = Math.max(1, parseInt(process.env.PULL_WIKI_READ_CONCURRENCY ?? "20", 10));
+// Base64-encoding a ZIP adds ~33% overhead; large wikis can produce a response
+// that silently overflows MCP client buffers (observed at ~3-5.5 MB). Reject
+// before encoding and point the caller at the HTTP async export endpoint instead.
+export const INLINE_ZIP_SIZE_LIMIT_BYTES = 3 * 1024 * 1024;
+export const exportWikiInputSchema = z.object({
+    outputPath: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Optional: absolute or relative path where the ZIP archive will be written (e.g. '/tmp/wiki-export.zip'). When omitted, the ZIP is returned as a base64-encoded string in the response — no server filesystem access required."),
+    includeSystem: z
+        .boolean()
+        .default(true)
+        .describe("If true, includes system files index.md and log.md in the archive"),
+    folder: z
+        .string()
+        .optional()
+        .describe("Optional: filter to only pages whose path starts with this prefix (e.g. 'projects/brainsapp')"),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("Optional: filter to only pages that have at least one of these tags in their frontmatter"),
+});
+function pageMatchesFilter(name, content, folder, tags) {
+    const hasFilter = folder !== undefined || (tags !== undefined && tags.length > 0);
+    if (!hasFilter)
+        return true;
+    const normalizedFolder = folder ? folder.replace(/\/$/, "") + "/" : undefined;
+    const matchesFolder = normalizedFolder ? name.startsWith(normalizedFolder) : false;
+    if (tags && tags.length > 0) {
+        try {
+            const parsed = matter(content);
+            const pageTags = parsed.data?.tags ?? [];
+            const matchesTags = tags.some((t) => pageTags.includes(t));
+            if (matchesTags)
+                return true;
+        }
+        catch {
+            // If frontmatter parsing fails, fall through to folder check only
+        }
+    }
+    return matchesFolder;
+}
+// Returns false when the file can be skipped without a content read.
+function namePassesPreFilter(name, includeSystem, folder, tags) {
+    if (!includeSystem && (name === "index.md" || name === "log.md"))
+        return false;
+    // When a folder filter is set with no tags filter, we can reject by name alone.
+    if (folder && !(tags && tags.length > 0)) {
+        const normalizedFolder = folder.replace(/\/$/, "") + "/";
+        if (!name.startsWith(normalizedFolder))
+            return false;
+    }
+    return true;
+}
+// Run `fn` over `items` with at most `concurrency` items in-flight at a time.
+export async function mapConcurrent(items, concurrency, fn) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        let index = nextIndex++;
+        while (index < items.length) {
+            results[index] = await fn(items[index]);
+            index = nextIndex++;
+        }
+    };
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, worker);
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Active project-share grants (BRA-368) for `userId`, narrowed to those
+ * relevant to `folder` (if set). Without this, the delta/`changedAfter` export
+ * path queries the Postgres index by owner subject only and silently drops
+ * pages from projects shared to `userId` — same root cause as BRA-379/#380
+ * and BRA-383/#384.
+ */
+async function grantScopesFor(userId, folder) {
+    if (!userId)
+        return [];
+    const normalizedFolder = folder ? folder.replace(/\/$/, "") : undefined;
+    const grants = await listActiveGrantsForGrantee(userId);
+    return grants
+        .filter((g) => !normalizedFolder ||
+        g.project_path === normalizedFolder ||
+        g.project_path.startsWith(`${normalizedFolder}/`) ||
+        normalizedFolder.startsWith(`${g.project_path}/`))
+        .map((g) => ({ userId: g.owner_subject, folder: g.project_path }));
+}
+export async function buildExportZip(drive, options) {
+    const exportedAt = new Date().toISOString();
+    const includeSystem = options.includeSystem ?? false;
+    // Fetch Postgres content-modified timestamps when available — real edit dates
+    // rather than Supabase storage upload times (identical for all pages after bulk import).
+    const storageBackend = (process.env.STORAGE_BACKEND ?? "local").toLowerCase();
+    const pgIndex = getPostgresSearchIndex();
+    const usePg = storageBackend === "supabase" && pgIndex.isConfigured();
+    let pgTimestamps = null;
+    let changedSet = null;
+    if (usePg) {
+        try {
+            const grantScopes = await grantScopesFor(options.userId ?? "", options.folder);
+            const rows = await pgIndex.listPages({
+                userId: options.userId ?? "",
+                changedAfter: options.changedAfter,
+                compact: true,
+                grantScopes,
+            });
+            pgTimestamps = new Map(rows.map((r) => [r.name, r.modified]));
+            if (options.changedAfter) {
+                changedSet = new Set(rows.map((r) => r.name));
+            }
+        }
+        catch {
+            // Non-fatal — fall back to storage modifiedTime
+        }
+    }
+    const allEntries = await drive.listFiles();
+    // Pre-filter by name, Postgres delta set, or storage mtime.
+    const preFiltered = allEntries.filter((e) => {
+        if (!namePassesPreFilter(e.name, includeSystem, options.folder, options.tags))
+            return false;
+        if (changedSet !== null && !changedSet.has(e.name))
+            return false;
+        if (options.changedAfter && !usePg) {
+            const mtime = new Date(e.modifiedTime).getTime();
+            const cursor = new Date(options.changedAfter).getTime();
+            if (!isNaN(mtime) && !isNaN(cursor) && mtime <= cursor)
+                return false;
+        }
+        return true;
+    });
+    const nameSkipped = allEntries.length - preFiltered.length;
+    const readResults = await mapConcurrent(preFiltered, READ_CONCURRENCY, async (entry) => {
+        try {
+            const file = await drive.readFile(entry.name);
+            return { ok: true, name: entry.name, content: file.content, modifiedTime: file.modifiedTime };
+        }
+        catch (err) {
+            return { ok: false, name: entry.name, reason: err instanceof Error ? err.message : String(err) };
+        }
+    });
+    const zip = new AdmZip();
+    const index = [];
+    const errors = [];
+    let included = 0;
+    let skipped = nameSkipped;
+    for (const result of readResults) {
+        if (!result.ok) {
+            errors.push({ name: result.name, reason: result.reason });
+            continue;
+        }
+        if (!pageMatchesFilter(result.name, result.content, options.folder, options.tags)) {
+            skipped++;
+            continue;
+        }
+        const contentBuffer = Buffer.from(result.content, "utf8");
+        zip.addFile(result.name, contentBuffer);
+        // Use Postgres content-modified time over storage upload time
+        const modifiedTime = pgTimestamps?.get(result.name) || result.modifiedTime;
+        index.push({ name: result.name, size: contentBuffer.length, modifiedTime });
+        included++;
+    }
+    // Generate export-index.json inside the archive
+    const exportIndex = { exportedAt, fileCount: included, files: index };
+    if (options.changedAfter)
+        exportIndex.since = options.changedAfter;
+    zip.addFile("export-index.json", Buffer.from(JSON.stringify(exportIndex, null, 2), "utf8"));
+    return {
+        buffer: zip.toBuffer(),
+        pageCount: included,
+        skippedCount: skipped,
+        generatedAt: exportedAt,
+        ...(options.changedAfter ? { since: options.changedAfter } : {}),
+        files: index,
+        errors,
+    };
+}
+export async function exportWiki(drive, input) {
+    const startMs = Date.now();
+    const { buffer, pageCount, skippedCount, generatedAt, files, errors } = await buildExportZip(drive, {
+        includeSystem: input.includeSystem,
+        folder: input.folder,
+        tags: input.tags,
+    });
+    const durationMs = Date.now() - startMs;
+    const base = {
+        success: errors.length === 0,
+        exportedAt: generatedAt,
+        durationMs,
+        fileCount: pageCount,
+        skippedCount,
+        archiveSizeBytes: buffer.length,
+        files,
+        ...(errors.length > 0 ? { errors } : {}),
+    };
+    if (!input.outputPath) {
+        // Agent-friendly mode: return the zip as base64, no server filesystem write.
+        if (buffer.length > INLINE_ZIP_SIZE_LIMIT_BYTES) {
+            return {
+                ...base,
+                success: false,
+                error: `Export ZIP is ${(buffer.length / (1024 * 1024)).toFixed(1)} MB, which exceeds the ${INLINE_ZIP_SIZE_LIMIT_BYTES / (1024 * 1024)} MB limit for inline base64 responses and would silently overflow the response buffer. ` +
+                    `Use the HTTP async export endpoint instead: POST /api/v1/export followed by GET /api/v1/export/download, ` +
+                    `or pass an outputPath to write the ZIP to a local file.`,
+            };
+        }
+        return { ...base, zipData: buffer.toString("base64") };
+    }
+    // File-path mode: write to disk and return path metadata.
+    // Only here do we signal local-mode — a ZIP now exists on the local
+    // filesystem the agent can unpack and work on. (Not in base64 mode,
+    // where nothing is written to disk.)
+    const resolvedOutput = path.resolve(input.outputPath);
+    await fs.mkdir(path.dirname(resolvedOutput), { recursive: true });
+    await fs.writeFile(resolvedOutput, buffer);
+    return {
+        ...base,
+        outputPath: resolvedOutput,
+        local_mode: true,
+        _local_mode_instructions: `Wiki exported as a ZIP archive at ${resolvedOutput} (not an extracted folder). To edit locally: unzip it, then use filesystem ops on the extracted markdown — Read instead of read_page, Write/Edit instead of update_page/patch_page, Glob/Grep instead of search_pages/list_pages. When done, re-zip the files and call import_wiki with zipPath pointing to that ZIP to sync changes back.`,
+    };
+}
+//# sourceMappingURL=exportWiki.js.map

package/dist/tools/exportWiki.js.map

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

package/dist/tools/extractLinks.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export declare const extractLinksInputSchema: z.ZodObject<{
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    folder: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tags?: string[] | undefined;
+    folder?: string | undefined;
+}, {
+    tags?: string[] | undefined;
+    folder?: string | undefined;
+}>;
+export type ExtractLinksInput = z.infer<typeof extractLinksInputSchema>;
+export declare function extractLinks(input: ExtractLinksInput, userId?: string): Promise<object>;
+//# sourceMappingURL=extractLinks.d.ts.map

package/dist/tools/extractLinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractLinks.d.ts","sourceRoot":"","sources":["../../src/tools/extractLinks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,uBAAuB;;;;;;;;;EASlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,MAAM,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/tools/extractLinks.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+export const extractLinksInputSchema = z.object({
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("Filter pages by tag (any match). At least one of tags or folder is required."),
+    folder: z
+        .string()
+        .optional()
+        .describe("Filter pages by name prefix (e.g. 'projects/brainsapp')."),
+});
+export async function extractLinks(input, userId = "") {
+    const tags = (input.tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);
+    const folder = input.folder?.trim();
+    if (tags.length === 0 && !folder) {
+        throw new Error("At least one filter is required: tags or folder");
+    }
+    return await getPostgresSearchIndex().extractLinksForStalePages({
+        tags,
+        folder,
+        userId,
+    });
+}
+//# sourceMappingURL=extractLinks.js.map

package/dist/tools/extractLinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractLinks.js","sourceRoot":"","sources":["../../src/tools/extractLinks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC;SACJ,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CAAC,8EAA8E,CAAC;IAC3F,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,0DAA0D,CAAC;CACxE,CAAC,CAAC;AAIH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,MAAM,GAAG,EAAE;IAEX,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjF,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,MAAM,sBAAsB,EAAE,CAAC,yBAAyB,CAAC;QAC9D,IAAI;QACJ,MAAM;QACN,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/generateClaudeInstructions.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { type StorageClient } from "../storage/client.js";
+export declare const generateClaudeInstructionsInputSchema: z.ZodObject<{
+    projectName: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["minimal", "extended", "pointer"]>>;
+    projectPage: z.ZodOptional<z.ZodString>;
+    inScopePaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    materialOutcomeDefinition: z.ZodOptional<z.ZodString>;
+    includeExamples: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    variant: "minimal" | "extended" | "pointer";
+    includeExamples: boolean;
+    projectPage?: string | undefined;
+    inScopePaths?: string[] | undefined;
+    materialOutcomeDefinition?: string | undefined;
+}, {
+    projectName: string;
+    variant?: "minimal" | "extended" | "pointer" | undefined;
+    projectPage?: string | undefined;
+    inScopePaths?: string[] | undefined;
+    materialOutcomeDefinition?: string | undefined;
+    includeExamples?: boolean | undefined;
+}>;
+export type GenerateClaudeInstructionsInput = z.infer<typeof generateClaudeInstructionsInputSchema>;
+export declare function generateClaudeInstructions(input: GenerateClaudeInstructionsInput, drive?: StorageClient, userId?: string): Promise<object>;
+//# sourceMappingURL=generateClaudeInstructions.d.ts.map

package/dist/tools/generateClaudeInstructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateClaudeInstructions.d.ts","sourceRoot":"","sources":["../../src/tools/generateClaudeInstructions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA0C1D,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;EA+BhD,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAgMpG,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,EACtC,KAAK,CAAC,EAAE,aAAa,EACrB,MAAM,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CA2CjB"}

package/dist/tools/generateClaudeInstructions.js

@@ -0,0 +1,263 @@
+import { z } from "zod";
+import { gatherProjectContext, } from "./instructionContext.js";
+function slugifyProjectName(value) {
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return slug || "project";
+}
+/**
+ * The project's real slug.
+ *
+ * Prefer deriving it from projectPage, which callers set to the actual project
+ * location, over slugifying the display name. init_project accepts an explicit
+ * projectSlug that need not match slugify(projectName) — and when it did not,
+ * every write-back target in the emitted block pointed at a folder that does
+ * not exist. That is the "slug drift from generation" seen on cressida, whose
+ * block referenced projects/cressida-wagon/. Reproduced deterministically:
+ * projectSlug "index-probe-tmp" with projectName "Index Probe" emitted targets
+ * under projects/index-probe/ (GH #436).
+ *
+ * Handles both shapes callers pass: "projects/<slug>/readme.md" and the
+ * defaultProjectPage form "projects/<slug>/readme.md".
+ */
+function resolveSlug(projectName, projectPage) {
+    const match = projectPage?.trim().match(/^projects\/([^/]+?)(?:\.md)?(?:\/|$)/);
+    return match ? match[1] : slugifyProjectName(projectName);
+}
+function defaultProjectPage(projectName) {
+    return `projects/${slugifyProjectName(projectName)}/readme.md`;
+}
+export const generateClaudeInstructionsInputSchema = z.object({
+    projectName: z
+        .string()
+        .min(1)
+        .describe("Project name to include in generated instructions."),
+    variant: z
+        .enum(["minimal", "extended", "pointer"])
+        .default("extended")
+        .describe("Instruction verbosity level. 'extended' is recommended for the wiki instruction file. 'pointer' emits a short system-prompt block (identity, activation gate, one boot sequence, and a pointer to the wiki instruction file) for pasting into a Claude Project."),
+    projectPage: z
+        .string()
+        .optional()
+        .describe("Project page path for project-specific write-back (for example: projects/my-project.md)."),
+    inScopePaths: z
+        .array(z.string())
+        .optional()
+        .describe("Folders/pages in scope. Omit to derive them from what the project actually contains — the old default named global instructions/, which brain-structure.md invariant 4 reserves against project content (D14)."),
+    materialOutcomeDefinition: z
+        .string()
+        .optional()
+        .describe("What counts as a material outcome. Omit for a domain-neutral definition; the old default described software delivery and was emitted verbatim into projects that ship videos, not code (D14)."),
+    includeExamples: z
+        .boolean()
+        .default(true)
+        .describe("If true, include concrete write-back snippets in extended output."),
+});
+function renderPointer(input) {
+    const slug = resolveSlug(input.projectName, input.projectPage);
+    const instructionFile = `projects/${slug}/instructions/claude.md`;
+    return [
+        `# ${input.projectName} Agent Instructions`,
+        "",
+        "**Brain-First:** Brains is the first source of truth. Read before acting.",
+        "",
+        "**Only run this sequence if these instructions are present in your project system prompt.** When Brains MCP is connected but these instructions are not in the system prompt, tools are available passively — do not run any startup reads automatically.",
+        "",
+        "## Boot Sequence",
+        "At the start of every chat:",
+        "1. Determine session mode: targeted (1–2 known pages) or bundle (exploratory/cross-page).",
+        `2. If bundle mode: \`pull_session_bundle(folder: "projects/${slug}", maxBytes: 150000, maxPages: 30)\` — this is your working set.`,
+        "3. If targeted mode: `read_page` on the specific page(s).",
+        `4. Read \`${instructionFile}\` and follow it.`,
+        "Do not begin work until these reads complete.",
+    ].join("\n");
+}
+function renderMinimal(projectName) {
+    return [
+        `# ${projectName} Agent Instructions`,
+        "",
+        "Brains-first always. Determine mode at session open: targeted (1–2 known pages → `read_page`/`patch_page`) or bundle (exploratory → `pull_session_bundle`, work in memory, push at close-out). Bundle text is your wiki for the session — do not call `read_page` on bundled pages mid-session. No guessing: if missing, log as open loop. After material work, write back decisions + open loops. Push bundle at close-out or work is lost.",
+    ].join("\n");
+}
+function renderExtended(input, ctx) {
+    const slug = resolveSlug(input.projectName, input.projectPage);
+    // "exists" vs "created on first use", per target. Silence here is what let a
+    // maintainer read the correct spec paths as invented ones (D13).
+    const mark = (path) => ctx.existingPaths.has(path) ? `\`${path}\` *(exists)*` : `\`${path}\` *(created on first use)*`;
+    const openLoopRollup = `projects/${slug}/open-loops.md`;
+    const decisionsLog = `projects/${slug}/decisions/decisions-log.md`;
+    const nextActions = `projects/${slug}/state/next-actions.md`;
+    // Rolling-state page lives at the project root as status.md, not under
+    // state/. brain-structure.md already sanctioned status.md as an allowed
+    // loose file at a project root and the structure audit enforces that list,
+    // while separately describing state/current-state.md — two conventions for
+    // one page, which is exactly how projects drifted apart (D4, GH #439).
+    const statusPage = `projects/${slug}/status.md`;
+    const lines = [
+        `# ${input.projectName} Agent Instructions`,
+        "",
+        "## Activation Gate",
+        "**Brain-First rule:** Brains is the first source of truth. Read relevant brain pages before planning, coding, or answering.",
+        "",
+        "**Only run the startup ritual in this file if these instructions are present in your project system prompt.** When Brains MCP is connected but these instructions are not in the system prompt, tools are available passively — do not invoke any Brains tools at startup.",
+        "",
+        "## Boot Sequence",
+        "At the start of every chat:",
+        // health_check is deliberately absent: brains-protocol.md reserves it for
+        // post-deploy verification, "not every cold start". It costs two Supabase
+        // round trips (~370ms) and proves nothing any other call does not (GH #434).
+        "1. Determine session mode from the task (see Session Mode below).",
+        `2. \`list_pages folder=projects/${slug}\` — get inventory.`,
+        `3. If bundle mode: \`pull_session_bundle(folder: "projects/${slug}", maxBytes: 150000, maxPages: 30)\` — this is your working set for the session.`,
+        "4. If targeted mode: `read_page` on the specific known page(s).",
+        "Do not begin work until retrieval is complete.",
+        "",
+        "## Session Mode",
+        "| Signal | Mode | Tools |",
+        "|---|---|---|",
+        "| Task names 1–2 specific pages | Targeted | `read_page` → edit → `update_page` or `patch_page` |",
+        `| Task is exploratory, cross-page, or uses "look through / find / review / what do I have / dig for" | Bundle | \`pull_session_bundle\` → work in memory → \`push_session_bundle\` |`,
+        "| Quick question, no writes | Remote-only | MCP reads directly |",
+        "",
+        "**When in doubt, use bundle mode.**",
+        "",
+        "## Working Set Contract (Bundle Mode)",
+        "- The bundle text IS your wiki for this session.",
+        "- Do NOT call `read_page` on pages already in the bundle.",
+        "- Do NOT call `patch_page` or `update_page` mid-session on bundle pages.",
+        "- Edit the bundle text in memory. Push the full modified bundle at close-out.",
+        "- New pages created mid-session (not in bundle) may be written via `create_page` immediately.",
+        "",
+        "## Project Scope",
+        `- Active project slug: \`${slug}\``,
+        ctx.subdirs.length > 0
+            ? `- Subdirs in use: ${ctx.subdirs.map((d) => `\`${d}/\``).join(", ")}.`
+            : "- Subdirs: `canonical/`, `decisions/`, `data/`, `history/`, `state/`, plus any the project needs (e.g. `events/`, `scripts/`, `resources/`).",
+        ...(ctx.subProjects.length > 0
+            ? [`- Sub-projects: ${ctx.subProjects.map((s) => `\`projects/${s}/\``).join(", ")}. Their pages count toward this project and arrive in a folder-scoped bundle for it.`]
+            : []),
+        `- All new pages must live under \`projects/${slug}/...\`.`,
+        "- Full layout spec: `instructions/brain-structure.md`.",
+        "",
+        "In-scope folders/pages:",
+        ...(input.inScopePaths && input.inScopePaths.length > 0
+            ? input.inScopePaths.map((p) => `- ${p}`)
+            : [
+                `- \`projects/${slug}/\` — everything this project owns`,
+                `- \`projects/${slug}/instructions/claude.md\` — this file`,
+            ]),
+        "",
+        `Material outcome: ${input.materialOutcomeDefinition ?? "Any result that changes this project's state, plans, or committed decisions — not a question answered or a page merely read."}`,
+        "",
+        "## Write-Back (mandatory after material work)",
+        // init_project scaffolds only readme.md and the instruction file. The
+        // targets below are created on first use, which the block previously left
+        // unsaid — an agent told to append to a decisions log would reach for
+        // patch_page, which fails on a page that does not exist, and could read
+        // that as being in the wrong project (D1).
+        //
+        // Stated rather than scaffolded: bundles now select by folder, so empty
+        // stubs would be pulled into every session for the project's whole life.
+        ctx.exists
+            ? "Each target below is marked with whether it exists right now. Use `create_page` for one that does not — `patch_page` fails on a missing page, and that failure reads like being in the wrong project."
+            : "**These pages are created on first use.** Only `readme.md` and this instruction file exist after `init_project`. Use `create_page` for a target that does not exist yet, and `patch_page` only once it does — `patch_page` fails on a missing page.",
+        "",
+        "After any session with writes, record:",
+        `- Decisions → ${mark(decisionsLog)} (append-only) + \`projects/${slug}/decisions/<topic>.md\` for rationale-heavy ones`,
+        `- Open loops → detail at \`projects/${slug}/open-loops/<loop-slug>.md\` (one page per loop) + one-line entry in ${mark(openLoopRollup)} (project rollup)`,
+        `- Next actions → ${mark(nextActions)}`,
+        `- Current state changes → ${mark(statusPage)}`,
+        "- Unanswered questions → inline as `- [ ] Question:` in the relevant project page",
+        `- Raw ingest → \`projects/${slug}/data/<file>.md\``,
+        `- Stable facts → \`projects/${slug}/canonical/<file>.md\``,
+        "",
+        "Hub-and-spoke for loops: detail page + rollup entry. No standalone aggregate files at brain root.",
+        "",
+        "## Close-Out Ritual",
+        'Before ending any session where writes were made:',
+        '1. Summarise what changed: "Here\'s what we did: X. Ready to push?"',
+        '2. On confirmation: push in pages mode, carrying each page\'s `revision` token from the pull so concurrent writes are detected:',
+        '   `push_session_bundle(pages: [{name: "...", content: "...", revision: "<revision-from-pull>"}])`',
+        "3. Local work does not persist between chats — push or lose it.",
+        "",
+        "## Completion Gate",
+        "- [ ] Read relevant brain pages first (from bundle or targeted reads)",
+        "- [ ] No unsupported assumptions",
+        "- [ ] Decisions and open loops written back",
+        "- [ ] If bundle session: full modified bundle pushed via `push_session_bundle`",
+        "",
+        "Failure condition: write-back skipped, bundle not pushed — task is not done.",
+        "",
+        "## Scope Creep",
+        "If a new feature idea or architectural direction emerges mid-session that isn't already an open loop — name it, log it, do not design or implement it now.",
+        "",
+        "## API Notes",
+        "- **`patch_page` ops** — field sets vary by type:",
+        "  - `replace`: `find`, `replace` (optionally `occurrence`, `all`)",
+        "  - `insert_after` / `insert_before`: `anchor`, `text` (optionally `occurrence`)",
+        "  - `append`: `text`",
+        "  - `replace_lines`: `startLine`, `endLine`, `text`",
+    ];
+    if (input.includeExamples) {
+        lines.push("", "## Write-Back Snippets", "### Decision", "**Decision:** [what was decided]", "**Why:** [reason]", "**Implications:** [what changes now]", "", "### Open Loop", `- [ ] [what is unresolved] → detail at \`projects/${slug}/open-loops/<loop-slug>.md\``, "", "### Next Action", `- [ ] [single concrete action, owner if known] → \`${nextActions}\``);
+    }
+    // A declared filing system means this project is audited against that skill's
+    // layout, not the Operator invariants the block above assumes. Say so rather
+    // than quietly handing it the wrong write-back table.
+    if (ctx.filing) {
+        lines.push("", "## Filing Override", `This project declares \`filing: ${ctx.filing}\` in its readme, so it is governed and audited by that skill, **not** by the Operator layout. Treat the write-back paths above as Operator defaults that may not apply — follow \`${ctx.filing}\`'s own layout where they differ.`);
+    }
+    // Anything hand-written survives regeneration. Without this, a refresh returns
+    // a block with the project's voice, contacts and conventions missing — so
+    // nobody refreshes, the file rots, and the drift this generator exists to
+    // prevent happens to the generator's own output (D13).
+    if (ctx.preservedRegion) {
+        lines.push("", ctx.preservedRegion);
+    }
+    return lines.join("\n");
+}
+export async function generateClaudeInstructions(input, drive, userId = "") {
+    const projectPage = input.projectPage?.trim() || defaultProjectPage(input.projectName);
+    const slug = resolveSlug(input.projectName, input.projectPage);
+    const openLoopRollup = `projects/${slug}/open-loops.md`;
+    const decisionsLog = `projects/${slug}/decisions/decisions-log.md`;
+    const nextActions = `projects/${slug}/state/next-actions.md`;
+    const statusPage = `projects/${slug}/status.md`;
+    const candidatePaths = [decisionsLog, openLoopRollup, nextActions, statusPage, projectPage];
+    // Only the extended variant renders write-back targets or scope, so the
+    // minimal and pointer variants stay free of wiki round trips.
+    const ctx = drive && input.variant === "extended"
+        ? await gatherProjectContext(drive, slug, "claude", candidatePaths, userId)
+        : { exists: false, pageCount: 0, subdirs: [], subProjects: [], existingPaths: new Set() };
+    const markdown = input.variant === "minimal"
+        ? renderMinimal(input.projectName)
+        : input.variant === "pointer"
+            ? renderPointer(input)
+            : renderExtended(input, ctx);
+    return {
+        success: true,
+        platform: "claude",
+        variant: input.variant,
+        projectName: input.projectName,
+        projectPage,
+        writeBackTargets: [decisionsLog, openLoopRollup, projectPage],
+        // Reported alongside the block so a caller can see what the generator knew,
+        // rather than having to infer it from the prose.
+        projectContext: {
+            exists: ctx.exists,
+            pageCount: ctx.pageCount,
+            subdirs: ctx.subdirs,
+            subProjects: ctx.subProjects,
+            ...(ctx.filing ? { filing: ctx.filing } : {}),
+            existingTargets: candidatePaths.filter((p) => ctx.existingPaths.has(p)),
+            missingTargets: candidatePaths.filter((p) => !ctx.existingPaths.has(p)),
+            preservedDomainContext: ctx.preservedRegion !== undefined,
+        },
+        markdown,
+    };
+}
+//# sourceMappingURL=generateClaudeInstructions.js.map

package/dist/tools/generateClaudeInstructions.js.map

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

package/dist/tools/generateGptInstructions.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { type StorageClient } from "../storage/client.js";
+export declare const generateGptInstructionsInputSchema: z.ZodObject<{
+    projectName: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["minimal", "extended", "pointer"]>>;
+    projectPage: z.ZodOptional<z.ZodString>;
+    inScopePaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    materialOutcomeDefinition: z.ZodOptional<z.ZodString>;
+    includeExamples: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    variant: "minimal" | "extended" | "pointer";
+    includeExamples: boolean;
+    projectPage?: string | undefined;
+    inScopePaths?: string[] | undefined;
+    materialOutcomeDefinition?: string | undefined;
+}, {
+    projectName: string;
+    variant?: "minimal" | "extended" | "pointer" | undefined;
+    projectPage?: string | undefined;
+    inScopePaths?: string[] | undefined;
+    materialOutcomeDefinition?: string | undefined;
+    includeExamples?: boolean | undefined;
+}>;
+export type GenerateGptInstructionsInput = z.infer<typeof generateGptInstructionsInputSchema>;
+export declare function generateGptInstructions(input: GenerateGptInstructionsInput, drive?: StorageClient, userId?: string): Promise<object>;
+//# sourceMappingURL=generateGptInstructions.d.ts.map

package/dist/tools/generateGptInstructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateGptInstructions.d.ts","sourceRoot":"","sources":["../../src/tools/generateGptInstructions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAqC1D,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;EA2B7C,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AA4I9F,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,EACnC,KAAK,CAAC,EAAE,aAAa,EACrB,MAAM,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CAuCjB"}