changebook 0.3.1 → 0.4.0

package/README.md

@@ -7,7 +7,24 @@ codebase, plus a CLI that feeds that memory from any terminal: sign in,
 analyze uncommitted changes, sync the product map. All MCP tools are
 read-only, and Row Level Security scopes every query to the signed-in user.
 
-## Quick start
+## Two ways to run it
+
+**Local (npm):** the CLI runs the MCP server on stdio — no server to host, works
+offline against your account. See Quick start below.
+
+**Hosted (HTTP, no install):** point any client at the hosted endpoint with a
+Personal Access Token — nothing to install, just a URL:
+
+```bash
+claude mcp add --transport http changebook \
+  https://mcp.changebook.app \
+  --header "Authorization: Bearer <your-PAT>"
+```
+
+Generate the PAT in the web app (Account → Access tokens). The token is
+SHA-256-hashed server-side and revocable; every query is scoped to your account.
+
+## Quick start (local)
 
 ```bash
 npx changebook init   # login (browser) + register in Claude Code/Codex + sync
@@ -17,7 +34,9 @@ npx changebook init   # login (browser) + register in Claude Code/Codex + sync
 (one Authorize click — no token copy-pasting), registers the MCP server in
 **every coding agent it finds on the machine** — Claude Code, Codex, Cursor,
 Windsurf, Claude Desktop and VS Code (Copilot agent mode) — installs the
-post-commit hook so the atlas updates itself, and writes the product map
+git hooks (post-commit: the atlas updates itself; pre-commit: the signal
+guard warns before touching a module with an open alert), and writes the
+product map
 into the project's `CLAUDE.md`/`AGENTS.md`. It only touches agents that are
 actually installed, and merges into existing MCP configs without clobbering
 your other servers.
@@ -30,7 +49,8 @@ your other servers.
 | `changebook logout` | Forget the stored session. |
 | `changebook analyze [dir]` | Analyze the repo's uncommitted changes (`git diff HEAD`) and update the atlas — same pipeline as the VS Code extension, no editor needed. |
 | `changebook analyze --commit [ref]` | Analyze one commit. Deduped by hash server-side, so re-runs never bill. |
-| `changebook hook install\|uninstall\|status [dir]` | Git post-commit hook: every new commit is analyzed in the background (never blocks the commit). One hook covers Claude Code, Codex and manual commits — they all commit through git. |
+| `changebook hook install\|uninstall\|status [dir]` | Git hooks: every new commit is analyzed in the background (post-commit, never blocks), and the signal guard warns before you commit to a module with an open alert (pre-commit). One pair of hooks covers Claude Code, Codex and manual commits — they all commit through git. |
+| `changebook guard [dir]` | What the pre-commit hook runs: checks staged files against the atlas' open alerts. Warn-only and fail-open by default; `CHANGEBOOK_GUARD=block` makes findings abort the commit (bypass once with `git commit --no-verify`), `CHANGEBOOK_GUARD=off` silences it. |
 | `changebook sync [dir]` | Refresh the product map inside `CLAUDE.md`/`AGENTS.md`. |
 | `changebook init [dir]` | login + register MCP server + install hook + sync, in one go. |
 | `changebook open` | Open the web atlas in the browser. |

package/dist/analyze.js

@@ -7,6 +7,7 @@
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
 import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, } from "./git.js";
+import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI, truncateAtFileBoundary } from "./optimize.js";
 export async function analyze(db, options = {}) {
     const cwd = path.resolve(options.dir ?? process.cwd());
@@ -46,6 +47,9 @@ export async function analyze(db, options = {}) {
     const { status, body } = await db.invokeFunction("analyze-diff", {
         compressedDiff,
         rawDiffChars: rawDiff.length,
+        // Identidad de contenido calculada sobre el diff CRUDO, antes de
+        // comprimir: es lo único que coincide entre este hook y el webhook.
+        rawContentHash: canonicalDiffHash(rawDiff),
         projectName,
         commitHash,
         committedAt,

package/dist/canonical.js

@@ -0,0 +1,44 @@
+/**
+ * Canonical content hash of a unified diff — mirror of the server's
+ * canonicalDiffContent/canonicalDiffHash in supabase/functions/_shared/
+ * analysis.ts. The npm package must be self-contained, so this is a
+ * deliberate duplicate pinned equal by test/canonicalParity.test.ts: drift
+ * breaks CI, never the dedup.
+ *
+ * Why the CLIENT computes it, on the RAW diff, BEFORE compressing: the CLI
+ * compresses with optimize.ts and the GitHub webhook sends the API patch
+ * as-is, so the texts that reach the server for the SAME change differ and
+ * no server-side hash can reconcile them (visto en vivo 2026-07-18: el
+ * squash de la PR #165 no dedupeó contra el análisis del hook). Only the raw
+ * content, canonicalized, is a stable identity across senders.
+ */
+import { createHash } from 'node:crypto';
+export function canonicalDiffContent(diff) {
+    const out = [];
+    let minusPath = '';
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('--- a/') || line === '--- /dev/null') {
+            minusPath = line === '--- /dev/null' ? '' : line.slice(6).trim();
+            continue;
+        }
+        if (line.startsWith('+++ b/') || line === '+++ /dev/null') {
+            const path = line === '+++ /dev/null' ? minusPath : line.slice(6).trim();
+            out.push(`F:${path}`);
+            continue;
+        }
+        if (line.startsWith('Binary files ')) {
+            out.push(line);
+            continue;
+        }
+        if (line.startsWith('+') || line.startsWith('-'))
+            out.push(line);
+    }
+    return out.join('\n');
+}
+export function canonicalDiffHash(diff) {
+    const canonical = canonicalDiffContent(diff);
+    return createHash('sha256')
+        .update((canonical || diff).replace(/\s+/g, ''))
+        .digest('hex');
+}
+//# sourceMappingURL=canonical.js.map

package/dist/guard.js

@@ -0,0 +1,254 @@
+/**
+ * `changebook guard` — the pre-commit signal guard. Checks the files staged
+ * for commit against the atlas' open regression alerts and warns when the
+ * commit is about to touch a module with an unresolved alert ("you're editing
+ * something that a previous change already broke").
+ *
+ * Contract with the pre-commit hook (see hook.ts):
+ *   exit 0 — pass (including every failure mode: offline, logged out, no
+ *            project in the atlas… a guard that blocks commits when the
+ *            network is down would get uninstalled the same day)
+ *   exit 3 — findings under CHANGEBOOK_GUARD=block; the hook maps it to a
+ *            failed commit. Any OTHER non-zero exit (node missing, crash)
+ *            deliberately does NOT block.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFileAsync } from "./git.js";
+/** Exit code that asks the pre-commit hook to abort the commit. */
+export const EXIT_BLOCK = 3;
+// A commit should never feel slow because of us: whatever the network hasn't
+// answered by then is treated as "no findings".
+const GUARD_TIMEOUT_MS = 3_500;
+// Open alerts move at analysis speed (one per commit at most), so a short
+// cache makes rebases/amend streaks free without risking stale warnings.
+const CACHE_TTL_MS = 5 * 60_000;
+const MAX_ALERTS = 20;
+/**
+ * Same slug the backend derives from the project name (analysis.ts slugify):
+ * the CLI sends `path.basename(cwd)` as projectName and the server slugifies
+ * it, so reproducing that transform is how the guard finds its project row.
+ */
+export function slugifyProject(value) {
+    return value
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "") // strip diacritics left by NFD
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 50);
+}
+/**
+ * PostgREST `in.(...)` list. Module labels are human text ("Perfil y cuenta")
+ * so every value is double-quoted with `"` and `\` escaped — a comma or paren
+ * inside a label must never split the list.
+ */
+export function pgInList(values) {
+    return values
+        .map((v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`)
+        .join(",");
+}
+/**
+ * change_module rows → the UNION of files each module touched recently. The
+ * union, not the latest row: a module's changes touch different files each
+ * time, and an alerted module's alert applies to ALL of them — matching only
+ * the newest snapshot silently missed real hits (visto en vivo 2026-07-18:
+ * PublicAtlas.tsx pertenece a «Páginas legales» por filas anteriores y el
+ * guardián calló ante su alerta abierta).
+ */
+export function moduleFilesUnion(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const label = (row.module ?? "").trim();
+        if (!label)
+            continue;
+        const set = map.get(label) ?? new Set();
+        if (Array.isArray(row.files)) {
+            for (const f of row.files)
+                set.add(String(f));
+        }
+        map.set(label, set);
+    }
+    return new Map([...map.entries()].map(([k, v]) => [k, [...v]]));
+}
+/** Open alerts × staged files → warnings, deduped by (module, message). */
+export function guardFindings(staged, alerts, filesByModule) {
+    const stagedSet = new Set(staged);
+    const seen = new Set();
+    const findings = [];
+    for (const alert of alerts) {
+        const module = (alert.module ?? "").trim();
+        const plain = (alert.plain ?? "").trim();
+        if (!module || !plain)
+            continue;
+        const touched = (filesByModule.get(module) ?? []).filter((f) => stagedSet.has(f));
+        if (touched.length === 0)
+            continue;
+        const key = module + "\u0000" + plain;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        findings.push({ module, plain, staged: touched });
+    }
+    return findings;
+}
+async function gitPath(dir, name) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", name], { cwd: dir, encoding: "utf8" });
+    return path.resolve(dir, stdout.trim());
+}
+export async function stagedFiles(dir) {
+    // -z: NUL-separated, and crucially git does NOT octal-quote non-ASCII paths
+    // (default quotepath would emit "m\303\263dulo.ts", which never matches the
+    // real UTF-8 path the atlas stores → the alert is silenced). -z also covers
+    // paths with newlines. Product en español: rutas con acentos son plausibles.
+    const { stdout } = await execFileAsync("git", ["diff", "--cached", "--name-only", "-z"], { cwd: dir, encoding: "utf8" });
+    return stdout.split("\0").filter(Boolean);
+}
+function loadCache(file) {
+    try {
+        const cache = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (Date.now() - cache.fetched_at > CACHE_TTL_MS)
+            return null;
+        return cache;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchSignals(db, dir, env) {
+    const cacheFile = await gitPath(dir, "changebook-guard-cache.json").catch(() => null);
+    const cached = cacheFile ? loadCache(cacheFile) : null;
+    if (cached) {
+        return {
+            alerts: cached.alerts,
+            filesByModule: new Map(Object.entries(cached.files)),
+            projectId: cached.project_id,
+            fromCache: true,
+        };
+    }
+    // Same project the analyze/hook pipeline reports to: CHANGEBOOK_PROJECT
+    // wins, otherwise the directory name, matched by server-side slug first.
+    const candidate = env.CHANGEBOOK_PROJECT?.trim() || path.basename(path.resolve(dir));
+    const slug = slugifyProject(candidate);
+    let projects = slug
+        ? await db.rest(`projects?select=id&slug=eq.${encodeURIComponent(slug)}&limit=1`)
+        : [];
+    if (projects.length === 0) {
+        projects = await db.rest(`projects?select=id&name=eq.${encodeURIComponent(candidate)}&limit=1`);
+    }
+    let alerts = [];
+    let filesByModule = new Map();
+    const projectId = projects[0]?.id ?? null;
+    if (projectId) {
+        alerts = await db.rest(`regression_alerts?select=module,plain,created_at&project_id=eq.${projectId}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}`);
+        const modules = [
+            ...new Set(alerts.map((a) => (a.module ?? "").trim()).filter(Boolean)),
+        ];
+        if (modules.length > 0) {
+            const rows = await db.rest(`change_module?select=module,files,created_at&project_id=eq.${projectId}&module=in.(${encodeURIComponent(pgInList(modules))})&order=created_at.desc&limit=200`);
+            filesByModule = moduleFilesUnion(rows);
+        }
+    }
+    if (cacheFile) {
+        const cache = {
+            fetched_at: Date.now(),
+            project_id: projectId,
+            alerts,
+            files: Object.fromEntries(filesByModule),
+        };
+        try {
+            fs.writeFileSync(cacheFile, JSON.stringify(cache));
+        }
+        catch {
+            // Cache is an optimization; a read-only .git dir must not break the guard.
+        }
+    }
+    return { alerts, filesByModule, projectId, fromCache: false };
+}
+/** One-line last-run trace so "why didn't it warn?" is answerable. */
+async function logRun(dir, message) {
+    try {
+        const file = await gitPath(dir, "changebook-guard.log");
+        fs.writeFileSync(file, `${new Date().toISOString()} ${message}\n`);
+    }
+    catch {
+        // Best-effort only.
+    }
+}
+function printFindings(findings, block) {
+    console.error(`\n⚠ ChangeBook: ${findings.length === 1 ? "an open alert" : `${findings.length} open alerts`} on what you're about to commit:\n`);
+    for (const f of findings) {
+        console.error(`  • ${f.module} — ${f.plain}`);
+        console.error(`    staged: ${f.staged.slice(0, 5).join(", ")}`);
+    }
+    console.error(block
+        ? "\nCommit blocked (CHANGEBOOK_GUARD=block). Review the alert in your atlas (changebook open) or bypass once with: git commit --no-verify\n"
+        : "\nReview or dismiss the alert in your atlas: changebook open\n");
+}
+/**
+ * Returns the process exit code. Everything that can go wrong resolves to 0
+ * (pass): the guard informs, it does not gatekeep — except when the user
+ * explicitly opts into CHANGEBOOK_GUARD=block.
+ */
+export async function runGuard(db, dir, env = process.env) {
+    const mode = (env.CHANGEBOOK_GUARD ?? "").trim().toLowerCase();
+    if (mode === "off")
+        return 0;
+    if (!db.hasCredentials())
+        return 0;
+    let staged;
+    try {
+        staged = await stagedFiles(dir);
+    }
+    catch {
+        return 0;
+    }
+    if (staged.length === 0)
+        return 0;
+    let signals;
+    try {
+        signals = await Promise.race([
+            fetchSignals(db, dir, env),
+            new Promise((resolve) => {
+                // The caller process.exit()s right after, so the losing fetch never
+                // holds the commit hostage; unref keeps the timer from doing so either.
+                setTimeout(() => resolve(null), GUARD_TIMEOUT_MS).unref();
+            }),
+        ]);
+    }
+    catch (error) {
+        await logRun(dir, `error: ${error instanceof Error ? error.message.slice(0, 200) : String(error)}`);
+        return 0;
+    }
+    if (signals === null) {
+        await logRun(dir, `timeout after ${GUARD_TIMEOUT_MS}ms — passing`);
+        return 0;
+    }
+    const findings = guardFindings(staged, signals.alerts, signals.filesByModule);
+    // La consulta del guardián también es una consulta del atlas (QA
+    // 2026-07-18: el contador solo veía las tools MCP y el trabajo más
+    // constante del atlas era invisible). Solo las frescas — un rebase servido
+    // de caché no re-consulta nada. Best-effort y ACOTADO: jamás puede
+    // convertir un commit rápido en uno lento.
+    if (!signals.fromCache && signals.projectId) {
+        await Promise.race([
+            db
+                .insertRow("atlas_reads", {
+                project_id: signals.projectId,
+                tool: "guard_precommit",
+                source: "guard",
+            })
+                .catch(() => { }),
+            new Promise((resolve) => {
+                setTimeout(resolve, 800).unref();
+            }),
+        ]);
+    }
+    await logRun(dir, `staged=${staged.length} openAlerts=${signals.alerts.length} findings=${findings.length}`);
+    if (findings.length === 0)
+        return 0;
+    const block = mode === "block";
+    printFindings(findings, block);
+    return block ? EXIT_BLOCK : 0;
+}
+//# sourceMappingURL=guard.js.map

package/dist/hook.js

@@ -1,33 +1,77 @@
 /**
- * `changebook hook install|uninstall|status [dir]` — git post-commit hook that
- * analyzes each new commit into the atlas, in the background, without ever
- * blocking the commit. One analysis per commit, deduped server-side by hash,
- * so the cost is bounded and re-runs are free. This one hook covers every
- * client that commits: Claude Code, Codex, the terminal, any editor.
+ * `changebook hook install|uninstall|status [dir]` — the pair of git hooks
+ * that make the atlas live:
+ *
+ *   post-commit  analyzes each new commit into the atlas, in the background,
+ *                without ever blocking the commit. One analysis per commit,
+ *                deduped server-side by hash, so the cost is bounded and
+ *                re-runs are free.
+ *   pre-commit   the signal guard: warns (never blocks, unless the user opts
+ *                into CHANGEBOOK_GUARD=block) when a staged file belongs to a
+ *                module with an open regression alert.
+ *
+ * These two hooks cover every client that commits: Claude Code, Codex, the
+ * terminal, any editor.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileAsync } from "./git.js";
-const MARKER = "# changebook post-commit hook";
-function hookScript() {
-    const entry = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
+function cliEntry() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
+}
+const POST_COMMIT_MARKER = "# changebook post-commit hook";
+const PRE_COMMIT_MARKER = "# changebook pre-commit guard";
+/** Exported for tests: the contract between this script and guard.ts. */
+export function postCommitScript() {
     // Background subshell + `|| true`: a broken analyze (offline, out of
     // credits, logged out) must never make `git commit` fail or feel slow.
     // The log keeps only the last run so it can't grow unbounded.
     return `#!/bin/sh
-${MARKER} — analyzes each commit into your ChangeBook atlas.
+${POST_COMMIT_MARKER} — analyzes each commit into your ChangeBook atlas.
 # Runs in the background and never blocks the commit. Remove with:
 #   changebook hook uninstall
-( ${JSON.stringify(process.execPath)} ${JSON.stringify(entry)} analyze --commit HEAD > "$(git rev-parse --git-dir)/changebook-hook.log" 2>&1 & ) || true
+( ${JSON.stringify(process.execPath)} ${JSON.stringify(cliEntry())} analyze --commit HEAD > "$(git rev-parse --git-dir)/changebook-hook.log" 2>&1 & ) || true
+`;
+}
+/** Exported for tests: the contract between this script and guard.ts. */
+export function preCommitScript() {
+    // Foreground (a warning printed after the commit would be pointless) but
+    // fail-open by exit-code contract: ONLY the guard's deliberate exit 3
+    // (CHANGEBOOK_GUARD=block with findings) aborts the commit. A missing node,
+    // a crash, a network error — any other status — lets the commit through.
+    // The if/elif form is immune to `set -e`: a non-zero guard exit (crash,
+    // node missing, exit 3) is consumed by the condition instead of aborting the
+    // script mid-line. This matters when the line is pasted into a foreign
+    // pre-commit that runs under `set -e` (classic Husky) — only the deliberate
+    // exit 3 must block, never a crash.
+    return `#!/bin/sh
+${PRE_COMMIT_MARKER} — warns when a staged file belongs to a module with an
+# open ChangeBook alert. Warn-only unless CHANGEBOOK_GUARD=block. Remove with:
+#   changebook hook uninstall
+if ${JSON.stringify(process.execPath)} ${JSON.stringify(cliEntry())} guard; then :; elif [ $? -eq 3 ]; then exit 1; fi
 `;
 }
-async function hookPath(dir) {
+const HOOKS = [
+    {
+        name: "post-commit",
+        marker: POST_COMMIT_MARKER,
+        script: postCommitScript,
+        installedNote: "Every new commit is analyzed into your atlas in the background (1 credit each; re-runs of the same commit are free).",
+    },
+    {
+        name: "pre-commit",
+        marker: PRE_COMMIT_MARKER,
+        script: preCommitScript,
+        installedNote: "Before each commit, you'll be warned if a staged file belongs to a module with an open alert (set CHANGEBOOK_GUARD=block to make it blocking, =off to silence it).",
+    },
+];
+async function hookPath(dir, name) {
     // --git-path (not --git-dir + "/hooks") resolves core.hooksPath — set by
     // Husky in most modern JS repos to .husky/ — and linked worktrees' common
-    // dir. Building <git-dir>/hooks/post-commit by hand ignores both, so the hook
+    // dir. Building <git-dir>/hooks/<name> by hand ignores both, so the hook
     // installed to a path git never runs and the atlas silently stops updating.
-    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", "hooks/post-commit"], {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", `hooks/${name}`], {
         cwd: dir,
         encoding: "utf8",
     }).catch(() => {
@@ -36,34 +80,84 @@ async function hookPath(dir) {
     // The path is relative to `dir`.
     return path.resolve(dir, stdout.trim());
 }
+/** Whether `child` resolves inside `parent` (not the same, actually within). */
+function isInside(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * Refuse to install into a GLOBAL core.hooksPath. `git config --global
+ * core.hooksPath ~/.git-hooks` (a common setup) makes `--git-path hooks/…`
+ * resolve OUTSIDE this repo, so the post-commit would fire for EVERY repo on
+ * the machine — including private work repos — uploading their diffs and
+ * minting phantom projects. Husky's in-repo .husky/ stays inside the worktree
+ * and is fine; only a hooks dir outside both the worktree and the git-dir is
+ * the dangerous global case.
+ */
+async function assertHookInsideRepo(dir, file) {
+    const run = (args) => execFileAsync("git", args, { cwd: dir, encoding: "utf8" })
+        .then((r) => r.stdout.trim())
+        .catch(() => "");
+    const top = await run(["rev-parse", "--show-toplevel"]);
+    const common = await run(["rev-parse", "--git-common-dir"]);
+    const roots = [top, common && path.resolve(dir, common)].filter(Boolean);
+    if (roots.length > 0 && !roots.some((root) => isInside(root, file))) {
+        throw new Error(`Refusing to install: core.hooksPath points OUTSIDE this repo (${path.dirname(file)}), ` +
+            `so the hook would run for every repo on your machine and upload their diffs. ` +
+            `Install per-repo by unsetting the global hooksPath, or point it at an in-repo dir like .husky/.`);
+    }
+}
 export async function installHook(dir) {
-    const file = await hookPath(dir);
-    if (fs.existsSync(file)) {
-        const current = fs.readFileSync(file, "utf8");
-        if (!current.includes(MARKER)) {
-            throw new Error(`A post-commit hook already exists at ${file} and it isn't ChangeBook's — not overwriting it. Add this line to it manually if you want both:\n\n` +
-                hookScript().split("\n").slice(-2).join("\n"));
+    // Install each hook independently and report the conflicts together at the
+    // end: a foreign pre-commit (Husky, a repo's own guard) must not stop the
+    // post-commit analyzer from being installed, and vice versa.
+    const problems = [];
+    for (const hook of HOOKS) {
+        const file = await hookPath(dir, hook.name);
+        await assertHookInsideRepo(dir, file);
+        if (fs.existsSync(file)) {
+            const current = fs.readFileSync(file, "utf8");
+            if (!current.includes(hook.marker)) {
+                problems.push(`A ${hook.name} hook already exists at ${file} and it isn't ChangeBook's — not overwriting it. Add this to it manually if you want both:\n\n` +
+                    hook.script().split("\n").slice(4).join("\n"));
+                continue;
+            }
         }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, hook.script(), { mode: 0o755 });
+        console.error(`✓ ${hook.name} hook installed (${file}).`);
+        console.error(hook.installedNote);
     }
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, hookScript(), { mode: 0o755 });
-    console.error(`✓ post-commit hook installed (${file}).`);
-    console.error("Every new commit is analyzed into your atlas in the background (1 credit each; re-runs of the same commit are free).");
+    if (problems.length > 0)
+        throw new Error(problems.join("\n\n"));
 }
 export async function uninstallHook(dir) {
-    const file = await hookPath(dir);
-    if (!fs.existsSync(file) || !fs.readFileSync(file, "utf8").includes(MARKER)) {
-        console.error("No ChangeBook post-commit hook found.");
-        return;
+    for (const hook of HOOKS) {
+        const file = await hookPath(dir, hook.name);
+        if (!fs.existsSync(file) ||
+            !fs.readFileSync(file, "utf8").includes(hook.marker)) {
+            console.error(`No ChangeBook ${hook.name} hook found.`);
+            continue;
+        }
+        fs.unlinkSync(file);
+        console.error(`✓ ${hook.name} hook removed.`);
     }
-    fs.unlinkSync(file);
-    console.error("✓ post-commit hook removed.");
 }
 export async function hookStatus(dir) {
-    const file = await hookPath(dir);
-    const installed = fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(MARKER);
-    console.error(installed
-        ? `✓ ChangeBook post-commit hook installed (${file}).`
-        : "No ChangeBook post-commit hook in this repository. Install it with: changebook hook install");
+    let missing = false;
+    for (const hook of HOOKS) {
+        const file = await hookPath(dir, hook.name);
+        const installed = fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(hook.marker);
+        if (installed) {
+            console.error(`✓ ChangeBook ${hook.name} hook installed (${file}).`);
+        }
+        else {
+            missing = true;
+            console.error(`✗ No ChangeBook ${hook.name} hook in this repository.`);
+        }
+    }
+    if (missing) {
+        console.error("Install the missing hooks with: changebook hook install");
+    }
 }
 //# sourceMappingURL=hook.js.map

package/dist/import.js

@@ -11,6 +11,7 @@
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
 import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, } from "./git.js";
+import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI } from "./optimize.js";
 // Under the server's MAX_BATCH_ITEMS (25) to leave headroom.
 const CHUNK_SIZE = 20;
@@ -55,6 +56,7 @@ export async function importHistory(db, options = {}) {
         items.push({
             compressedDiff: compressed,
             rawDiffChars: diff.length,
+            rawContentHash: canonicalDiffHash(diff),
             commitHash: commit.hash,
             committedAt: commit.date,
         });

package/dist/index.js

@@ -8,11 +8,15 @@
  * The CLI subcommands feed and connect that memory without the VS Code
  * extension: login, analyze, sync, init, open.
  */
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { analyze } from "./analyze.js";
 import { atlasWebUrl, openInBrowser } from "./browser.js";
 import { clearCredentials, credentialsPath } from "./credentials.js";
+import { runGuard } from "./guard.js";
 import { hookStatus, installHook, uninstallHook } from "./hook.js";
 import { importHistory } from "./import.js";
 import { registerAgents } from "./init.js";
@@ -20,6 +24,10 @@ import { login } from "./login.js";
 import { AUTH_HELP, Supabase } from "./supabase.js";
 import { syncContextFiles } from "./sync.js";
 import { registerTools } from "./tools.js";
+// Single source of truth for the reported version: package.json (dist is one
+// level below it). Avoids the hardcoded "0.2.0" drifting from the published
+// version (audit M5). test/mcpVersion.test.ts pins package.json ↔ server.json.
+const VERSION = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
 const HELP = `changebook — the ChangeBook product memory, from any terminal
 
 Usage:
@@ -31,14 +39,19 @@ Usage:
                           Backfill the last N commits (default 25) via the
                           Anthropic Batch API — 50% cheaper, non-interactive
   changebook hook install|uninstall|status [dir]
-                          Git post-commit hook: analyze every new commit automatically
+                          Git hooks: analyze every new commit (post-commit) and
+                          warn before committing to a module with an open alert
+                          (pre-commit signal guard)
+  changebook guard [dir]    Check staged files against open atlas alerts
+                          (what the pre-commit hook runs; exit 3 = block)
   changebook sync [dir]     Refresh the product map inside CLAUDE.md/AGENTS.md
   changebook init [dir]     login + register MCP in every agent found + hook + sync
   changebook open           Open the web atlas in the browser
   changebook serve          Run the MCP server on stdio (default with no arguments)
 
 Environment: CHANGEBOOK_REFRESH_TOKEN / CHANGEBOOK_ACCESS_TOKEN override the stored
-session (CI/headless); CHANGEBOOK_PROJECT scopes queries to one project.`;
+session (CI/headless); CHANGEBOOK_PROJECT scopes queries to one project;
+CHANGEBOOK_GUARD=off|block tunes the pre-commit signal guard (default: warn).`;
 function requireCredentials(db) {
     if (!db.hasCredentials()) {
         console.error(AUTH_HELP);
@@ -48,7 +61,7 @@ function requireCredentials(db) {
 async function serve(db) {
     const server = new McpServer({
         name: "changebook-mcp-server",
-        version: "0.2.0",
+        version: VERSION,
     });
     registerTools(server, db);
     if (!db.hasCredentials()) {
@@ -104,11 +117,17 @@ async function main() {
         case "login":
             await login();
             return;
-        case "logout":
+        case "logout": {
+            // Revoke server-side first (best-effort), then forget the local file —
+            // otherwise the refresh token stays alive on the server after "logout".
+            const db = new Supabase();
+            if (db.hasCredentials())
+                await db.signOut();
             console.error(clearCredentials()
                 ? `✓ Session removed from ${credentialsPath()}`
                 : "No stored session.");
             return;
+        }
         case "analyze": {
             const db = new Supabase();
             requireCredentials(db);
@@ -121,6 +140,13 @@ async function main() {
             await importHistory(db, parseImportArgs(process.argv.slice(3)));
             return;
         }
+        case "guard": {
+            // No requireCredentials: a logged-out (or offline, or never-imported)
+            // repo must commit exactly as before — runGuard resolves every failure
+            // to exit 0 itself. The explicit exit also drops any fetch still racing
+            // the timeout, so the commit never waits on a dangling socket.
+            return process.exit(await runGuard(new Supabase(), arg ?? process.cwd()));
+        }
         case "hook": {
             const dir = process.argv[4] ?? process.cwd();
             if (arg === "install")

package/dist/supabase.js

@@ -6,6 +6,7 @@
  * refresh token when needed (refresh does not require a captcha).
  */
 import { loadCredentials, saveCredentials } from "./credentials.js";
+import { slugifyProject } from "./guard.js";
 // Public defaults — the anon key is the same public key the web app ships.
 const DEFAULT_URL = "https://oyosihxkecspjkiligga.supabase.co";
 const DEFAULT_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im95b3NpaHhrZWNzcGpraWxpZ2dhIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODMwMDYyNTUsImV4cCI6MjA5ODU4MjI1NX0.TU-UK1DToHmLHp9q7QEQ5eAa7V3sq3HtgCxPEa-DvDE";
@@ -70,6 +71,14 @@ export class Supabase {
         if (this.projectFilterCache !== undefined)
             return this.projectFilterCache;
         if (!this.projectEnv) {
+            // Sin proyecto explícito: si la cuenta tiene VARIOS proyectos, negar la
+            // mezcla — la frontera por proyecto que el MCP hospedado ya aplica
+            // (auditoría M3: el stdio devolvía "" = todos los proyectos y mezclaba
+            // historia/módulos/contexto). Con 0 o 1 proyecto no hay ambigüedad.
+            const some = await this.rest("projects?select=id&limit=2");
+            if (some.length > 1) {
+                throw new SupabaseError("Esta cuenta tiene varios proyectos. Define CHANGEBOOK_PROJECT (nombre o slug del repo) o pasa `project` en la tool para no mezclar sus datos.", 400);
+            }
             this.projectFilterCache = "";
             return this.projectFilterCache;
         }
@@ -84,6 +93,111 @@ export class Supabase {
         this.projectFilterCache = `&project_id=eq.${rows[0].id}`;
         return this.projectFilterCache;
     }
+    /**
+     * Per-call variant of projectFilter(): resolves an explicit project (tool
+     * argument — the repo the agent is working in) by server-side slug first,
+     * then exact name; falls back to the env-based filter when absent. The
+     * atlas is per-project, so tools pass what the agent gave them here.
+     */
+    async projectFilterFor(project) {
+        const wanted = project?.trim();
+        if (!wanted)
+            return this.projectFilter();
+        const slug = slugifyProject(wanted);
+        let rows = slug
+            ? await this.rest(`projects?select=id&slug=eq.${encodeURIComponent(slug)}&limit=1`)
+            : [];
+        if (rows.length === 0) {
+            rows = await this.rest(`projects?select=id&name=eq.${encodeURIComponent(wanted)}&limit=1`);
+        }
+        if (rows.length === 0) {
+            throw new SupabaseError(`No ChangeBook project named "${wanted}" (by slug or name).`, 404);
+        }
+        return `&project_id=eq.${rows[0].id}`;
+    }
+    /**
+     * POST one row via PostgREST as the signed-in user (RLS applies). Used for
+     * best-effort metering inserts — callers typically fire-and-forget it.
+     */
+    async insertRow(table, row) {
+        if (!this.hasCredentials())
+            throw new SupabaseError(AUTH_HELP, 401);
+        if (!this.accessToken)
+            await this.refresh();
+        let res = await this.insertOnce(table, row);
+        if (res.status === 401 && this.refreshToken) {
+            await this.refresh();
+            res = await this.insertOnce(table, row);
+        }
+        if (!res.ok) {
+            throw new SupabaseError(`Insert into ${table} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
+        }
+    }
+    /** POST /rest/v1/rpc/<fn> as the signed-in user (definer rules apply). */
+    async callRpc(fn, args) {
+        if (!this.hasCredentials())
+            throw new SupabaseError(AUTH_HELP, 401);
+        if (!this.accessToken)
+            await this.refresh();
+        let res = await this.rpcOnce(fn, args);
+        if (res.status === 401 && this.refreshToken) {
+            await this.refresh();
+            res = await this.rpcOnce(fn, args);
+        }
+        if (!res.ok) {
+            throw new SupabaseError(`RPC ${fn} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
+        }
+        return (await res.json());
+    }
+    rpcOnce(fn, args) {
+        return fetch(`${this.url}/rest/v1/rpc/${fn}`, {
+            method: "POST",
+            headers: {
+                apikey: this.anonKey,
+                Authorization: `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(args),
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    insertOnce(table, row) {
+        return fetch(`${this.url}/rest/v1/${table}`, {
+            method: "POST",
+            headers: {
+                apikey: this.anonKey,
+                Authorization: `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json",
+                Prefer: "return=minimal",
+            },
+            body: JSON.stringify(row),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    /**
+     * Revoke the session server-side (GoTrue /logout). Best-effort: the caller
+     * still clears the local file afterwards. The extension already does this;
+     * without it a `changebook logout` left the refresh token alive on the
+     * server (audit B4).
+     */
+    async signOut() {
+        if (!this.accessToken) {
+            try {
+                await this.refresh();
+            }
+            catch {
+                return; // no valid token to revoke
+            }
+        }
+        await fetch(`${this.url}/auth/v1/logout?scope=global`, {
+            method: "POST",
+            headers: {
+                apikey: this.anonKey,
+                Authorization: `Bearer ${this.accessToken}`,
+            },
+            signal: AbortSignal.timeout(10_000),
+        }).catch(() => { });
+    }
     /** GET a PostgREST path (e.g. "changelog?select=...") as the signed-in user. */
     async rest(pathWithQuery) {
         if (!this.hasCredentials())

package/dist/sync.js

@@ -12,6 +12,11 @@
  */
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+/** The project identity of the synced repo (same rule as analyze/guard). */
+function projectNameFor(targetDir) {
+    return (process.env.CHANGEBOOK_PROJECT?.trim() ||
+        path.basename(path.resolve(targetDir)));
+}
 const START = "<!-- changebook:start -->";
 const END = "<!-- changebook:end -->";
 // DB text (notes, alert bodies, business impact) is AI-written and gets embedded
@@ -26,10 +31,12 @@ const MAX_MODULES = 15;
 const MAX_CHANGES = 5;
 const MAX_COUPLINGS = 5;
 // El bloque entra en CADA sesión de agente del usuario, así que tiene un
-// presupuesto fijo (~500 tokens) y nunca crece sin control. Cuando no cabe
-// todo, se recorta por prioridad: regresiones > acoplamientos > hotspots >
-// módulos > últimos cambios.
-const SYNC_BUDGET_CHARS = 2_000;
+// presupuesto fijo (~750 tokens) y nunca crece sin control. Cuando no cabe
+// todo, se recorta por prioridad: regresiones > encargos > acoplamientos >
+// hotspots > módulos > últimos cambios. Subido de 2.000 a 3.000 el
+// 2026-07-18: la cabecera ganó las reglas de frontera/aviso/file-context y
+// con 2.000 expulsaba Módulos y Encargos enteros del mapa.
+const SYNC_BUDGET_CHARS = 3_000;
 // Co-change pair thresholds — same spirit as the web's signals: at least 3
 // shared analyses and a ≥60% rate before we call it a dependency.
 const MIN_PAIR_COUNT = 3;
@@ -38,9 +45,23 @@ const MIN_PAIR_RATE = 0.6;
 const ALERT_WINDOW_DAYS = 14;
 const MAX_ALERTS = 3;
 export async function syncContextFiles(db, targetDir) {
-    const projectFilter = await db.projectFilter();
+    const projectName = projectNameFor(targetDir);
+    // Frontera por proyecto también aquí (QA 2026-07-18): sin filtro, una
+    // cuenta con varios proyectos construiría el mapa de ESTE repo mezclando
+    // los datos de todos. Y si el proyecto aún no existe en el atlas, el mapa
+    // debe salir VACÍO — jamás el de otro proyecto.
+    let projectFilter;
+    let projectResolved = true;
+    try {
+        projectFilter = await db.projectFilterFor(projectName);
+    }
+    catch {
+        projectFilter = "&project_id=eq.00000000-0000-0000-0000-000000000000";
+        projectResolved = false;
+    }
+    const projectId = /project_id=eq\.([0-9a-f-]+)/.exec(projectFilter)?.[1] ?? null;
     const since = new Date(Date.now() - ALERT_WINDOW_DAYS * 24 * 3600 * 1000).toISOString();
-    const [moduleRows, changes, alerts] = await Promise.all([
+    const [moduleRows, changes, alerts, pendingTasks] = await Promise.all([
         db.rest("change_module?select=changelog_id,module,domain,risk,files,note,created_at&order=created_at.desc&limit=500" +
             projectFilter),
         db.rest(`changelog?select=business_impact,created_at&order=created_at.desc&limit=${MAX_CHANGES}` +
@@ -48,19 +69,47 @@ export async function syncContextFiles(db, targetDir) {
         // AI-detected regression warnings: best-effort — an error (older schema,
         // RLS hiccup) must not block the sync of the rest of the map.
         db
-            .rest(`regression_alerts?select=module,plain,created_at&created_at=gte.${since}&order=created_at.desc&limit=${MAX_ALERTS}` +
+            .rest(
+        // resolved_at=is.null: a dismissed/auto-resolved alert inside the
+        // window must not resurface in every agent session as urgent.
+        `regression_alerts?select=module,plain,created_at&created_at=gte.${since}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}` +
             projectFilter)
             .catch(() => []),
+        // Auto-remediación fase 2: los encargos pendientes entran en el bloque
+        // para que CUALQUIER sesión arranque sabiéndolos y se ofrezca a atacarlos
+        // (proponer, no ejecutar — la aprobación sigue siendo del humano).
+        // Best-effort como las alertas.
+        projectResolved && projectId
+            ? db
+                .callRpc("list_agent_tasks", {
+                p_project_id: projectId,
+            })
+                .then((rows) => rows.filter((r) => r.status === "pending"))
+                .catch(() => [])
+            : Promise.resolve([]),
     ]);
-    const section = buildSection(moduleRows, changes, alerts);
+    const section = buildSection(moduleRows, changes, alerts, projectName, pendingTasks);
     for (const name of ["CLAUDE.md", "AGENTS.md"]) {
         const file = path.join(targetDir, name);
         const updated = await upsertSection(file, section);
         console.error(`${updated} ${name}`);
     }
+    // El sync ES una consulta del atlas — la más apalancada: el mapa que
+    // destila entra en CADA sesión de agente vía CLAUDE.md/AGENTS.md sin
+    // pagar tool calls. Cuenta como lectura (best-effort).
+    if (projectResolved && projectId) {
+        await db
+            .insertRow("atlas_reads", {
+            project_id: projectId,
+            tool: "sync_context_files",
+            source: "sync",
+            chars_served: section.length,
+        })
+            .catch(() => { });
+    }
 }
 /** Exported for tests. */
-export function buildSection(rows, changes, alerts = []) {
+export function buildSection(rows, changes, alerts = [], projectName, pendingTasks = []) {
     // Newest-first rows: the first occurrence of a module is its latest state.
     const seen = new Map();
     for (const row of rows) {
@@ -79,7 +128,25 @@ export function buildSection(rows, changes, alerts = []) {
         // útiles ya van por entrada (regresiones, últimos cambios).
         "## Mapa del producto (ChangeBook · auto-generado)",
         "",
-        "Este proyecto tiene memoria en ChangeBook. Antes de explorar código a mano, orienta con las tools MCP: `atlas_modules` (mapa), `atlas_recent_changes` (historia), `atlas_module_detail` (detalle + diffs).",
+        "Este proyecto tiene memoria en ChangeBook. Al EMPEZAR la sesión, oriéntate con UNA sola llamada a la tool MCP `atlas_project_brief` (mapa + alertas + encargos pendientes + últimos cambios); para profundizar: `atlas_module_detail` (detalle + diffs).",
+        "",
+        "Si vas a trabajar un encargo pendiente del atlas, anuncia primero al usuario en 2-3 líneas qué vas a hacer y por qué, antes de tocar código.",
+        "",
+        "Antes de tocar un archivo concreto, consulta `atlas_file_context` con sus rutas: te da su módulo, riesgo, alertas abiertas e historia por una llamada — más barato que releer el código y su git log.",
+        "",
+        // Frontera por proyecto (QA 2026-07-18): el atlas y la cola de encargos
+        // son POR PROYECTO; sin este dato el agente recibiría los de otros.
+        ...(projectName
+            ? [
+                `El proyecto de ESTE repo es \`${sanitizeCell(projectName)}\`. El atlas es por proyecto: pasa SIEMPRE \`project: "${sanitizeCell(projectName)}"\` en las tools del atlas (mapa, historia, detalle, encargos y registro). Los encargos o datos de otros proyectos no pertenecen a esta sesión.`,
+                "",
+            ]
+            : []),
+        // La instrucción de escritura vive AQUÍ y no en la doc de la tool: los
+        // agentes obedecen lo que el workspace les dice, no lo que una tool
+        // disponible insinúa (lección 2026-07-17: un agente con la tool conectada
+        // hizo 3 PRs y no registró ninguno hasta que se lo pidieron).
+        "Tras cada commit, registra el cambio con la tool MCP `atlas_record_change`: pásale el diff (`git show HEAD`), `commit_hash`, `committed_at` y SIEMPRE `summary` (2-5 frases tuyas sobre qué cambió y por qué — abarata mucho el análisis). Reenviar un commit ya registrado es un no-op gratuito.",
         "",
     ];
     if (modules.length === 0) {
@@ -118,14 +185,33 @@ export function buildSection(rows, changes, alerts = []) {
         return `- **${m.module}** está marcado crítico${note ? ` — ${note}` : ""}`;
     });
     const changeLines = changes.map((c) => `- ${c.created_at.slice(0, 10)} — ${sanitizeCell((c.business_impact ?? "").slice(0, 140))}`);
+    // Auto-remediación fase 2: la cola entra en cada sesión para que el agente
+    // se OFREZCA a atacarla — proponer con plan y esperar el OK del humano,
+    // nunca ejecutar por su cuenta. Títulos deduplicados (la cola real puede
+    // llevar la misma señal encolada varias veces).
+    const taskTitles = [
+        ...new Set(pendingTasks.map((t) => (t.title ?? "").trim()).filter(Boolean)),
+    ].slice(0, 3);
+    const taskLines = taskTitles.length > 0
+        ? [
+            `- Hay ${pendingTasks.length} encargo(s) pendientes en la cola de este proyecto. Al empezar, propón al usuario cuál atacarías y por qué, y espera su OK antes de tocar código. Cola viva: \`atlas_pending_tasks\`; cierra con \`atlas_complete_task\`.`,
+            ...taskTitles.map((t) => `- ${sanitizeCell(t.slice(0, 120))}`),
+        ]
+        : [];
     // El orden de renderizado (legibilidad) y la prioridad de presupuesto
     // (utilidad para el agente) son independientes: si no cabe todo, caen
     // primero los últimos cambios y los módulos, nunca las regresiones.
     const sections = [
-        { key: "modules", priority: 3, title: "### Módulos", lines: moduleLines },
+        { key: "modules", priority: 4, title: "### Módulos", lines: moduleLines },
         {
-            key: "couplings",
+            key: "tasks",
             priority: 1,
+            title: "### Encargos pendientes del dueño (proponte atacarlos)",
+            lines: taskLines,
+        },
+        {
+            key: "couplings",
+            priority: 2,
             title: "### Módulos que cambian juntos (si tocas uno, revisa el otro)",
             lines: couplingLines,
         },
@@ -137,13 +223,13 @@ export function buildSection(rows, changes, alerts = []) {
         },
         {
             key: "hotspots",
-            priority: 2,
+            priority: 3,
             title: "### Avisos abiertos (revisar antes de modificar)",
             lines: hotspotLines,
         },
         {
             key: "changes",
-            priority: 4,
+            priority: 5,
             title: "### Últimos cambios",
             lines: changeLines,
         },

package/dist/tools.js

@@ -55,6 +55,36 @@ function previewExcerpt(excerpt) {
 function day(iso) {
     return iso.slice(0, 10);
 }
+// Pre-edit lookup helpers (mirror of the hosted scope.ts — the npm package
+// must stay self-contained, so these three stay tiny and duplicated).
+// Exported so test/mcpParity.test.ts can pin them equal to the hosted copies:
+// drift would break atlas_file_context on stdio silently (audit M7).
+export function normalizeRepoPath(path) {
+    return path.trim().replace(/^\.\//, "").replace(/^\/+/, "");
+}
+export function fileContainsFilter(path) {
+    return `files=cs.${encodeURIComponent(JSON.stringify([path]))}`;
+}
+export function quotedInList(values) {
+    return values
+        .map((v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`)
+        .join(",");
+}
+// Consultation metering (never billing): each successful read leaves a row in
+// atlas_reads so the web can show "your agent consulted the atlas N times".
+// Best-effort and non-blocking — metering must never break or slow a read.
+// user_id is filled server-side (column default auth.uid()).
+function recordRead(db, tool, projectFilter, charsServed) {
+    const projectId = /project_id=eq\.([0-9a-f-]+)/.exec(projectFilter)?.[1] ?? null;
+    void db
+        .insertRow("atlas_reads", {
+        project_id: projectId,
+        tool,
+        source: "stdio",
+        chars_served: charsServed,
+    })
+        .catch(() => { });
+}
 /** PostgREST `or=(...ilike...)` needs the pattern URL-encoded once. */
 function ilikePattern(search) {
     return encodeURIComponent(`*${search.replace(/[%*,()]/g, " ").trim()}*`);
@@ -71,6 +101,7 @@ Args:
   - limit (1-50, default 10): entries to return.
   - offset (default 0): pagination offset.
   - search (optional): case-insensitive text filter over the business and technical summaries.
+  - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
 
 Returns (structured): { count, offset, has_more, changes: [{ id, date, business_impact, summary_tech, diff_chars, modules: [{ module, risk }] }] }
 
@@ -82,6 +113,8 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                 .describe("Pagination offset"),
             search: z.string().min(2).max(120).optional()
                 .describe("Case-insensitive filter over summaries"),
+            project: z.string().min(1).max(120).optional()
+                .describe("Project to scope to (repo folder name or slug)"),
         },
         annotations: {
             readOnlyHint: true,
@@ -89,11 +122,12 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ limit, offset, search }) => {
+    }, async ({ limit, offset, search, project }) => {
         try {
+            const pf = await db.projectFilterFor(project);
             let query = `changelog?select=id,business_impact,summary_tech,created_at,diff_character_count` +
                 `&order=created_at.desc&limit=${limit}&offset=${offset}` +
-                (await db.projectFilter());
+                pf;
             if (search) {
                 const p = ilikePattern(search);
                 query += `&or=(business_impact.ilike.${p},summary_tech.ilike.${p})`;
@@ -148,7 +182,9 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                     ? `No changes match "${search}". Try a broader search or omit it.`
                     : "No analyzed changes yet. Analyze a diff from the ChangeBook extension first.");
             }
-            return toolResult(lines.join("\n"), output);
+            const changesText = lines.join("\n");
+            recordRead(db, "atlas_recent_changes", pf, changesText.length);
+            return toolResult(changesText, output);
         }
         catch (error) {
             return errorResult(error);
@@ -162,11 +198,14 @@ For each module: domain, category, latest risk level, number of analyzed changes
 
 Args:
   - domain (optional): filter by domain (e.g. "billing").
+  - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
 
 Returns (structured): { count, modules: [{ module, domain, category, risk, changes, last_changed, files }] }`,
         inputSchema: {
             domain: z.string().min(1).max(80).optional()
                 .describe("Only modules in this domain"),
+            project: z.string().min(1).max(120).optional()
+                .describe("Project to scope to (repo folder name or slug)"),
         },
         annotations: {
             readOnlyHint: true,
@@ -174,14 +213,15 @@ Returns (structured): { count, modules: [{ module, domain, category, risk, chang
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ domain }) => {
+    }, async ({ domain, project }) => {
         try {
+            const pf = await db.projectFilterFor(project);
             let query = 
             // The aggregation below uses only these columns; note/tech/excerpt
             // (up to ~1.5k each × 1000 rows) would move 1-2 MB per call for nothing.
             `change_module?select=module,domain,category,risk,files,created_at` +
                 `&order=created_at.desc&limit=1000` +
-                (await db.projectFilter());
+                pf;
             if (domain)
                 query += `&domain=eq.${encodeURIComponent(domain)}`;
             const rows = await db.rest(query);
@@ -219,7 +259,9 @@ Returns (structured): { count, modules: [{ module, domain, category, risk, chang
                     ? `No modules in domain "${domain}". Call atlas_modules without a domain to see all.`
                     : "No modules yet. Analyze a diff from the ChangeBook extension first.");
             }
-            return toolResult(lines.join("\n"), output);
+            const modulesText = lines.join("\n");
+            recordRead(db, "atlas_modules", pf, modulesText.length);
+            return toolResult(modulesText, output);
         }
         catch (error) {
             return errorResult(error);
@@ -236,6 +278,7 @@ Args:
   - limit (1-20, default 5): number of recent changes to include.
   - include_excerpts (default true): include diff excerpts (short previews unless full is set).
   - full (default false): return the diff excerpts verbatim instead of the token-saving previews. Only pass it when you actually need the code lines.
+  - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
 
 Returns (structured): { module, count, changes: [{ date, risk, note, tech, files, business_impact, excerpt, excerpt_truncated }] }`,
         inputSchema: {
@@ -247,6 +290,8 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 .describe("Include diff excerpts (previews unless full)"),
             full: z.boolean().default(false)
                 .describe("Verbatim excerpts instead of short previews"),
+            project: z.string().min(1).max(120).optional()
+                .describe("Project to scope to (repo folder name or slug)"),
         },
         annotations: {
             readOnlyHint: true,
@@ -254,11 +299,12 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ module, limit, include_excerpts, full }) => {
+    }, async ({ module, limit, include_excerpts, full, project }) => {
         try {
+            const pf = await db.projectFilterFor(project);
             const rows = await db.rest(`change_module?select=changelog_id,module,domain,category,risk,files,note,tech,excerpt,created_at` +
                 `&module=eq.${encodeURIComponent(module)}&order=created_at.desc&limit=${limit}` +
-                (await db.projectFilter()));
+                pf);
             if (rows.length === 0) {
                 return {
                     content: [
@@ -328,7 +374,98 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 }
                 lines.push("");
             }
-            return toolResult(lines.join("\n"), output);
+            const detailText = lines.join("\n");
+            recordRead(db, "atlas_module_detail", pf, detailText.length);
+            return toolResult(detailText, output);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("atlas_file_context", {
+        title: "Context of the files you are about to edit",
+        description: `Everything the atlas knows about specific FILES: which module each belongs to, its risk, open regression alerts on those modules, and how often they changed recently.
+
+Call this BEFORE editing a file — one cheap call instead of re-reading the code and its git history.
+
+Args:
+  - files (required): 1-8 repo-relative paths.
+  - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
+
+Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_changed, last_note }], open_alerts }] }`,
+        inputSchema: {
+            files: z.array(z.string().min(1).max(300)).min(1).max(8)
+                .describe("Repo-relative paths you are about to edit"),
+            project: z.string().min(1).max(120).optional()
+                .describe("Project to scope to (repo folder name or slug)"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ files, project }) => {
+        try {
+            const pf = await db.projectFilterFor(project);
+            const paths = [...new Set(files.map(normalizeRepoPath).filter(Boolean))];
+            const perFile = await Promise.all(paths.map(async (file) => {
+                const rows = await db.rest(`change_module?select=module,risk,note,created_at&${fileContainsFilter(file)}&order=created_at.desc&limit=20` +
+                    pf);
+                const byModule = new Map();
+                for (const row of rows) {
+                    const name = (row.module ?? "").trim();
+                    if (!name)
+                        continue;
+                    const existing = byModule.get(name);
+                    if (existing)
+                        existing.changes += 1;
+                    else {
+                        byModule.set(name, {
+                            module: name,
+                            risk: row.risk,
+                            changes: 1,
+                            last_changed: day(row.created_at),
+                            last_note: row.note,
+                        });
+                    }
+                }
+                return { file, modules: [...byModule.values()] };
+            }));
+            const moduleNames = [
+                ...new Set(perFile.flatMap((f) => f.modules.map((m) => m.module))),
+            ];
+            const alerts = moduleNames.length
+                ? await db.rest(`regression_alerts?select=module,plain&resolved_at=is.null&module=in.(${encodeURIComponent(quotedInList(moduleNames))})&order=created_at.desc&limit=10` +
+                    pf)
+                : [];
+            const alertsByModule = new Map();
+            for (const a of alerts) {
+                const m = (a.module ?? "").trim();
+                if (!m || !a.plain)
+                    continue;
+                alertsByModule.set(m, [...(alertsByModule.get(m) ?? []), a.plain]);
+            }
+            const lines = [`# File context (${paths.length} file(s))`, ""];
+            for (const f of perFile) {
+                lines.push(`## ${f.file}`);
+                if (f.modules.length === 0) {
+                    lines.push("No atlas history for this file yet (new or never analyzed).");
+                }
+                for (const m of f.modules) {
+                    lines.push(`- Module **${m.module}** — ${m.changes} change(s), last ${m.last_changed}` +
+                        (m.risk ? `, risk: ${m.risk}` : ""));
+                    if (m.last_note)
+                        lines.push(`  - Latest note: ${m.last_note}`);
+                    for (const plain of alertsByModule.get(m.module) ?? []) {
+                        lines.push(`  - ⚠ OPEN ALERT: ${plain}`);
+                    }
+                }
+                lines.push("");
+            }
+            const contextText = lines.join("\n");
+            recordRead(db, "atlas_file_context", pf, contextText.length);
+            return toolResult(contextText, { files: perFile });
         }
         catch (error) {
             return errorResult(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "mcpName": "io.github.raulbr90/changebook",
   "description": "ChangeBook for coding agents: MCP server (product memory for Claude Code/Codex) + CLI to sign in, analyze changes and sync the product map.",
   "type": "module",

package/server.json

@@ -2,14 +2,20 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.raulbr90/changebook",
   "description": "Query your product's living memory: module map + analyzed change history. Read-only MCP tools.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "websiteUrl": "https://changebook.dev",
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.changebook.app"
+    }
+  ],
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "changebook",
-      "version": "0.3.1",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       }