Issue #3586392: Clarify and stabilize scope plugin extension boundary for 1.0.

Description

Closes #3586392

Locks down the 1.0 custom scope extension boundary ahead of 1.0 without changing runtime behavior. This is the small boundary/docs half of the old persistence-refactor work; the capability-based persistence API remains deferred to a follow-up issue.

What changed

Documentation

• docs/developers/api-stability.md — 1.0 storage contract, public entity scope helpers (effective vs stored), manager/resolver internal status
• docs/developers/scope_api.md — extension boundary for 1.0, dual meaning of supportsSubscriptions(), manager marked internal
• docs/developers/custom_scopes.md — map-only storage for custom scopes, icon guidance without manager injection, complete plugin example including doGetCurrentValue()

Code (no behavior changes)

• Added PLUGIN_ID constants on all seven core scope plugins
• Replaced hardcoded core scope ID literals with those constants in forms, entity helpers, resolver, index, view builder, and manager
• Centralized stored-value reads in AiContextScopeManager::getStoredScopeValuesForPlugin() (internal seam for future persistence work)
• Marked AiContextScopeResolverInterface as @internal
• Expanded supportsSubscriptions() PHPDoc on AiContextScopeInterface

Tests

• testCoreScopePluginIdConstants() — constants match discovered plugin IDs (including target entity after DER install)
• testBuildScopeSummaryFromStoredValuesUsesScopeMap() — map-backed stored summaries
• testBuildScopeSummaryFromStoredValuesIncludesTargetEntity() — target entity path uses the centralized seam

Public 1.0 contract (summary)

Supported: scope plugins via AiContextScopeBase, scope-map storage, documented hooks/alters, entity helpers via getScopeItem() for effective scope and stored accessors for saved values.

Not supported in 1.0: custom entity-field storage, hooking the index/cleanup/presave pipelines directly, injecting plugin.manager.ai_context_scope from contrib.

Breaking changes

None. This clarifies and documents boundaries; it does not remove or rename public APIs.

Testing instructions

1. Check out branch 3586392-scope-extension-docs from the issue fork.
2. From the Drupal project root, run:

   ddev exec phpunit web/modules/contrib/ai_context/tests/src/Kernel/AiContextScopeManagerTest.php

   Expect 14 tests, 0 failures.
3. From web/modules/contrib/ai_context, run:

   ./lint.sh

   Expect all checks to pass.
4. Smoke test (no functional change expected):
   • Context item add/edit: scope fieldsets render and save as before
   • Agent settings: scope subscription widgets render as before
   • Context listing (/admin/config/ai/context/items): loads without errors
5. Optional doc review:
   • docs/developers/api-stability.md
   • docs/developers/scope_api.md
   • docs/developers/custom_scopes.md

Checklist

• I have updated the MR title to use format: Issue #1234: My issue title.
• I have updated the MR description to include: Closes #1234
• I have performed a self-review of my own code
• I have added or updated tests, or explained in the description why this change is not covered by tests
• I have updated documentation for any new or changed functionality
• I have written testing instructions and verified them locally
• I have noted any required post-merge steps (config imports, cache rebuilds, manual changes)
• This MR contains no breaking API or hook changes, or they are explicitly documented in the description

Post-merge: drush cr only. No config import or update hooks.

AI Compliance

Note

Check the one that best describes your usage, or leave all unchecked if AI was not significantly used.

• AI Assisted Code
  Mainly written by a human; AI used for autocomplete or partial generation under full human supervision.

• AI Generated Code
  Mainly generated by AI, reviewed and approved by a human before this MR was created.

• Vibe Coded
  Generated by AI and only functionally reviewed before this MR was created.