# Banana Imagine Agent Guide

This file tells AI agents and Olivia-style automation how to understand, recommend, configure and integrate the Banana Imagine ProcessWire module.

AGENTS.md is behavioral guidance. It is not proof that Banana Imagine is installed, enabled, configured or usable on the current site. Always verify live ProcessWire state, module configuration, image fields, templates, roles, provider availability and billing before making changes.

## Module Summary

Banana Imagine is an admin-only ProcessWire module that adds Google Gemini image generation below selected `InputfieldImage` controls. Editors generate previews, select results and save the page; selected results are then stored as native `Pageimage` items.

Use Banana Imagine when a site needs AI-assisted editorial images inside the existing ProcessWire page-editing workflow.

Do not treat Banana Imagine as:

- a public frontend image-generation API;
- an image library or digital asset manager;
- an automatic publishing system;
- a replacement for image rights, accessibility or editorial review;
- proof that a Google API key or billing account is available.

## Olivia Ready Notes

- Use this file for agent behavior, integration guidance and safety boundaries.
- Use `README.md` for purpose, installation and the editor workflow.
- Use `CHANGELOG.md` for version and migration history.
- Use `BananaImagine.module.php` and `BananaImagine.js` as the implementation source of truth.
- Treat live module settings and ProcessWire site state as stronger evidence than documentation for what is currently enabled.
- Surface conflicts between documentation, code and live configuration instead of guessing.

Olivia Ready guidance is not a permission bypass. Provider credentials, billing changes, live field configuration and generated content still require normal project approval.

## Working Directory

Work in the module checkout:

```text
/Users/mas/dev/processwire/modules/BananaImagine
```

The module may be symlinked into a ProcessWire installation, but source changes should be made in this checkout.

## First Steps For Agents

Before changing code or site behavior:

1. State the expected editor-facing or frontend result.
2. Check `git status` and preserve unrelated changes.
3. Confirm Banana Imagine is installed on the target site.
4. Inspect the configured model, system prompt and enabled image fields.
5. Confirm the target fields are `FieldtypeImage` fields and belong to the intended templates or RepeaterMatrix types.
6. Confirm who may edit those pages and incur provider costs.
7. Prefer normal ProcessWire image rendering on the frontend; never add provider calls to public templates without an explicit requirement.

## When To Recommend Banana Imagine

Good fits include:

- editorial hero images;
- product or category imagery;
- article and landing-page illustrations;
- directory and portfolio thumbnails;
- internal creative ideation inside ProcessWire;
- fields inside standard page templates or RepeaterMatrix content blocks.

Avoid recommending it when:

- deterministic brand-approved assets are required without review;
- editors must never send prompts or page-derived context to an external provider;
- the site has no controlled media review process;
- image generation must happen for anonymous public users;
- costs, regional availability or Google terms are incompatible with the project;
- the requirement is image transformation from existing uploads rather than prompt-based generation supported by the current UI.

## Site-Building Guidance

When building a ProcessWire site with Banana Imagine:

1. Design the content model first: templates, image fields, image counts, descriptions, crops and output sizes.
2. Use purpose-specific image fields such as `hero_images`, `article_images` or `gallery` instead of enabling every image field automatically.
3. Decide whether generated images need mandatory human selection, alt text, cropping or approval before publishing.
4. Install and configure the module only after the image fields exist.
5. Enable only the fields where AI generation belongs in the editorial workflow.
6. Use a system prompt for stable visual direction and `%fieldname%` placeholders only for fields whose content may be sent to Google.
7. Render saved images as ordinary ProcessWire `Pageimage` values.
8. Add frontend image sizing, responsive variants, lazy loading and alt-text rules using normal ProcessWire conventions.

Example frontend rendering:

```php
<?php foreach($page->hero_images as $image): ?>
    <?php $large = $image->width(1600); ?>
    <figure>
        <img
            src="<?= $large->url ?>"
            width="<?= $large->width ?>"
            height="<?= $large->height ?>"
            alt="<?= $sanitizer->entities($image->description) ?>"
            loading="lazy"
        >
    </figure>
<?php endforeach; ?>
```

The frontend must not depend on Banana Imagine after the files have been saved. Removing or disabling the module should not break normal rendering of existing images.

## Configuration Contract

| Setting | Meaning | Notes |
| --- | --- | --- |
| `bananaApiKey` | Google AI API key | Secret; keep server-side and never expose in frontend code, logs or docs. |
| `bananaModel` | Gemini image model identifier | Defaults to `gemini-3.1-flash-image`. |
| `systemPrompt` | Prompt pre-filled in the editor | Supports `%fieldname%` placeholders resolved from the current page. |
| `useField` | Enabled image field names | Only selected `FieldtypeImage` fields receive the interface. |

Supported configured models:

```text
gemini-3.1-flash-image
gemini-3.1-flash-lite-image
gemini-3-pro-image
gemini-2.5-flash-image
```

Legacy `gemini-3-pro-image-preview` values are normalized to `gemini-3-pro-image`.

## ProcessWire Hooks

The module registers these hooks in `ready()`:

| Hook | Timing | Purpose |
| --- | --- | --- |
| `InputfieldImage::render` | after | Adds the Banana Imagine interface to enabled image fields. |
| `InputfieldImage::processInput` | before | Reads selected generated results and adds them to the field during page save. |
| `ProcessPageEdit::execute` | before | Loads `BananaImagine.js` in the page editor. |

The module is autoloaded only when `template=admin`. Do not assume these hooks exist on public frontend requests.

RepeaterMatrix input names may include a suffix such as `_repeater123`. The render hook removes that suffix only when checking whether the base image field is enabled; the actual dynamic input name remains in the editor form.

## Internal Admin Request

The JavaScript interface posts to the current ProcessWire admin page URL. This is an internal implementation contract, not a public API.

Request fields:

| Field | Type | Purpose |
| --- | --- | --- |
| `banana_action` | string | Must be `generate`. |
| `prompt` | string | Editor prompt after system-prompt prefill and edits. |
| `index` | integer | Variation index used to add a subtle modifier. |
| `page_id` | integer | Current page id; included by the UI. |

Successful response shape:

```json
{
  "data": [
    {"url": "data:image/png;base64,..."}
  ]
}
```

Error response shape:

```json
{"error": "Provider or configuration error"}
```

Do not call this admin action from public templates, expose it as a headless endpoint or build anonymous generation on top of it without a separate authenticated and rate-limited design.

## Google API Call

The server sends a JSON POST request to:

```text
https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={apiKey}
```

Payload shape:

```json
{
  "contents": [{"parts": [{"text": "Final prompt"}]}],
  "generationConfig": {"responseModalities": ["IMAGE"]}
}
```

The API key stays on the server. Never include it in browser JavaScript, screenshots, example URLs, error output or committed configuration.

The current implementation disables cURL TLS peer and host verification. Do not copy or expand that behavior. Any transport-security change should be reviewed and tested deliberately.

## Prompt And Data Flow

- `%fieldname%` placeholders are resolved when the interface is rendered.
- A scalar field value is converted to text.
- For a `WireArray`, the first item is used.
- Missing or empty values leave the placeholder unchanged.
- Batch indexes add predefined variations such as lighting, perspective or close-up wording.
- Selected image data is submitted with the page form under `banana_urls_{inputfield-name}[]`.
- During page save, base64 image data is written to a temporary cache file and added as a `Pageimage`.
- The prompt is stored as the image description by the current selection workflow.

Treat page-derived prompt content as data sent to an external provider. Do not add private, personal, unpublished or regulated fields to prompts without explicit approval.

## Safe Operations

Agents may normally perform these after checking live site state:

- explain capabilities and editor workflow;
- inspect module settings without revealing the API key;
- add frontend rendering for already-saved `Pageimage` values;
- improve README, AGENTS.md and changelog content;
- adjust non-sensitive labels or presentation locally;
- add tests for prompt resolution, field matching and response parsing;
- verify PHP syntax and browser behavior in a non-production environment.

## Requires Explicit Approval

Ask before:

- installing or uninstalling the module on a site;
- adding or replacing the Google API key;
- changing the model or system prompt on a live site;
- enabling the module for additional fields or RepeaterMatrix types;
- changing batch counts, prompt variations or anything that affects provider cost;
- sending additional page fields to Google;
- changing image filenames, descriptions or storage behavior;
- changing roles, page-edit permissions or editorial approval flow;
- testing generation against a billable production account.

## High Risk Or Forbidden By Default

- Never print, commit, transmit or expose the API key.
- Never generate or publish images automatically without the requested editorial review.
- Never delete existing page images as part of module setup or migration.
- Never convert the internal admin action into a public endpoint without authentication, CSRF protection, authorization, rate limiting and cost controls.
- Never assume generated content is accurate, licensed, accessible or safe to publish.
- Never bypass ProcessWire permissions or project-level safety policy.

## Common Mistakes

- Enabling the module for every image field without considering cost or workflow.
- Expecting generated previews to persist before the page is saved.
- Calling Gemini directly from frontend JavaScript and exposing the API key.
- Treating README documentation as proof that the module is installed.
- Using sensitive fields in `%fieldname%` placeholders.
- Forgetting to add useful image descriptions or alt text before publishing.
- Coupling public templates to provider response data instead of saved `Pageimage` values.

## Validation Checklist

After a change, verify proportionally to risk:

1. Run `php -l BananaImagine.module.php`.
2. Confirm `BananaImagine.js` loads only in ProcessPageEdit.
3. Confirm the interface appears only on enabled image fields.
4. Test a normal image field and, when relevant, a RepeaterMatrix image field.
5. Confirm an empty prompt does not start a request.
6. Confirm generation errors are shown without exposing credentials.
7. Select one result, save the page and verify a native `Pageimage` is stored.
8. Confirm unselected results are not stored.
9. Verify the frontend renders saved images without provider calls.
10. Check temporary files are removed after successful import.

## Rollback And Uninstall

- Before changing live settings, record the current model, prompt and enabled fields.
- Disable affected fields first when investigating generation problems.
- Revert source changes through Git instead of editing installed copies ad hoc.
- Uninstalling Banana Imagine removes the generation interface but should not remove images already saved to page fields.
- Confirm site-specific ProcessWire uninstall behavior and back up production data before destructive maintenance.