[gobby-cli-#170] docs: prepare gcode FalkorDB release

Author: joshwilhelmi

CHANGELOG.md

@@ -11,7 +11,7 @@ cargo build --workspace --no-default-features
 cargo test --workspace --no-default-features
 ```
 
-The `rust-toolchain.toml` ensures you have the right toolchain and components (clippy, rustfmt) installed automatically. The `--no-default-features` flag skips the gcode `embeddings` feature which requires cmake.
+The `rust-toolchain.toml` ensures you have the right toolchain and components (clippy, rustfmt) installed automatically. CI uses `--no-default-features`; keep that build clean even when a crate has no default feature set.
 
 ## Development
 
@@ -41,17 +41,17 @@ All PRs must pass CI (fmt, clippy, tests) before merging.
 
 ```
 crates/
-  gcode/                 — AST-aware code search (heavy: tree-sitter, SQLite, opt-level=3)
+  gcode/                 — AST-aware code search (heavy: tree-sitter, PostgreSQL, opt-level=3)
     src/
       main.rs            — CLI entry point, command dispatch
       config.rs          — Runtime context resolution, service configs
-      db.rs              — SQLite connection helpers
+      db.rs              — PostgreSQL hub connection helpers
       models.rs          — Data types: Symbol, IndexedFile, SearchResult, etc.
       secrets.rs         — Fernet decryption for Gobby secrets
-      neo4j.rs           — Neo4j HTTP client for graph queries
+      falkor.rs          — FalkorDB client for graph queries
       commands/          — Subcommand handlers (init, index, search, graph, etc.)
       index/             — Indexing pipeline (walker, parser, chunker, hasher, indexer)
-      search/            — Search pipeline (FTS5, semantic, graph_boost, RRF)
+      search/            — Search pipeline (pg_search BM25, semantic, graph_boost, RRF)
   gsqz/                  — Output compressor (tiny: regex, opt-level="z")
     src/
       main.rs            — CLI entry point, command execution, ANSI stripping

CONTRIBUTING.md

@@ -85,7 +85,10 @@ cargo install gobby-hooks
 ```
 
 `gcode` graph and semantic features are configured at runtime. There are no
-Cargo feature flags for FalkorDB, Qdrant, or embeddings support.
+Cargo feature flags for FalkorDB, Qdrant, or embeddings support. Gobby-managed
+projects read FalkorDB settings from `databases.falkordb.*`; daemon-independent
+setups can use `GOBBY_FALKORDB_HOST`, `GOBBY_FALKORDB_PORT`, and
+`GOBBY_FALKORDB_PASSWORD`.
 
 `gcode` 0.8.0+ uses the migrated Gobby PostgreSQL hub. It reads
 `~/.gobby/bootstrap.yaml`, requires `hub_backend: postgres`, and resolves the

README.md

@@ -90,7 +90,10 @@ cargo install gobby-code
 ```
 
 Graph and semantic features are configured at runtime. You do not need Cargo
-feature flags to enable FalkorDB, Qdrant, or embeddings support.
+feature flags to enable FalkorDB, Qdrant, or embeddings support. Gobby-managed
+projects read FalkorDB settings from `databases.falkordb.*`; daemon-independent
+setups can use `GOBBY_FALKORDB_HOST`, `GOBBY_FALKORDB_PORT`, and
+`GOBBY_FALKORDB_PASSWORD`.
 
 Runtime indexing/search requires a migrated Gobby PostgreSQL hub. gcode reads
 `~/.gobby/bootstrap.yaml`, requires `hub_backend: postgres`, and resolves the

crates/gcode/README.md

@@ -12,7 +12,7 @@ CLI (main.rs, clap)
     → commands/{search,symbols,graph,index,status,init}.rs
       → search/ pipeline (pg_search BM25 + optional semantic + optional graph sources → RRF)
       → index/ pipeline (walker → parser → chunker → hasher → indexer)
-      → neo4j (HTTP Cypher queries)
+      → falkor (FalkorDB graph queries)
       → db (PostgreSQL hub connections)
       → output (JSON/text formatting)
 ```
@@ -93,13 +93,13 @@ tell users to finish `gobby postgres migrate-from-sqlite` and cut over.
 
 ### Service Configuration
 
-Resolution order per service (Neo4j, Qdrant, embeddings):
+Resolution order per service (FalkorDB, Qdrant, embeddings):
 
 | Priority | Source | Example |
 |----------|--------|---------|
-| 1 (highest) | Environment variables | `GOBBY_NEO4J_URL`, `GOBBY_QDRANT_URL`, `GOBBY_EMBEDDING_URL` |
-| 2 | `config_store` table in PostgreSQL | `databases.neo4j.url`, `databases.qdrant.url`, `embeddings.api_base` |
-| 3 (lowest) | Hardcoded defaults | Neo4j `http://localhost:8474` / `neo4j`; embeddings model `nomic-embed-text` once an API base exists |
+| 1 (highest) | Environment variables | `GOBBY_FALKORDB_HOST`, `GOBBY_FALKORDB_PORT`, `GOBBY_FALKORDB_PASSWORD`, `GOBBY_QDRANT_URL`, `GOBBY_EMBEDDING_URL` |
+| 2 | `config_store` table in PostgreSQL | `databases.falkordb.host`, `databases.falkordb.port`, `databases.falkordb.requirepass`, `databases.qdrant.url`, `embeddings.api_base` |
+| 3 (lowest) | Hardcoded defaults | FalkorDB port `16379` and graph name `gobby_code` once a host is configured; embeddings model `nomic-embed-text` once an API base exists |
 
 Config values are JSON-encoded in `config_store` — strings have surrounding quotes stripped. Secret patterns like `$secret:NAME` are resolved via `secrets.rs` (Fernet decryption using machine_id + salt, 600K PBKDF2 iterations).
 
@@ -161,7 +161,7 @@ pass before call targets are finalized:
 - Unmatched calls stay `unresolved`
 - Import-bound external calls are marked `external` and retain their source module
 
-This keeps external package calls out of the local call graph and improves Neo4j
+This keeps external package calls out of the local call graph and improves FalkorDB
 correctness for `callers`, `usages`, `blast-radius`, and graph-backed search.
 
 ### Language Support (languages.rs)
@@ -189,7 +189,7 @@ Files are split into overlapping chunks for BM25 content search:
 
 1. **Hash comparison**: SHA-256 content hash per file, stored in `code_indexed_files`
 2. **Stale detection**: Compare current hashes against stored hashes; files with changed hashes are re-indexed.
-3. **Orphan cleanup**: Files in the DB that no longer exist on disk have their hub rows deleted. External cleanup (Neo4j/Qdrant) is handled by the daemon's reconcile/sync workers.
+3. **Orphan cleanup**: Files in the DB that no longer exist on disk have their hub rows deleted. External cleanup (FalkorDB/Qdrant) is handled by the daemon's reconcile/sync workers.
 4. **Per-file transactions**: PostgreSQL writes (delete old data, upsert symbols, upsert file, upsert content chunks, upsert imports/calls) are wrapped in a single transaction to prevent half-indexed files on crash.
 5. **External sync flags**: Changed files are written with `graph_synced=false`, `vectors_synced=false`, and `graph_sync_attempted_at=NULL` so the daemon can regenerate graph and vector projections.
 
@@ -232,15 +232,15 @@ The runtime schema validator requires these tables before gcode starts index/sea
 
 ### Graph Lifecycle RPCs
 
-Read-side graph queries still go straight to Neo4j. Graph lifecycle operations
+Read-side graph queries still go straight to FalkorDB. Graph lifecycle operations
 are daemon-backed orchestration commands instead:
 
 - `gcode graph clear` → `POST /api/code-index/graph/clear?project_id=...`
 - `gcode graph rebuild` → `POST /api/code-index/graph/rebuild?project_id=...`
 
 These commands use the current resolved `Context.project_id`, require a daemon
 URL, and fail hard on transport errors, non-2xx responses, or invalid JSON
-success bodies. They do not talk to Neo4j directly.
+success bodies. They do not talk to FalkorDB directly.
 
 ### UUID5 Parity
 
@@ -264,11 +264,11 @@ Source 2: Semantic (Qdrant vector search)
   → POST to Qdrant /collections/{name}/points/search
   → returns (symbol_id, score) pairs
 
-Source 3: Graph Boost (Neo4j)
+Source 3: Graph Boost (FalkorDB)
   → find_callers + find_usages for query term
   → returns symbol IDs that are connected in the call/import graph
 
-Source 4: Graph Expand (Neo4j)
+Source 4: Graph Expand (FalkorDB)
   → seed from top FTS + semantic hits
   → expand through callees first, then callers
 
@@ -293,7 +293,7 @@ score(symbol) = Σ 1/(K + rank) for each source containing the symbol
 
 ### Symbol Resolution
 
-After RRF merge, ALL symbol IDs are resolved against PostgreSQL before computing `total`. This ensures `total` reflects the count of actually-resolvable symbols (stale Qdrant/Neo4j entries are silently skipped). Offset/limit pagination is applied after resolution.
+After RRF merge, ALL symbol IDs are resolved against PostgreSQL before computing `total`. This ensures `total` reflects the count of actually-resolvable symbols (stale Qdrant/FalkorDB entries are silently skipped). Offset/limit pagination is applied after resolution.
 
 The `total` for hybrid search is a best-effort estimate bounded by `fetch_limit`
 per source — exact counts aren't feasible because RRF merges results from
@@ -320,7 +320,7 @@ All search/graph commands return a `PagedResponse` envelope:
 
 - `--offset N` skips the first N results
 - `--limit N` caps results per page (default: 10)
-- `hint` is populated when Neo4j is unavailable (graph commands only)
+- `hint` is populated when FalkorDB is unavailable (graph commands only)
 - Text mode shows a pagination footer: `-- 10 of 47 results (use --offset 10 for more)`
 
 ## Database Schema
@@ -361,7 +361,7 @@ Gobby repository migrations/baseline; gcode only validates and uses the tables.
 | symbol_count | INTEGER | |
 | byte_size | INTEGER | |
 | indexed_at | TIMESTAMPTZ | Cast to text for CLI output |
-| graph_synced | BOOLEAN | `false` means Neo4j sync pending |
+| graph_synced | BOOLEAN | `false` means FalkorDB sync pending |
 | vectors_synced | BOOLEAN | `false` means Qdrant sync pending |
 
 **`code_imports`** — Import relations (daemon migration v183, Gobby mode only)
@@ -407,7 +407,7 @@ UNIQUE constraint on `(project_id, source_file, target_module)`.
 
 **`config_store`** — Key-value configuration (Gobby mode only)
 
-## Neo4j Graph Model
+## FalkorDB Graph Model
 
 ### Nodes
 
@@ -436,13 +436,13 @@ Count queries use the same patterns with `RETURN count(...)` for accurate pagina
 
 **File:** `src/search/fts.rs` (`resolve_graph_symbol`), `src/commands/graph.rs` (`resolve_symbol`)
 
-All graph commands resolve user input to an actual symbol name before querying Neo4j. Resolution order:
+All graph commands resolve user input to an actual symbol name before querying FalkorDB. Resolution order:
 
 1. **Exact match** — `SELECT ... FROM code_symbols WHERE id/name/qualified_name = $1`
 2. **LIKE match** — `WHERE name LIKE $pattern OR qualified_name LIKE $pattern`
 3. **BM25 search** — `search_symbols_fts()` across names, signatures, docstrings, summaries
 
-Single match → used directly. Multiple matches → fail closed with alternatives shown on stderr. No match → error message, no Neo4j query issued.
+Single match → used directly. Multiple matches → fail closed with alternatives shown on stderr. No match → error message, no FalkorDB query issued.
 
 ## Semantic Search Integration
 
@@ -472,7 +472,7 @@ Each external service degrades independently:
 
 | Service | When Unavailable | Impact |
 |---------|-----------------|--------|
-| Neo4j | No config or connection refused | Graph commands return `[]` with hint; search loses graph boost |
+| FalkorDB | No config or connection refused | Graph commands return `[]` with hint; search loses graph boost |
 | Qdrant | No URL configured | Search loses semantic source; BM25 still works |
 | Embeddings API | No API base, auth failure, or request error | Semantic search disabled for that query |
 | Daemon | Not running | Normal index/search still work; graph lifecycle RPCs fail and external sync waits for the daemon |

docs/guides/gcode-development-guide.md

@@ -13,7 +13,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 Gobby's PostgreSQL hub bootstrap. gcode reads
 `~/.gobby/bootstrap.yaml`, requires `hub_backend: postgres`, and connects
@@ -80,7 +80,7 @@ gcode offers four search modes for different use cases.
 ### Hybrid Search (`gcode search`)
 
 The default. Combines pg_search BM25 text matching with optional semantic similarity,
-graph boost, and graph expansion using Reciprocal Rank Fusion. If Neo4j,
+graph boost, and graph expansion using Reciprocal Rank Fusion. If FalkorDB,
 Qdrant, or the embeddings endpoint are unavailable, `gcode search` falls back
 to the sources that are configured.
 
@@ -141,7 +141,7 @@ pg_search BM25 search across file content chunks — covers source bodies, comme
 
 ```bash
 gcode search-content "TODO: refactor"
-gcode search-content "GOBBY_NEO4J_URL" --path "*.py"
+gcode search-content "GOBBY_FALKORDB_HOST" --path "*.py"
 gcode search-content "primary-color" --language css
 ```
 
@@ -201,10 +201,10 @@ Useful for understanding project structure at a glance.
 
 ## Dependency Graph
 
-Read-side graph commands require Neo4j. Gobby-managed projects usually provide this
-automatically, and daemon-independent projects can opt in with `GOBBY_NEO4J_URL` and
-`GOBBY_NEO4J_AUTH`. Without Neo4j, graph read commands return empty results
-gracefully.
+Read-side graph commands require FalkorDB. Gobby-managed projects usually provide this
+automatically, and daemon-independent projects can opt in with `GOBBY_FALKORDB_HOST`,
+`GOBBY_FALKORDB_PORT`, and `GOBBY_FALKORDB_PASSWORD`. Without FalkorDB, graph read
+commands return empty results gracefully.
 
 All read-side graph commands resolve fuzzy input — you don't need the exact symbol name. Resolution tries exact match, then substring match, then BM25 search across names, signatures, and docstrings. When multiple matches are found, the best is used and alternatives are shown on stderr.
 
@@ -320,7 +320,7 @@ gcode index --files src/config.rs src/main.rs
 
 `gcode index` writes symbols, files, chunks, imports, and calls to the
 PostgreSQL hub. It marks graph/vector sync flags dirty; the Gobby daemon handles
-Neo4j graph edges and Qdrant vector sync asynchronously when it is running.
+FalkorDB graph edges and Qdrant vector sync asynchronously when it is running.
 BM25 search (`search-text`, `search-content`) works as soon as the transaction
 commits; graph and semantic search improve once the external stores sync.
 
@@ -331,7 +331,7 @@ gcode invalidate
 gcode index
 ```
 
-In Gobby mode, `invalidate` also notifies the daemon to clean up Neo4j graph nodes and Qdrant vectors for the project. Use `--force` to skip the confirmation prompt.
+In Gobby mode, `invalidate` also notifies the daemon to clean up FalkorDB graph nodes and Qdrant vectors for the project. Use `--force` to skip the confirmation prompt.
 
 Graph projection lifecycle is separate:
 
@@ -348,7 +348,7 @@ gcode is daemon-independent but not database-independent:
 - Database: PostgreSQL hub from `~/.gobby/bootstrap.yaml`
 - Required bootstrap: `hub_backend: postgres` plus supported `database_url_ref` or `database_url`
 - Identity: `.gobby/project.json`, `.gobby/gcode.json`, isolated root, linked worktree, or generated identity from `gcode init`
-- Optional services: Neo4j, Qdrant, and embeddings via env vars or PostgreSQL `config_store`
+- Optional services: FalkorDB, Qdrant, and embeddings via env vars or PostgreSQL `config_store`
 
 Graph commands and semantic search become available when the required services are configured.
 
@@ -363,11 +363,11 @@ Both cases are reported by `gcode init`'s status line (`isolated`, `linked-workt
 
 ## Configuration
 
-gcode resolves configuration in this order:
+gcode resolves graph/vector configuration in this order:
 
-1. **Environment variables** — `GOBBY_NEO4J_URL`, `GOBBY_NEO4J_AUTH`, `GOBBY_QDRANT_URL`, `GOBBY_PORT`
-2. **config_store table** — Key-value pairs in the PostgreSQL hub (`databases.neo4j.*`, `databases.qdrant.*`, `embeddings.*`)
-3. **Hardcoded defaults** — Neo4j at `http://localhost:8474`, database `neo4j` (only when `config_store` exists)
+1. **Environment variables** — `GOBBY_FALKORDB_HOST`, `GOBBY_FALKORDB_PORT`, `GOBBY_FALKORDB_PASSWORD`, `GOBBY_QDRANT_URL`
+2. **config_store table** — Key-value pairs in the PostgreSQL hub (`databases.falkordb.host`, `databases.falkordb.port`, `databases.falkordb.requirepass`, `databases.qdrant.*`, `embeddings.*`)
+3. **Hardcoded defaults** — FalkorDB port `16379` and graph name `gobby_code` once a host is configured; no default FalkorDB host is assumed
 
 Semantic search uses the same precedence rules:
 1. **Environment variables** — `GOBBY_EMBEDDING_URL`, `GOBBY_EMBEDDING_MODEL`, `GOBBY_EMBEDDING_API_KEY`
@@ -486,10 +486,11 @@ gcode projects
 
 If you get "No symbol matching 'X' found", the input didn't resolve to any indexed symbol. Try a different term or check what's indexed with `gcode search-text "X"`.
 
-If results are empty but the symbol exists, this is expected when Neo4j is not configured. In Gobby mode, check that Neo4j is running and configured:
+If results are empty but the symbol exists, this is expected when FalkorDB is not configured. In Gobby mode, check that FalkorDB is running and configured:
 
 ```bash
-echo $GOBBY_NEO4J_URL
+echo $GOBBY_FALKORDB_HOST
+echo $GOBBY_FALKORDB_PORT
 gcode status
 ```
 

docs/guides/gcode-user-guide.md

@@ -4,7 +4,7 @@
 
 gcode currently cannot run without gobby having set up the database first. It has zero `CREATE TABLE` logic — writes silently fail, reads return empty when tables are missing. This plan adds self-initializing schema creation so gcode works fully standalone (FTS5 search, no external deps) while seamlessly integrating when gobby is installed (shared `~/.gobby/gobby-hub.db`).
 
-**Value ladder:** gcode standalone = fast FTS search. With gobby = adds Qdrant semantic search, Neo4j graph, AI summaries.
+**Value ladder:** gcode standalone = fast FTS search. With gobby = adds Qdrant semantic search, FalkorDB graph, AI summaries.
 
 ## Implementation