| 1 | --- |
| 2 | description: One-pass Generate profile for agent-decided preparation, direct SVG authoring, and final PPTX delivery without durable planning or confirmation artifacts. |
| 3 | --- |
| 4 | |
| 5 | # Quick Generate Profile |
| 6 | |
| 7 | > Generate-PPTX profile, not a top-level route. The current main agent completes |
| 8 | > one uninterrupted run without a separate Strategist/confirmation handoff or a |
| 9 | > resumable design record. This removes interaction and traceability, not the |
| 10 | > facts, resources, or authoring capabilities needed to build the final deck. |
| 11 | |
| 12 | **Trigger**: the user explicitly requests quick/fast generation, asks to skip |
| 13 | strategy/confirmation, or directs the agent to proceed to SVG and export. |
| 14 | Page count alone never activates or blocks this profile. |
| 15 | |
| 16 | **Hard rule — Quick paths**: Apply the entry-time `SKILL_DIR` anchor to every |
| 17 | linked or abbreviated package path below. Expand it inside each tool call; |
| 18 | never change CWD or inherit a prior shell working directory. |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## 1. Profile Boundary |
| 23 | |
| 24 | | Concern | Quick Generate contract | |
| 25 | |---|---| |
| 26 | | Authority | Follow every explicit user requirement as stated; decide every unspecified choice directly without asking | |
| 27 | | Interaction | The current main agent decides content, design, resources, and implementation without Strategist, Confirm UI, or approval stops | |
| 28 | | Execution memory | Keep routine page, visual, and resource decisions only in the current active context; losing that context restarts Quick instead of reconstructing a plan from project files | |
| 29 | | Inputs | Any supported Generate input; convert/import sources and run bounded factual research when the input requires them | |
| 30 | | Templates | Directly validate and install at most one exact workspace root per kind supplied for this run; when none are supplied, use free design without catalog selection or Confirm UI | |
| 31 | | Resources | Prepare every project-local image, icon, and required provenance/manifest artifact before its SVG; author native formula markers and hyperlink anchors directly in the affected SVG; sound waits for §4 | |
| 32 | | Planning artifacts | Do not author a root project `design_spec.md`, `spec_lock.md`, confirmation payloads, or any substitute planning artifact; installed `templates/design_spec.<kind>.<id>.md` files remain template input | |
| 33 | | Traceability | Operational resource manifests, checker reports, postflight, and bounded Python command/outcome audit entries may remain, but they do not record the AI's design reasoning or form a resumable generation history | |
| 34 | | Delivery | Hand-author the resolved SVG roster, run one lockless final checker, skip `finalize_svg.py`, and export the final native PPTX through `--quick-generate` | |
| 35 | |
| 36 | **Artifact ownership**: follow |
| 37 | [`artifact-ownership.md`](../../references/artifact-ownership.md) for source, |
| 38 | fact, author, derived, and regeneration boundaries. Quick changes the planning |
| 39 | handoff, not those artifact roles. |
| 40 | |
| 41 | **Hard rule — speed removes interaction and durable planning, not capability**: |
| 42 | all ordinary source, research, visual-carrier, resource-preparation, analysis, |
| 43 | authoring, and export capabilities remain available when they serve the deck. |
| 44 | This is capability availability, not a requirement to use every carrier. |
| 45 | |
| 46 | Explicit user facts, wording, choices, exclusions, and permission boundaries |
| 47 | still win. For every unspecified routine choice, decide directly and continue; |
| 48 | do not ask the user to approve a strategy or implementation detail. |
| 49 | |
| 50 | After entry, continue through selected work, the final checker, and export. |
| 51 | Pause only for user interruption or an unresolved hard prerequisite. |
| 52 | |
| 53 | **Default — optional production behavior (may override when useful)**: Speaker |
| 54 | notes, Custom Animations, and narration start off for ordinary Quick work. The |
| 55 | current agent may enable any ordinary capability when the request or deck |
| 56 | benefits; use its normal inputs, flags, and prerequisites without asking for |
| 57 | approval. Quick video delivery follows the mandatory Custom Animations rule |
| 58 | below. Quick never creates or reads a root project Design Spec or lock to enable |
| 59 | an optional or mandatory capability. |
| 60 | |
| 61 | **Mandatory — discover motion before deciding whether to load it**: apply this |
| 62 | gate once during §2's pre-P01 planning. Do not load the full reference when |
| 63 | the defaults fit. |
| 64 | |
| 65 | | Signal | Action | |
| 66 | |---|---| |
| 67 | | Adjacent beats may share one mental map | Evaluate visible states; repetition alone does not require Morph. If continuity clarifies orientation, enable Custom Animations, load [`animations.md`](../../references/animations.md) before SVG, and author compatible Morph endpoints | |
| 68 | | Page- or object-specific reveal, renewed emphasis, meaningful movement, or same-page removal clarifies the message | Load [`animations.md`](../../references/animations.md) before SVG authoring; preserve the required units/states, then run [`customize-animations`](../stages/customize-animations.md) after the final checker | |
| 69 | | One deck-wide entrance policy supplies all required staged reveal | Load [`animations.md`](../../references/animations.md) before export and use an exporter flag such as `-a auto`; do not run the custom stage | |
| 70 | | A directional/section boundary benefits from a non-default transition | Load [`animations.md`](../../references/animations.md) before export and select from its §3 playbook | |
| 71 | | No earlier signal applies | Keep `fade` transitions and object animation `none`; do not load the motion reference | |
| 72 | |
| 73 | This gate activates capability discovery, not motion coverage. Keep the |
| 74 | defaults when no row supplies a concrete communication job. When several |
| 75 | signals apply, perform every required action and use the earliest required load |
| 76 | point; a before-authoring signal always overrides a before-export-only timing. |
| 77 | |
| 78 | **Hard rule — Quick video Custom Animations**: when |
| 79 | [`video-design.md`](../../references/video-design.md) is active because the |
| 80 | effective Quick delivery purpose is recorded, self-running, or video-directed, |
| 81 | enable Custom Animations, load [`animations.md`](../../references/animations.md) |
| 82 | before SVG authoring, preserve the required semantic motion units, and run |
| 83 | [`customize-animations`](../stages/customize-animations.md) after the final |
| 84 | checker. Use the discovery table above to choose the choreography, not whether |
| 85 | Custom Animations exists. Individual pages or groups may remain static, so this |
| 86 | is not an animation-coverage quota. A Quick video run without a validated |
| 87 | `animations.json` fails this requirement unless the user explicitly requests |
| 88 | static or page-transition-only playback. Narration-governed motion also |
| 89 | activates cue synchronization. |
| 90 | |
| 91 | --- |
| 92 | |
| 93 | ## 2. Source and Resource Preparation |
| 94 | |
| 95 | Prepare source facts before initialization: |
| 96 | |
| 97 | | Input | Action | |
| 98 | |---|---| |
| 99 | | Topic or requirements without supporting facts | Run [`topic-research`](../stages/topic-research.md) immediately and retain its Markdown supplement plus fact-provenance JSON; adopted webpage URLs remain inside that pair and are not import inputs | |
| 100 | | One or more PNG / JPEG / WebP files representing page frames under Image to PPTX | Do not call `source_to_md.py`; normalize single-page files and multi-frame contact sheets into the canonical ordered frame roster through that profile, then import the originals below | |
| 101 | | PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | Run `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` | |
| 102 | | CSV / TSV | Read directly as a plain-text table source | |
| 103 | | Markdown or direct conversation text | Read directly | |
| 104 | |
| 105 | The conversion dispatcher writes standard Markdown plus its conversion profile |
| 106 | beside each local source by default. Use `-t <type>` only when detection is |
| 107 | ambiguous and `-o` only for a required output path; with several or directory |
| 108 | inputs, `-o` names an output directory. A PPTX is converted to Markdown here and |
| 109 | receives its project analysis during the import step below. |
| 110 | |
| 111 | **Source-image orientation trigger**: Before import and initialization, follow |
| 112 | [`conversion.md`](../../scripts/docs/conversion.md) § Image Orientation Review |
| 113 | when correction is requested, converted text asks for rotated viewing, or a |
| 114 | downloaded asset is visibly sideways. Skip the legacy HTML tool. |
| 115 | |
| 116 | After reading every direct and converted source, assess factual sufficiency: |
| 117 | |
| 118 | | Material state | Action | |
| 119 | |---|---| |
| 120 | | Image to PPTX page surface | Treat as a closed visible corpus; unreadable/occluded regions become `manual_required`, never external research | |
| 121 | | The requested outcome is supported | Continue | |
| 122 | | A required externally verifiable claim remains unsupported | Run [`topic-research`](../stages/topic-research.md) for those gaps only | |
| 123 | | Closed corpus / source-only / no external enrichment | Stay within the supplied material | |
| 124 | |
| 125 | **Sufficiency test**: research only when the requested outcome would otherwise |
| 126 | require inventing, omitting, or leaving unsupported an externally verifiable |
| 127 | claim. File presence or length does not establish sufficiency. Research records |
| 128 | the needed facts and adopted webpage URLs in its research pair. Project |
| 129 | initialization fetches none of those pages; independent AI / web / slice |
| 130 | acquisition remains part of the resource preparation below. |
| 131 | |
| 132 | **Conditional video-delivery context**: when the intended use is recorded, |
| 133 | self-running, or video-directed—or an explicit final/literal narration script |
| 134 | will become notes/audio—read |
| 135 | [`video-design.md`](../../references/video-design.md) now and retain it through |
| 136 | roster, SVG, notes, and motion decisions. This changes neither the Quick profile |
| 137 | nor its artifacts. |
| 138 | |
| 139 | Before initialization, resolve exactly one template branch: |
| 140 | |
| 141 | When [`image-to-pptx.md`](./image-to-pptx.md) is active, its canonical page |
| 142 | surface owns the design: select **Free design** directly and do not inspect, |
| 143 | install, or apply a supplied template workspace. The branches below apply to |
| 144 | ordinary Quick and other compatible profiles. |
| 145 | |
| 146 | - **Direct template application**: one or more exact current workspace roots |
| 147 | were supplied in the request, or Create Template returned an exact validated |
| 148 | root in the current conversation. Accept at most one root per declared kind. |
| 149 | Before initialization, load |
| 150 | [`apply-template-workspace`](../stages/apply-template-workspace.md), normalize |
| 151 | each supplied root, read only the matching spec frontmatter needed to resolve |
| 152 | its kind/canvas, and run that stage's read-only schema/structured preflight. |
| 153 | Do not scan the library, fuzzy-match a name, or open a selector. Explicit user |
| 154 | canvas wins; otherwise use the selected structure owner (Layout before Deck) |
| 155 | canvas when present, then fall back to `ppt169`. |
| 156 | - **Free design**: no exact root was supplied. Continue immediately with the |
| 157 | requested canvas or `ppt169`. A bare template name, brand mention, style |
| 158 | phrase, or vague request to choose a template is ordinary brief input, not a |
| 159 | workspace reference. |
| 160 | |
| 161 | Neither branch creates anything under `confirm_ui/` or executes |
| 162 | `confirm_ui/server.py`. Initialize the minimal workspace with: |
| 163 | |
| 164 | ```bash |
| 165 | python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> \ |
| 166 | --format <format> --quick-generate |
| 167 | ``` |
| 168 | |
| 169 | It creates `svg_output/` plus the cold |
| 170 | `validation/workflow.log` command/outcome audit log, and no root README. After |
| 171 | this command, run project-scoped Python tools directly; their shared CLI |
| 172 | bootstrap records command envelopes, material tagged outcomes, bounded status |
| 173 | samples, and omission counts. A concise manual entry is allowed only for a |
| 174 | material stage handoff, rework reason, user-approved exception, or manual |
| 175 | recovery choice that has no owning command output; do not record routine page |
| 176 | progress, artifact contents, or private reasoning. |
| 177 | Never read the log during ordinary Quick execution; open it only for an |
| 178 | explicit user-requested run review. Add |
| 179 | capability inputs only when triggered; later tools create `exports/` and the |
| 180 | default-path `backup/`. |
| 181 | |
| 182 | With file-based sources, import the original inputs, converted outputs, and any |
| 183 | research pair together: |
| 184 | |
| 185 | ```bash |
| 186 | python3 ${SKILL_DIR}/scripts/project_manager.py import-sources \ |
| 187 | <project_path> <source_files_or_dirs...> [<converted_outputs...>] \ |
| 188 | [projects/<research_slug>.md projects/<research_slug>.facts.json] |
| 189 | ``` |
| 190 | |
| 191 | **✅ Checkpoint — every named input landed**: `import-sources` exits 0 as long |
| 192 | as one input produced a usable artifact, so a partially failed batch still |
| 193 | succeeds. Read the printed `skipped` reasons before continuing. An entry skipped |
| 194 | because equivalent content already exists is benign; `path not found`, a failed |
| 195 | conversion, or no usable Markdown means that source is absent. Re-import or |
| 196 | supply a converted equivalent for each absent source, or state why the deck |
| 197 | proceeds without it. |
| 198 | |
| 199 | The facts JSON is the sole URL authority, not a download queue. |
| 200 | `project_manager.py` imports it as an ordinary file and never expands its |
| 201 | `source_url` values. If normal web-image search is exhausted, follow |
| 202 | [`topic-research`](../stages/topic-research.md) § Hand-off to fetch one relevant |
| 203 | webpage package, review it, and copy only accepted images into the runtime pool. |
| 204 | |
| 205 | Only inputs already under the repository's `projects/` tree move into the |
| 206 | target project; every external path is copied and remains untouched. Use |
| 207 | `--copy` when a projects-local input must also remain in place. When conversion |
| 208 | wrote Markdown beside the original source, pass that source path or directory |
| 209 | once; when `-o` wrote it elsewhere, pass both locations. Direct supported bitmap |
| 210 | inputs are archived under `sources/` and copied collision-safely into `images/`. |
| 211 | When [`image-to-pptx.md`](./image-to-pptx.md) is active, its |
| 212 | normalized frame roster is canonical page-surface input and the current main |
| 213 | agent writes the source-evidence-only `analysis/reconstruction_inventory.json` |
| 214 | before deciding the layer stack in active context. |
| 215 | |
| 216 | For each imported PPTX, `import-sources` automatically writes |
| 217 | `analysis/<stem>.identity.json`, `analysis/<stem>.slide_library.json`, and the |
| 218 | multi-deck `analysis/source_profile.json` index. Read that index as source facts |
| 219 | and open a per-deck artifact only when the current task needs its additional |
| 220 | detail; these facts are recommendations, not replica constraints. Distinct PPTX |
| 221 | stems may coexist, and re-importing one stem replaces only that deck's entry. |
| 222 | |
| 223 | Conversion companion manifests may place extracted SVG/EMF/WMF assets into the |
| 224 | project resource flow. Preserve EMF/WMF as vector references and never convert |
| 225 | them to PNG; browser preview may be blank while native PPTX export remains the |
| 226 | source of truth. Standalone SVG/EMF/WMF inputs remain source assets unless such |
| 227 | a manifest supplies their display metadata. |
| 228 | |
| 229 | Never scaffold a Design Spec or lock. Use a new path, or verify that an existing |
| 230 | path's `svg_output/` is empty; Quick ignores any existing `design_spec.md` or |
| 231 | `spec_lock.md`. |
| 232 | |
| 233 | The audit log is an operational tool record only. It does not capture direct |
| 234 | SVG authoring, active-context design choices, or private reasoning and cannot be |
| 235 | used to resume or reconstruct a Quick run. |
| 236 | |
| 237 | For the direct-template branch, continue with |
| 238 | [`apply-template-workspace`](../stages/apply-template-workspace.md) after |
| 239 | initialization against only the preflighted roots. The user's request is the |
| 240 | selection authority; there is no template confirmation receipt or handoff. The |
| 241 | stage installs each workspace as its own spec file under `<project_path>/templates/` plus |
| 242 | the project-local asset pools. All later reads use that installed state, never |
| 243 | the original roots. |
| 244 | |
| 245 | Before writing P01, read every installed |
| 246 | `templates/design_spec.<kind>.<id>.md` once and, for Layout/Deck, inspect the |
| 247 | relevant SVG prototypes. Apply Brand identity, Style direction/method, the |
| 248 | selected structure owner's useful prototype geometry, and Deck application |
| 249 | context directly in the active context under the existing segment precedence |
| 250 | ([`apply-template-workspace`](../stages/apply-template-workspace.md) §5). A |
| 251 | segment owner's instruction about how a value should dominate, recede, or stay |
| 252 | rare binds as strongly as the value itself; a Style composition or whitespace |
| 253 | tendency never demotes a Brand's declared dominant color to an incidental |
| 254 | accent. Follow explicit instructions about literal or visual-only |
| 255 | use; otherwise decide which prototypes to use, skip, repeat, reorder, or adapt |
| 256 | while authoring. Persist no separate template-application artifact. If no |
| 257 | template was installed, make the same design choices freely. |
| 258 | |
| 259 | Before resolving the one-pass design, read this fixed planning-capability batch |
| 260 | in one pass: |
| 261 | |
| 262 | ``` |
| 263 | Read ${SKILL_DIR}/references/canvas-formats.md |
| 264 | Read ${SKILL_DIR}/references/image-layout-spec.md |
| 265 | Read ${SKILL_DIR}/references/image-layout-patterns.md |
| 266 | Read ${SKILL_DIR}/references/modes/_index.md |
| 267 | Read ${SKILL_DIR}/references/visual-styles/_index.md |
| 268 | Read ${SKILL_DIR}/references/image-renderings/_index.md |
| 269 | Read ${SKILL_DIR}/templates/icons/README.md |
| 270 | Read ${SKILL_DIR}/templates/charts/chart-vocabulary.md |
| 271 | Read ${SKILL_DIR}/templates/tables/table-vocabulary.md |
| 272 | ``` |
| 273 | |
| 274 | This batch is the complete capability map for planning, not a usage checklist: |
| 275 | zero use of any capability remains valid. Resolve the best whole solution from |
| 276 | the project brief and loaded decision authorities, freeze its exact |
| 277 | mode/style/rendering ids, then read only those selected detail files or custom |
| 278 | bases. A novel custom reads none. Never open unselected detail siblings to |
| 279 | compare candidates, glob a catalog, or let them influence the decision. Decide |
| 280 | whether AI images are useful as a separate source judgment; even when the |
| 281 | answer is no, retain the chosen rendering direction for visual coherence. Keep |
| 282 | the chosen mode, style, rendering, and exact bases in active context only. |
| 283 | |
| 284 | **One-pass decision boundary**: resolve only what is needed to author this deck |
| 285 | in the current context. Do not print a strategy summary, create a planning |
| 286 | checkpoint, or persist a page/resource plan. |
| 287 | |
| 288 | Before P01, apply the §1 gate while co-resolving these choices; freeze |
| 289 | the roster after the whole-roster check: |
| 290 | |
| 291 | - the narrative beats, mental-map arcs, candidate visible states, their semantic deltas, and enabled notes segments. Adopt continuity only when it clarifies the message. Profile-fixed count/order/content, including 1:1/fidelity, permits only existing-neighbor evaluation; never alter those invariants to manufacture endpoints; |
| 292 | - the effective Speaker Notes, Custom Animations, and Narration Audio outcomes; narration requires notes, later recording alone forces neither audio nor object animation, while a Quick recorded/self-running/video delivery purpose follows [`video-design.md`](../../references/video-design.md) and enables Custom Animations before SVG authoring; direct narrated video additionally enables notes/narration/video and decides before audio whether narration governs group timing; |
| 293 | - the resulting exact slide roster and one compact core message for every page, used to choose its composition and hierarchy; |
| 294 | - the canvas, visual direction, wording, intended viewing distance, and effective reading mode: choose `presentation` for distance-first projected or recorded viewing, `balanced` for mixed viewing, or `text` for close content-heavy reading. Take the initial body anchor and sanity band from [`canvas-formats.md`](../../references/canvas-formats.md) § "Typography Scale Start" for the resolved canvas—PPT remains reading-mode-driven, while registered/custom non-PPT canvases use their canvas-derived start—then resolve one concrete typography plan for the delivery target defined by [`shared-standards-core.md`](../../references/shared-standards-core.md) §4.1, never from the authoring host's font inventory, with stable size anchors for title, body, annotation, and every other recurring role the roster uses. When content does not fit, preserve its core message and apply only fitting actions the source/profile invariants permit—restructure, shorten, or split; if none is permitted, surface the unresolved fit instead of shrinking a recurring role. Explicit user, template, fidelity-profile, or resolved-style requirements may call for a deliberate exception; |
| 295 | - the semantic color roles actually needed by the roster, each with a concrete active-context color anchor, including background/surface, primary/secondary text, dominant/accent, and status roles as applicable. Honor explicit user, installed template/brand, fidelity-profile source-identity, and resolved-style color semantics before deriving only the missing roles that the active profile permits; decide which roles dominate, support, or remain rare, and preserve sufficient contrast for meaning-bearing text. Pair newly authored color-coded states, categories, or relationships with a label, symbol, line, or geometry cue; when fidelity forbids adding one, preserve the source encoding; |
| 296 | - an ordinary body-content frame and a density judgment for every page, adapted to the canvas and any user / template / style geometry; use `anchor`, `dense`, `breathing`, or an equivalent active-context distinction instead of one uniform fill level; |
| 297 | - for each page not bound to literal supplied geometry, a primary visual zone and one compact page-scale geometry job tied to its core message—what geometry must organize, without naming a preset or encoding form; keep it only in the transient roster for §3's authoring-time move; |
| 298 | - for each page, preserve its semantic units, source-stated qualitative relationships, intended entry, and outcome so §3 can make the sole Structure decision before geometry; |
| 299 | - the resolved visual direction's deck-level shape language under |
| 300 | [`visual-styles/_index.md`](../../references/visual-styles/_index.md) §2, |
| 301 | retained for page-fit native geometry without selecting an exact preset here; |
| 302 | - when useful, an additional transient deck-level visual motif system with an identity or |
| 303 | communication job, a recognizable invariant, and a reuse mode: fixed chrome, |
| 304 | adaptive variation, or both; treat restraint as control of visual weight, |
| 305 | recurrence, and reuse, not as a reason by itself to omit an evidenced source, |
| 306 | identity, or communication motif; omit the system when no motif earns a |
| 307 | continuity job or when reuse would add false meaning, compete with the page |
| 308 | message, or reduce clarity; |
| 309 | - the resource decisions needed for immediate preparation. Required operational |
| 310 | image manifests may carry filenames, page relationship, status, and |
| 311 | generation/crop/focal cues. When page use depends on stable composition, also |
| 312 | retain subject/quiet zones, boundary or direction, intended overlap/seam, and |
| 313 | approximate share only when needed. Do not create a general resource roster |
| 314 | or icon-to-page assignment. Keep each selected formula's source LaTeX in active |
| 315 | context for direct marker authoring; retain each selected hyperlink's exact |
| 316 | absolute URI or 1-based same-deck target; create no formula/link manifest; |
| 317 | - the implementation path for each resource. An explicit user path wins; |
| 318 | otherwise choose the registered automatic/default path without another |
| 319 | interaction. |
| 320 | |
| 321 | **Prepared final narration**: when the user explicitly marks a script as |
| 322 | final/literal and intends it for notes or generated audio, segment it by semantic |
| 323 | scene while resolving the roster and preserve every spoken word. Before writing |
| 324 | P01, write the ordered segments once to `notes/total.md` with |
| 325 | `# Slide <number>` headings and `---` separators. Keep that file as exact |
| 326 | production input for page design; it is not a planning checkpoint. Do not split |
| 327 | it until the SVG roster exists. Draft narration instead remains source material |
| 328 | and uses the ordinary post-SVG notes branch when notes are enabled. |
| 329 | |
| 330 | **Mandatory — image treatment / subject layers**: Before preparation choose per |
| 331 | image: `none`; native SVG crop/transform/depth; or prepared |
| 332 | blur/tone/cutout/registered layers. `none` is valid. A subject crossing native |
| 333 | content requires a clean full-canvas base plus registered RGBA cutout |
| 334 | (`#A2-03`; [`image-generator.md`](../../references/image-generator.md) §4.4); |
| 335 | a floating cutout may use `#A2-01`. Finish assets before SVG per |
| 336 | [`image-base.md`](../../references/image-base.md) §2–3. |
| 337 | |
| 338 | **Prepared derivative**: create it with `image_treat.py` (blur, |
| 339 | desaturation/grayscale, duotone, brightness, contrast) under a name separate |
| 340 | from its source. The canonical file stays intact: a derivative never overwrites |
| 341 | its source, never becomes another derivative's parent, and never has its output |
| 342 | equal its input. Derive only after that source is itself final. |
| 343 | |
| 344 | **Mandatory — whole-roster rhythm check**: During the same active-context |
| 345 | resolution, compare neighbors and section arcs to judge whether chapter entries |
| 346 | visibly reset, extended same-density runs are intentional, extended repetitions |
| 347 | of one carrier or composition move form an intentional page-job arc, repeated |
| 348 | dominant geometry carries a continuity job, each section follows a mode-fitting |
| 349 | progression—including framework → explanation/evidence → judgment/action when |
| 350 | it serves the objective—and the final arc resolves the communication objective |
| 351 | before a genuine ending lowers information load. Same section, equal weight or |
| 352 | density, one style, and prior-page precedent do not establish a page-job arc. |
| 353 | Repair the transient roster, density, and composition choices in place. This is |
| 354 | judgment, not quota; preserve intentional continuity, legitimately all-`dense` |
| 355 | material, and 1:1/literal order. Add no filler page: a `breathing` page marks a |
| 356 | meaningful pause—chapter transition, standalone emphasis, or SCQA bridge—and |
| 357 | must stand alone. Create no artifact, checkpoint, lock, or second |
| 358 | authoring/review pass. |
| 359 | |
| 360 | **Mandatory — one-pass page carrier resolution, not a coverage quota**: During |
| 361 | the same transient-roster resolution and before resource preparation or |
| 362 | coordinates, decide each page's complete mix of background, editable text and |
| 363 | optional lettering, native geometry and lines, photos/scenes, |
| 364 | illustrations/icons, and applicable visualizations. Decide their primary, |
| 365 | structural, and supporting jobs together; do not finish a text/container layout |
| 366 | and then treat the other families as optional decoration. Only selected image, |
| 367 | lettering, or illustrated-icon jobs with plausible page roles create image |
| 368 | resources; ordinary SVG/emoji icons retain their curated-pool boundary. |
| 369 | Omitting any carrier is valid after this review; Quick speed, resolved style, |
| 370 | or easier syntax never skips it. |
| 371 | |
| 372 | **Reference — carriers compose, not compete**: Use any suitable subset from the resolved mix; outside explicit requirements, no carrier is mandatory or mutually exclusive. The resolved style controls treatment, visual weight, and recurrence; it never decides carrier eligibility, image source, or the complete native construction vocabulary. A compact icon cue does not discharge a scene, subject, or visual-weight job that a photo or illustration family would serve. |
| 373 | |
| 374 | **Hard rule**: Credentials do not decide image need or the initial carrier plan. Do not inspect backend configuration or probe a provider before planning. Web acquisition retains zero-config providers; actual AI generation capability is resolved only during resource preparation, where the declared Quick no-AI replan below owns automated exhaustion. |
| 375 | |
| 376 | **Default — visual grounding before a zero-image deck (may override when the full-roster carrier review finds no useful image job)**: Honor an explicit no-image requirement. When the audience must recognize, experience, compare, or choose an externally verifiable subject, place, product, or setting, plan supplied/extracted or web images. Prepare AI imagery proactively where invented or deliberately stylized expression materially improves a planned visual job; this may be a complete image or transparent elements composed with other page carriers. A zero-image result remains valid when no image job improves communication. This is a semantic decision, not an image-count quota. |
| 377 | |
| 378 | **Mandatory — materialize a selected composable illustration family**: When |
| 379 | the carrier resolution selects one, resolve the family before SVG authoring. |
| 380 | Elements may repeat unchanged as title/corner chrome or vary as dominant |
| 381 | anchors, supporting figures, and accents on any suitable page. Batch compatible |
| 382 | elements through Illustration Sheets, split only for geometry/detail/quality |
| 383 | conflicts, and keep final page composition in SVG under |
| 384 | [`image-generator.md`](../../references/image-generator.md) §4.3. |
| 385 | |
| 386 | **Mandatory — materialize selected AI illustrated-icon jobs**: When the carrier |
| 387 | resolution selects them and the user has not forbidden AI, prepare useful cues |
| 388 | as transparent slices under `images/`. Leave grouping, count, and coexistence |
| 389 | with SVG icons to the page and deck fit under |
| 390 | [`image-generator.md`](../../references/image-generator.md) §4.3; apply no |
| 391 | coverage quota and never treat the slices as SVG inventory. |
| 392 | |
| 393 | **Mandatory — proactive decorative-lettering capability scan**: During that same one-pass |
| 394 | carrier resolution, when the user has not forbidden AI, scan the frozen roster |
| 395 | for display strings anywhere in the deck. Two questions expose candidates: is |
| 396 | that wording stable, and could an artistic treatment plausibly communicate |
| 397 | better than native type? Passing both exposes a possible AI visual job; it does |
| 398 | not select lettering or add AI by itself. Page role, string length, line count, |
| 399 | kind of noun, and resolved style never pre-filter candidates — |
| 400 | a cover hook, chapter word, place or product name, dish or exhibit name, year, |
| 401 | hero number, pull quote, or recurring motif word all qualify when both answers |
| 402 | are yes. Read any such list as examples, never as the set of allowed cases; a |
| 403 | two-character mark, an eight-character phrase, and a two-line lockup are equally |
| 404 | valid, and a phrase is never trimmed toward one or two characters to feel more |
| 405 | "wordmark-like". Set over photography or a busy field is often exactly where |
| 406 | native type reads pasted-on. Compare every candidate inside the complete page |
| 407 | and deck carrier mix, then select any coherent set whose treatment wins that |
| 408 | fit; selecting none remains valid and needs no skip explanation or coverage |
| 409 | quota. For every selected mark, keep a native title wherever the page needs a |
| 410 | searchable, selectable, or outline-visible heading, with the lettering as its |
| 411 | display layer. Prepare the selected set without a separate request: preserve |
| 412 | the exact approved strings, use one ordinary AI |
| 413 | item for a single mark or group compatible marks through Illustration Sheets |
| 414 | and transparent slices. Let the intended character and treatment guide grouping. |
| 415 | Give the model the marks' role, placement/background relationship, relative |
| 416 | visual weight, and energy; apply `image-generator.md` §5.3's |
| 417 | controlled-default/high-expression boundary. Split when geometry, quality, or |
| 418 | the intended treatment benefits, and keep ordinary |
| 419 | title/chrome copy native. A prepared wordmark |
| 420 | and an editable title are not mutually exclusive: |
| 421 | one page may carry the wordmark as its display layer while its subtitle, chrome, |
| 422 | and body stay native text, so a wish to keep that wording editable is answered |
| 423 | by the native layer rather than by dropping the lettering. AI permission is not |
| 424 | coverage: never invent or alter copy, or create lettering merely to justify AI |
| 425 | usage. Actual generation capability is resolved during resource preparation, |
| 426 | after selection rather than during candidate discovery. |
| 427 | |
| 428 | | Communication job | Available carrier | |
| 429 | |---|---| |
| 430 | | Real subject, place, product, evidence, atmosphere, or scene benefits from visual grounding | Supplied/extracted, web, AI, or sliced image | |
| 431 | | Reusable title/corner decoration, a dominant illustrated anchor, supporting figure, or accent strengthens one or more page compositions | A coherent AI illustration family prepared as transparent `slice` assets and combined freely with other carriers | |
| 432 | | A compact semantic cue clarifies a category, process, KPI, state, or navigation item | Prepared project-local SVG/emoji icon, an illustrated-icon `slice`, or a coherent combination | |
| 433 | | A real company, product, service, or social brand must appear as itself | Prepare the exact brand mark from `simple-icons` or supplied project assets as needed; it is not a user-facing library choice | |
| 434 | | Editable geometry can express a relationship, flow, emphasis, callout, symbol, or diagram | Page-fit contours from the full native vocabulary, then their simplest exact authoring forms; independent composition when possible, required Boolean next, necessary freeform last | |
| 435 | | Values, categories, time, weights, or duration determine mark geometry | Value-driven chart | |
| 436 | | Sequence, hierarchy, role, region, or relationship determines page-local topology | Qualitative structure | |
| 437 | | Rows, columns, cells, headers, merges, and alignment form the information model | Cell-grid table | |
| 438 | | Mathematical notation is clearer as typeset math than ordinary text | PowerPoint-native inline or block math | |
| 439 | | Any stable display string in the deck — cover hook, chapter word, place or product name, dish or exhibit name, year, hero number, pull quote, motif word — reads better with a material, dimensional, hand-rendered, or otherwise illustrative treatment than as ordinary text | Apply the proactive rule above; place prepared lettering assets as images and keep ordinary editable title/chrome in separate text frames | |
| 440 | | Typography, spacing, and simple geometry already carry the message | Use no additional visual carrier | |
| 441 | |
| 442 | This carrier menu does not satisfy or replace the per-page Structure decision in §3. |
| 443 | |
| 444 | **Mandatory — per-image source decision, never inherited from the resolved style**: During that same carrier resolution, outside Image to PPTX whose closed page surface owns its reconstruction assets, decide each selected page image's source separately — supplied/extracted, web, AI, or slice. Prefer a supplied/extracted asset that already carries authority; use web when an externally verifiable subject must appear as itself; use AI when invented or deliberately stylized expression matters more than documentary identity. Mixed sources across one deck are normal. |
| 445 | |
| 446 | Resolving one visual style, `Illus.` propensity, or generated-image rendering resolves how imagery **looks**; it resolves the source for no page. A named place, building, product, artwork, person, or other externally verifiable subject stays a web/supplied candidate no matter how illustrative the deck looks. When such a subject is deliberately not shown as itself, state that choice and its reason in the final report rather than leaving it implicit. |
| 447 | |
| 448 | **Mandatory — complete Chart/Table capability review**: During that same |
| 449 | carrier resolution, compare every page's information model against every entry |
| 450 | in the already-loaded Chart and Table expression vocabularies. These |
| 451 | complete capability maps expose what exists; their descriptions do not rank |
| 452 | candidates or replace judgment from the actual information, and they are |
| 453 | neither usage quotas nor whitelists. Do not select a catalog reference for |
| 454 | qualitative shape composition. Choose at most one primary Chart/Table |
| 455 | `family/key` for a page, validate it with `visualization_recall.py validate`, |
| 456 | and keep its short purpose only in active context. Retain `no-template-match` |
| 457 | when none fits. The reference remains flexible: it does not lock final type, |
| 458 | geometry, style, or native output. |
| 459 | Describe an embedded child Chart/Table and every qualitative relationship in |
| 460 | the page's active decision rather than selecting another primary reference. |
| 461 | Actual information models determine the loaded execution branches. Give every independent |
| 462 | Chart/Table a page-local semantic `kebab-case` object key; keep its |
| 463 | `<object-key>=yes|no` native-ready decision and any promoted chart-verification |
| 464 | status in active context. Qualitative relationships create no catalog key or |
| 465 | reusable Master/Layout/placeholder contract. |
| 466 | |
| 467 | Prepare only the resource paths needed by the decided pages: |
| 468 | |
| 469 | | Resource | Required preparation | |
| 470 | |---|---| |
| 471 | | Supplied/extracted image | Copy the selected file into `images/`; preserve its factual/provenance context and use the measured file rather than an invented substitute | |
| 472 | | Image-to-PPTX reconstruction asset | In Codex, preserve identity graphics through an exact vector, deterministic redraw, sufficient source asset, or reference-based high-resolution reconstruction; keep data graphics native-and-verified or exact. For scene imagery, build the minimum registered clean-base/midground/subject/foreground group; batch padded-bbox-disjoint objects into one shared plate, then split them with grid slicing or independent nested-SVG bbox crops | |
| 473 | | Bundled/custom/brand SVG icon | Follow the [icon library contract](../../templates/icons/README.md), choose at most one coherent primary generic library when generic icons are useful, sync a project pool covering recurring semantics and likely page-local needs without assigning icons to pages, and add `simple-icons` marks only when actual content names the corresponding brand | |
| 474 | | Formula | Create no resource file. Retain the exact source LaTeX, then choose ordinary text, an inline native marker, or a block native marker under §3; the registered SVG preview is discarded by native export | |
| 475 | | AI image | Follow `image-base.md` + `image-generator.md`; apply only the chosen rendering preset or exact custom bases, never blend unselected catalog identities, and keep `image_prompts.json` plus its human-readable sidecar | |
| 476 | | Web image | Follow `image-base.md` + `image-searcher.md`; keep query/status data and `image_sources.json`, including any required on-slide attribution | |
| 477 | | Composable illustration / illustrated-icon / lettering slice | Generate or obtain the parent sheet, run `slice_images.py --trim --alpha --bg KEY_HEX_FROM_PROMPT --strict-alpha`, and place only outputs from a successful strict cut. Slices remain under `images/` and may serve several pages; each lettering sheet still names every exact stable string assigned to it | |
| 478 | | Registered reconstruction group | Follow `image-generator.md` §4.4; keep full-canvas members registered with `crop=no-crop`, and materialize every required shared-plate member as an independent picture object | |
| 479 | | Visualization | Keep Chart values, Table cell topology, and chosen treatment in active context; load the applicable Chart/Table authority in §3 and write native replacement metadata for every supported chart and pure text grid, which are native-ready by default | |
| 480 | |
| 481 | **Hard rule — planned slice closure**: Every placeable-element sheet carries `slice_grid` plus comma-separated `slice_names` in `image_prompts.json`. Deterministically enumerate those basenames and require every `images/<name>.png` after an exit-0 `slice_images.py --strict-alpha` run before SVG authoring; a `Generated` parent sheet never satisfies its named outputs. A nonzero slice run returns the parent to image preparation: correct only an evidenced key/tolerance mismatch, then enlarge cells or split incompatible shape families and regenerate when content reaches a cell edge. Repeating the same failing grid is not recovery. An explicitly selected manual path retains the marker, sets the affected item to `Needs-Manual` with `last_error`, and blocks Quick SVG/export until every named output is supplied and validated. Exhausted automated AI generation or dependent slicing instead follows the no-AI replan below; never retain an unresolved AI/slice row merely to continue. |
| 482 | |
| 483 | **Validation**: Before §3, verify every required file-backed resource has a usable terminal state and every `slice_names` basename resolves to its real PNG output. Any missing name resumes the owning acquisition/slicing step; it cannot be deferred to the final SVG checker. |
| 484 | |
| 485 | **Quick exhausted-automation no-AI replan**: Follow [`image-generator.md`](../../references/image-generator.md) §7 when an automated AI path or its required dependent slicing is exhausted: ask no path question, enter no manual fallback, remove the affected AI jobs and stale manifest entries, preserve their communication content with native editable text/SVG or already prepared non-AI assets, and continue the same run. An explicitly selected `manual` path remains subject to the file-readiness gate. To retain AI imagery after automated failure, repair the generation capability and start a new Quick run. |
| 486 | |
| 487 | **Image inspection boundary**: acquisition-time suitability review follows the |
| 488 | owning AI/web/slice reference. Once resources reach terminal status, SVG |
| 489 | authoring follows `executor-image.md`'s narrow placement inspection: inspect only |
| 490 | one specifically ambiguous `Existing`/`Sourced` asset and never routinely reopen |
| 491 | `Generated` outputs. Image to PPTX is the narrow fidelity exception: inspect |
| 492 | every normalized page once for its inventory, inspect every generated |
| 493 | reconstruction layer or shared plate once, and inspect the final recomposition |
| 494 | against the canonical frame. Reopen only the current page or one unresolved |
| 495 | region after that required comparison. |
| 496 | |
| 497 | After image resources change, run `analyze_images.py` so |
| 498 | `analysis/image_analysis.csv` reflects the files that SVG authoring will use. |
| 499 | Operational manifests and provenance are resource truth, not a hidden design |
| 500 | strategy. |
| 501 | |
| 502 | Every required file-backed resource must reach a usable terminal state before |
| 503 | its page. Web `Needs-Selection` blocks until one thumbnail is promoted or the |
| 504 | bounded ranked pages and materially different query variants are exhausted; |
| 505 | only then may a vision-capable owner fetch one adopted-page source package, |
| 506 | review its companion images, and promote only accepted files; never auto-expand |
| 507 | facts URLs or use those packages as the initial pool. |
| 508 | `Needs-Manual` blocks even when an unverified file exists. With no visual |
| 509 | capability, only the strict metadata-ranked web path may reach `Sourced`, and |
| 510 | its provenance must say `selection_method: metadata-ranked` rather than imply |
| 511 | visual confirmation. After selection or manual supply/replacement, validate |
| 512 | evidence and reconcile to `Existing`, `Generated`, or `Sourced`; never bypass |
| 513 | status by preview/file presence or substitute unrelated material. Native |
| 514 | formula markers are authored page content, not file-backed resources or |
| 515 | terminal-status rows. |
| 516 | |
| 517 | --- |
| 518 | |
| 519 | ## 3. Direct SVG Authoring |
| 520 | |
| 521 | Always read the following fixed authoring references directly in one batch; do |
| 522 | not route among them one file at a time: |
| 523 | [`shared-standards-core.md`](../../references/shared-standards-core.md), |
| 524 | [`svg-effects.md`](../../references/svg-effects.md), |
| 525 | [`native-shape-authoring.md`](../../references/native-shape-authoring.md), |
| 526 | [`preset-shape-vocabulary.md`](../../references/preset-shape-vocabulary.md), |
| 527 | [`semantic-svg.md`](../../references/semantic-svg.md), |
| 528 | and [`executor-structure.md`](../../references/executor-structure.md). Retain |
| 529 | only the mode/style detail files selected during one-pass design resolution and |
| 530 | realize that chosen direction. Exact `*_references` define the catalog material |
| 531 | actually used by a custom: apply one basis under its behavior, synthesize several |
| 532 | by their stated contributions, or follow the behavior directly when none exist. |
| 533 | |
| 534 | Do not load `executor-base.md`: it owns Default's persisted-plan handoff, |
| 535 | first-page gate, and completion routing. Excluding that file is not a capability |
| 536 | exclusion; Quick loads the shared and conditional execution authorities here |
| 537 | directly. Reuse the already-loaded image-layout authorities. When any image |
| 538 | exists, read once before the first affected page and reuse throughout the valid |
| 539 | execution context: [`executor-image.md`](../../references/executor-image.md) |
| 540 | and [`svg-image-embedding.md`](../../references/svg-image-embedding.md); add |
| 541 | [`executor-web-image.md`](../../references/executor-web-image.md) for a placed |
| 542 | `Status: Sourced` image or filename recorded in `image_sources.json`. |
| 543 | Reread only after a known file change or context invalidation. |
| 544 | |
| 545 | `executor-structure.md` is loaded once before all SVG authoring so every |
| 546 | `Structure=yes` result can apply its qualitative topology grammar. |
| 547 | `native-shape-authoring.md` independently owns contour selection and compound |
| 548 | page geometry for both Structure results. Reuse both throughout the valid |
| 549 | execution context; before P01, read the complete preset vocabulary once, then |
| 550 | reread only after a known file change or context invalidation. |
| 551 | |
| 552 | **Mandatory — per-image-page composition decision**: For every page with one |
| 553 | or more images, after its content and communication move are |
| 554 | determined but before choosing geometry, apply |
| 555 | [`executor-image.md`](../../references/executor-image.md)'s active image-integration |
| 556 | decision once. Keep its role, direction source, parent |
| 557 | contour, slot/rhythm system, image/shape action, and any continuity only in |
| 558 | active context; create no artifact, spec, lock, manifest, or extra pass. A |
| 559 | deliberate plain or equal-grid result remains valid when it communicates the |
| 560 | relationship better. |
| 561 | |
| 562 | **Mandatory — native formulas**: Quick creates no formula resource or manifest; |
| 563 | retain exact LaTeX in active context, then choose ordinary text, same-paragraph |
| 564 | native inline math, or a standalone native block and author its matching SVG |
| 565 | preview under [`native-formula.md`](../../references/native-formula.md). |
| 566 | |
| 567 | **Mandatory — native hyperlinks**: Quick creates no hyperlink resource or |
| 568 | manifest. For every selected link, retain the exact target, choose an inline or |
| 569 | whole-object carrier, and author canonical SVG `<a href>` under |
| 570 | [`native-hyperlinks.md`](../../references/native-hyperlinks.md). Never guess an |
| 571 | unknown destination. |
| 572 | |
| 573 | Image to PPTX replaces the open image-composition and page-geometry decisions |
| 574 | for its canonical page frame: preserve the source geometry, restore text |
| 575 | natively, preserve source-graphic identity through the prepared exact or |
| 576 | reconstructed asset, and use the active-context registered layer/plate stack |
| 577 | for scene imagery. Run either ordinary decision only for additional non-source |
| 578 | content whose placement or geometry is not already fixed by that surface. |
| 579 | |
| 580 | **Mandatory — per-page Structure decision**: after the current page's content |
| 581 | and communication move are determined, but before choosing any geometry or |
| 582 | shape, decide whether geometry must carry qualitative `order`, `link`, `parent`, |
| 583 | `membership`, `contrast`, or `overlap`. Keep the yes/no result and, when yes, |
| 584 | the relationship meaning and reading path in active context only; create no |
| 585 | artifact, spec, lock, manifest, or extra pass. |
| 586 | |
| 587 | - `no` → use Quick's shared base authoring path in this section. |
| 588 | - `yes` → apply the already-loaded Shape Composition Grammar before drawing. |
| 589 | |
| 590 | This decision is mandatory on every page and cannot be satisfied by the |
| 591 | capability menu, visualization recall, template geometry, or a later check. |
| 592 | |
| 593 | **Mandatory — independent per-page geometry move**: after the Structure result |
| 594 | and any applicable topology resolve, apply |
| 595 | [`native-shape-authoring.md`](../../references/native-shape-authoring.md) §2.1 |
| 596 | to the transient geometry job, actual content, retained deck shape language, |
| 597 | resolved style, and complete loaded native vocabulary before writing |
| 598 | coordinates. Select through direct semantic comparison; use `describe --compact` only when objective geometry |
| 599 | facts could change a serious candidate decision. This move owns the exact-fit |
| 600 | geometry gate, independent relationship / carrier fit, |
| 601 | contour-family / exact-result choice, reader effect for a generic or undrawn |
| 602 | result, running actual-geometry signature, and materialization boundary. A |
| 603 | primitive remains valid when it wins this comparison; there is no preset quota. |
| 604 | Apply the move to both `no` and `yes`; keep the current decision in active |
| 605 | context and never change the Structure result. |
| 606 | |
| 607 | | Deterministic trigger | Additional authority | |
| 608 | |---|---| |
| 609 | | A selected primary Chart/Table `family/key` | [`executor-visualization.md`](../../references/executor-visualization.md), then the matching Chart/Table authority | |
| 610 | | Any actual value-driven geometry, including mini/inset charts and sparklines | [`executor-chart.md`](../../references/executor-chart.md) | |
| 611 | | Any actual row × column fact grid | [`executor-table.md`](../../references/executor-table.md) | |
| 612 | | Any mathematical notation that may require native math | [`native-formula.md`](../../references/native-formula.md) before choosing ordinary text, inline native math, or block native math | |
| 613 | | Any external or same-deck click hyperlink | [`native-hyperlinks.md`](../../references/native-hyperlinks.md) before authoring its inline or whole-object SVG anchor | |
| 614 | | A used preset pattern fill, or one independent Chart/Table object resolved as `<object-key>=yes` in active context | [`native-data-interface.md`](../../references/native-data-interface.md) before drawing that object | |
| 615 | | Any data-driven chart geometry | [`verify-charts.md`](../stages/verify-charts.md) after the complete roster and before the one final checker | |
| 616 | |
| 617 | Chart/Table reference and final information model are independent loading |
| 618 | signals; load every applicable authority. Selection never makes an object |
| 619 | native-ready or replaces the per-page Structure decision. |
| 620 | |
| 621 | Keep the core's shared visual-quality / leading defaults and `svg-effects.md` §6.1 job diagnostic active while authoring, with its Visual Job Router as recall. Explicit user/template requirements and the resolved style override compatible aesthetic defaults, never technical Required / Forbidden boundaries, carrier eligibility, or native capability discovery. Treat selected style composition examples as generative vocabulary rather than a finite layout menu. |
| 622 | |
| 623 | **Per-page execution anchors**: apply the transient core-message, typography-role, semantic-color, body-frame, density, and composition anchors resolved in §2 while authoring; they guide the current run without creating a persisted planning artifact. |
| 624 | |
| 625 | When `notes/total.md` was frozen from a final script, retain its corresponding |
| 626 | segment while authoring each page. The visible state and real direct-root |
| 627 | semantic groups must support that spoken segment without duplicating the full |
| 628 | script as body copy or changing its wording. |
| 629 | |
| 630 | Use one zero-padded filename width sized for the resolved roster, such as |
| 631 | `01_cover.svg` through `12_end.svg` or `001_cover.svg` through `120_end.svg`. |
| 632 | Never reuse pages from another run: the exporter publishes every SVG discovered |
| 633 | under `svg_output/`. |
| 634 | |
| 635 | **Canvas**: use the canvas resolved in §2: explicit user choice, otherwise the |
| 636 | selected Layout/Deck structure-owner canvas, otherwise `ppt169` with |
| 637 | `viewBox="0 0 1280 720"`. For another registered format, load |
| 638 | [`canvas-formats.md`](../../references/canvas-formats.md) and use its exact |
| 639 | viewBox. Template canvas is a default, not a compatibility gate; an explicit |
| 640 | user canvas may adapt the installed visual system. The first SVG establishes |
| 641 | the export canvas; every remaining page must match it exactly. |
| 642 | |
| 643 | **PPTX structure**: author flat, Slide-local SVG only, including when a Layout or |
| 644 | Deck workspace is installed. In that branch, visibly realize the resolved |
| 645 | template rules and prototype geometry in the complete pages; do not fall back to |
| 646 | free design or merely explain how the template could be used. Include the |
| 647 | complete visible page and all resource references in each SVG; set one root |
| 648 | `data-pptx-page-role` from `cover`, `toc`, `section`, `content`, or `ending`, |
| 649 | and omit Master/Layout/layer/placeholder metadata. A request that specifically |
| 650 | requires reusable native Master/Layout/placeholder output is incompatible with |
| 651 | the lockless Quick exporter and must use the default lock-backed profile. |
| 652 | |
| 653 | **Typography**: name a concrete target-installed/approved PowerPoint family |
| 654 | under [`shared-standards-core.md`](../../references/shared-standards-core.md) |
| 655 | §4.1; do not depend on a lock or generated font asset. |
| 656 | |
| 657 | **Generation pacing**: the current main agent hand-writes the SVG roster in |
| 658 | order. Use P01 to calibrate visual identity and cover-specific expression; use |
| 659 | the first page that exercises ordinary content relationships to calibrate |
| 660 | content geometry and carrier integration. Neither becomes a reusable topology |
| 661 | template. Continue directly without a first-page checker or confirmation stop. |
| 662 | When a motif was |
| 663 | resolved, follow its reuse mode: exact repetition is valid for deliberate |
| 664 | title/corner chrome, while adaptive motifs may vary scale, crop, density, |
| 665 | position, or content interaction. Keep this choice only in active context; |
| 666 | create no planning artifact or approval stop. After every page |
| 667 | exists, run the one final checker below. Apply other supporting tools and |
| 668 | stages only when their capability is actually needed. |
| 669 | |
| 670 | **Hard rule — direct page authoring stays with the current main agent**: write |
| 671 | every page SVG directly in the active context. Do not delegate page generation |
| 672 | to another agent, and do not run a Python, Node, shell, or other generator that |
| 673 | writes slide files into `svg_output/`. Documented fragment-only helpers remain |
| 674 | allowed after the current main agent chooses the object's role, operands, |
| 675 | paint, and z-order and integrates the fragment itself. This boundary does not |
| 676 | restrict resource preparation, inspection, checker, verification, |
| 677 | post-processing, or export tools; a run fails this profile only when a delegated |
| 678 | agent or generator authors a page SVG on the main agent's behalf. |
| 679 | |
| 680 | This is not a resume protocol. If the active context is lost before delivery, |
| 681 | start a clean Quick run rather than inferring an unfinished plan from the files |
| 682 | already present. |
| 683 | |
| 684 | --- |
| 685 | |
| 686 | ## 4. Export |
| 687 | |
| 688 | After every page and required referenced resource exists, run the Quick branch |
| 689 | of [`verify-charts`](../stages/verify-charts.md) when any data-driven chart was |
| 690 | authored. Complete all coordinate repairs first; then run the one lockless final |
| 691 | SVG check: |
| 692 | |
| 693 | ```bash |
| 694 | python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> \ |
| 695 | --quick-generate --stage final --json |
| 696 | ``` |
| 697 | |
| 698 | Fix every blocking error and rerun the same command. |
| 699 | |
| 700 | **Mandatory — final carrier-receipt review**: Review the factual |
| 701 | `[CARRIERS]` summary against the retained page jobs, deck shape language, any |
| 702 | adopted motif, resource roles, and running geometry signatures before export. |
| 703 | Counts and diversity are not quotas; zero preset use alone neither proves fit |
| 704 | nor establishes a defect. When the summary contradicts an active decision, read |
| 705 | only the affected `files[].info.carrier_receipt` rows from the current report, |
| 706 | repair those pages in one consolidated pass, and rerun the same final checker. |
| 707 | |
| 708 | Then export: |
| 709 | |
| 710 | When Speaker Notes is enabled, load |
| 711 | [`executor-notes.md`](../../references/executor-notes.md) after the passing final |
| 712 | check. Validate an already frozen final script or direct-video pre-SVG narration |
| 713 | without regenerating it; otherwise generate `notes/total.md` from the final SVG |
| 714 | roster. Then run: |
| 715 | |
| 716 | ```bash |
| 717 | python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path> |
| 718 | ``` |
| 719 | |
| 720 | **Success criterion**: per-slide Markdown files exist under |
| 721 | `<project_path>/notes/` and cover every published slide. The command exits |
| 722 | non-zero when a slide has no notes or a write fails; repair `notes/total.md` and |
| 723 | rerun before animations or export, and never let leftover files from an earlier |
| 724 | run satisfy this criterion. |
| 725 | |
| 726 | Run [`customize-animations`](../stages/customize-animations.md) after that notes |
| 727 | pass when the active-context outcome or an existing sidecar triggers it. Resolve |
| 728 | deck-wide-only motion through the selected exporter flags instead. |
| 729 | |
| 730 | After visual motion is final, sync a selected cue per |
| 731 | [`animations.md`](../../references/animations.md) §2.2; otherwise create no |
| 732 | `sounds/`. Sidecars never use `templates/sounds/`. This configures the native |
| 733 | PPTX only; `generate-audio` completes direct narrated MP4 delivery with either |
| 734 | the verified native-export mix or an explicitly selected real-time PowerPoint |
| 735 | slideshow capture. Those sound branches are mutually exclusive. |
| 736 | |
| 737 | For Quick recorded/self-running/video delivery, complete the mandatory Custom |
| 738 | Animations stage and validate `animations.json` before the base export unless |
| 739 | the user explicitly requested static or page-transition-only playback. Direct |
| 740 | narrated video derives cue timing only when narration governs groups; otherwise |
| 741 | it exports the canonical custom timing without an object-sync claim. Do not |
| 742 | replace this requirement with deck-wide `-a auto` or page transitions. |
| 743 | |
| 744 | Choose exactly one notes mode for the base export: |
| 745 | |
| 746 | ```bash |
| 747 | # Speaker Notes enabled |
| 748 | python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> \ |
| 749 | --quick-generate --with-notes |
| 750 | |
| 751 | # Speaker Notes disabled |
| 752 | python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> \ |
| 753 | --quick-generate --no-notes |
| 754 | ``` |
| 755 | |
| 756 | `--quick-generate` reads `svg_output/` as the page source and resolves the |
| 757 | project-local assets referenced by those SVGs. It infers one consistent canvas, |
| 758 | uses a lockless flat PowerPoint package, and does not force-disable ordinary |
| 759 | export options. Notes, Custom Animations, and narration remain off unless |
| 760 | selected by the agent or required by the Quick video rule above. Do not run |
| 761 | `finalize_svg.py`. After the validated base export, run |
| 762 | [`generate-audio`](../stages/generate-audio.md) when Narration Audio is enabled; |
| 763 | it owns page audio/SRT, narrated PPTX, the optional raw native MP4, and the |
| 764 | final mixed or captured MP4. When a selected manual capture has not yet been |
| 765 | returned, it owns the capture-ready narrated PPTX handoff instead. |
| 766 | |
| 767 | The exporter requires a passing `final` report whose SVG fingerprint matches |
| 768 | the current `svg_output/`; missing, blocking, non-final, or stale reports stop |
| 769 | before PPTX creation. The default output path retains ordinary backup and |
| 770 | postflight behavior. An explicit `-o <path>.pptx` keeps the ordinary no-backup |
| 771 | behavior. On failure, repair the owning SVG, resource, or optional capability |
| 772 | input, rerun the final checker, then export again; do not create a Design Spec |
| 773 | or lock. |
| 774 | |
| 775 | ```markdown |
| 776 | ## ✅ Quick Generate Complete |
| 777 | |
| 778 | - [x] All required source/resource preparation is complete |
| 779 | - [x] The fixed planning-capability batch was read before the roster, and every selected detail source was read |
| 780 | - [x] The complete 187-name native preset vocabulary was read before P01; each page chose from that full capability surface, with objective candidate details inspected only when needed |
| 781 | - [x] Every page considered suitable carrier combinations without a coverage quota or single-carrier assumption |
| 782 | - [x] The proactive decorative-lettering capability scan ran before carrier selection; every selected lettering job entered an AI item or lettering sheet/slice job, and zero selected jobs remained valid |
| 783 | - [x] The deck shape language remained active independently of any optional motif; every page not bound to literal supplied geometry carried its geometry job into authoring, resolved each drawn contour from its exact family and job, retained the reader effect for any generic or undrawn result, and compared its actual geometry signature before the next page; repetition served the same page job / relationship or continuity motif |
| 784 | - [x] Image need was decided independently of credentials; any zero-image deck followed a complete roster review in which no image job improved communication or the selected non-image carriers fully carried it |
| 785 | - [x] Every `slice_names` output exists after an exit-0 strict-alpha run, and no page whose chosen composition depends on a slice was authored or exported without it |
| 786 | - [x] Every image-bearing page made its one pre-geometry composition decision |
| 787 | - [x] Every image decided its own source from that page's subject and job — not inherited from the resolved visual style — and every externally verifiable subject deliberately not shown as itself was stated with its reason |
| 788 | - [x] Every exhausted automated AI job was replanned under the declared no-AI rule, with its filename, attempted path, concrete error, and replacement carrier retained for final disclosure; N/A when no such replan occurred |
| 789 | - [x] Every selected formula uses the checker-valid ordinary/inline/block form with a matching visible SVG preview and no formula image resource |
| 790 | - [x] Every selected hyperlink uses a checker-valid inline/whole-object anchor and an exact external or same-deck target |
| 791 | - [x] Resolved SVG pages and their project-local references exist |
| 792 | - [x] Every role declared by an installed template spec is locatable in the finished pages, or its non-use is deliberate — checked per installed spec, not from memory |
| 793 | - [x] Every triggered capability-specific preparation and pre-checker verification completed |
| 794 | - [x] The current final report's carrier receipt was compared with the retained page jobs and any factual contradiction was repaired before export, without treating counts as quotas |
| 795 | - [x] The lockless final SVG quality report passes and matches the current SVGs |
| 796 | - [x] Enabled notes were validated/generated and split; enabled custom motion ran through its owning stage |
| 797 | - [x] One native PPTX exists under `exports/` or the explicit output path |
| 798 | - [x] No Strategist, confirmation, root project Design Spec, or lock artifact was created |
| 799 | - [ ] **Next**: Report the base PPTX and any enabled narrated PPTX, raw/mixed/captured MP4, or capture-ready PPTX handoff, plus the resolved mode, visual style, and the image sources actually used. For every no-AI replan, report the affected AI job, attempted path, concrete error, replacement carrier, and that retaining AI imagery requires repairing generation capability and starting a new Quick run |
| 800 | ``` |
| 801 |