brains-mcp 1.61.2

package/dist/wiki/layoutLint.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Write-time layout lint.
+ *
+ * `brain-structure.md` defines the layout invariants and `structure-audit.md`
+ * checks them periodically. Nothing checked them at the moment a page was
+ * written, so a write to a path the spec forbids succeeded silently and the
+ * violation was only found later — if anyone ran the audit at all.
+ *
+ * The cost of that gap is not tidiness. An instruction file naming a write-back
+ * target that does not exist does not fail: the target gets created, the write
+ * reports success, and the page everyone else reads goes stale. On one project
+ * that ran for four months — a video sat recorded as "in edit ~50%" ten weeks
+ * after it published, because state was being written to a phantom `active/`
+ * tree nothing else read (GH #458).
+ *
+ * Warnings only. Never blocks, never throws. Brains hold years of legacy layout
+ * and a hard failure mid-session is worse than a misfiled page — the point is to
+ * tell the agent while it still has the context to fix it.
+ *
+ * Path-only, no I/O: this runs on every write, and a round trip per write to
+ * check the spec would cost more than the spec is worth. That constraint shapes
+ * which rules are here — see the note on scope below.
+ */
+export interface LayoutWarning {
+    /** Stable machine-readable rule id, so callers can filter. */
+    rule: string;
+    path: string;
+    message: string;
+}
+/**
+ * Check a write target against the layout invariants.
+ *
+ * Scope note: every rule here concerns the brain root or the top level of
+ * `projects/`. That is deliberate, and not only because those are the
+ * unambiguous cases. A project may declare its own filing system in
+ * `projects/<slug>/readme.md` frontmatter, and a declared project is audited
+ * against that skill's rules rather than the Operator invariants — but an
+ * override only ever governs the inside of its own folder. Keeping every rule
+ * outside project subtrees means no rule here can fire wrongly on a
+ * `mind-palace` project, without needing to read a readme to find out.
+ *
+ * Invariant 2 (thin project roots) is the notable omission. Its threshold is a
+ * count of loose files, which cannot be known from a path, and its allowed-list
+ * half would fire on the majority of legitimate writes in projects that predate
+ * the rule. It stays with the audit until there is data on how often it would
+ * actually fire.
+ */
+export declare function lintLayout(name: string): LayoutWarning[];
+/** Lint several targets at once, e.g. a bundle push. Order is preserved. */
+export declare function lintLayoutMany(names: string[]): LayoutWarning[];
+//# sourceMappingURL=layoutLint.d.ts.map

package/dist/wiki/layoutLint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layoutLint.d.ts","sourceRoot":"","sources":["../../src/wiki/layoutLint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAmCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAmFxD;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,CAE/D"}

package/dist/wiki/layoutLint.js

@@ -0,0 +1,146 @@
+/**
+ * Write-time layout lint.
+ *
+ * `brain-structure.md` defines the layout invariants and `structure-audit.md`
+ * checks them periodically. Nothing checked them at the moment a page was
+ * written, so a write to a path the spec forbids succeeded silently and the
+ * violation was only found later — if anyone ran the audit at all.
+ *
+ * The cost of that gap is not tidiness. An instruction file naming a write-back
+ * target that does not exist does not fail: the target gets created, the write
+ * reports success, and the page everyone else reads goes stale. On one project
+ * that ran for four months — a video sat recorded as "in edit ~50%" ten weeks
+ * after it published, because state was being written to a phantom `active/`
+ * tree nothing else read (GH #458).
+ *
+ * Warnings only. Never blocks, never throws. Brains hold years of legacy layout
+ * and a hard failure mid-session is worse than a misfiled page — the point is to
+ * tell the agent while it still has the context to fix it.
+ *
+ * Path-only, no I/O: this runs on every write, and a round trip per write to
+ * check the spec would cost more than the spec is worth. That constraint shapes
+ * which rules are here — see the note on scope below.
+ */
+/**
+ * Directories permitted at the brain root, from `brain-structure.md`'s
+ * "cross-cutting root after a clean audit" list, plus the two system paths.
+ */
+const SANCTIONED_ROOT_DIRS = new Set([
+    "projects",
+    "people",
+    "instructions",
+    "canonical",
+    "data",
+    "decisions",
+    "dumps",
+    "history",
+    "page-versions",
+]);
+/** Files permitted loose at the brain root. `active-*.md` is matched separately. */
+const SANCTIONED_ROOT_FILES = new Set(["open-loops.md", "readme.md", "index.md", "log.md"]);
+/**
+ * Root taxonomies that hold cross-cutting content only, and where a subfolder is
+ * therefore always suspect.
+ *
+ * `canonical/` and `data/` are deliberately absent: the spec explicitly allows
+ * topic subfolders there (`data/watchlist/`, `data/shopping/`) and forbids only
+ * project-slug ones. Telling those apart needs to know the project list, which
+ * needs I/O, so that half of invariant 4 stays with the periodic audit.
+ */
+const CROSS_CUTTING_DIRS_WITHOUT_SUBFOLDERS = new Set(["decisions", "history"]);
+/** `<slug>-claude.md`, `<slug>-gpt.md`, `<slug>-cmo.md` — a project's agent instructions. */
+const PROJECT_INSTRUCTION_FILE = /^instructions\/[^/]+-(claude|gpt|cmo)\.md$/;
+/**
+ * Check a write target against the layout invariants.
+ *
+ * Scope note: every rule here concerns the brain root or the top level of
+ * `projects/`. That is deliberate, and not only because those are the
+ * unambiguous cases. A project may declare its own filing system in
+ * `projects/<slug>/readme.md` frontmatter, and a declared project is audited
+ * against that skill's rules rather than the Operator invariants — but an
+ * override only ever governs the inside of its own folder. Keeping every rule
+ * outside project subtrees means no rule here can fire wrongly on a
+ * `mind-palace` project, without needing to read a readme to find out.
+ *
+ * Invariant 2 (thin project roots) is the notable omission. Its threshold is a
+ * count of loose files, which cannot be known from a path, and its allowed-list
+ * half would fire on the majority of legitimate writes in projects that predate
+ * the rule. It stays with the audit until there is data on how often it would
+ * actually fire.
+ */
+export function lintLayout(name) {
+    const warnings = [];
+    const path = name.replace(/^\/+/, "");
+    if (path === "")
+        return warnings;
+    const segments = path.split("/");
+    const [head, ...rest] = segments;
+    const isFileAtRoot = segments.length === 1;
+    // Invariant 1 — projects/ holds only <slug>/ folders plus a single readme.md.
+    if (head === "projects" && rest.length === 1 && rest[0].endsWith(".md")) {
+        if (rest[0] !== "readme.md") {
+            warnings.push({
+                rule: "projects-root-loose-file",
+                path,
+                message: `'${path}' puts a loose file directly in projects/, which holds only <slug>/ ` +
+                    `folders plus a single readme.md (brain-structure.md invariant 1). A cross-project ` +
+                    `tracker belongs at the brain root; project content belongs in projects/<slug>/.`,
+            });
+        }
+    }
+    // Invariant 4 — project instructions never live in global instructions/.
+    if (PROJECT_INSTRUCTION_FILE.test(path)) {
+        const slug = rest[0].replace(/-(claude|gpt|cmo)\.md$/, "");
+        const platform = rest[0].match(/-(claude|gpt|cmo)\.md$/)?.[1] ?? "claude";
+        warnings.push({
+            rule: "project-instructions-at-root",
+            path,
+            message: `'${path}' looks like a project's agent instructions in global instructions/, which ` +
+                `is reserved for operating rules and templates (brain-structure.md invariant 4). ` +
+                `Project instructions live at projects/${slug}/instructions/${platform}.md.`,
+        });
+    }
+    // Invariant 4 — no project-scoped subtree under root decisions/ or history/.
+    if (CROSS_CUTTING_DIRS_WITHOUT_SUBFOLDERS.has(head) &&
+        rest.length > 1) {
+        warnings.push({
+            rule: "project-subfolder-at-cross-cutting-root",
+            path,
+            message: `'${path}' nests a subfolder under root ${head}/, which holds cross-cutting ` +
+                `content only (brain-structure.md invariant 4). If '${rest[0]}' is a project, this ` +
+                `belongs at projects/${rest[0]}/${head}/.`,
+        });
+    }
+    // A write that invents a new top-level folder. This is the one that matters
+    // most: `active/` was born exactly this way, from an instruction file naming a
+    // write-back target nobody had created, and every write to it reported success.
+    if (!isFileAtRoot && !SANCTIONED_ROOT_DIRS.has(head)) {
+        warnings.push({
+            rule: "unsanctioned-root-folder",
+            path,
+            message: `'${path}' is under a top-level folder ('${head}/') outside the sanctioned set ` +
+                `(${[...SANCTIONED_ROOT_DIRS].filter((d) => d !== "page-versions").sort().join(", ")}). ` +
+                `If this is project content it belongs under projects/<slug>/. Nothing blocks this ` +
+                `write, so a mistyped or invented path will succeed and be read by nobody.`,
+        });
+    }
+    // A loose file at the brain root that is not one of the permitted few.
+    if (isFileAtRoot && path.endsWith(".md")) {
+        const permitted = SANCTIONED_ROOT_FILES.has(path) || /^active-[^/]+\.md$/.test(path);
+        if (!permitted) {
+            warnings.push({
+                rule: "unsanctioned-root-file",
+                path,
+                message: `'${path}' is a loose file at the brain root, which holds only open-loops.md, ` +
+                    `active-*.md trackers, and the taxonomy folders (brain-structure.md). Project ` +
+                    `content belongs under projects/<slug>/.`,
+            });
+        }
+    }
+    return warnings;
+}
+/** Lint several targets at once, e.g. a bundle push. Order is preserved. */
+export function lintLayoutMany(names) {
+    return names.flatMap((name) => lintLayout(name));
+}
+//# sourceMappingURL=layoutLint.js.map

package/dist/wiki/layoutLint.js.map

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

package/dist/wiki/links.d.ts

@@ -0,0 +1,6 @@
+export interface ExtractedWikiLink {
+    target: string;
+    anchorText: string;
+}
+export declare function extractWikiLinks(source: string, markdown: string): ExtractedWikiLink[];
+//# sourceMappingURL=links.d.ts.map

package/dist/wiki/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/wiki/links.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAkBtF"}

package/dist/wiki/links.js

@@ -0,0 +1,45 @@
+import path from "path";
+const MARKDOWN_LINK_REGEX = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/g;
+export function extractWikiLinks(source, markdown) {
+    const unique = new Map();
+    const sourceDir = path.posix.dirname(source);
+    for (const match of markdown.matchAll(MARKDOWN_LINK_REGEX)) {
+        const anchorText = (match[1] ?? "").trim();
+        const hrefRaw = (match[2] ?? "").trim();
+        if (!anchorText || !hrefRaw)
+            continue;
+        const target = resolveWikiLinkTarget(sourceDir, hrefRaw);
+        if (!target)
+            continue;
+        if (!unique.has(target)) {
+            unique.set(target, anchorText);
+        }
+    }
+    return Array.from(unique.entries()).map(([target, anchorText]) => ({ target, anchorText }));
+}
+function resolveWikiLinkTarget(sourceDir, href) {
+    const token = href.split(/\s+/)[0]?.trim().replace(/^<|>$/g, "") ?? "";
+    if (!token)
+        return null;
+    if (token.startsWith("#"))
+        return null;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(token) || token.startsWith("//"))
+        return null;
+    const [withoutQuery] = token.split("?");
+    const [withoutFragment] = withoutQuery.split("#");
+    if (!withoutFragment)
+        return null;
+    const normalized = withoutFragment.replace(/\\/g, "/");
+    const resolved = normalized.startsWith("/")
+        ? normalized.slice(1)
+        : path.posix.normalize(path.posix.join(sourceDir, normalized));
+    if (!resolved || resolved.startsWith("../"))
+        return null;
+    const ext = path.posix.extname(resolved);
+    if (ext && ext !== ".md")
+        return null;
+    if (!ext)
+        return `${resolved}.md`;
+    return resolved;
+}
+//# sourceMappingURL=links.js.map

package/dist/wiki/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/wiki/links.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAOxB,MAAM,mBAAmB,GAAG,gCAAgC,CAAC;AAE7D,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,QAAgB;IAC/D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7C,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC3D,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO;YAAE,SAAS;QAEtC,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM;YAAE,SAAS;QAEtB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;AAC9F,CAAC;AAED,SAAS,qBAAqB,CAAC,SAAiB,EAAE,IAAY;IAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACvE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9E,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,CAAC,eAAe,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;QACzC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QACrB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,GAAG,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,QAAQ,KAAK,CAAC;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/wiki/log.d.ts

@@ -0,0 +1,58 @@
+import type { StorageClient } from "../storage/client.js";
+/**
+ * Hard ceiling on log.md, enforced on every append.
+ *
+ * Storage has no append primitive, so appendLogEntry is a read-modify-write of
+ * the whole file. Left unbounded it grows forever and eventually crosses
+ * MAX_FILE_SIZE_BYTES (2 MB), at which point updateFile throws — and because
+ * every caller invokes appendLogEntry fire-and-forget with a swallowed catch,
+ * logging would stop silently. Production was at 1.0 MB and growing ~30 KB/day
+ * when this was added (GH #417).
+ *
+ * 512 KB is a deliberate compromise, not a perf target. The activity digest
+ * parses log.md for the last 7 days, so the file cannot be trimmed below that
+ * window without breaking it. At the observed ~620 bytes/entry this holds
+ * roughly 845 entries (~17 days at the observed rate) — comfortable margin
+ * over the digest's 7 days, and a quarter of the hard cap.
+ *
+ * Getting the write path genuinely cheap needs the events moved out of a
+ * markdown file entirely; this bounds the damage until then.
+ */
+export declare const LOG_MAX_BYTES: number;
+/**
+ * Age-based trim, applied in addition to the byte ceiling. Note this is the
+ * weaker of the two bounds in practice — production had zero entries older
+ * than two months, so the byte ceiling is what actually does the work.
+ */
+export declare const LOG_RETENTION_DAYS = 90;
+/**
+ * Trim log.md to the configured bounds, oldest entries first.
+ *
+ * Preserves any preamble before the first entry and keeps entries in their
+ * original order. Returns the content unchanged when nothing needs dropping,
+ * so a bounded file costs only the scan.
+ */
+export declare function rotateLog(content: string, now?: Date): string;
+export type LogEventType = "ingest" | "query" | "update" | "create" | "move" | "delete" | "lint" | "error";
+export interface LogEntry {
+    type: LogEventType;
+    title: string;
+    detail?: string;
+}
+/**
+ * Record an activity event.
+ *
+ * On Postgres-backed deployments this is a single indexed insert into
+ * `wiki_events`, and `log.md` is not touched at all. Storage has no append
+ * primitive, so the previous implementation read the whole file, concatenated,
+ * and wrote it back — ~920 KB of round-trip traffic per page write, measured
+ * at 2.6-3.6s against the production file, on every create/update/patch/move/
+ * restore/delete (GH #417, #419).
+ *
+ * Local and Drive backends keep appending to `log.md`, bounded by rotateLog().
+ *
+ * @param userId Storage owner subject. Empty for api-key / connector-key
+ *               writes, which share the global root.
+ */
+export declare function appendLogEntry(drive: StorageClient, entry: LogEntry, userId?: string): Promise<void>;
+//# sourceMappingURL=log.d.ts.map

package/dist/wiki/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/wiki/log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAK1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,QAAa,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAUrC;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAa,GAAG,MAAM,CAwDnE;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3G,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,QAAQ,EACf,MAAM,SAAK,GACV,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/wiki/log.js

@@ -0,0 +1,126 @@
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+const LOG_FILE = "log.md";
+/**
+ * Hard ceiling on log.md, enforced on every append.
+ *
+ * Storage has no append primitive, so appendLogEntry is a read-modify-write of
+ * the whole file. Left unbounded it grows forever and eventually crosses
+ * MAX_FILE_SIZE_BYTES (2 MB), at which point updateFile throws — and because
+ * every caller invokes appendLogEntry fire-and-forget with a swallowed catch,
+ * logging would stop silently. Production was at 1.0 MB and growing ~30 KB/day
+ * when this was added (GH #417).
+ *
+ * 512 KB is a deliberate compromise, not a perf target. The activity digest
+ * parses log.md for the last 7 days, so the file cannot be trimmed below that
+ * window without breaking it. At the observed ~620 bytes/entry this holds
+ * roughly 845 entries (~17 days at the observed rate) — comfortable margin
+ * over the digest's 7 days, and a quarter of the hard cap.
+ *
+ * Getting the write path genuinely cheap needs the events moved out of a
+ * markdown file entirely; this bounds the damage until then.
+ */
+export const LOG_MAX_BYTES = 512 * 1024;
+/**
+ * Age-based trim, applied in addition to the byte ceiling. Note this is the
+ * weaker of the two bounds in practice — production had zero entries older
+ * than two months, so the byte ceiling is what actually does the work.
+ */
+export const LOG_RETENTION_DAYS = 90;
+const ENTRY_HEADING = /^##\s+\[(\d{4}-\d{2}-\d{2})\]\s+\w+\s+\|/;
+const ROTATION_MARKER = /^<!-- log rotated:.*-->$/;
+function envInt(name, fallback) {
+    const raw = parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+/**
+ * Trim log.md to the configured bounds, oldest entries first.
+ *
+ * Preserves any preamble before the first entry and keeps entries in their
+ * original order. Returns the content unchanged when nothing needs dropping,
+ * so a bounded file costs only the scan.
+ */
+export function rotateLog(content, now = new Date()) {
+    const lines = content.split("\n");
+    const firstEntryIdx = lines.findIndex((l) => ENTRY_HEADING.test(l));
+    if (firstEntryIdx === -1)
+        return content;
+    const preamble = lines
+        .slice(0, firstEntryIdx)
+        .filter((l) => !ROTATION_MARKER.test(l));
+    // Group lines into entry blocks: a heading plus everything up to the next one.
+    const blocks = [];
+    let current = null;
+    for (const line of lines.slice(firstEntryIdx)) {
+        const m = line.match(ENTRY_HEADING);
+        if (m) {
+            if (current)
+                blocks.push({ date: current.date, text: current.buf.join("\n") });
+            current = { date: m[1], buf: [line] };
+        }
+        else if (current) {
+            current.buf.push(line);
+        }
+    }
+    if (current)
+        blocks.push({ date: current.date, text: current.buf.join("\n") });
+    const totalBefore = blocks.length;
+    const cutoff = new Date(now.getTime() - envInt("BRAINS_LOG_RETENTION_DAYS", LOG_RETENTION_DAYS) * 86_400_000)
+        .toISOString()
+        .slice(0, 10);
+    const kept = blocks.filter((b) => b.date >= cutoff);
+    // Byte ceiling — drop oldest until under. Always keep at least one entry so
+    // an oversized single entry cannot empty the log.
+    const maxBytes = envInt("BRAINS_LOG_MAX_BYTES", LOG_MAX_BYTES);
+    const noteFor = (dropped) => dropped === 0
+        ? []
+        : [
+            `<!-- log rotated: ${dropped} older ${dropped === 1 ? "entry" : "entries"} trimmed on ` +
+                `${now.toISOString().slice(0, 10)} (keeping <=${Math.round(maxBytes / 1024)} KB) -->`,
+        ];
+    const render = (bs, note) => [...preamble, ...note, ...bs.map((b) => b.text.trimEnd())].join("\n").trimEnd() + "\n";
+    // Measure the note too — it ships in the output, so excluding it here would
+    // let the result exceed maxBytes by the marker's length.
+    while (kept.length > 1) {
+        if (Buffer.byteLength(render(kept, noteFor(totalBefore - kept.length)), "utf8") <= maxBytes)
+            break;
+        kept.shift();
+    }
+    const dropped = totalBefore - kept.length;
+    if (dropped === 0)
+        return content;
+    return render(kept, noteFor(dropped));
+}
+/**
+ * Record an activity event.
+ *
+ * On Postgres-backed deployments this is a single indexed insert into
+ * `wiki_events`, and `log.md` is not touched at all. Storage has no append
+ * primitive, so the previous implementation read the whole file, concatenated,
+ * and wrote it back — ~920 KB of round-trip traffic per page write, measured
+ * at 2.6-3.6s against the production file, on every create/update/patch/move/
+ * restore/delete (GH #417, #419).
+ *
+ * Local and Drive backends keep appending to `log.md`, bounded by rotateLog().
+ *
+ * @param userId Storage owner subject. Empty for api-key / connector-key
+ *               writes, which share the global root.
+ */
+export async function appendLogEntry(drive, entry, userId = "") {
+    const pgIndex = getPostgresSearchIndex();
+    if (pgIndex.isConfigured()) {
+        await pgIndex.appendEvent({
+            userId,
+            type: entry.type,
+            title: entry.title,
+            detail: entry.detail,
+        });
+        return;
+    }
+    const file = await drive.readFile(LOG_FILE);
+    const date = new Date().toISOString().slice(0, 10);
+    const heading = `## [${date}] ${entry.type} | ${entry.title}`;
+    const body = entry.detail ? `\n${entry.detail}\n` : "";
+    const appended = `${file.content.trimEnd()}\n\n${heading}${body}\n`;
+    await drive.updateFile(file.fileId, rotateLog(appended), file.revision);
+}
+//# sourceMappingURL=log.js.map

package/dist/wiki/log.js.map

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

package/dist/wiki/path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalize user-provided page paths to wiki-safe relative paths.
+ * Examples:
+ * - "Fitty Cent" -> "fitty-cent.md"
+ * - "projects/Fitty Cent" -> "projects/fitty-cent.md"
+ */
+export declare function normalizeWikiPath(raw: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/wiki/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/wiki/path.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASrD"}

package/dist/wiki/path.js

@@ -0,0 +1,25 @@
+function slugSegment(value) {
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/\.md$/i, "")
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return slug || "untitled";
+}
+/**
+ * Normalize user-provided page paths to wiki-safe relative paths.
+ * Examples:
+ * - "Fitty Cent" -> "fitty-cent.md"
+ * - "projects/Fitty Cent" -> "projects/fitty-cent.md"
+ */
+export function normalizeWikiPath(raw) {
+    const normalized = raw.replace(/\\/g, "/").trim().replace(/^\/+|\/+$/g, "");
+    const parts = normalized.split("/").filter(Boolean);
+    const safeParts = (parts.length > 0 ? parts : ["untitled"]).map((p) => slugSegment(p));
+    const last = safeParts[safeParts.length - 1];
+    safeParts[safeParts.length - 1] = last.endsWith(".md") ? last : `${last}.md`;
+    return safeParts.join("/");
+}
+//# sourceMappingURL=path.js.map

package/dist/wiki/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/wiki/path.ts"],"names":[],"mappings":"AAAA,SAAS,WAAW,CAAC,KAAa;IAChC,MAAM,IAAI,GAAG,KAAK;SACf,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzB,OAAO,IAAI,IAAI,UAAU,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC5E,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvF,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC;IAE7E,OAAO,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}