documentation update

docs/services/orchestration-service.md

@@ -73,6 +73,9 @@ via `appSettings.load()` — changes apply immediately without a service restart
 | `scoreThreshold` | 0.5 | Minimum similarity score for Qdrant semantic results |
 | `semanticWeight` | 1.0 | RRF weight for Qdrant semantic results |
 | `keywordWeight` | 0 | RRF weight for FTS5 keyword results (`0` = disabled) |
+| `contextBudget` | — | Token budget for context assembly (char/4 estimation on stored text) |
+| `entityWeight` | — | Scoring bonus for entity-linked episodes in the context pool |
+| `minRecentEpisodes` | — | Guaranteed floor of recent episodes always included in context |
 | `modelsFolderPath` | `/mnt/nexus-models` | Path to folder containing .gguf files |
 | `temperature` | 0.7 | Inference temperature |
 | `repeatPenalty` | 1.1 | Repeat token penalty |
@@ -101,35 +104,43 @@ difference is how the inference response is delivered to the client.
 
 4. **Recent episode retrieval** — fetch most recent episodes (`recentEpisodeLimit`).
 
-5. **Fused episode retrieval** — runs semantic (Qdrant) and keyword (FTS5)
+5. **Trivial-turn gate** — greetings/pleasantries (`isTrivialTurn`) skip all
+   retrieval (semantic, keyword, entity); recent history alone is the context.
+   Breaks the greeting → marginal-retrieval → confabulation loop.
+
+6. **Fused episode retrieval** — runs semantic (Qdrant) and keyword (FTS5)
    search in parallel, then merges results via Reciprocal Rank Fusion (RRF).
-   Both paths are filtered against `recentIds` before fusion. FTS is scoped
-   to the current session or all project sessions. If `keywordWeight` is `0`,
-   the FTS call is skipped entirely. Non-critical — failures fall back to
-   whichever strategy succeeded.
+   The query is embedded once and shared with entity search. Both paths are
+   filtered against `recentIds` before fusion. FTS is scoped to the current
+   session or all project sessions. If `keywordWeight` is `0`, the FTS call
+   is skipped entirely. Non-critical — failures fall back to whichever
+   strategy succeeded.
 
-6. **Entity search** — query `entities` Qdrant collection filtered by
-   `projectId`. Returns entity IDs alongside Qdrant payload data (the Qdrant
-   point ID equals the SQLite entity ID). Non-critical.
+7. **Entity search + graph expansion** — query `entities` Qdrant collection
+   (project-scoped, or session-scoped via `/sessions/:id/entity-ids` for
+   non-project chats). Entity IDs are expanded into a 1-hop subgraph via
+   `POST /graph/neighbors`; on failure, falls back to flat entity list.
+   Non-critical.
 
-7. **Graph neighborhood expansion** — call `POST /graph/neighbors` on
-   memory-service with the entity IDs from step 6. Returns a 1-hop subgraph
-   `{ nodes, edges }` — entity objects plus the relationships connecting them.
-   If no entities were found or the graph call fails, falls back to flat entity
-   list (no edges). Non-critical.
+8. **Scored pool + budget selection** — `buildScoredPool` combines RRF scores,
+   recency, and entity-linkage bonus; `selectWithinBudget` fills `contextBudget`
+   (char/4 token estimation on stored text) above a guaranteed floor of
+   `minRecentEpisodes` recent episodes. Selected episode IDs are then reported
+   to `POST /episodes/touch` fire-and-forget (access tracking for the
+   consolidation lifecycle).
 
-8. **Prompt assembly** — combine system prompt, graph context, fused episodes,
-   recent episodes, and user message.
+9. **Prompt assembly** — combine system prompt, graph context, selected
+   episodes, guaranteed recent episodes, and user message.
 
-9. **Inference** — send to inference service. `/chat` awaits full response;
-   `/chat/stream` pipes SSE chunks to the client.
+10. **Inference** — send to inference service. `/chat` awaits full response;
+    `/chat/stream` pipes SSE chunks to the client.
 
-10. **Episode write** — write exchange back to memory with `projectId`.
+11. **Episode write** — write exchange back to memory with `projectId`.
 
-11. **Summarisation trigger** — `triggerSummary(session, allEpisodes)` called
+12. **Summarisation trigger** — `triggerSummary(session)` called
     fire-and-forget. See `summarization.md` for full details.
 
-12. **Auto-naming** — on first message with no session name, fires a secondary
+13. **Auto-naming** — on first message with no session name, fires a secondary
     inference call (max 20 tokens, temperature 0.3) to generate a session name.
 
 ### Prompt Structure