Skip to content

Drupal: Context Acquisition (not development doctrine)

Role in the context plane

Teaches an agent how to acquire context about a Drupal site before working on it. This is not Drupal development doctrine — for HOW to build Drupal, read Drupal AI Best Practices (backend/AI/orchestration ladder) and Drupal Site-Building Doctrine (Canvas/component/theme ownership). This file does not duplicate either; it only tells an agent where Drupal context comes from before those doctrines apply.

Drupal is not one box. Classify every Drupal surface by its actual authority:

Surface Classification Source
Site identity, deployment config PRODUCT CONTEXT Site repo composer.json/config, GitLab
Composer-installed package graph RUNTIME OBSERVATION composer show inside the live site — not source authority; the producer's Git repo is
Enabled modules / current config RUNTIME OBSERVATION drush status / config export — a snapshot, not doctrine
Content / entities / config (the database) RUNTIME OBSERVATION (site-specific, not reproducible from Git alone) The live site database/config sync
Drupal core / contrib module behavior UPSTREAM DOCUMENTATION drupal.org project page → linked docs → project.pages.drupalcode.org → upstream GitLab source → README — current docs/source beat memory
Canvas component metadata, Recipes, Site Templates DERIVED CONTEXT Canvas CLI / current Canvas tooling — generated from source, not hand-maintained
Tool API / MCP / Drupal AI / AI Agents UPSTREAM DOCUMENTATION + PRODUCT CONTEXT Per-module upstream docs, plus Drupal AI Best Practices for Bluefly's binding usage rules

Authority

Never authoritative on its own. A Drupal site's runtime (installed packages, enabled modules, live config) is an observation of the currently-deployed state — it is not the source of that state. The producer's Git repository (module, theme, Recipe) is always the source authority; the installed copy inside vendor//web/modules/contrib/ is a generated artifact (same rule as drupal-standard.md's "generated trees are never source").

Query/access path

  • Upstream module docs: drupal.org project page first, then linked documentation, then project.pages.drupalcode.org, then upstream source on git.drupalcode.org — in that order, current docs over memory.
  • Site runtime: drush status, composer show, config export — inside the correct execution context (see drupal-site-building-standard.md §16 for ddev ssh/host distinction).
  • Canvas state: current official Canvas CLI, not memorized syntax.

Freshness

RUNTIME OBSERVATION for anything read from a live/local site (changes on every deploy/config-sync). UPSTREAM DOCUMENTATION for module behavior (changes on every upstream release — re-check version before trusting memory).

Mutation boundary

Never edit an installed package copy to "fix" a producer defect — identify the owning repo, fix it there, release, then update the consumer's dependency. Never treat a runtime observation (installed version, enabled module) as if it were the producer's source of truth.

Relationship to other context sources