## Summary _**Note that this could be implemented in rc1 because it's docs/help text and no functionality changes.**_ Follow-up to: - #3586281+s - #3586270+s - #3586335+s - #3586337+s Beta testing confirmed that the **subscription** model can remain for beta4, but the UI and documentation do 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. ## Problem The current Context scope description says: > 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. This is incomplete and can be misleading: 1. Matching a scope does not always guarantee that a context item reaches the prompt. 2. Some scopes participate in subscription scoring, while scopes with contextual detection can also exclude items that do not match the current request. 3. Context items still compete within the configured maximum item and token limits. 4. Global context, Target entity matching, and per-consumer inclusion overrides do not behave like ordinary subscription matches. 5. Several scope descriptions explain what values can be selected but not how those values affect selection. 6. Site builders must currently read developer documentation or source code to understand why an apparently relevant item was not selected. The result is an inaccurate expectation that assigning a scope such as Entity bundle = `node:article` guarantees that the item will be injected 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 item or token limits? ## Proposed solution ### 1. Correct the Context scope form description (UX team) Replace wording that implies every matching scope guarantees inclusion. The revised description should explain, in concise language, that scopes help determine whether an item is applicable and how it is prioritized. Actual selection also depends on consumer subscriptions, inclusion overrides, and configured limits. Exact copy can be refined during implementation and UX review. ### 2. Improve built-in scope descriptions (UX team) Review the item-form and subscription-form descriptions for all built-in scopes: - Global - Use case - Language - Tag - Site section - Entity bundle - Target entity Each description should explain: - What the scope represents. - Whether values are manually matched through subscriptions, detected from the current request, or both. - Whether a match affects eligibility, ranking, or automatic inclusion 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 in this issue. Terms such as “categorization” and “environmental context” may be used descriptively when they improve understanding, but they must not establish a new plugin API or stored taxonomy. ### 3. Clarify the consumer subscription form (UX team) 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 consumer. - Maximum context items and maximum tokens can limit the final selection. Where practical, link the limits reference to the existing Advanced settings or the documentation section that explains them. The terminology should follow the consumer rearchitecture if that work lands before this issue. Avoid adding new agent-specific wording that will immediately become obsolete. ### 4. Expand user-facing scope documentation (Kristen) 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, context-auto-included, and explicitly included items receive their existing priority. 4. Remaining applicable items are scored against subscriptions. 5. Maximum item and token limits determine the final result. The documentation must describe current behavior rather than the possible future model discussed in #3586281. ### 5. Add worked examples (Kristen with UX Team input) Include at least these examples: #### A. Subscription match does not guarantee selection An item tagged “Editorial” matches a consumer subscription. The match improves its score, but another item may be selected instead when the item or token limit 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 bundle is applicability, not a guarantee “Article editorial standards” is scoped to `node:article`. When the consumer works with an article, the item is applicable, but ordinary scope matching does not guarantee that it survives ranking and limits. #### D. Target entity behavior An item targets a specific entity. Explain the current automatic-inclusion behavior and how it differs from the broader Entity bundle scope. #### E. Explicit override A consumer’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. Explain the global item limit and the ordering used when more Global items exist than the configured limit. ### 6. Coordinate with subscription-limit UX #3586337+ handles visual indicators for approaching or reaching subscription limits. This issue should provide accurate terminology and documentation for that work but should not duplicate its warning designs or implementation. ## Non-goals This issue does not: - Add or expose formal scope types. - Group the item form into “Match any” and “Filter by” sections. - Remove Language, Site section, or Entity bundle from subscriptions. - Add a per-item inclusion mode. - Change scoring, filtering, auto-inclusion, or priority ordering. - Change maximum item or token behavior. - Migrate stored scope values or consumer subscriptions. - Add selection preview or explainability tooling. - Implement the future model discussed in #3586281. ## Affected areas Expected areas include: - `AiContextItemForm` Context scope help - Consumer/agent configuration form subscription help - Built-in scope plugin descriptions - `docs/features/scopes.md` - `docs/features/agent_configuration.md` - Other user-facing context item documentation containing selection claims Developer API documentation should only be changed where it currently makes an incorrect user-visible behavioral claim. ## Acceptance criteria - [ ] The Context scope form no longer says or implies that every matching scope guarantees inclusion. - [ ] Inline help distinguishes applicability or prioritization from guaranteed inclusion. - [ ] All seven built-in scope descriptions have been reviewed for accuracy. - [ ] Subscription-form help explains prioritization, overrides, and limits. - [ ] Documentation accurately describes the current selection sequence. - [ ] Documentation includes examples A–F or equivalent examples covering the same behavior. - [ ] Entity bundle and Target entity behavior are clearly distinguished. - [ ] Global context and inclusion overrides are clearly distinguished from ordinary subscription matching. - [ ] Documentation links are provided where inline descriptions cannot contain the necessary detail. - [ ] Copy uses “consumer” where appropriate if the consumer rearchitecture has landed. - [ ] No scope-selection, persistence, scoring, filtering, or migration behavior changes are included. - [ ] Existing relevant automated tests pass. - [ ] Functional assertions are updated or added for materially changed form help text. - [ ] `./lint.sh` passes. ## Manual test plan 1. Edit a context item. 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. Edit a configured context consumer. 5. Confirm the subscription help explains prioritization, overrides, and limits. 6. Follow the contextual-help link to the scope documentation. 7. Confirm the documentation answers whether an article-scoped item is always injected. 8. Confirm the worked examples match current runtime behavior. 9. Check the changed forms at narrow and wide viewport widths. 10. Confirm help links and descriptions are keyboard accessible and retain appropriate form associations. ## Related issues - #3586281+s — discussion of future scope roles and inclusion semantics - #3586270+s — beta feedback about Tags and scope selection - #3586335+s — UX decision to retain subscription terminology - #3586337+s — subscription-limit indicator - #3586243+s — scope plugin persistence and capability API - #3586197+s — future boundaries and exclusions ## AI usage - [x] AI assisted issue