| 1 | > See [`image-generator.md`](./image-generator.md) and [`image-searcher.md`](./image-searcher.md) for path-specific behavior. |
| 2 | |
| 3 | # Image Acquisition and Preparation 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`, or when any §VIII / Quick active-context resource is a pending prepared derivative. Canonical rows with `user` / `placeholder` are tracked but skipped by 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, every newly authored `ai` row, and every prepared derivative regardless of source class. 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` rows and AI path `auto`, without interaction. |
| 32 | |
| 33 | **Mandatory — consume the resolved path**: Default consumes Strategist-chosen §VIII rows; Quick resolves once in active context before preparation. This phase never adds or reselects a treatment: |
| 34 | |
| 35 | | Path | Behavior | |
| 36 | |---|---| |
| 37 | | `none` | Use the canonical bitmap unchanged | |
| 38 | | `native` | No new file; SVG owns crop/clip, transform, opacity, frame/shadow/scrim/vignette, and overlap | |
| 39 | | `prepared derivative` | Separate file only for pixel blur, desaturation/grayscale, duotone, brightness/contrast, or existing cutout/registered-layer preparation | |
| 40 | |
| 41 | Choosing `none` is valid. Never bake a native treatment into a derivative. |
| 42 | |
| 43 | **Reference — exact pattern mapping, not activation**: An adopted pattern may use this mapping; its id alone creates nothing. |
| 44 | |
| 45 | | Pattern | Preparation | |
| 46 | |---|---| |
| 47 | | `P*`, `M*`, `C*` | Use existing assets with native SVG/PPT composition; no automatic derivative | |
| 48 | | `A1-02` / `A1-03` | `image_treat.py` blur / duotone | |
| 49 | | `A1-01` / `A1-04` | Existing prepared composite or host/AI path; `image_treat.py` does not blend | |
| 50 | | `A2-01` | Existing/host-prepared RGBA or flat-key AI/slice asset; when source-scene registration is required, use `A2-02` / `A2-03` + [`image-generator.md`](./image-generator.md) §4.4 | |
| 51 | | `A2-02` / `A2-03` | [`image-generator.md`](./image-generator.md) §4.4 registered layers | |
| 52 | | `A2-04` | Existing/host-prepared transparent frame or device asset via the `A2-01` paths, plus an existing content picture registered beneath it; no automatic derivative | |
| 53 | | `A3-01` | Original/subject plus registered `image_treat.py` blur/tone/desaturate derivative | |
| 54 | | `A3-02` | Registered full-canvas `image_treat.py` blur derivative; crop panels natively | |
| 55 | | `A3-03` | `image_treat.py` desaturated base plus existing/§4.4 color subject layer | |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## 3. Path Dispatch |
| 60 | |
| 61 | Classify `Reference: Derived from <canonical bare filename>; treatment=<operation>; ...` before `Acquire Via`. Its distinct, non-derived parent must be `user`, `web`, `ai`, or `slice`; reject placeholder parents, chains, cycles, and self-reference. For each Pending row: |
| 62 | |
| 63 | | Row kind / Acquire Via | Load reference | Run | Success status | |
| 64 | |---|---|---|---| |
| 65 | | Deterministic prepared derivative | This common reference | After parent is usable, run `image_treat.py` to a distinct `.png`; preserve source | Inherit parent: `user → Existing`, `web → Sourced`, `ai/slice → Generated` | |
| 66 | | Registered-layer derivative | [`image-generator.md`](./image-generator.md) §4.4 | After parent is usable, run §4.4 | Supplied final: `user → Existing`; generated/reconstructed: `ai → Generated` | |
| 67 | | `ai` | [`image-generator.md`](./image-generator.md) | `image_gen.py` | `Generated` | |
| 68 | | `web` | [`image-searcher.md`](./image-searcher.md) | `image_search.py`; with vision, bounded thumbnail pages then one selected original; without vision, strict metadata-ranked best-only | `Sourced` (`Needs-Selection` is intermediate only) | |
| 69 | | `slice` | [`image-generator.md`](./image-generator.md) §4.3 | `slice_images.py` after parent AI sheet is `Generated` | `Generated` | |
| 70 | | `user` | — | — | (already `Existing`) | |
| 71 | | `placeholder` | — | — | (already `Placeholder`) | |
| 72 | |
| 73 | > Lazy load: an all-`web` deck never reads `image-generator.md`, and vice versa. |
| 74 | |
| 75 | --- |
| 76 | |
| 77 | ## 4. Analysis Phase |
| 78 | |
| 79 | 1. Read the Default Design Spec/lock, or reuse Quick's active-context resource/page decisions. |
| 80 | 2. Separate derivatives before grouping canonical rows by `Acquire Via`; ensure `project/images/` exists. |
| 81 | 3. Finish user and triggered ai/web/slice canonical preparation. |
| 82 | 4. Materialize only declared derivatives from usable parents, preserve originals, then run `analyze_images.py` once before SVG. |
| 83 | |
| 84 | --- |
| 85 | |
| 86 | ## 5. Verification Phase |
| 87 | |
| 88 | After all rows reach terminal status: |
| 89 | |
| 90 | - Every non-skipped row has a file at `project/images/<filename>`, or is marked `Needs-Manual` |
| 91 | - Each derivative has its distinct file and usable parent; web provenance is copied in `image_sources.json` |
| 92 | - Every `slice` row has a generated element file, or is marked `Needs-Manual` because its parent sheet is not available |
| 93 | - No `Pending`, `Failed`, or `Needs-Selection` rows remain |
| 94 | - `image_prompts.json` exists when ≥1 active ai row remains; every entry has `status ∈ {Generated, Needs-Manual}` (no `Pending` or `Failed` remaining) |
| 95 | - `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) |
| 96 | |
| 97 | > `Needs-Manual` is terminal for acquisition, not export readiness. A later |
| 98 | > supplied/replaced file must be validated and its row reconciled to |
| 99 | > `Existing`, `Generated`, or `Sourced` with matching evidence. |
| 100 | > Quick blocks every required row that still says `Needs-Selection` or |
| 101 | > `Needs-Manual`, regardless of whether a preview or unverified candidate file |
| 102 | > happens to exist. See |
| 103 | > [`image-generator.md`](./image-generator.md) §7. |
| 104 | |
| 105 | --- |
| 106 | |
| 107 | ## 6. Failure Handling |
| 108 | |
| 109 | **Hard rule — automatic exhaustion before blocking**: acquisition failures MUST NOT open an interactive choice or stop while an untried permitted strategy remains. After exhaustion, follow the owning path's decision policy; Default AI generation uses `image-generator.md` §7's three-outcome recovery gate instead of assuming manual fulfillment. |
| 110 | |
| 111 | 1. Run the selected path's initial strategy |
| 112 | 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 |
| 113 | 3. When the path-specific query variants/ranked pages/provider/license-stage or backend/retry strategy is exhausted, follow its owning terminal rule. Web may set `Status: Needs-Manual`; Default AI rows remain `Failed` while its recovery decision or retry is unresolved, and only confirmed manual fulfillment sets `Needs-Manual`; Quick removes exhausted automated AI/dependent-slice jobs through `image-generator.md` §7's declared no-AI replan, while an explicitly selected manual path may set `Needs-Manual` |
| 114 | 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`. |
| 115 | |
| 116 | **Quick Generate export gate**: exhaust allowed automation without asking; stop |
| 117 | before `--quick-generate` when a required row is not both backed by its |
| 118 | validated file/provenance and in a usable status. Preview/file presence alone |
| 119 | never bypasses `Needs-Selection` or `Needs-Manual`. |
| 120 | |
| 121 | `Needs-Manual` is also the entry status for **Offline Manual Mode**. Default uses it only when final Stage 2 or the runtime recovery decision explicitly confirmed `manual`; Quick uses it only when the active-context instruction explicitly selected `manual`. Neither profile checks configuration or probes a provider during planning; automated capability is resolved only during [`image-generator.md`](./image-generator.md) §7 execution. |
| 122 | |
| 123 | Path-specific retry policies (provider chain, backend chain) live in the path's own reference. |
| 124 | |
| 125 | --- |
| 126 | |
| 127 | ## 7. Credits — Single Source of Truth |
| 128 | |
| 129 | License / attribution data lives **only** in `project/images/image_sources.json`. |
| 130 | |
| 131 | **Forbidden — credits anywhere else**: |
| 132 | |
| 133 | - `notes/*.md` (TTS would speak them in the audio export) |
| 134 | - `total.md` (gets split, then overwritten) |
| 135 | - SVG `<title>` / `<desc>` (stripped by `svg_to_pptx.py`) |
| 136 | - A separate "Image Credits" appendix slide (lost on single-page sharing) |
| 137 | |
| 138 | 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. |
| 139 | |
| 140 | --- |
| 141 | |
| 142 | ## 8. Intent Ownership |
| 143 | |
| 144 | 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. |
| 145 | |
| 146 | For derivatives, the required lineage/treatment prefix is intent metadata, not a provider query. |
| 147 | |
| 148 | | ✅ Intent | ❌ Pre-processed | |
| 149 | |---|---| |
| 150 | | `"Diverse engineering team in modern office, natural light"` | `"team office light"` | |
| 151 | | `"Abstract digital waves, deep navy gradient #0A2540"` | `"use openverse, search 'waves'"` | |
| 152 | |
| 153 | --- |
| 154 | |
| 155 | ## 9. Handoff with SVG Authoring |
| 156 | |
| 157 | SVG authoring consumes the active profile's resource authority plus: |
| 158 | |
| 159 | | Artifact | Path | Purpose | |
| 160 | |---|---|---| |
| 161 | | Image files | `project/images/*.{jpg,png,webp}` | `<image>` references | |
| 162 | | Manifest | `project/images/image_sources.json` | License/provenance for sourced images and their derivatives | |
| 163 | |
| 164 | **Default Generate boundary**: Executor does NOT invoke `image_gen.py` / `image_search.py` / `slice_images.py` / `image_treat.py`; missing material returns to Strategist-owned preparation. |
| 165 | |
| 166 | **Quick Generate boundary**: the main agent finishes acquisition and planned derivation before SVG authoring, then neither acquires, derives, nor reselects while drawing. |
| 167 | |
| 168 | --- |
| 169 | |
| 170 | ## 10. Task Completion Checkpoint |
| 171 | |
| 172 | Verify every row, file, triggered manifest/sidecar, and provenance record. |
| 173 | Default proceeds to Executor. Quick proceeds without interaction after |
| 174 | preparation and exports only when every required row has validated evidence and |
| 175 | a usable status. Report only blocking recovery. |
| 176 |