Building in Drupal — The 2026 Way¶
Bluefly.io Catalog Update · October 2, 2026¶
Revision: Post-Rotterdam 2026 · Based on live runtime discovery against
bluefly.ddev.sitePrevious verification: April 25, 2026 Source: Liveddev drushqueries + Drupal.org project research + Drupal AI Initiative blogs MUTATIONS_MADE: 0
ROTTERDAM 2026 — WHAT ACTUALLY CHANGED¶
The Inside AI / Outside AI Split¶
The Drupal AI Initiative now has two explicit product workstreams. This is not a marketing label — it reflects a genuine architectural split in how Drupal relates to AI.
INSIDE AI — person uses Drupal → Drupal uses AI to help
The editorial AI environment. A Drupal user working in the CMS gets AI assistance for their existing workflow. The AI operates within Drupal's session, permissions, and editorial context.
Current strategic priorities: - AI Search (semantic search integrated into Drupal admin) - AI content review (quality, style, compliance) - AI translation (multilingual content workflow) - Chat-driven content editing (AG-UI + AI Agents) - Bulk content updates (AI Automators) - Canvas AI / intelligent layouts (Canvas AI agents) - AI-assisted editorial workflows (ECA + AI integration) - Observability / responsible AI underneath
OUTSIDE AI — person uses an external Agent → Agent uses Drupal
The external agent environment. An AI agent (Claude, ChatGPT, coding agents, custom agents) connects to Drupal, understands it, acts on it — all under Drupal's governance.
The external Agent should be able to:
CONNECT → OAuth / MCP / authenticated identity
UNDERSTAND → discover capabilities, content model, available tools
ACT → create/edit content, compose Canvas pages, manage config
VERIFY → confirm results, check permissions, audit trail
RECOVER → rollback, draft-first, revision history
Drupal remains responsible for: structured state, identity, permissions, access, workflow, revision history, verification, rollback.
[!IMPORTANT] Do not describe Drupal AI as primarily: chatbot, text generation, RAG, or provider plugins. Those are lower-level capabilities. The architectural story is: Drupal exposes governed capabilities that both humans and agents use through the same typed contracts.
The New Front Door¶
External Agents can: build a Drupal site, extend Drupal, prepare content, inspect Drupal, operate on Drupal — while Drupal remains the system defining structured content, permissions, workflows, identity, and allowed capabilities.
The strategic goal:
AGENT OPERATES THROUGH DRUPAL'S DECLARED CAPABILITIES
AGENT RANDOMLY EDITS DATABASE / CONFIG / FILES
UPDATED LAYER STACK¶
Canvas (experience_builder)
Visual page composition · React + SDC + code components [Extension]
Recipes
Packaging / config bundles · drush recipe:apply [Core]
ECA + FlowDrop
Workflow / event logic · pipelines · approval gates [Workflow]
Modeler API
Visual modeling substrate · BPMN.io · powers ECA, AI Agents [Extension]
Tool API + Tool Belt
Execution contract · typed JSON Schema I/O [Contract]
THE ONLY SANCTIONED EXECUTABLE CONTRACT
Canvas Tools [Extension]
Agent-driven Canvas authoring through Tool API — NEW
MCP Server / Client
Protocol / external access · OAuth 2.1 · STDIO + HTTP [Protocol]
Agent Access [Recipe]
Composition: Simple OAuth + Tool API + MCP Server — NEW
AG-UI
Agent-human interaction · streaming · generative UI · SDC chat [Extension]
AI Agents (+ OSSA)
Agent orchestration · tool-calling loop · OSSA manifests [Execution]
Provider modules
LLM · embedding · VDB integrations [Integration]
AI Context (Context Control Center)
Governed prompt construction · scope-aware retrieval [Extension]
AI Core (drupal/ai)
Framework · provider abstraction · ai.provider service [Framework]
KEY ARCHITECTURAL CHANGE: Tool API is Foundational¶
Tool API is no longer just "another module." It is the common typed capability contract — one definition, many consumers:
ONE Tool definition
→ AI Agents
→ MCP clients
→ ECA actions
→ FlowDrop nodes
→ Canvas Tools
→ Drush
→ PHP
Do NOT create separate implementations for AI Agent action, MCP action, ECA action, CLI action when one Tool can own the capability.
BLUEFLY.IO RUNTIME STATE (Live Discovery — October 2, 2026)¶
DRUPAL_VERSION = 11.x (CMS 2.0)
CANVAS_VERSION = 1.0.0-beta1
CANVAS_ENTITY_REF_VERSION = 1.0.0-beta1
AI_VERSION = 1.0.0-beta4
AI_AGENTS_VERSION = 1.0.0-beta4
AI_CONTEXT_VERSION = 1.0.0-beta4
TOOL_VERSION = 1.0.0-alpha1
TOOL_BELT_VERSION = 1.0.0-alpha1
MCP_SERVER_VERSION = 1.0.x-dev
MCP_TOOLS_VERSION = 1.0.x-dev
MCP_CLIENT_VERSION = 1.0.x-dev
API_NORMALIZATION_VERSION = 1.0.x-dev
ORCHESTRATION_VERSION = 1.0.0
AI_AGENTS_OSSA_VERSION = 1.0.x-dev
AI_CKEDITOR_VERSION = 1.0.0-beta4
CANVAS_TOOLS_INSTALLED = NO (not in Composer)
AGENT_ACCESS_INSTALLED = NO (not in Composer)
AGUI_INSTALLED = NO (not installed)
ECA_INSTALLED = NO (not installed)
FLOWDROP_INSTALLED = NO (not installed)
FLOWDROP_AGENTS_INSTALLED = NO
DAEDALUS_INSTALLED = YES (1.0.x-dev) but NOT ENABLED
CONFIG_DRIFT = ZERO (clean)
SDC_FORMATTERS_IN_USE = ZERO
CANVAS_ENTITY_REF_CONFIG = NONE EXPORTED
AI_CONTEXT_CONFIG = NONE EXPORTED
AI_AGENT_CONFIGS_EXPORTED = NONE
TOOL_API_TOOLS_TOTAL = 75
api_normalization = 31
tool_belt_content = 15
tool_belt_entity = varies
tool_belt_system = varies
tool_belt_user = varies
tool_belt_workspace = varies
Canvas tools = 0
CANVAS_AI_AGENTS_IN_REGISTRY = 6
canvas_ai_orchestrator
canvas_component_agent
canvas_metadata_generation_agent
canvas_page_builder_agent
canvas_template_builder_agent
canvas_title_generation_agent
OTHER_AI_AGENTS_IN_REGISTRY = 7
taxonomy_agent
field_type_agent
node_content_type_agent
content_type_agent_triage
drupal_cms_assistant
field_agent_triage
taxonomy_agent_config
Connection Assessment¶
| Connection | Supported Upstream | Installed | Configured | Proven Working | Gap |
|---|---|---|---|---|---|
| Entity → View Modes | YES | YES | YES | YES (card views exist) | No SDC formatters wired |
| View Modes → SDC | YES (canvas_naive_render_sdc_tree) | YES | NO | NO | Formatter exists, not configured |
| SDC → Canvas | YES | YES | YES | PARTIAL | Canvas renders SDCs but via manual props |
| Canvas Entity Reference | YES | YES | NO CONFIG | NO | Module enabled, zero configuration |
| AI Agents → Tool API | YES | YES | PARTIAL | UNKNOWN | Agents exist in registry, tools exist |
| MCP → Tool API | YES | YES | PARTIAL | UNKNOWN | MCP tools exist, scope unclear |
| Canvas AI Agents → Canvas | YES | YES | UNKNOWN | UNKNOWN | 6 Canvas agents registered |
| AI Context → Agents | YES | YES | NO CONFIG | NO | Module enabled, zero context defined |
| ECA → Tool API | YES | NO | NO | NO | ECA not installed |
| FlowDrop → Tool API | YES | NO | NO | NO | FlowDrop not installed |
| AG-UI → AI Agents | YES | NO | NO | NO | AG-UI not installed |
| Canvas Tools → Tool API → Canvas | YES (upstream) | NO | NO | NO | Not in Composer |
| Agent Access → OAuth → MCP | YES (upstream) | NO | NO | NO | Not in Composer |
UPDATED MODULE CATALOG¶
Canvas Tools (canvas_tools) — NEW ENTRY¶
PROJECT = canvas_tools
PACKAGE = drupal/canvas_tools
STABILITY = Beta / Watch + Pilot
SECURITY_POLICY = Not yet covered
MAINTAINER = Acquia
DESCRIPTION = Lets AI agents or scripts build Canvas pages, page templates
and content templates through typed Tool API operations.
DRAFT_FIRST = YES — all changes go to Canvas autosave/draft system
ACCESS_MODEL = Same access checks as the Canvas editor
AGENT_SKILLS = Ships .agents/skills for page building order-of-operations
BLUEFLY_PRIORITY = P0 / EVALUATE AGGRESSIVELY
Capabilities: - Find Canvas targets (pages, templates) - Find available components - Create pages - Place and arrange components - Set component props - Bind props to entity fields - Manage page templates and content templates - Publish or discard drafts
[!IMPORTANT] Canvas Tools is the upstream answer for agent-driven Canvas authoring. It is not installed on Bluefly.io yet. Before building any custom Canvas automation, evaluate this project first.
CLASSIFICATION: PILOT_NOW
Agent Access (agent_access) — NEW ENTRY¶
PROJECT = agent_access
PACKAGE = drupal/agent_access
TYPE = Recipe (composition, not runtime)
STABILITY = Unknown — verify
MAINTAINER = Acquia
COMPOSITION = Simple OAuth + Tool API + MCP Server
PURPOSE = Safe external Agent connection with Drupal identity
The Outside AI recipe. External agents connect with their own Drupal identity. Drupal permissions determine what that user/Agent may do. Composes: - Tool Belt: create/edit content, manage fields and users, site operations - MCP Tools: content, media, taxonomy, menus, Views, site admin - ECA Tool: make ECA workflows available as tools
[!WARNING] Do NOT build a Bluefly-specific external-Agent authentication layer unless Agent Access has a proven gap.
CLASSIFICATION: PILOT_NOW
AG-UI (agui) — REFRESHED¶
PROJECT = agui
PACKAGE = drupal/agui
CURRENT_RELEASE = 1.0.4
STABILITY = Stable
SECURITY_POLICY = Covered
MAINTAINER = ImageX
AG-UI is NOT just another chatbot widget. It is the agent-human interaction surface: - Streaming chat - Tool calling with progress - Human-in-the-loop transactions - Generative UI (tool results become structured Drupal UI) - JWT support for remote calls - SDC-based chat UI - Custom tool rendering for modules
For Bluefly.io evaluate: - Drupal Admin copilot - Canvas page-building assistant - Content architecture assistant - Editorial Agent interactions - Proof/approval UI
Do NOT automatically expose public visitor chat. Admin-only initially.
CLASSIFICATION: PILOT_NOW (not currently installed)
FlowDrop (flowdrop) — REFRESHED¶
PROJECT = flowdrop
PACKAGE = drupal/flowdrop
MAINTAINER = Factorial.io
SUPPORTING_ORGS = European Commission, EU Institutions
Visual workflow orchestration for modern Drupal: - 65+ built-in nodes - Visual drag-and-drop graph editor - Workflows are standard Drupal config entities (YAML, git, drush cex/cim) - Three execution modes: Synchronous, Asynchronous, StateGraph (checkpointed/resumable) - Human-in-the-loop: pause for confirmations, approvals, forms - Event-driven triggers: entity changes, user events, cron, external - Nested workflows - Key module integration
FlowDrop Agents (flowdrop_agents):
- AI Agent Executor node (run any AI Agent in a FlowDrop workflow)
- Blueprint Mode — agents return blueprints for review before Drupal mutations
- Direct vs Blueprint mode selection
- Structured output (created/edited/deleted entities)
- Dynamic agent discovery
CLASSIFICATION: WATCH / PILOT_LATER (not currently installed, evaluate after Canvas proof)
Canvas Entity Reference (canvas_entity_reference) — CRITICAL UPDATE¶
PROJECT = canvas_entity_reference
PACKAGE = drupal/canvas_entity_reference
CURRENT_RELEASE = 1.0.0-beta1 (runtime)
STABILITY = Beta
MAINTAINER = Specbee
This is the bridge between structured entities and Canvas components. The mechanism:
- Add
x-entity-type: nodeto any SDC prop schema → becomes entity reference autocomplete in Canvas editor x-entity-field: nid→ returns numeric entity ID (forentity_render())x-entity-type-bundles: service,case_study→ restrict which bundles appearx-entity-widget: autocomplete_tags→ choose widget per-propentity_render()Twig function → render referenced entity in any view mode directly from component template- Auto-creation of terms (optional)
- Canvas live preview integration
Current Bluefly.io state: ENABLED but ZERO configuration exported. The module works, but no settings (target vocabularies, widget choice) have been saved.
CLASSIFICATION: ADOPT_NOW / CONFIGURE IMMEDIATELY
AI Agents Canvas Direct Edit (ai_agents_canvas_direct_edit) — NEW ENTRY¶
PROJECT = ai_agents_canvas_direct_edit
PACKAGE = drupal/ai_agents_canvas_direct_edit
STABILITY = Alpha / Experimental
MAINTAINER = Zivtech
Deterministic-first Canvas editing. When users make simple changes ("set the color to blue"), the result is deterministic — resolved directly from SDC schema without AI. AI is fallback only.
Patterns: - Exact and alias matches - Bare value inference - Relative adjustments ("bigger"/"smaller" navigates enum ordinals) - Boolean toggles - Reset to defaults - Compound edits
CLASSIFICATION: WATCH (pattern is strategically interesting: deterministic first → AI fallback)
AI Context / Context Control Center — CRITICAL UPDATE¶
PROJECT = ai_context
PACKAGE = drupal/ai_context
CURRENT_RELEASE = 1.0.0-beta4 (runtime) — RC 1 announced on drupal.org
STABILITY = RC
MAINTAINER = Salsa Digital, Foster Interactive, University of Edinburgh
Scope types available: - Global, Entity Type, Entity Item, Site Section, Language, Roles, Tag, Taxonomy, Use Case - Consumer types: Agent, Automator
For Bluefly.io, AI Context should supply: - Brand voice / tone guidance - Page-tier rules (Tier 0-4 composition constraints) - Service definitions for AI suggestions - CTA rules per content type - Canvas design constraints / SDC usage rules - Editorial policy - Agent constraints and boundaries
Current Bluefly.io state: ENABLED but ZERO content defined. No context configs exported.
CLASSIFICATION: ADOPT_NOW / CONFIGURE FOR PILOT
Tool API (tool) — ELEVATED IMPORTANCE¶
PROJECT = tool
PACKAGE = drupal/tool
CURRENT_RELEASE = 1.0.0-alpha1 (runtime)
STABILITY = Alpha → Beta
MAINTAINERS = EPAM, Pantheon, Acquia
THE common typed capability contract. One definition → reusable by AI Agents, MCP clients, ECA, FlowDrop, Canvas Tools, Drush, PHP.
Features: typed inputs, typed outputs, JSON Schema validation, access control, discoverability, write-once/call-anywhere.
CLASSIFICATION: ADOPT_NOW / FOUNDATIONAL
ECA — STATUS CORRECTION¶
ECA IS NOT INSTALLED ON BLUEFLY.IO
The earlier audit based on composer.lock was incorrect about the runtime state. ECA 3.1.9 may be in composer.lock but the module is not present in this runtime environment.
CLASSIFICATION: PILOT_NOW (install and configure for bounded event-driven governance)
DRUPAL 2026 FRONTIER — RANKING¶
ADOPT NOW¶
| Module | Version | Why |
|---|---|---|
| drupal/ai | 1.0.0-beta4 | Framework — already installed |
| drupal/ai_agents | 1.0.0-beta4 | Execution — Canvas agents already in registry |
| drupal/canvas | 1.0.0-beta1 | Page composition — already installed |
| drupal/canvas_entity_reference | 1.0.0-beta1 | Entity → Canvas bridge — CONFIGURE IT |
| drupal/tool | 1.0.0-alpha1 | Typed capability contract — already installed |
| drupal/tool_belt | 1.0.0-alpha1 | Content/entity tools — scope governance needed |
| drupal/ai_context | 1.0.0-beta4 | Context scoping — POPULATE IT |
| drupal/mcp_server | 1.0.x-dev | External agent transport — already installed |
| drupal/mcp_tools | 1.0.x-dev | Drupal capability exposure — already installed |
PILOT NOW¶
| Module | Status | Why |
|---|---|---|
| drupal/canvas_tools | NOT INSTALLED | Agent-driven Canvas authoring through Tool API |
| drupal/agent_access | NOT INSTALLED | Outside AI recipe (OAuth + Tool API + MCP) |
| drupal/agui | NOT INSTALLED | Agent-human interaction surface |
| drupal/eca | NOT INSTALLED | Deterministic event-driven automation |
| drupal/ai_ckeditor | Installed | Per-action editor AI assistance |
WATCH CLOSELY¶
| Module | Why |
|---|---|
| drupal/ai_agents_canvas_direct_edit | Deterministic-first Canvas editing pattern |
| drupal/flowdrop + flowdrop_agents | Visual multi-step workflows, Blueprint mode |
| Canvas AI features (Drupal CMS) | Agent-driven page generation |
| Capability description / Rosetta work | Shared agent-readable Drupal capability definitions |
| Outside AI workflows | Emerging patterns for external agent governance |
CONTRIBUTE¶
| Area | Bluefly Opportunity |
|---|---|
| Tool/API interoperability | OpenAPI → Tool through api_normalization |
| Agent-readable capability descriptions | Shared ontology for tools/components |
| Governed Canvas operations | Canvas authoring governance patterns |
| OSSA interoperability | Where genuinely useful for agent identity |
DEFER¶
| What | Why |
|---|---|
| Custom agent runtimes | AI Agents + Canvas agents already exist |
| Custom page builders | Canvas is the composition layer |
| Custom workflow engines | ECA + FlowDrop cover this |
| Custom MCP stacks | MCP Server/Tools already installed |
| Custom Tool abstractions | Tool API is the contract |
BLUEFLY.IO EXECUTION PLAN — 4-TASK BOUNDED PROOF¶
Objective¶
Prove that an authorized Agent can build a Bluefly.io page THROUGH Drupal itself.
Drupal entities → View Modes → SDC → Canvas → Draft → Human review → Publish
↑
AI Agent → Tool API → Canvas capabilities
Task 1: Wire Structured Entities to Existing SDCs¶
Current state: Card view modes exist with correct fields. SDC components exist with matching props. But they are not connected — zero SDC formatters configured.
| Entity | View Mode | SDC Target | Field → Prop Mapping |
|---|---|---|---|
| service.card | card | bluefly-service-card | field_short_title→title, field_summary→description, field_eyebrow→focus_area, path→link_url |
| proof.card | card | bluefly-evidence-panel | field_value→metric, field_unit→metric_label, field_statement→description |
| proof.stat | stat | bluefly-metric-counter | field_value→value, field_unit→label, field_statement→sublabel |
| case_study.card | card | bluefly-case-study-card | field_short_title→headline, field_summary→description, field_eyebrow→industry |
| person.card | card | bluefly-profile-card | title→name, field_role→role, field_bio→bio, field_featured_media→photo_url |
Implementation approach: Use the canvas_naive_render_sdc_tree formatter (already available) or configure Twig templates in the card view modes to render through SDC includes. Research the exact Drupal 11 mechanism for wiring view mode output through SDC templates.
Acceptance: ENTITY_VIEW_MODE_SDC=PASS
Task 2: Configure Canvas Entity Reference¶
Current state: Module enabled, zero configuration.
Configuration needed:
- Global settings:
- Target vocabularies: audience, capability_category, insight_type, platform_class, product_family, service_category, technology, topic
- Default widget: autocomplete
-
Auto-create terms: NO (initially)
-
SDC prop annotations (add to bluefly-service-card, etc.):
# Example: Add to bluefly-service-card.component.yml service_ref: type: integer title: Service Reference x-entity-type: node x-entity-type-bundles: service x-entity-field: nid -
Twig template update (use
entity_render()):{# In bluefly-service-card.html.twig #} {% if service_ref %} {{ entity_render(service_ref, 'card') }} {% endif %}
Acceptance: CANVAS_ENTITY_REFERENCE=PASS, STRUCTURED_ENTITY_RENDERED_IN_CANVAS=YES
Task 3: Create Services Landing Page Draft¶
Current state: /services exists at /page/4 (a Page node). 13 fully-populated Service entities exist.
Target composition (Tier 1 — primary navigation landing):
bluefly-hero
headline: from page node field_hero_headline
subheading: from page node field_hero_text
eyebrow: "Services"
cta_primary: "Get a Drupal Health Review"
cta_secondary: "See Our Work"
bluefly-section (columns: 3, background: white)
heading: "What We Do"
content: [13 × bluefly-service-card via entity reference]
bluefly-section (columns: 3, background: grey)
heading: "Proven Results"
content: [proof entities via bluefly-evidence-panel]
bluefly-section (columns: 2, background: white)
heading: "Our Work"
content: [case_study entities via bluefly-case-study-card]
bluefly-cta-cluster
heading: "Ready to Get Started?"
buttons: [{text: "Schedule a Drupal Health Review", url: "/contact"}]
background: dark
Create as DRAFT only. Do not publish.
Acceptance: SERVICES_PAGE_DRAFT=PASS
Task 4: Narrowly-Scoped AI Agent¶
Current state: 6 Canvas AI Agents exist in the registry (canvas_page_builder_agent, etc.) + 7 other agents (taxonomy_agent, field_type_agent, etc.)
Agent Tool Allowlist:
READ:
entity_load_by_id
entity_field_values
entity_list
entity_load_by_property
entity_metadata
entity_field_value_definitions
entity_bundle_list
entity_bundle_field_definitions
entity_type_list
CANVAS READ (if Canvas Tools installed):
find_canvas_targets
find_components
read_canvas_page
CANVAS WRITE (if Canvas Tools installed):
create_page (DRAFT ONLY)
place_component
arrange_components
set_component_props
bind_entity_field
discard_draft
WRITE:
entity_stub (DRAFT content only)
entity_save (DRAFT content only)
Agent Tool Denylist:
DESTRUCTIVE:
entity_delete
field_delete
field_storage_delete
entity_bundle_delete
workspace_delete
SITE BUILDING:
entity_bundle_add
field_add
field_storage_add
field_update
field_storage_update
entity_bundle_update
ADMIN:
user_block / user_add_role / user_remove_role
send_email
workspace_publish
API NORMALIZATION (all 31 tools — not needed for page composition):
delete_schema
delete_gateway_route
import_schema
create_gateway_routes_from_spec
generate_entity_from_schema
(... all others)
Acceptance:
AI_AGENT_CAN_READ_ARCHITECTURE = PASS
AI_AGENT_CAN_DISCOVER_COMPONENTS = PASS
AI_AGENT_CAN_COMPOSE_DRAFT = PASS (requires Canvas Tools)
AI_AGENT_CANNOT_CHANGE_SCHEMA = PASS
AI_AGENT_CANNOT_USE_DESTRUCTIVE = PASS
HUMAN_REVIEW_REQUIRED = PASS
CANVAS AGENT AUTHORING — CURRENT CAPABILITY ASSESSMENT¶
What Exists Today (Without Canvas Tools)¶
The Bluefly.io runtime has Canvas AI Agents in the registry that can orchestrate Canvas page building. These agents operate through Canvas's internal API rather than through Tool API:
canvas_ai_orchestrator → coordinates other Canvas agents
canvas_page_builder_agent → builds Canvas pages
canvas_template_builder_agent → builds Canvas templates
canvas_component_agent → manages Canvas components
canvas_metadata_generation_agent → generates page metadata
canvas_title_generation_agent → generates page titles
HOWEVER: These agents have ZERO Canvas-specific Tool API tools. They appear to work through Canvas's internal PHP API, which means they are NOT currently callable via MCP, ECA, or FlowDrop.
What Canvas Tools Would Add¶
Canvas Tools would register typed Tool API operations for Canvas authoring, making them available to: - External agents via MCP - Internal agents via Tool API - Workflows via ECA/FlowDrop - Scripts via Drush
This is the missing link.
Recommended Evaluation Path¶
1. Test existing Canvas AI Agents through Drupal admin UI
→ Can canvas_page_builder_agent build a Services page draft?
→ Does it respect entity references?
→ Does it use existing SDC components?
2. If Canvas AI Agents work well enough:
→ Use them for the pilot WITHOUT Canvas Tools
3. If they don't, or if MCP/external access is needed:
→ Install canvas_tools
→ Wire through Tool API
→ Test the full Agent → Tool API → Canvas Tools → Draft path
API NORMALIZATION — TOOL PATH ASSESSMENT¶
OPENAPI_IMPORT = INVESTIGATE (31 tools exist, capability unclear)
NORMALIZED_ENTITY = INVESTIGATE (schema entity likely exists)
TOOL_DISCOVERY = PASS (31 tools registered in Tool API)
TOOL_GENERATION = INVESTIGATE (OpenAPI → Tool bridge status unknown)
AGENT_CONSUMPTION = PASS (tools callable by AI Agents)
MCP_CONSUMPTION = PASS (MCP tools expose api_normalization)
ECA_CONSUMPTION = N/A (ECA not installed)
FLOWDROP_CONSUMPTION = N/A (FlowDrop not installed)
Potential Bluefly contribution: If the OpenAPI → normalized schema → Tool API bridge is incomplete upstream, this is where api_normalization provides value. Do not build a private bridge — search upstream first.
BLUEFLY.IO REFERENCE STACK¶
STRUCTURED CONTENT Drupal entities + fields + taxonomy
PRESENTATION View modes + SDC
PAGE COMPOSITION Canvas + Canvas Entity Reference
SITE-BUILDING ACTIONS Tool API + Tool Belt (scoped)
INSIDE AI AI Agents + AI Context + AI CKEditor
OUTSIDE AI MCP Server + MCP Tools (+ Agent Access when installed)
AGENT-HUMAN INTERACTION AG-UI (when installed)
DETERMINISTIC AUTOMATION ECA (when installed)
VISUAL MULTI-STEP FlowDrop (when justified)
EXTERNAL API INGESTION api_normalization
REUSABLE CONFIGURATION Recipes
The architectural rule: ONE CAPABILITY → MANY CONSUMERS
Tool → AI Agent → ECA → MCP → FlowDrop → Drush
UPSTREAM GAPS AND CONTRIBUTION OPPORTUNITIES¶
| Gap | Evidence | Bluefly Action |
|---|---|---|
| Canvas Tools not in Composer | Not available as a standard package yet | Monitor drupal.org, install when available |
| Agent Access not in Composer | Recipe not published yet | Monitor, use as Outside AI foundation |
| Canvas entity ref → SDC view mode bridge | No standard mechanism to wire entity card → SDC formatter | Research contrib formatters, contribute if missing |
| AI Context site architecture scope | No existing scope for "what pages exist" | Potentially contribute a site_architecture scope plugin |
| Tool API governance/scoping | No per-tool access control beyond basic permissions | Contribute governance patterns |
IMPLEMENTATION ORDER¶
PHASE 1 — PROVE THE PATH (This directive)
1. Wire entity card view modes to SDC
2. Configure Canvas Entity Reference
3. Build /services Canvas draft
4. Test Canvas AI Agent (page_builder_agent)
5. Define Agent tool allowlist/denylist
PHASE 2 — INSTALL MISSING UPSTREAM
6. Install + configure ECA (3 bounded models)
7. Install + evaluate Canvas Tools (when available)
8. Install + evaluate Agent Access
9. Install + evaluate AG-UI
10. Populate AI Context with Bluefly rules
PHASE 3 — GOVERNANCE
11. Map ONE workflow (draft→review→published→archived)
12. Create Site Architecture admin View
13. Create Content Quality admin View
14. Reconcile config drift
15. Package as Recipes
PHASE 4 — SCALE
16. Wire remaining entity types to SDC
17. Build remaining Tier 1 pages
18. Configure FlowDrop (if multi-step workflows needed)
19. Test Outside AI path (Claude → MCP → Drupal)
20. Contribute upstream gaps
CUSTOM CODE TO AVOID¶
NEVER BUILD:
Custom agent runtimes → AI Agents + Canvas agents exist
Custom page builders → Canvas + Canvas Tools
Custom workflow engines → ECA + FlowDrop
Custom MCP stacks → MCP Server/Tools installed
Custom Tool abstractions → Tool API is the contract
Custom REST tool endpoints → Tool API plugins
Custom ReAct loops → AI Agents handles this
Custom prompt assemblers → AI Context handles this
Custom entity types for → Use existing content model
plans/tasks/sessions
Direct LLM SDK calls → drupal/ai provider abstraction
NEXT 5 ACTIONS¶
1. Configure Canvas Entity Reference settings (allowed entity types, vocabularies)
2. Annotate pilot SDC component.yml files with x-entity-type props
3. Test canvas_page_builder_agent through Drupal admin
4. Build /services Canvas draft using existing Canvas AI or manual composition
5. Populate AI Context with Bluefly brand rules and tier constraints
CATALOG_UPDATED = YES (in-place)
ROTTERDAM_FINDINGS = Inside/Outside AI split, Canvas Tools, Agent Access
INSIDE_AI_STACK = AI + AI Agents + AI Context + AI CKEditor + Canvas AI agents
OUTSIDE_AI_STACK = MCP Server + MCP Tools (+ Agent Access when available)
CANVAS_TOOLS_STATUS = NOT_INSTALLED / P0_EVALUATE
AGENT_ACCESS_STATUS = NOT_INSTALLED / PILOT_WHEN_AVAILABLE
AGUI_STATUS = NOT_INSTALLED / PILOT_NOW
FLOWDROP_STATUS = NOT_INSTALLED / WATCH
AI_CONTEXT_STATUS = INSTALLED / ZERO_CONTENT / CONFIGURE_NOW
API_NORMALIZATION_STATUS = INSTALLED / 31_TOOLS / INVESTIGATE_BRIDGE
TOOL_API_STATUS = INSTALLED / 75_TOOLS / GOVERNANCE_NEEDED
ENTITY_VIEW_MODE_SDC = IMPLEMENT_NOW (Task 1)
CANVAS_ENTITY_REFERENCE = CONFIGURE_NOW (Task 2)
SERVICES_PAGE_DRAFT = BUILD_NOW (Task 3)
SITE_BUILDER_AGENT = TEST_EXISTING_CANVAS_AGENTS (Task 4)
AGENT_TOOL_ALLOWLIST = DEFINED (see §Task 4)
AGENT_TOOL_DENYLIST = DEFINED (see §Task 4)
HUMAN_REVIEW = MANDATORY (draft-first)
SITE_ARCHITECTURE_VIEW = PHASE 3
CONFIG_DRIFT = ZERO (clean — different from earlier audit)
UPSTREAM_GAPS = Canvas Tools not published, Agent Access not published
BLUEFLY_CONTRIBUTION_OPPORTUNITIES = SDC formatter bridge, site architecture scope, tool governance
CUSTOM_CODE_CREATED = 0
MUTATIONS_MADE = 0