Dev

.env.example

@@ -49,6 +49,11 @@ OPENAI_API_KEY=
 OPENAI_CHAT_MODEL=
 OPENAI_EMBED_MODEL=
 OPENAI_VISION_MODEL=
+# Fixed dimension for embedding vectors from MRL-capable embedding models
+# (e.g. Qwen3 via OpenRouter). Must match the dimension the Chroma collection
+# was created with — changing it requires re-creating the collection. Leave
+# empty to use the model's native output dimension.
+OPENAI_EMBED_DIMENSIONS=
 # Optional output limit for streamed chat answers. When a reasoning budget is
 # enabled, this value must be greater than OPENAI_REASONING_MAX_TOKENS.
 OPENAI_MAX_TOKENS=
@@ -61,6 +66,15 @@ OPENAI_REASONING_MAX_TOKENS=
 # Set to 1 to log each agent's reasoning step (LLM text + tool calls) to stderr.
 # AGENT_DEBUG=0
 
+# --- prompt-injection fence (onboarding buddy) ---
+# Every user message the buddy sees is wrapped in an HMAC marker; the key is
+# drawn per process unless FENCE_KEY is set. A deployment with more than one
+# worker or replica must set the same FENCE_KEY everywhere — with different
+# keys, each process fences the same text into different bytes, so prompt
+# caching stops matching across processes (still safe, just slower). Any
+# sufficiently random string; it is hashed to the key.
+FENCE_KEY=
+
 # --- ingestion settings ---
 # INGEST_CONCURRENCY=8
 # INGEST_MAX_CONTENT_LENGTH=500000

.gitignore

@@ -222,4 +222,8 @@ __marimo__/
 
 data/
 
-opencode.json
+opencode.json
+
+# Hermes agent working files (per-developer)
+.worktrees/
+.worktreeinclude

AGENT.md

@@ -37,25 +37,25 @@ Run lint + type-check + tests before considering a change done.
 `src/` layout, by subpackage:
 
 - **`api/`** — FastAPI app (`app.py`), DI (`dependencies.py`), `schemas.py`,
-  and routes: `health`, `ingest`, `chat`, `title`, `vector_db`, plus
+  and routes: `health`, `ingest`, `buddy`, `title`, `vector_db`, plus
   `onboarding` and `blueprints` (from #98).
-- **`agents/`** — `ChatAgent` (`chat_agent.py`) runs one flat tool loop over a
-  single message list, capped by `_MAX_STEPS`: it searches while the model
-  asks for searches, then streams the answer from that same conversation.
-  Tool results carry the retrieved text, so the loop that searched is also the
-  loop that answers — there is no separate gather and answer phase.
-  `ChatOrchestrator` (`orchestrator.py`) maps the run's events into the SSE
-  stream consumed by `/api/v1/chat`. Tools live in `agents/tools/`, registered
-  via `ToolRegistry`.
+- **`agents/`** — the buddy's tool-loop building blocks: tools live in
+  `agents/tools/` (retrieval, grep, evidence helpers), registered via
+  `ToolRegistry`, and `artifact_summary.py` backs the summaries endpoint. The
+  conversation engine itself is `onboarding/buddy_agent.py`: one flat tool
+  loop over a single message list, capped by `_MAX_STEPS` — it searches while
+  the model asks for searches, then answers from that same conversation. Tool
+  results carry the retrieved text, so the loop that searched is also the loop
+  that answers — there is no separate gather and answer phase.
 - **`ingestion/`** — per-filetype parsers (`text_parser`, `pdf_parser`,
   `code_parser`, `image_parser`) behind `parser.py`, then `chunker.py` and
   `metadata_store.py`.
 - **`rag/`** — `retriever.py`, `hybrid.py` (BM25 + vector hybrid retrieval),
   `citation.py`, `prompt.py`.
 - **`llm/`** — `LLMClient` interface (`base.py`), implemented by
   `ollama_client.py`, `openai_client.py`, `anthropic_client.py`.
-  `split_client.py` lets chat and embeddings use different backends
-  (`LLM_BACKEND` for chat/generate/vision, `EMBED_BACKEND` for embeddings).
+  `split_client.py` lets generation and embeddings use different backends
+  (`LLM_BACKEND` for generate/chat/vision, `EMBED_BACKEND` for embeddings).
   Every backend takes a request timeout (`LLM_TIMEOUT_SECONDS`, default 600).
   The Anthropic client sets prompt-cache breakpoints on the system prompt and
   the last message — see `anthropic_client._user_message` before changing how
@@ -79,15 +79,15 @@ Run lint + type-check + tests before considering a change done.
 - Don't assume Ollama-only: check `llm/base.py`'s `LLMClient` interface when
   touching anything that calls an LLM, since backend is configurable per
   deployment (`LLM_BACKEND` / `EMBED_BACKEND`).
-- Chat is one agent running one loop. Extend it with a new `Tool` in
+- The buddy is one agent running one loop. Extend it with a new `Tool` in
   `agents/tools/` rather than a sub-agent to delegate to: every tier costs a
   serialized round-trip ahead of the user's first token, which is what the
   previous orchestrator/synthesis split cost. Tool results must carry their
   chunk text — a count-only summary forces a second pass to write the answer.
 - **Tools must be read-only and thread-safe.** A turn's tool calls run
-  concurrently (`ChatAgent._run_tools`), so a tool that mutates shared state
-  would race. Anything cached across calls needs its own lock, the way
-  `rag.hybrid.BM25IndexCache` guards its rebuild.
+  concurrently (`agents.tools.base.run_tool_calls`), so a tool that mutates
+  shared state would race. Anything cached across calls needs its own lock,
+  the way `rag.hybrid.BM25IndexCache` guards its rebuild.
 - `AGENT_DEBUG=1` logs each agent's reasoning (LLM text + tool calls) to
   stderr — useful when debugging agent behavior.
 - The onboarding pipeline is intentionally deterministic/staged rather than

AGENTS.md

@@ -43,20 +43,22 @@ triggers Docker image publish to `ghcr.io/sprintstartproject/sprintstart-ai`.
 
 - **`api/`** — FastAPI app (`app.py`), DI (`dependencies.py`), `schemas.py`,
   SSE helpers (`sse.py`), and route modules under `routes/`.
-- **`agents/`** — `ChatAgent` (`chat_agent.py`) runs one flat tool loop over a
-  single message list: it searches while the model asks, then streams the
-  answer from that same conversation. Tool results carry the retrieved text,
-  so the loop that searched is the loop that answers. Tools live in
-  `agents/tools/`, registered via `ToolRegistry`. `ChatOrchestrator`
-  (`orchestrator.py`) maps the run's events to SSE for `/api/v1/chat`.
+- **`agents/`** — the buddy's tool-loop building blocks: tools live in
+  `agents/tools/` (retrieval, grep, evidence helpers), registered via
+  `ToolRegistry`, and `artifact_summary.py` backs the summaries endpoint. The
+  conversation engine itself is `onboarding/buddy_agent.py`
+  (`run_agent_turn`): one flat tool loop over a single message list — it
+  searches while the model asks, then answers from that same conversation.
+  Tool results carry the retrieved text, so the loop that searched is the
+  loop that answers. `api/routes/buddy.py` serves it.
 - **`ingestion/`** — Per-filetype parsers (`text_parser`, `pdf_parser`,
   `code_parser`, `image_parser`) behind `parser.py`, then `chunker.py` and
   `metadata_store.py`.
 - **`rag/`** — `retriever.py`, `hybrid.py` (BM25 + vector hybrid retrieval
   with RRF fusion), `citation.py`, `prompt.py`.
 - **`llm/`** — `LLMClient` protocol (`base.py`) with implementations:
   `ollama_client.py`, `openai_client.py`, `anthropic_client.py`.
-  `SplitLLMClient` lets chat and embeddings use different backends
+  `SplitLLMClient` lets generation and embeddings use different backends
   (`LLM_BACKEND` vs `EMBED_BACKEND`). All three take a request timeout
   (`LLM_TIMEOUT_SECONDS`, default 600). The Anthropic client sets
   prompt-cache breakpoints; caching matches on exact bytes, so read
@@ -76,10 +78,14 @@ scoping is **fail-closed** — a chunk with no project association is invisible
 to all projects rather than visible to all of them. When touching retrieval,
 ingest, or an endpoint, keep that property:
 
-- `project_id` is required on `ChatRequest`, `OnboardingPathRequest`,
+- `project_id` is required on `OnboardingPathRequest`,
   `GenerateBlueprintsRequest`, `KnowledgeGapsRequest` and `FaqGroupRequest`
   (all inherit `ProjectScopedRequest` in `api/schemas.py`).
-- `RetrievalFilters.project_id` is enforced in **both** halves of hybrid
+  `project_ids` (plural, required) is enforced on `AssembleOrientationRequest`,
+  `AssembleDiagramRequest`, and `MineStarterWorkRequest` for multi-project
+  scoping; `BuddyAgentRequest.project_ids` scopes the buddy's searches the
+  same way (empty admits nothing).
+- `RetrievalFilters.project_id` / `project_ids` is enforced in **both** halves of hybrid
   retrieval — `where_filter_for_chroma()` for the vector side and
   `matches_retrieval_filters()` for the BM25/in-memory side (`rag/filters.py`).
   Anything that scans `all_chunks_without_embeddings()` directly (the `grep`
@@ -100,13 +106,13 @@ ingest, or an endpoint, keep that property:
 - Don't assume Ollama-only: check `llm/base.py`'s `LLMClient` protocol when
   touching LLM calls. Backend is configurable per deployment via
   `LLM_BACKEND` / `EMBED_BACKEND`.
-- Chat is one agent, one loop. Give it a new `Tool` in `agents/tools/` rather
-  than a sub-agent to delegate to: every tier costs a serialized round-trip
-  ahead of the user's first token. Tool results must carry their chunk text —
-  a count-only summary forces a second pass to write the answer.
+- The buddy is one agent, one loop. Give it a new `Tool` in `agents/tools/`
+  rather than a sub-agent to delegate to: every tier costs a serialized
+  round-trip ahead of the user's first token. Tool results must carry their
+  chunk text — a count-only summary forces a second pass to write the answer.
 - Tools must be read-only and thread-safe: a turn's tool calls run
-  concurrently (`ChatAgent._run_tools`). Cache across calls only behind a lock,
-  as `rag.hybrid.BM25IndexCache` does.
+  concurrently (`agents.tools.base.run_tool_calls`). Cache across calls only
+  behind a lock, as `rag.hybrid.BM25IndexCache` does.
 - `AGENT_DEBUG=1` logs each agent's reasoning (LLM text + tool calls) to
   stderr — useful when debugging agent behavior.
 - The onboarding pipeline is intentionally deterministic/staged rather than

docs/faq-grouping-concept.md

@@ -73,6 +73,12 @@ Supporting decisions:
 - **Classification is idempotent** via the source message id. Events can be redelivered, and
   counting a message twice would quietly corrupt the frequency ranking the whole panel is ordered
   by.
+- **The classifier, not the caller, decides what is an FAQ question.** Questions to Buddy (the
+  project's assistant, Wiki#319) include requests to act ("move my card to done"), questions about
+  the asker's own onboarding ("what should I work on next?") and context-only follow-ups ("and the
+  second one?") next to documentation questions. All of them are sent; `relevant = false` drops
+  them, as it drops smalltalk. Classify and the full rebuild share one list of these categories
+  (`insights.faq.NON_FAQ_KINDS`), so a rebuild keeps out exactly what the live path kept out.
 - **Retrieval only runs for a new entry.** An existing one already carries the documents that
   answer it.
 - **Redaction is folded into the same call**, rather than a second round-trip per message.

scripts/_client.py

@@ -1,6 +1,6 @@
 """Shared HTTP client for the SprintStart AI terminal tools.
 
-All the subcommands (chat, ingest, onboard, corpus) talk to the same running
+All the subcommands (ingest, onboard, corpus) talk to the same running
 service, so the connection handling, health check, SSE decoding, error
 reporting, and document ingestion live here once. The offline chunk inspector
 (`chunk_inspector_cli.py`) intentionally does not use this — it parses local
@@ -183,7 +183,7 @@ def detail(response: httpx.Response) -> str:
         except (json.JSONDecodeError, ValueError):
             return response.text
 
-    # --- ingestion (shared by the chat REPL and the ingest subcommand) ----
+    # --- ingestion (used by the ingest subcommand) -----------------------
 
     def ingest_path(self, raw_path: str, artifact_id: str | None) -> None:
         path = Path(raw_path).expanduser()