## Problem/Motivation Follow-up from the beta4/1.0.x analysis triage: #3586309+s Combines remaining developer-experience and docs polish that does not need a separate design track: - analysis item #7 (`ai_context.api.php` + `@internal`) - analysis item #9 (config/docs consistency) - leftover analysis item #8 nits only (`strict_types`, Global scope descriptions, subcontext toggle trait) Related (do not duplicate here): #3586271+s — larger consistency/DX cleanup (final classes, constructor promotion, snake_case, etc.) Already done / out of scope here: - `hook_help()` (already present) - full procedural → `#[Hook]` migration (defer to 1.1) - accessibility tooltip work (#3586302) ## Proposed resolution Target: **1.0.0-rc1** polish (can land earlier in beta4 if convenient). ### 1. API stubs and `@internal` alignment - Add `ai_context.api.php` with documented alter-hook stubs currently only described in `docs/developers/hooks.md` (e.g. `hook_ai_context_scope_info_alter`, scope-values alter). - Add `@internal` docblocks to classes/services declared internal in `docs/developers/api-stability.md` (today mostly only `AiContextItemViewBuilder` is tagged). ### 2. Config/docs consistency - Add missing `content_moderation` config dependency on `core.entity_view_display.ai_context_item.ai_context_item.default.yml` (renders `content_moderation_control`; `full`/form displays already declare the dependency). - Document `ai_context.scheduler_defaults` in `docs/developers/services.md`. - Document entity-lifecycle hook implementations in `docs/developers/hooks.md` where missing. - Cross-link function-call plugins from `services.md` if still absent. ### 3. Small code-standards and DX nits - Add `declare(strict_types=1);` to `src/Plugin/diff/Field/DynamicEntityReferenceFieldBuilder.php`. - Separate the Global scope's general plugin description from its context-item form guidance: - The plugin attribute and `getDescription()` should contain only the general description shown on scope overview/settings pages. - The Global context checkbox should retain its form-specific save/clear warning and line break. - Keep these as separate complete translatable strings because they serve different UI contexts; do not mechanically compose or alter translated text. - Refactor `AiContextSubcontextToggleTrait` so it does not call `\Drupal::config()` when the consuming service already has `ConfigFactoryInterface`. - Keep the content entity's non-DI config lookup explicit rather than using the trait's service-oriented behavior. - Normalize unit-test group metadata across supported Drupal versions: retain `@group` annotations for PHPUnit 9 on Drupal 10 and add `#[Group]` attributes for PHPUnit 10+ on Drupal 11. No intentional selection, storage, matching, access, or public API behavior changes are included. The only user-facing copy change is removing context-item save guidance from scope overview/settings pages where no context item is being saved. Generalizing context-specific descriptions across all scope plugins through a new plugin API method is a separate follow-up. ## Acceptance criteria - `ai_context.api.php` exists and matches documented alter hooks. - Stability-policy internal services/classes are `@internal`-tagged. - Default view display config dependency and developer docs gaps above are fixed. - `declare(strict_types=1);` is added to the Diff field builder. - Scope overview/settings pages describe what the Global scope does without mentioning context-item save behavior. - The Global context checkbox retains the save/clear warning and line break. - The Global overview/settings and item-form descriptions remain separate, complete translatable strings. - Automated coverage verifies the Global context checkbox description and the overview/settings description split. - DI-capable `AiContextSubcontextToggleTrait` consumers use their injected `ConfigFactoryInterface`; the content entity does not use the trait. - `./lint.sh` / CI quality jobs pass. - No broad hook-attribute migration is included. - Unit tests use both `@group` and `#[Group]` so group filtering works on Drupal 10 and Drupal 11. ## Out of scope - Adding a generic `getItemFormDescription()` scope plugin API. - Rewriting descriptions for all scope plugins. - Full `#[Hook]` migration. - Larger DX sweep already tracked in #3586271. - Drop-D10 modernization (#10). - Access/permission or accessibility work. ## AI usage - [x] AI assisted issue