## Summary Two UI texts describe behavior that the code does not have. Correct the text before 1.0.0, because these are translatable strings. Behavior does not change. 1. **Language scope.** The help text says that a context item is kept when the current language cannot be determined. That case never happens. 2. **Conditional parent cap.** The field title says "per request", but the limit applies to each context resolution call. Target: 1.0.0 if this is RTBC by the code freeze on 2026-11-09, otherwise 1.0.1. This is a good issue for a novice contributor. ## Part 1: Language scope `AiContextLanguageService::detect()` always returns a language code (`src/Service/AiContextLanguageService.php:44-56`). When no language prefix is found, detection uses Drupal content language negotiation (line 55). This is usually the default language. So a Drush command, cron or a queue worker, which has no language prefix, leaves out an item that is set only to non-default languages. Why the "kept" case never runs: - `AiContextScopeLanguage::doGetDetectedValue()` returns `detect()` (`src/Plugin/AiContextScope/AiContextScopeLanguage.php:210-212`). - For an item with Language values, `AiContextScopeBase::matchesRequestContext()` returns NULL (neutral) only when the detected value is NULL (`src/Plugin/AiContextScope/AiContextScopeBase.php:521-526`). For Language this never happens, so the result is always TRUE or FALSE. - `AiContextScopeResolver` removes the item on FALSE (`src/Service/AiContextScopeResolver.php:99-102`). - The class comment already says that detection always resolves a language code (`AiContextScopeLanguage.php:19-22`). #3586448+s says the same. The wrong text is in five places (added by #3586348+s): - `src/Plugin/AiContextScope/AiContextScopeLanguage.php:27` (scope description on Context Scope Settings) - `src/Plugin/AiContextScope/AiContextScopeLanguage.php:149` (context item form) - `src/Form/AiContextConsumerForm.php:393` (Context Inclusion Rules, "Default" row) - `src/Form/AiContextConsumerForm.php:441` (Scope Subscriptions help) - `docs/features/scopes.md:293-294` ### Steps to reproduce 1. On a site with English (default) and Spanish, where Spanish uses the URL prefix `es`, go to `/admin/config/ai/context/settings/scope`. The Languages description says: "If the language cannot be determined, the item is not left out for that reason." 2. Create a published context item with Languages set to Spanish only. Note its ID. 3. Run `drush php:eval 'echo \Drupal::service("ai_context.language_service")->detect();'`. It prints `en`. 4. Run `drush php:eval '$item = \Drupal::entityTypeManager()->getStorage("ai_context_item")->load(ITEM_ID); var_dump(\Drupal::service("plugin.manager.ai_context_scope")->createInstance("language")->matchesRequestContext($item));'`. Replace `ITEM_ID` with the ID from step 2. It prints `bool(false)`, not `NULL`. ### Expected result The text describes what the code does: - A language is always detected. - If no language prefix is found, Drupal content language negotiation decides. This is usually the default language. - A context item set only to other languages is left out. ### Actual result The text promises a neutral result that cannot happen. An editor can expect a Spanish-only item to reach Drush, cron or queue calls. It does not. ### Proposed resolution Change text only. Do not change `AiContextLanguageService` or the scope plugin logic. Wording as merged (items 1 and 2 use "effective page path" after the review in !355): 1. `AiContextScopeLanguage.php:27`: "Match context items to the language of the current page or content. A context item set only to other languages is left out. If no language prefix is found in the effective page path, Drupal's negotiated content language is used, often the site default. Matching the current language can include the item in Relevant mode and above. Consumers cannot subscribe to languages." 2. `AiContextScopeLanguage.php:149`: replace "If the current language cannot be determined, this context item is not left out for that reason." with "If no language prefix is found in the effective page path, Drupal's negotiated content language is used, often the site default." 3. `AiContextConsumerForm.php:393`: replace "If the current language is known and different, it is also left out." with "If it is set only to other languages, it is also left out." 4. `AiContextConsumerForm.php:441`: replace "Languages leave an item out only when the current language is known and different, not when the language cannot be determined." with "Languages leave out context items set only to other languages." 5. `docs/features/scopes.md:293-294`: replace "If the detected language cannot be determined, Language scope does not remove the item." with "Language detection always returns a language. If no language prefix is found, Drupal content language negotiation decides. For a Drush, cron or queue call this is usually the default language, so on a site with English as the default language the filter removes S." 6. `docs/features/scopes.md:283-285`, in the same example: S also passes on a Spanish request. Replace "removes E, leaving T and U" with "removes E, leaving T, S and U". ## Part 2: Conditional parent cap label On Context Items Settings, the field title says "Max conditional parent decisions per request" (`src/Form/AiContextItemSettingsForm.php:162`). The field description (line 166), the config schema label (`config/schema/ai_context.schema.yml:75`) and the code apply the limit to one context resolution call. One page request or agent run can make several resolution calls, so it can make more AI decisions than the number in this field. How the code counts: - `AiContextSubcontextResolver::resolve()` reads the limit and sets the counter to 0 at the start of every call (`src/Service/AiContextSubcontextResolver.php:103-109`). The check is at lines 297-304. - `AiContextSelector::select()` calls `resolve()` once (`src/Service/AiContextSelector.php:532-537`). Each "Load AI Context Item By ID" tool call also calls it once (`src/Plugin/AiFunctionCall/LoadAiContextItemById.php:238-243`). - A decision for the same parent, task and children is reused within one PHP request (`src/Service/AiContextSubcontextResolver.php:289-292`). #3586207+s added the limit. ### Steps to reproduce 1. Go to `/admin/config/ai/context/settings/items`. 2. Open the Subcontext section. 3. Check "Enable subcontext hierarchy" and "Enable conditional subcontext AI decisions". 4. Read the title and the description of the limit field. ### Expected result The title and the description name the same unit: one context resolution call. ### Actual result The title says "per request". The description says "per context resolution call". The docs also say "per request": - `docs/developers/configuration.md:92` (setting name in the table) - `docs/developers/debugging.md:120-121` (`decision_cap_exhausted`) ### Proposed resolution - Change the title at `src/Form/AiContextItemSettingsForm.php:162` to "Max conditional parent decisions per context resolution call". - Add one sentence to the description at line 166: "A page request or agent run can make several resolution calls, for example one when the system prompt is built and one for each Load AI Context Item By ID tool call." - Use the new name in `docs/developers/configuration.md:92` and `docs/developers/debugging.md:120-121`. Add the same sentence to `docs/features/subcontext.md:51-53`, where the decision cap is named. - Do not change the setting key, the schema or the limit logic. ## Remaining tasks - [x] Part 1: update the four UI strings and the two docs passages. - [x] Part 2: change the field title and description, and update `docs/developers/configuration.md`, `docs/developers/debugging.md` and `docs/features/subcontext.md`. - [x] Functional: update the assertions that check the old Language strings: - `tests/src/Functional/AiContextScopeSettingsTest.php:158` - `tests/src/Functional/AiContextScopeContextItemFormTest.php:304` - `tests/src/Functional/AiContextScopeConsumerFormTest.php:163` - `tests/src/Functional/AiContextConsumerSettingsTest.php:146` - [x] Functional: extend `testSettingsHelpDescribesTokenLimitTruncation()` in `tests/src/Functional/AiContextAdminSettingsTest.php`. It already loads the settings page (line 244). Assert the new cap title. Assert that "Max conditional parent decisions per request" is not on the page. - [x] Kernel: add `testRequestWithoutPrefixUsesNegotiatedLanguage()` to `tests/src/Kernel/AiContextScopeLanguageTest.php`. Use English (default) and Spanish and a request path with no prefix. Assert that `matchesRequestContext()` returns FALSE for a Spanish-only item, TRUE for an English item, and NULL for an item with no Language values. The existing `testMatchesRequestContextLanguage()` (`tests/src/Kernel/AiContextScopeResolverTest.php:417`) only uses a language that is not installed (`fr`). - [x] Kernel: in `tests/src/Kernel/AiContextItemSettingsConfigValidationTest.php`, extend `testItemSettingsFormBuildIncludesSubcontextFields()` to assert the `#title` of `conditional_max_parents`. - [x] Unit: no new test. `tests/src/Unit/AiContextLanguageServiceTest.php` already covers the fallback (`testFallsBackToLanguageManager()` and `testFallsBackWhenNoRequest()`). - [x] No update hook, no schema change and no behavior change. - [x] Also name the Roles hard filter in the three consumer help strings (Always include, Default and Scope Subscriptions), and fix two more Language docs lines: `multilingual.md` ("detection happens once per request") and `context_selection.md` ("how it scores"). Found in the opus check of !355. - [x] Release note: "Corrected the Language scope help text, the conditional parent limit label, and the consumer help about which scopes leave a context item out (it now names Roles). Behavior did not change." Tell translators that seven source strings changed (two Language scope strings, three consumer form help strings, and the title and description of the cap field). ## Environment - Drupal version: any version that 1.0.0-rc1 supports (^10.5 || ^11.2) - Module version: 1.0.0-rc1 (8a57807); 1.0.x has no later commits - PHP version: any supported version - Provider: not provider-specific - Last known working version: none ### Frontend environment *(only required for UI / frontend issues)* - OS: not OS-specific - Browser: not browser-specific ### Screenshots / recordings *(optional)* None. ### Error messages or logs *(optional)* None. > [!note] > Check the one that best describes your usage, or leave all unchecked if AI was not significantly used. > > * [ ] AI **Assisted Issue** \ > _Mainly written by a human; AI used for partial generation under full human supervision._ > > * [x] AI **Generated Issue** \ > _Mainly generated by AI, reviewed and approved by a human before this issue was created._