## Problem/motivation Follow-up to: #3586237+s Agent context selection is confusing today because the two selection modes encode mechanisms instead of user intent, and they are not supersets of each other: - **Minimal** (default) with **no subscriptions** injects almost nothing except Global, Always include, and **Target Entity** auto-matches. New agents silently get no situational context. - **Subscriptions** are required to inject Use Case, Context Tags, Taxonomy Terms, Entity Bundle, etc. — and an **empty scope on an item counts as a full subscription match**, so unscoped "generic" items appear everywhere once any subscription exists. - **Match all** only activates when subscriptions are **empty**, and it **replaces** the scored bucket rather than supplementing it. It is broader than site builders expect (includes neutral/unscoped items) while also being unavailable exactly when subscriptions are in use. Several built-in scopes already detect the current situation via `matchesCurrentContext()` (Taxonomy Terms, Entity Bundle, Site Section, Language) but only use it for hard filtering and subscription scoring — a positive situational match is never enough for inclusion on its own. After #3586237+s this gap is very visible: "this item is tagged Climate and I am editing a Climate node" should be enough without subscribing to the Climate term. ## Proposed solution Replace the selection mode enum with a **strictly nested ladder**. Each mode is a superset of the one below, so users can reason "more context or less context" without understanding internals: | Mode | Behavior | |---|---| | **Minimal** (`minimal`) | Global + Always include + Target Entity matches + **strict** subscription matches. Strict means an empty scope on an item no longer earns full subscription credit. | | **Relevant** (`relevant`) — proposed default | Minimal **plus** auto-included items with a **positive** situational match (`matchesCurrentContext() === TRUE`) from contextual scopes: Taxonomy Terms, Entity Bundle, Site Section, Language. | | **Broad** (`broad`) | Relevant **plus** remaining token budget filled with any published item that passes hard filters, ordered by Priority (#3586376). | **Remove `match_all` entirely.** Once Broad exists, match_all has no distinct meaning: its only unique behaviors (empty-subscriptions-only activation, replacing the scored bucket) are the defects this issue fixes. It is used in six src files and no tests; no deprecation is needed in beta. Diagnostic "show everything" needs are covered by Broad with a large budget; explaining *why* items were included or excluded is a separate preview/debugging feature, not a mode. Hard context filters continue to apply in **all** modes (for example, Sports-scoped items are still excluded on a Climate-only node). ### Example (from #3586237 manual testing) Climate node, no subscriptions: - **Minimal**: nothing beyond Global / Always include / Target Entity. - **Relevant**: Climate context and Climate+Sports context included (positive taxonomy match); Sports context excluded (hard filter); Generic context excluded (no positive match). - **Broad**: also includes Generic context, budget permitting, by Priority order. ## Tasks - Replace `SELECTION_MODE_MATCH_ALL` with `SELECTION_MODE_BROAD` and add `SELECTION_MODE_RELEVANT` in `AiContextRequest`; update `VALID_SELECTION_MODES`. - Remove the empty-scope-equals-full-credit behavior from `AiContextScopeResolver::calculateScopeScore()` (strict subscriptions in all modes). - Rework `AiContextSelector`: replace the four match_all branches with (a) situational auto-include for Relevant and (b) a supplemental fill group for Broad that appends **after** Global → Always → Auto → Subscriptions and consumes only leftover budget. Keep an internal (non-configurable) candidate cap for the chunked catalog scan. - Agent form: three radios with intent-based one-line descriptions; update the empty-subscription warning to fire only in Minimal mode. - `AiContextRequestFactory`: fail validation on unknown mode values instead of silently coercing to minimal; change `getRenderedContext()`/`getResult()` from hardcoded match_all to a mode parameter defaulting to `relevant`. - `get_relevant_ai_context_items` function call: update the Choice constraint to the three values and rewrite the parameter description as intent-based (the description is read by LLM callers). - Update hook: rewrite stored `match_all` agent config to `broad`. - Docs: `docs/features/context_selection.md`, agent form help, function-call docs. - Kernel/functional tests using taxonomy + entity bundle fixtures (reuse the Climate/Sports matrix from #3586237 testing), including nesting assertions (Relevant ⊇ Minimal, Broad ⊇ Relevant). ## Default mode **Recommendation:** make **Relevant** the default. It matches intuitive "situational context" behavior, makes agents useful without subscriptions, and demotes the empty-subscription warning to a rare Minimal-mode notice. We are in beta, so changing the default is acceptable; existing agents explicitly set to `minimal` keep it. ## Coordination - #3586376 — Priority field is effectively a prerequisite for Broad (it decides which supplemental items win the remaining budget). - #3586378 — max_items removal: Broad's cap is the token budget; sequence these so the selector is only reworked once. - #3586281 — subscription config rewrite window, if schema changes overlap. ## Out of scope - Per-item "eligible as supplemental" opt-in flag (possible future refinement of Broad). - Selection explanation / preview UI (why an item was included or excluded). - Changing hard-filter semantics for Taxonomy Terms. - Changing `max_tokens` behavior or defaults. ## AI usage - [x] AI assisted issue