Shashankss1205 · Oct 15, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/.cursor/skills/codegraphcontext/SKILL.md b/.cursor/skills/codegraphcontext/SKILL.md
@@ -36,5 +36,4 @@ description: >-
 
 - CLI entry: `codegraphcontext.cli.main`
 - MCP server and tool wiring: `codegraphcontext.server`, `tool_definitions.py`
-- User-facing setup detail: `docs/docs/setup_workflows.md`, `docs/docs/guides/mcp_guide.md`
-- Published copy of this skill (for docs / GitHub): `docs/docs/agent_skill_codegraphcontext.md`
+- User-facing setup detail: `docs/docs/getting-started/installation.md`, `docs/docs/getting-started/mcp-setup.md`
diff --git a/.env.example b/.env.example
@@ -27,6 +27,11 @@ PYTHONDONTWRITEBYTECODE=1
 # ATLASCLOUD_API_BASE=https://api.atlascloud.ai/v1
 # ATLASCLOUD_MODEL=deepseek-ai/deepseek-v4-pro
 
+# Optional: Cheaper Inference for natural-language graph queries (OpenAI-compatible)
+# CHEAPER_INFERENCE_API_KEY=CHANGE_ME
+# CHEAPER_INFERENCE_API_BASE=https://api.cheaperinference.com/v1
+# CHEAPER_INFERENCE_MODEL=gpt-5.4-mini
+
 # Remote FalkorDB (set DEFAULT_DATABASE=falkordb-remote or set FALKORDB_HOST)
 # FALKORDB_HOST=127.0.0.1
 # FALKORDB_PORT=6379

diff --git a/README.md b/README.md
@@ -218,9 +218,14 @@ CodeGraphContext provides comprehensive parsing and analysis for the following l
 | 🌙 | **Lua** | 🚀 | **Scala** | λ | **Haskell** |
 | 💧 | **Elixir** | 📜 | **Emacs Lisp (elisp)** | 🌐 | **HTML** |
 | 🎨 | **CSS** | ⚛️ | **TSX** | ⛓️ | **Solidity** |
+| 🏗️ | **HCL (Terraform/Terragrunt)** | | | | |
 
 Each language parser extracts functions, classes, methods, parameters, inheritance relationships, function calls, and imports to build a comprehensive code graph.
 
+**HCL notes:** `.tf`, `.tfvars` and `.hcl` cover Terraform, OpenTofu and Terragrunt. HCL declares
+rather than calls, so it contributes blocks, variables and cross-configuration imports but no
+function calls. See `docs/docs/contributing_languages.md` § HCL.
+
 **Solidity notes:** `.sol` uses Tree-sitter via `tree-sitter-language-pack` (no SCIP). Supports Foundry remappings, modifier invocations, `using Lib for T`, and `emit` / custom-error `revert` as CALLS. See `docs/docs/contributing_languages.md` § Solidity.
 
 **Kotlin notes:** Annotations are recorded on functions and classes as `decorators`, retaining

diff --git a/docs/MCP_TOOLS.md b/docs/MCP_TOOLS.md
@@ -202,13 +202,20 @@ List background jobs (indexing, scans, etc.).
 - **Args:** None
 - **Returns:** Job list with status
 
+Failed jobs also include `error_type` and `traceback` diagnostics. The existing
+`errors` list retains its concise messages. Tracebacks are limited to 32,768
+characters; oversized values begin with a truncation marker.
+
 ### `check_job_status`
 
 Poll a single job.
 
 - **Args:** `job_id` (string)
 - **Returns:** Status and progress
 
+Failed jobs expose the same `error_type` and bounded `traceback` fields as
+`list_jobs`, so clients can inspect the cause without access to server logs.
+
 ---
 
 ## Advanced querying

diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -105,6 +105,16 @@ Open an issue with: your `cgc --version`, the backend line from startup, the
 exact command, and the full output. The Discord invite in the README is the
 fastest route for questions that aren't bugs.
 
+### Failed background indexing jobs
+
+`check_job_status` and `list_jobs` include additive `error_type` and `traceback`
+fields for indexing exceptions. The existing `errors[0]` message is preserved.
+Tracebacks are capped at 32,768 characters; oversized values start with a
+truncation marker and retain the final frames. Jobs presumed stalled have no
+exception traceback. These diagnostics are held in memory and disappear after
+job cleanup or a server restart. Review tracebacks before sharing them: exception
+messages and source lines may contain repository information.
+
 ### Parser initialization failures
 
 Failure to initialize a supported source parser is an indexing error, rather
@@ -113,3 +123,29 @@ with the original grammar or cache error included. A per-file initialization
 failure contributes to failed_files and the job's error list. Dependency
 loading no longer downloads Python's grammar when another language is requested.
 Check the grammar cache ownership and network access before reinstalling packages.
+
+### Gateway health stalls during indexing
+
+Indexing runs discovery, parser initialization, import pre-scans, graph writes
+and resolution in workers so the serving event loop can answer `/health` and
+job-status requests. SCIP's blocking CLI and augmentation phases also run in a
+worker. Writes remain sequential within each indexing job.
+
+On a cold cache, language-pack 1.20's `get_language` can hold Python's interpreter
+lock during network I/O. CGC uses `prefetch` before loading each requested
+grammar; that download path releases the lock. A pre-scan initialization failure
+fails the job before per-file parsing, with the original error included.
+
+For offline deployment, populate the cache at build time using the same pinned
+language-pack version and supported platform, for example:
+
+```bash
+python -c 'from tree_sitter_language_pack import prefetch; prefetch(["python", "typescript"])'
+```
+
+Choose the languages your deployment uses and make the resulting cache available
+to the runtime user. A missing grammar can still wait for the downloader's
+network timeout, but the serving loop remains available. Cancelling a worker
+cannot interrupt an in-flight native/subprocess call or roll back graph writes;
+SCIP stops subsequent phases when that call returns. Transactional cancellation
+is tracked separately in #829.
diff --git a/docs/docs/contributing_languages.md b/docs/docs/contributing_languages.md
@@ -178,3 +178,50 @@ Expected results include files such as `Greeter.sol` / `BaseGreeter.sol` / `Usin
 The initial Emacs Lisp implementation intentionally stays on the Tree-sitter pipeline. There is no standard `scip-elisp` indexer to register in `EXTENSION_TO_SCIP`, and the commonly used `elisp-refs` package is designed as an interactive Emacs reference finder rather than a batch indexer: it searches files recorded in the running Emacs `load-history`, renders results in a special buffer instead of emitting JSON or SCIP data, and exposes useful Lisp-2 function/variable heuristics only through internal APIs.
 
 A future semantic indexer could reuse those heuristics in a dedicated batch wrapper, but it would still need directory discovery, side-effect-safe loading or buffer creation, line/column conversion from character offsets, structured output, and explicit handling for macro expansion and indirect calls. Until that exists, `.el` files should continue to use Tree-sitter indexing with documented limitations around arbitrary macro semantics and dynamic dispatch.
+
+### HCL smoke check
+
+`.tf`, `.tfvars` and `.hcl` are parsed by `languages/hcl.py` (Terraform, OpenTofu, Terragrunt).
+The `hcl` grammar ships with every `tree-sitter-language-pack` release in the declared range.
+
+```bash
+cgc index ./tests/fixtures/sample_projects/sample_project_hcl --force
+cgc query "MATCH (c:Class) WHERE c.lang = 'hcl' RETURN c.name, c.node_type"
+cgc query "MATCH (f:File)-[:IMPORTS]->(m:Module) RETURN f.relative_path, m.name"
+```
+
+Expect blocks under their Terraform address (`aws_s3_bucket.artifacts`,
+`data.aws_caller_identity.current`, `module.logs`), variables as they are referenced
+(`var.bucket_name`, `output.bucket_arn`, `local.tags`) and one import per literal module source,
+`include` path, `dependency` config path and `dependencies` path. `modules/bucket` is imported
+by both `main.tf` and `live/app/terragrunt.hcl`; the `.terraform.lock.hcl` is not indexed. The
+graph is pinned by `tests/fixtures/goldens/sample_project_hcl` and
+`tests/integration/test_hcl_indexing_smoke.py`.
+
+### HCL graph schema
+
+| Graph element | HCL source | Properties |
+| :--- | :--- | :--- |
+| `File` | `.tf`, `.tfvars`, `.hcl` | `language = 'hcl'` |
+| `Class` | every labelled block other than `variable` and `output` | `name` = Terraform address, `node_type` = block type, `docstring` = literal or heredoc `description`, `line_number`, `end_line`, `lang = 'hcl'` |
+| `Variable` | `variable`, `output`, each `locals` entry, bare top-level assignments (`.tfvars`, Terragrunt `inputs`) | `name` = `var.x` / `output.x` / `local.x` / `x`, `value` = default or value as written, `docstring` |
+| `Module` | the target of a literal reference | `name` = registry or git address as written, or the absolute path of a local one, which equals that directory's `Directory.path` |
+| `(File)-[:CONTAINS]->(Class\|Variable)` | every extracted block and variable | |
+| `(File)-[:IMPORTS]->(Module)` | `module { source }`, Terragrunt `terraform { source }`, `include { path }`, `dependency { config_path }`, `dependencies { paths }` | `line_number` of the block |
+
+`Advanced_language_query` serves these through `query_tool_languages/hcl_toolkit.py`.
+
+### HCL limitations (v1)
+
+- No reference extraction, so no `function_calls` and no edges from a block to the variables it
+  reads. "Which configurations consume this module" works; "what breaks if I change
+  `var.location`" does not yet.
+- Only a reference written as a quoted string becomes an import. One built by a function call,
+  such as Terragrunt's `find_in_parent_folders("root.hcl")`, names no single target, and imports
+  merge into `Module` nodes by name alone, so keeping it would merge every configuration using
+  that idiom onto one node.
+- A reference relative to the file that writes it is resolved against that file, including
+  `${get_terragrunt_dir()}`. Other interpolations are kept as written: `${get_repo_root()}/x`
+  names the same file from everywhere, so those configurations should meet on one node.
+- `.hcl` is also used by Packer, Nomad, Consul and Vault. Those files parse, but their block
+  vocabularies are not modelled, so addresses fall back to `<block type>.<label>`.
diff --git a/docs/docs/reference/config.md b/docs/docs/reference/config.md
@@ -102,7 +102,7 @@ cgc config set ALLOW_DB_DELETION false
 | :--- | :--- | :--- |
 | **`DEFAULT_DATABASE`** | `falkordb` | Active database engine. Options: `kuzudb`, `ladybugdb`, `falkordb`, `falkordb-remote`, `neo4j`. |
 | **`ENABLE_AUTO_WATCH`** | `false` | When `true`, indexing a project automatically initializes a directory watcher. |
-| **`PARALLEL_WORKERS`** | `4` | Max thread pool size for parsing code files concurrently. |
+| **`PARALLEL_WORKERS`** | `4` | Max thread pool size for parsing code files concurrently. Shared by full indexing and the file watcher. Values above 32 are clamped. An empty or invalid value falls back to 10 for a full index and 4 for the watcher. |
 | **`CACHE_ENABLED`** | `true` | Caches file hashes to support fast incremental scans. |
 
 ### Indexing Scope Configurations