docs: add ReadTheDocs MkDocs scaffold

.github/workflows/build-reusable.yml

@@ -659,14 +659,36 @@ jobs:
         run: |
           source .venv/bin/activate || source .venv/Scripts/activate
           python - <<'PY'
+          import numpy as np
           import leann
           import leann_backend_hnsw as h
           import leann_backend_diskann as d
           import leann_backend_ivf as ivf
           from leann import LeannBuilder, LeannSearcher
-          b = LeannBuilder(backend_name="hnsw")
+
+          b = LeannBuilder(
+              backend_name="hnsw",
+              dimensions=2,
+              is_compact=False,
+              is_recompute=False,
+          )
           b.add_text("hello arch")
-          b.build_index("arch_demo.leann")
-          s = LeannSearcher("arch_demo.leann")
-          print("search:", s.search("hello", top_k=1))
+          b.build_index_from_arrays(
+              "arch_demo.leann",
+              ["0"],
+              np.asarray([[1.0, 0.0]], dtype=np.float32),
+          )
+
+          with LeannSearcher(
+              "arch_demo.leann",
+              recompute_embeddings=False,
+              enable_warmup=False,
+          ) as s:
+              s.backend_impl.compute_query_embedding = lambda *args, **kwargs: np.asarray(
+                  [[1.0, 0.0]], dtype=np.float32
+              )
+              result = s.search("hello", top_k=1)
+
+          assert result and result[0].text == "hello arch"
+          print("arch smoke ok")
           PY

.github/workflows/docs-build.yml

@@ -0,0 +1,28 @@
+name: Docs Build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  mkdocs:
+    name: MkDocs Strict Build
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install documentation dependencies
+        run: python -m pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: python -m mkdocs build --strict --config-file mkdocs.yml

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -1110,7 +1110,10 @@ leann ask my-docs "Where are prompts configured?"
 # Detect file changes since last build/watch checkpoint
 leann watch my-docs
 
-# List all your indexes
+# Keep an index current as files are saved
+leann watch my-docs --live
+
+# List discoverable indexes
 leann list
 
 # Remove an index
@@ -1152,23 +1155,27 @@ leann search INDEX_NAME QUERY [OPTIONS]
 Options:
   --top-k N                     Number of results (default: 5)
   --complexity N                Search complexity (default: 64)
+  --max-depth N                 Maximum app-index discovery depth (default: 4)
   --recompute / --no-recompute  Enable/disable embedding recomputation (default: enabled). Should not do a `no-recompute` search in a `recompute` build.
   --pruning-strategy {global,local,proportional}
 ```
 
 **Watch Command:**
 ```bash
-leann watch INDEX_NAME
+leann watch INDEX_NAME [OPTIONS]
 
 # Compares the current file system state against the last checkpoint (Merkle tree snapshot)
-# and reports which files have been added, removed, or modified, along with their chunk IDs.
+# and updates the index when files have been added, removed, or modified.
 #
-# - Automatically saves a new checkpoint after detecting changes
+# - Use --once --dry-run to report changes without updating the index
+# - Use --live to wake updates from filesystem events instead of the polling interval
+# - --debounce-ms controls live event batching (default: 500)
+# - Automatically saves a new checkpoint after successful index updates
 # - Each subsequent run compares against the most recent checkpoint
 # - File change detection uses SHA-256 content hashing via a Merkle tree
 #
 # Example output:
-#   === Changes since last checkpoint ===
+#   === Changes detected ===
 #   modified (1):
 #     - /path/to/file.py
 #       chunks: 42, 43, 44
@@ -1187,24 +1194,34 @@ Options:
 
 **List Command:**
 ```bash
-leann list
+leann list [OPTIONS]
+
+Options:
+  --max-depth N                 Maximum app-index discovery depth (default: 4)
 
-# Lists all indexes across all projects with status indicators:
+# Lists discoverable indexes from the current project and registered project roots:
 # ✅ - Index is complete and ready to use
 # ❌ - Index is incomplete or corrupted
 # 📁 - CLI-created index (in .leann/indexes/)
 # 📄 - App-created index (*.leann.meta.json files)
+#
+# App-created index discovery is bounded and skips heavyweight directories
+# such as .git, node_modules, virtualenvs, build/cache folders, and directory symlinks.
+#
+# Commands that resolve app-created indexes by name also accept --max-depth,
+# including search, watch, rebuild, migrate-ids, warmup, daemon, and react.
 ```
 
 **Remove Command:**
 ```bash
 leann remove INDEX_NAME [OPTIONS]
 
 Options:
-  --force, -f    Force removal without confirmation
+  --force, -f                    Force removal without confirmation
+  --max-depth N                  Maximum app-index discovery depth (default: 4)
 
 # Smart removal: automatically finds and safely removes indexes
-# - Shows all matching indexes across projects
+# - Shows all bounded matching indexes across registered projects
 # - Requires confirmation for cross-project removal
 # - Interactive selection when multiple matches found
 # - Supports both CLI and app-created indexes
@@ -1272,6 +1289,9 @@ results = searcher.search("banana‑crocodile", use_grep=True, top_k=1)
 
 ## Benchmarks
 
+For the current benchmark inventory and reporting template, see the
+[Benchmark Guide](docs/benchmarks.md).
+
 **[DiskANN vs HNSW Performance Comparison →](benchmarks/diskann_vs_hnsw_speed_comparison.py)** - Compare search performance between both backends
 
 **[Simple Example: Compare LEANN vs FAISS →](benchmarks/compare_faiss_vs_leann.py)** - See storage savings in action