## Summary _**Docs and help text only. No selection-behavior changes.**_ Follow-up to: - #3586281 - #3586270 - #3586335 - #3586337 Also coordinated with: - #3586378 (maximum context-item count removed; global-item and token limits remain) - #3586388 (Entity Types is a hard filter; scope weights/scoring) - #3586346 (consumer rearchitecture; **not landed**, so this issue keeps **agent** terminology) - #3586369 (Global checkbox `<br>` rendering) - #3586301 (accessible new-tab links) Beta testing confirmed that the **subscription** model can remain, but the UI and documentation did not clearly explain how scope matching, eligibility, ranking, overrides, and limits work together. This issue improves inline help and user-facing documentation without changing scope behavior, configuration storage, selection logic, or subscription semantics. Implemented in MR !257. ## Problem The previous Context scope description said: > Control when this context item is included. Add multiple scopes to include it > whenever any one matches, or turn on Global context to always include it. That was incomplete and misleading: 1. Matching a scope does not guarantee that a context item reaches the prompt. 2. Some scopes participate in subscription scoring, while scopes with contextual detection can also **leave out** items that do not match the current request (Languages, Site Sections, and Entity Types). 3. Context items still compete within the configured **global-item** and **token** limits. There is no separate “maximum context items” cap (#3586378). 4. Global context, Specific Entities matching, and per-agent inclusion overrides do not behave like ordinary subscription matches. 5. Several scope descriptions explained what values can be selected but not how those values affect selection. 6. Site builders had to read developer documentation or source code to understand why an apparently relevant item was not selected. The result was an inaccurate expectation that assigning a scope such as Entity Types = `node:article` guaranteed injection whenever an agent works with an article. ## Goal A site builder should be able to answer these questions from the UI and user-facing documentation: - What does assigning this scope to a context item do? - Does a matching scope guarantee inclusion? - What is the difference between subscription matching and contextual detection? - How do multiple scope values interact? - How do inclusion overrides affect selection? - Can an applicable item still be omitted because of global-item or token limits? ## Proposed solution ### 1. Correct the Context scope form description Replace wording that implies every matching scope guarantees inclusion. The revised description explains that scopes help determine whether a context item is applicable and how it is prioritized. Actual selection also depends on agent subscriptions, inclusion overrides, visibility, and configured limits. ### 2. Improve built-in scope descriptions Review the item-form, overview, and subscription-form descriptions for all built-in scopes: - Global - Use Cases - Languages - Tags - Site Sections - Entity Types - Specific Entities Each description should explain: - What the scope represents. - Whether values are matched through subscriptions, detected from the current request, or both. - Whether a match affects eligibility, ranking, or automatic selection under the current implementation. - That ordinary matching does not guarantee selection within the configured limits. Descriptions should remain short enough to scan in the form. Link to the documentation for the complete selection model and examples. Do not introduce formal user-facing scope types. Terms such as “categorization” and “environmental context” may be used descriptively, but they must not establish a new plugin API or stored taxonomy. ### 3. Clarify the agent subscription form Add or revise always-visible help text explaining that: - Subscriptions prioritize applicable context items. - Subscribing does not guarantee that every matching item will be selected. - Inclusion overrides can force or prevent an item for that agent. - The global-item limit and token budget can limit the final selection. Link to Context Scope Settings and the Context Selection Guide. Keep **agent** terminology until the consumer rearchitecture (#3586346) lands. ### 4. Expand user-facing scope documentation Update `docs/features/scopes.md` and related user documentation to describe the selection process in plain language: 1. Published and accessible items become candidates. 2. Explicit exclusions and contextual mismatches remove items. 3. Global, situation-based auto-selected, and explicitly included items receive their existing priority. 4. Remaining applicable items are scored against subscriptions. 5. Global-item and token limits determine the final rendered result. The documentation must describe current behavior rather than the possible future model discussed in #3586281. ### 5. Add worked examples Include at least these examples: #### A. Subscription match does not guarantee selection An item tagged “Editorial” matches an agent subscription. The match improves its score, but another item may be selected instead when the token budget is reached. #### B. Contextual mismatch excludes an item An item has Use case = Working with text and Language = French. The use-case subscription matches, but the current context is English. The language mismatch makes the item inapplicable. #### C. Entity Types is applicability, not a guarantee “Article editorial standards” is scoped to `node:article`. If the agent is working on a different type, the item is left out. When the agent is working on an article, the item is applicable, but that does not guarantee it survives ranking and limits. #### D. Specific Entities behavior An item targets a specific piece of content, such as the “About us” page. It is selected automatically when an agent is working on that exact content, but that is not a guarantee. Token limits still apply. This is more specific than Entity Types. #### E. Explicit override An agent’s **Always include** override gives an item priority independently of ordinary subscription scoring, subject to the selector’s existing overall limits. #### F. Global context A Global item does not require a subscription. It is applicable to every agent, but publication, view access, the global-item limit, and the token budget still apply. ### 6. Coordinate with subscription-limit UX #3586337 handles visual indicators for approaching or reaching subscription limits. This issue provides accurate terminology and documentation for that work but does not duplicate its warning designs or implementation. ## Implementation notes Landed in MR !257. Review follow-ups included: - Entity Types copy now says a type mismatch **leaves the item out**, then ranking/limits. Agent subscription help lists Languages, Site Sections, **and Entity Types** as hard filters. - Specific Entities keeps **selected automatically**, and now says that is not guaranteed because of token limits. - Agent table label is **Global (applicable to every agent)**, not “always included” or “offered”. - Help links use `AiContextNewTabLinkTrait` so they include visually hidden “(opens in new tab)” text. - Scope overview table caption **Available context scope plugins and their status** is present. - **Context Selection Guide** stays in title case (not Drupal sentence case). - Merged `1.0.x` (#3586388 weights/scoring and #3586392 plugin boundary). This MR kept its descriptions and the `1.0.x` weights. ## Non-goals This issue does not: - Add or expose formal scope types. - Group the item form into “Match any” and “Filter by” sections. - Remove Languages, Site Sections, or Entity Types from subscriptions. - Add a per-item inclusion mode. - Change scoring, filtering, auto-selection, or priority ordering. - Change global-item or token behavior. - Restore a maximum context-item count (#3586378). - Migrate stored scope values or agent subscriptions. - Add selection preview or explainability tooling. - Implement the future model discussed in #3586281. - Switch UI copy to “consumer” before #3586346 lands. ## Affected areas - `AiContextItemForm` Context Scope help - Agent configuration form inclusion-rule and subscription help - Built-in scope plugin descriptions - `docs/features/scopes.md` - `docs/features/context_selection.md` - `docs/features/agent_configuration.md` - `docs/developers/scope_api.md` where it made an incorrect user-visible claim ## Acceptance criteria - [x] The Context scope form no longer says or implies that every matching scope guarantees inclusion. - [x] Inline help distinguishes applicability or prioritization from guaranteed inclusion. - [x] All seven built-in scope descriptions have been reviewed for accuracy. - [x] Subscription-form help explains prioritization, overrides, and limits. - [x] Documentation accurately describes the current selection sequence. - [x] Documentation includes examples A–F or equivalent examples covering the same behavior. - [x] Entity Types and Specific Entities behavior are clearly distinguished. - [x] Global context and inclusion overrides are clearly distinguished from ordinary subscription matching. - [x] Documentation links are provided where inline descriptions cannot contain the necessary detail. - [x] Copy keeps “agent” because the consumer rearchitecture (#3586346) has not landed. - [x] No scope-selection, persistence, scoring, filtering, or migration behavior changes are included (aside from the already-landed #3586369 `<br>` rendering fix carried in this MR). - [x] Existing relevant automated tests pass. - [x] Functional assertions are updated or added for materially changed form help text. - [x] `./lint.sh` passes. ## Manual test plan 1. Add or edit a context item at `/admin/config/ai/context/items/add`. 2. Review the Context Scope introduction and every enabled scope description. 3. Confirm that the copy does not promise inclusion merely because a scope matches. 4. Confirm Entity Types says a different content type **leaves the item out**. 5. Confirm Specific Entities says **selected automatically** and that this is not guaranteed. 6. Confirm Global says the item is **applicable** to every agent and still counts toward limits. 7. Open an agent’s context settings at `/admin/config/ai/context/settings/agents/{ai_agent}/edit`. 8. Confirm inclusion-rule help and the table label **Global (applicable to every agent)**. 9. Confirm subscription help explains prioritization, overrides, hard filters, and limits. 10. Confirm **Context Scope Settings** and **Context Selection Guide** open in a new tab and include “(opens in new tab)” for assistive tech. 11. Follow the item-form **scope documentation** link and confirm examples A–F match current behavior. 12. Visit `/admin/config/ai/context/settings/scope` and confirm the overview table caption is present. 13. Check the changed forms at narrow and wide viewport widths. 14. Confirm help links and descriptions are keyboard accessible. ## Related issues - #3586281 — discussion of future scope roles and inclusion semantics - #3586270 — beta feedback about Tags and scope selection - #3586335 — UX decision to retain subscription terminology - #3586337 — subscription-limit indicator - #3586378 — remove maximum context-item count - #3586388 — scope scoring and Entity Types hard filter - #3586346 — consumer rearchitecture (not landed) - #3586369 — Global checkbox line break - #3586301 — accessible new-tab links - #3586243 — scope plugin persistence and capability API - #3586197 — future boundaries and exclusions ## AI usage - [x] AI assisted issue