## Summary Follow-up to: #3586270+s Beta feedback shows site builders expect context items scoped to the current task (e.g., Entity bundle = Content: article) to be **always included** when an agent works on that content. In practice, most scoped items are only **eligible** and then **prioritized** via subscription scoring, subject to per-agent limits. Only a few paths guarantee inclusion (Global, Always include override, Target entity match). The agent configuration UI and scope docs do not make that distinction clear enough. ## Problem During beta testing, a site builder assumed this mental model: > Context item scoped to **Entity bundle = Content: article** → when the agent does anything with an article, that item is used. No questions asked. After reading the docs and the agent **Advanced** settings, they found the behavior feels like a black box. **Inclusion Overrides → Always include** appears to be the only obvious way to get the behavior they originally expected was default. Root causes: 1. **Context item scope language over-promises.** The context item edit form says scope values “define when this context item should be included,” which reads as guaranteed inclusion. 2. **Agent scope subscriptions sound like filtering, but behave like ranking.** Docs say subscribed items “score higher and are more likely to be selected,” but the **Scope matching** section does not walk through a concrete scenario showing eligibility vs selection vs limits. 3. **Entity bundle (and similar contextual scopes) blur two roles.** On a context item, entity bundle acts as a **hard eligibility filter** (excluded when the current bundle does not match). It does **not** auto-include the item the way **Target entity** does. That distinction is easy to miss because both scopes mention “when the agent operates on…” language. 4. **Important constraints are buried.** Per-agent **max context items**, **max tokens**, and **selection mode** live under **Advanced** and strongly affect whether a “matching” item actually reaches the prompt. 5. **Inclusion Overrides terminology is opaque.** “Do not override (use subscriptions)” and “Default: included based on scope matching and context relevance” do not explain the three-tier model below. ### Actual selection model (for reference) When an agent runs, context items fall into roughly three buckets: | Bucket | Mechanism | Guaranteed? | |--------|-----------|-------------| | **Always included** | Global items; per-agent **Always include**; **Target entity** match (non-subscription auto-include) | Yes (within global/max limits) | | **Eligible + prioritized** | Pass hard context filters (language, site section, entity bundle, etc.); scored against agent **scope subscriptions**; top scores selected up to **max items** / **max tokens** | No — competition among candidates | | **Excluded** | **Never include**; hard filter mismatch; unpublished; zero subscription score when subscriptions exist | — | With **minimal** selection mode (default) and **no** scope subscriptions, only the first bucket applies unless selection mode is changed to **Match all**. ## Proposed solution ### Documentation (`docs/features/scopes.md`, `docs/features/agent_configuration.md`) Expand **Scope matching** with 2–3 worked examples, e.g.: **Example A — Entity bundle scope (eligibility, not guarantee)** - Context item “Article editorial standards” scoped to `node:article`. - Agent has **no** entity bundle subscription; minimal mode; max items = 5. - Agent edits an article → item is **eligible** (passes hard filter) but **not guaranteed**; it only enters the pool if the agent has matching subscriptions or wins scoring against other candidates within the item cap. **Example B — Same item, forced inclusion** - Same item; agent override set to **Always include** → item is **always** injected (subject to token budget). **Example C — Target entity vs entity bundle** - Side-by-side: target-entity-scoped item auto-includes when working on that entity; entity-bundle-scoped item only narrows eligibility and participates in subscription scoring. Also tighten wording on the context item form docs: scope values define **eligibility and categorization**, not automatic injection. ### Agent configuration UI (`AiContextAgentForm`) 1. Add a short, visible intro (not only collapsed **Context Inclusion Rules**) explaining the three buckets above in plain language. 2. **Scope Subscriptions** fieldset: clarify that subscriptions **prioritize** among eligible items; they do not force inclusion unless combined with **Always include** or a non-subscription auto-include scope (Target entity, Global). 3. **Inclusion Overrides** column: rename or supplement options, e.g. - “Default (eligible + prioritized by subscriptions)” - “Always include (force into prompt)” - “Never include (exclude from this agent)” 4. Surface a one-line reminder near the context items table about **max context items** / **max tokens** (with link to Advanced), since limits explain “why didn’t my matching item appear?” 5. Consider a contextual help link from **Scope Subscriptions** → docs anchor for “Scope matching examples.” ### Context item edit UI (`AiContextItemForm`) Revise the **Context scope** description from “define when this context item should be included” to language that distinguishes: - **Eligibility** (contextual scopes filter by current page/task) - **Agent configuration** (subscriptions, overrides, limits decide what actually gets injected) Optionally add per-scope hints on entity bundle / language / site section: “Narrows when this item can be considered; does not guarantee inclusion for every agent.” ### Optional follow-up (out of scope unless cheap) - Selection preview or debugger hint listing *why* an item was included/excluded/skipped (ties to `ai_agents_debugger` if available). ## Workaround (today) For any context item that must always reach a specific agent when relevant: 1. Open `/admin/config/ai/context/settings/agents/{agent_id}/edit` 2. Set the item’s **Inclusion Overrides** to **Always include context item** Or use **Global** / **Target entity** scopes where those semantics fit. ## Affected functional areas - Agent configuration UI (`/admin/config/ai/context/settings/agents/{agent}/edit`) - Context item edit UI (`/admin/config/ai/context/items/add|edit`) - End-user docs: `docs/features/scopes.md`, `docs/features/agent_configuration.md`, `docs/features/context_items.md` - Possibly inline help in scope plugin subscription descriptions (`getSubscriptionDescription()`) ## Acceptance criteria - [ ] A beta tester can answer: “If I scope an item to articles only, will it always be injected?” without opening source code. - [ ] Docs include at least two concrete before/after examples (eligible-but-not-selected vs always-included). - [ ] Agent form copy explicitly states that scope subscriptions **prioritize**, not **guarantee**, unless overridden. - [ ] Entity bundle vs Target entity behavior is documented and surfaced in UI help. - [ ] No change to selection algorithm required unless product decides guaranteed inclusion should be the default for contextual scopes (separate decision).