carto-md 2.1.0 → 2.1.1

package/src/brain/conventions/index.js

@@ -4,13 +4,18 @@
  * Semantic Memory — convention learning.
  *
  * Mines conventions from the static index:
- *   - File naming patterns per directory (e.g. *.service.ts)
- *   - Import bundles that co-occur (e.g. `useState` always with `useEffect`)
+ *   - Identifier-case naming per directory + extension (PascalCase components,
+ *     camelCase utils, kebab-case files, …) — the actionable one for scaffolding.
+ *   - File naming suffix patterns per directory (e.g. *.service.ts, *.config.*)
  *   - Export style (default vs named) per domain
- *   - Domain co-location (file X and file Y always live in same domain)
+ *   - Directory language (e.g. src/* is all TypeScript)
  *
- * Each convention has a confidence score; only conventions with confidence
- * >= 0.75 are returned by default.
+ * Each convention carries a `confidence` (0–1) and a derived `strength`
+ * (`high` ≥ 0.9, `medium` ≥ threshold). By default only conventions at or
+ * above `threshold` (0.75) are returned, so the caller never sees a rule the
+ * evidence doesn't support. When nothing clears the bar the caller gets an
+ * empty list and the formatter says so honestly, rather than emitting a
+ * misleading low-confidence "rule".
  *
  * Consumed by:
  *   - `get_conventions(file_or_dir)` — what conventions apply to this file
@@ -20,22 +25,102 @@
 const path = require('path');
 
 const DEFAULT_THRESHOLD = 0.75;
+const MIN_EVIDENCE = 4; // need at least this many files before a pattern is a "convention"
+
+function strengthOf(conf) {
+  return conf >= 0.9 ? 'high' : 'medium';
+}
+
+/**
+ * Classify an identifier (a filename without its extension) into a case style.
+ * Returns null for names we don't want to vote on (empty, dotfiles, purely
+ * numeric, or single ambiguous lowercase words like `index`/`utils` that carry
+ * no style signal).
+ */
+function classifyCase(name) {
+  if (!name) return null;
+  // Strip a leading dot for dotfiles like `.eslintrc` — no naming signal.
+  if (name.startsWith('.')) return null;
+  if (/^\d+$/.test(name)) return null;
+
+  if (name.includes('-') && /^[a-z0-9]+(-[a-z0-9]+)+$/.test(name)) return 'kebab-case';
+  if (name.includes('_') && /^[a-z0-9]+(_[a-z0-9]+)+$/.test(name)) return 'snake_case';
+  // PascalCase: starts uppercase, has a lowercase letter somewhere (excludes
+  // SCREAMING_CONST-style and single-letter tokens).
+  if (/^[A-Z][A-Za-z0-9]*$/.test(name) && /[a-z]/.test(name)) return 'PascalCase';
+  // camelCase: starts lowercase, has at least one uppercase hump.
+  if (/^[a-z][A-Za-z0-9]*$/.test(name) && /[A-Z]/.test(name)) return 'camelCase';
+  // Single all-lowercase word (index, utils, types, page) — ambiguous, skip.
+  return null;
+}
 
 /**
  * mineConventions(store, opts) → Array<convention>
  *
  * Each convention:
- *   { id, kind, scope, rule, confidence, evidence_count }
+ *   { id, kind, scope, rule, confidence, strength, evidence_count, ext? }
  */
 function mineConventions(store, { threshold = DEFAULT_THRESHOLD } = {}) {
   if (!store || !store.db) return [];
   const out = [];
+  out.push(...mineCaseStyleConventions(store, { threshold }));
   out.push(...mineNamingConventions(store, { threshold }));
   out.push(...mineExportConventions(store, { threshold }));
   out.push(...mineDirectoryConventions(store, { threshold }));
   return out;
 }
 
+/**
+ * Per (directory, extension): the dominant identifier-case of the file names.
+ * This is the convention an AI actually needs when it's told "add a component
+ * to apps/studio/components/grid" — it should learn those files are PascalCase
+ * .tsx, not merely that the directory is "typescript".
+ */
+function mineCaseStyleConventions(store, { threshold }) {
+  const rows = store.db.prepare('SELECT path FROM files').all();
+  // Map<dir, Map<ext, Map<style, count>>> plus a classified-total per (dir,ext).
+  const byDirExt = new Map();
+  for (const r of rows) {
+    const dir = path.posix.dirname(r.path);
+    const base = path.posix.basename(r.path);
+    const ext = path.posix.extname(base); // includes leading dot, '' if none
+    const stem = ext ? base.slice(0, -ext.length) : base;
+    const style = classifyCase(stem);
+    if (!style) continue;
+    if (!byDirExt.has(dir)) byDirExt.set(dir, new Map());
+    const extMap = byDirExt.get(dir);
+    if (!extMap.has(ext)) extMap.set(ext, new Map());
+    const styleMap = extMap.get(ext);
+    styleMap.set(style, (styleMap.get(style) || 0) + 1);
+  }
+
+  const out = [];
+  for (const [dir, extMap] of byDirExt) {
+    for (const [ext, styleMap] of extMap) {
+      const total = Array.from(styleMap.values()).reduce((a, b) => a + b, 0);
+      if (total < MIN_EVIDENCE) continue;
+      let topStyle = null, topCount = 0;
+      for (const [style, c] of styleMap) {
+        if (c > topCount) { topStyle = style; topCount = c; }
+      }
+      const conf = topCount / total;
+      if (conf < threshold) continue;
+      const extLabel = ext || '(no ext)';
+      out.push({
+        id: `case_${dir}_${ext}_${topStyle}`,
+        kind: 'naming_case',
+        scope: dir,
+        ext,
+        rule: `${extLabel} files in ${dir}/ are typically named ${topStyle} (${topCount}/${total}).`,
+        confidence: Math.round(conf * 100) / 100,
+        strength: strengthOf(conf),
+        evidence_count: topCount,
+      });
+    }
+  }
+  return out;
+}
+
 function mineNamingConventions(store, { threshold }) {
   // Look for filename suffix patterns within each directory.
   // E.g. if 8/10 files in src/services match *.service.ts → convention.
@@ -49,7 +134,7 @@ function mineNamingConventions(store, { threshold }) {
 
   const out = [];
   for (const [dir, files] of byDir) {
-    if (files.length < 4) continue;
+    if (files.length < MIN_EVIDENCE) continue;
     // Count suffix patterns: tokenize on '.' from the end, look for the
     // second-from-last token (`*.service.ts` → 'service').
     const suffixCounts = new Map();
@@ -66,8 +151,9 @@ function mineNamingConventions(store, { threshold }) {
           id: `naming_${dir}_${suffix}`,
           kind: 'filename_suffix',
           scope: dir,
-          rule: `Files in ${dir}/ typically match *.${suffix}.*`,
+          rule: `Files in ${dir}/ typically match *.${suffix}.* (${count}/${files.length}).`,
           confidence: Math.round(conf * 100) / 100,
+          strength: strengthOf(conf),
           evidence_count: count,
         });
       }
@@ -98,18 +184,22 @@ function mineExportConventions(store, { threshold }) {
         id: `export_${r.domain_name}_default`,
         kind: 'export_style',
         scope: r.domain_name,
-        rule: `${r.domain_name} files typically use default exports.`,
+        rule: `${r.domain_name} files typically use default exports (${r.defaults}/${r.total}).`,
         confidence: Math.round(defaultRatio * 100) / 100,
+        strength: strengthOf(defaultRatio),
         evidence_count: r.defaults,
       });
     } else if ((1 - defaultRatio) >= threshold) {
+      const namedRatio = 1 - defaultRatio;
+      const named = r.total - (r.defaults || 0);
       out.push({
         id: `export_${r.domain_name}_named`,
         kind: 'export_style',
         scope: r.domain_name,
-        rule: `${r.domain_name} files typically use named exports.`,
-        confidence: Math.round((1 - defaultRatio) * 100) / 100,
-        evidence_count: r.total - (r.defaults || 0),
+        rule: `${r.domain_name} files typically use named exports (${named}/${r.total}).`,
+        confidence: Math.round(namedRatio * 100) / 100,
+        strength: strengthOf(namedRatio),
+        evidence_count: named,
       });
     }
   }
@@ -149,8 +239,9 @@ function mineDirectoryConventions(store, { threshold }) {
         id: `dir_lang_${prefix}_${topLang}`,
         kind: 'directory_language',
         scope: prefix,
-        rule: `${prefix}/ is predominantly ${topLang}.`,
+        rule: `${prefix}/ is predominantly ${topLang} (${topCount}/${total}).`,
         confidence: Math.round(conf * 100) / 100,
+        strength: strengthOf(conf),
         evidence_count: topCount,
       });
     }
@@ -158,28 +249,51 @@ function mineDirectoryConventions(store, { threshold }) {
   return out;
 }
 
+/**
+ * True when `filePath` lives in directory `scope` or any subdirectory of it.
+ */
+function underScope(filePath, scope) {
+  const dir = path.posix.dirname(filePath);
+  return dir === scope || dir.startsWith(scope + '/');
+}
+
 /**
  * conventionsForFile(store, filePath, opts) → Array<convention>
  *
- * Returns the subset of conventions whose `scope` matches `filePath`.
+ * Returns the subset of conventions whose `scope` matches `filePath`, sorted by
+ * confidence (desc) so the strongest, most specific guidance comes first.
  * Used by `get_conventions(file_or_dir)`.
  */
 function conventionsForFile(store, filePath, opts = {}) {
   if (!filePath) return [];
   const all = mineConventions(store, opts);
-  const dir = path.posix.dirname(filePath);
-  return all.filter(c => {
-    if (c.kind === 'filename_suffix') return c.scope === dir;
+  const ext = path.posix.extname(filePath);
+  const matched = all.filter(c => {
+    if (c.kind === 'naming_case') {
+      // Match same-extension case conventions in this dir or an ancestor dir.
+      return (!c.ext || c.ext === ext) && underScope(filePath, c.scope);
+    }
+    if (c.kind === 'filename_suffix') return underScope(filePath, c.scope);
     if (c.kind === 'directory_language') return filePath.startsWith(c.scope + '/');
     if (c.kind === 'export_style') {
       // Match if the file belongs to the domain in `scope`.
+      const domain = store.getDomainOf ? store.getDomainOf(filePath) : null;
+      if (domain) return domain === c.scope;
+      // Fallback for older stores without getDomainOf.
       const file = store.getFileByPath(filePath);
       if (!file || !file.domain_id) return false;
-      const domain = store.db.prepare('SELECT name FROM domains WHERE id = ?').get(file.domain_id);
-      return domain && domain.name === c.scope;
+      const d = store.db.prepare('SELECT name FROM domains WHERE id = ?').get(file.domain_id);
+      return d && d.name === c.scope;
     }
     return false;
   });
+  matched.sort((a, b) => (b.confidence - a.confidence));
+  return matched;
 }
 
-module.exports = { mineConventions, conventionsForFile, DEFAULT_THRESHOLD };
+module.exports = {
+  mineConventions,
+  conventionsForFile,
+  classifyCase,
+  DEFAULT_THRESHOLD,
+};

package/src/brain/invariants/index.js

@@ -195,53 +195,107 @@ function mineDomainNamingInvariants(store, { threshold, domain }) {
   return out;
 }
 
+// Path fragments that mark a file as a demo / example / test / fixture — never a
+// canonical exemplar, even if it declares many routes or models. Matched as
+// directory-segment substrings (SQL LIKE '%/frag/%') so we don't accidentally
+// exclude a legitimate file whose name merely contains one of these words.
+const NON_CANONICAL_PATH_FRAGMENTS = [
+  'demo', 'demos',
+  'example', 'examples',
+  'sample', 'samples',
+  'test', 'tests', '__tests__',
+  'fixture', 'fixtures',
+  'mock', 'mocks', '__mocks__',
+];
+
+// Build the reusable "exclude junk paths" SQL fragment + params.
+function nonCanonicalPathFilter() {
+  const clauses = NON_CANONICAL_PATH_FRAGMENTS.map(() => 'f.path NOT LIKE ?');
+  const params = NON_CANONICAL_PATH_FRAGMENTS.map((frag) => `%/${frag}/%`);
+  return { sql: clauses.join(' AND '), params };
+}
+
 /**
  * getCanonicalPattern(store, { pattern_type }) → { type, examples, confidence }
  *
  * Returns the canonical example of a high-level pattern. Used by
  * `scaffold_for_intent` to find templates the AI should copy.
+ *
+ * The exemplar must be *well-connected* and *real*, not a stray demo/proxy
+ * route with zero dependents (see CF-4). We therefore:
+ *   1. Require `centrality > 0` (the file must actually be depended on).
+ *   2. Exclude demo/example/test/fixture/mock paths.
+ *   3. Rank by `count × log(dependents + 1)` — rewarding both multi-route/
+ *      multi-model files and non-trivial blast radius, instead of the old
+ *      raw `count DESC, centrality DESC` sort where a 1-route, 0-dependent
+ *      file could win.
  */
 function getCanonicalPattern(store, { pattern_type, domain = null } = {}) {
   if (!store || !store.db || !pattern_type) return null;
 
+  // Higher weight on blast radius is more discriminating than raw count alone,
+  // so rank on count × ln(dependents + 1). Ties break on count then centrality.
+  const score = (count, centrality) => count * Math.log((centrality || 0) + 1);
+  const pickBest = (rows) => {
+    let best = null;
+    for (const row of rows) {
+      row._score = score(row._count, row.centrality);
+      if (
+        !best ||
+        row._score > best._score ||
+        (row._score === best._score && row._count > best._count) ||
+        (row._score === best._score && row._count === best._count && row.centrality > best.centrality)
+      ) {
+        best = row;
+      }
+    }
+    return best;
+  };
+
+  const pathFilter = nonCanonicalPathFilter();
+
   if (pattern_type === 'route_handler') {
-    // Find the file with the most routes that also has high blast_radius
-    // — that's likely the canonical handler.
-    const row = store.db.prepare(`
-      SELECT f.path, f.centrality, COUNT(r.id) as route_count
+    // Candidate route-declaring files: must have >0 dependents and not live
+    // under a demo/example/test/fixture path.
+    const rows = store.db.prepare(`
+      SELECT f.path, f.centrality, COUNT(r.id) as _count
       FROM files f
       JOIN routes r ON r.file_id = f.id
-      ${domain ? 'JOIN domains d ON f.domain_id = d.id WHERE d.name = ?' : ''}
+      ${domain ? 'JOIN domains d ON f.domain_id = d.id' : ''}
+      WHERE f.centrality > 0
+        AND ${pathFilter.sql}
+        ${domain ? 'AND d.name = ?' : ''}
       GROUP BY f.id
-      ORDER BY route_count DESC, f.centrality DESC
-      LIMIT 1
-    `).get(...(domain ? [domain] : []));
-    if (!row) return null;
+    `).all(...pathFilter.params, ...(domain ? [domain] : []));
+    const best = pickBest(rows);
+    if (!best) return null;
     return {
       type: 'route_handler',
-      file: row.path,
-      route_count: row.route_count,
-      blast_radius: row.centrality,
+      file: best.path,
+      route_count: best._count,
+      blast_radius: best.centrality,
       confidence: 0.9,
     };
   }
 
   if (pattern_type === 'model_definition') {
-    const row = store.db.prepare(`
-      SELECT f.path, f.centrality, COUNT(m.id) as model_count
+    const rows = store.db.prepare(`
+      SELECT f.path, f.centrality, COUNT(m.id) as _count
       FROM files f
       JOIN models m ON m.file_id = f.id
-      ${domain ? 'JOIN domains d ON f.domain_id = d.id WHERE d.name = ?' : ''}
+      ${domain ? 'JOIN domains d ON f.domain_id = d.id' : ''}
+      WHERE f.centrality > 0
+        AND ${pathFilter.sql}
+        ${domain ? 'AND d.name = ?' : ''}
       GROUP BY f.id
-      ORDER BY model_count DESC
-      LIMIT 1
-    `).get(...(domain ? [domain] : []));
-    if (!row) return null;
+    `).all(...pathFilter.params, ...(domain ? [domain] : []));
+    const best = pickBest(rows);
+    if (!best) return null;
     return {
       type: 'model_definition',
-      file: row.path,
-      model_count: row.model_count,
-      blast_radius: row.centrality,
+      file: best.path,
+      model_count: best._count,
+      blast_radius: best.centrality,
       confidence: 0.85,
     };
   }

package/src/cli/anci.js

@@ -134,8 +134,20 @@ function runShow(projectRoot) {
   lines.push('');
   lines.push(`  spec version    : ${h.anci.version}`);
   lines.push(`  generator       : ${h.anci.generator}`);
+  lines.push(`  carto version   : ${h.anci.carto_version || 'n/a'}`);
   lines.push(`  generated_at    : ${h.anci.generated_at}`);
   lines.push(`  body file       : ${h.anci.body.file} (${formatBytes(h.anci.body.bytes)})`);
+  if (h.anci.body && h.anci.body.content_digest) {
+    lines.push(`  content digest  : ${h.anci.body.content_digest}`);
+  }
+  if (Array.isArray(h.anci.contains) && h.anci.contains.length) {
+    lines.push(`  contains        : ${h.anci.contains.join(', ')}`);
+  }
+  if (h.source && (h.source.commit || h.source.branch)) {
+    const commit = h.source.commit ? h.source.commit.slice(0, 12) : 'n/a';
+    const branch = h.source.branch ? ` (${h.source.branch})` : '';
+    lines.push(`  source commit   : ${commit}${branch}`);
+  }
   lines.push('');
   if (h.project) {
     lines.push('Project');
@@ -223,7 +235,21 @@ function runValidate(dir) {
     }
   }
 
-  console.log(`[CARTO] ANCI valid: ${header.anci.version}, ${body.size} files indexed.`);
+  // Integrity: verify the content digest when the header declares one
+  // (CT-1). A mismatch means the body was altered after the manifest was
+  // written — fail loudly.
+  const { verifyBodyDigest } = require('../anci/consumer');
+  const digest = verifyBodyDigest(header, bodyBuf);
+  if (digest && digest.ok === false) {
+    console.error(
+      `[CARTO] content digest mismatch: header declares ${digest.expected}, ` +
+      `body hashes to ${digest.actual}`
+    );
+    return 1;
+  }
+
+  const digestNote = digest ? ' (digest verified)' : '';
+  console.log(`[CARTO] ANCI valid: ${header.anci.version}, ${body.size} files indexed.${digestNote}`);
   return 0;
 }
 

package/src/cli/doctor.js

@@ -143,6 +143,38 @@ function diagnose(projectRoot) {
     });
   }
 
+  // ─── Index staleness vs git HEAD (CT-1b) ────────────────────────
+  // The ANCI manifest records the commit the index was built from. If
+  // HEAD has moved (or the working tree is dirty), the index serves
+  // numbers from an older repo state — warn with the sync fix.
+  try {
+    const { computeStaleness, stalenessBanner } = require('../anci/staleness');
+    const st = computeStaleness(projectRoot, { cartoDir });
+    const banner = stalenessBanner(st);
+    if (banner) {
+      results.push({
+        id: 'index-staleness',
+        status: 'warn',
+        label: 'Index freshness',
+        detail: st.status === 'behind'
+          ? `${st.commitsBehind == null ? 'several' : st.commitsBehind} commit(s) behind HEAD` +
+            (st.uncommitted ? ` + ${st.uncommitted} uncommitted` : '')
+          : st.status === 'diverged'
+            ? 'built from a commit not in the current history'
+            : `${st.uncommitted} uncommitted file(s) since the index was built`,
+        fix: 'Run `carto sync` to refresh the index to the current HEAD.',
+      });
+    } else if (st.status === 'fresh') {
+      results.push({
+        id: 'index-staleness',
+        status: 'ok',
+        label: 'Index freshness',
+        detail: 'index matches current git HEAD',
+      });
+    }
+    // status 'unknown' → stay quiet (no manifest / non-git / can't tell).
+  } catch { /* staleness is best-effort — never break doctor */ }
+
   // ─── Git hooks ──────────────────────────────────────────────────
   const gitDir = path.join(projectRoot, '.git');
   if (fs.existsSync(gitDir)) {
@@ -174,6 +206,43 @@ function diagnose(projectRoot) {
     });
   }
 
+  // ─── Temporal store populated ───────────────────────────────────
+  // A fresh `carto init` auto-backfills git history (CF-1). If the store
+  // is empty (0 commits) but this IS a git repo, the history-based tools
+  // (drift, hotspots, velocity, predictive_risk, scaffold_for_intent) will
+  // silently return nothing — warn with the manual fix.
+  if (fs.existsSync(gitDir)) {
+    let temporalCommits = null; // null = couldn't read
+    try {
+      const { TemporalStore } = require('../temporal/store');
+      const ts = TemporalStore.openIfExists(projectRoot, { readonly: true });
+      if (ts) {
+        try { temporalCommits = ts.countCommits(); } finally { ts.close(); }
+      } else {
+        temporalCommits = 0; // no temporal db at all
+      }
+    } catch { temporalCommits = null; }
+
+    if (temporalCommits === 0) {
+      results.push({
+        id: 'temporal-store',
+        status: 'warn',
+        label: 'Temporal history',
+        detail: 'empty — history-based tools (drift, hotspots, velocity, predictive risk) will return nothing',
+        fix: 'Run `carto temporal init` to backfill git history (or re-run `carto init`, which now backfills automatically).',
+      });
+    } else if (temporalCommits > 0) {
+      results.push({
+        id: 'temporal-store',
+        status: 'ok',
+        label: 'Temporal history',
+        detail: `${temporalCommits} commit${temporalCommits === 1 ? '' : 's'} backfilled`,
+      });
+    }
+    // temporalCommits === null → couldn't read; stay quiet rather than
+    // emit a confusing check.
+  }
+
   // ─── .cartoignore conflicts ─────────────────────────────────────
   const cartoIgnore = path.join(projectRoot, '.cartoignore');
   if (fs.existsSync(cartoIgnore)) {

package/src/cli/export.js

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * `carto export [--out <file.anci>]`
+ *
+ * Packs the project's ANCI pair (`.carto/anci.{yaml,bin}`) into ONE
+ * portable single-file container (`project.anci` by default) that can be
+ * copied to another machine and loaded with `carto load` — with NO
+ * re-index. This is the "build once, load anywhere" half of CT-3.
+ *
+ * If the ANCI files don't exist yet but an index does, they are emitted
+ * first (same code path as `carto anci publish`) so `carto export` works
+ * immediately after `carto init` without a manual publish step.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { packFromCartoDir } = require('../anci/pack');
+const { ANCI_BIN_FILENAME, ANCI_YAML_FILENAME } = require('../anci/serialize');
+
+function printUsage() {
+  console.log(`
+Usage: carto export [--out <file.anci>]
+
+Pack .carto/anci.{yaml,bin} into a single portable container file.
+Copy the file to another machine and \`carto load\` it — no re-index.
+
+Options:
+  --out <file>   Output path (default: project.anci in the cwd).
+  --help, -h     Show this help.
+`);
+}
+
+/**
+ * run({ argv }) → exit code (0 ok, 1 error).
+ */
+function run({ argv }) {
+  let outPath = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { printUsage(); return 0; }
+    else if (a === '--out' || a === '-o') { outPath = argv[++i]; }
+    else if (a.startsWith('--out=')) { outPath = a.slice('--out='.length); }
+    else { console.error(`[CARTO] export: unknown argument ${a}`); printUsage(); return 1; }
+  }
+
+  const projectRoot = process.cwd();
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  const yamlPath = path.join(cartoDir, ANCI_YAML_FILENAME);
+  const binPath = path.join(cartoDir, ANCI_BIN_FILENAME);
+
+  // Ensure ANCI files exist; emit them from the index if not.
+  if (!fs.existsSync(yamlPath) || !fs.existsSync(binPath)) {
+    if (!fs.existsSync(dbPath)) {
+      console.error(`[CARTO] No index found at ${dbPath}. Run \`carto init\` first.`);
+      return 1;
+    }
+    try {
+      emitFromIndex(projectRoot, cartoDir);
+    } catch (err) {
+      console.error(`[CARTO] export: failed to emit ANCI from index: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (!outPath) outPath = path.join(projectRoot, 'project.anci');
+
+  let packed;
+  try {
+    packed = packFromCartoDir(cartoDir);
+  } catch (err) {
+    console.error(`[CARTO] export: ${err.message}`);
+    return 1;
+  }
+
+  try {
+    const tmp = outPath + '.tmp';
+    fs.writeFileSync(tmp, packed);
+    fs.renameSync(tmp, outPath);
+  } catch (err) {
+    console.error(`[CARTO] export: failed to write ${outPath}: ${err.message}`);
+    return 1;
+  }
+
+  // Report identity so the operator can verify the container.
+  let digest = null, sourceCommit = null;
+  try {
+    const yaml = require('../anci/yaml');
+    const header = yaml.parse(fs.readFileSync(yamlPath, 'utf-8'));
+    digest = header && header.anci && header.anci.body && header.anci.body.content_digest;
+    sourceCommit = header && header.source && header.source.commit;
+  } catch { /* best-effort */ }
+
+  console.log(`[CARTO] Exported container → ${path.relative(projectRoot, outPath)} (${formatBytes(packed.length)})`);
+  if (digest) console.log(`  content digest : ${digest}`);
+  if (sourceCommit) console.log(`  source commit  : ${sourceCommit.slice(0, 12)}`);
+  console.log(`  load with      : carto load ${path.basename(outPath)}`);
+  return 0;
+}
+
+/**
+ * emitFromIndex(projectRoot, cartoDir) — re-emit anci.{yaml,bin} from the
+ * existing SQLite index + bitmap sidecar. Mirrors `carto anci publish`.
+ */
+function emitFromIndex(projectRoot, cartoDir) {
+  const { SQLiteStore } = require('../store/sqlite-store');
+  const { ensureBitmapFresh } = require('../bitmap/index');
+  const { emitToCartoDir } = require('../anci/emit');
+
+  const store = new SQLiteStore(projectRoot);
+  store.open();
+  try {
+    const sidecar = ensureBitmapFresh(cartoDir, store);
+    emitToCartoDir({ cartoDir, sidecar, store });
+  } finally {
+    try { store.close(); } catch {}
+  }
+}
+
+function formatBytes(n) {
+  if (n === null || n === undefined) return 'n/a';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+module.exports = { run };

package/src/cli/index.js

@@ -11,6 +11,8 @@ Commands:
   init          Detect project, write .carto/config.json, run first sync.
                 Installs git hooks (pre-commit, post-checkout, post-merge,
                 post-rewrite) so the index stays fresh on every git event.
+                Auto-backfills temporal history from git (bounded to the
+                last 200 commits). Pass --no-temporal to skip the backfill.
   sync          Read .carto/config.json, run one sync, exit
   watch         (Optional) Start file watcher for sub-second freshness.
                 Not required — git hooks + lazy MCP re-parse keep the
@@ -46,6 +48,14 @@ Commands:
   anci          ANCI v0.1 DRAFT export. Subcommands: publish, show,
                 validate. Writes/reads .carto/anci.{yaml,bin} — the
                 public, tool-neutral architecture description spec.
+  export        Pack .carto/anci.{yaml,bin} into a single portable
+                container file (project.anci). Copy it to another
+                machine and \`carto load\` it — no re-index.
+                Options: --out <file.anci>.
+  load <file>   Unpack a portable .anci container into a queryable
+                .carto/ with NO re-index; verifies the content digest.
+                Loaded contents are treated as untrusted data, never
+                instructions. Options: --into <dir>, --no-verify.
   temporal      Architectural history. Subcommands: init (backfill from
                 git), status, events. Powers temporal MCP tools (drift,
                 hotspots, evolution, complexity, churn, arch_events,
@@ -74,7 +84,7 @@ if (!command || command === '--help' || command === '-h') {
 }
 
 if (command === 'init') {
-  require('./init').run(process.cwd()).catch(err => {
+  require('./init').run(process.cwd(), { argv: process.argv.slice(3) }).catch(err => {
     console.error(`[CARTO] Fatal error: ${err.message}`);
     process.exit(1);
   });
@@ -170,6 +180,14 @@ if (command === 'init') {
   // anci has its own subcommand parser; pass argv after `carto anci`.
   const code = require('./anci').run({ argv: process.argv.slice(3) });
   process.exit(code);
+} else if (command === 'export') {
+  // `carto export [--out <file.anci>]` — pack ANCI into one file.
+  const code = require('./export').run({ argv: process.argv.slice(3) });
+  process.exit(code);
+} else if (command === 'load') {
+  // `carto load <file.anci> [--into <dir>]` — unpack, no re-index.
+  const code = require('./load').run({ argv: process.argv.slice(3) });
+  process.exit(code);
 } else if (command === 'temporal') {
   // `carto temporal <subcmd>` — temporal history layer.
   require('./temporal').main(process.argv.slice(3)).catch(err => {