Drupal Glossary¶

Overview¶

This glossary defines the Drupal terminology Bluefly uses for current Drupal 11, Drupal CMS 2, Canvas, Recipes, the Drupal AI ecosystem, and modern Composer-based delivery.

It is intentionally not a historical Drupal 7/8/9 glossary. Older terminology is included only when needed to prevent agents from applying obsolete patterns to current Drupal work.

Current baseline at the time of this update:

Drupal core: Drupal 11.4.x; 11.4.5 is the current production patch release verified for this revision.
Drupal CMS: Drupal CMS 2.x is the current product line for new-site assembly; it is distinct from Drupal core.
Drupal Canvas: the current name of the experience-building system formerly developed as Experience Builder. Canvas 1.11.x is current stable at this revision.
Single-Directory Components (SDC): part of Drupal core's render system since Drupal 10.3.
Recipes: the modern, composable mechanism for applying site capabilities and configuration.
Composer: the authoritative dependency-management mechanism for Drupal core and contributed PHP packages.
Drupal AI: the contrib ecosystem for model providers, AI abstractions, agents, tools, context, workflows, and integrations.

The operating principle is:

CORE
→ STABLE CONTRIB
→ CONTRIB CONFIGURATION
→ DRUPAL CONFIGURATION
→ RECIPE
→ CONFIG ACTION
→ CANVAS / SDC
→ ECA / MODELER
→ DRUPAL AI
→ AI AGENTS
→ TOOL API
→ TOOL BELT
→ MCP / EXISTING INTEGRATION
→ EXISTING BLUEFLY EXTENSION
→ CUSTOM CODE ONLY AFTER PROVEN GAP

Fences¶

These are terminology and architecture fences. Agents must not cross them casually.

Drupal Core vs Drupal CMS¶

Drupal core is the framework and CMS platform distributed as drupal/core-*.

Drupal CMS is a product built on Drupal core for accelerated site creation. It uses recipes, site templates, Canvas, and curated capabilities.

Do not use the terms interchangeably.

DRUPAL CORE != DRUPAL CMS

Canvas vs Experience Builder¶

Canvas is the current product name.

Experience Builder is the former development/working name.

Use:

Drupal Canvas

Do not introduce new documentation that treats Experience Builder as the current name.

Drupal Composer Repository vs Packagist¶

Drupal contrib is normally resolved from:

https://packages.drupal.org/8

Packages use Composer names such as:

drupal/ai
drupal/eca
drupal/canvas
drupal/tool

Most Drupal contrib is not sourced from Packagist directly.

DRUPAL CONTRIB AUTHORITY = packages.drupal.org
PACKAGIST = general PHP ecosystem

Source vs Composer Projection¶

These are dependency projections:

web/modules/contrib/
web/themes/contrib/
vendor/

Do not edit them as authoritative source.

Permanent law:

Do not edit what Composer installed. Edit what Composer installs from.

Recipe vs Module¶

A Recipe applies and composes site capabilities/configuration.

A Module provides runtime code and extension behavior.

RECIPE != MODULE

Do not add custom PHP to a Recipe to avoid creating or fixing the proper runtime owner.

Configuration vs Content¶

Drupal distinguishes configuration from content.

Configuration includes things such as:

field definitions;
view displays;
Views;
roles;
workflows;
module settings;
entity type configuration.

Content includes things such as:

nodes;
media;
taxonomy terms;
users;
content entity instances.

Do not assume exporting configuration exports content.

Canvas vs SDC¶

SDC is Drupal's component definition/rendering system.

Canvas is an authoring and experience-composition product that can consume component-based frontend capabilities.

SDC = COMPONENT API / RENDERING BUILDING BLOCK
CANVAS = EXPERIENCE COMPOSITION / AUTHORING

Tool API vs Tool Belt¶

Tool API defines the typed executable-unit framework.

Tool Belt provides a growing collection of reusable Tool API plugins.

TOOL API = FRAMEWORK
TOOL BELT = TOOL IMPLEMENTATIONS

Do not freeze a specific Tool Belt tool count into architecture documentation.

MCP vs MCP Server¶

The older drupal/mcp project is no longer the preferred server implementation.

For a Drupal MCP server, upstream currently recommends:

drupal/mcp_server

Treat drupal/mcp as legacy/transitional unless an existing consumer specifically requires it.

AI Integration - ECA vs Older AI/ECA Integrations¶

Current upstream integration:

drupal/ai_integration_eca

It replaces older AI/ECA integration attempts, including drupal/ai_eca.

Do not create new architecture around the obsolete integration.

AI Context / Context Control Center vs Bluefly ContextControl¶

Context Control Center (CCC) is the upstream Drupal project:

drupal/ai_context

ContextControl.ai is Bluefly's governed product layer.

AI CONTEXT / CCC = UPSTREAM DRUPAL CONTEXT MODEL
CONTEXTCONTROL.AI = BLUEFLY GOVERNANCE PRODUCT

Bluefly should extend upstream context capability rather than replace it.

Drupal Work vs Factory Work¶

Drupal owns Drupal application behavior.

Drupal does not replace:

Gas City
Beads
GitLab CI
Cedar
1Password
host provisioning
container orchestration

Core Platform Terms¶

Drupal¶

The open-source content management framework and application platform.

In current Bluefly work, "Drupal" normally means modern Drupal 11 unless a project explicitly declares another supported version.

Drupal Core¶

The foundational Drupal codebase.

Typical Composer packages include:

drupal/core
drupal/core-recommended
drupal/core-composer-scaffold
drupal/core-project-message

For standard sites, prefer drupal/core-recommended unless there is a specific dependency reason not to.

Drupal 11¶

The current major Drupal core line used by Bluefly.

At this revision, Drupal 11.4.x is the current supported minor line used as the reference baseline.

Do not write architecture that assumes Drupal 10-era limitations still apply without checking current Drupal 11 behavior.

Drupal CMS¶

A curated Drupal product built on Drupal core for faster creation of production sites.

Drupal CMS is a starting point, not a separate runtime platform. After installation it is a normal Drupal site.

Drupal CMS 2 integrates modern site templates and Canvas-oriented experience building.

Site Template¶

A Drupal CMS starting configuration for a new site.

A site template may assemble recipes, themes, content patterns, Canvas capabilities, and other defaults.

A site template is broader than a single Recipe.

Distribution¶

Historically, a Drupal install profile plus packaged configuration/modules used to deliver a preconfigured Drupal solution.

For modern Drupal assembly, prefer composable Recipes and Drupal CMS site templates where possible rather than creating a new monolithic distribution.

Composer & Package Terms¶

Composer¶

PHP dependency manager used by Drupal.

Composer owns dependency resolution and installation.

Common commands:

composer install
composer require drupal/<project>
composer update
composer show drupal/<project>

`packages.drupal.org`¶

Drupal.org's Composer repository for contributed Drupal projects.

Canonical repository:

https://packages.drupal.org/8

Despite the /8 path, it is the Composer endpoint used for current Drupal versions.

Composer Lock File¶

composer.lock

Records the exact resolved dependency graph used by the project.

Documentation and implementation decisions must be checked against the versions actually resolved here, not merely the newest upstream release.

Composer Constraint¶

The allowed package version range declared in composer.json.

Examples:

^1.0
^1.0@beta
1.0.x-dev

Constraints are policy; composer.lock records the exact resolved versions.

Stable Release¶

A release upstream considers production-ready.

For contrib, stable releases covered by Drupal's security advisory policy are preferred when they satisfy the required capability.

Alpha / Beta / RC¶

Pre-stable release channels.

Use intentionally.

alpha = early / changing
beta  = feature-complete direction but still pre-stable
rc    = release candidate

Do not treat an alpha package as equivalent to supported stable infrastructure.

Dev Release¶

A branch-based development package such as:

1.x-dev
1.0.x-dev

Use only when there is a specific reason.

Do not silently normalize development constraints into production architecture.

Drupal Composer Scaffold¶

Core Composer tooling that places required Drupal root files into the project during installation/update.

It is part of the Composer build process and should not be replaced with custom file-copy logic.

Drupal Extension Terms¶

Module¶

A Drupal extension providing application behavior, services, plugins, routes, configuration, UI, integrations, or other runtime capability.

Contrib package type:

drupal-module

Contrib¶

Community-maintained Drupal extension code distributed through Drupal.org.

Examples:

drupal/ai
drupal/eca
drupal/key
drupal/tool

Bluefly policy is contrib-first.

Custom Module¶

Project-specific Drupal runtime code.

Custom code is the last step after upstream capability discovery.

Valid reasons include true Bluefly-specific:

governance semantics;
provenance;
domain model;
Cedar integration;
cross-system correlation;
product-specific policy/UI.

Theme¶

Drupal extension controlling presentation and frontend rendering.

Modern themes should use component-oriented practices where appropriate, especially SDC.

Submodule¶

A module shipped inside a larger Drupal project that can be enabled independently.

Do not confuse a submodule machine name with its Composer project name.

Project Machine Name¶

Drupal.org project identifier used in URLs and usually Composer names.

Example:

https://www.drupal.org/project/ai_context
composer require drupal/ai_context

Entity System¶

Entity¶

Drupal's primary structured data abstraction.

Drupal has two major classes:

CONTENT ENTITY
CONFIG ENTITY

Content Entity¶

Entity whose instances represent content or operational records.

Common examples:

node;
media;
taxonomy term;
user;
block content.

Content entities may support fields, revisions, translations, moderation, and access control.

Configuration Entity¶

Entity whose instances are configuration.

Examples include many:

Views;
workflows;
image styles;
roles;
field configuration objects.

Configuration entities participate in configuration management rather than normal content synchronization.

Entity Type¶

The Drupal definition of a class of entities.

Examples:

node
media
user
taxonomy_term

Bundle¶

A subtype of an entity type.

Examples:

node:article
media:image
taxonomy_term:tags

"Content type" is the UI-oriented name for a node bundle.

Content Type¶

A bundle of the node entity type.

Do not use "content type" as a synonym for all entity bundles.

Field¶

A typed data definition attached to an entity/bundle.

Drupal fields have separate storage and instance/configuration concepts.

Base Field¶

Field defined by an entity type's code rather than site configuration.

Field Storage¶

Configuration describing the underlying field storage definition.

Field Config¶

Bundle-specific configuration for a field attached to a particular entity bundle.

Revision¶

A historical version of a revisionable entity.

Revisions are not the same as Git versions.

Default Revision¶

The revision Drupal considers current/live for an entity.

Translation¶

Language-specific field/content values for a translatable entity.

Translation is separate from revisioning.

Configuration System¶

Configuration¶

Drupal's deployable site settings and structural definitions.

Typical configuration YAML lives in the configured sync directory.

Active Configuration¶

Configuration currently stored and used by the running Drupal site.

Configuration Sync Directory¶

Filesystem representation used for importing/exporting configuration.

Typical workflow:

drush config:export -y
drush config:import -y

The sync directory is not automatically the correct owner for every reusable capability; reusable capability may belong in a Recipe.

Configuration Export¶

Copies active configuration to the configured sync directory.

drush config:export -y

Exporting is not architecture design. Curate ownership before committing generated configuration.

Configuration Import¶

Applies synchronized configuration to the site.

drush config:import -y

Configuration Split¶

A contributed pattern/module used to vary configuration between environments.

Do not use it reflexively when settings/environment overrides or other current Drupal mechanisms solve the problem more directly.

Configuration Override¶

Runtime override of configuration values without changing the stored configuration object.

Often used for environment-specific values.

Secrets should still come from secret authority rather than be embedded in source.

Recipes¶

Recipe¶

A declarative package that applies capabilities and configuration to an existing or new Drupal site.

Recipes can:

install modules/themes;
import other recipes;
create configuration;
apply configuration actions.

Recipes should be composable and narrowly owned.

`recipe.yml`¶

Primary Recipe definition file.

Describes the Recipe's metadata, dependencies/imports, extensions to install, configuration to create, and config actions to apply.

`drupal-recipe`¶

Composer package type for a Recipe package.

Recipe Composition¶

Using smaller Recipes from a higher-level Recipe.

Preferred:

SMALL CAPABILITY RECIPE
+ SMALL CAPABILITY RECIPE
+ PRODUCT RECIPE

instead of one giant site recipe.

Recipe Unpack¶

Composer workflow that converts Recipe package dependencies into normal project dependencies so the resulting site does not remain permanently coupled to a Recipe package as if it were a runtime module.

Drupal CMS uses recipe-unpack tooling as part of its modern assembly flow.

Config Action¶

A typed, idempotent operation applied to existing Drupal configuration from a Recipe.

Examples include permission grants and configuration updates.

Prefer Config Actions to custom install/update PHP when the desired change is configuration-level behavior.

Recipe Update Path¶

Recipes are applied, not managed like modules with normal update hooks.

Do not assume reapplying a newer Recipe gives an automatic upgrade path for a site previously assembled with an older version.

Rendering & Frontend¶

Render Array¶

Drupal's structured PHP array representation of renderable output.

Render arrays carry markup definitions plus cacheability and rendering metadata.

Cache Metadata¶

Drupal's cache correctness model.

The three core concepts are:

CACHE TAGS
CACHE CONTEXTS
MAX-AGE

A rendered result without correct cache metadata is not complete.

Cache Tags¶

Describe which data dependencies invalidate cached output.

Cache Contexts¶

Describe request/context variation, such as:

permissions;
language;
route;
user roles.

Max-Age¶

Defines time-based cache lifetime.

Twig¶

Drupal's primary server-side template language.

Twig templates should render data; business logic belongs elsewhere.

Single-Directory Components (SDC)¶

Drupal core's component model.

A component typically lives under:

components/<component-name>/

and contains:

<component-name>.component.yml
<component-name>.twig

with optional CSS, JS, assets, documentation, and source files.

Since Drupal 10.3, SDC is part of core's render system.

Component Metadata¶

The .component.yml definition for an SDC.

Defines properties such as:

name;
status;
props schema;
slots.

Component metadata is part of the component contract.

Component Plugin Manager¶

Core service:

plugin.manager.sdc

Used to discover and instantiate SDC components.

Canvas¶

Drupal's modern experience-building and visual composition system.

Current name:

Drupal Canvas

Former working name:

Experience Builder

Canvas works with component-oriented frontend architecture and supports experience composition beyond traditional template-only authoring.

Code Component¶

A frontend component managed through Canvas's local code workflow.

Code Components can include JS/TS, metadata, styles, dependencies, and related frontend assets.

Canvas CLI¶

NPM package:

@drupal-canvas/cli

Current workflow centers on commands such as:

npx canvas pull
npx canvas validate
npx canvas push

Use the current CLI command behavior rather than old Experience Builder-era assumptions.

Canvas Agent Context¶

Canvas CLI capability that exposes authoritative component/entity-reference metadata for coding agents.

Use it rather than guessing Canvas metadata.

Examples include:

npx canvas agents-context cer-expressions
npx canvas agents-context cer-preview <component>

Page Template¶

As of Canvas 1.11, Canvas includes editable, theme-independent page templates.

Do not confuse Canvas page templates with Twig template files or Drupal CMS site templates.

Global Region¶

Canvas-managed reusable page region.

Content Template¶

Canvas-managed presentation/template definition for content.

Brand Kit¶

Canvas-oriented source-controlled design/brand assets and configuration used by a local Canvas codebase.

Layout & Experience Terms¶

Layout Builder¶

Core Drupal layout authoring system predating Canvas.

It remains a real Drupal capability, but do not assume it is the strategic destination for new Canvas-oriented product work.

Paragraphs¶

Contrib entity-based component/content composition system.

It remains widely used but is not synonymous with Canvas or SDC.

Do not automatically create Paragraph-based architecture for new Canvas-native work.

Block¶

Reusable renderable unit placed in a Drupal region or layout.

Block Content¶

Content entity type for reusable custom block content.

Region¶

Theme-defined placement area.

Canvas global regions are related experience concepts but should not be conflated with classic theme regions.

Workflow & Content Governance¶

Workflow¶

Core framework for defining states and transitions.

Content Moderation¶

Core module that applies moderation workflows to content entities.

Moderation State¶

Current workflow state of moderated content.

Examples:

draft
published
archived

Actual states are site configuration, not universal constants.

Workspace¶

Drupal core capability for staging groups of content changes in isolated workspaces before publishing them to live/default content.

Tool Belt includes workspace-oriented tools.

ECA¶

Event - Condition - Action.

Drupal automation framework for model-driven workflows.

Use ECA when behavior naturally fits:

EVENT
→ CONDITION
→ ACTION

before creating custom event glue.

ECA Model¶

Configured workflow graph/model executed by ECA.

Modeler¶

UI/representation layer used to build workflow models, depending on installed ECA/modeler capabilities.

FlowDrop¶

Visual modeling capability used in parts of the modern Drupal automation ecosystem.

Treat it as a modeling/UI layer, not a replacement for Drupal runtime ownership.

API & Integration¶

JSON:API¶

Drupal core RESTful API based on the JSON:API specification.

It exposes Drupal entities through standardized resource endpoints.

Use it for deterministic entity CRUD/integration when it satisfies the contract.

REST¶

Drupal core's REST system.

Do not create custom REST endpoints before checking JSON:API, contrib integration modules, Tool API, and existing owners.

API Orchestrator¶

Contrib project:

drupal/api_orchestrator

Configuration-oriented external API integration layer.

Use before writing custom Guzzle/cURL services for ordinary external API communication.

Webhook¶

Event-driven HTTP notification between systems.

Before creating a custom webhook receiver or sender, check:

platform-native webhook capability;
drupal/webhooks;
API Orchestrator;
existing Bluefly ingress owner.

MCP¶

Model Context Protocol.

Protocol for exposing tools, prompts, and resources to AI clients/agents.

MCP is a protocol, not Drupal's internal orchestration model.

MCP Server¶

Current preferred Drupal contrib server project:

drupal/mcp_server

At this revision, it is on the 2.x beta line and uses the official MCP PHP SDK.

Do not assume the older drupal/mcp project is the current preferred server.

MCP Client¶

Software consuming MCP resources/tools/prompts from an MCP server.

Do not create a Drupal-specific MCP transport when an existing generic client owner already satisfies the requirement.

Drupal Plugin / Service Architecture¶

Service¶

Object registered in Drupal's Symfony dependency-injection container.

Services provide reusable application logic.

Dependency Injection¶

Pattern where services receive their dependencies from the container rather than locating globals directly.

Preferred for testable Drupal service architecture.

Plugin¶

Drupal's discoverable implementation pattern for swappable units of behavior.

Examples include:

blocks;
field widgets;
field formatters;
actions;
Tool API tools;
AI provider plugins.

Plugin Manager¶

Service responsible for discovering and instantiating a plugin type.

Event Subscriber¶

Symfony/Drupal service that reacts to dispatched events.

Prefer ECA or existing extension points when event handling can be expressed without custom code.

Hook¶

Drupal extension point implemented with named callback conventions or modern hook mechanisms supported by current Drupal.

Do not assume legacy procedural hook implementation is always the preferred modern implementation.

Route¶

Symfony route defining an HTTP endpoint/controller mapping.

A need for executable functionality does not automatically imply a custom route; check Tool API and existing APIs first.

Controller¶

Drupal/Symfony class handling an HTTP route request.

Controllers should remain thin and delegate domain behavior to proper services/tools.

Form API¶

Drupal's structured form definition, validation, submission, and rendering system.

Batch API¶

Drupal API for long-running operations split across requests.

Queue API¶

Drupal API for deferred/background work items.

Do not use Queue API to recreate Gas City/Beads agent orchestration.

Cron¶

Drupal's periodic execution mechanism.

Use for Drupal-owned maintenance work, not as a substitute for the engineering factory scheduler.

Views & Querying¶

Views¶

Core Drupal query/display builder.

Views should be considered before custom listing/query controllers.

View¶

A configured Views definition.

Can expose displays such as:

page;
block;
feed;
REST export.

Entity Query¶

Drupal API for querying entities by field/property conditions.

Use access-aware patterns appropriate to the operation.

Search & Data Retrieval¶

Search API¶

Contrib search abstraction widely used for indexed Drupal search.

AI Search¶

Drupal AI ecosystem capability for semantic/vector-oriented retrieval.

Use established Drupal AI/vector provider ownership before creating a custom vector client.

Vector Database¶

Database optimized for vector embeddings/similarity search.

Examples may include Qdrant and other supported providers.

The vector database is storage infrastructure, not the governance model.

Embedding¶

Numeric vector representation of content used for semantic similarity/retrieval.

RAG¶

Retrieval-Augmented Generation.

Pattern where relevant retrieved context is supplied to a model for generation.

RAG is not itself durable memory or governance.

Drupal AI Ecosystem¶

Drupal AI¶

Contrib ecosystem centered on:

drupal/ai

Provides provider abstraction and AI-oriented capabilities used by other Drupal modules.

Current Drupal AI architecture includes broad provider abstractions rather than binding the application directly to one model vendor.

AI Provider¶

Plugin/integration implementing an AI model capability behind Drupal AI's provider abstractions.

Examples of capability categories may include:

chat;
embeddings;
moderation;
reranking;
speech;
image/audio generation;
classification;
object detection;
translation.

Do not hardcode one provider where Drupal AI already exposes an abstraction.

AI Automator¶

Drupal AI capability for applying AI operations to Drupal fields/content workflows.

Guardrail¶

Validation/policy layer that constrains or evaluates AI input/output.

Do not confuse model guardrails with hard infrastructure authorization such as Cedar.

AI Agents¶

Contrib project:

drupal/ai_agents

Provides configurable agents using tools within Drupal.

At this revision, 1.3.x is a stable release line while 1.4.x is in beta.

AI Agent¶

Configured agent that has a prompt/instructions plus allowed executable capabilities/tools.

A Drupal AI Agent does not replace Gas City as Bluefly's engineering orchestration plane.

Tool API¶

Contrib project:

drupal/tool

Typed executable-unit framework for Drupal.

A Tool has defined inputs/outputs and can be reused by automation, agents, and other callers.

Use Tool API before inventing another application-specific "agent action" abstraction.

Tool¶

One executable capability defined through Tool API.

A Tool should represent a bounded domain operation.

Tool Belt¶

Contrib project:

drupal/tool_belt

Collection of reusable Tool API implementations.

At this revision, it is still on an alpha release line despite active development.

Check Tool Belt before reimplementing common Drupal operations.

AI Integration - ECA¶

Contrib project:

drupal/ai_integration_eca

Current bridge between Drupal AI and ECA.

As of this revision, 1.0.0 is a stable, security-covered release.

It replaces older AI/ECA integration approaches.

AI Context / Context Control Center (CCC)¶

Contrib project:

drupal/ai_context

Governed Drupal context model for AI-related use.

At this revision, the current release line is 1.0 beta.

Bluefly extends this upstream context authority rather than recreating it.

Context Item¶

Governed context record/entity managed by the Context Control Center.

Exact fields/bundles are implementation and configuration details; do not invent them from memory.

Context Scope¶

Configuration/selection mechanism defining where context applies.

Treat upstream scope behavior as authoritative.

Security & Access¶

Permission¶

Named Drupal authorization capability assigned to roles.

Permissions are not authentication.

Role¶

Collection of permissions assigned to users.

Access Check¶

Runtime authorization decision controlling access to a route/entity/operation.

Use Drupal access APIs rather than hand-rolled route guards.

CSRF¶

Cross-Site Request Forgery protection.

Mutation endpoints exposed to browsers must use appropriate Drupal/Symfony CSRF/auth patterns.

Key¶

Contrib project:

drupal/key

Drupal-facing abstraction for secret/key consumption.

Bluefly model:

1Password = secret authority
Drupal Key = Drupal consumption/reference layer

Do not store secret values in exported config.

Development & Local Runtime¶

DDEV¶

Recommended local containerized development environment in current Drupal documentation and Bluefly's standard local Drupal runtime.

Bluefly workflow:

BEAD
→ GOVERNED WORKTREE
→ DDEV
→ COMPOSER
→ DRUSH
→ TEST
→ MR

Drush¶

Drupal command-line administration and developer tool.

Common current operations include:

drush status
drush pm:list
drush config:status
drush config:export -y
drush config:import -y
drush cache:rebuild
drush generate
drush recipe

Drush is an execution interface, not an architecture.

Generator¶

Scaffolding capability exposed by Drush for supported Drupal code structures.

A generator can create code skeletons.

Its existence does not prove custom code should be created.

Cache Rebuild¶

Common Drush command:

drush cache:rebuild

Rebuilds Drupal caches.

Do not use cache rebuilds as a substitute for finding configuration/container/schema defects.

Testing & Quality¶

Kernel Test¶

Drupal test type bootstrapping enough Drupal services/database functionality for integration-level module behavior without a full browser stack.

Functional Test¶

Drupal test exercising site behavior through HTTP/browser-oriented APIs.

Functional JavaScript Test¶

Browser/JavaScript-capable Drupal functional test.

Unit Test¶

Isolated PHP test without bootstrapping the full Drupal kernel.

Nightwatch¶

JavaScript end-to-end testing tooling used in Drupal core/frontend contexts.

Check the current project/tooling before assuming Nightwatch is the correct choice for contrib or product browser tests.

PHPUnit¶

Primary PHP test framework in Drupal core/contrib.

Deprecation¶

API marked for future removal.

Do not introduce new usage of deprecated APIs.

Backward Compatibility (BC)¶

Drupal core policy around preserving supported APIs within compatibility guarantees.

Contrib stability varies by project/release maturity.

Drupal.org & Contribution¶

Drupal.org Project Page¶

Canonical public project landing page:

https://www.drupal.org/project/<machine_name>

Check here for:

releases;
security coverage;
compatibility;
maintenance state;
issue queue;
documentation;
ecosystem.

DrupalCode¶

Drupal.org's GitLab-based source hosting:

https://git.drupalcode.org/project/<machine_name>

Canonical upstream source for Drupal core/contrib projects hosted on Drupal.org.

Ecosystem Page¶

Project ecosystem discovery page:

https://www.drupal.org/project/<machine_name>/ecosystem

Use it before creating companion/bridge modules.

Security Advisory Coverage¶

Drupal.org indication that supported stable releases are covered by the Drupal Security Team's advisory policy.

A project being active does not automatically mean every release line is security-covered.

Issue Queue¶

Drupal.org work/discussion system for upstream bugs, features, support, and tasks.

When Bluefly encounters an upstream defect, contribute upstream rather than permanently forking where practical.

Merge Request¶

Git-based contribution proposed against DrupalCode.

Modern Drupal contribution uses GitLab merge requests rather than the historical patch-only workflow.

Patch¶

Diff file representing code changes.

Patches still exist in workflows, but for upstream development prefer the current DrupalCode/GitLab contribution path where supported.

Current-vs-Legacy Terminology¶

Prefer Now	Older / Contextual Term	Guidance
Drupal Canvas	Experience Builder	Experience Builder was the working name; use Canvas for current docs.
Drupal CMS	Starshot	Starshot was the initiative/codename; Drupal CMS is the product.
Recipes	install-profile-only assembly	Prefer composable Recipes/site templates for new capability assembly.
SDC	theme-specific ad hoc component systems	SDC is core's component API.
Tool API	generic custom action wrappers	Use typed Tools when the capability fits.
Tool Belt	copying common Drupal tools into custom modules	Reuse upstream implementations.
AI Integration - ECA	AI ECA / old ECA integration submodule	Current upstream integration is `drupal/ai_integration_eca`.
MCP Server	older `drupal/mcp` server assumption	Upstream recommends `drupal/mcp_server` for current server implementation.
Composer	Drush download / manual contrib zip	Composer is dependency authority.
DrupalCode GitLab MR	patch-only contribution workflow	Use modern upstream GitLab workflow.
Configuration / Recipes	custom install PHP for every site change	Prefer declarative ownership.

Bluefly-Specific Drupal Terms¶

ContextControl.ai¶

Bluefly product providing human governance, review, correction, curation, audit, and governed shared context around Drupal-native capabilities.

It is not the execution control plane.

`recipe_contextual_memory`¶

Bluefly Recipe that assembles/configures contextual-memory capability.

It should remain declarative and compose upstream owners.

`kb_cache`¶

Bluefly governance/memory extension.

Bluefly-specific ownership includes areas such as:

provenance
tenancy
idempotency
conflict detection
write guards
governed memory semantics

It should not recreate a generic Qdrant/vector provider client already owned upstream.

GAID¶

Bluefly identity/provenance concept used in governed agent/memory context.

It is Bluefly-specific, not a Drupal core term.

Cedar¶

Authorization layer used by Bluefly for hard mutation decisions.

principal
+ action
+ resource
+ context
→ Allow | Deny

Cedar authorization is distinct from Drupal prompt instructions and model guardrails.

Gas City¶

Bluefly's agent orchestration plane.

Drupal can invoke or receive governed work from Gas City but does not recreate its scheduling/work graph.

Bead¶

Durable unit of engineering/agent work in Gas City/Beads.

Not a Drupal entity by default.

If represented in Drupal, the Drupal representation is a projection/governance view unless explicitly established otherwise.

Receipt¶

Governed record of an external execution/result correlated back into Drupal/ContextControl.

A receipt is evidence, not the work authority itself.

Current Reference Baseline — 2026-09-16¶

The following versions/statuses were verified against current Drupal.org information while updating this glossary.

Project	Current Reference State
Drupal core	11.4.5 production patch release; 11.4.x security coverage through June 2027
Drupal Canvas	1.11.0 stable; works with Drupal `^11.3`
Drupal AI Context / CCC	1.0.0-beta5; works with Drupal `^10.5 \|\| ^11.2`; no supported stable release yet
AI Integration - ECA	1.0.0 stable/security-covered; works with Drupal `^10.3 \|\| ^11 \|\| ^12`
Tool Belt	1.0.0-alpha5; no supported stable release yet
AI Agents	1.3.5 stable; 1.4.x beta also exists
MCP Server	2.0.0-beta2; preferred current Drupal MCP server project, no supported stable release yet
Drupal CMS	2.x current product line; Drupal CMS is distinct from Drupal core

These are observations as of this document update, not permanent architecture constraints.

Always verify the installed project:

composer show drupal/<project>

and compare against current upstream before changing a dependency constraint.

Permanent Drupal Operating Law¶

SEARCH BEFORE BUILDING.

CORE BEFORE CONTRIB.

CONTRIB BEFORE CUSTOM.

CONFIG BEFORE PHP.

RECIPE BEFORE INSTALL-PROFILE LOGIC.

SDC BEFORE INVENTING A COMPONENT SYSTEM.

CANVAS BEFORE INVENTING A PAGE BUILDER.

ECA BEFORE CUSTOM WORKFLOW GLUE.

TOOL API BEFORE CUSTOM EXECUTION ABSTRACTIONS.

TOOL BELT BEFORE REIMPLEMENTING COMMON DRUPAL OPERATIONS.

API ORCHESTRATOR BEFORE CUSTOM HTTP CLIENTS.

EXISTING WEBHOOK OWNERS BEFORE NEW WEBHOOK RECEIVERS.

AI CONTEXT BEFORE CUSTOM CONTEXT MODELS.

DRUPAL AI PROVIDERS BEFORE CUSTOM MODEL/VECTOR CLIENTS.

MCP SERVER BEFORE A NEW DRUPAL MCP SERVER.

KEY REFERENCES SECRETS.

1PASSWORD OWNS SECRET VALUES.

COMPOSER OWNS DEPENDENCY PROJECTION.

DO NOT EDIT CONTRIB PROJECTIONS.

DRUPAL OWNS DRUPAL BEHAVIOR.

GAS CITY ORCHESTRATES AGENTS.

BEADS OWNS DURABLE FACTORY WORK.

CEDAR AUTHORIZES MUTATION.

GITLAB OWNS SOURCE.

REUSE THE OWNER.

FIX THE OWNER.

EXTEND THE OWNER.

CONTRIBUTE UPSTREAM.

OWN LESS.

SHIP MORE.

Authoritative Upstream References¶

Use current upstream documentation rather than relying on this glossary alone for exact API signatures or version constraints.

Drupal core releases: https://www.drupal.org/project/drupal/releases
Drupal Composer dependency management: https://www.drupal.org/docs/develop/using-composer/manage-dependencies
Drupal Composer repository: https://packages.drupal.org/8
Drupal CMS releases: https://www.drupal.org/project/cms/releases
Drupal CMS strategy: https://www.drupal.org/about/initiatives/cms/strategy-2026
Drupal Recipes: https://www.drupal.org/docs/extending-drupal/recipes
Single-Directory Components: https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components
Canvas: https://www.drupal.org/project/canvas
Drupal AI: https://www.drupal.org/project/ai
AI Agents: https://www.drupal.org/project/ai_agents
AI Context / Context Control Center: https://www.drupal.org/project/ai_context
Tool API: https://www.drupal.org/project/tool
Tool Belt: https://www.drupal.org/project/tool_belt
AI Integration - ECA: https://www.drupal.org/project/ai_integration_eca
MCP Server: https://www.drupal.org/project/mcp_server
DrupalCode: https://git.drupalcode.org/
Drush: https://www.drush.org/
DDEV Drupal documentation: https://ddev.readthedocs.io/

Drupal Glossary¶

Overview¶

Fences¶

Drupal Core vs Drupal CMS¶

Canvas vs Experience Builder¶

Drupal Composer Repository vs Packagist¶

Source vs Composer Projection¶

Recipe vs Module¶

Configuration vs Content¶

Canvas vs SDC¶

Tool API vs Tool Belt¶

MCP vs MCP Server¶

AI Integration - ECA vs Older AI/ECA Integrations¶

AI Context / Context Control Center vs Bluefly ContextControl¶

Drupal Work vs Factory Work¶

Core Platform Terms¶

Drupal¶

Drupal Core¶

Drupal 11¶

Drupal CMS¶

Site Template¶

Distribution¶

Composer & Package Terms¶

Composer¶

packages.drupal.org¶

Composer Lock File¶

Composer Constraint¶

Stable Release¶

Alpha / Beta / RC¶

Dev Release¶

Drupal Composer Scaffold¶

Drupal Extension Terms¶

Module¶

Contrib¶

Custom Module¶

Theme¶

Submodule¶

Project Machine Name¶

Entity System¶

Entity¶

Content Entity¶

Configuration Entity¶

Entity Type¶

Bundle¶

Content Type¶

Field¶

Base Field¶

Field Storage¶

Field Config¶

Revision¶

Default Revision¶

Translation¶

Configuration System¶

Configuration¶

Active Configuration¶

Configuration Sync Directory¶

Configuration Export¶

Configuration Import¶

Configuration Split¶

Configuration Override¶

Recipes¶

Recipe¶

recipe.yml¶

drupal-recipe¶

Recipe Composition¶

Recipe Unpack¶

Config Action¶

Recipe Update Path¶

Rendering & Frontend¶

Render Array¶

Cache Metadata¶

Cache Tags¶

Cache Contexts¶

Max-Age¶

Twig¶

Single-Directory Components (SDC)¶

Component Metadata¶

Component Plugin Manager¶

Canvas¶

Code Component¶

`packages.drupal.org`¶

`recipe.yml`¶

`drupal-recipe`¶