Merge branch 'task-14665-update-rust-repo-documentation'

Author: joshwilhelmi

AGENTS.md

@@ -4,7 +4,7 @@ This file is for AI coding agents (Claude, Copilot, Cursor, etc.) working on the
 
 ## What This Is
 
-`gobby-code` is a Rust CLI (`gcode`) that provides AST-aware code search, symbol navigation, and dependency graph analysis. It reads/writes the Gobby PostgreSQL hub for symbols/search, Neo4j for call graphs, and Qdrant for semantic vectors. It works without the Gobby daemon process, but requires a migrated PostgreSQL hub bootstrap.
+`gobby-code` is a Rust CLI (`gcode`) that provides AST-aware code search, symbol navigation, and dependency graph analysis. It reads/writes the Gobby PostgreSQL hub for symbols/search, FalkorDB for call graphs, and Qdrant for semantic vectors. It works without the Gobby daemon process, but requires a migrated PostgreSQL hub bootstrap.
 
 ## Build & Test
 
@@ -25,7 +25,7 @@ main.rs (clap CLI)
     → db::connect_readwrite/readonly # PostgreSQL hub connection
     → index/*                      # Indexing pipeline (walker → parser → chunker → indexer)
     → search/*                     # Search pipeline (fts + semantic + graph_boost → rrf)
-    → neo4j::*                     # Graph queries via HTTP
+    → falkor::*                     # Graph queries via FalkorDB
 ```
 
 ## Critical Constraints
@@ -49,7 +49,7 @@ These must match the Python daemon's `Symbol.make_id()` exactly. See `src/models
 
 ### 3. Config resolution order
 
-Always: env vars (`GOBBY_NEO4J_URL`, etc.) → `config_store` table → hardcoded defaults. Don't short-circuit.
+Always: env vars (`GOBBY_FALKORDB_HOST`, `GOBBY_FALKORDB_PORT`, `GOBBY_FALKORDB_PASSWORD`, etc.) → `config_store` table → hardcoded defaults. Don't short-circuit.
 
 ### 4. Do NOT run `gcode invalidate`
 
@@ -74,7 +74,7 @@ Always: env vars (`GOBBY_NEO4J_URL`, etc.) → `config_store` table → hardcode
 Search uses Reciprocal Rank Fusion in `src/search/rrf.rs` to merge results from:
 - `src/search/fts.rs` — pg_search BM25 symbol and content search
 - `src/search/semantic.rs` — Qdrant vector similarity
-- `src/search/graph_boost.rs` — Neo4j graph relevance
+- `src/search/graph_boost.rs` — FalkorDB graph relevance
 
 ### Modify the indexing pipeline
 
@@ -90,4 +90,4 @@ The pipeline in `src/index/indexer.rs` orchestrates:
 - Don't change UUID5 generation without verifying Python parity
 - Don't add `println!` for user output — use `eprintln!` for status, and `output::print_json` / `output::print_text` for command results
 - Don't skip the `--no-default-features` test pass — CI runs both configurations
-- Don't assume Neo4j or Qdrant are available — all code must handle `None` configs gracefully
+- Don't assume FalkorDB or Qdrant are available — all code must handle `None` configs gracefully

CHANGELOG.md

@@ -7,6 +7,21 @@ All notable changes to gobby-cli are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+#### gcode
+
+- **FalkorDB graph backend transition** - `gcode` now reads graph service
+  settings from the Gobby 0.4.x FalkorDB config path (`databases.falkordb.*`)
+  and uses FalkorDB for graph reads such as `callers`, `usages`, `imports`,
+  `blast-radius`, and graph-boosted search. `gcode 0.7.0+` requires
+  `gobby 0.4.0+`; running new `gcode` against an older daemon that still writes
+  Neo4j config-store keys silently degrades to "graph unavailable". Upgrade the
+  daemon and CLI together. This compatibility boundary is covered by the
+  Neo4j-to-FalkorDB Phase 8.3 validation matrix.
+
 ## [0.8.3] — gcode
 
 ### Changed

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 A Cargo workspace containing three Gobby CLI tools:
 
-- **gcode** (`crates/gcode/`) — AST-aware code search, symbol navigation, and dependency graph analysis. Reads/writes the Gobby PostgreSQL hub; reads Neo4j and Qdrant when configured. External sync (embeddings, graph) is handled by the Gobby daemon.
+- **gcode** (`crates/gcode/`) — AST-aware code search, symbol navigation, and dependency graph analysis. Reads/writes the Gobby PostgreSQL hub; reads FalkorDB and Qdrant when configured. External sync (embeddings, graph) is handled by the Gobby daemon.
 - **gsqz** (`crates/gsqz/`) — YAML-configurable output compressor for LLM token optimization. Wraps shell commands and applies pattern-based compression pipelines.
 - **gloc** (`crates/gloc/`) — Local LLM launcher. Auto-detects backends (LM Studio, Ollama), manages model lifecycle, and execs into AI CLI tools (Claude Code, Codex) with the right env vars.
 
@@ -26,7 +26,7 @@ cargo fmt --all --check                    # Check formatting
 
 ```
 crates/
-  gcode/    — Heavy binary (tree-sitter, PostgreSQL, Neo4j, Qdrant, opt-level=3)
+  gcode/    — Heavy binary (tree-sitter, PostgreSQL, FalkorDB, Qdrant, opt-level=3)
   gsqz/     — Tiny binary (regex pipelines, shell wrapper, opt-level="z")
   gloc/     — Tiny binary (local LLM launcher, backend detection, opt-level="z")
 ```
@@ -41,11 +41,11 @@ Release profiles are in the root `Cargo.toml` with per-package overrides. Each b
 
 ### Core Modules
 
-- **`config`** — Resolves runtime context: `~/.gobby/bootstrap.yaml` PostgreSQL DSN → PostgreSQL `config_store` → Neo4j/Qdrant configs. Detects project root by walking up from cwd looking for `.gobby/project.json`. Resolves `$secret:NAME` patterns via `secrets`.
+- **`config`** — Resolves runtime context: `~/.gobby/bootstrap.yaml` PostgreSQL DSN → PostgreSQL `config_store` → FalkorDB/Qdrant configs. Detects project root by walking up from cwd looking for `.gobby/project.json`. Resolves `$secret:NAME` patterns via `secrets`.
 - **`db`** — PostgreSQL bootstrap/keyring resolution plus read/write connection helpers. Runtime schema is validated, never created or migrated by gcode.
 - **`models`** — All data types: `Symbol`, `IndexedFile`, `ContentChunk`, `SearchResult`, `GraphResult`, etc.
 - **`secrets`** — Fernet decryption of Gobby secrets using `~/.gobby/machine_id` + `~/.gobby/.secret_salt` for key derivation.
-- **`neo4j`** — HTTP client for Neo4j Cypher read queries (callers, usages, imports, blast radius). Graph writes are handled by the Gobby daemon.
+- **`falkor`** — FalkorDB read client for graph queries (callers, usages, imports, blast radius). Graph writes are handled by the Gobby daemon.
 - **`output`** — Output formatting (text vs JSON).
 
 ### `commands/` — CLI Command Handlers
@@ -58,11 +58,11 @@ Each subcommand maps to a function: `index::run`, `search::search`, `symbols::ou
 
 ### `search/` — Search Pipeline
 
-`fts` (pg_search BM25 symbol + content search) + `semantic` (Qdrant vector search via OpenAI-compatible embedding API) + `graph_boost` (Neo4j relevance boost) → `rrf` (Reciprocal Rank Fusion to merge ranked results).
+`fts` (pg_search BM25 symbol + content search) + `semantic` (Qdrant vector search via OpenAI-compatible embedding API) + `graph_boost` (FalkorDB relevance boost) → `rrf` (Reciprocal Rank Fusion to merge ranked results).
 
 ### Graceful Degradation
 
-Neo4j/Qdrant/embedding API can each be unavailable independently. Graph commands return `[]` when Neo4j is down; semantic search returns `[]` when Qdrant or the embedding API is unavailable; BM25 search works when the PostgreSQL hub is configured and indexed.
+FalkorDB/Qdrant/embedding API can each be unavailable independently. Graph commands return `[]` when FalkorDB is down; semantic search returns `[]` when Qdrant or the embedding API is unavailable; BM25 search works when the PostgreSQL hub is configured and indexed.
 
 ## gsqz Architecture
 
@@ -94,7 +94,7 @@ CLI parses args → loads layered config → auto-detects backend (probes LM Stu
 ## Key Constraints
 
 - **UUID5 parity with Python** (gcode): Symbol IDs are deterministic UUID5 using namespace `c0de1de0-0000-4000-8000-000000000000` and key format `{project_id}:{file_path}:{name}:{kind}:{byte_start}`. Must match the Python daemon's `Symbol.make_id()` exactly.
-- **Config resolution order** (gcode): env vars (`GOBBY_NEO4J_URL`, etc.) → `config_store` table → hardcoded defaults.
+- **Config resolution order** (gcode): env vars (`GOBBY_FALKORDB_HOST`, `GOBBY_FALKORDB_PORT`, `GOBBY_FALKORDB_PASSWORD`, etc.) → `config_store` table → hardcoded defaults.
 - **Tree-sitter grammars** (gcode): Tier 1 (Python/JS/TS/Go/Rust/Java/C/C++/C#/Ruby/PHP/Swift/Kotlin), Tier 2 (Dart/Elixir), Tier 3 (JSON/YAML/Markdown). Adding a language requires a new `tree-sitter-*` dep in `crates/gcode/Cargo.toml` and a grammar entry in `index/languages`.
 - **Non-destructive to Gobby hub schema** (gcode): Validate existing Gobby-owned PostgreSQL tables and BM25 indexes. Never alter `project.json`, `config_store`, or Gobby-managed schema.
 - **Exit code 0** (gsqz): Always exit 0 regardless of subprocess exit code. The LLM reads pass/fail from content.

README.md

@@ -27,7 +27,7 @@ This workspace contains four Gobby CLI tools plus a shared library:
 
 AST-aware code search powered by tree-sitter. Indexes 18 languages into the
 Gobby PostgreSQL hub with pg_search BM25 for symbol lookup, content search, file
-tree navigation, and hybrid ranking. When Neo4j, Qdrant, and an embeddings
+tree navigation, and hybrid ranking. When FalkorDB, Qdrant, and an embeddings
 endpoint are configured - typically through Gobby - `gcode` adds graph-aware
 search, semantic search, dependency analysis (`callers`, `usages`, `imports`,
 `blast-radius`), and daemon-backed graph lifecycle commands (`gcode graph clear`,
@@ -85,7 +85,7 @@ cargo install gobby-hooks
 ```
 
 `gcode` graph and semantic features are configured at runtime. There are no
-Cargo feature flags for Neo4j, Qdrant, or embeddings support.
+Cargo feature flags for FalkorDB, Qdrant, or embeddings support.
 
 `gcode` 0.8.0+ uses the migrated Gobby PostgreSQL hub. It reads
 `~/.gobby/bootstrap.yaml`, requires `hub_backend: postgres`, and resolves the

crates/gcode/README.md

@@ -46,12 +46,12 @@ codebase → tree-sitter AST → PostgreSQL hub → search / retrieve / navigate
      │          │          │        │
   symbols    chunks     files    ┌──┴──┐
   (BM25)    (BM25)   (hashes)   │     │
-                              Neo4j  Qdrant
+                              FalkorDB Qdrant
                              (calls) (vectors)
 ```
 
 1. **Index** — Walk files, parse ASTs with tree-sitter, extract symbols and content chunks
-2. **Store** — PostgreSQL hub tables for symbols/content, Neo4j for call/import graphs, Qdrant for semantic vectors
+2. **Store** — PostgreSQL hub tables for symbols/content, FalkorDB for call/import graphs, Qdrant for semantic vectors
 3. **Search** — Hybrid ranking: pg_search BM25 + optional semantic + optional graph sources → Reciprocal Rank Fusion
 4. **Retrieve** — Byte-offset reads for exact symbol source, no file-level bloat
 
@@ -90,7 +90,7 @@ cargo install gobby-code
 ```
 
 Graph and semantic features are configured at runtime. You do not need Cargo
-feature flags to enable Neo4j, Qdrant, or embeddings support.
+feature flags to enable FalkorDB, Qdrant, or embeddings support.
 
 Runtime indexing/search requires a migrated Gobby PostgreSQL hub. gcode reads
 `~/.gobby/bootstrap.yaml`, requires `hub_backend: postgres`, and resolves the
@@ -130,7 +130,7 @@ gcode symbol <id>                         # Source code by symbol ID
 gcode symbols <id1> <id2> ...             # Batch retrieve
 gcode tree                                # File tree with symbol counts
 
-# Dependency graph reads (requires Neo4j)
+# Dependency graph reads (requires FalkorDB)
 gcode callers "handleAuth"                # Who calls this?
 gcode usages "handleAuth"                 # Incoming call sites
 gcode imports src/auth.ts                 # Import graph for a file
@@ -186,17 +186,17 @@ source of truth for code-index rows.
 
 ```
 codebase → tree-sitter → PostgreSQL hub + pg_search BM25
-                          Neo4j                 → call graphs, blast radius, imports
+                          FalkorDB              → call graphs, blast radius, imports
                           Qdrant + embeddings   → semantic vector search
                           Gobby daemon          → auto-indexing, graph/vector sync,
                                                   config, secrets, sessions, agents
 ```
 
 Gobby adds graph queries, graph lifecycle orchestration, semantic search, and infrastructure that makes gcode better at its core job — not just more features bolted on.
 
-**Search quality improves.** With Neo4j, `gcode search` blends BM25 text matching with call-graph relevance. With Qdrant plus a configured embeddings API, conceptual queries like "database connection pooling" can find semantically similar code even when the exact words don't match.
+**Search quality improves.** With FalkorDB, `gcode search` blends BM25 text matching with call-graph relevance. With Qdrant plus a configured embeddings API, conceptual queries like "database connection pooling" can find semantically similar code even when the exact words don't match.
 
-**Config and secrets are managed.** Neo4j URLs, Qdrant API keys, and auth credentials are stored in the shared database and encrypted with Fernet. No env vars to juggle.
+**Config and secrets are managed.** FalkorDB connection settings, Qdrant API keys, and auth credentials are stored in the shared database and encrypted with Fernet. No env vars to juggle.
 
 **PostgreSQL DSNs stay out of plaintext files.** Isolated gcode runtimes keep
 `database_url_ref: keyring:gobby:postgres_database_url`; gcode resolves it
@@ -208,10 +208,10 @@ keyring.
 | Capability | gcode CLI | With Gobby daemon/services |
 |-----------|-----------|-----------|
 | AST indexing + BM25 search | Yes, via PostgreSQL hub | Yes |
-| Graph-boosted search ranking | When Neo4j is configured | Yes |
+| Graph-boosted search ranking | When FalkorDB is configured | Yes |
 | Semantic vector search | When Qdrant + embeddings are configured | Yes |
-| Call graph / blast radius | When Neo4j is configured | Yes |
-| Import graph | When Neo4j is configured | Yes |
+| Call graph / blast radius | When FalkorDB is configured | Yes |
+| Import graph | When FalkorDB is configured | Yes |
 | Graph clear / rebuild lifecycle | Requires daemon | Yes |
 | Auto-indexing on file change | Manual `gcode index` | Yes (daemon file watcher) |
 | Centralized config + secrets | Reads PostgreSQL `config_store` + secrets | Yes |
@@ -226,13 +226,13 @@ Get started with Gobby at [github.com/GobbyAI/gobby](https://github.com/GobbyAI/
 
 | Service unavailable | Behavior |
 |---------------------|----------|
-| Neo4j down | Graph commands return `[]`. Search loses graph boost. |
+| FalkorDB down | Graph commands return `[]`. Search loses graph boost. |
 | Qdrant down | Search loses semantic boost. BM25 + graph still work. |
 | Embeddings API unavailable | Semantic embeddings disabled. BM25 + graph still work. |
 | PostgreSQL hub unavailable | Runtime index/search commands fail with a bootstrap or connection error. |
 | No index yet | Commands error with `Run gcode init to initialize`. |
 
-Read-side graph commands depend on Neo4j. `gcode graph clear` and `gcode graph rebuild`
+Read-side graph commands depend on FalkorDB. `gcode graph clear` and `gcode graph rebuild`
 are separate lifecycle operations routed through the Gobby daemon for the
 current resolved project.