## Follow-up to: #3586363+s Follow-up to "Before 1.0" triage in #3586363. Combines documentation, API annotation, security guidance, and release-policy work that should land before 1.0 without adding new functionality. **Scope:** #1, #2, #5, #6, #8 from the Before 1.0 list in #3586363+s. **Non-goals:** selector/diagnostics work (#3, #4, #9 — separate issue), performance benchmarks (#7 — 1.1), usage vs observability decision (#10 — #3567803 / #3586213). ## Problem / motivation _**Note that the following needs to be rechecked before working on this issue as some things may have been fixed.**_ Before 1.0, CCC needs accurate documentation and explicit trust/compatibility commitments. Several gaps remain after earlier API and access hardening work: stale consumer-configuration terminology, minor public/internal API contradictions, undocumented access boundaries, missing importer trust guidance, and no concise beta-to-1.0 upgrade policy. This issue is **documentation and policy consistency**, not a feature or permission redesign. ## Work packages ### #1 — Remove stale "Assigned items" documentation The docs still describe an "Assigned items" feature that is no longer part of the consumer configuration model. Known locations include: - `docs/developers/configuration.md` - `docs/features/agent_configuration.md` **Tasks:** - Remove or replace "Assigned items" references with the current model: scope subscriptions, **Always include**, and **Never include**. - Search UI help, tests, examples, and README links for the same terminology. - Documentation-only cleanup; no configuration schema changes. ### #2 — Finalize public versus internal APIs Most work landed in [#3586241](https://git.drupalcode.org/project/ai_context/-/work_items/3586241) and [#3586359](https://git.drupalcode.org/project/ai_context/-/work_items/3586359). A final consistency audit remains. **Tasks:** - Ensure every supported entry point appears on `docs/developers/api-stability.md`. - Confirm internal classes are marked `@internal` and `ai_context.api.php` stubs match. - Document deprecated APIs and their replacements. - Ensure examples use the request factory or documented events, not internal services. - Resolve contradictions such as `AiContextSelectorInterface` describing itself as public while API stability marks the selector as internal. ### #5 — Document access boundaries Much of the behavior is implemented and tested in [#3586356](https://git.drupalcode.org/project/ai_context/-/work_items/3586356). This package documents the security model for site builders and integrators. **Document that these are separate checks:** - Context-item view access - Usage-record access - Referenced target-entity access **Also document:** - Permission to view usage records does **not** grant permission to view the associated context item or target entity; CCC redacts or avoids linking inaccessible entities. - Target-entity references control **applicability**, not access to those entities. - Content copied into a context item has its own publication and access lifecycle; source-entity permissions do not protect copied material after import. Coordinate wording with #3586356 so admin docs match enforced behavior. ### #6 — Describe imported content as untrusted, review-required Add clear wording to importer and context-item documentation: - Imported files and webpages are **copied** into the editor — not trusted, synchronized, or continuously validated. - Imported text may be outdated, inaccurate, malicious, or contain prompt-injection instructions. - An authorized editor must review and revise content before publication. - Sanitization protects the editor from unsafe markup but does not establish semantic safety for AI prompts. - Recommend saving imported content as a draft or disabling **Publish by default** on importer-heavy sites. Provenance and synchronization remain 1.1 work; do not scope them here. ### #8 — Publish beta-to-1.0 support and compatibility commitments Add a concise release and upgrade policy (README section and/or dedicated doc linked from `docs/index.md`): - Supported Drupal, PHP, AI, AI Agents, and optional-module versions for 1.0. - Supported beta-to-1.0 upgrade paths and whether sites may skip intermediate beta releases. - Required database updates and expectations for preserving configuration and context-item data during upgrades. - How upgrade defects will be handled, especially following beta3 compatibility and data-repair work in [#3586338](https://git.drupalcode.org/project/ai_context/-/work_items/3586338). - After 1.0: documented public APIs follow compatibility and deprecation expectations; internal APIs may change without that guarantee. ## Acceptance criteria - [ ] No remaining "Assigned items" references in docs, help, tests, or examples (#1) - [ ] API stability page, `@internal` markers, and examples are consistent (#2) - [ ] Access-boundary and importer-trust guidance published for site builders (#5, #6) - [ ] Beta-to-1.0 upgrade and compatibility policy published and linked from main docs (#8) - [ ] Cross-links added from #3586363 and related closed issues where helpful - [ ] `./lint.sh` passes if any PHP `@internal` / docblock changes are included ## Related issues - Parent/meta: #3586363 - API stability (closed): #3586241, #3586359 - Access hardening (closed): #3586356 - Beta3 upgrade repair: #3586338 ## AI usage - [x] AI assisted issue