## Summary Follow-up to: #3586169 AI Context needs a module-wide developer doc that defines the stable public surface vs internal implementation details. Issue `#3586162` documents the **selection extension model** (pipeline events, no service decoration), but that covers only one slice of the module. **Goal:** Add a clear public/internal boundary in developer docs so contrib and site builders know what they can rely on without reading selector internals. ## Solution **Public (document as supported):** - `AiContextRequestFactory` and `AiContextRequest` / `AiContextResult` - Selector pipeline events (`ai_context.selection.*`) and event classes - Scope plugins, documented hooks/alters - Convenience APIs intended for non-agent consumers (`getRenderedContext()`, `getResult()`) **Internal (document as unsupported / may change without deprecation):** - `AiContextSelector` and its candidate pipeline (load, score, merge, subcontext) - Supporting services: scope resolver, scope index, subcontext resolver, renderer internals - Decorating or replacing internal services in `services.yml` **Proposed deliverables:** - New section in `docs/developers/services.md` (or a short `docs/developers/api-stability.md` linked from `index.md`) - Per-service **Status: public** / **Status: internal** labels where helpful - Cross-link from existing [Supported extension model](events.md#supported-extension-model) so selection docs aren’t duplicated - Optional: `@internal` PHPDoc on clearly internal service classes (separate sub-task if desired) **Out of scope:** - Re-documenting event subscriber contracts (already in `events.md`) - Implementing new extension points ## Acceptance criteria - A contrib developer can answer “what am I allowed to depend on?” from docs alone - Internal selector/pipeline services are explicitly marked unsupported - Public entry points (`request_factory`, events, models) are explicitly marked supported ## AI usage - [x] AI assisted issue - [ ] AI generated code