Merge pull request #16 from churcho/fix/documentation

Fix documentation to use `code_search code` subcommand prefix

Author: CamonZ

README.md

@@ -47,29 +47,29 @@ The database is automatically created at `.code_search/surrealdb.rocksdb` in you
 Import a call graph JSON file (generated by [ex_ast](https://github.com/CamonZ/ex_ast)):
 
 ```bash
-code_search import --file call_graph.json
+code_search code import --file call_graph.json
 ```
 
 ### 3. Query the data
 
 ```bash
 # Find where a function is defined
-code_search location get_user MyApp.Accounts
+code_search code location get_user MyApp.Accounts
 
 # What does this function call?
-code_search calls-from MyApp.Accounts get_user
+code_search code calls-from MyApp.Accounts get_user
 
 # Who calls this function?
-code_search calls-to MyApp.Repo get
+code_search code calls-to MyApp.Repo get
 
 # Trace the full call chain from a function
-code_search trace MyApp.Web.UserController show
+code_search code trace MyApp.Web.UserController show
 
 # Find unused functions
-code_search unused -P
+code_search code unused -P
 
 # Find hotspots (most called functions)
-code_search hotspots -l 10
+code_search code hotspots -l 10
 ```
 
 ## Output Formats
@@ -82,7 +82,7 @@ All commands support three output formats via `--format` or `-o`:
 
 ## Commands
 
-Use `code_search <command> --help` for detailed help on any command.
+Use `code_search code <command> --help` for detailed help on any command.
 
 ### Query Commands
 
@@ -169,26 +169,26 @@ If `--db` is not specified, commands automatically search for the database in th
 
 ```bash
 # Find all functions that accept a User.t type
-code_search accepts "User.t"
+code_search code accepts "User.t"
 
 # Find modules with circular dependencies
-code_search cycles MyApp.Core
+code_search code cycles MyApp.Core
 
 # Find the most complex functions in a namespace
-code_search complexity MyApp.Accounts --min 10
+code_search code complexity MyApp.Accounts --min 10
 
 # Trace how a controller action flows through the codebase
-code_search trace MyApp.Web.UserController create --depth 10
+code_search code trace MyApp.Web.UserController create --depth 10
 
 # Find all paths from an API endpoint to a database call
-code_search path --from-module MyApp.API --from-function create_user \
+code_search code path --from-module MyApp.API --from-function create_user \
                  --to-module MyApp.Repo --to-function insert
 
 # Find god modules (too large, too connected)
-code_search god-modules --min-functions 30 --min-loc 500
+code_search code god-modules --min-functions 30 --min-loc 500
 
 # Find boundary modules that many depend on
-code_search boundaries --min-ratio 3.0
+code_search code boundaries --min-ratio 3.0
 ```
 
 ## Claude Code Integration
@@ -234,6 +234,22 @@ git config code-search.mix-env test  # Default: dev
 
 See [docs/GIT_HOOKS.md](docs/GIT_HOOKS.md) for detailed documentation and troubleshooting.
 
+### Git Worktrees
+
+When using [git worktrees](https://git-scm.com/docs/git-worktree), each
+worktree must have its own local database. Run setup and import once in
+each worktree directory:
+
+```sh
+mix compile
+ex_ast --output /tmp/call_graph.json
+code_search setup
+code_search code import --file /tmp/call_graph.json
+```
+
+See [docs/WORKTREES.md](docs/WORKTREES.md) for full details and
+troubleshooting.
+
 ### Using with Claude Code
 
 Once templates are installed, Claude Code can automatically help you explore your codebase:

docs/GIT_HOOKS.md

@@ -81,7 +81,7 @@ When you make a commit, the post-commit hook:
    - Uses the configured Mix environment
    - Outputs JSON to a temporary file
 
-4. **Updates database**: Runs `code_search import` to update the database
+4. **Updates database**: Runs `code_search code import` to update the database
    - Database path auto-resolves to `.code_search/surrealdb.rocksdb`
    - Uses configured project name if set (optional)
    - Performs upsert operations (updates existing records, inserts new ones)
@@ -224,7 +224,7 @@ mix compile --debug-info
 ex_ast --git-diff HEAD~1 --format json --output changes.json
 
 # Import
-code_search --db call_graph.db import --file changes.json
+code_search --db call_graph.db code import --file changes.json
 ```
 
 Or for a different git reference:
@@ -246,7 +246,7 @@ The same approach works in CI/CD pipelines. Example GitHub Actions workflow:
   run: |
     mix compile --debug-info
     ex_ast --git-diff HEAD~1 --format json --output changes.json
-    code_search --db call_graph.db import --file changes.json
+    code_search --db call_graph.db code import --file changes.json
 ```
 
 ## Performance Characteristics

docs/NEW_COMMANDS.md

@@ -56,7 +56,7 @@ use crate::output::{OutputFormat, Outputable};
 #[derive(Args, Debug)]
 #[command(after_help = "\
 Examples:
-  code_search <name> --arg value    # Example usage")]
+  code_search code <name> --arg value    # Example usage")]
 pub struct <Name>Cmd {
     /// Description of the argument
     #[arg(short, long)]
@@ -148,34 +148,31 @@ impl Outputable for <Name>Result {
 
 See [examples/output_tests.rs.example](./examples/output_tests.rs.example) for a reference showing the snapshot testing pattern. The example includes a helper for generating the actual output values to use in your snapshots.
 
-### 8. Register the command (`src/commands/mod.rs`)
+### 8. Register the command
 
-Add the module declaration and public export:
+Add the module declaration and public export in `src/commands/mod.rs`:
 
 ```rust
 mod <name>;
 
 pub use <name>::<Name>Cmd;
 ```
 
-Add the variant to the `Command` enum:
+Add the variant to the `CodeCommand` enum in `src/commands/code.rs`:
 
 ```rust
 #[derive(Subcommand, Debug)]
 #[enum_dispatch(CommandRunner)]
-pub enum Command {
+pub enum CodeCommand {
     /// Existing commands...
     Import(ImportCmd),
 
     /// Description of your command
     <Name>(<Name>Cmd),
-
-    #[command(external_subcommand)]
-    Unknown(Vec<String>),
 }
 ```
 
-**Note:** The `#[enum_dispatch(CommandRunner)]` attribute is already on the `Command` enum. The `enum_dispatch` crate automatically generates the dispatch logic for all variants. You do NOT need to add a match arm in `Command::run()` - the `CommandRunner` implementation you added to your command's `mod.rs` file (in step 2) is all that's needed!
+**Note:** The top-level `Command` enum in `mod.rs` has only `Setup` and `Code(CodeCommand)`. All code analysis commands are registered in `CodeCommand` (in `code.rs`), not in `Command`. The `#[enum_dispatch(CommandRunner)]` attribute automatically generates dispatch logic for all variants. You do NOT need to add a match arm — the `CommandRunner` implementation you added to your command's `mod.rs` file (in step 2) is all that's needed!
 
 The dispatch is handled entirely by the `enum_dispatch` procedural macro at compile time, which is faster and more maintainable than manual match arms.
 
@@ -184,7 +181,7 @@ The dispatch is handled entirely by the `enum_dispatch` procedural macro at comp
 ```bash
 cargo build
 cargo test
-cargo run -- <name> --help
+cargo run -- code <name> --help
 ```
 
 ## Checklist
@@ -219,7 +216,7 @@ cargo run -- <name> --help
 - [ ] Registered command in `src/commands/mod.rs`
   - [ ] Added module declaration: `mod <name>;`
   - [ ] Added public export: `pub use <name>::<Name>Cmd;`
-  - [ ] Added enum variant to `Command` enum (dispatch is automatic via `#[enum_dispatch(CommandRunner)]`)
+- [ ] Added enum variant to `CodeCommand` in `src/commands/code.rs` (dispatch is automatic via `#[enum_dispatch(CommandRunner)]`)
   - [ ] **No match arm needed** - enum_dispatch handles it automatically!
 - [ ] Verified with `cargo build && cargo test`
 

docs/WORKTREES.md

@@ -0,0 +1,51 @@
+# Using code_search with Git Worktrees
+
+Each worktree must have its own local database. The tool uses an embedded
+RocksDB which only allows one process to hold the lock at a time — if multiple
+worktrees share the global `~/.code_search/surrealdb.rocksdb` you will get:
+
+```
+Error: "Failed to connect to SurrealDB: IO error: While lock file: LOCK:
+Resource temporarily unavailable"
+```
+
+## Setup per worktree
+
+Run this once in each worktree root:
+
+```sh
+mix compile
+ex_ast --output /tmp/call_graph.json
+code_search setup
+code_search code import --file /tmp/call_graph.json
+rm /tmp/call_graph.json
+```
+
+`code_search setup` creates `.code_search/surrealdb.rocksdb` in the current
+directory. The tool's path resolution always prefers a local `.code_search/`
+over the global `~/.code_search/`, so each worktree gets its own isolated
+database and lock file.
+
+## Rebuilding a stale or corrupt database
+
+If you see a "record already exists" or lock error on a worktree that already
+has a local DB:
+
+```sh
+rm -rf .code_search/surrealdb.rocksdb
+mix compile
+ex_ast --output /tmp/call_graph.json
+code_search setup
+code_search code import --file /tmp/call_graph.json
+rm /tmp/call_graph.json
+```
+
+## Important notes
+
+- Never rely on `~/.code_search/surrealdb.rocksdb` in a multi-worktree setup
+- Two processes cannot share the same RocksDB — this is an embedded database
+  limitation, not a bug in code_search
+- Each worktree's `.code_search/` should be in `.gitignore` (it is by default)
+- The git hook installed via `code_search setup --install-hooks` handles
+  incremental updates automatically after each commit, so you only need to do
+  the full import once per worktree

templates/agents/code-search-explorer.md

@@ -20,11 +20,11 @@ You are an expert Elixir/Erlang codebase explorer powered by the `code_search` C
 When asked to explore a codebase:
 
 1. **Identify the query type**:
-   - Finding definitions → Use `code_search location` or `code_search function`
-   - Understanding calls → Use `code_search calls-from` or `code_search calls-to`
-   - Tracing paths → Use `code_search trace` or `code_search reverse-trace`
-   - Module analysis → Use `code_search browse-module` or `code_search depends-on`
-   - Quality checks → Use `code_search unused`, `code_search hotspots`, etc.
+   - Finding definitions → Use `code_search code location` or `code_search code function`
+   - Understanding calls → Use `code_search code calls-from` or `code_search code calls-to`
+   - Tracing paths → Use `code_search code trace` or `code_search code reverse-trace`
+   - Module analysis → Use `code_search code browse-module` or `code_search code depends-on`
+   - Quality checks → Use `code_search code unused`, `code_search code hotspots`, etc.
 
 2. **Execute queries efficiently**:
    - Always use `--format toon` for token-efficient output
@@ -52,7 +52,7 @@ The database is automatically searched in:
 
 Override if needed:
 ```bash
-code_search --db /path/to/db.rocksdb <command>
+code_search --db /path/to/db.rocksdb code <command>
 ```
 
 ## Example Workflow
@@ -61,17 +61,17 @@ When user asks: "Where is the authenticate function defined and what calls it?"
 
 1. Find definition:
 ```bash
-code_search --format toon location authenticate
+code_search --format toon code location authenticate
 ```
 
 2. Find callers:
 ```bash
-code_search --format toon calls-to --function authenticate
+code_search --format toon code calls-to --function authenticate
 ```
 
 3. If results show a specific module, explore it:
 ```bash
-code_search --format toon browse-module AuthModule
+code_search --format toon code browse-module AuthModule
 ```
 
 4. Read source for context:
@@ -83,17 +83,17 @@ code_search --format toon browse-module AuthModule
 
 | Task | Command |
 |------|---------|
-| Find function | `code_search --format toon location <name>` |
-| Browse module | `code_search --format toon browse-module <module>` |
-| What calls X? | `code_search --format toon calls-to --function <name>` |
-| What does X call? | `code_search --format toon calls-from <module> <function>` |
-| Trace execution | `code_search --format toon trace <module> <function> --depth N` |
-| Find path A→B | `code_search --format toon path --from-module A --to-module B` |
-| Module deps | `code_search --format toon depends-on <module>` |
-| Who depends on X? | `code_search --format toon depended-by <module>` |
-| Unused code | `code_search --format toon unused` |
-| Hotspots | `code_search --format toon hotspots --kind incoming` |
-| Code smells | `code_search --format toon god-modules`, `complexity`, etc. |
+| Find function | `code_search --format toon code location <name>` |
+| Browse module | `code_search --format toon code browse-module <module>` |
+| What calls X? | `code_search --format toon code calls-to --function <name>` |
+| What does X call? | `code_search --format toon code calls-from <module> <function>` |
+| Trace execution | `code_search --format toon code trace <module> <function> --depth N` |
+| Find path A→B | `code_search --format toon code path --from-module A --to-module B` |
+| Module deps | `code_search --format toon code depends-on <module>` |
+| Who depends on X? | `code_search --format toon code depended-by <module>` |
+| Unused code | `code_search --format toon code unused` |
+| Hotspots | `code_search --format toon code hotspots --kind incoming` |
+| Code smells | `code_search --format toon code god-modules`, `complexity`, etc. |
 
 ## Important Notes
 

templates/hooks/post-commit

@@ -6,7 +6,7 @@
 # from the last commit. It:
 # 1. Ensures the project is compiled with debug info
 # 2. Extracts AST data for changed files using ex_ast --git-diff
-# 3. Imports the data into the database using code_search import
+# 3. Imports the data into the database using code_search code import
 #
 # Installation:
 #   cp hooks/post-commit .git/hooks/post-commit
@@ -105,7 +105,7 @@ fi
 # Database path will be auto-resolved to .code_search/surrealdb.rocksdb
 info "Importing data..."
 
-if code_search import --file "${TEMP_JSON}" 2>&1; then
+if code_search code import --file "${TEMP_JSON}" 2>&1; then
     info "Database updated successfully!"
 else
     error "Database import failed"

templates/skills/accepts/SKILL.md

@@ -14,7 +14,7 @@ Find functions that take certain types as input parameters. Use this to understa
 ## Usage
 
 ```bash
-code_search --format toon accepts <PATTERN> [MODULE] [OPTIONS]
+code_search --format toon code accepts <PATTERN> [MODULE] [OPTIONS]
 ```
 
 ## Arguments
@@ -34,10 +34,10 @@ code_search --format toon accepts <PATTERN> [MODULE] [OPTIONS]
 ## Examples
 
 ```bash
-code_search accepts "User.t"              # Find functions accepting User.t
-code_search accepts "map()"               # Find functions accepting maps
-code_search accepts "User.t" MyApp        # Filter to module MyApp
-code_search accepts -r "list\(.*\)"       # Regex pattern matching
+code_search code accepts "User.t"              # Find functions accepting User.t
+code_search code accepts "map()"               # Find functions accepting maps
+code_search code accepts "User.t" MyApp        # Filter to module MyApp
+code_search code accepts -r "list\(.*\)"       # Regex pattern matching
 ```
 
 ## Output Fields (toon format)

templates/skills/boundaries/SKILL.md

@@ -14,7 +14,7 @@ Identify modules that act as architectural boundaries - modules that are heavily
 ## Usage
 
 ```bash
-code_search --format toon boundaries [MODULE] [OPTIONS]
+code_search --format toon code boundaries [MODULE] [OPTIONS]
 ```
 
 ## Arguments
@@ -35,11 +35,11 @@ code_search --format toon boundaries [MODULE] [OPTIONS]
 ## Examples
 
 ```bash
-code_search boundaries                          # Find all boundary modules
-code_search boundaries MyApp.Web                # Filter to MyApp.Web namespace
-code_search boundaries --min-incoming 5         # With minimum 5 incoming calls
-code_search boundaries --min-ratio 2.0          # With minimum 2.0 ratio
-code_search boundaries -l 20                    # Show top 20 boundary modules
+code_search code boundaries                          # Find all boundary modules
+code_search code boundaries MyApp.Web                # Filter to MyApp.Web namespace
+code_search code boundaries --min-incoming 5         # With minimum 5 incoming calls
+code_search code boundaries --min-ratio 2.0          # With minimum 2.0 ratio
+code_search code boundaries -l 20                    # Show top 20 boundary modules
 ```
 
 ## Output Fields (toon format)