arceus-s 1.6.6 → 1.6.7

package/README.md

@@ -1,92 +1,67 @@
-# Arceus
+# Arceus Core CLI: `arceus-s`
 
-**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
-
-Works with **Cursor**, **Claude Code**, **Codex**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+This is the core compiler-aware static analyzer and Model Context Protocol (MCP) server daemon for Arceus. It parses raw codebase trees into a queryable semantic graph database (built on LadybugDB) to empower AI engineering agents with high-fidelity system-level reasoning.
 
 [![npm version](https://img.shields.io/npm/v/arceus-s.svg)](https://www.npmjs.com/package/arceus-s)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
 
 ---
 
-## Why?
+## Why Use Arceus?
 
-AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. Arceus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
+Standard AI code generation assistants are constrained by linear text analysis. They write, edit, and refactor lines of code without a compiler's understanding of structural side effects and calling dependencies. 
 
-**Three commands to give your AI agent full codebase awareness.**
+Arceus resolves imports, cross-file call targets, variable types, class interfaces, and modular clusters, representing the entire relational map inside an embedded local database. AI agents can then query this database, minimizing context pollution and preventing broken implementation chains.
 
-## Installation & Naming
+---
 
-Because the command name `arc` is extremely common and already registered by an unrelated package on the public npm registry, **Arceus CLI is published under the package name `arceus-s`**.
+## Installation & Command Ingestion
 
-When installed globally, npm maps the CLI binary to both `arc` and `arceus`, letting you use the tool natively:
+Because the command name `arc` is already registered by an unrelated project in the public registry, Arceus is distributed under the name **`arceus-s`**. Npm automatically routes global binary path calls to both `arc` and `arceus`.
 
 ```bash
-# Install globally from npm
+# Global install from registry
 npm install -g arceus-s
 
-# Run commands globally
-arc analyze
-# or: arceus analyze
+# Verify CLI commands
+arc --help
 ```
 
-## Quick Start
-
-If you prefer to run it without a global installation:
-
+### Ingesting Your First Repository
+Run the indexer from your project's root folder:
 ```bash
-# Index your repo (run from repo root)
+# Run one-off without global install
 npx arceus-s analyze
-```
-
-That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
-To configure MCP for your editor, run `arc setup` once (or use `npx arceus-s setup` if not installed globally).
-
-`arc setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
-
-### Editor Support
-
-| Editor | MCP | Skills | Hooks (auto-augment) | Support |
-|--------|-----|--------|---------------------|---------|
-| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
-| **Cursor** | Yes | Yes | Yes (postToolUse, [manual install](../arceus-cursor-integration/README.md#hook-install)) | **Full** |
-| **Codex** | Yes | Yes | — | MCP + Skills |
-| **Windsurf** | Yes | — | — | MCP |
-| **OpenCode** | Yes | Yes | — | MCP + Skills |
-
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
+# Or run via global installer
+arc analyze
+```
+This command maps the directory, persists the graph database inside `.arc/`, registers the repository in your global directory, and generates `AGENTS.md` and `CLAUDE.md` context files.
 
-### Community Integrations
+---
 
-| Agent | Install | Source |
-|-------|---------|--------|
-| [pi](https://pi.dev) | `pi install npm:pi-arc` | [pi-arc](https://github.com/tintinweb/pi-arc) |
+## Editor & MCP Server Integration
 
-## MCP Setup (manual)
+To automatically write the connection parameters for your active editors, run:
+```bash
+arc setup
+```
 
-If you prefer to configure manually instead of using `arc setup`:
+### Manual Configuration Schemes
 
-### Claude Code (full support — MCP + skills + hooks)
+If your editor requires manual server setup:
 
+#### 1. Claude Code
 ```bash
-# macOS / Linux
-claude mcp add arceus -- npx -y arceus-s mcp
-
-# Windows
+# Windows systems
 claude mcp add arceus -- cmd /c npx -y arceus-s mcp
-```
-
-### Codex (full support — MCP + skills)
 
-```bash
-codex mcp add arceus -- npx -y arceus-s mcp
+# Unix / macOS systems
+claude mcp add arceus -- npx -y arceus-s mcp
 ```
 
-### Cursor / Windsurf
-
-Add to `~/.cursor/mcp.json` (global — works for all projects):
-
+#### 2. Cursor
+Add this entry to your system's global config (`~/.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
@@ -98,10 +73,8 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
 }
 ```
 
-### OpenCode
-
-Add to `~/.config/opencode/config.json`:
-
+#### 3. OpenCode
+Append this config to `~/.config/opencode/config.json`:
 ```json
 {
   "mcp": {
@@ -113,144 +86,44 @@ Add to `~/.config/opencode/config.json`:
 }
 ```
 
-## How It Works
-
-Arceus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:
-
-1. **Structure** — Walks the file tree and maps folder/file relationships
-2. **Parsing** — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
-3. **Resolution** — Resolves imports and function calls across files with language-aware logic
-   - **Field & Property Type Resolution** — Tracks field types across classes and interfaces for deep chain resolution (e.g., `user.address.city.getName()`)
-   - **Return-Type-Aware Variable Binding** — Infers variable types from function return types, enabling accurate call-result binding
-4. **Clustering** — Groups related symbols into functional communities
-5. **Processes** — Traces execution flows from entry points through call chains
-6. **Search** — Builds hybrid search indexes for fast retrieval
-
-The result is a **LadybugDB graph database** stored locally in `.arc/` with full-text search and semantic embeddings.
-
-## MCP Tools
-
-Your AI agent gets these tools automatically:
-
-| Tool | What It Does | `repo` Param |
-|------|-------------|--------------|
-| `list_repos` | Discover all indexed repositories | — |
-| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional |
-| `context` | 360-degree symbol view — categorized refs, process participation | Optional |
-| `impact` | Blast radius analysis with depth grouping and confidence | Optional |
-| `detect_changes` | Git-diff impact — maps changed lines to affected processes | Optional |
-| `rename` | Multi-file coordinated rename with graph + text search | Optional |
-| `cypher` | Raw Cypher graph queries | Optional |
-
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
-
-## MCP Resources
-
-| Resource | Purpose |
-|----------|---------|
-| `arc://repos` | List all indexed repositories (read first) |
-| `arc://repo/{name}/context` | Codebase stats, staleness check, and available tools |
-| `arc://repo/{name}/clusters` | All functional clusters with cohesion scores |
-| `arc://repo/{name}/cluster/{name}` | Cluster members and details |
-| `arc://repo/{name}/processes` | All execution flows |
-| `arc://repo/{name}/process/{name}` | Full process trace with steps |
-| `arc://repo/{name}/schema` | Graph schema for Cypher queries |
-
-## MCP Prompts
-
-| Prompt | What It Does |
-|--------|-------------|
-| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level |
-| `generate_map` | Architecture documentation from the knowledge graph with mermaid diagrams |
-
-## CLI Commands
-
-```bash
-arc setup                   # Configure MCP for your editors (one-time)
-arc analyze [path]          # Index a repository (or update stale index)
-arc analyze --force         # Force full re-index
-arc analyze --embeddings    # Enable embedding generation (slower, better search)
-arc analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md arc section edits
-arc analyze --verbose       # Log skipped files when parsers are unavailable
-arc analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
-arc analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
-arc mcp                     # Start MCP server (stdio) — serves all indexed repos
-arc serve                   # Start local HTTP server (multi-repo) for web UI
-arc index                   # Register an existing .arc/ folder into the global registry
-arc list                    # List all indexed repositories
-arc status                  # Show index status for current repo
-arc clean                   # Delete index for current repo
-arc clean --all --force     # Delete all indexes
-arc wiki [path]             # Generate LLM-powered docs from knowledge graph
-arc wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
-
-# Repository groups (multi-repo / monorepo service tracking)
-arc group create <name>                                   # Create a repository group
-arc group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `arc list`)
-arc group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
-arc group list [name]                                     # List groups, or show one group's config
-arc group sync <name>                                     # Extract contracts and match across repos/services
-arc group contracts <name>  # Inspect extracted contracts and cross-links
-arc group query <name> <q>  # Search execution flows across all repos in a group
-arc group status <name>     # Check staleness of repos in a group
-```
-
-## Remote Embeddings
+---
 
-Set these env vars to use a remote OpenAI-compatible `/v1/embeddings` endpoint instead of the local model:
+## CLI Command Interface
 
 ```bash
-export ARC_EMBEDDING_URL=http://your-server:8080/v1
-export ARC_EMBEDDING_MODEL=BAAI/bge-large-en-v1.5
-export ARC_EMBEDDING_DIMS=1024          # optional, default 384
-export ARC_EMBEDDING_API_KEY=your-key   # optional, default: "unused"
-arc analyze . --embeddings
-```
-
-Works with Infinity, vLLM, TEI, llama.cpp, Ollama, LM Studio, or OpenAI. When unset, local embeddings are used unchanged.
-
-## Multi-Repo Support
-
-Arceus supports indexing multiple repositories. Each `arc analyze` registers the repo in a global registry (`~/.arc/registry.json`). The MCP server serves all indexed repos automatically.
-
-## Supported Languages
-
-TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby
-
-### Language Feature Matrix
-
-| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
-|----------|---------|----------------|---------|----------|-----------------|---------------------|--------|------------|-------------|
-| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
-| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
-| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ |
-| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-
-**Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics
-
-## Agent Skills
-
-Arceus ships with skill files that teach AI agents how to use the tools effectively:
-
-- **Exploring** — Navigate unfamiliar code using the knowledge graph
-- **Debugging** — Trace bugs through call chains
-- **Impact Analysis** — Analyze blast radius before changes
-- **Refactoring** — Plan safe refactors using dependency mapping
-
-Installed automatically by both `arc analyze` (per-repo) and `arc setup` (global).
+arc setup                     # Writes MCP configurations for active editors
+arc analyze [path]            # Parses source code and updates repository index
+arc analyze --force           # Discards graph caches and runs a full re-index
+arc analyze --skills          # Generates specialized AI agent guidelines
+arc analyze --skip-embeddings # Fast parse mode; skips calculating vector embeddings
+arc analyze --skip-git        # Indexes folder even if not initialized as a git repo
+arc analyze --embeddings      # Generates full semantic vector embeddings (slower)
+arc analyze --verbose         # Outputs file skips and parser debug logs
+arc analyze --worker-timeout N# Sets custom parse timeout in seconds
+arc mcp                       # Runs the Model Context Protocol daemon (stdio)
+arc serve                     # Launches HTTP server for browser Web UI connection
+arc list                      # Prints all registered repositories on this machine
+arc status                    # Shows index health, size, and statistics
+arc clean                     # Deletes database files for the current project
+arc clean --all --force       # Wipes all repository graphs from disk
+arc wiki [path]               # Formulates a markdown wiki from the codebase graph
+arc wiki --model <name>       # Custom LLM model target (defaults: gpt-4o-mini)
+arc wiki --base-url <url>     # Custom LLM provider endpoint URL
+```
+
+### Multi-Service Sync & Monorepos
+*   `arc group create <name>`: Mappings a new microservice group structure.
+*   `arc group add <group> <path> <name>`: Registers a codebase in a sync group.
+*   `arc group remove <group> <path>`: Deletes a codebase from a sync group.
+*   `arc group list [name]`: Outputs active group schemas.
+*   `arc group sync <name>`: Resolves boundaries and maps contract exchanges.
+*   `arc group contracts <name>`: Reviews service endpoints and interface dependencies.
+*   `arc group query <name> <q>`: Executes search routines across all service libraries in a group.
+*   `arc group status <name>`: Reports health and stale statuses for grouped codebases.
 
 ---
 
-## Context Efficiency & Token Optimization (Benchmark)
+## Token Efficiency & Graph RAG Performance
 
 Arceus's semantic graph model drastically reduces token wastage and context pollution for downstream LLMs compared to traditional lexical exploration (e.g., recursive grep and file reading).
 
@@ -262,156 +135,69 @@ Arceus's semantic graph model drastically reduces token wastage and context poll
 | **2. API Route Mapping** <br> Discover all registered endpoints and handler files. | **~20,162 tokens** <br>(Requires reading multiple route-registration files, middleware modules, and unit test suites). | **~65 tokens** <br>(Cypher execution: fetches all `Route` nodes containing route paths and source locations). | **310x Reduction** <br>(99.68% Saved) | **Interface Discovery**: Obtains complete routing topography without feeding entire source files to the LLM. |
 | **3. Monorepo Class Indexing** <br> Index all classes and paths in the workspace. | **~87,500 tokens** <br>(Requires reading over 20 files containing class structures to capture inheritance and signatures). | **~1,250 tokens** <br>(Cypher execution: returns a complete node list of all `Class` names and file paths). | **70x Reduction** <br>(98.57% Saved) | **Architecture Mapping**: Instant monorepo-wide indexing with minimal network and computational overhead. |
 
-### Architectural Advantages
-
-1. **Deterministic Precision (Zero Noise)**: Lexical tools like grep require models to ingest noise (boilerplates, imports, formatting, unrelated logic) to resolve relationships. Arceus returns only the exact requested graph nodes and edges.
-2. **Multi-Hop Traversal**: Tracing transitive chains (e.g., `Class A extends Class B implements Interface C`) normally requires iterative lexical searches. A single Cypher query (e.g., `MATCH (a:Class)-[:EXTENDS]->(b)-[:IMPLEMENTS]->(c) RETURN a, c`) evaluates this instantly on the graph.
-3. **Optimized Concurrency**: Read-only graph locking ensures concurrent MCP context retrieval does not block editor processes, runtime tasks, or local file systems.
-
 ---
 
-## Requirements
-
-- Node.js >= 18
-- Git repository (uses git for commit tracking)
-
-## Release candidates
+## Language Support Matrix
 
-Stable releases publish to the default `latest` dist-tag. When a pull request
-with non-documentation changes merges into `main`, an automated workflow also
-publishes a prerelease build under the `rc` dist-tag, so early adopters can
-try in-flight fixes without waiting for the next stable cut. (Docs-only
-merges are skipped.)
-
-```bash
-# Try the latest release candidate (pre-stable — may change at any time)
-npm install -g arceus-s@rc
-# — or —
-npx arceus-s@rc analyze
-```
-
-Release-candidate versions follow the standard semver prerelease format
-`X.Y.Z-rc.N`, where `X.Y.Z` is the next stable target (bumped from the
-current `latest` by patch by default; `minor` or `major` when kicking off a
-bigger cycle) and `N` increments per published rc. Example sequence:
-`1.6.2-rc.1`, `1.6.2-rc.2`, …, then once `1.6.2` ships stable,
-`1.6.3-rc.1`. See the [Releases page](https://github.com/Sirius6907/Arceus/releases)
-for the full list; stable `latest` is unaffected.
-
-## Troubleshooting
-
-### `Cannot destructure property 'package' of 'node.target' as it is null`
-
-This crash was caused by a dependency URL format that is incompatible with
-certain npm/arborist versions ([npm/cli#8126](https://github.com/npm/cli/issues/8126)).
-It is fixed in **arc v1.6.2+**. Upgrade to the latest version:
-
-```bash
-npx arceus-s analyze          # always uses the newest release
-# — or —
-npm install -g arceus-s       # upgrade a global install
-```
-
-If you still hit npm install issues after upgrading, these generic workarounds
-may help:
-
-```bash
-npm install -g npm@latest            # update npm itself
-npm cache clean --force              # clear a possibly corrupt cache
-```
-
-### Installation fails with native module errors
-
-Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, Arceus still works — those languages will be skipped.
-
-If `npm install -g arceus-s` fails on native modules:
-
-```bash
-# Ensure build tools are available (Linux/macOS)
-# Ubuntu/Debian: sudo apt install python3 make g++
-# macOS: xcode-select --install
-
-# Retry installation
-npm install -g arceus-s
-```
-
-### Analyze warns about unavailable FTS or VECTOR extensions
-
-Arceus uses optional DuckDB extensions for BM25 and vector search. The `arc serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
-
-Configure the behavior with two environment variables:
-
-| Variable | Values | Default | Effect |
-|----------|--------|---------|--------|
-| `ARC_LBUG_EXTENSION_INSTALL` | `auto`, `load-only`, `never` | `auto` | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely. |
-| `ARC_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer | `15000` | Wall-clock budget for the out-of-process `INSTALL` child before it is killed. |
-
-```bash
-# Offline/airgapped: never reach the network for extensions
-ARC_LBUG_EXTENSION_INSTALL=load-only npx arceus-s analyze
-
-# Slow network: give extension downloads more time
-ARC_LBUG_EXTENSION_INSTALL_TIMEOUT_MS=30000 npx arceus-s analyze
-```
-
-### Analysis runs out of memory
-
-For very large repositories:
-
-```bash
-# Increase Node.js heap size
-NODE_OPTIONS="--max-old-space-size=16384" npx arceus-s analyze
-
-# Exclude large directories
-echo "vendor/" >> .arcignore
-echo "dist/" >> .arcignore
-```
-
-### Large files are being skipped
-
-By default the walker skips files larger than **512 KB** (see log line `Skipped N large files (>512KB)`). Raise the threshold via either the CLI flag or the environment variable — both accept a value in **KB**:
-
-```bash
-# CLI flag (takes precedence over the env var)
-npx arceus-s analyze --max-file-size 2048     # skip only files > 2 MB
-
-# Environment variable (persists across commands)
-export ARC_MAX_FILE_SIZE=2048
-npx arceus-s analyze
-```
-
-Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, `analyze` prints the effective threshold in its startup banner (e.g. `ARC_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)`).
-
-### Analyze reports a worker timeout
+| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| **TypeScript** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **JavaScript** | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
+| **Python** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Java** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| **Kotlin** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| **C#** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Go** | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Rust** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| **PHP** | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Ruby** | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
+| **Swift** | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **C** | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ |
+| **C++** | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| **Dart** | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
 
-Worker parse timeouts are recoverable. Arceus retries stalled worker jobs with backoff, splits large jobs to isolate slow files, and falls back to the sequential parser when needed. If a large repository needs more time per worker job, use either:
+---
 
+## Troubleshooting Guide
+
+### 1. Arborist Conflict: `Cannot destructure property 'package'`
+This error occurs in older npm environments due to unresolved symbolic references. 
+*   **Remedy**: Update your CLI package to version `v1.6.2+`:
+    ```bash
+    npm install -g arceus-s@latest
+    npm cache clean --force
+    ```
+
+### 2. Grammar Compilation Failures
+Advanced syntax structures (Dart, Kotlin, Swift) require local C++ compilers. If compilation fails, Arceus bypasses these optional parsers and functions normally for other languages.
+*   **Remedy (macOS/Linux)**: Install development essentials:
+    ```bash
+    # Debian/Ubuntu
+    sudo apt install python3 make g++
+    # macOS
+    xcode-select --install
+    ```
+
+### 3. DuckDB Vector Extension Load Warns
+Arceus queries leverage local analytical extensions. During `analyze`, it attempts to auto-download them. If offline or in an air-gapped environment, you can set the install behavior:
+
+| Environment Variable | Supported Options | Description |
+| :--- | :--- | :--- |
+| `ARC_LBUG_EXTENSION_INSTALL` | `auto`, `load-only`, `never` | `auto` downloads on demand. `load-only` prevents network queries. `never` disables vector extensions. |
+| `ARC_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | Integer value | Download process budget in milliseconds (defaults to `15000`). |
+
+### 4. Memory Heap Exceeded on Large Codebases
+If the process runs out of memory, increase Node's heap size:
 ```bash
-# CLI flag, in seconds
-npx arceus-s analyze --worker-timeout 60
-
-# Environment variable, in milliseconds
-export ARC_WORKER_SUB_BATCH_TIMEOUT_MS=60000
-npx arceus-s analyze
+NODE_OPTIONS="--max-old-space-size=16384" arc analyze
 ```
 
-For repositories with very large source files, `ARC_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. The default is **8388608 bytes (8 MB)**.
-
-## Privacy
-
-- All processing happens locally on your machine
-- No code is sent to any server
-- Index stored in `.arc/` inside your repo (gitignored)
-- Global registry at `~/.arc/` stores only paths and metadata
-
-## Web UI
-
-Arceus also has a browser-based UI at [arceus-arc.vercel.app](https://arceus-arc.vercel.app) — 100% client-side, your code never leaves the browser.
-
-**Local Backend Mode:** Run `arc serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
+---
 
 ## License
 
+Copyright (c) 2026 Chandan Kumar Behera
+
 [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
 
 Free for non-commercial use. Contact for commercial licensing.

package/dist/_shared/integrations/understand-quickly.js

@@ -26,7 +26,7 @@ export const UNDERSTAND_QUICKLY_DISPATCH_URL = [
     'repos',
     'looptech-ai',
     'understand-quickly',
-    'dispatches'
+    'dispatches',
 ].join('/');
 /**
  * Event type the registry's sync workflow listens for.

package/dist/cli/analyze.js

@@ -271,9 +271,7 @@ export const analyzeCommand = async (inputPath, options) => {
     // overwrite the bar mid-render. We capture originals, swap to barLog for
     // the lifetime of the run, and restore on completion/error/SIGINT.
     const origLog = console.log.bind(console);
-    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     const origWarn = console.warn.bind(console);
-    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     const origError = console.error.bind(console);
     let barCurrentValue = 0;
     const barLog = (...args) => {
@@ -282,9 +280,7 @@ export const analyzeCommand = async (inputPath, options) => {
         bar.update(barCurrentValue);
     };
     console.log = barLog;
-    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     console.warn = barLog;
-    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     console.error = barLog;
     // Track elapsed time per phase
     let lastPhaseLabel = 'Initializing...';
@@ -344,9 +340,7 @@ export const analyzeCommand = async (inputPath, options) => {
             clearInterval(elapsedTimer);
             process.removeListener('SIGINT', sigintHandler);
             console.log = origLog;
-            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
             console.warn = origWarn;
-            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
             console.error = origError;
             bar.stop();
             console.log('  Already up to date\n');
@@ -404,9 +398,7 @@ export const analyzeCommand = async (inputPath, options) => {
         clearInterval(elapsedTimer);
         process.removeListener('SIGINT', sigintHandler);
         console.log = origLog;
-        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.warn = origWarn;
-        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.error = origError;
         bar.update(100, { phase: 'Done' });
         bar.stop();
@@ -427,9 +419,7 @@ export const analyzeCommand = async (inputPath, options) => {
         clearInterval(elapsedTimer);
         process.removeListener('SIGINT', sigintHandler);
         console.log = origLog;
-        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.warn = origWarn;
-        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.error = origError;
         bar.stop();
         const msg = err.message || String(err);

package/dist/core/embeddings/config.js

@@ -29,8 +29,6 @@ export const resolveEmbeddingConfig = (overrides = {}) => {
         batchSize: parsePositiveInt('ARC_EMBEDDING_BATCH_SIZE', env.ARC_EMBEDDING_BATCH_SIZE, overrides.batchSize ?? DEFAULT_EMBEDDING_CONFIG.batchSize),
         subBatchSize: parsePositiveInt('ARC_EMBEDDING_SUB_BATCH_SIZE', env.ARC_EMBEDDING_SUB_BATCH_SIZE, overrides.subBatchSize ?? DEFAULT_EMBEDDING_CONFIG.subBatchSize),
         threads: parsePositiveInt('ARC_EMBEDDING_THREADS', env.ARC_EMBEDDING_THREADS, overrides.threads ?? defaultEmbeddingThreads()),
-        device: parseDevice(env.ARC_EMBEDDING_DEVICE) ??
-            overrides.device ??
-            DEFAULT_EMBEDDING_CONFIG.device,
+        device: parseDevice(env.ARC_EMBEDDING_DEVICE) ?? overrides.device ?? DEFAULT_EMBEDDING_CONFIG.device,
     };
 };

package/dist/core/lbug/lbug-config.js

@@ -229,11 +229,30 @@ export async function openLbugConnection(lbugModule, databasePath, options = {})
     let db;
     try {
         db = await openWithLockRetry(() => createLbugDatabase(lbugModule, databasePath, options), databasePath);
+        await db.init();
         return { db, conn: new lbugModule.Connection(db) };
     }
     catch (err) {
         if (db)
             await db.close().catch(() => { });
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('replay shadow pages')) {
+            try {
+                // Open in read-write mode briefly to replay shadow pages and auto-checkpoint the WAL
+                const tempDb = await openWithLockRetry(() => createLbugDatabase(lbugModule, databasePath, { ...options, readOnly: false }), databasePath);
+                await tempDb.init();
+                await tempDb.close().catch(() => { });
+                // Re-try opening in read-only mode
+                db = await openWithLockRetry(() => createLbugDatabase(lbugModule, databasePath, options), databasePath);
+                await db.init();
+                return { db, conn: new lbugModule.Connection(db) };
+            }
+            catch (retryErr) {
+                if (db)
+                    await db.close().catch(() => { });
+                throw retryErr;
+            }
+        }
         throw err;
     }
 }