From ce8b6e310813ee29dac67e81184f5a27fa5c9d27 Mon Sep 17 00:00:00 2001 From: lbruton Date: Thu, 29 Oct 2026 08:06:29 -0500 Subject: [PATCH] chore: document project scope in README and Overview SESF-64 resolves project_root against indexed roots (paths with subfolders and worktrees, folder names, '*') and prints a Scope line. The Overview still said a path filter returned empty. Also note that Desktop Code-tab, Desktop chat and Codex send no X-Project-Root (SESF-83). --- DocVault/Overview.md | 3 ++- README.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/DocVault/Overview.md b/DocVault/Overview.md index 8379162..7552757 100644 --- a/DocVault/Overview.md +++ b/DocVault/Overview.md @@ -55,7 +55,8 @@ Hosted/OpenAI embeddings are **explicitly deferred**. Embedding stays local MLX ## Operational Notes - Embedding model is downloaded via `download-model.sh` — EmbeddingGemma local on Apple Silicon (MLX Metal). -- **Gotcha:** `search_all_sessions` silently returns empty when a `project_root` filesystem path is passed. Omit the filter or pass `"*"`. +- **Project scope:** `project_root` takes a path (its indexed subfolders and worktrees are included), a folder name such as `CoWork`, or `"*"`. A name or path with no indexed turns searches every project. Search and stats output opens with a `Scope:` line that names the roots and the reason. +- **Gotcha:** Claude desktop Code-tab sessions, Desktop chat and Codex send no `X-Project-Root` header, so their searches default to every project. Pass `project_root` explicitly from those clients. - **MLX Metal SIGSEGV under sustained load** — EmbeddingGemma crashes the GPU driver after ~50min continuous compute. Backfill throttle is 200ms between inserts; do not drop below 100ms. - **FTS schema migration** writes a sentinel and emits a `WARNING` log line while the keyword index rebuilds — expected, not an error. - **LaunchAgent (optional):** `cc.lbruton.sessionflow` user agent autostarts the server at login. Disable via `launchctl unload` if running ad-hoc. diff --git a/README.md b/README.md index 61ece9e..d9729ff 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ SessionFlow HTTP server (SESSIONFLOW_PORT, default 7102) | Tool | Returns | |------|---------| | `search_session` | Turns that match a query, scoped to the current project. Omit `query` to list recent turns. | -| `search_all_sessions` | Turns that match a query, with `project_root`, `git_branch`, `provider`, `date_from`, `date_to` and `issue_id` filters. | +| `search_all_sessions` | Turns that match a query, with `project_root`, `git_branch`, `provider`, `date_from`, `date_to` and `issue_id` filters. `project_root` takes a path, a folder name such as `CoWork`, or `"*"`. | | `get_turns` | The turns around one turn of a session. Requires `session_id` and `turn_index` from a search result. | | `get_session_stats` | Turn, session, branch and provider counts for the index. | | `get_issue_timeline` | Every turn that mentions an issue ID, oldest first. Requires `issue_id`. |