## Problem/motivation Follow-up to: #3586237+s Also depends on (landed): - #3586383+s - #3586348+s Agent context selection is confusing because the two modes encode mechanisms instead of user intent, and they are not supersets of each other: - **Minimal** (previous default) with **no subscriptions** injects almost nothing except Global, Always include, and Specific Entities auto-matches. New agents silently get no situational context. - **Subscriptions** are required to inject Use Case, Context Tags, Taxonomy Terms, Entity Types, etc. 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 Types, 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 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. The token budget remains a soft ceiling (truncation at item boundaries + prefix overhead can slightly exceed it, with a warning logged). That is pre-existing renderer behavior and is documented, not changed. See !244 comment 1709155. A later gap: the new default lived only as a hardcoded factory fallback and a per-agent radio. There was no site-wide setting, so changing the default for every agent meant editing each agent. Individual agents still need an override. ## Proposed solution Full plan: [selection_mode_ladder.plan.md](/uploads/ddd8e3eaa5088ff623f03af80fb77157/selection_mode_ladder.plan.md) Replace the selection mode enum with a **strictly nested ladder**. Each mode is a superset of the one below. Hard filters continue to apply in all modes. | Mode | Behavior | |---|---| | **Minimal** (`minimal`) | Global + Always include + Specific Entities matches + **strict** subscription matches. Empty item scope no longer earns full subscription credit. | | **Relevant** (`relevant`) — shipped site-wide default | Minimal **plus** auto-included items with a **positive** situational match (`matchesCurrentContext() === TRUE`) from Language, Site Section, Entity Types, and Taxonomy Terms. | | **Broad** (`broad`) | Relevant **plus** remaining token budget filled with any published item that passes hard filters, ordered by Priority (#3586376). Broad **appends** after Global → Always include → auto-include → subscriptions; it does not replace the scored bucket. | **Remove `match_all` entirely.** No runtime alias. An update hook rewrites stored `match_all` agent config to `broad`. Unknown explicit mode values fail validation. **Site-wide default with per-agent override.** General settings stores `ai_context.settings:selection_mode` (shipped as Relevant). Agents without a stored mode inherit that setting. The agent form adds a **Site default (currently X)** option that unsets the agent override. An explicit agent mode still wins. Request-factory callers that omit the mode also inherit the site default. Direct `AiContextRequest` construction does not read config. **Shipped default:** Relevant. Existing sites get `selection_mode: relevant` via post-update 0004. Agents later saved as Minimal store `minimal` explicitly. ### Example (from #3586237 manual testing) Climate node, no subscriptions: - **Minimal**: nothing beyond Global / Always include / Specific Entities. - **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. Implementation details (selector prefilter, factory validation, agent radios, docs on top of #3586383 / #3586348 copy, tests) are in the attached plan. ## Tasks - Replace `SELECTION_MODE_MATCH_ALL` with `SELECTION_MODE_BROAD` and add `SELECTION_MODE_RELEVANT`. - Remove empty-scope-equals-full-credit from `AiContextScopeResolver::calculateScopeScore()`. - Rework `AiContextSelector`: situational auto-include for Relevant; Broad fill group after scored items; keep the internal candidate cap; remove the match_all broad-scan warning. - Add `selection_mode` to `ai_context.settings` (schema, install default, post-update 0004 backfill). - General settings: site-wide Default context selection mode radios, with copy that this applies site-wide unless an agent or caller overrides it. - Agent form: Site default inherit option plus Minimal / Relevant / Broad overrides; empty-subscription warning when Minimal is in effect (selected or inherited). - Factory and budget calculator: missing/invalid stored agent mode falls back to the site default; omitted convenience-method mode does the same. Explicit unknown caller modes still throw. - Function call: Choice constraint and LLM-facing description for the three modes; omitted mode inherits the agent or the site default. - Update hook: rewrite stored `match_all` to `broad`. - Docs: rewrite selection-mode copy on top of #3586383 / #3586348; document the site-wide default and inherit behavior; keep truncation and non-guarantee language. - Kernel/functional/JS tests including Climate/Sports nesting assertions (Relevant ⊇ Minimal, Broad ⊇ Relevant), site-default inheritance, and post-update 0004. ## Acceptance criteria - [x] Minimal / Relevant / Broad are a nested ladder; hard filters apply in all modes - [x] Empty item scope does not earn full subscription credit - [x] Relevant auto-includes positive matches from Language, Site Section, Entity Types, and Taxonomy Terms - [x] Broad supplements leftover budget by Priority and does not displace Global, Always include, auto-include, scored, or required-subcontext items - [x] `match_all` is removed; stored config is rewritten to `broad`; unknown explicit modes fail validation - [x] Relevant is the shipped site-wide default on General settings - [x] Agents inherit the site default unless they store an override; the agent form has a Site default option - [x] Empty-subscription warning fires when Minimal is in effect, including inherited Minimal - [x] Docs and UI help match the new modes, the site-wide default, and preserve #3586383 / #3586348 truncation / non-guarantee copy - [x] Kernel/functional/JS tests cover the Climate/Sports matrix, nesting, inheritance, and post-updates; `./lint.sh` passes ## Out of scope - Per-item "eligible as supplemental" opt-in flag - Selection explanation / preview UI (#3586242) - Changing hard-filter semantics - Changing `max_tokens` behavior or defaults - Making `AiContextRequest` itself read module config (direct constructors stay explicit) ## Related issues - Follow-up to / taxonomy fixtures: #3586237 - Land first (docs/reliability): #3586383, #3586348 - Priority field (merged): #3586376 - max_items removal (merged): #3586378 - Subscription config rewrite (no schema overlap): #3586281 - Rich diagnostics (out of scope): #3586242 ## AI usage - [x] AI assisted issue