>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3584815. --> Reported by: [tim bozeman](https://www.drupal.org/user/2241356) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The context/metadata system used <code>usage_notes</code> and <code>schema_meta</code> naming which was inconsistent and unclear. The <code>hook_entity_blueprint_schema_meta_alter</code> hook name didn't clearly convey its purpose, and the system lacked a declarative (non-PHP) way to provide context and managed keys &mdash; modules had to implement hooks even for purely static data.</p> <p>The <code>EntityStorageHandler</code> lived in the <code>entity_blueprint_ai</code> sub-module despite being a general-purpose storage routing service, limiting reuse by other consumers of the base module.</p> <p>Field handlers had no mechanism to advertise the input formats they accept, forcing AI consumers to rely on hardcoded documentation or system prompts to understand field type semantics.</p> <p>There was no workspace enforcement &mdash; AI tools could persist content changes directly to the live environment without requiring an active workspace, creating risk of unreviewed changes in production.</p> <p>The schema builder did not check entity access, allowing schema retrieval for bundles the current user cannot create. Layout components always required an explicit <code>region</code> even for single-region layouts, adding unnecessary verbosity for the most common case.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Context system refactor:</strong></p> <ul> <li>Rename <code>usage_notes</code> to <code>guidance</code> and <code>hook_entity_blueprint_schema_meta_alter</code> to <code>hook_entity_blueprint_context_alter</code> throughout.</li> <li>Add YAML file discovery for both context (<code>MODULE.entity_blueprint.context.yml</code>) and managed keys (<code>MODULE.entity_blueprint.managed_keys.yml</code>), with scoped variants for entity_type/bundle-specific declarations (<code>MODULE.entity_blueprint.context.ENTITY_TYPE.BUNDLE.yml</code>).</li> <li>Three-layer precedence: universal YAML &rarr; scoped YAML &rarr; hooks (alter always wins). Uses <code>array_replace_recursive()</code> for clean scalar replacement.</li> <li>Add a <code>field_types</code> context level so modules can provide or override guidance per field type.</li> </ul> <p><strong>Field handler guidance:</strong></p> <ul> <li>Add <code>getGuidance(): ?string</code> to <code>FieldHandlerInterface</code>. All handlers implement it with concise LLM-facing descriptions of accepted input formats.</li> <li>Guidance is collected by <code>BlueprintSchemaBuilder</code> into a deduplicated <code>field_types</code> section in schema output, and also included per-field in field info.</li> </ul> <p><strong>Workspace enforcement:</strong></p> <ul> <li>Move <code>EntityStorageHandler</code> from <code>entity_blueprint_ai</code> to the base <code>entity_blueprint</code> module as a proper service (<code>entity_blueprint.storage_handler</code>).</li> <li>Add <code>WorkspaceRequiredException</code> and workspace checking to <code>EntityStorageHandler::persist()</code>.</li> <li>Add configurable <code>require_workspace</code> setting (default: TRUE) with admin form at <code>/admin/config/content/entity-blueprint</code>.</li> <li>Add <code>SettingsFormTrait</code> for shared form elements, used by both the standalone <code>SettingsForm</code> and a <code>SettingsFormAlter</code> hook class that embeds settings in the Plus Suite form.</li> <li>Add <code>requireWorkspace()</code> helper to <code>EntityBlueprintToolBase</code> &mdash; all AI write tools call it at the top of <code>execute()</code>. When a workspace is required, the tool returns available workspaces and instructs the AI to ask the user before choosing.</li> <li>Add <code>SwitchWorkspace</code> AI tool plugin for switching to or creating workspaces.</li> </ul> <p><strong>Other improvements:</strong></p> <ul> <li>Schema builder now checks bundle create access before returning schema.</li> <li>Single-region layouts no longer require explicit <code>region</code> on components &mdash; both the structural validator and layout deserializer auto-resolve the default region.</li> <li>Add <code>hook_entity_blueprint_entity_persisted</code> to the base module (fires from <code>EntityStorageHandler</code> after every successful persist).</li> <li>Rename the AI sub-module's persist hook to <code>hook_entity_blueprint_ai_tool_persisted</code> for clarity, and change its <code>$save</code> parameter to <code>$is_new</code>.</li> <li><code>GenerateImage</code> now routes through <code>EntityStorageHandler::persist()</code> instead of calling <code>$media-&amp;gt;save()</code> directly.</li> <li>Rename schema key <code>layout_builder</code> to <code>layout_builder__layout</code> to match the actual field name.</li> <li>Remove unused <code>workflow_hint</code> from serializer output.</li> <li>Reorder <code>ALWAYS_SKIP_FIELDS</code> and add <code>entity_workflow_content</code> to the skip list.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <ul> <li>New admin settings form at <code>/admin/config/content/entity-blueprint</code> with a "Require workspace for content changes" checkbox (visible only when the Workspaces module is enabled).</li> <li>Module now has a "Configure" link on the Extend page pointing to this settings form.</li> <li>Entity Blueprint settings are also embedded in the Plus Suite settings form when that module is present.</li> </ul> <h3 id="summary-api-changes">API changes</h3> <ul> <li><strong>Renamed hook:</strong> <code>hook_entity_blueprint_schema_meta_alter</code> &rarr; <code>hook_entity_blueprint_context_alter</code>. Parameter renamed from <code>$meta</code> to <code>$context</code>.</li> <li><strong>Renamed key:</strong> <code>usage_notes</code> &rarr; <code>guidance</code> in all schema output and context arrays.</li> <li><strong>Renamed schema key:</strong> <code>layout_builder</code> &rarr; <code>layout_builder__layout</code> in schema output.</li> <li><strong>New hook:</strong> <code>hook_entity_blueprint_context_alter</code> supports a <code>field_types</code> level for per-field-type guidance.</li> <li><strong>New hook:</strong> <code>hook_entity_blueprint_entity_persisted</code> in the base module (fires after <code>EntityStorageHandler::persist()</code>).</li> <li><strong>Renamed hook (AI sub-module):</strong> <code>hook_entity_blueprint_entity_persisted</code> &rarr; <code>hook_entity_blueprint_ai_tool_persisted</code> with <code>$save</code> renamed to <code>$is_new</code>.</li> <li><strong>New interface method:</strong> <code>FieldHandlerInterface::getGuidance(): ?string</code>.</li> <li><strong>Moved service:</strong> <code>entity_blueprint_ai.storage_handler</code> &rarr; <code>entity_blueprint.storage_handler</code> (class moved from <code>Drupal\entity_blueprint_ai</code> to <code>Drupal\entity_blueprint</code> namespace).</li> <li><strong>New exception:</strong> <code>WorkspaceRequiredException</code> thrown by <code>EntityStorageHandler::persist()</code>.</li> <li><strong>New AI tool plugin:</strong> <code>entity_blueprint:switch_workspace</code> (<code>SwitchWorkspace</code>).</li> <li><strong>YAML discovery:</strong> Modules can now declare managed keys and context via YAML files instead of hooks.</li> <li><strong>Schema builder</strong> now requires create access for the bundle; throws <code>BlueprintException</code> on access denied.</li> <li><strong>Region omission:</strong> Components in single-region layouts no longer require an explicit <code>region</code>.</li> </ul> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New config object <code>entity_blueprint.settings</code> with a single <code>require_workspace</code> boolean property (default: <code>TRUE</code>).</p>