feat: add multi-folder indexing with dynamic add/remove capabilities

docs/user-guide/cli-reference.md

@@ -16,6 +16,10 @@ Available for all commands:
 |---------|-------------|
 | `codanna init` | Set up .codanna directory with default configuration |
 | `codanna index` | Build searchable index from codebase |
+| `codanna add-folder` | Add a folder to be indexed |
+| `codanna remove-folder` | Remove a folder from indexed paths |
+| `codanna list-folders` | List all folders that are being indexed |
+| `codanna clean` | Remove symbols from folders no longer in indexed paths |
 | `codanna retrieve` | Query symbols, relationships, and dependencies |
 | `codanna serve` | Start MCP server |
 | `codanna config` | Display active settings |
@@ -33,11 +37,12 @@ Set up .codanna directory with default configuration
 **Options:**
 - `-f, --force` - Force overwrite existing configuration
 
-`codanna index <PATH>`
+`codanna index [PATHS...]`
 Build searchable index from codebase
 
 **Arguments:**
-- `<PATH>` - Path to file or directory to index
+- `[PATHS...]` - Paths to files or directories to index (multiple paths allowed)
+- If no paths provided, uses `indexed_paths` from configuration (must be configured via `add-folder`)
 
 **Options:**
 - `-t, --threads <THREADS>` - Number of threads to use (overrides config)
@@ -46,6 +51,118 @@ Build searchable index from codebase
 - `--dry-run` - Dry run - show what would be indexed without indexing
 - `--max-files <MAX_FILES>` - Maximum number of files to index
 
+**Examples:**
+```bash
+# Index a single directory
+codanna index src --progress
+
+# Index multiple directories at once
+codanna index src lib tests --progress
+
+# Use configured indexed paths
+codanna index --progress
+```
+
+**Behavior:**
+- Accepts multiple paths for indexing in a single operation
+- When run without arguments, uses folders from `indexed_paths` configuration
+- Automatically cleans up symbols from removed folders when using configuration
+- Backward compatible with single-path usage
+
+`codanna add-folder <PATH>`
+Add a folder to the indexed paths list
+
+**Arguments:**
+- `<PATH>` - Path to folder to add
+
+**Examples:**
+```bash
+# Add a folder to be indexed
+codanna add-folder /path/to/project
+
+# Add multiple folders
+codanna add-folder src
+codanna add-folder lib
+codanna add-folder tests
+```
+
+**Behavior:**
+- Adds folder to `indexed_paths` in configuration
+- Saves configuration to `.codanna/settings.toml`
+- Paths are canonicalized to absolute paths
+- Prevents duplicate entries
+- Does not automatically index the folder (run `codanna index` after)
+
+`codanna remove-folder <PATH>`
+Remove a folder from the indexed paths list
+
+**Arguments:**
+- `<PATH>` - Path to folder to remove
+
+**Examples:**
+```bash
+# Remove a folder from indexed paths
+codanna remove-folder /path/to/old-project
+
+# Remove by relative path (will be canonicalized)
+codanna remove-folder tests
+```
+
+**Behavior:**
+- Removes folder from `indexed_paths` in configuration
+- Saves configuration to `.codanna/settings.toml`
+- Does not automatically clean symbols (run `codanna clean` or `codanna index` after)
+- Path must exist in configuration or error is returned
+
+`codanna list-folders`
+List all folders that are being indexed
+
+**Examples:**
+```bash
+# List all indexed folders
+codanna list-folders
+```
+
+**Output:**
+```
+Indexed folders:
+  - /path/to/project1
+  - /path/to/project2
+  - /path/to/project3
+```
+
+Or if none configured:
+```
+Indexed folders:
+  (none configured)
+
+To add folders: codanna add-folder <path>
+```
+
+**Behavior:**
+- Displays all folders in `indexed_paths` configuration
+- Shows helpful message if empty
+- Useful for verifying configuration state
+
+`codanna clean`
+Remove symbols from folders no longer in indexed paths
+
+**Examples:**
+```bash
+# Clean up symbols from removed folders
+codanna clean
+```
+
+**Behavior:**
+- Compares current `indexed_paths` with files in index
+- Removes symbols from files not under any configured folder
+- Reports number of files cleaned
+- Saves updated index
+- Safe to run multiple times (idempotent)
+- Requires `indexed_paths` to be configured
+
+**Note:** Running `codanna index` automatically performs cleanup, so this command is optional in most workflows.
+
 `codanna retrieve <SUBCOMMAND>`
 Query indexed symbols, relationships, and dependencies
 

docs/user-guide/configuration.md

@@ -112,6 +112,109 @@ threads = 8  # Number of threads for parallel indexing
 max_file_size_mb = 10  # Skip files larger than this
 ```
 
+## Multi-Folder Indexing
+
+Index multiple directories simultaneously with persistent configuration.
+
+### Configuration
+
+```toml
+[indexing]
+indexed_paths = [
+    "/absolute/path/to/project1",
+    "/absolute/path/to/project2",
+    "/absolute/path/to/project3"
+]
+```
+
+### Managing Indexed Folders
+
+**Add folders:**
+```bash
+# Add individual folders
+codanna add-folder /path/to/project1
+codanna add-folder /path/to/project2
+
+# Or use relative paths (will be converted to absolute)
+codanna add-folder src
+codanna add-folder lib
+```
+
+**List configured folders:**
+```bash
+codanna list-folders
+```
+
+**Remove a folder:**
+```bash
+codanna remove-folder /path/to/project1
+```
+
+**Clean up symbols from removed folders:**
+```bash
+codanna clean
+```
+
+### Usage Examples
+
+**Multi-project workspace:**
+```bash
+# Configure folders
+codanna add-folder ~/workspace/project-api
+codanna add-folder ~/workspace/project-web
+codanna add-folder ~/workspace/shared-lib
+
+# Index all configured folders
+codanna index --progress
+```
+
+**Monorepo support:**
+```bash
+# Index specific packages
+codanna add-folder packages/backend
+codanna add-folder packages/frontend
+codanna add-folder packages/shared
+codanna index --progress
+```
+
+**Selective indexing:**
+```bash
+# Index only specific directories
+codanna index src lib tests --progress
+
+# Or configure for repeated indexing
+codanna add-folder src
+codanna add-folder lib
+codanna index --progress  # Uses configured paths
+```
+
+### Behavior
+
+**Default behavior:**
+- If no `indexed_paths` configured, `codanna index` requires explicit path arguments (backward compatible)
+- Paths are stored as canonical absolute paths
+- Duplicate paths are automatically prevented
+
+**Automatic cleanup:**
+- Running `codanna index` without arguments uses configured paths
+- Automatically removes symbols from folders no longer in configuration
+- Manual cleanup available via `codanna clean` command
+
+**Path canonicalization:**
+- Relative paths are converted to absolute
+- Symlinks are resolved to actual paths
+- Prevents duplicate entries for the same folder
+
+### Use Cases
+
+**Multi-project workspaces** - Index multiple related projects together for cross-project symbol resolution
+
+**Monorepo support** - Index different components separately while maintaining cross-references
+
+**Selective indexing** - Only index specific directories within large codebases
+
+**Dynamic workflows** - Add and remove folders as your project structure changes
+
 ## Ignore Patterns
 
 Codanna respects `.gitignore` and adds its own `.codannaignore`: