| 1 | > See [`image-generator.md`](./image-generator.md) and [`image-searcher.md`](./image-searcher.md) for path-specific behavior. |
| 2 | |
| 3 | # Image Acquisition Common Reference |
| 4 | |
| 5 | Shared baseline for both acquisition paths. Path-specific behavior lives in the path's own reference. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## 1. Trigger Condition |
| 10 | |
| 11 | Active when at least one resource row has `Acquire Via: ai` / `web` / `slice`. Rows with `user` / `formula` / `placeholder` are tracked but skipped by these acquisition roles. |
| 12 | |
| 13 | | Mode | Trigger | |
| 14 | |---|---| |
| 15 | | Default Generate | `generate-ppt` workflow, `design_spec.md §VIII` image rows present | |
| 16 | | Quick Generate | [`quick-generate`](../workflows/profiles/quick-generate.md) is active and the current main agent has resolved one or more required images in active context | |
| 17 | | Standalone | Direct request against an existing project | |
| 18 | |
| 19 | --- |
| 20 | |
| 21 | ## 2. Image Resource List Format |
| 22 | |
| 23 | Default Generate uses Strategist-owned `design_spec.md §VIII` plus its lock projection. Quick Generate substitutes active-context resource decisions plus required operational manifests; it creates no planning artifact or general resource roster. Status enum: [`svg-image-embedding.md`](svg-image-embedding.md). |
| 24 | |
| 25 | | Filename | Dimensions | Purpose / Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference | |
| 26 | |---|---|---|---|---|---|---|---| |
| 27 | | `<planned file>` | `<planned size>` | `<planned role>` | `<owner-resolved recommendation>` | `adaptive` / `no-crop` | `ai` / `web` / `slice` | Pending | `<acquisition brief>` | |
| 28 | |
| 29 | **Required per non-skipped row**: `Acquire Via` and `Status`. `Reference` is required for every `web` / `slice` row and every newly authored `ai` row. An existing `ai` row whose `Reference` is omitted or blank may continue only through the declared inference in [`image-generator.md`](./image-generator.md) §8; no other path may infer it. |
| 30 | |
| 31 | **Quick Generate ownership**: explicit user assets, URLs, and path instructions win. Otherwise the main agent chooses required `user` / `ai` / `web` / `slice` / `formula` rows and AI path `auto`, without interaction. |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## 3. Path Dispatch |
| 36 | |
| 37 | For each row with `Status: Pending`: |
| 38 | |
| 39 | | Acquire Via | Load reference | Run | Success status | |
| 40 | |---|---|---|---| |
| 41 | | `ai` | [`image-generator.md`](./image-generator.md) | `image_gen.py` | `Generated` | |
| 42 | | `web` | [`image-searcher.md`](./image-searcher.md) | `image_search.py` | `Sourced` | |
| 43 | | `slice` | [`image-generator.md`](./image-generator.md) §4.3 | `slice_images.py` after parent AI sheet is `Generated` | `Generated` | |
| 44 | | `user` | — | — | (already `Existing`) | |
| 45 | | `formula` | — | — | (already `Rendered`) | |
| 46 | | `placeholder` | — | — | (already `Placeholder`) | |
| 47 | |
| 48 | > Lazy load: an all-`web` deck never reads `image-generator.md`, and vice versa. |
| 49 | |
| 50 | --- |
| 51 | |
| 52 | ## 4. Analysis Phase |
| 53 | |
| 54 | Before processing any row: |
| 55 | |
| 56 | 1. Read the Default Design Spec/lock, or reuse Quick's active-context resource and visual/page decisions |
| 57 | 2. Group resource list rows by `Acquire Via` |
| 58 | 3. Confirm `project/images/` exists |
| 59 | 4. Materialize explicit user assets, render declared formulas, and finish triggered ai/web/slice acquisition before SVG authoring begins |
| 60 | |
| 61 | --- |
| 62 | |
| 63 | ## 5. Verification Phase |
| 64 | |
| 65 | After all rows reach terminal status: |
| 66 | |
| 67 | - Every non-skipped row has a file at `project/images/<filename>`, or is marked `Needs-Manual` |
| 68 | - Every `slice` row has a generated element file, or is marked `Needs-Manual` because its parent sheet is not available |
| 69 | - No `Pending` or `Failed` rows remain |
| 70 | - `image_prompts.json` exists when ≥1 ai row processed; every entry has `status ∈ {Generated, Needs-Manual}` (no `Pending` or `Failed` remaining) |
| 71 | - `image_sources.json` exists when ≥1 web row processed; every entry has `license_tier ∈ {no-attribution, attribution-required, manual}` (`manual` = a user-supplied `--from-url` replacement) |
| 72 | |
| 73 | > `Needs-Manual` is terminal for acquisition, not export readiness. A later |
| 74 | > supplied/replaced file must be validated and its row reconciled to |
| 75 | > `Generated`, `Sourced`, or `Rendered` with the matching manifest evidence. |
| 76 | > Quick blocks every required row that still says `Needs-Manual`, regardless of |
| 77 | > whether an unverified candidate file happens to exist. See |
| 78 | > [`image-generator.md`](./image-generator.md) §7. |
| 79 | |
| 80 | --- |
| 81 | |
| 82 | ## 6. Failure Handling |
| 83 | |
| 84 | **Hard rule — automatic exhaustion before blocking**: acquisition failures MUST NOT open an interactive choice or stop while an untried permitted strategy remains. |
| 85 | |
| 86 | 1. Run the selected path's initial strategy |
| 87 | 2. On recoverable failure (network, no candidates, license rejection, rate limit), continue through materially different strategies that remain inside that path's confirmed permissions; never loop an already exhausted strategy |
| 88 | 3. When the path-specific query/provider/license-stage or backend/retry strategy is exhausted, set `Status: Needs-Manual`, log the reason in conversation, and continue |
| 89 | 4. After the phase completes, summarize all `Needs-Manual` rows for the user — list filenames, where prompts live (`images/image_prompts.md` paste-ready blocks for ai rows; refresh via `image_gen.py --render-md` if stale), and where to place generated files (`project/images/<filename>`). After supply/replacement, validate the file and reconcile the owning row plus manifest to its usable status. For `slice` rows, list the parent sheet filename and target element names; the user places the sheet, then the agent reruns `slice_images.py`. |
| 90 | |
| 91 | **Quick Generate export gate**: exhaust allowed automation without asking; stop |
| 92 | before `--quick-generate` when a required row is not both backed by its |
| 93 | validated file/provenance and in a usable status. File presence alone never |
| 94 | bypasses `Needs-Manual`. |
| 95 | |
| 96 | `Needs-Manual` is also the entry status for **Offline Manual Mode** (no `IMAGE_BACKEND` configured, no host-native image tool in use). Affected ai rows are marked `Needs-Manual` from the start without a failed attempt — see [`image-generator.md`](./image-generator.md) §7 Offline Manual Mode. |
| 97 | |
| 98 | Path-specific retry policies (provider chain, backend chain) live in the path's own reference. |
| 99 | |
| 100 | --- |
| 101 | |
| 102 | ## 7. Credits — Single Source of Truth |
| 103 | |
| 104 | License / attribution data lives **only** in `project/images/image_sources.json`. |
| 105 | |
| 106 | **Forbidden — credits anywhere else**: |
| 107 | |
| 108 | - `notes/*.md` (TTS would speak them in the audio export) |
| 109 | - `total.md` (gets split, then overwritten) |
| 110 | - SVG `<title>` / `<desc>` (stripped by `svg_to_pptx.py`) |
| 111 | - A separate "Image Credits" appendix slide (lost on single-page sharing) |
| 112 | |
| 113 | Executor reads the manifest per slide and renders inline credits when needed — see [`executor-web-image.md`](./executor-web-image.md) §1 and [`image-searcher.md`](./image-searcher.md) §7. |
| 114 | |
| 115 | --- |
| 116 | |
| 117 | ## 8. Intent Ownership |
| 118 | |
| 119 | The `Reference` field is **intent**, not a query. Strategist owns it by default; Quick's main agent resolves it in active context. The receiving role translates without reopening it. |
| 120 | |
| 121 | | ✅ Intent | ❌ Pre-processed | |
| 122 | |---|---| |
| 123 | | `"Diverse engineering team in modern office, natural light"` | `"team office light"` | |
| 124 | | `"Abstract digital waves, deep navy gradient #0A2540"` | `"use openverse, search 'waves'"` | |
| 125 | |
| 126 | --- |
| 127 | |
| 128 | ## 9. Handoff with SVG Authoring |
| 129 | |
| 130 | SVG authoring consumes the active profile's resource authority plus: |
| 131 | |
| 132 | | Artifact | Path | Purpose | |
| 133 | |---|---|---| |
| 134 | | Image files | `project/images/*.{jpg,png,webp}` | `<image>` references | |
| 135 | | Manifest | `project/images/image_sources.json` | `license_tier` per Sourced image | |
| 136 | |
| 137 | **Default Generate boundary**: Executor does NOT invoke `image_gen.py` / `image_search.py` / `slice_images.py`; missing material returns to Strategist-owned preparation. |
| 138 | |
| 139 | **Quick Generate boundary**: the main agent finishes acquisition before SVG authoring, then neither acquires nor reselects while drawing. |
| 140 | |
| 141 | --- |
| 142 | |
| 143 | ## 10. Task Completion Checkpoint |
| 144 | |
| 145 | Verify every row, file, triggered manifest/sidecar, and provenance record. |
| 146 | Default proceeds to Executor. Quick proceeds without interaction after |
| 147 | preparation and exports only when every required row has validated evidence and |
| 148 | a usable status. Report only blocking recovery. |
| 149 |