@fentech/gitcontext 0.3.3 → 0.5.0

package/dist/index.js

@@ -14844,6 +14844,49 @@ var {
   Option,
   Help
 } = import__.default;
+// package.json
+var package_default = {
+  name: "@fentech/gitcontext",
+  version: "0.4.0",
+  description: "GitContext CLI \u2014 capture, sync, and query git-backed knowledge docs",
+  type: "module",
+  bin: {
+    gitcontext: "./dist/index.js"
+  },
+  files: [
+    "dist",
+    "src/templates"
+  ],
+  scripts: {
+    build: "bun build src/index.ts --outfile dist/index.js --target bun",
+    "build:dev": "bun build src/index.ts --outfile dist/index.dev.js --target bun",
+    dev: "bun build src/index.ts --outfile dist/index.dev.js --target bun --watch",
+    typecheck: "tsc --noEmit",
+    start: "bun run src/index.ts",
+    lint: "biome check .",
+    "lint:fix": "biome check --write .",
+    test: "bun test",
+    "test:watch": "bun test --watch",
+    "release:patch": `npm version patch --no-workspaces --no-git-tag-version && NEW_V=$(node -p 'require("./package.json").version') && git add package.json && SKIP_SIMPLE_GIT_HOOKS=1 git commit -m "chore(cli): bump to v$NEW_V" && git tag "v$NEW_V" && git push origin main --tags`,
+    "release:minor": `npm version minor --no-workspaces --no-git-tag-version && NEW_V=$(node -p 'require("./package.json").version') && git add package.json && SKIP_SIMPLE_GIT_HOOKS=1 git commit -m "chore(cli): bump to v$NEW_V" && git tag "v$NEW_V" && git push origin main --tags`,
+    "release:major": `npm version major --no-workspaces --no-git-tag-version && NEW_V=$(node -p 'require("./package.json").version') && git add package.json && SKIP_SIMPLE_GIT_HOOKS=1 git commit -m "chore(cli): bump to v$NEW_V" && git tag "v$NEW_V" && git push origin main --tags`
+  },
+  dependencies: {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@inquirer/prompts": "^8.5.0",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    chalk: "^5.6.2",
+    commander: "^14.0.3",
+    "fast-glob": "^3.3.3",
+    zod: "^4.4.3"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    "@types/node": "^22.10.2",
+    "bun-types": "latest",
+    typescript: "^6.0.2"
+  }
+};
 
 // src/commands/analyze.ts
 import { execFileSync as execFileSync3 } from "child_process";
@@ -17094,7 +17137,11 @@ function readActiveProfile(profileName) {
   if (!profile || typeof profile.apiUrl !== "string" || typeof profile.userToken !== "string") {
     return null;
   }
-  return { apiUrl: profile.apiUrl, userToken: profile.userToken };
+  return {
+    apiUrl: profile.apiUrl,
+    userToken: profile.userToken,
+    orgId: typeof profile.orgId === "string" ? profile.orgId : undefined
+  };
 }
 function getActiveProfileName() {
   const config = readProfilesConfig();
@@ -17134,7 +17181,8 @@ function readRepoConfig(workingDir) {
     repoName: parsed.repoName,
     platforms: Array.isArray(parsed.platforms) ? parsed.platforms.filter((p) => typeof p === "string") : undefined,
     docProfiles: parsed.docProfiles && typeof parsed.docProfiles === "object" ? parsed.docProfiles : undefined,
-    storageMode
+    storageMode,
+    docStorageModes: parsed.docStorageModes && typeof parsed.docStorageModes === "object" ? parsed.docStorageModes : undefined
   };
 }
 function writeRepoConfig(workingDir, config) {
@@ -17145,7 +17193,8 @@ function writeRepoConfig(workingDir, config) {
   }
   const payload = {
     ...config,
-    storageMode: normalizeStorageMode(config.storageMode)
+    storageMode: normalizeStorageMode(config.storageMode),
+    ...config.docStorageModes ? { docStorageModes: config.docStorageModes } : {}
   };
   writeFileSync(join2(root, REPO_CONFIG_RELATIVE), `${JSON.stringify(payload, null, 2)}
 `, "utf-8");
@@ -17158,6 +17207,10 @@ function normalizeStorageMode(value) {
 }
 
 // src/lib/api-client.ts
+var meCache = null;
+function getCachedMe() {
+  return meCache;
+}
 class ApiClientError extends Error {
   status;
   constructor(message, status) {
@@ -17170,26 +17223,33 @@ class ApiClientError extends Error {
 class ApiClient {
   apiUrl;
   userToken;
-  constructor(apiUrl, userToken) {
+  orgId;
+  constructor(apiUrl, userToken, orgId) {
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.userToken = userToken;
+    this.orgId = orgId;
   }
   static fromProfile(profileName) {
     const config = readActiveProfile(profileName);
     if (!config) {
       throw new ApiClientError("Not authenticated. Run `gitcontext auth login` first.", 401);
     }
-    return new ApiClient(config.apiUrl, config.userToken);
+    return new ApiClient(config.apiUrl, config.userToken, config.orgId);
   }
   static fromUserConfig() {
     const config = readUserConfig();
     if (!config) {
       throw new ApiClientError("Not authenticated. Run `gitcontext auth login` first.", 401);
     }
-    return new ApiClient(config.apiUrl, config.userToken);
+    return new ApiClient(config.apiUrl, config.userToken, config.orgId);
+  }
+  static forPublic(apiUrl) {
+    return new ApiClient(apiUrl, "");
   }
   async getMe() {
-    return this.request("GET", "/api/me");
+    const me = await this.request("GET", "/api/me");
+    meCache = me;
+    return me;
   }
   async processDoc(input) {
     return this.request("POST", "/api/process-doc", input);
@@ -17235,6 +17295,57 @@ class ApiClient {
   async getDocRevision(docId, revisionNumber) {
     return this.request("GET", `/api/docs/${encodeURIComponent(docId)}/revisions/${revisionNumber}`);
   }
+  async getInstallLink(repoName) {
+    return this.request("GET", "/api/github/install-link", undefined, {
+      repoName
+    });
+  }
+  async listProjects(repoName) {
+    return this.request("GET", "/api/projects", undefined, repoName ? { repoName } : undefined);
+  }
+  async estimateBackfill(params) {
+    return this.request("GET", "/api/backfill/estimate", undefined, params);
+  }
+  async startPRBackfill(params) {
+    return this.request("POST", "/api/backfill/start", params);
+  }
+  async getOrgDocStorageModes() {
+    const result = await this.request("GET", "/api/org-doc-type-settings");
+    return result.docStorageModes;
+  }
+  async getLatestChangelog(packageKey) {
+    return this.requestPublic("GET", "/api/changelog/latest", {
+      package: packageKey
+    });
+  }
+  async getChangelog(packageKey, limit) {
+    const query = { package: packageKey };
+    if (limit !== undefined)
+      query.limit = limit;
+    return this.requestPublic("GET", "/api/changelog", query);
+  }
+  async requestPublic(method, path2, query) {
+    const url = new URL(`${this.apiUrl}${path2}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      const message = await response.text();
+      throw new ApiClientError(message || response.statusText, response.status);
+    }
+    return await response.json();
+  }
   async request(method, path2, body, query) {
     const url = new URL(`${this.apiUrl}${path2}`);
     if (query) {
@@ -17248,6 +17359,7 @@ class ApiClient {
       method,
       headers: {
         Authorization: `Bearer ${this.userToken}`,
+        ...this.orgId ? { "X-Org-Id": this.orgId } : {},
         "Content-Type": "application/json",
         Accept: "application/json"
       },
@@ -17270,7 +17382,8 @@ var TYPE_META = {
   bug: { emoji: "\uD83D\uDC1B", label: "Bug Discovery" },
   convention: { emoji: "\uD83D\uDCD0", label: "Convention Change" },
   blocker: { emoji: "\uD83D\uDEA7", label: "Blocker" },
-  conversation: { emoji: "\uD83D\uDCAC", label: "Conversation" }
+  conversation: { emoji: "\uD83D\uDCAC", label: "Conversation" },
+  report: { emoji: "\uD83D\uDCCA", label: "Report" }
 };
 function typeMeta(type) {
   return TYPE_META[type] ?? { emoji: "\uD83D\uDCC4", label: type };
@@ -17329,7 +17442,14 @@ function wrapLine(text, width) {
 
 // src/lib/file-writer.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
 import { basename, join as join3 } from "path";
 
 // src/lib/profiles.ts
@@ -17383,6 +17503,91 @@ ${structuredDoc.content.trim()}
   }
   return { filePath: relativePath, committed };
 }
+function findDocFileById(id, workingDir = process.cwd()) {
+  let root;
+  try {
+    root = resolveGitRoot(workingDir);
+  } catch {
+    return null;
+  }
+  const docsDir = join3(root, ".gitcontext", "docs");
+  if (!existsSync3(docsDir))
+    return null;
+  let entries;
+  try {
+    entries = readdirSync(docsDir);
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".md") && !entry.endsWith(".mdx"))
+      continue;
+    const absolutePath = join3(docsDir, entry);
+    let raw;
+    try {
+      raw = readFileSync2(absolutePath, "utf-8");
+    } catch {
+      continue;
+    }
+    if (!raw.startsWith(`---
+`))
+      continue;
+    const end = raw.indexOf(`
+---`, 4);
+    if (end === -1)
+      continue;
+    const yamlBlock = raw.slice(4, end);
+    for (const line of yamlBlock.split(`
+`)) {
+      if (!line.startsWith("id:"))
+        continue;
+      const val = line.slice(3).trim().replace(/^"|"$/g, "");
+      if (val === id) {
+        return { absolutePath, relativePath: join3(".gitcontext", "docs", entry) };
+      }
+    }
+  }
+  return null;
+}
+function overwriteDocFile(structuredDoc, absolutePath, relativePath, options = {}, workingDir = process.cwd()) {
+  let gitRoot;
+  try {
+    gitRoot = resolveGitRoot(workingDir);
+  } catch {
+    gitRoot = workingDir;
+  }
+  const date = new Date().toISOString().slice(0, 10);
+  const docProfile = resolveDocProfile(structuredDoc.type, gitRoot);
+  const frontmatter = {
+    id: structuredDoc.id,
+    title: structuredDoc.title,
+    branch: getCurrentBranch(gitRoot),
+    commit: getCurrentCommit(gitRoot),
+    repo: getRepoName(gitRoot),
+    author: options.author ?? "unknown",
+    date,
+    docProfile,
+    ...structuredDoc.frontmatter,
+    type: structuredDoc.type
+  };
+  const body = `---
+${toYamlFrontmatter(frontmatter)}
+---
+
+${structuredDoc.content.trim()}
+`;
+  writeFileSync2(absolutePath, body, "utf-8");
+  let committed = false;
+  if (!options.noCommit) {
+    execFileSync2("git", ["add", relativePath], { cwd: gitRoot, stdio: "inherit" });
+    execFileSync2("git", ["commit", "-m", `docs: revise \u2014 ${structuredDoc.title}`], {
+      cwd: gitRoot,
+      stdio: "inherit"
+    });
+    committed = true;
+  }
+  return { filePath: relativePath, committed };
+}
 function adoptDoc(input, repoRoot) {
   const docsDir = join3(repoRoot, ".gitcontext", "docs");
   if (!existsSync3(docsDir)) {
@@ -17775,7 +17980,8 @@ async function handleMultiDoc(docs, ctx) {
   }
 }
 async function persistDoc(doc, ctx) {
-  const storageMode = readRepoConfig(ctx.workingDir)?.storageMode ?? "repo";
+  const repoConfig = readRepoConfig(ctx.workingDir);
+  const storageMode = repoConfig?.docStorageModes?.[doc.type] ?? "repo";
   let filePath;
   if (storageMode === "cloud") {
     filePath = buildCloudFilePath(doc);
@@ -17794,6 +18000,7 @@ async function persistDoc(doc, ctx) {
       title: doc.title,
       content: doc.content,
       filePath,
+      storageMode,
       branch: ctx.branch,
       commitHash: ctx.commitHash,
       repoName: ctx.repoName,
@@ -18005,6 +18212,7 @@ async function runAnalyze(options) {
         title: doc.title,
         content: doc.content,
         filePath,
+        storageMode: "repo",
         branch,
         commitHash,
         repoName,
@@ -18069,7 +18277,8 @@ async function startCallbackServer() {
     }
     res.writeHead(200, { "Content-Type": "text/html" });
     res.end(renderHtml("\u2705 Authenticated. You can close this tab and return to your terminal."));
-    resolveToken(token);
+    const orgId = url.searchParams.get("orgId") ?? undefined;
+    resolveToken({ token, orgId });
   });
   await new Promise((resolve2) => server.listen(0, "127.0.0.1", resolve2));
   const address = server.address();
@@ -18127,8 +18336,9 @@ async function login(options) {
 `);
   openBrowser(loginUrl.toString());
   let token;
+  let orgId;
   try {
-    token = await server.waitForToken();
+    ({ token, orgId } = await server.waitForToken());
   } catch (error) {
     server.close();
     console.error(error instanceof Error ? error.message : String(error));
@@ -18137,7 +18347,7 @@ async function login(options) {
   }
   server.close();
   const newConfig = profilesConfig ?? { active: profileName, profiles: {} };
-  newConfig.profiles[profileName] = { apiUrl, userToken: token };
+  newConfig.profiles[profileName] = { apiUrl, userToken: token, orgId };
   newConfig.active = profileName;
   writeProfilesConfig(newConfig);
   try {
@@ -18203,11 +18413,14 @@ async function list() {
   }
 }
 
+// src/commands/backfill.ts
+import * as readline3 from "readline";
+
 // src/lib/backfill.ts
 import { execFileSync as execFileSync4 } from "child_process";
 
 // src/lib/local-doc-scanner.ts
-import { readdirSync, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 import { join as join4, relative } from "path";
 var EXCLUDED_DIRS = new Set([
   "node_modules",
@@ -18235,7 +18448,7 @@ function walkDir(repoRoot, dir, docsDir, depth, maxDepth, results) {
     return;
   let entries;
   try {
-    entries = readdirSync(dir);
+    entries = readdirSync2(dir);
   } catch {
     return;
   }
@@ -18361,6 +18574,7 @@ ${candidate.content.slice(0, 3000)}`,
           title: c.title,
           content: result.content,
           filePath: result.relativePath,
+          storageMode: "repo",
           branch,
           commitHash,
           repoName,
@@ -18389,14 +18603,29 @@ ${candidate.content.slice(0, 3000)}`,
 }
 
 // src/commands/backfill.ts
+async function promptConfirm(question) {
+  const rl = readline3.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve2) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve2(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
 function registerBackfillCommand(program2) {
-  program2.command("backfill").description("Scan, classify, and adopt existing markdown docs into .gitcontext/docs/").option("--local", "Adopt local .md/.mdx files found outside .gitcontext/docs/").action(async (options) => {
+  program2.command("backfill").description("Seed your knowledge base from existing docs or PR history").option("--local", "Adopt local .md/.mdx files found outside .gitcontext/docs/").option("--from-prs", "Generate draft docs from your last 6 months of merged PRs").option("--months <n>", "Number of months of PR history to analyze (default: 6)", "6").option("--max-prs <n>", "Maximum number of PRs to analyze (default: 20, max: 50)", "20").action(async (options) => {
+    if (options.fromPrs) {
+      await runBackfillFromPRs(options);
+      return;
+    }
     if (!options.local) {
-      console.error("Unknown backfill mode. Use: gitcontext backfill --local");
+      console.error("Specify a backfill mode:");
+      console.error("  gitcontext backfill --local       Adopt existing markdown docs");
+      console.error("  gitcontext backfill --from-prs    Generate docs from PR history");
       process.exitCode = 1;
       return;
     }
-    const config = readUserConfig();
+    const config = readActiveProfile();
     if (!config) {
       console.error("Not authenticated. Run `gitcontext auth login` first.");
       process.exitCode = 1;
@@ -18406,6 +18635,66 @@ function registerBackfillCommand(program2) {
     await runBackfill(client, process.cwd());
   });
 }
+async function runBackfillFromPRs(options) {
+  const config = readActiveProfile();
+  if (!config) {
+    console.error("Not authenticated. Run `gitcontext auth login` first.");
+    process.exitCode = 1;
+    return;
+  }
+  const monthsBack = Math.max(1, Math.min(12, Number(options.months ?? "6") || 6));
+  const maxPRs = Math.max(1, Math.min(50, Number(options.maxPrs ?? "20") || 20));
+  let repoName;
+  let repoFullName;
+  try {
+    repoName = getRepoName(process.cwd());
+    repoFullName = repoName;
+  } catch {
+    console.error("Could not detect repository. Run from inside a git repo.");
+    process.exitCode = 1;
+    return;
+  }
+  const client = new ApiClient(config.apiUrl, config.userToken);
+  let estimate;
+  try {
+    estimate = await client.estimateBackfill({ monthsBack, maxPRs });
+  } catch (err) {
+    const msg = err instanceof ApiClientError ? err.message : String(err);
+    console.error(`Failed to fetch backfill estimate: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`
+PR history backfill for ${repoName}`);
+  console.log(`  Months of history : ${monthsBack}`);
+  console.log(`  PRs to analyze    : up to ${estimate.estimatedPRs}`);
+  console.log(`  Estimated tokens  : ~${estimate.estimatedTokens.toLocaleString()}`);
+  console.log(`  Estimated cost    : ~$${(estimate.estimatedCostCents / 100).toFixed(2)}
+`);
+  const confirmed = await promptConfirm("Proceed? [y/N]: ");
+  if (!confirmed) {
+    console.log("Backfill cancelled.");
+    return;
+  }
+  console.log(`
+Queuing backfill job\u2026`);
+  let result;
+  try {
+    result = await client.startPRBackfill({ repoName, repoFullName, monthsBack, maxPRs });
+  } catch (err) {
+    const msg = err instanceof ApiClientError ? err.message : String(err);
+    console.error(`Backfill failed to start: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log("Backfill queued successfully!");
+  console.log(`Session ID: ${result.sessionId}`);
+  console.log(`
+Once complete, review suggestions at:
+  ${result.reviewUrl}
+`);
+  console.log("Tip: check status with `gitcontext status`.");
+}
 
 // src/commands/blockers.ts
 function handleError(error) {
@@ -18529,6 +18818,117 @@ Cancelled.`);
   });
 }
 
+// src/commands/changelog.ts
+import { spawnSync } from "child_process";
+var PRODUCTION_API_URL = "https://app.gitcontext.app";
+var WRAP_WIDTH = 72;
+function registerChangelogCommand(program2) {
+  program2.command("changelog").description("Display CLI release notes").option("--json", "Output raw JSON array").option("--limit <n>", "Show only the N most recent entries", Number).action(async (opts) => {
+    await runChangelog(opts);
+  });
+}
+async function runChangelog(opts) {
+  const profile = readActiveProfile();
+  const apiUrl = profile?.apiUrl ?? PRODUCTION_API_URL;
+  const client = ApiClient.forPublic(apiUrl);
+  let entries;
+  try {
+    entries = await client.getChangelog("cli", opts.limit);
+  } catch {
+    process.stderr.write(`Could not fetch changelog. Visit https://gitcontext.dev/changelog for the latest updates.
+`);
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(entries, null, 2)}
+`);
+    return;
+  }
+  const isTTY = process.stdout.isTTY === true;
+  const output = isTTY ? buildColorOutput(entries) : buildPlainOutput(entries);
+  if (isTTY) {
+    const lessResult = spawnSync("less", ["-R"], {
+      input: output,
+      stdio: ["pipe", "inherit", "inherit"]
+    });
+    const lessNotFound = lessResult.error && lessResult.error.code === "ENOENT";
+    if (lessNotFound) {
+      const moreResult = spawnSync("more", [], {
+        input: output,
+        stdio: ["pipe", "inherit", "inherit"]
+      });
+      const moreNotFound = moreResult.error && moreResult.error.code === "ENOENT";
+      if (moreNotFound) {
+        process.stdout.write(output);
+      }
+    }
+  } else {
+    process.stdout.write(output);
+  }
+}
+function wrapBullet(text, firstPrefix, hangPrefix) {
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let line = firstPrefix;
+  for (const word of words) {
+    if (line === firstPrefix) {
+      line += word;
+    } else if (line.length + 1 + word.length <= WRAP_WIDTH) {
+      line += ` ${word}`;
+    } else {
+      lines.push(line);
+      line = hangPrefix + word;
+    }
+  }
+  if (line !== firstPrefix)
+    lines.push(line);
+  return lines.join(`
+`);
+}
+function parseMarkdownBullets(notes) {
+  return notes.split(`
+`).map((line) => line.trim()).filter((line) => /^[-*+]\s+/.test(line)).map((line) => line.replace(/^[-*+]\s+/, ""));
+}
+function buildPlainOutput(entries) {
+  const divider = "\u2500".repeat(WRAP_WIDTH);
+  const parts = [];
+  for (const entry of entries) {
+    parts.push(divider);
+    parts.push(`${entry.date} \u2014 ${entry.headline}`);
+    if (entry.notes) {
+      const bullets = parseMarkdownBullets(entry.notes);
+      for (const bullet of bullets) {
+        parts.push(wrapBullet(bullet, "  \u2022 ", "    "));
+      }
+    }
+    parts.push("");
+  }
+  if (parts.length > 0)
+    parts.push(divider);
+  return parts.join(`
+`);
+}
+function buildColorOutput(entries) {
+  const divider = source_default.dim("\u2500".repeat(WRAP_WIDTH));
+  const parts = [];
+  for (const entry of entries) {
+    parts.push(divider);
+    parts.push(source_default.bold(`${entry.date} \u2014 ${entry.headline}`));
+    if (entry.notes) {
+      const bullets = parseMarkdownBullets(entry.notes);
+      for (const bullet of bullets) {
+        parts.push(wrapBullet(bullet, `  ${source_default.dim("\u2022")} `, "    "));
+      }
+    }
+    parts.push("");
+  }
+  if (parts.length > 0)
+    parts.push(divider);
+  return parts.join(`
+`);
+}
+
 // src/commands/docs.ts
 function handleError2(error) {
   if (error instanceof ApiClientError) {
@@ -18716,10 +19116,10 @@ ${meta.emoji} ${meta.label} \u2014 ${doc.title}`);
 }
 
 // src/commands/init.ts
-import { execFileSync as execFileSync5, spawnSync } from "child_process";
+import { execFileSync as execFileSync5, spawnSync as spawnSync2 } from "child_process";
 
 // src/lib/platform-installer.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
 import { homedir as homedir2 } from "os";
 import { dirname, join as join5 } from "path";
 var TEMPLATES_DIR = join5(import.meta.dir, "..", "templates");
@@ -18777,7 +19177,7 @@ function copyTemplateDir(srcDir, destDir, global3 = false) {
   if (!existsSync5(srcDir))
     return [];
   const files = [];
-  for (const entry of readdirSync2(srcDir, { withFileTypes: true })) {
+  for (const entry of readdirSync3(srcDir, { withFileTypes: true })) {
     if (entry.isFile()) {
       const content = readFileSync5(join5(srcDir, entry.name), "utf-8");
       files.push(writeFileSafe(join5(destDir, entry.name), content, global3));
@@ -18870,7 +19270,6 @@ var BANNER = `
 \u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551   \u2588\u2588\u2551   \u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2554\u255D \u2588\u2588\u2557   \u2588\u2588\u2551
  \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u255D   \u255A\u2550\u255D    \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D   \u255A\u2550\u255D   \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D   \u255A\u2550\u255D
 `;
-var GITHUB_APP_URL = process.env.GITCONTEXT_GITHUB_APP_URL ?? "https://github.com/apps/gitcontext/installations/new";
 var PLATFORM_CHOICES = [
   { value: "claude-code", name: "Claude Code" },
   { value: "cursor", name: "Cursor" },
@@ -18961,19 +19360,80 @@ Setting up GitContext for ${repoName}...
 `);
     }
   }
-  const installApp = await dist_default5({
-    message: "Install the GitContext GitHub App to enable PR analysis and doc suggestions?",
-    default: true
-  });
-  if (installApp) {
-    const installUrl = `${GITHUB_APP_URL}?repo=${encodeURIComponent(repoName)}`;
-    console.log(`
+  const apiClientForGH = new ApiClient(userConfig.apiUrl, userConfig.userToken, userConfig.orgId);
+  let alreadyConnected = false;
+  try {
+    const { projects: existingProjects } = await apiClientForGH.listProjects(repoName);
+    if (existingProjects.length > 0) {
+      alreadyConnected = true;
+      console.log(source_default.green(`
+  \u2713 GitHub App already installed \u2014 ${repoName} is connected`));
+    }
+  } catch {}
+  if (!alreadyConnected) {
+    const installApp = await dist_default5({
+      message: "Install the GitContext GitHub App to enable PR analysis and doc suggestions?",
+      default: true
+    });
+    if (installApp) {
+      let installUrl;
+      let usePolling = true;
+      try {
+        const { url } = await apiClientForGH.getInstallLink(repoName);
+        installUrl = url;
+      } catch {
+        const githubAppFallbackUrl = process.env.GITCONTEXT_GITHUB_APP_URL ?? null;
+        if (!githubAppFallbackUrl) {
+          console.log(source_default.yellow(`
+  Warning: could not retrieve install URL and no fallback is configured.
+` + `  Set GITCONTEXT_GITHUB_APP_URL or connect your repo from the web dashboard.
+`));
+          usePolling = false;
+          installUrl = "";
+        } else {
+          usePolling = false;
+          installUrl = `${githubAppFallbackUrl}?repo=${encodeURIComponent(repoName)}`;
+          console.log(source_default.yellow(`
+  Warning: could not get signed install URL \u2014 using fallback link.`));
+        }
+      }
+      if (!installUrl) {} else {
+        console.log(`
 Opening GitHub App installation page...`);
-    console.log(`If it doesn't open automatically, visit:
+        console.log(`If it doesn't open automatically, visit:
   ${installUrl}
 `);
-    openBrowser(installUrl);
-    await dist_default5({ message: "Press enter once the GitHub App is installed", default: true });
+        openBrowser(installUrl);
+        await dist_default5({ message: "Press enter once the GitHub App is installed", default: true });
+      }
+      if (usePolling) {
+        const POLL_INTERVAL_MS = 2000;
+        const MAX_ATTEMPTS = 8;
+        let connected = false;
+        for (let attempt = 0;attempt < MAX_ATTEMPTS; attempt++) {
+          try {
+            const { projects: polledProjects } = await apiClientForGH.listProjects(repoName);
+            if (polledProjects.length > 0) {
+              connected = true;
+              break;
+            }
+          } catch {}
+          if (attempt < MAX_ATTEMPTS - 1) {
+            await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
+          }
+        }
+        if (connected) {
+          console.log(source_default.green(`
+  \u2713 GitHub App installed \u2014 ${repoName} is now connected`));
+        } else {
+          const settingsUrl = `${userConfig.apiUrl}/settings/org/repos`;
+          console.log(source_default.yellow(`
+  Warning: could not confirm GitHub App installation for ${repoName}.
+` + `  Verify at: ${settingsUrl}
+`));
+        }
+      }
+    }
   }
   const installedFiles = [];
   for (const platform2 of selectedPlatforms) {
@@ -19008,7 +19468,7 @@ Opening GitHub App installation page...`);
       process.exitCode = 1;
       return;
     }
-    const hasStagedChanges = spawnSync("git", ["diff", "--cached", "--quiet"], { cwd: repoRoot }).status !== 0;
+    const hasStagedChanges = spawnSync2("git", ["diff", "--cached", "--quiet"], { cwd: repoRoot }).status !== 0;
     if (!hasStagedChanges) {
       console.log(`
   \u2713 Files written (no new git changes to commit)`);
@@ -19028,7 +19488,7 @@ Opening GitHub App installation page...`);
       }
     }
   }
-  const apiClient = new ApiClient(userConfig.apiUrl, userConfig.userToken);
+  const apiClient = new ApiClient(userConfig.apiUrl, userConfig.userToken, userConfig.orgId);
   const candidateCount = scanLocalDocs(repoRoot).length;
   if (candidateCount > 0) {
     const wantAdopt = await dist_default5({
@@ -19040,7 +19500,7 @@ Opening GitHub App installation page...`);
     }
   }
   console.log(source_default.bold.hex("#6366f1")(BANNER));
-  console.log(source_default.dim("  docs that ship with your code") + `
+  console.log(`${source_default.dim("  docs that ship with your code")}
 `);
   console.log(`  Repo:    ${repoName}`);
   console.log(`  Profile: ${docProfile}`);
@@ -41881,6 +42341,31 @@ After all docs are created, provide a summary table: doc type, title, file path.
       }
     ]
   }));
+  server.registerPrompt("revise_doc", {
+    title: "Revise Doc",
+    description: "AI-assisted revision of an existing doc \u2014 find, revise, and persist"
+  }, async () => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are revising an existing knowledge doc in this repository.
+
+## Steps
+
+1. Call \`mcp__gitcontext__list_docs\` (optionally with a branch or type filter) to find the target doc, or ask the developer which doc they want to revise.
+2. Call \`mcp__gitcontext__revise_doc\` with the chosen \`docId\` and the developer's revision prompt.
+3. Present the suggested revision to the developer (show title and content).
+4. Ask: "Accept (write & save), Revise (refine with feedback), or Reject (discard)?"
+   - **Accept**: call \`mcp__gitcontext__write_doc\` with \`overwrite: true\`. If the result contains \`notFoundLocally: true\`, the doc has no local file \u2014 skip the local write and call \`mcp__gitcontext__ingest_doc\` directly using the doc's existing \`filePath\` from the \`revise_doc\` response. If the file was written, use the \`filePath\` from \`write_doc\` result for \`ingest_doc\`.
+   - **Revise**: collect feedback, call \`mcp__gitcontext__revise_doc\` again using the current suggestion as the new base (pass the current content as context in the prompt), then loop back to step 3.
+   - **Reject**: discard \u2014 nothing is saved.
+5. On accept, confirm: "\u2705 Doc revised and live in dashboard."`
+        }
+      }
+    ]
+  }));
   server.registerPrompt("analyze_pr", {
     title: "Analyze PR",
     description: "Lightweight one-shot PR analysis \u2014 automatically fetches the diff and presents doc suggestions"
@@ -41999,7 +42484,7 @@ function registerDocsTools(server) {
     }
   });
   server.registerTool("write_doc", {
-    description: "Write a structured doc to .gitcontext/docs/ and optionally commit it",
+    description: "Write a structured doc to .gitcontext/docs/ and optionally commit it. Set overwrite: true to overwrite an existing file matched by frontmatter id.",
     inputSchema: {
       structuredDoc: exports_external.object({
         id: exports_external.string(),
@@ -42010,10 +42495,26 @@ function registerDocsTools(server) {
         frontmatter: exports_external.record(exports_external.string(), exports_external.unknown())
       }).describe("Structured doc object from process_doc"),
       workingDir: exports_external.string().optional().describe("Git working directory"),
-      noCommit: exports_external.boolean().optional().describe("Skip git commit after writing")
+      noCommit: exports_external.boolean().optional().describe("Skip git commit after writing"),
+      overwrite: exports_external.boolean().optional().describe("When true, overwrite the existing file matched by frontmatter id instead of creating a new one")
     }
-  }, async ({ structuredDoc, workingDir, noCommit }) => {
+  }, async ({ structuredDoc, workingDir, noCommit, overwrite }) => {
     try {
+      if (overwrite) {
+        const existing = findDocFileById(structuredDoc.id, workingDir);
+        if (existing) {
+          const result2 = overwriteDocFile(structuredDoc, existing.absolutePath, existing.relativePath, { noCommit }, workingDir);
+          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ notFoundLocally: true, id: structuredDoc.id }, null, 2)
+            }
+          ]
+        };
+      }
       const result = writeDoc(structuredDoc, workingDir, { noCommit });
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
@@ -42042,6 +42543,7 @@ function registerDocsTools(server) {
         title,
         content,
         filePath,
+        storageMode: "repo",
         branch,
         commitHash,
         repoName,
@@ -42053,6 +42555,49 @@ function registerDocsTools(server) {
       return errorResult2(err);
     }
   });
+  server.registerTool("revise_doc", {
+    description: "Fetch an existing doc by ID, send it + a revision prompt to /api/process-doc, and return the suggested revised content. Stateless \u2014 does not write or ingest. The agent drives the accept/revise/reject loop through conversation.",
+    inputSchema: {
+      docId: exports_external.string().describe("ID of the doc to revise"),
+      prompt: exports_external.string().describe("Revision instruction"),
+      workingDir: exports_external.string().optional().describe("Git working directory (for git context)")
+    }
+  }, async ({ docId, prompt }) => {
+    try {
+      const client = ApiClient.fromUserConfig();
+      const originalDoc = await client.getDoc(docId);
+      const originalContent = originalDoc.content;
+      let author;
+      try {
+        const me = await client.getMe();
+        author = me.githubLogin ?? me.name ?? me.email ?? "unknown";
+      } catch {
+        author = "unknown";
+      }
+      const context = `Current doc (revise this):
+${originalContent}`;
+      const result = await client.processDoc({
+        prompt,
+        branch: originalDoc.branch,
+        commitHash: originalDoc.commitHash,
+        repoName: originalDoc.repoName,
+        author,
+        context
+      });
+      const raw = result.docs[0] ?? null;
+      const suggested = raw ? { ...raw, id: docId, frontmatter: { ...raw.frontmatter, id: docId } } : null;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ ...suggested, originalContent }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return errorResult2(err);
+    }
+  });
   server.registerTool("list_docs", {
     description: "List docs with optional filters and cursor-based pagination",
     inputSchema: {
@@ -42305,6 +42850,7 @@ function registerPushCommand(program2) {
           title: doc2.title,
           content: doc2.content,
           filePath: doc2.filePath,
+          storageMode: "repo",
           branch: doc2.branch,
           commitHash: doc2.commitHash,
           repoName: doc2.repoName,
@@ -42344,6 +42890,257 @@ function registerPushCommand(program2) {
   });
 }
 
+// src/commands/revise.ts
+function registerReviseCommand(program2) {
+  program2.command("revise").description("AI-assisted revision of an existing doc").option("--doc <id>", "Doc ID to revise (skips fuzzy search)").option("--prompt <text>", "Revision prompt (skips interactive prompt)").option("--no-commit", "Write the file without creating a git commit").option("--no-local", "Skip local file overwrite; only update the cloud DB").option("--json", "Output revised doc as JSON (non-interactive)").action(async (options) => {
+    await runRevise(options);
+  });
+}
+async function runRevise(options) {
+  const config2 = readUserConfig();
+  if (!config2) {
+    console.error("Not authenticated. Run `gitcontext auth login` first.");
+    process.exitCode = 1;
+    return;
+  }
+  const client = new ApiClient(config2.apiUrl, config2.userToken);
+  const workingDir = process.cwd();
+  const branch = getCurrentBranch(workingDir);
+  const commitHash = getCurrentCommit(workingDir);
+  const repoName = getRepoName(workingDir);
+  let me;
+  try {
+    me = await client.getMe();
+  } catch (error51) {
+    handleApiError(error51);
+    return;
+  }
+  const author = me.githubLogin ?? me.name ?? me.email ?? "unknown";
+  let targetDoc;
+  if (options.doc) {
+    try {
+      targetDoc = await client.getDoc(options.doc);
+    } catch (error51) {
+      handleApiError(error51);
+      return;
+    }
+  } else {
+    if (options.json) {
+      console.error("--doc <id> is required in --json mode.");
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      targetDoc = await pickDocInteractive(client);
+    } catch (error51) {
+      if (error51.code === "ERR_USE_AFTER_CLOSE") {
+        return;
+      }
+      handleApiError(error51);
+      return;
+    }
+  }
+  let revisionPrompt = options.prompt?.trim() ?? "";
+  if (!revisionPrompt) {
+    if (options.json) {
+      console.error("--prompt <text> is required in --json mode.");
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      revisionPrompt = await dist_default6({ message: "What should be updated?" });
+    } catch {
+      return;
+    }
+  }
+  if (!revisionPrompt) {
+    console.error("No revision prompt provided.");
+    process.exitCode = 1;
+    return;
+  }
+  const originalContent = targetDoc.content;
+  const context = `Current doc (revise this):
+${originalContent}`;
+  let result;
+  try {
+    result = await client.processDoc({
+      prompt: revisionPrompt,
+      branch,
+      commitHash,
+      repoName,
+      author,
+      context
+    });
+  } catch (error51) {
+    handleApiError(error51);
+    return;
+  }
+  if (result.docs.length === 0) {
+    console.error("AI returned no revised content.");
+    process.exitCode = 1;
+    return;
+  }
+  let current = normalizeRevisionId(result.docs[0], targetDoc.id);
+  if (options.json) {
+    console.log(JSON.stringify({ ...current, originalContent }, null, 2));
+    return;
+  }
+  while (true) {
+    console.log(`
+${renderDocBox(current)}
+`);
+    let action;
+    try {
+      action = await dist_default8({
+        message: "What would you like to do?",
+        choices: [
+          { name: "[A] Accept \u2014 save this revision", value: "accept" },
+          { name: "[R] Revise \u2014 refine with another prompt", value: "revise" },
+          { name: "[X] Reject \u2014 discard", value: "reject" }
+        ]
+      });
+    } catch {
+      return;
+    }
+    if (action === "reject") {
+      console.log("Discarded. Nothing was saved.");
+      return;
+    }
+    if (action === "accept") {
+      await persistRevision(current, targetDoc, {
+        client,
+        workingDir,
+        branch,
+        commitHash,
+        repoName,
+        options,
+        author
+      });
+      return;
+    }
+    let feedback;
+    try {
+      feedback = await dist_default6({ message: "How should I revise it?" });
+    } catch {
+      return;
+    }
+    const reviseContext = `Current draft (revise this):
+${current.content}`;
+    let revised;
+    try {
+      revised = await client.processDoc({
+        prompt: feedback,
+        branch,
+        commitHash,
+        repoName,
+        author,
+        context: reviseContext
+      });
+    } catch (error51) {
+      handleApiError(error51);
+      return;
+    }
+    if (revised.docs.length === 0) {
+      console.error("Revision produced no doc; keeping the previous draft.");
+      continue;
+    }
+    current = normalizeRevisionId(revised.docs[0], targetDoc.id);
+  }
+}
+function normalizeRevisionId(doc2, canonicalId) {
+  return {
+    ...doc2,
+    id: canonicalId,
+    frontmatter: { ...doc2.frontmatter, id: canonicalId }
+  };
+}
+async function pickDocInteractive(client) {
+  return dist_default7({
+    message: "Search docs:",
+    source: async (term) => {
+      const query = (term ?? "").trim();
+      if (query.length < 2)
+        return [];
+      try {
+        const results = await client.searchDocs({ query, limit: 10 });
+        return results.map((d) => {
+          const meta3 = typeMeta(d.type);
+          const age = formatAge(d.createdAt);
+          return {
+            name: `${meta3.emoji} ${d.title}  (${d.branch}, ${age})`,
+            value: d
+          };
+        });
+      } catch {
+        return [];
+      }
+    }
+  });
+}
+async function persistRevision(doc2, original, ctx) {
+  const noLocal = ctx.options.local === false;
+  const noCommit = ctx.options.commit === false;
+  let filePath;
+  if (noLocal) {
+    filePath = original.filePath ?? `.gitcontext/docs/${original.id}.md`;
+  } else {
+    const existing = findDocFileById(doc2.id, ctx.workingDir);
+    if (existing) {
+      try {
+        const written = overwriteDocFile(doc2, existing.absolutePath, existing.relativePath, {
+          noCommit,
+          author: ctx.author
+        });
+        filePath = written.filePath;
+        console.log(written.committed ? `\uD83D\uDCDD Revised & committed ${filePath}` : `\uD83D\uDCDD Revised ${filePath}`);
+      } catch (error51) {
+        console.error(`Failed to write file: ${error51 instanceof Error ? error51.message : String(error51)}`);
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      filePath = original.filePath ?? `.gitcontext/docs/${original.id}.md`;
+      console.log("No local file found \u2014 updating cloud DB only.");
+    }
+  }
+  try {
+    const res = await ctx.client.ingestDoc({
+      id: doc2.id,
+      type: doc2.type,
+      title: doc2.title,
+      content: doc2.content,
+      filePath,
+      storageMode: "repo",
+      branch: ctx.branch,
+      commitHash: ctx.commitHash,
+      repoName: ctx.repoName,
+      frontmatter: doc2.frontmatter,
+      revisionSource: "cli_capture"
+    });
+    console.log(`
+\u2705 Doc revised (revision ${res.revisionNumber}) \u2014 committed and live in dashboard.`);
+  } catch (error51) {
+    const message = error51 instanceof Error ? error51.message : String(error51);
+    console.warn(`\u26A0\uFE0F  Ingest failed for "${doc2.title}": ${message}`);
+    console.warn("   The file is saved locally and will reconcile at PR merge.");
+  }
+}
+function formatAge(isoDate) {
+  const ms = Date.now() - new Date(isoDate).getTime();
+  const days = Math.floor(ms / 86400000);
+  if (days === 0)
+    return "today";
+  if (days === 1)
+    return "1 day ago";
+  if (days < 30)
+    return `${days} days ago`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 8)
+    return `${weeks} week${weeks === 1 ? "" : "s"} ago`;
+  const months = Math.floor(days / 30);
+  return `${months} month${months === 1 ? "" : "s"} ago`;
+}
+
 // src/commands/status.ts
 function handleError4(error51) {
   if (error51 instanceof ApiClientError) {
@@ -42424,8 +43221,80 @@ function registerStatusCommand(program2) {
   });
 }
 
+// src/commands/teach.ts
+var TEACH_PROMPT = "Pick one interesting, surprising, or practically useful insight that a developer on this team would benefit from knowing. It could be a hard-won lesson, a subtle gotcha, a convention rationale, or a pattern worth remembering. Make it specific and actionable \u2014 not generic advice. Return it as a single 'learning' doc.";
+var DOC_TYPES4 = ["learning", "bug", "blocker", "convention", "conversation"];
+function registerTeachCommand(program2) {
+  program2.command("teach").description("Pull a surprising or useful insight from your team's captured docs via AI").option("--type <type>", "Bias toward a specific doc type").option("--repo <name>", "Scope to a specific repo").option("--branch <name>", "Scope to a specific branch").option("--json", "Output structured doc as JSON").action(async (options) => {
+    await runTeach(options);
+  });
+}
+async function runTeach(options) {
+  const config2 = readUserConfig();
+  if (!config2) {
+    console.error("Not authenticated. Run `gitcontext auth login` first.");
+    process.exitCode = 1;
+    return;
+  }
+  if (options.type && !DOC_TYPES4.includes(options.type)) {
+    console.error(`Invalid --type "${options.type}". Expected one of: ${DOC_TYPES4.join(", ")}.`);
+    process.exitCode = 1;
+    return;
+  }
+  const client = new ApiClient(config2.apiUrl, config2.userToken);
+  let me;
+  try {
+    me = await client.getMe();
+  } catch (error51) {
+    handleApiError(error51);
+    return;
+  }
+  if (me.subscription && me.subscription.monthlyAiDocLimit >= 0 && me.subscription.monthlyAiDocCount >= me.subscription.monthlyAiDocLimit) {
+    console.error(`Monthly AI doc limit reached (${me.subscription.monthlyAiDocCount}/${me.subscription.monthlyAiDocLimit}).`);
+    console.error(`Upgrade your plan to generate more docs: ${config2.apiUrl}/settings/org`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!options.json) {
+    console.log(source_default.dim(`
+  \u2726 Teaching you something\u2026
+`));
+  }
+  let promptText = TEACH_PROMPT;
+  if (options.type) {
+    promptText += ` Focus on "${options.type}" type docs.`;
+  }
+  const author = me.githubLogin ?? me.name ?? me.email ?? "unknown";
+  let result;
+  try {
+    result = await client.processDoc({
+      prompt: promptText,
+      ...options.branch ? { branch: options.branch } : {},
+      ...options.repo ? { repoName: options.repo } : {},
+      author
+    });
+  } catch (error51) {
+    handleApiError(error51);
+    return;
+  }
+  const { docs } = result;
+  if (docs.length === 0) {
+    console.error("No insight was generated. Try again.");
+    process.exitCode = 1;
+    return;
+  }
+  if (options.json) {
+    console.log(JSON.stringify({ docs }, null, 2));
+    return;
+  }
+  console.log(renderDocBox(docs[0]));
+  console.log(`
+  \uD83D\uDCA1 Run again for a different insight.
+`);
+}
+
 // src/commands/update.ts
-import { execFileSync as execFileSync6, spawnSync as spawnSync2 } from "child_process";
+import { execFileSync as execFileSync6, spawnSync as spawnSync3 } from "child_process";
 function registerUpdateCommand(program2) {
   program2.command("update").description("Re-install integration templates from the installed package").action(async () => {
     await runUpdate();
@@ -42450,6 +43319,7 @@ async function runUpdate() {
   const platforms = (config2.platforms ?? []).filter(isValidPlatform);
   if (platforms.length === 0) {
     console.log("No platforms configured. Run `gitcontext init` to set up platforms.");
+    await syncDocStorageModes(workingDir);
     return;
   }
   console.log(`Updating GitContext integration for ${platforms.join(", ")}...
@@ -42468,6 +43338,7 @@ async function runUpdate() {
   }
   if (installedFiles.length === 0) {
     console.log("No files updated.");
+    await syncDocStorageModes(workingDir);
     return;
   }
   const repoLocalPaths = installedFiles.filter((f) => !f.global).map((f) => f.path.startsWith(repoRoot) ? f.path.slice(repoRoot.length + 1) : f.path).filter((p) => !p.startsWith("/"));
@@ -42480,7 +43351,7 @@ async function runUpdate() {
       process.exitCode = 1;
       return;
     }
-    const hasStagedChanges = spawnSync2("git", ["diff", "--cached", "--quiet"], { cwd: repoRoot }).status !== 0;
+    const hasStagedChanges = spawnSync3("git", ["diff", "--cached", "--quiet"], { cwd: repoRoot }).status !== 0;
     if (!hasStagedChanges) {
       console.log("  \u2713 Files written (no new git changes to commit)");
     } else {
@@ -42507,11 +43378,146 @@ async function runUpdate() {
     const suffix = f.global ? " (global)" : "";
     console.log(`  ${prefix} ${displayPath}${suffix}`);
   }
+  await syncDocStorageModes(workingDir);
+}
+async function syncDocStorageModes(workingDir) {
+  const userConfig = readUserConfig();
+  if (!userConfig)
+    return;
+  try {
+    const client = new ApiClient(userConfig.apiUrl, userConfig.userToken, userConfig.orgId);
+    const docStorageModes = await client.getOrgDocStorageModes();
+    const validDocTypes = [
+      "learning",
+      "bug",
+      "blocker",
+      "convention",
+      "conversation",
+      "report"
+    ];
+    const typed = {};
+    for (const dt of validDocTypes) {
+      const val = docStorageModes[dt];
+      if (val === "repo" || val === "cloud") {
+        typed[dt] = val;
+      }
+    }
+    const latestConfig = readRepoConfig(workingDir);
+    if (latestConfig) {
+      writeRepoConfig(workingDir, { ...latestConfig, docStorageModes: typed });
+      console.log(`
+\u2713 Doc storage settings synced from org config`);
+    }
+  } catch (err) {
+    if (err instanceof ApiClientError) {
+      console.warn(`
+\u26A0\uFE0F  Could not sync doc storage settings: ${err.message}`);
+    }
+  }
+}
+
+// src/lib/session-alerts.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join7 } from "path";
+function getPath() {
+  return join7(homedir3(), ".gitcontext", "session-alerts.json");
+}
+function read() {
+  try {
+    const raw = readFileSync7(getPath(), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function write(data) {
+  const dir = join7(homedir3(), ".gitcontext");
+  if (!existsSync6(dir))
+    mkdirSync4(dir, { recursive: true });
+  writeFileSync4(getPath(), `${JSON.stringify(data, null, 2)}
+`, "utf-8");
+}
+function isToday(isoTimestamp) {
+  const d = new Date(isoTimestamp);
+  const now = new Date;
+  return d.getUTCFullYear() === now.getUTCFullYear() && d.getUTCMonth() === now.getUTCMonth() && d.getUTCDate() === now.getUTCDate();
+}
+function shouldCheckToday(key) {
+  const ts = read()[key];
+  return !ts || !isToday(ts);
+}
+function markChecked(key) {
+  const data = read();
+  data[key] = new Date().toISOString();
+  write(data);
+}
+function getLastSeenVersion() {
+  return read().lastSeenVersion ?? null;
+}
+function setLastSeenVersion(version2) {
+  const data = read();
+  data.lastSeenVersion = version2;
+  write(data);
+}
+
+// src/lib/update-check.ts
+function parseSemver(v) {
+  const parts = v.split(".").map(Number);
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+function isNewerVersion(candidate, current) {
+  const [caMaj, caMin, caPatch] = parseSemver(candidate);
+  const [cuMaj, cuMin, cuPatch] = parseSemver(current);
+  if (caMaj !== cuMaj)
+    return caMaj > cuMaj;
+  if (caMin !== cuMin)
+    return caMin > cuMin;
+  return caPatch > cuPatch;
+}
+async function fetchLatestNpmVersion(packageName) {
+  try {
+    const controller = new AbortController;
+    const id = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`, { signal: controller.signal });
+    clearTimeout(id);
+    if (!res.ok)
+      return null;
+    const data = await res.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  }
+}
+function parseMarkdownBullets2(notes) {
+  return notes.split(`
+`).map((line) => line.trim()).filter((line) => /^[-*+]\s+/.test(line)).map((line) => line.replace(/^[-*+]\s+/, ""));
+}
+async function fetchChangelogNotes(apiUrl) {
+  try {
+    const controller = new AbortController;
+    const id = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`${apiUrl.replace(/\/$/, "")}/api/changelog/latest?package=cli`, {
+      signal: controller.signal
+    });
+    clearTimeout(id);
+    if (!res.ok)
+      return null;
+    const data = await res.json();
+    if (typeof data.notes !== "string" || !data.notes)
+      return null;
+    const lines = parseMarkdownBullets2(data.notes);
+    return lines.length > 0 ? lines : null;
+  } catch {
+    return null;
+  }
 }
 
 // src/index.ts
+var PACKAGE_NAME = "@fentech/gitcontext";
+var VERSION = package_default.version;
 var program2 = new Command;
-program2.name("gitcontext").description("GitContext CLI \u2014 capture, sync, and query git-backed knowledge docs").version("0.1.0").option("--profile <name>", "Auth profile to use for this invocation (overrides active profile)");
+program2.name("gitcontext").description("GitContext CLI \u2014 capture, sync, and query git-backed knowledge docs").version(VERSION).option("--profile <name>", "Auth profile to use for this invocation (overrides active profile)");
 program2.hook("preAction", () => {
   const opts = program2.opts();
   setProfileOverride(opts.profile);
@@ -42519,8 +43525,100 @@ program2.hook("preAction", () => {
     console.log(source_default.dim(`Using ${getActiveProfileName() ?? "prod"} profile`));
   }
 });
+function printUpdateAvailableBanner(current, latest) {
+  const lines = [
+    source_default.bold.yellow(`  gitcontext update available: ${current} \u2192 ${latest}`),
+    `  Run: ${source_default.cyan(`npm install -g ${PACKAGE_NAME}`)}`
+  ];
+  renderBox(lines);
+}
+var MAX_WHATS_NEW_NOTES = 8;
+function printWhatsNewBanner(version2, notes) {
+  const lines = [];
+  lines.push(source_default.bold.cyan(`  \u2728 What's new in gitcontext ${version2}`));
+  if (notes && notes.length > 0) {
+    const displayed = notes.slice(0, MAX_WHATS_NEW_NOTES);
+    const overflow = notes.length - displayed.length;
+    for (const note of displayed) {
+      lines.push(`  ${source_default.dim("\u2022")} ${note}`);
+    }
+    if (overflow > 0) {
+      lines.push(`  ${source_default.dim(`\u2026and ${overflow} more`)}`);
+    }
+  }
+  lines.push(`  ${source_default.dim(`Full changelog: ${source_default.cyan("gitcontext changelog")}`)}`);
+  renderBox(lines);
+}
+function renderBox(lines) {
+  const width = Math.max(...lines.map((l) => stripAnsi(l).length)) + 2;
+  const top = `\u256D${"\u2500".repeat(width)}\u256E`;
+  const bottom = `\u2570${"\u2500".repeat(width)}\u256F`;
+  const pad = (s) => {
+    const visible = stripAnsi(s).length;
+    return `\u2502${s}${" ".repeat(width - visible)}\u2502`;
+  };
+  process.stderr.write(`
+${top}
+${lines.map(pad).join(`
+`)}
+${bottom}
+`);
+}
+function stripAnsi(s) {
+  return s.replace(/\x1B\[[0-9;]*m/g, "");
+}
+program2.hook("postAction", async (_thisCommand, actionCommand) => {
+  const cmdName = actionCommand.name();
+  const parentName = actionCommand.parent?.name();
+  const isAuthLoginOrLogout = parentName === "auth" && (cmdName === "login" || cmdName === "logout");
+  const tasks = [];
+  if (shouldCheckToday("updateCheckedAt")) {
+    markChecked("updateCheckedAt");
+    tasks.push((async () => {
+      const lastSeen = getLastSeenVersion();
+      if (lastSeen !== null && isNewerVersion(VERSION, lastSeen)) {
+        const profile = readActiveProfile();
+        const apiUrl = profile?.apiUrl ?? "https://app.gitcontext.app";
+        const notes = await fetchChangelogNotes(apiUrl);
+        printWhatsNewBanner(VERSION, notes);
+        setLastSeenVersion(VERSION);
+        return;
+      }
+      if (lastSeen === null) {
+        setLastSeenVersion(VERSION);
+        return;
+      }
+      const latest = await fetchLatestNpmVersion(PACKAGE_NAME);
+      if (latest && isNewerVersion(latest, VERSION)) {
+        printUpdateAvailableBanner(VERSION, latest);
+      }
+    })());
+  }
+  if (!isAuthLoginOrLogout && readUserConfig() && shouldCheckToday("usageCheckedAt")) {
+    markChecked("usageCheckedAt");
+    tasks.push((async () => {
+      try {
+        const me = getCachedMe() ?? await ApiClient.fromUserConfig().getMe();
+        const sub = me.subscription;
+        if (sub && sub.monthlyAiDocLimit > 0) {
+          const ratio = sub.monthlyAiDocCount / sub.monthlyAiDocLimit;
+          if (ratio >= 0.9) {
+            const pct = Math.round(ratio * 100);
+            const profile = readActiveProfile();
+            const appUrl = profile?.apiUrl ?? "https://app.gitcontext.app";
+            process.stderr.write(source_default.yellow(`
+\u26A0  AI doc usage: ${sub.monthlyAiDocCount}/${sub.monthlyAiDocLimit} (${pct}%) \u2014 upgrade at ${appUrl}/settings/org
+`));
+          }
+        }
+      } catch {}
+    })());
+  }
+  await Promise.all(tasks);
+});
 registerAnalyzeCommand(program2);
 registerAuthCommand(program2);
+registerChangelogCommand(program2);
 registerBackfillCommand(program2);
 registerCaptureCommand(program2);
 registerDocsCommand(program2);
@@ -42529,7 +43627,9 @@ registerStatusCommand(program2);
 registerInitCommand(program2);
 registerUpdateCommand(program2);
 registerPushCommand(program2);
+registerReviseCommand(program2);
 registerMcpCommand(program2);
+registerTeachCommand(program2);
 program2.parseAsync(process.argv).catch((error51) => {
   const message = error51 instanceof Error ? error51.message : String(error51);
   console.error(message);