# AGENT Guide - Image Generator Tool

Independent CLI tool to capture theme screenshots via Playwright and sync image galleries to WordPress CMS theme posts.

## Scope Boundary
- **Root**: `/var/www/html/conquer-online-worktrees/ai-agent-2/tools/image-generator`
- **Isolation**: Self-contained tool. Do NOT read, modify, or reference code outside this folder.

## Architecture Map

```
index.js (CLI / Orchestrator)
 ├─> presets/<preset>.yaml          (Page routes: public & private)
 ├─> controllers/image-crawler.js   (Playwright -> screenshots/<theme>/<theme>-<page>.png)
 └─> controllers/update-wordpress.js (Screenshots -> WP Media -> Gutenberg Blocks -> CMS Theme)
      └─> services/wordpress.js     (wpapi client + CPT route: /wp/v2/cms-themes/(?P<id>))
```

## Quick Reference & Contracts

| Component | Target / Contract | Key Details |
|---|---|---|
| **Entry Point** | `index.js` | ESM (`"type": "module"`), CLI options parsing |
| **Presets** | `presets/<name>.yaml` | Maps `public` and `private` page routes. Default: `store` |
| **Env Config** | `.env` | `DEMOS_URL` / `URL`, `THEME`, `THEMES`, `PRESET`, `SKIP_WP`, `WP_EP`, `WP_USERNAME`, `WP_PASSWORD` |
| **Crawler Output** | `screenshots/{theme}/{theme}-{page}.png` | `fullPage: true`, query param `?isScreenshot` |
| **Login Selectors** | `#page-login` | `input[name=Username]`, `input[name=Password]`, `button[name=login]` |
| **WP CPT Endpoint** | `/wp/v2/cms-themes/(?P<id>)` | Custom registered route on `wpapi` |
| **Media Filter** | `caption ~= "demo-content-theme-image"` | Identifies & purges previous theme screenshots |
| **Gutenberg Layout** | `<!-- wp:columns -->` | 3-column grid (`wp-block-columns` / `wp-block-column`) |

## CLI Options & Environment Mapping

```bash
#  CLI Flag               .env Fallback       Description
#  -u, --url <url>        URL / DEMOS_URL     Target URL template
#  -t, --theme <theme>    THEME               Single theme name
#      --themes <list>    THEMES              Comma-separated themes list
#  -p, --preset <name>    PRESET              Preset name (default: "store")
#      --skip-wp          SKIP_WP             Skip WP media upload and update
```

### URL & Theme Rules
- **URL lacks `{theme}` & `--themes` provided** => Error.
- **URL lacks `{theme}` & no `--theme`** => Error (`--theme` required for directory naming).
- **URL lacks `{theme}` & `--theme` provided** => Uses static URL, stores under `screenshots/<theme>/`.
- **URL has `{theme}` & `--themes` provided** => Overrides default themes, skips `--theme`.
- **URL has `{theme}` & `--theme` provided** => Runs for single `[theme]`.
- **`--skip-wp` OR missing `WP_EP`** => Skips WordPress media & post update steps.

## Commands

```bash
# Install dependencies
npm install

# Install Playwright browser engine
npx playwright install chromium

# Run with custom theme and skip WP sync
node index.js --url "https://{theme}.cms.powerofdark.com/{pageURL}" --theme cotowers --skip-wp

# Run with custom preset
node index.js --preset store

# Docker build & execution
docker build -t node-20-playwright .
docker run -it --rm --privileged -v $(pwd):/app -w /app node-20-playwright npm start
```

## Modification Invariants
- ESM only (`import`/`export`), no CommonJS `require()`.
- Keep Playwright browser close in `finally` or end of crawl.
- Maintain Gutenberg column-balancing logic (pads empty columns to 3).
- Media deletions must pass `{ force: true }` to avoid trash retention.
- Refer to `docs/` for extended technical specs:
  - `docs/workflow.md` (flowcharts & sequences)
  - `docs/configuration.md` (CLI, env, routes, selectors)
  - `docs/api-services.md` (method signatures)