Feature: PhotoBuilder — AI image generation for content pages

.env

@@ -67,6 +67,10 @@ LLM_CONTENT_EDITOR_OPENAI_API_KEY=your-key-here
 # Set to "1" to enable raw LLM provider API wire logging (request + response payloads).
 # Enabled by default in dev via .env.dev. Override per environment as needed.
 LLM_WIRE_LOG_ENABLED=0
+
+# PhotoBuilder: set to 1 to use fake/simulated adapters instead of real OpenAI calls
+PHOTO_BUILDER_SIMULATE_IMAGE_PROMPT_GENERATION=0
+PHOTO_BUILDER_SIMULATE_IMAGE_GENERATION=0
 ###< sitebuilder/llm-wire-log ###
 
 ###> sitebuilder/docker-execution ###

assets/bootstrap.ts

@@ -13,6 +13,8 @@ import ManifestUrlsController from "../src/ProjectMgmt/Presentation/Resources/as
 import S3CredentialsController from "../src/ProjectMgmt/Presentation/Resources/assets/controllers/s3_credentials_controller.ts";
 import RemoteAssetBrowserController from "../src/RemoteContentAssets/Presentation/Resources/assets/controllers/remote_asset_browser_controller.ts";
 import HtmlEditorController from "../src/ChatBasedContentEditor/Presentation/Resources/assets/controllers/html_editor_controller.ts";
+import PhotoBuilderController from "../src/PhotoBuilder/Presentation/Resources/assets/controllers/photo_builder_controller.ts";
+import PhotoImageController from "../src/PhotoBuilder/Presentation/Resources/assets/controllers/photo_image_controller.ts";
 
 const app = startStimulusApp();
 
@@ -27,5 +29,7 @@ app.register("manifest-urls", ManifestUrlsController);
 app.register("s3-credentials", S3CredentialsController);
 app.register("remote-asset-browser", RemoteAssetBrowserController);
 app.register("html-editor", HtmlEditorController);
+app.register("photo-builder", PhotoBuilderController);
+app.register("photo-image", PhotoImageController);
 
 webuiBootstrap(app);

config/packages/asset_mapper.yaml

@@ -6,6 +6,7 @@ framework:
             - src/ChatBasedContentEditor/Presentation/Resources/assets/controllers/
             - src/ProjectMgmt/Presentation/Resources/assets/controllers/
             - src/RemoteContentAssets/Presentation/Resources/assets/controllers/
+            - src/PhotoBuilder/Presentation/Resources/assets/controllers/
         missing_import_mode: strict
 
 sensiolabs_typescript:
@@ -14,6 +15,7 @@ sensiolabs_typescript:
         - "%kernel.project_dir%/src/ChatBasedContentEditor/Presentation/Resources/assets/controllers/"
         - "%kernel.project_dir%/src/ProjectMgmt/Presentation/Resources/assets/controllers/"
         - "%kernel.project_dir%/src/RemoteContentAssets/Presentation/Resources/assets/controllers/"
+        - "%kernel.project_dir%/src/PhotoBuilder/Presentation/Resources/assets/controllers/"
 
 when@prod:
     framework:

config/packages/doctrine.yaml

@@ -51,6 +51,12 @@ doctrine:
                 dir: "%kernel.project_dir%/src/WorkspaceMgmt/Domain/Entity"
                 prefix: 'App\WorkspaceMgmt\Domain\Entity'
 
+            App\PhotoBuilder\Domain\Entity:
+                type: attribute
+                is_bundle: false
+                dir: "%kernel.project_dir%/src/PhotoBuilder/Domain/Entity"
+                prefix: 'App\PhotoBuilder\Domain\Entity'
+
         controller_resolver:
             auto_mapping: false
 

config/packages/twig.yaml

@@ -7,8 +7,10 @@ twig:
         "src/Account/Presentation/Resources/templates": "account.presentation"
         "src/ChatBasedContentEditor/Presentation/Resources/templates": "chat_based_content_editor.presentation"
         "src/ProjectMgmt/Presentation/Resources/templates": "project_mgmt.presentation"
+        "src/RemoteContentAssets/Presentation/Resources/templates": "remote_content_assets.presentation"
         "src/WorkspaceMgmt/Presentation/Resources/templates": "workspace_mgmt.presentation"
         "src/Organization/Presentation/Resources/templates": "organization.presentation"
+        "src/PhotoBuilder/Presentation/Resources/templates": "photo_builder.presentation"
 
 when@test:
     twig:

config/services.yaml

@@ -168,6 +168,21 @@ services:
     # Conversation log formatter - human-readable plain-text output
     App\LlmContentEditor\Infrastructure\ConversationLog\ConversationLogFormatter: ~
 
+    # PhotoBuilder infrastructure bindings
+    App\PhotoBuilder\Infrastructure\Storage\GeneratedImageStorage:
+        arguments:
+            - "%kernel.project_dir%/var/photo-builder"
+
+    App\PhotoBuilder\Infrastructure\Adapter\PromptGeneratorInterface:
+        class: App\PhotoBuilder\Infrastructure\Adapter\OpenAiPromptGenerator
+
+    App\PhotoBuilder\Infrastructure\Adapter\ImageGeneratorInterface:
+        class: App\PhotoBuilder\Infrastructure\Adapter\OpenAiImageGenerator
+
+    App\PhotoBuilder\Infrastructure\Adapter\OpenAiImageGenerator: ~
+    App\PhotoBuilder\Infrastructure\Adapter\GeminiImageGenerator: ~
+    App\PhotoBuilder\Infrastructure\Adapter\ImageGeneratorFactory: ~
+
     # LLM content editor facade - inject loggers + enable flag
     App\LlmContentEditor\Facade\LlmContentEditorFacade:
         arguments:

docker-compose.yml

@@ -29,7 +29,8 @@ services:
         build:
             context: .
             dockerfile: docker/app/Dockerfile
-        container_name: etfs_${ETFS_PROJECT_NAME}_messenger
+        deploy:
+            replicas: 5
         volumes:
             - .:/var/www
             - mise_data:/opt/mise

docs/frontendbook.md

@@ -91,6 +91,23 @@ Bind **actions** to DOM events (e.g. `submit`, `click`):
 
 `stimulus_action(controllerName, methodName, event)`. Omit the third argument to use the default event for the element (e.g. `submit` for forms, `click` for buttons).
 
+#### Multiple actions on the same element
+
+**IMPORTANT**: Each `{{ stimulus_action(...) }}` call renders its own `data-action` HTML attribute. If you place multiple calls on the same element, only the first takes effect — HTML silently discards duplicate attributes.
+
+To bind **multiple actions** on an element that also has `stimulus_controller`, chain the `|stimulus_action` **filter** off the controller call:
+
+```twig
+<div {{ stimulus_controller('photo-builder', { ... })
+     |stimulus_action('photo-builder', 'handlePromptEdited', 'photo-image:promptEdited')
+     |stimulus_action('photo-builder', 'handleRegenerate', 'photo-image:regenerateRequested')
+     |stimulus_action('photo-builder', 'handleUpload', 'photo-image:uploadRequested') }}>
+```
+
+This pipes the `StimulusAttributes` object through each filter, accumulating all action descriptors into a single `data-action` attribute.
+
+The same principle applies to `|stimulus_target` — use the filter form when combining with other Stimulus helpers on the same element.
+
 ---
 
 ## 3. Controller Structure (TypeScript)
@@ -229,7 +246,8 @@ Handle non‑OK responses and parse JSON or streamed bodies as needed.
 5. **Twig**  
    - `{{ stimulus_controller('kebab-name', { … }) }}` for the element that owns the behavior.  
    - `{{ stimulus_target('kebab-name', 'targetName') }}` on elements the controller needs.  
-   - `{{ stimulus_action('kebab-name', 'methodName', 'event') }}` to wire events.
+   - `{{ stimulus_action('kebab-name', 'methodName', 'event') }}` to wire events.  
+   - **Multiple actions on one element**: use `|stimulus_action` filter chaining, never multiple `{{ stimulus_action() }}` calls (see section 2.4).
 
 6. **Build and quality**  
    - `mise run frontend`  
@@ -313,7 +331,75 @@ This pattern ensures:
 
 ---
 
-## 6. References
+## 6. Parent-to-Child Communication Between Controllers
+
+When a parent Stimulus controller needs to notify child controllers (e.g. an orchestrator telling per-item controllers to update), **dispatch the event on each child element, not on the parent**.
+
+### The Pitfall
+
+DOM events **bubble upward** (child → parent → document), never downward. If a parent dispatches an event on its own element, child controllers listening on *their* elements will never receive it — even with `bubbles: true`:
+
+```ts
+// BAD: event fires on the parent element and bubbles UP to document.
+// Child controllers listening on their own elements never see it.
+this.element.dispatchEvent(
+    new CustomEvent("my-controller:doSomething", { bubbles: true }),
+);
+```
+
+The child's Twig wiring listens on the child element:
+
+```twig
+<div {{ stimulus_controller('child-ctrl')
+     |stimulus_action('child-ctrl', 'doSomething', 'my-controller:doSomething') }}>
+```
+
+This means the `data-action` is on the **child** `<div>`, so it only captures `my-controller:doSomething` events that fire **on or below** that `<div>`.
+
+### The Correct Pattern
+
+Iterate over the child target elements and dispatch directly on each one:
+
+```ts
+// GOOD: event fires on each child element, where the action listener lives.
+for (const card of this.childCardTargets) {
+    card.dispatchEvent(
+        new CustomEvent("my-controller:doSomething", { bubbles: false }),
+    );
+}
+```
+
+This matches the pattern used for per-element state updates (e.g. passing poll data to each card):
+
+```ts
+for (const card of this.imageCardTargets) {
+    card.dispatchEvent(
+        new CustomEvent("photo-builder:stateChanged", {
+            detail: imageData,
+            bubbles: false,
+        }),
+    );
+}
+```
+
+### When to Use Each Direction
+
+| Direction | Mechanism | Example |
+|---|---|---|
+| **Child → Parent** | `bubbles: true` on the child element; parent listens via `\|stimulus_action` filter | Child card emits `photo-image:uploadRequested`, parent catches it |
+| **Parent → Child** | Loop over child targets, dispatch on each | Parent tells all children to clear prompt text |
+| **Sibling → Sibling** | Go through a shared parent, or use `window` events | Rarely needed; prefer parent orchestration |
+
+### Key Points
+
+1. **Always dispatch on the element where the listener lives** — that's the element with the `data-action` attribute
+2. **Use `bubbles: false`** for parent-to-child events — there is no reason for them to propagate further
+3. **Use Stimulus targets** (e.g. `imageCardTargets`) to collect the child elements to dispatch on
+4. **Child-to-parent** naturally works with bubbling — the child dispatches, the event bubbles up to the parent's element
+
+---
+
+## 7. References
 
 - **Rules**: `.cursor/rules/05-frontend.mdc` (TypeScript, Stimulus, quality).
 - **Architecture**: `docs/archbook.md` — Client-Side Organization, vertical layout.

docs/llm-usage-book.md

@@ -0,0 +1,144 @@
+# LLM Usage Book
+
+How AI models are used in this application, which providers are supported, and how per-project configuration works.
+
+---
+
+## 1. Concerns
+
+The application has two distinct AI-powered concerns, each with its own provider and API key configuration:
+
+| Concern | Description | Configured via |
+|---|---|---|
+| **Content Editing** | Chat-based content editor that rewrites and creates web page content | `contentEditingLlmModelProvider` + `contentEditingLlmModelProviderApiKey` |
+| **PhotoBuilder** | Generates image prompts from page content, then generates images from those prompts | `photoBuilderLlmModelProvider` + `photoBuilderLlmModelProviderApiKey` (or falls back to content editing settings) |
+
+### Content Editing
+
+The content editing concern powers the `ChatBasedContentEditor` vertical. An LLM agent (`ContentEditorAgent`) receives the current page content plus user instructions and streams back edits. This is the primary feature of the application and its provider/key are **always required** on every project.
+
+### PhotoBuilder
+
+The PhotoBuilder concern has two sub-steps:
+
+1. **Image Prompt Generation** -- An LLM agent (`ImagePromptAgent`) reads the page HTML and generates descriptive prompts for each image, plus a descriptive filename. This is a text-generation task using tool calls.
+2. **Image Generation** -- An image-generation model turns each prompt into a PNG image. This is a dedicated image-generation API call.
+
+Both sub-steps use the same provider and API key (the project's PhotoBuilder settings).
+
+---
+
+## 2. Providers
+
+| Provider | Enum value | Content Editing | Image Prompt Generation | Image Generation |
+|---|---|---|---|---|
+| **OpenAI** | `openai` | Yes (required) | Yes | Yes |
+| **Google Gemini** | `google` | No | Yes | Yes |
+
+OpenAI is the only provider available for content editing. For the PhotoBuilder, either OpenAI or Google Gemini can be used.
+
+---
+
+## 3. Models
+
+### Content Editing
+
+| Provider | Model | Enum | Purpose |
+|---|---|---|---|
+| OpenAI | `gpt-5.2` | `LlmModelName::Gpt52` | Text generation for content editing |
+
+### PhotoBuilder -- Image Prompt Generation
+
+| Provider | Model | Enum | Purpose |
+|---|---|---|---|
+| OpenAI | `gpt-5.2` | `LlmModelName::Gpt52` | Text generation with tool calls to produce image prompts |
+| Google | `gemini-3-pro-preview` | `LlmModelName::Gemini3ProPreview` | Text generation with tool calls to produce image prompts |
+
+### PhotoBuilder -- Image Generation
+
+| Provider | Model | Enum | Purpose |
+|---|---|---|---|
+| OpenAI | `gpt-image-1` | `LlmModelName::GptImage1` | Image generation from text prompt |
+| Google | `gemini-3-pro-image-preview` | `LlmModelName::Gemini3ProImagePreview` | Image generation from text prompt |
+
+---
+
+## 4. Per-Project Configuration
+
+Each project stores two sets of LLM settings:
+
+### Content Editing (mandatory)
+
+- `contentEditingLlmModelProvider` -- always `openai` (the only supported provider for content editing)
+- `contentEditingLlmModelProviderApiKey` -- the user's OpenAI API key
+
+These fields are required when creating or editing a project.
+
+### PhotoBuilder (optional, with fallback)
+
+- `photoBuilderLlmModelProvider` -- `openai` or `google`, nullable
+- `photoBuilderLlmModelProviderApiKey` -- the matching API key, nullable
+
+**Fallback rule**: When the PhotoBuilder fields are `null`, the application uses the content editing provider and API key for the PhotoBuilder. This is the default for all projects, including prefab-created projects.
+
+The project form offers two options:
+
+- **Option A** -- "Use Content Editing LLM settings for image generation" (default). No additional fields are shown. Under the hood, PhotoBuilder fields remain `null`.
+- **Option B** -- "Use dedicated LLM settings for image generation". The user selects a provider (OpenAI or Google) and provides an API key. The same one-click key reuse UI is available.
+
+### Effective Provider Resolution
+
+```
+function getEffectivePhotoBuilderProvider():
+    if photoBuilderLlmModelProvider is not null:
+        return photoBuilderLlmModelProvider
+    return contentEditingLlmModelProvider
+
+function getEffectivePhotoBuilderApiKey():
+    if photoBuilderLlmModelProviderApiKey is not null:
+        return photoBuilderLlmModelProviderApiKey
+    return contentEditingLlmModelProviderApiKey
+```
+
+---
+
+## 5. Prefab Projects
+
+Prefab-based projects (created automatically when a new organization is set up) always use **Option A** -- the PhotoBuilder fields are not set in the prefab YAML and default to `null`, meaning they reuse the content editing settings.
+
+The `keysVisible` flag in the prefab configuration controls whether API keys are shown to users in the project form. When `keysVisible` is `false`, keys are used by the application but never displayed or editable.
+
+---
+
+## 6. Key Security
+
+- API keys are stored encrypted at rest in the database.
+- The `keysVisible` flag prevents prefab-managed keys from being shown in the UI.
+- The one-click key reuse feature only shows abbreviated keys (`sk-abc...xyz`) and filters by organization to prevent cross-organization leakage.
+- API keys are never sent to the frontend; verification happens server-side via dedicated AJAX endpoints.
+
+---
+
+## 7. Architecture
+
+### Prompt Generation
+
+The `ImagePromptAgent` (NeuronAI agent) supports both providers:
+
+- **OpenAI**: uses `NeuronAI\Providers\OpenAI\OpenAI` with model `gpt-5.2`
+- **Google**: uses `NeuronAI\Providers\Gemini\Gemini` with model `gemini-3-pro-preview`
+
+The agent's `provider()` method selects the right NeuronAI provider based on the project's effective PhotoBuilder provider.
+
+### Image Generation
+
+Image generation uses dedicated adapter classes behind `ImageGeneratorInterface`:
+
+- `OpenAiImageGenerator` -- calls OpenAI's `/v1/images/generations` endpoint with model `gpt-image-1`
+- `GeminiImageGenerator` -- calls Google's `generativelanguage.googleapis.com` endpoint with model `gemini-3-pro-image-preview`
+
+A `PhotoBuilderImageGeneratorFactory` selects the correct adapter based on the project's effective PhotoBuilder provider.
+
+### Content Editing
+
+Content editing is handled by the `ContentEditorAgent` (NeuronAI agent) using OpenAI exclusively. This path is not affected by the PhotoBuilder provider configuration.

docs/vertical-wiring.md

@@ -8,6 +8,7 @@ flowchart LR
         direction TB
         CBCE["ChatBasedContentEditor"]
         LLM["LlmContentEditor"]
+        PB["PhotoBuilder"]
         WSM["WorkspaceMgmt"]
         WST["WorkspaceTooling"]
         ORG["Organization"]
@@ -37,6 +38,11 @@ flowchart LR
     LLM -->|tools: build, preview, assets, rules| WSTF
     LLM -->|getAgentConfigTemplate| PRJF
 
+    PB -->|getAccountInfoByEmail| ACC
+    PB -->|getProjectInfo| PRJF
+    PB -->|readWorkspaceFile, getWorkspaceById| WSMF
+    PB -->|uploadAsset| RCAF
+
     WSM -->|getProjectInfo| PRJF
     WSM -->|getLatestConversationId| CBCEF
 
@@ -67,6 +73,7 @@ Method details are in the summary table below.
 |---------------------------|----------------------------|--------------|
 | **ChatBasedContentEditor** | Account, ProjectMgmt, WorkspaceMgmt, LlmContentEditor | Workspace lifecycle, commitAndPush, streamEditWithHistory, buildAgentContextDump, account resolution |
 | **LlmContentEditor**      | WorkspaceTooling, ProjectMgmt | runQualityChecks, runTests, runBuild, suggestCommitMessage, getPreviewUrl, list/search remote assets, getWorkspaceRules; getAgentConfigTemplate (EditContentCommand) |
+| **PhotoBuilder**           | Account, ProjectMgmt, WorkspaceMgmt, RemoteContentAssets | getAccountInfoByEmail; getProjectInfo (API key, S3 config); readWorkspaceFile (page HTML), getWorkspaceById; uploadAsset (S3) |
 | **WorkspaceMgmt**         | ProjectMgmt, ChatBasedContentEditor | getProjectInfo (setup, git, review); getLatestConversationId (reviewer UI) |
 | **WorkspaceTooling**      | RemoteContentAssets        | fetchAndMergeAssetUrls, getRemoteAssetInfo |
 | **Organization**         | Prefab, ProjectMgmt, WorkspaceMgmt, Account | loadPrefabs, createProjectFromPrefab, dispatchSetupIfNeeded; account resolution and registration |
@@ -81,3 +88,4 @@ Method details are in the summary table below.
 - **WorkspaceTooling** delegates remote asset listing/info to **RemoteContentAssets**.
 - **Organization** onboarding (AccountCoreCreatedSymfonyEventSubscriber) wires **Prefab → ProjectMgmt → WorkspaceMgmt** to create projects and dispatch setup.
 - **ProjectMgmt** presentation layer coordinates **ChatBasedContentEditor**, **WorkspaceMgmt**, **LlmContentEditor**, and **RemoteContentAssets** for project/workspace/conversation and validation flows.
+- **PhotoBuilder** reads workspace page HTML via **WorkspaceMgmt**, fetches API keys and S3 config via **ProjectMgmt**, uploads generated images via **RemoteContentAssets**, and validates user access via **Account**.