@rryando/arcs 3.3.2 → 3.4.0

package/opencode/arcs/skills/deep-pr-review/{graphify-diff.md → codegraph-diff.md}

@@ -1,19 +1,21 @@
-# Graphify Diff Algorithm
+# Codegraph Diff Algorithm
 
-`graphify` has no native "diff against PR" command. This file defines how `deep-pr-review` builds coupling/duplication checks on top of the existing `affected`, `query`, and `diagnose multigraph` primitives.
+`codegraph` has no native "diff against PR" command. This file defines how `deep-pr-review` builds coupling/duplication checks on top of the existing `impact`, `callers`/`callees`, and `query` primitives.
 
 ## Prerequisites
 
 ```bash
-which graphify || echo "skip"            # graceful absence
-ls graphify-out/graph.json 2>/dev/null   # graph must exist
+which codegraph || echo "skip"           # graceful absence
+codegraph status --json 2>/dev/null      # index must exist + be initialized
 ```
 
-If graphify is missing or `graph.json` is older than the PR's base commit, refresh:
+If codegraph is missing or the index is stale relative to the PR's base commit, refresh:
 ```bash
-graphify update .
+codegraph sync .        # incremental; or `codegraph index . --force` for a full rebuild
 ```
 
+The index lives in `.codegraph/` (SQLite, gitignored) — there is no `graph.json` file.
+
 ## Step 1: Extract changed symbols from the diff
 
 ```bash
@@ -22,7 +24,7 @@ gh pr diff <num> --patch > /tmp/pr.diff
 
 Parse `/tmp/pr.diff` to extract changed symbols:
 - For each `+++ b/<file>` hunk, capture the file path
-- For each added / modified function or exported identifier, capture `<file>::<symbol>`
+- For each added / modified function or exported identifier, capture `<symbol>` (codegraph addresses symbols by name, not `<file>::<symbol>`)
 - Skip pure deletions (handled separately under "removed coupling" check)
 
 Heuristic for symbol extraction (language-aware):
@@ -32,16 +34,19 @@ Heuristic for symbol extraction (language-aware):
 - Rust: `fn X`, `struct X`, `impl X`
 - Other: fall back to file-level granularity
 
-## Step 2: Run `affected` per changed symbol
+## Step 2: Run `impact` per changed symbol
 
 ```bash
-graphify affected "<file>::<symbol>" --depth 2 --json
+codegraph impact "<symbol>" --json      # what code is affected by changing this symbol
+codegraph callers "<symbol>" --json     # direct callers (one hop)
 ```
 
+`codegraph impact` is the closest equivalent to the old `affected --depth N`: it walks the reverse-dependency closure for a symbol. Use `callers` for a precise one-hop view when `impact` is too broad.
+
 Collect for each symbol:
-- **Fan-out callers** — who depends on this symbol (changes ripple here)
-- **Fan-out depth** — how many hops to leaves
-- **Cross-module edges** — callers in different top-level dirs
+- **Fan-out callers** — who depends on this symbol (changes ripple here), from `callers` / `impact`
+- **Fan-out reach** — size of the impact set (proxy for blast radius)
+- **Cross-module edges** — callers in different top-level dirs (derive from each caller's `file_path`)
 
 ## Step 3: Detect surprising fan-out
 
@@ -57,23 +62,15 @@ Flag as 🟠 **risk** in the report when:
 
 For each new function added in the diff, run:
 ```bash
-graphify query "functions similar to <new-symbol-signature>" --budget 8 --json
-```
-
-If results include symbols with similar signatures (≥70% name overlap or matching parameter shape), flag as 🟡 **suggestion** with citation `graphify: similar to <existing-symbol>` and propose extraction or reuse.
-
-## Step 5: Diagnose multigraph (architectural drift)
-
-```bash
-graphify diagnose multigraph --json
+codegraph query "<new-symbol-name or signature keywords>" --json
 ```
 
-If the PR introduces edges that contribute to a multigraph collapse (multiple edges between the same node pair), flag as 🟠 **risk** with handoff to `architecture-review`. Same-endpoint multi-edges are a structural duplication signal worth surfacing but not worth diagnosing inline.
+`codegraph query` is a symbol search over the index. If results include symbols with similar names/signatures (≥70% name overlap or matching parameter shape), flag as 🟡 **suggestion** with citation `codegraph: similar to <existing-symbol>` and propose extraction or reuse.
 
-## Step 6: Aggregate findings
+## Step 5: Aggregate findings
 
-Each graphify-derived finding must include:
-- The `graphify` command that produced it (for reproducibility)
+Each codegraph-derived finding must include:
+- The `codegraph` command that produced it (for reproducibility)
 - The cited symbol(s) — use backticks
 - The cited module path(s)
 - A finding ID for re-review tracking: `<file>:<line>:<dimension>:<short-hash>`
@@ -84,19 +81,18 @@ Each graphify-derived finding must include:
   - All exported / public symbols first (always)
   - Then internal symbols by descending hunk size
 - Skip step 4 (duplication) entirely if diff size exceeds 1500 LOC — too noisy
-- Skip step 5 (multigraph) if `graphify diagnose multigraph` runtime exceeds 10s — log and continue without
 
 ## Graceful degradation
 
-If any graphify call fails or returns empty:
-- Note in report: `Graphify step <N> unavailable: <reason>` under "Cleared Dimensions"
+If any codegraph call fails or returns empty:
+- Note in report: `Codegraph step <N> unavailable: <reason>` under "Cleared Dimensions"
 - Continue with the remaining dimensions
-- Never let a graphify failure abort the review
+- Never let a codegraph failure abort the review
 
 ## Output integration
 
-Graphify findings flow back into the standard finding pipeline. Each one is:
-- Cited as `graphify: <one-line observation>`
+Codegraph findings flow back into the standard finding pipeline. Each one is:
+- Cited as `codegraph: <one-line observation>`
 - Severity-classified (most are 🟡 suggestion or 🟠 risk; rarely 🔴)
 - Attached to a specific file+line if possible; otherwise lives in the top-level review body
 - Tagged for re-review with `<!-- arcs:deep-review:<finding-id> -->`

package/opencode/arcs/skills/deep-pr-review/review-template.md

@@ -31,7 +31,7 @@ Used as the `body` field of `gh api repos/{owner}/{repo}/pulls/{pull_number}/rev
 ### Citations Used
 - AGENTS.md §<section> — <what was checked>
 - knowledge/<id> — <what was checked>
-- graphify — <observations, if run>
+- codegraph — <observations, if run>
 
 ---
 <!-- arcs:deep-review:meta version=1 commit=<HEAD_SHA> rubric=<activated> mode=<posting-mode> -->
@@ -51,7 +51,7 @@ Used as the `body` field of `gh api repos/{owner}/{repo}/pulls/{pull_number}/rev
 
 <optional 1-2 sentences of why, only if not obvious from problem>
 
-Citation: <AGENTS.md §x | knowledge/<id> | graphify | principle: <name>>
+Citation: <AGENTS.md §x | knowledge/<id> | codegraph | principle: <name>>
 
 ​```suggestion
 <replacement code — only for small line replacements>

package/opencode/arcs/skills/{enriching-graphify-proposals → enriching-codegraph-proposals}/SKILL.md

@@ -1,17 +1,17 @@
 ---
-name: enriching-graphify-proposals
-description: Use when `arcs project init` or `arcs graphify-sync` returns `pending_enrichment: true` — drives the per-proposal verdict loop (keep/drop/merge) and produces agent-authored knowledge entries from raw graphify proposals.
+name: enriching-codegraph-proposals
+description: Use when `arcs project init` or `arcs codegraph-sync` returns `pending_enrichment: true` — drives the per-proposal verdict loop (keep/drop/merge) and produces agent-authored knowledge entries from raw codegraph proposals.
 ---
 
-# Skill: enriching-graphify-proposals
+# Skill: enriching-codegraph-proposals
 
 ## When
 
-The CLI surfaced raw graphify proposals and is waiting for an agent to turn them into real knowledge entries. Mandatory triggers:
+The CLI surfaced raw codegraph proposals and is waiting for an agent to turn them into real knowledge entries. Mandatory triggers:
 
-- `arcs project init` returned `graphify.pending_enrichment: true` in its JSON envelope.
-- `arcs graphify-sync` returned `pending_enrichment: true`.
-- User said "enrich the proposals", "process the graphify queue", "promote the pending proposals", or similar.
+- `arcs project init` returned `codegraph.pending_enrichment: true` in its JSON envelope.
+- `arcs codegraph-sync` returned `pending_enrichment: true`.
+- User said "enrich the proposals", "process the codegraph queue", "promote the pending proposals", or similar.
 
 > **Read-write skill.** This skill mutates the DAG via `arcs proposal promote/drop`. Self-score ≥80% via `confidence-gate` before each promote.
 
@@ -75,7 +75,7 @@ Use `arcs proposal promote --merge-with=<existing-id>` when:
 - `suggestedDedupCandidates` lists an existing knowledge entry whose `kind` matches the proposal's natural kind, AND
 - The proposal adds genuinely new structural facts the existing entry does not already document (e.g. precise degree numbers, additional top hubs, cross-module edges, fileCount).
 
-The agent appends a `## From graphify analysis` section to the existing entry — it does NOT replace prior body content. Treat the existing entry as the spine; the merge adds a graph-evidence rib.
+The agent appends a `## From codegraph analysis` section to the existing entry — it does NOT replace prior body content. Treat the existing entry as the spine; the merge adds a graph-evidence rib.
 
 ## Enrichment Output Contract
 

package/opencode/arcs/skills/init-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: init-project
-description: Use when initializing a new ARCS project — bootstrapping a repo into the DAG with metadata, docs, and structural knowledge entries. Covers gather → present summary → init → graphify ingestion → fan-out analysis across typed sub-agents.
+description: Use when initializing a new ARCS project — bootstrapping a repo into the DAG with metadata, docs, and structural knowledge entries. Covers gather → present summary → init → codegraph ingestion → fan-out analysis across typed sub-agents.
 ---
 
 # Skill: init-project
@@ -21,11 +21,11 @@ flowchart TD
     B --> C[Present summary to user]
     C -->|user confirms| D[arcs project init]
     D --> E[arcs project update-doc × 4]
-    E --> F{graphify on PATH?}
-    F -->|yes| G[graphify update --force --no-cluster]
+    E --> F{codegraph on PATH?}
+    F -->|yes| G[codegraph index --force --quiet]
     F -->|no| H[Skip graph step, log gap]
     G --> G2[ingestGraph → ≤20 proposals]
-    G2 --> G3[graphify query / explain for enrichment]:::sub
+    G2 --> G3[codegraph MCP explore / impact for enrichment]:::sub
     H & G3 --> I[Fan out: system-architect + docs-researcher + tech-architect]:::sub
     I --> J[Collect proposals → dedup → arcs knowledge create × N]
     J --> K[Done]
@@ -44,33 +44,33 @@ Discovery: `arcs --commands --json`. Mutating commands run directly — no token
 - Verify `dependsOn` targets exist via `arcs project list --json`
 - `arcs project init` creates empty `plans/`, `knowledge/`, `tasks/` indexes — don't pre-populate
 - Repo analysis is **fan-out across typed agents**, never a generic "analysis sub-agent" (see Agent Dispatch below)
-- Never block INIT on graphify — it's optional. Skip cleanly if missing.
+- Never block INIT on codegraph — it's optional. Skip cleanly if missing.
 
-## Graphify Sub-Flow (DEFAULT: ON when binary present)
+## Codegraph Sub-Flow (DEFAULT: ON when binary present)
 
-The orchestrator runs graphify directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals are durable on the proposal-store ledger; agents enrich them into knowledge entries via the `enriching-graphify-proposals` skill. This is the default path when `graphify` is on PATH; skip cleanly otherwise.
+The orchestrator runs codegraph directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals are durable on the proposal-store ledger; agents enrich them into knowledge entries via the `enriching-codegraph-proposals` skill. This is the default path when `codegraph` is on PATH; skip cleanly otherwise.
 
-1. **Detect:** call `detectGraphify()` from `src/utils/graphify.ts`. If unavailable, log "graphify not on PATH; proceeding without graph signal" and skip steps 3–6.
-2. **Trust the gitignore guarantee:** `runExtraction()` already auto-appends `graphify-out/` to `.gitignore` via `ensureGitignoreEntry`. Do NOT redundantly check or modify `.gitignore` from agents — running extraction is sufficient.
-3. **Extract** (AST-only, no LLM API key required):
+1. **Detect:** call `detectCodegraph()` from `src/utils/codegraph.ts`. If unavailable, log "codegraph not on PATH; proceeding without graph signal" and skip steps 3–6.
+2. **Trust the gitignore guarantee:** `runIndex()` already auto-appends `.codegraph/` to `.gitignore` via `ensureGitignoreEntry`. Do NOT redundantly check or modify `.gitignore` from agents — running the index is sufficient.
+3. **Index** (project-based; CLI drives the bundled runtime — no LLM API key required):
    ```bash
-   graphify update <workspacePath> --force --no-cluster
+   codegraph index <workspacePath> --force --quiet
    ```
-   Produces `<workspacePath>/graphify-out/graph.json`.
-4. **Ingest as proposals:** `arcs project init` internally calls `ingestGraph(graphJsonPath, slug)`, which writes up to 20 structural proposals to `proposals/graphify.json` (test files filtered):
-   - 8 god nodes (`kind=module`, top 5% degree)
-   - 8 architecture clusters (`kind=architecture`, by community or directory grouping)
-   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs)
-
-   Graphify never writes directly to the knowledge surface. The init envelope returns `data.graphify.pending_enrichment: true` to signal that proposals are waiting.
-5. **Enrich** with the `enriching-graphify-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), persist via `arcs proposal promote` and `arcs proposal drop`. The skill encodes the decision heuristics, output contract, and cost discipline; do not paraphrase.
-6. **Optional graph queries** for evidence during enrichment (sub-agents may run these):
-   - `graphify query "entry points and main commands" --graph graphify-out/graph.json --budget 2000` → seeds for "key files" reference entries
-   - `graphify query "core data flow" --graph graphify-out/graph.json --budget 2000` → seeds for "core modules" entries
-   - `graphify explain "<godNodeLabel>" --graph graphify-out/graph.json` → plain-language summary for module entry bodies
-   - `graphify affected "<critical-symbol>" --graph graphify-out/graph.json --depth 2` → reverse-impact map for high-risk modules
-   - `graphify path "<A>" "<B>" --graph graphify-out/graph.json` → shortest dependency path for architecture entries
-7. **Hand to typed agents** (in parallel) for code-grounded follow-up entries that go beyond what graphify proposals cover — see **Agent Dispatch** below.
+   Builds a per-project codegraph index under `<workspacePath>/.codegraph/`.
+4. **Ingest as proposals:** `arcs project init` internally calls `ingestGraph(slug)`, which parses codegraph CLI `--json` output and writes up to 20 structural proposals to `proposals/graphify.json` (filename retained for compatibility; rename pending; test files filtered):
+   - 8 god nodes (`kind=module`, ranked by callers+callees / impact as a proxy for degree)
+   - 8 architecture clusters (`kind=architecture`, synthesized pseudo-communities by directory prefix — codegraph has no community/cluster export)
+   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs; relations hard-coded as `["calls"]`)
+
+   Codegraph never writes directly to the knowledge surface. The init envelope returns `data.codegraph.pending_enrichment: true` to signal that proposals are waiting.
+5. **Enrich** with the `enriching-codegraph-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), persist via `arcs proposal promote` and `arcs proposal drop`. The skill encodes the decision heuristics, output contract, and cost discipline; do not paraphrase.
+6. **Optional graph queries** for evidence during enrichment (sub-agents may run these via the codegraph MCP server, which auto-syncs through its own file watcher):
+   - `codegraph_search "entry points and main commands"` → seeds for "key files" reference entries
+   - `codegraph_explore` on core modules → seeds for "core modules" entries
+   - `codegraph_node "<godNodeLabel>"` → structural summary for module entry bodies
+   - `codegraph_impact "<critical-symbol>"` → reverse-impact map for high-risk modules
+   - `codegraph_callers` / `codegraph_callees "<symbol>"` → dependency paths for architecture entries
+7. **Hand to typed agents** (in parallel) for code-grounded follow-up entries that go beyond what codegraph proposals cover — see **Agent Dispatch** below.
 
 ## Content Guidelines
 
@@ -93,8 +93,8 @@ Update via `arcs project update-doc <slug> <doc> --content="..."`.
 | `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
 
 Dispatch in parallel — load `dispatching-parallel-agents`. Each agent receives:
-- The relevant `KnowledgeProposal` records from `ingestGraph` (so they don't rediscover what graphify already found)
-- Targeted graphify queries for evidence (e.g., `graphify explain` output for the modules they own)
+- The relevant `KnowledgeProposal` records from `ingestGraph` (so they don't rediscover what codegraph already found)
+- Targeted codegraph queries for evidence (e.g., `codegraph_node` / `codegraph_impact` output for the modules they own)
 - Explicit scope (which files / which kinds to produce)
 
 Each agent returns finalized proposals: `{title, kind, summary, keywords, sourceFiles, body}`. The orchestrator dedups, then writes the entries directly via `arcs knowledge create` (or `arcs batch`).
@@ -104,15 +104,15 @@ Each agent returns finalized proposals: `{title, kind, summary, keywords, source
 | Category | Kind | What to discover | Primary agent |
 |----------|------|------------------|---------------|
 | tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
-| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (use `graphify query "entry points"`) |
+| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (use `codegraph_search "entry points"`) |
 | code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `qa-analyst` or `system-architect` |
 | coding style | `pattern` | Formatting, linting, import ordering, file organization | `qa-analyst` |
-| core modules | `module` | Core modules / shared functions — what, where, interconnections | `system-architect` (god nodes from graphify) |
+| core modules | `module` | Core modules / shared functions — what, where, interconnections | `system-architect` (god nodes from codegraph) |
 | external services | `module` | APIs, databases, message queues the project interacts with | `docs-researcher` |
 | third-party libraries | `reference` | Key dependencies and why they are used | `docs-researcher` |
 | features | `feature` | Major user-facing or system-facing features | `docs-researcher` |
-| cross-module couplings | `gotcha` | Hot edges between modules surfaced by graphify | `tech-architect` (auto from `ingestGraph`) |
-| architecture clusters | `architecture` | Community / directory groupings from graphify | `system-architect` (auto from `ingestGraph`) |
+| cross-module couplings | `gotcha` | Hot edges between modules surfaced by codegraph | `tech-architect` (auto from `ingestGraph`) |
+| architecture clusters | `architecture` | Pseudo-community / directory groupings from codegraph | `system-architect` (auto from `ingestGraph`) |
 
 ## Worked Example
 
@@ -127,11 +127,11 @@ arcs project init "Foo" --description="Foo CLI tool" --path="$(pwd)" --json
 arcs project update-doc foo overview --content="..." --json
 # ... repeat for tasks, dependencies, knowledge
 
-# 4. Graphify (if available) — runs inside `arcs project init`
-graphify update . --force --no-cluster
-# ingestGraph writes proposals to proposals/graphify.json
-# init envelope: data.graphify.pending_enrichment === true → load
-# `enriching-graphify-proposals` and run the verdict loop:
+# 4. Codegraph (if available) — runs inside `arcs project init`
+codegraph index . --force --quiet
+# ingestGraph parses codegraph CLI --json → proposals/graphify.json (filename retained; rename pending)
+# init envelope: data.codegraph.pending_enrichment === true → load
+# `enriching-codegraph-proposals` and run the verdict loop:
 arcs proposal list foo --json
 arcs proposal promote foo <id> --title="..." --summary="..." --body-file=... --kind=module --source-files=... --json
 arcs proposal drop foo <id> --reason="..." --json
@@ -152,6 +152,6 @@ arcs knowledge create foo "Tech stack: TypeScript + Node 20" --kind=architecture
 |-----------|--------|
 | Project already in DAG (slug collision) | Stop. Surface conflict; ask user to rename or use existing |
 | User declines summary | Stop. No mutations performed |
-| `graphify` missing | Continue without graph signal; sub-agents run with code reading only |
+| `codegraph` missing | Continue without graph signal; sub-agents run with code reading only |
 | `dependsOn` target missing | Stop. Ask user to init dependencies first or remove the link |
 | Init succeeds but knowledge fan-out fails | Project exists in DAG; rerun knowledge phase later via SYNC |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rryando/arcs",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "ARCS — DAG-based task orchestration for AI agents. Persistent workflow continuity via graph-structured context.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "opencode/"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "repository": {
     "type": "git",

package/scripts/build-opencode-bundle.mjs

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import {
   normalizeRelativePath,
@@ -8,7 +8,8 @@ import {
   validateDeclaredPath,
 } from "./lib/bundle-helpers.mjs";
 
-const repoRoot = resolve(import.meta.dirname, "..");
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
 const defaultManifestPath = resolve(repoRoot, "opencode/arcs/bundle-runtime.json");
 const defaultOutputRoot = resolve(repoRoot, "opencode/arcs");
 // Files that are repo-authored and must not be pruned. The repo bundle
@@ -19,7 +20,7 @@ const preservedOutputFiles = new Set([
   ".opencode/plugins/arcs.js",
   // ARCS-native skills (authored in this repo, no upstream source)
   // init-project skill — ARCS-native (mirrors orchestrator INIT workflow with
-  // graphify sub-flow, typed-agent dispatch, knowledge categories).
+  // codegraph sub-flow, typed-agent dispatch, knowledge categories).
   "skills/init-project/SKILL.md",
   // Caveman commit skill — adapted from https://github.com/JuliusBrussee/caveman (MIT).
   "skills/caveman-commit/SKILL.md",

package/scripts/deploy-claudecode-bundle.mjs

@@ -31,8 +31,11 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { wireCodegraphMcp } from "./lib/bundle-helpers.mjs";
 
-const repoRoot = resolve(import.meta.dirname, "..");
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
 const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
 const defaultConfigRoot = resolve(homedir(), ".claude");
 const defaultProjectRoot = repoRoot;
@@ -422,6 +425,9 @@ function main() {
     }
   }
 
+  // Best-effort: wire the codegraph MCP server. Skipped on dry-run; never fatal.
+  const codegraphWired = dryRun ? false : wireCodegraphMcp("claude");
+
   const result = {
     dryRun,
     source: bundleRoot,
@@ -431,6 +437,7 @@ function main() {
     filesChanged,
     filesRemoved,
     filesUnchanged,
+    codegraphWired,
   };
 
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/deploy-opencode-bundle.mjs

@@ -23,8 +23,11 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { wireCodegraphMcp } from "./lib/bundle-helpers.mjs";
 
-const repoRoot = resolve(import.meta.dirname, "..");
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
 const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
 const defaultConfigRoot = resolve(homedir(), ".config/opencode");
 
@@ -176,6 +179,9 @@ async function main() {
     }
   }
 
+  // Best-effort: wire the codegraph MCP server. Skipped on dry-run; never fatal.
+  const codegraphWired = dryRun ? false : wireCodegraphMcp("opencode");
+
   const result = {
     dryRun,
     source: bundleRoot,
@@ -186,6 +192,7 @@ async function main() {
     filesUnchanged,
     restartRequired,
     cliRegistered: !dryRun,
+    codegraphWired,
     ...(restartRequired && {
       restartGuidance: "Plugin file changed. Restart opencode for changes to take effect.",
     }),

package/scripts/lib/bundle-helpers.mjs

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { isAbsolute, relative, resolve } from "node:path";
 
 export function normalizeRelativePath(filePath) {
@@ -170,3 +171,19 @@ export function validateDeclaredPath(relativePath, outputRoot, validationRoot) {
 
   return normalizedPath;
 }
+
+export function wireCodegraphMcp(target) {
+  // Best-effort: wire the codegraph MCP server for this host. Non-fatal.
+  // Skipped silently if the codegraph binary is absent.
+  try {
+    const r = spawnSync("codegraph", ["install", `--target=${target}`, "--yes"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 120_000,
+    });
+    if (r.error || r.status !== 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/lint-bundle.mjs

@@ -9,9 +9,12 @@
 // Exit code: 0 if no errors, 1 if errors found.
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const repoRoot = resolve(import.meta.dirname, "..");
+// import.meta.dirname is Node >=20.11; derive it for Node 18 compatibility.
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
 const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
 
 const bundleRoot = process.env.BUNDLE_LINT_BUNDLE_ROOT

package/skills/init-project.md

@@ -19,11 +19,11 @@ flowchart TD
     B --> C[Present summary to user]
     C -->|confirmed| D[arcs project init]
     D --> E[arcs project update-doc × 4]
-    E --> F{graphify on PATH?}
-    F -->|yes| G[graphify update --force --no-cluster]
+    E --> F{codegraph on PATH?}
+    F -->|yes| G[codegraph index --force --quiet]
     F -->|no| H[Skip graph step, log gap]
     G --> G2[ingestGraph → ≤20 proposals]
-    G2 --> G3[graphify query / explain for enrichment]:::sub
+    G2 --> G3[codegraph MCP explore / impact for enrichment]:::sub
     H & G3 --> I[Fan out: system-architect + docs-researcher + tech-architect]:::sub
     I --> J[Collect proposals → dedup → arcs knowledge create × N]
     J --> K[Done]
@@ -43,31 +43,31 @@ Discovery: `arcs --commands --json`
 - Init creates empty plans/ and knowledge/ indexes
 - Repo analysis is **fan-out across typed agents**, not a generic "analysis sub-agent" (see Agent Dispatch table below)
 
-## Graphify Sub-Flow (DEFAULT: ON when binary present)
+## Codegraph Sub-Flow (DEFAULT: ON when binary present)
 
-The orchestrator runs graphify directly during INIT to seed knowledge entries with structural evidence before any sub-agent reads code.
+The orchestrator runs codegraph directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals land on the proposal-store ledger (`pending_enrichment: true`); agents enrich them into knowledge entries via the `enriching-codegraph-proposals` skill.
 
-1. **Detect:** `detectGraphify()` from `src/utils/graphify.ts`. If unavailable, skip cleanly — never block INIT on graphify.
-2. **Trust the gitignore guarantee:** `runExtraction()` already auto-appends `graphify-out/` to `.gitignore` (`ensureGitignoreEntry`). Don't redundantly check or modify `.gitignore` from agents — running extraction is sufficient.
-3. **Extract (AST-only, no LLM key required):**
+1. **Detect:** `detectCodegraph()` from `src/utils/codegraph.ts`. If unavailable, skip cleanly — never block INIT on codegraph.
+2. **Trust the gitignore guarantee:** `runIndex()` already auto-appends `.codegraph/` to `.gitignore` (`ensureGitignoreEntry`). Don't redundantly check or modify `.gitignore` from agents — running the index is sufficient.
+3. **Index (AST-based; CLI drives the bundled runtime, no LLM key required):**
    ```bash
-   graphify update <workspacePath> --force --no-cluster
+   codegraph index <workspacePath> --force --quiet
    ```
-   Produces `graphify-out/graph.json`.
-4. **Ingest:** call internal `ingestGraph(graphJsonPath, slug)` → up to 20 `KnowledgeProposal` records:
-   - 8 god nodes (`kind=module`, top 5% degree, test files filtered)
-   - 8 architecture clusters (`kind=architecture`, by community or directory grouping)
+   Builds a per-project SQLite index under `<workspacePath>/.codegraph/`. There is no `graph.json` artifact.
+4. **Ingest:** `arcs project init` internally calls `ingestGraph(workspacePath, slug)` → up to 20 `KnowledgeProposal` records written to `proposals/graphify.json` (filename retained for compatibility; rename pending; test files filtered):
+   - 8 god nodes (`kind=module`, ranked by callers+callees / impact)
+   - 8 architecture clusters (`kind=architecture`, synthesized pseudo-communities by directory prefix)
    - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs)
-5. **Enrich** with read-only graph queries (sub-agents may run these):
-   - `graphify query "entry points and main commands" --graph graphify-out/graph.json --budget 2000` → seeds for "key files" reference entries
-   - `graphify query "core data flow" --graph graphify-out/graph.json --budget 2000` → seeds for "core modules" entries
-   - `graphify explain "<godNodeLabel>" --graph graphify-out/graph.json` → plain-language summary for module entry bodies
-   - `graphify affected "<critical-symbol>" --graph graphify-out/graph.json --depth 2` → reverse-impact map for high-risk modules
-   - `graphify path "<A>" "<B>" --graph graphify-out/graph.json` → shortest dependency path for architecture entries
+5. **Enrich** with the `enriching-codegraph-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), persist via `arcs proposal promote` and `arcs proposal drop`. Sub-agents may run read-only codegraph MCP queries for evidence (the MCP server auto-syncs via its own file watcher):
+   - `codegraph_search "entry points and main commands"` → seeds for "key files" reference entries
+   - `codegraph_explore` on core modules → seeds for "core modules" entries
+   - `codegraph_node "<godNodeLabel>"` → structural summary for module entry bodies
+   - `codegraph_impact "<critical-symbol>"` → reverse-impact map for high-risk modules
+   - `codegraph_callers` / `codegraph_callees "<symbol>"` → dependency paths for architecture entries
 6. **Hand to typed agents:** the proposals + query results go to the sub-agents listed in **Agent Dispatch** below; they merge graph evidence with code reading and return finalized knowledge entries.
 7. **Write** the entries directly via `arcs batch --file=ops.json` (one batch invocation for all knowledge entries) or `arcs knowledge create` per entry.
 
-If graphify is missing, log "graphify not on PATH; proceeding without graph signal" and skip steps 3–5. Sub-agents still run; they just lack the graph priors.
+If codegraph is missing, log "codegraph not on PATH; proceeding without graph signal" and skip steps 3–5. Sub-agents still run; they just lack the graph priors.
 
 ## Content Guidelines
 
@@ -87,19 +87,19 @@ If graphify is missing, log "graphify not on PATH; proceeding without graph sign
 | `tech-architect` | Cross-module couplings, structural gotchas, lessons | `gotcha`, `lesson` |
 | `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
 
-Dispatch in parallel (load `dispatching-parallel-agents`). Each agent receives the relevant `KnowledgeProposal` records from `ingestGraph` plus targeted graphify queries for evidence. Each agent returns finalized proposals (title, kind, summary, keywords, sourceFiles, body) for the orchestrator to write directly via `arcs knowledge create` (or `arcs batch`).
+Dispatch in parallel (load `dispatching-parallel-agents`). Each agent receives the relevant `KnowledgeProposal` records from `ingestGraph` plus targeted codegraph MCP queries for evidence. Each agent returns finalized proposals (title, kind, summary, keywords, sourceFiles, body) for the orchestrator to write directly via `arcs knowledge create` (or `arcs batch`).
 
 ## Knowledge Categories for Analysis Sub-Agents
 
 | Category | Kind | What to discover | Primary agent |
 |----------|------|------------------|---------------|
 | tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
-| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (graphify query "entry points") |
+| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (codegraph_search "entry points") |
 | code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `qa-analyst` or `system-architect` |
 | coding style | `pattern` | Formatting, linting, import ordering, file organization | `qa-analyst` |
-| core modules | `module` | Core modules/shared functions — what, where, interconnections | `system-architect` (god nodes from graphify) |
+| core modules | `module` | Core modules/shared functions — what, where, interconnections | `system-architect` (god nodes from codegraph) |
 | external services | `module` | APIs, databases, message queues the project interacts with | `docs-researcher` |
 | third-party libraries | `reference` | Key dependencies and why they are used | `docs-researcher` |
 | features | `feature` | Major user-facing or system-facing features | `docs-researcher` |
-| cross-module couplings | `gotcha` | Hot edges between modules surfaced by graphify | `tech-architect` (auto from `ingestGraph`) |
-| architecture clusters | `architecture` | Community/directory groupings from graphify | `system-architect` (auto from `ingestGraph`) |
+| cross-module couplings | `gotcha` | Hot edges between modules surfaced by codegraph | `tech-architect` (auto from `ingestGraph`) |
+| architecture clusters | `architecture` | Pseudo-community/directory groupings from codegraph | `system-architect` (auto from `ingestGraph`) |