Issue #3586365: Document scope selection and ranking logic.

Kristen Polrequested to merge
issue/ai_context-3586365:3586365-scope-ranking-logic-docs into 1.0.x

Description

Documents how Context Control Center selects and ranks Context Items before 1.0, based on the review in #3586365.

Adds a canonical site-builder guide and expands built-in scope docs with concrete matching examples. Also corrects a few outdated or inaccurate statements found while writing those docs.

What’s new

  • docs/features/context_selection.md — full selection pipeline: exclusions, priority tiers, hard filters vs subscription scoring, generic/blank scope credit, selection modes, limits, and translation as a separate step
  • docs/features/scopes.md — matching examples for Global, Use Case, Language, Tags, Site Section, Entity Bundle, and Target Entity
  • docs/developers/scope_api.md — tri-state matchesCurrentContext() contract and internal scoring formula / relative weights
  • Cross-links from README, docs index, agent configuration, multilingual, developer architecture, and MkDocs nav

Accuracy fixes in existing docs

  • Entity Bundle matches are not auto-included; only exact Target Entity matches are
  • Removed unimplemented Assigned items wording
  • Clarified Language scope (interface language hard filter) vs entity translation selection (content language / path / Referer)
  • Corrected relative scoring influence: Entity Bundle → Site Section / Use Case (equal) → Tag → Language
  • Updated outdated Use Case labels

Closes #3586365

Testing instructions

Docs-only change. No Drupal UI or functional regression testing is required.

  1. Review the new and updated pages in this MR, especially:
    • docs/features/context_selection.md
    • docs/features/scopes.md
    • docs/developers/scope_api.md
  2. Optionally build docs locally and confirm the new nav item renders:
pip install mkdocs mkdocs-material
mkdocs serve
  1. Open http://localhost:8000 and check:
    • Features → Context Selection
    • Features → Context Scopes (examples under each built-in scope)
    • Developers → Scope API (Scope scoring section)
  2. Spot-check cross-links from README / docs home / Agent Configuration / Multilingual.

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

Why no tests: documentation-only MR; no runtime behavior changed.

Post-merge: none (docs site rebuild only if/when docs are published).

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.

Edited by Kristen Pol

Merge request reports