scopecairn 0.1.0 → 0.2.0

package/README.md

@@ -15,7 +15,27 @@ npm install -g scopecairn
 
 Requires Node.js ≥ 20.
 
-## Quickstart
+## Agent-driven setup
+
+Install once, then just type `scopecairn ./` to your AI agent —
+it runs project setup itself.
+
+1. Install the skill once (global):
+   ```bash
+   npx skills add <github-user>/scopecairn -g
+   ```
+   (fallback without a skill: add one line to your global agent
+   instructions — `~/.claude/CLAUDE.md` or equivalent: *When the user
+   writes "scopecairn \<path\>", run `scopecairn init \<path\>`.*)
+2. In any project chat, type:
+   ```
+   scopecairn ./
+   ```
+   The agent runs `scopecairn init ./`, reports files indexed and
+   integration files written. Approve the terminal command once;
+   afterwards, add the printed allowlist so later calls need no approval.
+
+## Quickstart (manual)
 
 ```bash
 cd your-repo
@@ -34,7 +54,6 @@ scopecairn doctor
 ```
 
 ## Commands
-
 | Command | Description |
 |---|---|
 | `init` | Initial indexing + generate `AGENTS.md`, Skill, Workflow |
@@ -47,6 +66,22 @@ scopecairn doctor
 | `read symbol <name>` | Symbol-level source excerpt |
 | `benchmark [--tune]` | Retrieval recall and weight calibration |
 
+## Framework adapters
+
+Detected automatically during `scan` (shown in output and `status`).
+No configuration needed.
+
+| Adapter | Detects | Produces |
+|---|---|---|
+| `nextjs` | `app/`, `pages/`, `next.config.*` | Route symbols (`GET /api/x`, `PAGE /y` incl. route groups, dynamic segments), `ROUTES_TO` handler edges, `QUERIES` handler→model edges |
+| `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
+in `src/adapters/index.ts` (see `FrameworkAdapter` in `src/adapters/types.ts`).
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/cli.js

@@ -2,11 +2,11 @@
 
 // src/cli.ts
 import { Command } from "commander";
-import path13 from "path";
+import path15 from "path";
 
 // src/scanner.ts
-import fs5 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path8 from "path";
 
 // src/languages.ts
 var EXT_MAP = {
@@ -178,8 +178,10 @@ var WEIGHT = {
   IMPORTS: 0.9,
   EXPORTS: 0.9,
   TESTS: 0.9,
+  ROUTES_TO: 0.9,
   EXTENDS: 0.8,
   IMPLEMENTS: 0.8,
+  QUERIES: 0.8,
   CALLS: 0.7,
   REFERENCES: 0.5,
   USES: 0.5
@@ -984,14 +986,488 @@ top_n: 20
   ensureProtectedFile(repoRoot2);
 }
 
+// src/adapters/index.ts
+import fs6 from "fs";
+import path7 from "path";
+
+// src/adapters/types.ts
+function findSymbolId(db, name, types) {
+  const row = types && types.length > 0 ? db.prepare(
+    `SELECT id FROM symbols WHERE name = ? AND type IN (${types.map(() => "?").join(",")}) LIMIT 1`
+  ).get(name, ...types) : db.prepare(`SELECT id FROM symbols WHERE name = ? LIMIT 1`).get(name);
+  return row ? row.id : null;
+}
+function fileSymbolOf(db, fileId) {
+  const row = db.prepare(`SELECT id FROM symbols WHERE file_id = ? AND type = 'file'`).get(fileId);
+  return row ? row.id : null;
+}
+function ensureAdapterSymbol(db, fileId, s) {
+  const row = db.prepare(`SELECT id FROM symbols WHERE file_id = ? AND name = ? AND type = ? LIMIT 1`).get(fileId, s.name, s.type);
+  if (row) return row.id;
+  const r = db.prepare(
+    `INSERT INTO symbols(file_id, name, type, signature, start_line, end_line)
+       VALUES (?, ?, ?, ?, ?, ?)`
+  ).run(fileId, s.name, s.type, s.signature, s.startLine, s.endLine);
+  return Number(r.lastInsertRowid);
+}
+function insertRelation(db, sourceId, targetId, rel, weight, confidence) {
+  if (sourceId === targetId) return;
+  db.prepare(
+    `INSERT INTO relationships(source_id, target_id, relationship_type, weight, confidence)
+     VALUES (?, ?, ?, ?, ?)`
+  ).run(sourceId, targetId, rel, weight, confidence);
+}
+function lineOf3(content, index) {
+  return content.slice(0, index).split("\n").length;
+}
+function enclosingFunction(db, fileId, line) {
+  const rows = db.prepare(
+    `SELECT id, name FROM symbols WHERE file_id = ? AND type IN ('function','method','component') AND start_line <= ? ORDER BY start_line DESC LIMIT 5`
+  ).all(fileId, line);
+  return rows.length > 0 ? rows[0].id : null;
+}
+
+// src/adapters/prisma.ts
+function parsePrismaModels(content) {
+  const out = [];
+  const re = /^model\s+(\w+)\s*\{/gm;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    out.push({ name: m[1], line: content.slice(0, m.index).split("\n").length });
+  }
+  return out;
+}
+var prismaAdapter = {
+  id: "prisma",
+  label: "Prisma",
+  detect: (files) => files.some((f) => f.endsWith("schema.prisma")),
+  relevant: (rel) => rel.endsWith("schema.prisma"),
+  apply(ctx, files) {
+    let symbols = 0;
+    let relations = 0;
+    for (const f of files) {
+      const fileSym = fileSymbolOf(ctx.db, f.fileId);
+      if (!fileSym) continue;
+      for (const model of parsePrismaModels(f.content)) {
+        const id = ensureAdapterSymbol(ctx.db, f.fileId, {
+          name: model.name,
+          type: "model",
+          signature: `model ${model.name}`,
+          startLine: model.line,
+          endLine: model.line
+        });
+        symbols++;
+        insertRelation(ctx.db, fileSym, id, "CONTAINS", 1, 1);
+        relations++;
+      }
+    }
+    return { symbols, relations };
+  }
+};
+
+// src/adapters/nextjs.ts
+var PRISMA_OPS = [
+  "findMany",
+  "findUnique",
+  "findFirst",
+  "findFirstOrThrow",
+  "findUniqueOrThrow",
+  "create",
+  "createMany",
+  "update",
+  "updateMany",
+  "upsert",
+  "delete",
+  "deleteMany",
+  "count",
+  "aggregate",
+  "groupBy"
+];
+function stripSrcPrefix(rel) {
+  return rel.startsWith("src/") ? rel.slice(4) : rel;
+}
+function cleanSegments(segs) {
+  const out = [];
+  for (let s of segs) {
+    if (/^\(.*\)$/.test(s) || s.startsWith("@")) continue;
+    s = s.replace(/^\(\.+\)/, "");
+    if (s) out.push(s);
+  }
+  return out;
+}
+function appRouteFromRel(rel) {
+  const p = stripSrcPrefix(rel);
+  if (!p.startsWith("app/")) return null;
+  const parts = p.slice(4).split("/");
+  const file = parts[parts.length - 1];
+  const dir = cleanSegments(parts.slice(0, -1));
+  const url = "/" + dir.join("/");
+  if (/^page\.(tsx|ts|jsx|js|mdx?)$/.test(file)) return { kind: "page", url };
+  if (/^route\.(ts|js)$/.test(file)) return { kind: "route", url };
+  return null;
+}
+function pagesRouteFromRel(rel) {
+  const p = stripSrcPrefix(rel);
+  if (!p.startsWith("pages/")) return null;
+  const rest = p.slice(6).replace(/\.(tsx|ts|jsx|js|mdx?)$/, "");
+  if (rest.startsWith("_") || rest.startsWith("api/_")) return null;
+  if (rest === "index") return { kind: "page", url: "/" };
+  if (rest.startsWith("api/")) return { kind: "route", url: "/" + rest };
+  if (rest.endsWith("/index")) return { kind: "page", url: "/" + rest.slice(0, -6) };
+  return { kind: "page", url: "/" + rest };
+}
+function routeHandlers(content) {
+  const out = [];
+  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) });
+  }
+  return out;
+}
+function prismaCalls(content) {
+  const out = [];
+  const ops = PRISMA_OPS.join("|");
+  const re = new RegExp(`prisma\\.(\\w+)\\.(${ops})\\s*\\(`, "g");
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    out.push({ model: m[1], op: m[2], index: m.index });
+  }
+  return out;
+}
+function resolveModel(db, name) {
+  return findSymbolId(db, name, ["model"]) ?? dbLowerModel(db, name);
+}
+function refreshQueries(db, files) {
+  let n = 0;
+  const del = db.prepare(
+    `DELETE FROM relationships WHERE relationship_type = 'QUERIES' AND source_id IN (SELECT id FROM symbols WHERE file_id = ?)`
+  );
+  const ins = db.prepare(
+    `INSERT INTO relationships(source_id, target_id, relationship_type, weight, confidence)
+     VALUES (?, ?, 'QUERIES', ${WEIGHT.QUERIES}, 0.9)`
+  );
+  for (const f of files) {
+    const fileSym = fileSymbolOf(db, f.fileId);
+    if (!fileSym) continue;
+    del.run(f.fileId);
+    for (const call of prismaCalls(f.content)) {
+      const modelId = resolveModel(db, call.model);
+      if (!modelId) continue;
+      const line = lineOf3(f.content, call.index);
+      const caller = enclosingFunction(db, f.fileId, line) ?? fileSym;
+      if (caller === modelId) continue;
+      ins.run(caller, modelId);
+      n++;
+    }
+  }
+  return n;
+}
+var nextjsAdapter = {
+  id: "nextjs",
+  label: "Next.js",
+  detect: (files) => files.some((f) => {
+    const p = stripSrcPrefix(f);
+    return p.startsWith("app/") || p.startsWith("pages/") || /(^|\/)next\.config\.(js|ts|mjs)$/.test(f);
+  }),
+  relevant: (rel) => {
+    const p = stripSrcPrefix(rel);
+    return p.startsWith("app/") || p.startsWith("pages/");
+  },
+  apply(ctx, files) {
+    let symbols = 0;
+    let relations = 0;
+    for (const f of files) {
+      const fileSym = fileSymbolOf(ctx.db, f.fileId);
+      if (!fileSym) continue;
+      const mapped = appRouteFromRel(f.rel) ?? pagesRouteFromRel(f.rel);
+      if (mapped) {
+        if (mapped.kind === "page") {
+          const id = ensureAdapterSymbol(ctx.db, f.fileId, {
+            name: `PAGE ${mapped.url}`,
+            type: "route",
+            signature: `page ${mapped.url}`,
+            startLine: 1,
+            endLine: 1
+          });
+          symbols++;
+          insertRelation(ctx.db, fileSym, id, "CONTAINS", 1, 1);
+          relations++;
+        } else {
+          const handlers = routeHandlers(f.content);
+          if (handlers.length === 0) {
+            const id = ensureAdapterSymbol(ctx.db, f.fileId, {
+              name: `API ${mapped.url}`,
+              type: "route",
+              signature: `route ${mapped.url} (no exported handler)`,
+              startLine: 1,
+              endLine: 1
+            });
+            symbols++;
+            insertRelation(ctx.db, fileSym, id, "CONTAINS", 1, 0.6);
+            relations++;
+          }
+          for (const h of handlers) {
+            const routeId = ensureAdapterSymbol(ctx.db, f.fileId, {
+              name: `${h.method} ${mapped.url}`,
+              type: "route",
+              signature: `${h.method} ${mapped.url}`,
+              startLine: h.line,
+              endLine: h.line
+            });
+            symbols++;
+            insertRelation(ctx.db, fileSym, routeId, "CONTAINS", 1, 1);
+            relations++;
+            const handlerId = findInFile(ctx.db, f.fileId, h.method);
+            if (handlerId) {
+              insertRelation(ctx.db, handlerId, routeId, "ROUTES_TO", WEIGHT.ROUTES_TO, 1);
+              relations++;
+            }
+          }
+        }
+      }
+    }
+    relations += refreshQueries(
+      ctx.db,
+      files.map((f) => ({ fileId: f.fileId, rel: f.rel, content: f.content }))
+    );
+    return { symbols, relations };
+  }
+};
+function dbLowerModel(db, name) {
+  const row = db.prepare(`SELECT id, name FROM symbols WHERE type = 'model'`).all();
+  const lower = name.toLowerCase();
+  return row.find((r) => r.name.toLowerCase() === lower)?.id ?? null;
+}
+function findInFile(db, fileId, name) {
+  const row = db.prepare(`SELECT id FROM symbols WHERE file_id = ? AND name = ? LIMIT 1`).get(fileId, name);
+  return row ? row.id : null;
+}
+
+// src/adapters/drizzle.ts
+import fs5 from "fs";
+import path6 from "path";
+var TABLE_FNS = ["pgTable", "sqliteTable", "mysqlTable"];
+var RELATIONAL_OPS = [
+  "findMany",
+  "findFirst",
+  "findFirstOrThrow",
+  "findUnique"
+];
+function parseDrizzleTables(content) {
+  const out = [];
+  const fns = TABLE_FNS.join("|");
+  const re = new RegExp(
+    `(?:export\\s+)?(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:${fns})\\s*\\(\\s*["'\`]([^"'\\\`]+)["'\`]`,
+    "g"
+  );
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    out.push({
+      name: m[1],
+      table: m[2],
+      line: content.slice(0, m.index).split("\n").length
+    });
+  }
+  return out;
+}
+function parseDrizzleQueries(content) {
+  const out = [];
+  const relOps = RELATIONAL_OPS.join("|");
+  const relRe = new RegExp(`db\\s*\\.\\s*query\\s*\\.\\s*(\\w+)\\s*\\.\\s*(?:${relOps})\\s*\\(`, "g");
+  let m;
+  while ((m = relRe.exec(content)) !== null) {
+    out.push({ table: m[1], index: m.index });
+  }
+  const builderRe = /db\s*\.\s*(select|selectDistinct|insert|update|delete)\b/g;
+  while ((m = builderRe.exec(content)) !== null) {
+    const op = m[1];
+    const window = content.slice(m.index, m.index + 400);
+    let tm;
+    if (op === "select" || op === "selectDistinct") {
+      tm = /\.from\s*\(\s*(\w+)/.exec(window);
+    } else {
+      tm = /\(\s*(\w+)\s*[,)]/.exec(window);
+    }
+    if (tm) out.push({ table: tm[1], index: m.index });
+  }
+  return out;
+}
+function hasDrizzleMarker(content) {
+  if (content.includes("drizzle-orm") || TABLE_FNS.some((f) => content.includes(`${f}(`)) || /db\s*\.\s*query\s*\./.test(content)) {
+    return true;
+  }
+  return /db\s*\.\s*(select|selectDistinct|insert|update|delete)\b/.test(content);
+}
+function refreshDrizzleQueries(db, files) {
+  let n = 0;
+  const del = db.prepare(
+    `DELETE FROM relationships WHERE relationship_type = 'QUERIES' AND source_id IN (SELECT id FROM symbols WHERE file_id = ?)`
+  );
+  const ins = db.prepare(
+    `INSERT INTO relationships(source_id, target_id, relationship_type, weight, confidence)
+     VALUES (?, ?, 'QUERIES', ${WEIGHT.QUERIES}, 0.85)`
+  );
+  for (const f of files) {
+    const fileSym = fileSymbolOf(db, f.fileId);
+    if (!fileSym || !hasDrizzleMarker(f.content)) continue;
+    del.run(f.fileId);
+    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;
+      if (caller === target) continue;
+      ins.run(caller, target);
+      n++;
+    }
+  }
+  return n;
+}
+function findModelInFile(db, fileId, name) {
+  const row = db.prepare(
+    `SELECT id FROM symbols WHERE file_id = ? AND name = ? AND type = 'model' LIMIT 1`
+  ).get(fileId, name);
+  return row ? row.id : null;
+}
+function findModelGlobal(db, name) {
+  const rows = db.prepare(`SELECT id, name FROM symbols WHERE type = 'model'`).all();
+  const lower = name.toLowerCase();
+  return rows.find((r) => r.name.toLowerCase() === lower)?.id ?? null;
+}
+var drizzleAdapter = {
+  id: "drizzle",
+  label: "Drizzle ORM",
+  detect: (files) => files.some(
+    (f) => f.includes("drizzle") || /(^|\/)drizzle\.config\.(ts|js|mjs)$/.test(f) || /(^|\/)(db|drizzle)\/.*schema.*\.ts$/.test(f)
+  ),
+  // Pola path lemah (`src/adapters/drizzle.ts` ikut cocok) — konfirmasi isi:
+  // path kuat (config/dir drizzle, skema db/) langsung lolos, sisanya butuh
+  // dependensi drizzle di package.json.
+  confirm: (repoRoot2, files) => {
+    if (files.some(
+      (f) => /(^|\/)drizzle\.config\.(ts|js|mjs)$/.test(f) || /(^|\/)drizzle\//.test(f) || /(^|\/)(db|drizzle)\/.*schema.*\.ts$/.test(f)
+    )) {
+      return true;
+    }
+    try {
+      const pkg = fs5.readFileSync(path6.join(repoRoot2, "package.json"), "utf8");
+      return pkg.includes('"drizzle-orm"') || pkg.includes('"drizzle-kit"') || pkg.includes("'drizzle-orm'");
+    } catch {
+      return false;
+    }
+  },
+  relevant: (rel) => /\.(ts|tsx|js|jsx|mjs)$/.test(rel),
+  apply(ctx, files) {
+    let symbols = 0;
+    let relations = 0;
+    for (const f of files) {
+      if (!hasDrizzleMarker(f.content)) continue;
+      const fileSym = fileSymbolOf(ctx.db, f.fileId);
+      if (!fileSym) continue;
+      for (const t of parseDrizzleTables(f.content)) {
+        const id = ensureAdapterSymbol(ctx.db, f.fileId, {
+          name: t.name,
+          type: "model",
+          signature: `table ${t.name} ("${t.table}")`,
+          startLine: t.line,
+          endLine: t.line
+        });
+        symbols++;
+        insertRelation(ctx.db, fileSym, id, "CONTAINS", 1, 1);
+        relations++;
+      }
+    }
+    relations += refreshDrizzleQueries(
+      ctx.db,
+      files.map((f) => ({ fileId: f.fileId, rel: f.rel, content: f.content }))
+    );
+    return { symbols, relations };
+  }
+};
+
+// src/adapters/index.ts
+var ADAPTERS = [prismaAdapter, drizzleAdapter, nextjsAdapter];
+function detectAdapters(files, repoRoot2) {
+  return ADAPTERS.filter((a) => {
+    try {
+      if (!a.detect(files)) return false;
+      if (repoRoot2 && a.confirm) return a.confirm(repoRoot2, files);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+function runAdapters(db, repoRoot2, changed) {
+  const allFiles = db.prepare(`SELECT path FROM files`).all().map((r) => r.path);
+  const active = detectAdapters(allFiles, repoRoot2);
+  if (active.length === 0) return { adapters: [], symbols: 0, relations: 0 };
+  let symbols = 0;
+  let relations = 0;
+  const touched = /* @__PURE__ */ new Set();
+  for (const adapter of active) {
+    const inputs = [];
+    for (const c of changed) {
+      if (!adapter.relevant(c.rel)) continue;
+      const abs = path7.join(repoRoot2, ...c.rel.split("/"));
+      let content;
+      try {
+        content = fs6.readFileSync(abs, "utf8");
+      } catch {
+        continue;
+      }
+      inputs.push({ fileId: c.fileId, rel: c.rel, content });
+    }
+    if (inputs.length === 0) continue;
+    try {
+      const r = adapter.apply({ db, repoRoot: repoRoot2 }, inputs);
+      symbols += r.symbols;
+      relations += r.relations;
+      for (const i of inputs) touched.add(i.fileId);
+    } catch {
+    }
+  }
+  for (const fileId of touched) {
+    const row = db.prepare(`SELECT path FROM files WHERE id = ?`).get(fileId);
+    if (row) {
+      try {
+        syncFileIndex(db, fileId, row.path);
+      } catch {
+      }
+    }
+  }
+  const refreshTargets = (id, relevant, refresh) => {
+    if (!active.some((a) => a.id === id)) return;
+    try {
+      const all = db.prepare(`SELECT id, path FROM files`).all().filter((r) => relevant(r.path));
+      const inputs = [];
+      for (const r of all) {
+        try {
+          inputs.push({
+            fileId: r.id,
+            rel: r.path,
+            content: fs6.readFileSync(path7.join(repoRoot2, ...r.path.split("/")), "utf8")
+          });
+        } catch {
+        }
+      }
+      relations += refresh(db, inputs);
+    } catch {
+    }
+  };
+  refreshTargets("nextjs", nextjsAdapter.relevant, refreshQueries);
+  refreshTargets("drizzle", drizzleAdapter.relevant, refreshDrizzleQueries);
+  return { adapters: active.map((a) => a.id), symbols, relations };
+}
+
 // src/scanner.ts
 function toPosixRel(repoRoot2, abs) {
-  return path6.relative(repoRoot2, abs).split(path6.sep).join("/");
+  return path8.relative(repoRoot2, abs).split(path8.sep).join("/");
 }
 function walk(absDir, out) {
-  const entries = fs5.readdirSync(absDir, { withFileTypes: true });
+  const entries = fs7.readdirSync(absDir, { withFileTypes: true });
   for (const e of entries) {
-    const abs = path6.join(absDir, e.name);
+    const abs = path8.join(absDir, e.name);
     if (e.isDirectory()) {
       if (e.isSymbolicLink()) continue;
       walk(abs, out);
@@ -1031,6 +1507,7 @@ function scanRepository(repoRoot2) {
     }
     const backfill = symbolCount === 0 || ftsCount === 0;
     const pending = [];
+    const metaChanged = [];
     for (const abs of allAbs) {
       const rel = toPosixRel(repoRoot2, abs);
       if (isIgnored(rel, rules)) continue;
@@ -1043,7 +1520,7 @@ function scanRepository(repoRoot2) {
       seenPaths.add(rel);
       let buf;
       try {
-        buf = fs5.readFileSync(abs);
+        buf = fs7.readFileSync(abs);
       } catch {
         continue;
       }
@@ -1056,6 +1533,7 @@ function scanRepository(repoRoot2) {
           pending.push({ fileId: Number(r.lastInsertRowid), rel, content: buf.toString("utf8") });
         } else {
           indexMetaFile(db, Number(r.lastInsertRowid), rel);
+          metaChanged.push({ fileId: Number(r.lastInsertRowid), rel });
         }
         inserted++;
       } else if (row.hash !== hash || backfill) {
@@ -1064,6 +1542,7 @@ function scanRepository(repoRoot2) {
           pending.push({ fileId: row.id, rel, content: buf.toString("utf8") });
         } else {
           indexMetaFile(db, row.id, rel);
+          metaChanged.push({ fileId: row.id, rel });
         }
         updated++;
       } else {
@@ -1086,6 +1565,11 @@ function scanRepository(repoRoot2) {
     for (const p of phased) {
       indexFileRelations(db, p.fileId, p.rel, p.extraction, p.fileSym);
     }
+    const adapterChanged = [
+      ...pending.map((p) => ({ fileId: p.fileId, rel: p.rel })),
+      ...metaChanged
+    ];
+    const adapterRun = runAdapters(db, repoRoot2, adapterChanged);
     db.prepare(
       `INSERT INTO meta(key, value) VALUES ('last_scan', datetime('now'))
        ON CONFLICT(key) DO UPDATE SET value = excluded.value`
@@ -1101,6 +1585,7 @@ function scanRepository(repoRoot2) {
       metaFiles,
       symbols,
       relationships,
+      adapters: adapterRun.adapters,
       inserted,
       updated,
       unchanged,
@@ -1124,6 +1609,9 @@ function cmdScan(repoRoot2) {
   }
   console.log(`\u2713 ${stats.symbols} symbols`);
   console.log(`\u2713 ${stats.relationships} relationships`);
+  if (stats.adapters.length > 0) {
+    console.log(`\u2713 adapters: ${stats.adapters.join(", ")}`);
+  }
   console.log(
     `\u2713 index: +${stats.inserted} new, ~${stats.updated} updated, =${stats.unchanged} unchanged, -${stats.removed} removed`
   );
@@ -1132,11 +1620,11 @@ function cmdScan(repoRoot2) {
 }
 
 // src/commands/status.ts
-import fs6 from "fs";
-import path7 from "path";
+import fs8 from "fs";
+import path9 from "path";
 function cmdStatus(repoRoot2) {
   const dir = dataDir(repoRoot2);
-  if (!fs6.existsSync(path7.join(dir, "scopecairn.db"))) {
+  if (!fs8.existsSync(path9.join(dir, "scopecairn.db"))) {
     console.log("ScopeCairn");
     console.log("Status: NOT INITIALIZED (run `scopecairn scan`)");
     return;
@@ -1164,6 +1652,14 @@ function cmdStatus(repoRoot2) {
     } catch {
     }
     console.log(`Last scan: ${lastScan}`);
+    try {
+      const paths = db.prepare(`SELECT path FROM files`).all().map((r) => r.path);
+      const adapters = detectAdapters(paths, repoRoot2);
+      if (adapters.length > 0) {
+        console.log(`Adapters: ${adapters.map((a) => a.id).join(", ")}`);
+      }
+    } catch {
+    }
     try {
       const inv = db.prepare(
         `SELECT command, COUNT(*) AS n FROM invocations GROUP BY command ORDER BY n DESC`
@@ -1180,7 +1676,7 @@ function cmdStatus(repoRoot2) {
 }
 function cmdClean(repoRoot2) {
   const dir = dataDir(repoRoot2);
-  fs6.rmSync(dir, { recursive: true, force: true });
+  fs8.rmSync(dir, { recursive: true, force: true });
   console.log(`Cleaned ${dir}`);
 }
 
@@ -1191,8 +1687,8 @@ function cmdRebuild(repoRoot2) {
 }
 
 // src/commands/doctor.ts
-import fs8 from "fs";
-import path9 from "path";
+import fs10 from "fs";
+import path11 from "path";
 
 // src/treesitter.ts
 var cached = null;
@@ -1217,18 +1713,18 @@ async function checkTreeSitter() {
 }
 
 // src/integrate/detect.ts
-import fs7 from "fs";
-import path8 from "path";
+import fs9 from "fs";
+import path10 from "path";
 function detectAgentDir(repoRoot2) {
-  const plural = fs7.existsSync(path8.join(repoRoot2, ".agents"));
-  const singular = fs7.existsSync(path8.join(repoRoot2, ".agent"));
+  const plural = fs9.existsSync(path10.join(repoRoot2, ".agents"));
+  const singular = fs9.existsSync(path10.join(repoRoot2, ".agent"));
   if (singular && !plural) return ".agent";
   return ".agents";
 }
 function detectPrefix(repoRoot2) {
   try {
     const pkg = JSON.parse(
-      fs7.readFileSync(path8.join(repoRoot2, "package.json"), "utf8")
+      fs9.readFileSync(path10.join(repoRoot2, "package.json"), "utf8")
     );
     if (pkg.dependencies?.["scopecairn"] || pkg.devDependencies?.["scopecairn"]) {
       return "npx scopecairn";
@@ -1245,9 +1741,8 @@ function extractPrefixUsed(text) {
 
 // src/integrate/templates.ts
 var MARKER = "<!-- scopecairn:managed -->";
-function agentsMd(prefix) {
-  return `${MARKER}
-# ScopeCairn
+function ruleBody(prefix) {
+  return `# ScopeCairn
 
 ## Wajib untuk setiap task coding
 Sebelum membaca file atau menjalankan grep, jalankan:
@@ -1268,6 +1763,23 @@ Gunakan hasilnya sebagai titik awal. Jangan menjelajah repository dari nol.
 Lewati ScopeCairn hanya untuk pertanyaan non-coding.
 `;
 }
+function agentsMd(prefix) {
+  return `${MARKER}
+${ruleBody(prefix)}`;
+}
+function genericRuleMd(prefix) {
+  return `${MARKER}
+${ruleBody(prefix)}`;
+}
+function cursorRuleMdc(prefix) {
+  return `---
+description: ScopeCairn codebase rules \u2014 panggil scopecairn context di tiap task coding
+alwaysApply: true
+---
+
+${MARKER}
+${ruleBody(prefix)}`;
+}
 function skillMd(prefix) {
   return `---
 name: scopecairn
@@ -1313,6 +1825,74 @@ tambahkan entri berikut ke Terminal Allow List Antigravity
 Catatan: ScopeCairn tidak mengubah pengaturan IDE Anda secara otomatis.`;
 }
 
+// src/integrate/matrix.ts
+var AGENT_MATRIX = [
+  {
+    id: "agents",
+    label: "AGENTS.md (universal: Codex, Aider, Opencode, Amp, Jules, ...)",
+    rel: "AGENTS.md",
+    mode: "merge",
+    render: agentsMd,
+    presentMarker: "AGENTS.md"
+  },
+  {
+    id: "claude",
+    label: "Claude Code",
+    rel: "CLAUDE.md",
+    mode: "merge",
+    render: genericRuleMd,
+    presentMarker: "CLAUDE.md"
+  },
+  {
+    id: "gemini",
+    label: "Gemini / Antigravity CLI",
+    rel: "GEMINI.md",
+    mode: "merge",
+    render: genericRuleMd,
+    presentMarker: "GEMINI.md"
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    rel: ".cursor/rules/scopecairn.mdc",
+    mode: "new",
+    render: cursorRuleMdc,
+    presentMarker: ".cursor"
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    rel: ".windsurf/rules/scopecairn.md",
+    mode: "new",
+    render: genericRuleMd,
+    presentMarker: ".windsurf"
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot",
+    rel: ".github/copilot-instructions.md",
+    mode: "merge",
+    render: genericRuleMd,
+    presentMarker: ".github"
+  },
+  {
+    id: "kiro",
+    label: "Kiro",
+    rel: ".kiro/steering/scopecairn.md",
+    mode: "new",
+    render: genericRuleMd,
+    presentMarker: ".kiro"
+  }
+];
+function findTarget(id) {
+  return AGENT_MATRIX.find((t) => t.id === id);
+}
+function parseAgentsOption(raw) {
+  if (!raw) return null;
+  if (raw.trim().toLowerCase() === "all") return "all";
+  return raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+
 // src/commands/doctor.ts
 function tick(ok) {
   return ok ? "\u2713" : "\u2717";
@@ -1340,41 +1920,45 @@ 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 = fs8.existsSync(dbPath(repoRoot2));
+    dbOk = fs10.existsSync(dbPath(repoRoot2));
     graphDetail = ` (${s} symbols, ${r} rels)`;
   } catch {
     dbOk = false;
   }
   console.log(`${tick(dbOk)} Database ${dbPath(repoRoot2)}${graphDetail}`);
-  const protPath = path9.join(dataDir(repoRoot2), "protected.yml");
-  console.log(`${tick(fs8.existsSync(protPath))} Protected ${protPath}`);
+  const protPath = path11.join(dataDir(repoRoot2), "protected.yml");
+  console.log(`${tick(fs10.existsSync(protPath))} Protected ${protPath}`);
   const expectedPrefix = detectPrefix(repoRoot2);
   const agentDir = detectAgentDir(repoRoot2);
-  const agentsPath = path9.join(repoRoot2, "AGENTS.md");
-  let agentsOk = false;
-  let agentsPrefix = null;
-  if (fs8.existsSync(agentsPath)) {
-    const text = fs8.readFileSync(agentsPath, "utf8");
-    agentsOk = text.includes(MARKER);
-    agentsPrefix = extractPrefixUsed(text);
-  }
-  console.log(`${tick(agentsOk)} AGENTS.md (${agentsOk ? "blok ScopeCairn ada" : "hilang \u2014 jalankan `scopecairn init`"})`);
-  const skillPath = path9.join(repoRoot2, agentDir, "skills", "scopecairn", "SKILL.md");
-  const skillOk = fs8.existsSync(skillPath);
-  console.log(`${tick(skillOk)} Skill (${agentDir}/skills/scopecairn/SKILL.md)`);
-  const wfPath = path9.join(repoRoot2, "workflows", "scopecairn.md");
-  console.log(`${tick(fs8.existsSync(wfPath))} Workflow (workflows/scopecairn.md, opsional)`);
   let prefixOk = true;
-  if (agentsOk && agentsPrefix && agentsPrefix !== expectedPrefix) {
-    prefixOk = false;
-    console.log(
-      `\u2717 Prefix tak konsisten: AGENTS.md memakai \`${agentsPrefix}\`, instalasi terdeteksi \`${expectedPrefix}\`. Jalankan ulang \`scopecairn init\`.`
-    );
-  } else if (agentsOk) {
+  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 (!text.includes(MARKER)) continue;
+    matrixOk++;
+    const used = extractPrefixUsed(text);
+    if (used && used !== expectedPrefix) {
+      prefixOk = false;
+      console.log(
+        `\u2717 Prefix tak konsisten di ${t.rel}: memakai \`${used}\`, instalasi terdeteksi \`${expectedPrefix}\`. Jalankan ulang \`scopecairn init\`.`
+      );
+    }
+  }
+  console.log(`${tick(matrixOk > 0)} Agent matrix (${matrixOk}/${AGENT_MATRIX.length} target terpasang)`);
+  if (matrixOk === 0) {
+    console.log(`  Jalankan \`scopecairn init --agents all\` untuk memasang semua.`);
+  } else if (prefixOk) {
     console.log(`\u2713 Prefix konsisten (\`${expectedPrefix} context\`)`);
   }
+  const skillPath = path11.join(repoRoot2, agentDir, "skills", "scopecairn", "SKILL.md");
+  const skillOk = fs10.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(`i Strict Mode mengabaikan allowlist \u2014 semua perintah tetap perlu persetujuan.`);
-  const healthy = nodeOk && sqliteOk && ts.ok && dbOk && agentsOk && skillOk && prefixOk;
+  const healthy = nodeOk && sqliteOk && ts.ok && dbOk && matrixOk > 0 && skillOk && prefixOk;
   console.log(`Status: ${healthy ? "HEALTHY" : "DEGRADED (see \u2717 above)"}`);
 }
 
@@ -1516,8 +2100,8 @@ function cmdQuery(repoRoot2, text) {
 }
 
 // src/commands/read.ts
-import fs9 from "fs";
-import path10 from "path";
+import fs11 from "fs";
+import path12 from "path";
 function cmdRead(repoRoot2, kind, name) {
   if (kind !== "symbol") {
     console.log(`Unknown read kind "${kind}". Usage: scopecairn read symbol <nama>`);
@@ -1533,10 +2117,10 @@ function cmdRead(repoRoot2, kind, name) {
       return;
     }
     const row = db.prepare(`SELECT start_line, end_line FROM symbols WHERE id = ?`).get(node.id);
-    const abs = path10.join(repoRoot2, node.file);
+    const abs = path12.join(repoRoot2, node.file);
     let lines;
     try {
-      lines = fs9.readFileSync(abs, "utf8").split("\n");
+      lines = fs11.readFileSync(abs, "utf8").split("\n");
     } catch {
       console.log(`Cannot read ${node.file}.`);
       return;
@@ -2072,7 +2656,7 @@ function cmdImpact(repoRoot2, target, opts = {}) {
         }
         if (out.length >= 15) break;
       }
-      if (out.length === 0 && fileHit != null && (rel === "CALLS" || rel === "USES")) {
+      if (out.length === 0 && fileHit != null && (rel === "CALLS" || rel === "USES" || rel === "QUERIES")) {
         try {
           const rows = db.prepare(
             `SELECT DISTINCT t.name AS n, f.path AS p
@@ -2124,6 +2708,9 @@ function cmdImpact(repoRoot2, target, opts = {}) {
       `Diimpor oleh: ${byRel("IMPORTS", "in").join(", ") || "-"}`,
       `Memanggil: ${byRel("CALLS", "out").join(", ") || "-"}`,
       `Dipanggil oleh: ${byRel("CALLS", "in").join(", ") || "-"}`,
+      `Mengquery: ${byRel("QUERIES", "out").join(", ") || "-"}`,
+      `Diquery oleh: ${byRel("QUERIES", "in").join(", ") || "-"}`,
+      `Rute: ${[...byRel("ROUTES_TO", "out"), ...byRel("ROUTES_TO", "in")].join(", ") || "-"}`,
       ``,
       `## Indirect (${indirect.size})`,
       ...[...indirect.values()].slice(0, 15).map((v) => `- ${v.name} (${v.type}, ${v.file}) via ${v.via}`),
@@ -2144,9 +2731,32 @@ function cmdImpact(repoRoot2, target, opts = {}) {
 }
 
 // src/commands/init.ts
-import fs10 from "fs";
-import path11 from "path";
-function cmdInit(repoRoot2) {
+import fs12 from "fs";
+import path13 from "path";
+function writeTarget(repoRoot2, target, prefix) {
+  const abs = path13.join(repoRoot2, target.rel);
+  const block = target.render(prefix);
+  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";
+  }
+  if (fs12.existsSync(abs)) {
+    const cur = fs12.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";
+    }
+    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";
+}
+function cmdInit(repoRoot2, opts = {}) {
   console.log("ScopeCairn");
   console.log("\u2713 Repository detected");
   const stats = scanRepository(repoRoot2);
@@ -2156,39 +2766,47 @@ function cmdInit(repoRoot2) {
   console.log(`\u2713 ${stats.relationships} relationships`);
   const prefix = detectPrefix(repoRoot2);
   const agentDir = detectAgentDir(repoRoot2);
-  const agentsPath = path11.join(repoRoot2, "AGENTS.md");
-  const block = agentsMd(prefix);
-  if (fs10.existsSync(agentsPath)) {
-    const cur = fs10.readFileSync(agentsPath, "utf8");
-    if (cur.includes(MARKER)) {
-      const re = new RegExp(`${MARKER}[\\s\\S]*?(?=\\n#[^#]|$)`, "");
-      const next = cur.replace(re, block.trimEnd());
-      fs10.writeFileSync(agentsPath, next.trimEnd() + "\n");
-      console.log("\u2713 AGENTS.md updated (blok ScopeCairn diganti)");
-    } else {
-      fs10.writeFileSync(agentsPath, cur.trimEnd() + "\n\n" + block);
-      console.log("\u2713 AGENTS.md extended (blok ScopeCairn ditambahkan)");
+  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 {
-    fs10.writeFileSync(agentsPath, block);
-    console.log("\u2713 AGENTS.md generated");
+    targets = [AGENT_MATRIX[0]];
+    for (const t of AGENT_MATRIX.slice(1)) {
+      if (fs12.existsSync(path13.join(repoRoot2, t.presentMarker))) targets.push(t);
+    }
   }
-  const skillPath = path11.join(repoRoot2, agentDir, "skills", "scopecairn", "SKILL.md");
-  fs10.mkdirSync(path11.dirname(skillPath), { recursive: true });
-  fs10.writeFileSync(skillPath, skillMd(prefix));
-  console.log(`\u2713 Skill installed (${path11.relative(repoRoot2, skillPath)})`);
-  const wfPath = path11.join(repoRoot2, "workflows", "scopecairn.md");
-  fs10.mkdirSync(path11.dirname(wfPath), { recursive: true });
-  fs10.writeFileSync(wfPath, workflowMd(prefix));
-  console.log(`\u2713 Workflow installed (${path11.relative(repoRoot2, wfPath)})`);
+  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)})`);
   console.log("Ready.");
   console.log("");
   console.log(allowlistGuide(prefix));
 }
 
 // src/benchmark/run.ts
-import fs11 from "fs";
-import path12 from "path";
+import fs13 from "fs";
+import path14 from "path";
 
 // src/benchmark/dataset.ts
 var BENCHMARK_TASKS = [
@@ -2245,7 +2863,7 @@ var BENCHMARK_TASKS = [
 // src/benchmark/run.ts
 function fileChars(repoRoot2, rel) {
   try {
-    return fs11.readFileSync(path12.join(repoRoot2, rel), "utf8").length;
+    return fs13.readFileSync(path14.join(repoRoot2, rel), "utf8").length;
   } catch {
     return 0;
   }
@@ -2394,11 +3012,66 @@ function cmdBenchmark(repoRoot2, opts = {}) {
   }
 }
 
+// package.json
+var package_default = {
+  name: "scopecairn",
+  version: "0.2.0",
+  description: "ScopeCairn \u2014 Codebase Intelligence & Agent Optimization Layer (local-first)",
+  license: "MIT",
+  type: "module",
+  engines: {
+    node: ">=20"
+  },
+  bin: {
+    scopecairn: "dist/cli.js"
+  },
+  files: [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  keywords: [
+    "code-intelligence",
+    "knowledge-graph",
+    "ai-agents",
+    "coding-assistant",
+    "static-analysis",
+    "developer-tools"
+  ],
+  scripts: {
+    build: "tsup",
+    prepublishOnly: "npm run typecheck && npm run build",
+    dev: "tsx src/cli.ts",
+    scan: "tsx src/cli.ts scan",
+    status: "tsx src/cli.ts status",
+    doctor: "tsx src/cli.ts doctor",
+    clean: "tsx src/cli.ts clean",
+    rebuild: "tsx src/cli.ts rebuild",
+    typecheck: "tsc --noEmit"
+  },
+  dependencies: {
+    commander: "^12.1.0",
+    ignore: "^7.0.0",
+    "web-tree-sitter": "^0.25.0"
+  },
+  devDependencies: {
+    "@types/node": "^22.7.0",
+    tsup: "^8.3.0",
+    tsx: "^4.19.0",
+    typescript: "^5.6.0"
+  }
+};
+
 // src/cli.ts
 var program = new Command();
-program.name("scopecairn").description("ScopeCairn \u2014 local-first codebase intelligence layer").version("0.1.0");
+program.name("scopecairn").description("ScopeCairn \u2014 local-first codebase intelligence layer").version(package_default.version);
 function repoRoot() {
-  return path13.resolve(process.cwd());
+  return path15.resolve(process.cwd());
+}
+function resolveRoot(given) {
+  if (!given) return repoRoot();
+  return path15.resolve(process.cwd(), given);
 }
 program.command("scan").description("Index repository (Fase 1: files + hash + language)").action(() => cmdScan(repoRoot()));
 program.command("status").description("Show index status").action(() => cmdStatus(repoRoot()));
@@ -2416,8 +3089,13 @@ program.command("context <task>").description("Main entry point: auto-refresh +
 program.command("impact <target>").description("Change impact analysis: file, symbol, function, or class").option("--no-refresh", "skip incremental refresh (debugging/benchmark)").action(
   (target, opts) => cmdImpact(repoRoot(), target, opts)
 );
-program.command("init").description("Initial indexing + generate AGENTS.md, Skill, Workflow").action(() => cmdInit(repoRoot()));
+program.command("init [path]").description("Initial indexing + generate AGENTS.md, Skill, Workflow, agent matrix").option("--agents <list>", "agent targets: comma list from agents,claude,gemini,cursor,windsurf,copilot,kiro, or 'all'").action(
+  (targetPath, opts) => cmdInit(resolveRoot(targetPath), opts)
+);
 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)
 );
 program.parseAsync(process.argv);
+export {
+  resolveRoot
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scopecairn",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ScopeCairn — Codebase Intelligence & Agent Optimization Layer (local-first)",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/scopecairn/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: scopecairn
+description: Set up ScopeCairn codebase intelligence in a repository. Use when the user says "scopecairn", "scopecairn ./", "scopecairn <path>", asks to index a repo for an AI agent, or wants the agent to understand a codebase with ScopeCairn.
+---
+
+# ScopeCairn setup
+
+The user invoked ScopeCairn with a path (e.g. `scopecairn ./`).
+Your job: run project setup so this repo becomes agent-readable.
+
+## Steps
+
+1. Resolve the path: `.` or `./` means the current project directory.
+   A relative or absolute path means that directory.
+2. Run setup in that directory:
+   `scopecairn init <path>` (or `npx -y scopecairn init <path>` if it is not installed).
+3. If the command is not found, install globally first
+   (`npm install -g scopecairn`), then retry step 2.
+4. Report back, briefly: files indexed, symbols, relationships,
+   detected adapters, and which integration files were written
+   (AGENTS.md, Skill, Workflow, agent matrix).
+
+## Rules
+
+- Setup is read-only toward source code. `init` only adds/updates
+  `AGENTS.md` (marker block), the agent Skill, the Workflow file,
+  and the `.scopecairn/` index directory. Never refactor user code.
+- If a terminal command needs approval, ask once — after setup,
+  recommend the user allowlist the read-only commands printed by `init`.
+- After setup, coding tasks go through `scopecairn context "<task>"`,
+  never by re-exploring the repository from zero.