docs: search-index lock-acquisition order and threading model

[clean6378-max-it]

Summary

• Document the four search-index locks, permitted nesting contract, and FTS pointer-swap threading model in docs/architecture.md.
• Add a Deployment — WSGI workers note in README.md warning against multi-worker Gunicorn/uWSGI on a shared index directory; point to single-worker or CLAUDE_CODE_CHAT_BROWSER_NO_SEARCH_INDEX=1.

Docs-only (Week 30 item #6); defines the invariant for the follow-up concurrency suite (item #7).

Test plan

• Reviewed lock usage against utils/search_index.py (lines 57–63, 187–219, 521, 641–693)
• CI green (ruff, pytest, link checks as applicable)
• Reviewer confirms lock contract matches intended concurrency test assertions

Summary by CodeRabbit

• Documentation
  • Added a new “Deployment: WSGI workers” guide describing how the search index, cache, and locks behave per process, including warnings about nondeterministic freshness and fallback behavior with multiple workers.
  • Updated GET /api/search?q=... documentation to reflect SQLite FTS5 querying when available, with a live JSONL scan fallback when the index is missing, stale, or temporarily locked.
  • Expanded architecture notes on index rebuild/publish flow, locking/threading expectations, and how to disable FTS index building/querying via CLAUDE_CODE_CHAT_BROWSER_NO_SEARCH_INDEX=1.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Documents /api/search FTS5 index usage, live-scan fallback behavior, index lifecycle and locking, and single-worker WSGI deployment guidance.

Changes

FTS search documentation

Layer / File(s)	Summary
Search index behavior and fallback docs/architecture.md	Documents local FTS5 querying with live JSONL-scan fallback when the index is unavailable, stale, or locked.
Search index lifecycle and deployment docs/architecture.md, README.md	Documents index storage, atomic publication, lock coordination, threading contracts, per-process cache scope, and single-worker WSGI configuration.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related issues

• Issue cppalliance/claude-code-chat-browser#135 — Covers the documented search-index threading, locking, atomic publication, and single-worker WSGI deployment constraints.

Possibly related PRs

• cppalliance/claude-code-chat-browser#120 — Introduced the FTS5 search-index behavior and environment configuration documented here.

Suggested reviewers: timon0305

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main documentation change about search-index locking order and threading behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/search-index-lock-order

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture.md`:
- Line 156: Update the Publish description for _publish_active_index so it does
not claim unconditional atomic pointer replacement; explicitly mention the
pointer.write_text fallback and qualify the reader guarantee to acknowledge
possible incomplete pointers, or remove that fallback from the implementation if
atomic publication is required.
- Line 158: Update the architecture documentation to distinguish rebuild
isolation from index_locked classification: explain that rebuilding a new SQLite
file does not normally lock the old active database, while query_index_hits
still classifies sqlite3.OperationalError as index_locked for fallback handling.
Avoid implying that rebuild concurrency inherently causes the error, and clarify
this distinction for follow-up tests.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 315eb35c-5452-4512-8803-b4baaaa035be

📥 Commits

Reviewing files that changed from the base of the PR and between 0c43bd7 and e4d8f3c.

📒 Files selected for processing (2)

• README.md
• docs/architecture.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Line 84: Update the README guidance for
CLAUDE_CODE_CHAT_BROWSER_NO_SEARCH_INDEX so it states that disabling the index
avoids using or building index files, rather than implying that existing index
files are removed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9b567a1f-22b7-4ca1-ac0c-47b5289233d3

📥 Commits

Reviewing files that changed from the base of the PR and between e4d8f3c and 10e6b86.

📒 Files selected for processing (2)

• README.md
• docs/architecture.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/architecture.md