arceus-s 1.6.4

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "arceus-s",
+  "version": "1.6.4",
+  "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
+  "author": "Chandan Kumar Behera",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "homepage": "https://github.com/Sirius6907/Arceus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sirius6907/Arceus.git",
+    "directory": "arc"
+  },
+  "bugs": {
+    "url": "https://github.com/Sirius6907/Arceus/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-intelligence",
+    "knowledge-graph",
+    "cursor",
+    "claude",
+    "codex",
+    "ai-agent",
+    "arc",
+    "static-analysis",
+    "codebase-indexing"
+  ],
+  "type": "module",
+  "bin": {
+    "arceus": "dist/cli/index.js",
+    "arc": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "hooks",
+    "scripts",
+    "skills",
+    "vendor",
+    "web"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "serve": "tsx src/cli/index.ts serve",
+    "dev": "tsx watch src/cli/index.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "pretest:integration": "node scripts/build.js",
+    "test:integration": "vitest run test/integration",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "postinstall": "node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs",
+    "prepare": "node scripts/build.js",
+    "prepack": "node scripts/build.js"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.1.0",
+    "@ladybugdb/core": "^0.16.1",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@scarf/scarf": "^1.4.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^14.0.3",
+    "cors": "^2.8.5",
+    "express": "^4.19.2",
+    "express-rate-limit": "^8.4.1",
+    "glob": "^13.0.6",
+    "graphology": "^0.26.0",
+    "graphology-indices": "^0.17.0",
+    "graphology-utils": "^2.3.0",
+    "ignore": "^7.0.5",
+    "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
+    "lru-cache": "^11.0.0",
+    "mnemonist": "^0.40.3",
+    "onnxruntime-node": "^1.24.0",
+    "pandemonium": "^2.4.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-c": "0.21.4",
+    "tree-sitter-c-sharp": "0.23.1",
+    "tree-sitter-cpp": "0.23.2",
+    "tree-sitter-go": "^0.23.0",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-javascript": "^0.23.0",
+    "tree-sitter-php": "^0.23.0",
+    "tree-sitter-python": "0.23.4",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-rust": "0.23.1",
+    "tree-sitter-typescript": "^0.23.2",
+    "uuid": "^14.0.0"
+  },
+  "optionalDependencies": {
+    "node-addon-api": "^8.0.0",
+    "node-gyp-build": "^4.8.0",
+    "tree-sitter-dart": "file:./vendor/tree-sitter-dart",
+    "tree-sitter-kotlin": "^0.3.8",
+    "tree-sitter-proto": "file:./vendor/tree-sitter-proto",
+    "tree-sitter-swift": "file:./vendor/tree-sitter-swift"
+  },
+  "devDependencies": {
+    "@types/cli-progress": "^3.11.6",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.6.0",
+    "@types/uuid": "^11.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "arceus-shared": "file:../arceus-shared",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.5",
+    "vitest": "^4.0.18"
+  },
+  "overrides": {
+    "@huggingface/transformers": {
+      "onnxruntime-node": "$onnxruntime-node"
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/scripts/bench-scope-resolution.ts

@@ -0,0 +1,134 @@
+/**
+ * Synthetic benchmark for scope-resolution. Builds a large in-memory
+ * Python workspace and times runScopeResolution against it directly,
+ * isolating the resolution cost from parse / heritage / pipeline
+ * overhead.
+ *
+ * Usage: REGISTRY_PRIMARY_PYTHON=1 npx tsx scripts/bench-scope-resolution.ts
+ */
+process.env.REGISTRY_PRIMARY_PYTHON = '1';
+
+import { generateId } from '../src/lib/utils.js';
+import { createKnowledgeGraph } from '../src/core/graph/graph.js';
+import { runScopeResolution } from '../src/core/ingestion/scope-resolution/index.js';
+import { pythonScopeResolver } from '../src/core/ingestion/languages/python/scope-resolver.js';
+
+const N_CLASSES = Number(process.env.BENCH_CLASSES ?? '60');
+const N_USERS = Number(process.env.BENCH_USERS ?? '40');
+const ITERS = Number(process.env.BENCH_ITERS ?? '5');
+
+function buildWorkspace(): { path: string; content: string }[] {
+  const files: { path: string; content: string }[] = [];
+
+  // Build N_CLASSES "model" files, each defining a class with a few methods.
+  for (let i = 0; i < N_CLASSES; i++) {
+    const lines: string[] = [];
+    for (let j = 0; j < 5; j++) {
+      lines.push(`class Model${i}_${j}:`);
+      lines.push(`    name: str`);
+      lines.push(`    def save(self) -> bool:`);
+      lines.push(`        return True`);
+      lines.push(`    def update(self, name: str) -> "Model${i}_${j}":`);
+      lines.push(`        self.name = name`);
+      lines.push(`        return self`);
+      lines.push(`    def get_other(self) -> "Model${i}_${(j + 1) % 5}":`);
+      lines.push(`        return Model${i}_${(j + 1) % 5}()`);
+      lines.push('');
+    }
+    files.push({ path: `models/m${i}.py`, content: lines.join('\n') });
+  }
+
+  // Build N_USERS "user" files that import from a few model files
+  // and exercise the receiver-bound dispatcher heavily.
+  for (let u = 0; u < N_USERS; u++) {
+    const targets = [u % N_CLASSES, (u + 1) % N_CLASSES, (u + 2) % N_CLASSES];
+    const imports = targets
+      .map((t) => `from models.m${t} import Model${t}_0, Model${t}_1, Model${t}_2`)
+      .join('\n');
+    const calls: string[] = [];
+    for (let k = 0; k < 30; k++) {
+      const t = targets[k % 3]!;
+      const j = k % 3;
+      calls.push(`    m${k} = Model${t}_${j}()`);
+      calls.push(`    m${k}.save()`);
+      calls.push(`    m${k}.update("x").save()`);
+      calls.push(`    m${k}.get_other().save()`);
+    }
+    const content = `${imports}\n\ndef use_${u}() -> None:\n${calls.join('\n')}\n`;
+    files.push({ path: `app/u${u}.py`, content });
+  }
+
+  return files;
+}
+
+function buildGraph(files: { path: string; content: string }[]) {
+  const graph = createKnowledgeGraph();
+  // Pre-populate File / Class / Function nodes the resolver expects.
+  for (const f of files) {
+    const fileId = generateId('File', f.path);
+    graph.addNode({
+      id: fileId,
+      label: 'File',
+      properties: { name: f.path, filePath: f.path },
+    });
+
+    // Lightweight regex-extract class & def names so the lookup index
+    // has something to find. Real pipeline builds these via parse phase;
+    // for the bench this stand-in is enough to exercise the resolver.
+    const classRe = /^class (\w+)/gm;
+    const defRe = /^\s*def (\w+)/gm;
+    let m: RegExpExecArray | null;
+    while ((m = classRe.exec(f.content)) !== null) {
+      const name = m[1]!;
+      const id = generateId('Class', `${f.path}:${name}`);
+      graph.addNode({
+        id,
+        label: 'Class',
+        properties: { name, filePath: f.path, qualifiedName: name },
+      });
+    }
+    while ((m = defRe.exec(f.content)) !== null) {
+      const name = m[1]!;
+      const id = generateId('Function', `${f.path}:${name}`);
+      graph.addNode({
+        id,
+        label: 'Function',
+        properties: { name, filePath: f.path, qualifiedName: name },
+      });
+    }
+  }
+  return graph;
+}
+
+async function main() {
+  const files = buildWorkspace();
+  console.log(`bench: ${files.length} files (${N_CLASSES} models × 5 classes + ${N_USERS} users)`);
+  console.log(`       × ${ITERS} iterations\n`);
+
+  // Warmup
+  for (let i = 0; i < 2; i++) {
+    const graph = buildGraph(files);
+    runScopeResolution({ graph, files, onWarn: () => {} }, pythonScopeResolver);
+  }
+
+  const samples: number[] = [];
+  for (let i = 0; i < ITERS; i++) {
+    const graph = buildGraph(files);
+    const start = process.hrtime.bigint();
+    runScopeResolution({ graph, files, onWarn: () => {} }, pythonScopeResolver);
+    const end = process.hrtime.bigint();
+    const ms = Number(end - start) / 1_000_000;
+    samples.push(ms);
+    console.log(`  iter ${i + 1}: ${ms.toFixed(0)} ms`);
+  }
+
+  samples.sort((a, b) => a - b);
+  const median = samples[Math.floor(samples.length / 2)]!;
+  const min = samples[0]!;
+  console.log(`\nmin: ${min.toFixed(0)} ms · median: ${median.toFixed(0)} ms`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/build-tree-sitter-dart.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Opt-out: skip the native rebuild entirely. Dart parsing becomes
+// unavailable but `npm install arc` finishes much faster on machines
+// without a C++ toolchain. Strict `=== '1'` only — '=true', '=yes', '=0'
+// (read as a string), and any other value all fall through to the rebuild.
+if (process.env.ARC_SKIP_OPTIONAL_GRAMMARS === '1') {
+  console.warn(
+    '[tree-sitter-dart] Skipping build (ARC_SKIP_OPTIONAL_GRAMMARS=1). Dart parsing will be unavailable until reinstalled without the env var.',
+  );
+  process.exit(0);
+}
+
+const dartDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-dart');
+const bindingGyp = path.join(dartDir, 'binding.gyp');
+const bindingNode = path.join(dartDir, 'build', 'Release', 'tree_sitter_dart_binding.node');
+
+try {
+  if (!fs.existsSync(bindingGyp) || fs.existsSync(bindingNode)) {
+    process.exit(0);
+  }
+
+  try {
+    require.resolve('node-addon-api');
+    require.resolve('node-gyp-build');
+  } catch (resolveErr) {
+    console.warn(
+      '[tree-sitter-dart] Skipping build: hoisted build deps not resolvable (%s).',
+      resolveErr.message,
+    );
+    console.warn(
+      '[tree-sitter-dart] Dart parsing will be unavailable. Install without --no-optional and with scripts enabled to build.',
+    );
+    process.exit(0);
+  }
+
+  console.log('[tree-sitter-dart] Building native binding...');
+  execSync('npx node-gyp rebuild', {
+    cwd: dartDir,
+    stdio: 'pipe',
+    timeout: 180000,
+  });
+  console.log('[tree-sitter-dart] Native binding built successfully');
+} catch (err) {
+  console.warn('[tree-sitter-dart] Could not build native binding:', err.message);
+  console.warn(
+    '[tree-sitter-dart] Dart parsing will be unavailable. Non-Dart functionality is unaffected.',
+  );
+  process.exit(0);
+}

package/scripts/build-tree-sitter-proto.cjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Build tree-sitter-proto native binding.
+ *
+ * Why this script exists:
+ *   tree-sitter-proto is vendored under arc/vendor/tree-sitter-proto/
+ *   and declared as a `file:` optionalDependency. Previously, the vendored
+ *   package had its own `dependencies` and `install` script, which caused
+ *   npm to create `vendor/tree-sitter-proto/node_modules/` and
+ *   `vendor/tree-sitter-proto/build/` during install. Those directories
+ *   blocked `rmdir` on global-install upgrade, producing:
+ *
+ *     ENOTEMPTY: directory not empty, rmdir
+ *       '.../arc/vendor/tree-sitter-proto/node_modules/node-addon-api'
+ *
+ *   (See https://github.com/Sirius6907/Arceus/issues/836.)
+ *
+ *   We stripped `dependencies` and the `install` script from the vendored
+ *   package.json, hoisted `node-addon-api` and `node-gyp-build` into
+ *   arc's own optionalDependencies, and moved native compilation here.
+ *
+ * What this does:
+ *   Runs `npx node-gyp rebuild` inside `node_modules/tree-sitter-proto/`
+ *   (which npm creates as a copy of vendor/tree-sitter-proto/ when
+ *   resolving the file: dep). Build output lands in
+ *   `node_modules/tree-sitter-proto/build/Release/tree_sitter_proto_binding.node`
+ *   — under npm-managed territory, safe on upgrade.
+ *
+ *   Mirrors the tree-sitter-dart build helper. Best-effort: if any
+ *   precondition fails (optional dep absent, no toolchain, --ignore-scripts),
+ *   warn and exit 0 so arc install still succeeds.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Opt-out: skip the native rebuild entirely. Proto parsing becomes
+// unavailable but `npm install arc` finishes much faster on machines
+// without a C++ toolchain. Strict `=== '1'` only — '=true', '=yes', '=0'
+// (read as a string), and any other value all fall through to the rebuild.
+if (process.env.ARC_SKIP_OPTIONAL_GRAMMARS === '1') {
+  console.warn(
+    '[tree-sitter-proto] Skipping build (ARC_SKIP_OPTIONAL_GRAMMARS=1). Proto parsing will be unavailable until reinstalled without the env var.',
+  );
+  process.exit(0);
+}
+
+const protoDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto');
+const bindingGyp = path.join(protoDir, 'binding.gyp');
+const bindingNode = path.join(protoDir, 'build', 'Release', 'tree_sitter_proto_binding.node');
+
+try {
+  if (!fs.existsSync(bindingGyp)) {
+    // tree-sitter-proto is an optionalDependency; absent when install
+    // skipped optional deps or the file: dep was not resolved.
+    process.exit(0);
+  }
+
+  // Skip if the native binding already exists (idempotent re-run).
+  if (fs.existsSync(bindingNode)) {
+    process.exit(0);
+  }
+
+  // Pre-flight: the hoisted build deps must be resolvable.
+  try {
+    require.resolve('node-addon-api');
+    require.resolve('node-gyp-build');
+  } catch (resolveErr) {
+    console.warn(
+      '[tree-sitter-proto] Skipping build: hoisted build deps not resolvable (%s).',
+      resolveErr.message,
+    );
+    console.warn(
+      '[tree-sitter-proto] Proto parsing will be unavailable. Install without --no-optional and with scripts enabled to build.',
+    );
+    process.exit(0);
+  }
+
+  console.log('[tree-sitter-proto] Building native binding...');
+  execSync('npx node-gyp rebuild', {
+    cwd: protoDir,
+    stdio: 'pipe',
+    timeout: 180000,
+  });
+  console.log('[tree-sitter-proto] Native binding built successfully');
+} catch (err) {
+  console.warn('[tree-sitter-proto] Could not build native binding:', err.message);
+  console.warn(
+    '[tree-sitter-proto] Proto (.proto) parsing will be unavailable. Non-proto arc functionality is unaffected.',
+  );
+  // Exit 0: optionalDependency failures must not fail the arc install.
+  process.exit(0);
+}

package/scripts/build.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Build script that compiles arc and inlines arceus-shared into the dist.
+ *
+ * Steps:
+ *  1. Build arceus-shared (tsc)
+ *  2. Build arc (tsc)
+ *  3. Copy arceus-shared/dist → dist/_shared
+ *  4. Rewrite bare 'arceus-shared' specifiers → relative paths
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const SHARED_ROOT = path.resolve(ROOT, '..', 'arceus-shared');
+const DIST = path.join(ROOT, 'dist');
+const SHARED_DEST = path.join(DIST, '_shared');
+
+// ── 1. Build arceus-shared ───────────────────────────────────────
+console.log('[build] compiling arceus-shared…');
+const tscCmd = path.resolve(
+  ROOT,
+  'node_modules',
+  '.bin',
+  process.platform === 'win32' ? 'tsc.cmd' : 'tsc'
+);
+execSync(tscCmd, { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 });
+
+// ── 2. Build arc ──────────────────────────────────────────────
+console.log('[build] compiling arc…');
+execSync(tscCmd, { cwd: ROOT, stdio: 'inherit', timeout: 120_000 });
+
+// ── 3. Copy shared dist ────────────────────────────────────────────
+console.log('[build] copying shared module into dist/_shared…');
+fs.cpSync(path.join(SHARED_ROOT, 'dist'), SHARED_DEST, { recursive: true });
+
+// ── 4. Rewrite imports ─────────────────────────────────────────────
+console.log('[build] rewriting arceus-shared imports…');
+let rewritten = 0;
+
+function rewriteFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  if (!content.includes('arceus-shared')) return;
+
+  const relDir = path.relative(path.dirname(filePath), SHARED_DEST);
+  // Always use posix separators and point to the package index
+  const relImport = relDir.split(path.sep).join('/') + '/index.js';
+
+  const updated = content
+    .replace(/from\s+['"]arceus-shared['"]/g, `from '${relImport}'`)
+    .replace(/import\(\s*['"]arceus-shared['"]\s*\)/g, `import('${relImport}')`);
+
+  if (updated !== content) {
+    fs.writeFileSync(filePath, updated);
+    rewritten++;
+  }
+}
+
+function walk(dir, extensions, cb) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, extensions, cb);
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      cb(full);
+    }
+  }
+}
+
+walk(DIST, ['.js', '.d.ts'], rewriteFile);
+
+// ── 5. Make CLI entry executable ────────────────────────────────────
+const cliEntry = path.join(DIST, 'cli', 'index.js');
+if (fs.existsSync(cliEntry)) fs.chmodSync(cliEntry, 0o755);
+
+// ── 6. Build & copy web UI ──────────────────────────────────────────
+const WEB_ROOT = path.resolve(ROOT, '..', 'arceus-web');
+const WEB_DEST = path.join(DIST, '..', 'web');
+
+if (fs.existsSync(path.join(WEB_ROOT, 'package.json'))) {
+  console.log('[build] building arceus-web…');
+  if (!fs.existsSync(path.join(WEB_ROOT, 'node_modules'))) {
+    console.log('[build] installing arceus-web dependencies…');
+    execSync('npm ci', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+  }
+  execSync('npm run build', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+
+  // Copy dist → arc/web/ (shipped in the npm package)
+  fs.rmSync(WEB_DEST, { recursive: true, force: true });
+  fs.cpSync(path.join(WEB_ROOT, 'dist'), WEB_DEST, { recursive: true });
+  console.log('[build] copied web UI → arc/web/');
+} else {
+  console.log('[build] skipping web UI (arceus-web not found)');
+}
+
+console.log(`[build] done — rewrote ${rewritten} files.`);

package/scripts/ci-list-migrated-languages.ts

@@ -0,0 +1,24 @@
+/**
+ * CI helper — emits the `MIGRATED_LANGUAGES` set as a JSON matrix array for
+ * GitHub Actions (`.github/workflows/ci-scope-parity.yml`).
+ *
+ * Consumed by the `discover` job in that workflow. Each entry has:
+ *   - `slug`: lowercase language id, matching `test/integration/resolvers/<slug>.test.ts`.
+ *   - `envvar`: uppercase suffix used to build the `REGISTRY_PRIMARY_<envvar>` toggle.
+ *
+ * Run with `npx tsx scripts/ci-list-migrated-languages.ts`. The script
+ * writes a single JSON array to stdout (no wrapper object) so the
+ * workflow can pipe it straight into `$GITHUB_OUTPUT`.
+ */
+
+import { MIGRATED_LANGUAGES } from '../src/core/ingestion/registry-primary-flag.js';
+
+const entries = [...MIGRATED_LANGUAGES].map((slug) => {
+  const s = String(slug);
+  return {
+    slug: s,
+    envvar: s.toUpperCase().replace(/-/g, '_'),
+  };
+});
+
+process.stdout.write(JSON.stringify(entries));

package/scripts/install-duckdb-extension.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function parseLbugMaxDbSize(raw) {
+  const parsed = raw ? Number(raw) : NaN;
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid LadybugDB max DB size for extension installer: ${raw ?? '<missing>'}`);
+  }
+  return Math.floor(parsed);
+}
+
+async function installDuckDbExtension(extensionName) {
+  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
+    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
+  }
+
+  const require = createRequire(import.meta.url);
+  const lbugModule = require('@ladybugdb/core');
+  const lbug = lbugModule.default ?? lbugModule;
+  const lbugMaxDbSize = parseLbugMaxDbSize(
+    process.argv[3] ?? process.env.ARC_LBUG_MAX_DB_SIZE,
+  );
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'arc-ext-install-'));
+  const dbPath = path.join(tmpDir, 'install.lbug');
+  let db;
+  let conn;
+
+  try {
+    db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
+    conn = new lbug.Connection(db);
+    await conn.query(`INSTALL ${extensionName}`);
+  } finally {
+    if (conn) await conn.close().catch(() => {});
+    if (db) await db.close().catch(() => {});
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+installDuckDbExtension(process.argv[2] ?? process.env.ARC_LBUG_EXTENSION_NAME).catch((err) => {
+  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+  process.exitCode = 1;
+});

package/skills/arc-cli.md

@@ -0,0 +1,83 @@
+---
+name: arc-cli
+description: "Use when the user needs to run Arceus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# Arceus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx arc analyze
+```
+
+Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.arc/`, and generates CLAUDE.md / AGENTS.md context files.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
+
+**When to run:** First time in a project, after major code changes, or when `arc://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
+
+### status — Check index freshness
+
+```bash
+npx arc status
+```
+
+Shows whether the current repo has a Arceus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
+
+### clean — Delete the index
+
+```bash
+npx arc clean
+```
+
+Deletes the `.arc/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing Arceus from a project.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx arc wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.arc/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx arc list
+```
+
+Lists all repositories registered in `~/.arc/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `arc://repo/{name}/context`** to verify the index loaded
+2. Use the other Arceus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding