Skip to content

Drupal Knowledge Index

Purpose. The single discovery entry point for any agent, Formula, Pack, Rig, or human doing Drupal work at Bluefly. It tells you which Drupal documents are authoritative, where normative rules live, where module and package ownership decisions live, where the Drupal AI architecture lives, where execution playbooks live, and where dated audits and evidence live. It points; it does not restate. If a rule is quoted here it is a pointer, and the linked file wins.

Current truth vs. historical evidence: everything under reference/, standards/, and Playbooks/ is current and maintained. Everything under ledger/ is dated observation and must be revalidated before it drives implementation.

Source specification for this index: products/Bluefly.io/bluefly-io-content-architecture-and-central-drupal-knowledge.md sections 24 through 30.

CURRENT_REFERENCE

Reference = what exists, what owns what, upstream and contrib relationships. Maintained; no raw audit dumps.

Document Answers
drupal-ai-architecture.md Current Drupal baseline, recommended AI projects, contrib-first AI architecture, delivery workflow
module-ownership-matrix.md Which contrib module owns which capability; disposition per evaluated module; last-verified date
bluefly-package-map.md Which Bluefly-owned Drupal package is still justified, which shrinks, which is replaced or contributed upstream
capability-ownership-map.md Capability to owner (core, contrib, config, recipe, Canvas, SDC, ECA, FlowDrop, Drupal AI, Tool API, MCP, Bluefly package)
../../catalog/drupal-ai-ecosystem.md Approval registry for the 345-module Drupal AI ecosystem; approval vocabulary; evaluation waves

NORMATIVE_STANDARDS

Standards = how Bluefly builds Drupal. MUST / SHOULD / MUST NOT. One rule, one owner.

Standard Owns
../../standards/core/contrib-first-policy.md The contrib-first prime directive (cross-platform)
../../standards/drupal/drupal-standard.md Drupal AI enforcement rules; Tool API as capability authority (section 7); Bluefly platform stack (section 10); Drupal ownership ladder and module = capability / recipe = composition (section 12); module evaluation record (section 13)
../../standards/drupal/drupal-site-building-standard.md Fundamental layer model; default build order; Canvas as default composition; theme ownership; contrib first and extend-don't-fork (sections 25, 26); ownership boundary table
../../standards/drupal/drupal-component-dry-standard.md Entities are the data source; Views own collections; taxonomy is data; Media is an owned type; references beat copy/paste; DRY acceptance
../../standards/drupal/how-we-build-in-drupal.md Upstream-first decision tree; discovery protocol; recipes as assembly; configuration before code; ECA as workflow layer; Canvas as composition layer; Bluefly module ownership (section 30)
../../standards/drupal/1password-drupal-secrets.md Key + 1Password Connect; no secrets in config
../../standards/drupal/ddev/ddev-standard.md DDEV as the local Drupal runtime

The in-place edits to these standards arising from the 2026-09-20 audit were applied on 2026-09-20 in the owning files: DRY sections 12, 23, 46, 48, 51, site-building sections 3, 4a, 16, drupal-standard sections 10 and 13 and how-we-build section 30.

PLAYBOOKS

Playbooks = repeatable execution procedures. Only mature procedures are promoted.

Playbook Use when
contrib-module-adoption.md Adopting a contrib module or retiring a module or Bluefly package; produces a matrix record
migration-factory-drupal.md Migrating content into a structured Drupal model with core Migrate and migrate_plus
DRUPAL-CONTRIB-FIRST-EVALUATION-PLAYBOOK.md Scoring a candidate module (green / yellow / red rubric)
DRUPAL-RECIPE-FACTORY-PLAYBOOK.md Authoring and testing a recipe
DRUPAL-CANVAS-CLI-PLAYBOOK.md Canvas code-component pull / validate / push
DRUPAL-ECA-AUTOMATION-PLAYBOOK.md Standard ECA patterns
DRUPAL-AI-CONTEXT-PLAYBOOK.md ai_context (Context Control Center) integration contract
DRUPAL-FACTORY-CONVERGENCE-PLAYBOOK.md Recipe-layer composition authority and publishing acceptance
DRUPAL-BEST-PRACTICES.md Coding invariants when custom PHP is proven necessary
DRUPAL-GASCITY-CONVOY-PLAYBOOK.md Running Drupal work as Gas City convoys and beads

MODULE_OWNERSHIP

module-ownership-matrix.md — one record per evaluated contrib module: upstream status, D11 compatibility, security coverage, capabilities, current Bluefly use and owner, overlapping Bluefly packages, disposition, what it replaces, net ownership effect, evidence link. Dispositions use the vocabulary from the specification section 25: ADOPT, ADOPT_WHEN_NEEDED, EVALUATE, DO_NOT_USE, REPLACE_BLUEFLY, KEEP_BLUEFLY, CONTRIBUTE_UPSTREAM. Every record carries LAST_VERIFIED; a record older than the current implementation decision must be revalidated with contrib-module-adoption.md.

BLUEFLY_PACKAGE_MAP

bluefly-package-map.md — every Bluefly-owned Drupal package named in the 2026-09-20 audit (contrib-ready, private, themes) with purpose, upstream owner if any, Bluefly differentiation, disposition (KEEP / SHRINK / REPLACE / CONTRIBUTE_UPSTREAM / DELETE_AFTER_MIGRATION), and overlap evidence. The justified-ownership set is small by design: protocol implementations Bluefly authors, governance extensions of upstream context plumbing, the Gas City bridge as Tool API plugins, and brand presentation.

CAPABILITY_OWNERSHIP

capability-ownership-map.md — capability to owner using the implementation precedence in the specification section 3 (Core → Contrib → Contrib configuration → Recipes / Config Actions → Canvas / SDC → Views → ECA / FlowDrop → Drupal AI → Tool API / MCP → existing Bluefly package → new custom code last). Each row links the standard that governs it.

DRUPAL_AI_ARCHITECTURE

CONTENT_MODELING

Structured content is the source of truth; pages are presentation. Fields own facts; entities own business objects; taxonomy classifies; Media owns assets; entity references build relationships; Views own collections; Canvas owns composition; SDC owns presentation.

CANVAS_SDC

TOOL_API

Tool API (drupal/tool) is the typed executable-capability owner. Protocols (MCP server, ECA, AI Agents, Drush, Gas City adapters) are adapters, not owners. Bluefly must not maintain competing tool registries.

ECA_FLOWDROP

Boundary (specification section 8): ECA = event-driven workflows; Modeler API = workflow/model abstraction; Tool API = typed executable capabilities; FlowDrop = visual/data pipeline workflows; Drupal AI = model/provider abstraction. Do not build parallel registries or workflow runtimes.

MIGRATION_FACTORY

Migration Factory composes Drupal core Migrate and migrate_plus first. It does not create private migration scaffolding where upstream owns the capability.

  • Method: migration-factory-drupal.md.
  • Classification vocabulary (12 dispositions) and the required migration map: specification section 15; reproduced as the method's CLASSIFICATION step.
  • First proof: bluefly.io itself (specification section 15) — the audit's Wave 1 replaces seed scripts and a planned private external_migration module with migrate_plus configuration.

MEDIA_EDITORIAL

  • Media is an owned data type; Drupal media owns file, alt text, metadata, focal point, reuse: drupal-component-dry-standard.md section 50.
  • Product media model (Image, Document, Remote Video, Logo) and editorial form architecture (Core / Story / Relationships / Media / Discovery / Promotion / Governance): specification sections 7 and 9.
  • Contrib owners: crop (+ focal_point), svg_image, ai_image_alt_text when media exists, media_directories under evaluation — module-ownership-matrix.md.
  • Rule (alt text required; AI alt text assists, editorial review remains; consistent form displays): site-building section 4a.

VALIDATION

AUDIT_EVIDENCE

Dated. Historical evidence, not permanent truth. Revalidate before acting.

Audit Scope
2026-09-20-bluefly-io-drupal-module-ownership-audit.md Contrib-first ownership reduction: 43 modules, 13 Bluefly packages, Wave 1 config-only actions
drupal-lane-audit-2026-09-14/README.md Drupal lane: CI producer defect, dead code, kb_cache semantic retrieval direction, method lessons

Project-local execution receipts (entity IDs, one-off scripts, MR state) stay in the owning project and its Beads; they are not copied here.

Knowledge promotion pipeline

PROJECT OBSERVATION  (consumer site, Bead, .agents/plans — proving ground)
  → LEDGER EVIDENCE   (ledger/audits, ledger/evidence — dated, tagged OBSERVED / REPORTED / INFERRED)
  → REFERENCE         (Engineering-Standard/reference/drupal — current map of what owns what)
  → STANDARD / PLAYBOOK (standards/drupal when Bluefly accepts the rule; Playbooks/drupal when it is a repeatable method)
  → PACK / FORMULA CONSUMPTION (Packs and Formulas reference the canonical file)

Promotion classes and what stays project-local are defined in the specification section 28 and in documentation-governance-standard.md section 7. Not every finding becomes a standard; a finding with no consumer stays evidence.

Consumption rule for Packs and Formulas

Packs and Formulas reference this index; they do not embed copies of it. A Drupal Formula declares its KNOWLEDGE_REFS= as repository-relative paths (this README, the matrix, the governing standard, the playbook it executes) and encodes execution only. A Drupal Pack selects agents, formulas, recipes, modules, and policies, but the reason a capability is selected must remain traceable to a file linked from this index. A Pack or Formula that carries its own module list, ownership decision, or migration strategy without a link back here is stale by definition. Specification section 27 is the contract.