scopecairn 0.2.0 → 0.3.0

package/README.md

@@ -1,12 +1,36 @@
 # ScopeCairn
 
 Local-first codebase intelligence layer for AI coding agents.
-Builds a knowledge graph of your repository, retrieves only the context
-relevant to the current task, analyzes change impact, and enforces
-minimal-work scope. No MCP server, no embeddings, no network calls.
+Understand the codebase, then give the agent only what it needs:
+a knowledge graph of the repository, the relevant context per task,
+change impact analysis, and enforced minimal-work scope.
+No MCP server, no embeddings, no network calls, no telemetry.
 
 > Understand before exploring. Retrieve before reading.
 
+## Features
+
+- **Knowledge graph** — files, symbols (functions, classes, methods,
+  interfaces, components, routes, models…), and typed relations
+  (`IMPORTS`, `CALLS`, `EXTENDS`, `TESTS`, `ROUTES_TO`, `QUERIES`…)
+  in local SQLite, fully deterministic.
+- **Graph retrieval, no embeddings** — token-matched seeds → weighted
+  expansion → 5-signal ranking (seed, proximity, centrality, git
+  recency, co-change). Weights configurable, calibrated by benchmark.
+- **Task scope control** — every complex task returns Required /
+  Optional / Protected file lists plus Task Guard rules and a
+  Definition of Done, so the agent changes only what matters.
+- **Change impact** — direct, indirect (2-hop), tests, and UI components
+  affected by a file or symbol.
+- **Auto-refresh** — `context` and `impact` re-index changed files first;
+  run `scan` after editing to close the loop.
+- **Framework adapters** — Next.js (App + Pages Router routes),
+  Prisma models, and Drizzle tables/queries detected automatically.
+- **Multi-language** — TypeScript, JavaScript, Python, Java, Go, Rust,
+  PHP, C#, C/C++, Ruby, HTML (plus config/schema files as graph nodes).
+- **Multi-agent setup** — one `init` writes rules for AGENTS.md,
+  Claude Code, Gemini, Cursor, Windsurf, Copilot, Kiro, or all at once.
+
 ## Install
 
 ```bash
@@ -47,24 +71,39 @@ To query manually:
 
 ```bash
 scopecairn context "add approval workflow"
+scopecairn context ./                 # repository orientation map
 scopecairn impact src/request/RequestService.ts
 scopecairn read symbol approveRequest
 scopecairn graph RequestService
 scopecairn doctor
 ```
 
+Per-agent installers (instead of `init --agents …`):
+
+```bash
+scopecairn antigravity install   # Skill + Workflow + allowlist guide
+scopecairn claude install        # CLAUDE.md (also: gemini, cursor, windsurf, copilot, kiro)
+scopecairn claude uninstall      # clean removal, user content preserved
+scopecairn agents list
+```
+
 ## Commands
+
 | Command | Description |
 |---|---|
-| `init` | Initial indexing + generate `AGENTS.md`, Skill, Workflow |
-| `scan` / `rebuild` / `clean` | Manual index management |
-| `status` / `doctor` | Index status and health checks |
-| `context "<task>"` | Main entry point: context + scope (`--escalate`, `--no-refresh`) |
-| `impact <path\|symbol>` | Change impact analysis |
+| `init [path]` | Initial indexing + `AGENTS.md`, Skill, Workflow, agent matrix (`--agents …\|all`) |
+| `scan` / `rebuild` | Manual index management (`scan` inkremental; `rebuild` dari nol) |
+| `status` / `doctor` | Index status (incl. adapters, invocations) and health checks |
+| `context "<task>"` | Main entry point: context + scope (`--escalate`, `--no-refresh`); a path task returns an orientation map |
+| `impact <path\|symbol>` | Change impact: direct, indirect, tests, UI, queries, routes |
 | `graph <symbol>` | Symbol relations |
-| `query "<text>"` | Symbol search |
-| `read symbol <name>` | Symbol-level source excerpt |
-| `benchmark [--tune]` | Retrieval recall and weight calibration |
+| `read symbol <name>` | Symbol-level source excerpt (not whole files) |
+| `<agent> install` | Per-agent setup: `antigravity`, `claude`, `gemini`, `cursor`, `windsurf`, `copilot`, `kiro` (each also `uninstall`; `agents list` to see all) |
+| `benchmark [--tune]` | Retrieval recall, irrelevant ratio, context reduction + weight calibration |
+
+Agent commands (`context`, `impact`, `read`, `graph`, `status`, `doctor`)
+are read-only toward source and only write to `.scopecairn/` — safe to
+allowlist. `init`, `scan`, and `rebuild` are manual/user-side commands.
 
 ## Framework adapters
 
@@ -77,11 +116,22 @@ No configuration needed.
 | `prisma` | `schema.prisma` | `model` symbols for `QUERIES` resolution |
 | `drizzle` | `drizzle*` paths/config, `db/` schemas | `model` symbols from `pgTable`/`sqliteTable`/`mysqlTable`; `QUERIES` from `db.query.*` relational and `db.select/insert/update/delete` builder calls |
 
-Limits (honest): Server Actions, middleware, and non-Prisma/Drizzle ORMs are not
-mapped yet. QUERIES re-derive on every scan so new models resolve without
-a rebuild. Contributing a new adapter = one file + one registration line
+Limits (honest): Server Actions, middleware, non-Prisma/Drizzle ORMs,
+inter-table references, raw SQL strings, and fully dynamic table names
+are not mapped yet — those edges are skipped silently, never hallucinated.
+QUERIES re-derive on every scan so new models resolve without a rebuild.
+Contributing a new adapter = one file + one registration line
 in `src/adapters/index.ts` (see `FrameworkAdapter` in `src/adapters/types.ts`).
 
+## Typical loop
+
+```
+prompt → scopecairn context (refresh at start) → agent edits code
+       → scopecairn scan (refresh at end, incremental, ~instant)
+```
+
+Measure retrieval quality anytime: `scopecairn benchmark [--tune]`.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { Command } from "commander";
-import path15 from "path";
+import path17 from "path";
 
 // src/scanner.ts
 import fs7 from "fs";
@@ -12,9 +12,28 @@ import path8 from "path";
 var EXT_MAP = {
   ".ts": "typescript",
   ".tsx": "typescript",
+  ".mts": "typescript",
+  ".cts": "typescript",
   ".js": "javascript",
   ".jsx": "javascript",
-  ".py": "python"
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".py": "python",
+  ".pyw": "python",
+  ".java": "java",
+  ".go": "go",
+  ".rs": "rust",
+  ".php": "php",
+  ".cs": "csharp",
+  ".cpp": "cpp",
+  ".cc": "cpp",
+  ".cxx": "cpp",
+  ".hpp": "cpp",
+  ".h": "c",
+  ".c": "c",
+  ".rb": "ruby",
+  ".html": "html",
+  ".htm": "html"
 };
 function detectLanguage(filePath) {
   const dot = filePath.lastIndexOf(".");
@@ -498,6 +517,231 @@ function extractPython(source) {
   return { symbols, relations };
 }
 
+// src/extract/generic.ts
+function lineOf3(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+function stripNoise(src) {
+  let out = "";
+  let i = 0;
+  let quote = null;
+  while (i < src.length) {
+    const c = src[i];
+    const nxt = src[i + 1] ?? "";
+    if (quote) {
+      if (c === "\\") {
+        out += "  ";
+        i += 2;
+        continue;
+      }
+      if (c === "\n") {
+        out += "\n";
+        if (quote !== "`") quote = null;
+        i++;
+        continue;
+      }
+      if (c === quote) quote = null;
+      out += " ";
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c;
+      out += " ";
+      i++;
+      continue;
+    }
+    if (c === "/" && nxt === "/") {
+      while (i < src.length && src[i] !== "\n") {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    if (c === "/" && nxt === "*") {
+      out += "  ";
+      i += 2;
+      while (i < src.length && !(src[i] === "*" && src[i + 1] === "/")) {
+        out += src[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      out += "  ";
+      i += 2;
+      continue;
+    }
+    if (c === "#") {
+      while (i < src.length && src[i] !== "\n") {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+var CALL_KEYWORDS = /* @__PURE__ */ new Set([
+  "if",
+  "for",
+  "while",
+  "switch",
+  "catch",
+  "return",
+  "function",
+  "class",
+  "import",
+  "export",
+  "new",
+  "typeof",
+  "instanceof",
+  "def",
+  "fn",
+  "func",
+  "elsif",
+  "unless",
+  "sizeof"
+]);
+function extractGeneric(source, lang) {
+  const symbols = [];
+  const relations = [];
+  const pushRel = (from, to, rel, confidence = 1) => relations.push({ from, to, rel, weight: WEIGHT[rel], confidence });
+  let m;
+  const importLine = /^\s*import\s+(.+?)\s*$/gm;
+  while ((m = importLine.exec(source)) !== null) {
+    const mod = m[1].replace(/["';]/g, "").trim().split(/\s+/)[0];
+    if (!mod || mod === "*") continue;
+    const ln = lineOf3(source, m.index);
+    symbols.push({ name: `import:${mod}`, type: "import", signature: m[0].trim().slice(0, 120), startLine: ln, endLine: ln });
+    pushRel("__file__", mod, "IMPORTS", 0.8);
+  }
+  if (lang === "c" || lang === "cpp" || lang === "csharp") {
+    const incRe = /#include\s+[<"]([^>"]+)[>"]/g;
+    while ((m = incRe.exec(source)) !== null) {
+      const ln = lineOf3(source, m.index);
+      symbols.push({ name: `import:${m[1]}`, type: "import", signature: m[0].slice(0, 120), startLine: ln, endLine: ln });
+      pushRel("__file__", m[1], "IMPORTS", 0.8);
+    }
+  }
+  if (lang === "php" || lang === "rust") {
+    const useRe = lang === "php" ? /^\s*use\s+([\w\\]+)\s*;/gm : /^\s*use\s+([\w:]+)(?:::\s*\{[^}]*\})?\s*;/gm;
+    while ((m = useRe.exec(source)) !== null) {
+      const ln = lineOf3(source, m.index);
+      symbols.push({ name: `import:${m[1]}`, type: "import", signature: m[0].trim().slice(0, 120), startLine: ln, endLine: ln });
+      pushRel("__file__", m[1], "IMPORTS", 0.8);
+    }
+  }
+  if (lang === "go") {
+    const goImp = /^\s*(?:(\w+)\s+)?["`]([^"`]+)["`]/gm;
+    const block = /^\s*import\s*\(\s*$/gm;
+    let b;
+    while ((b = block.exec(source)) !== null) {
+      const end = source.indexOf(")", b.index);
+      const body = source.slice(b.index, end === -1 ? b.index + 500 : end);
+      let im;
+      goImp.lastIndex = 0;
+      while ((im = goImp.exec(body)) !== null) {
+        const mod = im[2];
+        const ln = lineOf3(source, b.index);
+        symbols.push({ name: `import:${mod}`, type: "import", signature: mod.slice(0, 120), startLine: ln, endLine: ln });
+        pushRel("__file__", mod, "IMPORTS", 0.9);
+      }
+    }
+  }
+  const classRe = /(?:class|struct|interface|trait|enum)\s+(\w+)/g;
+  const classNames = /* @__PURE__ */ new Set();
+  while ((m = classRe.exec(source)) !== null) {
+    classNames.add(m[1]);
+    const ln = lineOf3(source, m.index);
+    symbols.push({ name: m[1], type: "class", signature: m[0].slice(0, 120), startLine: ln, endLine: ln });
+  }
+  if (lang === "go") {
+    const typeRe = /^\s*type\s+(\w+)\s+(struct|interface)\b/gm;
+    while ((m = typeRe.exec(source)) !== null) {
+      if (classNames.has(m[1])) continue;
+      classNames.add(m[1]);
+      const ln = lineOf3(source, m.index);
+      symbols.push({ name: m[1], type: "class", signature: m[0].trim().slice(0, 120), startLine: ln, endLine: ln });
+    }
+  }
+  const funcNames = /* @__PURE__ */ new Set();
+  const addFunc = (name, sig, idx, type = "function") => {
+    if (CALL_KEYWORDS.has(name) || classNames.has(name)) return;
+    funcNames.add(name);
+    const ln = lineOf3(source, idx);
+    symbols.push({ name, type, signature: sig.slice(0, 120), startLine: ln, endLine: ln });
+  };
+  if (lang === "go") {
+    const re = /func\s+(?:\([^)]*\)\s+)?(\w+)\s*\(/g;
+    while ((m = re.exec(source)) !== null) addFunc(m[1], m[0], m.index);
+  } else if (lang === "rust") {
+    const re = /fn\s+(\w+)\s*[<(]/g;
+    while ((m = re.exec(source)) !== null) addFunc(m[1], m[0], m.index);
+  } else if (lang === "ruby") {
+    const re = /^\s*def\s+([\w.]+)/gm;
+    while ((m = re.exec(source)) !== null) addFunc(m[1], m[0].trim(), m.index);
+  } else {
+    const re = /(?:^|[{};\n])\s*(?:[\w<>\[\],\s*&:|?]+\s+)?(\w+)\s*\([^();]*\)\s*(?:throws\s+[\w,\s]+)?\{/gm;
+    while ((m = re.exec(source)) !== null) {
+      if (m[0].includes(".") && !m[0].trimStart().startsWith(m[1])) continue;
+      addFunc(m[1], m[0].trim(), m.index);
+    }
+  }
+  const clean = stripNoise(source);
+  const funcsByLine = symbols.filter((s) => s.type === "function" || s.type === "method").sort((a, b) => a.startLine - b.startLine);
+  const callRe = /(\w+)\s*\(/g;
+  let guard = 0;
+  while ((m = callRe.exec(clean)) !== null && guard++ < 4e3) {
+    const callee = m[1];
+    if (CALL_KEYWORDS.has(callee)) continue;
+    const ln = lineOf3(clean, m.index);
+    let caller = "__file__";
+    for (const f of funcsByLine) {
+      if (f.startLine <= ln) caller = f.name;
+      else break;
+    }
+    if (caller === callee) continue;
+    relations.push({
+      from: caller,
+      to: callee,
+      rel: "CALLS",
+      weight: WEIGHT.CALLS,
+      confidence: 0.6,
+      methodCall: clean[m.index - 1] === "."
+    });
+  }
+  return { symbols, relations };
+}
+function extractHtml(source) {
+  const symbols = [];
+  const relations = [];
+  let m;
+  const idRe = /<(\w+)[^>]*\sid\s*=\s*["']([^"']+)["']/gi;
+  while ((m = idRe.exec(source)) !== null) {
+    const ln = lineOf3(source, m.index);
+    symbols.push({
+      name: m[2],
+      type: "element",
+      signature: `<${m[1]} id="${m[2]}">`.slice(0, 120),
+      startLine: ln,
+      endLine: ln
+    });
+  }
+  const refRe = /<(script|link)[^>]*(src|href)\s*=\s*["']([^"']+)["']/gi;
+  while ((m = refRe.exec(source)) !== null) {
+    const ln = lineOf3(source, m.index);
+    symbols.push({
+      name: `import:${m[3]}`,
+      type: "import",
+      signature: m[0].slice(0, 120),
+      startLine: ln,
+      endLine: ln
+    });
+    relations.push({ from: "__file__", to: m[3], rel: "IMPORTS", weight: WEIGHT.IMPORTS, confidence: 0.7 });
+  }
+  return { symbols, relations };
+}
+
 // src/extract/index.ts
 function extractFile(relPath, source) {
   const lang = detectLanguage(relPath);
@@ -508,6 +752,17 @@ function extractFile(relPath, source) {
       return extractTypeScript(source, relPath.endsWith("x"));
     case "python":
       return extractPython(source);
+    case "html":
+      return extractHtml(source);
+    case "java":
+    case "go":
+    case "rust":
+    case "php":
+    case "csharp":
+    case "cpp":
+    case "c":
+    case "ruby":
+      return extractGeneric(source, lang);
     default:
       return { symbols: [], relations: [] };
   }
@@ -1017,7 +1272,7 @@ function insertRelation(db, sourceId, targetId, rel, weight, confidence) {
      VALUES (?, ?, ?, ?, ?)`
   ).run(sourceId, targetId, rel, weight, confidence);
 }
-function lineOf3(content, index) {
+function lineOf4(content, index) {
   return content.slice(0, index).split("\n").length;
 }
 function enclosingFunction(db, fileId, line) {
@@ -1121,7 +1376,7 @@ function routeHandlers(content) {
   const re = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(/g;
   let m;
   while ((m = re.exec(content)) !== null) {
-    out.push({ method: m[1], line: lineOf3(content, m.index) });
+    out.push({ method: m[1], line: lineOf4(content, m.index) });
   }
   return out;
 }
@@ -1154,7 +1409,7 @@ function refreshQueries(db, files) {
     for (const call of prismaCalls(f.content)) {
       const modelId = resolveModel(db, call.model);
       if (!modelId) continue;
-      const line = lineOf3(f.content, call.index);
+      const line = lineOf4(f.content, call.index);
       const caller = enclosingFunction(db, f.fileId, line) ?? fileSym;
       if (caller === modelId) continue;
       ins.run(caller, modelId);
@@ -1315,7 +1570,7 @@ function refreshDrizzleQueries(db, files) {
     for (const q of parseDrizzleQueries(f.content)) {
       const target = findModelInFile(db, f.fileId, q.table) ?? findModelGlobal(db, q.table);
       if (!target) continue;
-      const caller = enclosingFunction(db, f.fileId, lineOf3(f.content, q.index)) ?? fileSym;
+      const caller = enclosingFunction(db, f.fileId, lineOf4(f.content, q.index)) ?? fileSym;
       if (caller === target) continue;
       ins.run(caller, target);
       n++;
@@ -1603,7 +1858,7 @@ function cmdScan(repoRoot2) {
   console.log("\u2713 Repository detected");
   const stats = scanRepository(repoRoot2);
   console.log(`\u2713 ${stats.totalFilesSeen} files found (non-ignored)`);
-  console.log(`\u2713 ${stats.sourceFiles} source files (ts/tsx/js/jsx/py)`);
+  console.log(`\u2713 ${stats.sourceFiles} source files`);
   if (stats.metaFiles > 0) {
     console.log(`\u2713 ${stats.metaFiles} config/schema files (json/yml/sql/prisma, file-level)`);
   }
@@ -1674,20 +1929,18 @@ function cmdStatus(repoRoot2) {
     db.close();
   }
 }
-function cmdClean(repoRoot2) {
-  const dir = dataDir(repoRoot2);
-  fs8.rmSync(dir, { recursive: true, force: true });
-  console.log(`Cleaned ${dir}`);
-}
 
 // src/commands/rebuild.ts
+import fs9 from "fs";
 function cmdRebuild(repoRoot2) {
-  cmdClean(repoRoot2);
+  const dir = dataDir(repoRoot2);
+  fs9.rmSync(dir, { recursive: true, force: true });
+  console.log(`Cleaned ${dir}`);
   cmdScan(repoRoot2);
 }
 
 // src/commands/doctor.ts
-import fs10 from "fs";
+import fs11 from "fs";
 import path11 from "path";
 
 // src/treesitter.ts
@@ -1713,18 +1966,18 @@ async function checkTreeSitter() {
 }
 
 // src/integrate/detect.ts
-import fs9 from "fs";
+import fs10 from "fs";
 import path10 from "path";
 function detectAgentDir(repoRoot2) {
-  const plural = fs9.existsSync(path10.join(repoRoot2, ".agents"));
-  const singular = fs9.existsSync(path10.join(repoRoot2, ".agent"));
+  const plural = fs10.existsSync(path10.join(repoRoot2, ".agents"));
+  const singular = fs10.existsSync(path10.join(repoRoot2, ".agent"));
   if (singular && !plural) return ".agent";
   return ".agents";
 }
 function detectPrefix(repoRoot2) {
   try {
     const pkg = JSON.parse(
-      fs9.readFileSync(path10.join(repoRoot2, "package.json"), "utf8")
+      fs10.readFileSync(path10.join(repoRoot2, "package.json"), "utf8")
     );
     if (pkg.dependencies?.["scopecairn"] || pkg.devDependencies?.["scopecairn"]) {
       return "npx scopecairn";
@@ -1754,11 +2007,16 @@ Gunakan hasilnya sebagai titik awal. Jangan menjelajah repository dari nol.
 ## Selama bekerja
 - Ubah hanya file di daftar Required dan Optional.
 - Jangan sentuh file di daftar Protected tanpa persetujuan user.
+- Bila ternyata lebih dari 2 file harus diubah, panggil ulang konteks penuh:
+  \`${prefix} context --escalate "<permintaan user>"\`
 - Sebelum mengubah simbol yang dipakai banyak tempat, jalankan:
   \`${prefix} impact <path>\`
 - Butuh source sebuah fungsi? Gunakan \`${prefix} read symbol <nama>\`
   alih-alih membaca file penuh.
 
+## Setelah selesai
+Jalankan \`${prefix} scan\` agar indeks ScopeCairn mencerminkan perubahanmu.
+
 ## Pengecualian
 Lewati ScopeCairn hanya untuk pertanyaan non-coding.
 `;
@@ -1792,6 +2050,7 @@ Langkah:
 2. Baca bagian Relevant Files dan Task Scope.
 3. Jika ada perubahan pada simbol bersama, jalankan \`${prefix} impact <path>\`.
 4. Kerjakan task sesuai scope, lalu berhenti saat selesai.
+5. Setelah mengedit, jalankan \`${prefix} scan\` agar indeks ScopeCairn mutakhir.
 `;
 }
 function workflowMd(prefix) {
@@ -1809,7 +2068,6 @@ var ALLOWLIST_COMMANDS = [
   "context",
   "impact",
   "read",
-  "query",
   "graph",
   "status",
   "doctor"
@@ -1920,22 +2178,22 @@ async function cmdDoctor(repoRoot2) {
     const s = db.prepare(`SELECT COUNT(*) AS n FROM symbols`).get().n;
     const r = db.prepare(`SELECT COUNT(*) AS n FROM relationships`).get().n;
     db.close();
-    dbOk = fs10.existsSync(dbPath(repoRoot2));
+    dbOk = fs11.existsSync(dbPath(repoRoot2));
     graphDetail = ` (${s} symbols, ${r} rels)`;
   } catch {
     dbOk = false;
   }
   console.log(`${tick(dbOk)} Database ${dbPath(repoRoot2)}${graphDetail}`);
   const protPath = path11.join(dataDir(repoRoot2), "protected.yml");
-  console.log(`${tick(fs10.existsSync(protPath))} Protected ${protPath}`);
+  console.log(`${tick(fs11.existsSync(protPath))} Protected ${protPath}`);
   const expectedPrefix = detectPrefix(repoRoot2);
   const agentDir = detectAgentDir(repoRoot2);
   let prefixOk = true;
   let matrixOk = 0;
   for (const t of AGENT_MATRIX) {
     const abs = path11.join(repoRoot2, t.rel);
-    if (!fs10.existsSync(abs)) continue;
-    const text = fs10.readFileSync(abs, "utf8");
+    if (!fs11.existsSync(abs)) continue;
+    const text = fs11.readFileSync(abs, "utf8");
     if (!text.includes(MARKER)) continue;
     matrixOk++;
     const used = extractPrefixUsed(text);
@@ -1953,10 +2211,10 @@ async function cmdDoctor(repoRoot2) {
     console.log(`\u2713 Prefix konsisten (\`${expectedPrefix} context\`)`);
   }
   const skillPath = path11.join(repoRoot2, agentDir, "skills", "scopecairn", "SKILL.md");
-  const skillOk = fs10.existsSync(skillPath);
+  const skillOk = fs11.existsSync(skillPath);
   console.log(`${tick(skillOk)} Skill (${agentDir}/skills/scopecairn/SKILL.md)`);
   const wfPath = path11.join(repoRoot2, "workflows", "scopecairn.md");
-  console.log(`${tick(fs10.existsSync(wfPath))} Workflow (workflows/scopecairn.md, opsional)`);
+  console.log(`${tick(fs11.existsSync(wfPath))} Workflow (workflows/scopecairn.md, opsional)`);
   console.log(`i Strict Mode mengabaikan allowlist \u2014 semua perintah tetap perlu persetujuan.`);
   const healthy = nodeOk && sqliteOk && ts.ok && dbOk && matrixOk > 0 && skillOk && prefixOk;
   console.log(`Status: ${healthy ? "HEALTHY" : "DEGRADED (see \u2717 above)"}`);
@@ -2075,32 +2333,8 @@ function cmdGraph(repoRoot2, key) {
   }
 }
 
-// src/commands/query.ts
-function cmdQuery(repoRoot2, text) {
-  const db = openDb(repoRoot2);
-  try {
-    logInvocation(db, "query");
-    const rows = db.prepare(
-      `SELECT s.name, s.type, s.signature, f.path AS file
-         FROM symbols s JOIN files f ON f.id = s.file_id
-         WHERE s.name LIKE ? OR f.path LIKE ? OR s.signature LIKE ?
-         ORDER BY CASE WHEN s.name = ? THEN 0 WHEN s.name LIKE ? THEN 1 ELSE 2 END,
-                  s.name LIMIT 30`
-    ).all(`%${text}%`, `%${text}%`, `%${text}%`, text, `${text}%`);
-    if (rows.length === 0) {
-      console.log(`No matches for "${text}".`);
-      return;
-    }
-    for (const r of rows) {
-      console.log(`${r.name} (${r.type}) \u2014 ${r.file}${r.signature ? ` \u2014 ${r.signature.slice(0, 80)}` : ""}`);
-    }
-  } finally {
-    db.close();
-  }
-}
-
 // src/commands/read.ts
-import fs11 from "fs";
+import fs12 from "fs";
 import path12 from "path";
 function cmdRead(repoRoot2, kind, name) {
   if (kind !== "symbol") {
@@ -2120,7 +2354,7 @@ function cmdRead(repoRoot2, kind, name) {
     const abs = path12.join(repoRoot2, node.file);
     let lines;
     try {
-      lines = fs11.readFileSync(abs, "utf8").split("\n");
+      lines = fs12.readFileSync(abs, "utf8").split("\n");
     } catch {
       console.log(`Cannot read ${node.file}.`);
       return;
@@ -2425,7 +2659,8 @@ var DEFINITION_OF_DONE = [
   "Test relevan lulus",
   "Tidak ada file berubah tanpa alasan",
   "Tidak ada refactoring tak terkait",
-  "Acceptance criteria terpenuhi"
+  "Acceptance criteria terpenuhi",
+  "Index dimutakhirkan (`scopecairn scan`)"
 ];
 function guardBlock() {
   return `## Task Guard
@@ -2544,6 +2779,116 @@ ${tests.map((t) => `- ${t}`).join("\n") || "-"}
   return { markdown: md, high: highFiles, medium: medFiles, tests, dependencies: deps };
 }
 
+// src/commands/orientasi.ts
+import fs13 from "fs";
+import path13 from "path";
+function isPathLike(task) {
+  const t = task.trim().replace(/^["']|["']$/g, "");
+  return t === "." || t === "./" || t === "/" || t.startsWith("./") || t.startsWith("../") || t.startsWith("/") || t.startsWith("~");
+}
+function looksLikeRepoPath(db, repoRoot2, task) {
+  const t = task.trim().replace(/^["']|["']$/g, "");
+  if (/\s/.test(t)) return false;
+  if (isPathLike(task)) return true;
+  try {
+    fs13.statSync(path13.resolve(repoRoot2, t));
+    return true;
+  } catch {
+  }
+  try {
+    const row = db.prepare(`SELECT 1 AS ok FROM files WHERE path = ? OR path LIKE ? LIMIT 1`).get(t, `%/${t}`);
+    return !!row;
+  } catch {
+    return false;
+  }
+}
+function topCentral(db, limit = 10) {
+  try {
+    return db.prepare(
+      `SELECT s.name, s.type, f.path AS file, COUNT(*) AS fanin
+         FROM relationships r
+         JOIN symbols s ON s.id = r.target_id
+         JOIN files f ON f.id = s.file_id
+         WHERE s.type IN ('function','class','method','component','interface','type')
+         GROUP BY r.target_id ORDER BY fanin DESC LIMIT ${limit}`
+    ).all();
+  } catch {
+    return [];
+  }
+}
+function cmdOrientasi(repoRoot2, task) {
+  const db = openDb(repoRoot2);
+  try {
+    const files = db.prepare(`SELECT COUNT(*) AS n FROM files`).get().n;
+    if (files === 0) {
+      console.log("Index kosong. Jalankan `scopecairn scan` dulu.");
+      return;
+    }
+    const byLang = db.prepare(`SELECT language, COUNT(*) AS n FROM files GROUP BY language ORDER BY n DESC`).all();
+    const symbols = db.prepare(`SELECT COUNT(*) AS n FROM symbols`).get().n;
+    const t = task.trim().replace(/^["']|["']$/g, "");
+    const abs = path13.resolve(repoRoot2, t);
+    let rel = null;
+    try {
+      const stat = fs13.statSync(abs);
+      if (stat.isFile()) rel = path13.relative(repoRoot2, abs).split(path13.sep).join("/");
+    } catch {
+      rel = null;
+    }
+    if (rel) {
+      const row = db.prepare(`SELECT id FROM files WHERE path = ?`).get(rel);
+      if (row) {
+        const syms = db.prepare(`SELECT name, type FROM symbols WHERE file_id = ? AND type != 'file' LIMIT 20`).all(row.id);
+        const fileSym = db.prepare(`SELECT id FROM symbols WHERE file_id = ? AND type = 'file'`).get(row.id);
+        const linked = /* @__PURE__ */ new Set();
+        if (fileSym) {
+          for (const e of neighbors(db, fileSym.id, 30)) {
+            if (e.other.file !== rel) linked.add(e.other.file);
+          }
+        }
+        console.log(
+          `# Task Context (orientasi)
+
+## Task
+${task}
+
+## File
+${rel}
+
+## Simbol (${syms.length})
+${syms.map((s) => `- ${s.name} (${s.type})`).join("\n") || "-"}
+
+## Terkait langsung
+${[...linked].slice(0, 10).map((f) => `- ${f}`).join("\n") || "-"}
+
+Butuh konteks kerja? Jalankan \`scopecairn context "<deskripsi task>"\`.
+`
+        );
+        return;
+      }
+    }
+    const central = topCentral(db);
+    console.log(
+      `# Task Context (orientasi)
+
+## Task
+${task}
+
+## Ringkasan index
+- ${files} file (${byLang.map((l) => `${l.language} ${l.n}`).join(", ")})
+- ${symbols} simbol
+
+## Simbol paling dipakai
+${central.map((c) => `- ${c.name} (${c.type}, ${c.file}) \u2190 ${c.fanin}x`).join("\n") || "-"}
+
+Mulai dari simbol di atas, atau jalankan \`scopecairn context "<deskripsi task>"\` untuk konteks kerja.
+`
+    );
+  } finally {
+    db.close();
+  }
+}
+
 // src/commands/context.ts
 function cmdContext(repoRoot2, task, opts = {}) {
   if (!opts.noRefresh) {
@@ -2562,6 +2907,11 @@ function cmdContext(repoRoot2, task, opts = {}) {
       console.log("Index kosong. Jalankan `scopecairn scan` dulu.");
       return;
     }
+    if (looksLikeRepoPath(db, repoRoot2, task)) {
+      logInvocation(db, "context");
+      cmdOrientasi(repoRoot2, task);
+      return;
+    }
     const result = retrieve(db, repoRoot2, task);
     if (result.ranked.length === 0) {
       logInvocation(db, "context");
@@ -2731,31 +3081,152 @@ function cmdImpact(repoRoot2, target, opts = {}) {
 }
 
 // src/commands/init.ts
-import fs12 from "fs";
-import path13 from "path";
-function writeTarget(repoRoot2, target, prefix) {
-  const abs = path13.join(repoRoot2, target.rel);
+import fs15 from "fs";
+import path15 from "path";
+
+// src/integrate/install.ts
+import fs14 from "fs";
+import path14 from "path";
+function installTarget(repoRoot2, target, prefix) {
+  const abs = path14.join(repoRoot2, target.rel);
   const block = target.render(prefix);
+  const finish = (how) => ({
+    agent: target.id,
+    rel: target.rel,
+    how
+  });
   if (target.mode === "new") {
-    const existed = fs12.existsSync(abs);
-    fs12.mkdirSync(path13.dirname(abs), { recursive: true });
-    fs12.writeFileSync(abs, block.endsWith("\n") ? block : block + "\n");
-    return existed ? "updated" : "generated";
+    const existed = fs14.existsSync(abs);
+    fs14.mkdirSync(path14.dirname(abs), { recursive: true });
+    fs14.writeFileSync(abs, block.endsWith("\n") ? block : block + "\n");
+    return finish(existed ? "updated" : "generated");
   }
-  if (fs12.existsSync(abs)) {
-    const cur = fs12.readFileSync(abs, "utf8");
+  if (fs14.existsSync(abs)) {
+    const cur = fs14.readFileSync(abs, "utf8");
     if (cur.includes(MARKER)) {
-      const re = new RegExp(`${MARKER}[\\s\\S]*?(?=\\n#[^#]|$)`, "");
-      fs12.writeFileSync(abs, cur.replace(re, block.trimEnd()).trimEnd() + "\n");
-      return "updated";
+      const { next: next2 } = removeManagedBlock(cur, (p) => target.render(p));
+      fs14.writeFileSync(abs, (next2 + "\n\n" + block).trimEnd() + "\n");
+      return finish("updated");
+    }
+    const { next, changed } = removeManagedBlock(cur, (p) => target.render(p));
+    const base = changed ? next : cur;
+    fs14.writeFileSync(abs, (base.trimEnd() + "\n\n" + block).trimEnd() + "\n");
+    return finish("extended");
+  }
+  fs14.mkdirSync(path14.dirname(abs), { recursive: true });
+  fs14.writeFileSync(abs, block.endsWith("\n") ? block : block + "\n");
+  return finish("generated");
+}
+function removeManagedBlock(content, render) {
+  for (const p of ["scopecairn", "npx scopecairn"]) {
+    for (const cand of [render(p), render(p).trimEnd(), render(p).trimEnd() + "\n"]) {
+      if (cand && content.includes(cand)) {
+        return { next: foldBlank(content.split(cand).join("")), changed: true };
+      }
     }
-    fs12.writeFileSync(abs, cur.trimEnd() + "\n\n" + block);
-    return "extended";
   }
-  fs12.mkdirSync(path13.dirname(abs), { recursive: true });
-  fs12.writeFileSync(abs, block.endsWith("\n") ? block : block + "\n");
-  return "generated";
+  const anchored = new RegExp(
+    `\\n*${MARKER}\\n# ScopeCairn[\\s\\S]*?pertanyaan non-coding\\.[ \\t]*(\\n|$)`,
+    ""
+  );
+  if (anchored.test(content)) {
+    return { next: foldBlank(content.replace(anchored, "\n")), changed: true };
+  }
+  const orphan = /# ScopeCairn[\s\S]*?pertanyaan non-coding\.[ \t]*(\n|$)/g;
+  if (orphan.test(content)) {
+    return { next: foldBlank(content.replace(orphan, "")), changed: true };
+  }
+  return { next: content, changed: false };
+}
+function foldBlank(s) {
+  return s.replace(/\n{3,}/g, "\n\n").trim();
+}
+function uninstallTarget(repoRoot2, target) {
+  const abs = path14.join(repoRoot2, target.rel);
+  const finish = (how) => ({
+    agent: target.id,
+    rel: target.rel,
+    how
+  });
+  if (!fs14.existsSync(abs)) return finish("absent");
+  if (target.mode === "new") {
+    fs14.rmSync(abs, { force: true });
+    pruneEmptyDirs(path14.dirname(abs), repoRoot2);
+    return finish("removed");
+  }
+  const cur = fs14.readFileSync(abs, "utf8");
+  if (!cur.includes(MARKER)) return finish("skipped");
+  const render = (p) => {
+    const t = resolveAgent(target.id);
+    return t ? t.render(p) : "";
+  };
+  const { next, changed } = removeManagedBlock(cur, render);
+  if (!changed) return finish("skipped");
+  if (!next) {
+    fs14.rmSync(abs, { force: true });
+    return finish("removed");
+  }
+  fs14.writeFileSync(abs, next + "\n");
+  return finish("removed");
+}
+function pruneEmptyDirs(dir, stop) {
+  let cur = dir;
+  while (cur.startsWith(stop) && cur !== stop) {
+    try {
+      fs14.rmdirSync(cur);
+    } catch {
+      return;
+    }
+    cur = path14.dirname(cur);
+  }
+}
+function installAntigravity(repoRoot2, prefix = detectPrefix(repoRoot2)) {
+  const agentDir = detectAgentDir(repoRoot2);
+  const out = [];
+  const skillPath = path14.join(repoRoot2, agentDir, "skills", "scopecairn", "SKILL.md");
+  fs14.mkdirSync(path14.dirname(skillPath), { recursive: true });
+  fs14.writeFileSync(skillPath, skillMd(prefix));
+  out.push(`Skill installed (${path14.relative(repoRoot2, skillPath)})`);
+  const wfPath = path14.join(repoRoot2, "workflows", "scopecairn.md");
+  fs14.mkdirSync(path14.dirname(wfPath), { recursive: true });
+  fs14.writeFileSync(wfPath, workflowMd(prefix));
+  out.push(`Workflow installed (${path14.relative(repoRoot2, wfPath)})`);
+  return out;
+}
+function uninstallAntigravity(repoRoot2) {
+  const out = [];
+  for (const dir of [".agents", ".agent"]) {
+    const p = path14.join(repoRoot2, dir, "skills", "scopecairn", "SKILL.md");
+    if (fs14.existsSync(p)) {
+      fs14.rmSync(p, { force: true });
+      pruneEmptyDirs(path14.dirname(p), repoRoot2);
+      out.push(`Skill removed (${path14.relative(repoRoot2, p)})`);
+    }
+  }
+  const wf = path14.join(repoRoot2, "workflows", "scopecairn.md");
+  if (fs14.existsSync(wf)) {
+    const text = fs14.readFileSync(wf, "utf8");
+    if (text.includes("scopecairn")) {
+      fs14.rmSync(wf, { force: true });
+      out.push(`Workflow removed (${path14.relative(repoRoot2, wf)})`);
+    } else {
+      out.push(`Workflow skipped (bukan milik ScopeCairn)`);
+    }
+  }
+  if (out.length === 0) out.push("Nothing installed.");
+  return out;
+}
+function agentIds() {
+  return ["antigravity", ...AGENT_MATRIX.map((t) => t.id)];
+}
+function allowlistText(repoRoot2) {
+  return allowlistGuide(detectPrefix(repoRoot2));
 }
+function resolveAgent(id) {
+  return findTarget(id);
+}
+
+// src/commands/init.ts
 function cmdInit(repoRoot2, opts = {}) {
   console.log("ScopeCairn");
   console.log("\u2713 Repository detected");
@@ -2764,49 +3235,43 @@ function cmdInit(repoRoot2, opts = {}) {
   if (stats.metaFiles > 0) console.log(`\u2713 ${stats.metaFiles} config/schema files`);
   console.log(`\u2713 ${stats.symbols} symbols`);
   console.log(`\u2713 ${stats.relationships} relationships`);
+  if (stats.adapters.length > 0) console.log(`\u2713 adapters: ${stats.adapters.join(", ")}`);
   const prefix = detectPrefix(repoRoot2);
-  const agentDir = detectAgentDir(repoRoot2);
   const requested = parseAgentsOption(opts.agents);
-  let targets;
-  if (requested === "all") {
-    targets = [...AGENT_MATRIX];
-  } else if (requested && requested.length > 0) {
-    targets = [];
-    for (const id of requested) {
-      const t = findTarget(id);
-      if (!t) {
-        console.log(`! Unknown agent "${id}" (pilihan: ${AGENT_MATRIX.map((x) => x.id).join(", ")}, all)`);
-        continue;
-      }
-      targets.push(t);
-    }
-    if (!targets.includes(AGENT_MATRIX[0])) targets.unshift(AGENT_MATRIX[0]);
-  } else {
-    targets = [AGENT_MATRIX[0]];
-    for (const t of AGENT_MATRIX.slice(1)) {
-      if (fs12.existsSync(path13.join(repoRoot2, t.presentMarker))) targets.push(t);
-    }
-  }
+  const targets = requested === "all" ? [...AGENT_MATRIX] : requested && requested.length > 0 ? withCore(requested) : withDetected(repoRoot2);
   for (const t of targets) {
-    const how = writeTarget(repoRoot2, t, prefix);
-    console.log(`\u2713 ${t.label}: ${t.rel} (${how})`);
-  }
-  const skillPath = path13.join(repoRoot2, agentDir, "skills", "scopecairn", "SKILL.md");
-  fs12.mkdirSync(path13.dirname(skillPath), { recursive: true });
-  fs12.writeFileSync(skillPath, skillMd(prefix));
-  console.log(`\u2713 Skill installed (${path13.relative(repoRoot2, skillPath)})`);
-  const wfPath = path13.join(repoRoot2, "workflows", "scopecairn.md");
-  fs12.mkdirSync(path13.dirname(wfPath), { recursive: true });
-  fs12.writeFileSync(wfPath, workflowMd(prefix));
-  console.log(`\u2713 Workflow installed (${path13.relative(repoRoot2, wfPath)})`);
+    const r = installTarget(repoRoot2, t, prefix);
+    console.log(`\u2713 ${t.label}: ${r.rel} (${r.how})`);
+  }
+  for (const line of installAntigravity(repoRoot2, prefix)) console.log(`\u2713 ${line}`);
   console.log("Ready.");
   console.log("");
-  console.log(allowlistGuide(prefix));
+  console.log(allowlistText(repoRoot2));
+}
+function withCore(ids) {
+  const out = [];
+  for (const id of ids) {
+    const t = findTarget(id);
+    if (!t) {
+      console.log(`! Unknown agent "${id}" (pilihan: ${AGENT_MATRIX.map((x) => x.id).join(", ")}, all)`);
+      continue;
+    }
+    out.push(t);
+  }
+  if (!out.includes(AGENT_MATRIX[0])) out.unshift(AGENT_MATRIX[0]);
+  return out;
+}
+function withDetected(repoRoot2) {
+  const targets = [AGENT_MATRIX[0]];
+  for (const t of AGENT_MATRIX.slice(1)) {
+    if (fs15.existsSync(path15.join(repoRoot2, t.presentMarker))) targets.push(t);
+  }
+  return targets;
 }
 
 // src/benchmark/run.ts
-import fs13 from "fs";
-import path14 from "path";
+import fs16 from "fs";
+import path16 from "path";
 
 // src/benchmark/dataset.ts
 var BENCHMARK_TASKS = [
@@ -2863,7 +3328,7 @@ var BENCHMARK_TASKS = [
 // src/benchmark/run.ts
 function fileChars(repoRoot2, rel) {
   try {
-    return fs13.readFileSync(path14.join(repoRoot2, rel), "utf8").length;
+    return fs16.readFileSync(path16.join(repoRoot2, rel), "utf8").length;
   } catch {
     return 0;
   }
@@ -3012,10 +3477,42 @@ function cmdBenchmark(repoRoot2, opts = {}) {
   }
 }
 
+// src/commands/agents.ts
+function registerAgentCommands(program2, repoRoot2) {
+  const list = program2.command("agents").description("List supported agent installers");
+  list.command("list").description("Show agent ids").action(() => {
+    console.log(agentIds().join("\n"));
+  });
+  const anti = program2.command("antigravity").description("Antigravity IDE integration");
+  anti.command("install").description("Install Skill + Workflow, print allowlist guide").action(() => {
+    const root = repoRoot2();
+    const prefix = detectPrefix(root);
+    for (const line of installAntigravity(root, prefix)) console.log(`\u2713 ${line}`);
+    console.log("");
+    console.log(allowlistText(root));
+  });
+  anti.command("uninstall").description("Remove Skill + Workflow").action(() => {
+    for (const line of uninstallAntigravity(repoRoot2())) console.log(`\u2713 ${line}`);
+  });
+  for (const t of AGENT_MATRIX) {
+    if (t.id === "agents") continue;
+    const cmd = program2.command(t.id).description(`${t.label} integration`);
+    cmd.command("install").description(`Write ${t.rel}`).action(() => {
+      const root = repoRoot2();
+      const r = installTarget(root, t, detectPrefix(root));
+      console.log(`\u2713 ${t.label}: ${r.rel} (${r.how})`);
+    });
+    cmd.command("uninstall").description(`Remove ScopeCairn block from ${t.rel}`).action(() => {
+      const r = uninstallTarget(repoRoot2(), t);
+      console.log(`\u2713 ${t.label}: ${r.rel} (${r.how})`);
+    });
+  }
+}
+
 // package.json
 var package_default = {
   name: "scopecairn",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "ScopeCairn \u2014 Codebase Intelligence & Agent Optimization Layer (local-first)",
   license: "MIT",
   type: "module",
@@ -3065,23 +3562,36 @@ var package_default = {
 
 // src/cli.ts
 var program = new Command();
-program.name("scopecairn").description("ScopeCairn \u2014 local-first codebase intelligence layer").version(package_default.version);
+program.name("scopecairn").description("ScopeCairn \u2014 local-first codebase intelligence layer").version(package_default.version).addHelpText(
+  "after",
+  `
+Examples:
+  $ scopecairn init                      index repo + setup agent integration
+  $ scopecairn init ./myapp --agents all  setup another directory, all agents
+  $ scopecairn context "add login"        relevant context + scope for a task
+  $ scopecairn context ./                 repository orientation map
+  $ scopecairn impact src/auth/login.ts   change impact analysis
+  $ scopecairn read symbol approveRequest  symbol-level source excerpt
+  $ scopecairn doctor                     health + integration check
+
+Agent commands (context, impact, read, graph, status, doctor) are
+read-only toward source and only write to .scopecairn/ \u2014 safe to allowlist.
+`
+);
 function repoRoot() {
-  return path15.resolve(process.cwd());
+  return path17.resolve(process.cwd());
 }
 function resolveRoot(given) {
   if (!given) return repoRoot();
-  return path15.resolve(process.cwd(), given);
+  return path17.resolve(process.cwd(), given);
 }
-program.command("scan").description("Index repository (Fase 1: files + hash + language)").action(() => cmdScan(repoRoot()));
+program.command("scan").description("Index repository (files + symbols + relations)").action(() => cmdScan(repoRoot()));
 program.command("status").description("Show index status").action(() => cmdStatus(repoRoot()));
-program.command("clean").description("Remove generated index data").action(() => cmdClean(repoRoot()));
 program.command("rebuild").description("Rebuild index from scratch (recover from corrupt index)").action(() => cmdRebuild(repoRoot()));
 program.command("doctor").description("Check integration health").action(async () => {
   await cmdDoctor(repoRoot());
 });
-program.command("graph <symbol>").description("Show relations of a symbol (Fase 2: 1-hop traversal)").action((symbol) => cmdGraph(repoRoot(), symbol));
-program.command("query <text>").description("Search symbols/codebase knowledge (substring match)").action((text) => cmdQuery(repoRoot(), text));
+program.command("graph <symbol>").description("Show relations of a symbol").action((symbol) => cmdGraph(repoRoot(), symbol));
 program.command("read").argument("<kind>", "what to read (symbol)").argument("<name>", "symbol name").description("Read a symbol's source excerpt (not the whole file)").action((kind, name) => cmdRead(repoRoot(), kind, name));
 program.command("context <task>").description("Main entry point: auto-refresh + classify + relevant context + scope").option("--escalate", "force full COMPLEX context").option("--no-refresh", "skip incremental refresh (debugging/benchmark)").action(
   (task, opts) => cmdContext(repoRoot(), task, opts)
@@ -3095,6 +3605,7 @@ program.command("init [path]").description("Initial indexing + generate AGENTS.m
 program.command("benchmark").description("Retrieval recall, irrelevant ratio, context reduction + weight tuning").option("--tune", "grid search bobot FR-05").option("--no-refresh", "skip incremental refresh (debugging/benchmark)").action(
   (opts) => cmdBenchmark(repoRoot(), opts)
 );
+registerAgentCommands(program, repoRoot);
 program.parseAsync(process.argv);
 export {
   resolveRoot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scopecairn",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ScopeCairn — Codebase Intelligence & Agent Optimization Layer (local-first)",
   "license": "MIT",
   "type": "module",