docs: clarify multi-worktree index scope workflow

README.md

@@ -117,6 +117,59 @@ sia-code config set search.vector_weight 0.0
 
 Note: backend selection is auto by default (`sqlite-vec` for new indexes, legacy `usearch` supported).
 
+## Multi-Worktree / Multi-Agent Setup
+
+Yes - Sia Code works with multiple git worktrees and multiple LLM CLI instances.
+
+Scope resolution order:
+
+1. `SIA_CODE_INDEX_DIR` (explicit path override)
+2. `SIA_CODE_INDEX_SCOPE` (`shared`, `worktree`, or `auto`)
+3. `auto` fallback:
+   - linked worktree -> shared index at `<git-common-dir>/sia-code`
+   - normal checkout -> local `.sia-code`
+
+```bash
+# Shared index across worktrees/agents
+export SIA_CODE_INDEX_SCOPE=shared
+
+# Isolated index per worktree
+export SIA_CODE_INDEX_SCOPE=worktree
+
+# Full explicit control
+export SIA_CODE_INDEX_DIR=/absolute/path/to/sia-index
+```
+
+Typical worktree workflow:
+
+```bash
+# in main checkout (build shared index once)
+export SIA_CODE_INDEX_SCOPE=shared
+sia-code init
+sia-code index .
+
+# create feature worktree
+git worktree add ../feat-auth feat/auth
+cd ../feat-auth
+
+# reuse same shared index, then incrementally refresh
+sia-code status
+sia-code index --update
+```
+
+When a worktree is merged/removed:
+
+- `shared` scope: index stays in git common dir and remains usable
+- `worktree` scope: index lives in that worktree directory and is removed with it
+- after merge, run `sia-code index --update` in the remaining checkout
+
+Practical guidance:
+
+- Many readers/searchers are fine in shared mode
+- Prefer one active index writer per shared index
+- For strict branch/agent isolation, use `worktree`
+- Teams on different machines should keep local indexes and sync context via git + `sia-code memory sync-git`
+
 ## Documentation
 
 - `docs/CLI_FEATURES.md` - concise CLI command reference

docs/INDEXING.md

@@ -17,6 +17,25 @@ sia-code index .
 | Parallel | `sia-code index --parallel --workers 8` | Large repos |
 | Watch | `sia-code index --watch --debounce 2.0` | Continuous local development |
 
+## Worktrees and Multiple Agent Sessions
+
+Sia Code supports git worktrees and parallel LLM CLI sessions.
+
+- Auto behavior in linked worktrees: shared index at `<git-common-dir>/sia-code`
+- Override behavior with env vars:
+
+```bash
+export SIA_CODE_INDEX_SCOPE=shared   # share one index across worktrees
+export SIA_CODE_INDEX_SCOPE=worktree # per-worktree .sia-code
+export SIA_CODE_INDEX_DIR=/absolute/path/to/sia-index
+```
+
+Practical guidance:
+
+- Many concurrent readers/searchers are fine
+- For indexing, prefer one writer at a time on the same shared index
+- If you need hard isolation per agent, use `SIA_CODE_INDEX_SCOPE=worktree`
+
 ## What gets indexed
 
 - Code files for supported languages

docs/LLM_CLI_INTEGRATION.md

@@ -45,6 +45,30 @@ uvx sia-code memory search "topic"
 uvx sia-code memory add-decision "Decision title" -d "Context" -r "Reason"
 ```
 
+## 5) Multiple worktrees / multiple Claude Code instances
+
+Use one of these index strategies per session:
+
+```bash
+# Shared index across worktrees/instances (best for reuse)
+export SIA_CODE_INDEX_SCOPE=shared
+
+# Isolated index per worktree/instance
+export SIA_CODE_INDEX_SCOPE=worktree
+```
+
+If you need full control, set an explicit directory:
+
+```bash
+export SIA_CODE_INDEX_DIR=/absolute/path/to/sia-index
+```
+
+Recommendation:
+
+- Shared mode for many search/read sessions
+- Worktree mode when you want strict isolation per branch/agent
+- For shared mode, avoid many simultaneous index writers
+
 ## Notes
 
 - Keep the skill file short and practical for agent speed.