Build Html Slides

Build HTML Slides

Create a self-contained presentation bundle with:

• one HTML deck;
• local assets when needed;
• sibling OUTPUT-notes.md presenter notes;
• when requested, sibling OUTPUT-guide.md, OUTPUT-guide.html, and OUTPUT-guide.pdf reader-facing study-guide outputs;
• sibling sources.json when raster assets are used.

Treat every slide as a fixed 16:9 presentation canvas, not a scrolling webpage. Presenter notes are mandatory for new decks in every mode. The reader-facing study guide is optional and must be created only when the user requests it.

Keep Working Files Out Of The Deliverable

Do not create review/, copy-draft.md, contact sheets, render logs, or temporary screenshots beside the final deck. Before research, initialize the workspace even though the planned deck does not exist yet:

bashCopy code
node scripts/render_slides.js --init-workspace OUTPUT.html

This creates and preserves <workspace>/drafts/research-brief.md from the bundled template without opening Chromium or overwriting prior work. On every resumed task or after context loss, read that brief first. After the deck exists, resolve the same workspace with:

bashCopy code
node scripts/render_slides.js --workspace-dir OUTPUT.html

The default is <agent-home>/build-html-slides/workspaces/<deck-id>/, with review/, drafts/, and tmp/ beneath it. Codex uses ~/.codex; Claude Code uses ~/.claude; Gemini CLI uses ~/.gemini. The renderer creates and reuses only the latest review evidence for that deck. Put outlines and copy drafts in drafts/; put contact sheets and disposable transforms in tmp/. CODEX_HOME, CLAUDE_CONFIG_DIR, CLAUDE_HOME, or GEMINI_HOME relocates the matching agent home. BUILD_HTML_SLIDES_AGENT_HOME overrides any agent home, and BUILD_HTML_SLIDES_WORKSPACE_ROOT overrides the workspace root directly.

The deliverable directory should contain only the HTML deck, presenter notes, the requested study-guide outputs and their capture assets, sources.json when used, and assets referenced by the deck. Keep the workspace for incremental revisions. Remove it only when the user asks or the evidence is no longer needed:

bashCopy code
node scripts/render_slides.js --clean-workspace OUTPUT.html

An explicit legacy REVIEW_DIR remains supported when integration with another system requires it.

Decide The Work Mode

Read references/validation-contract.md before substantial work.

For every new deck, resolve two explicit intake choices before researching, drafting, creating files, or generating assets: the validation mode and whether the optional reader-facing per-slide study guide is needed. Ask both questions together when both are unanswered. If the user already answered either choice, retain that answer and ask only the unanswered question; never ask again for an answer already given. Present Quick Draft and Full Validation with their scope and relative turnaround, and present the study guide as an optional companion consisting of sibling Markdown, readable HTML, and PDF outputs. Do not silently infer either choice, even when one appears likely from context. Interpret explicit choices semantically rather than with a keyword table or substring parser.

• Edit Only: ordinary revisions where the user primarily wants a change, not new assurance. Make the requested edit and do not create a new deck render or validation pass. Update notes when the story, claim, order, or talk track changed. If the deck has a study guide, update it whenever a slide's claim, diagram, process, terminology, order, or practical meaning changed, then regenerate its HTML/PDF companion. Disclose that the deck revision was not re-rendered or validated; guide-only capture/PDF production is not deck validation.
• Quick Draft: the user prioritizes iteration, exploration, a first usable version, or the shortest turnaround. This is a creation-only mode. Build the HTML, presenter notes, sources cache, required assets, and the study guide only when requested, then stop. Do not run check_environment.py, install browser dependencies solely for validation, render validation screenshots, run deterministic validators, invoke AI visual review, calculate a quality score, or request render-assurance review. When the study guide was requested, Chromium may be used only by render_slide_guide.js to produce its per-slide captures and PDF; this production use is not validation evidence and must be disclosed. The exactly one pre-authoring research/storyboard editorial pass remains part of authoring and is not validation evidence. Keep design ambition high during authoring, but clearly disclose that the deck itself was not rendered or validated.
• Full Validation: the output needs strong delivery assurance. Standard risk is the fixed default: render all slides, inspect every slide with AI once, score the settled deck once, and use bounded independent final review.

Do not infer high risk from technical complexity, image count, visual complexity, uncertainty, or audience sensitivity. Use high risk only when the user explicitly identifies legal/regulatory review, public release/publication, or a consequential decision, and pass --high-risk-reason legal|public-release|consequential-decision. Standard uses two primary reviewers; high uses three. Both use a bounded final cross-review: at most five slides for standard and six for high.

After the user chooses Full Validation, run this preflight before substantive work:

bashCopy code
python3 scripts/check_environment.py

The preflight never installs software. If it fails, report the exact missing or incompatible components and ask whether the user wants them installed. Stop until the user answers unless the original request already gave explicit installation consent. Never run npm install, npx playwright install, an OS package manager, or elevated installation commands without that consent. After approval, prefer python3 scripts/install_browser_dependencies.py --consent for a user-scoped Playwright/Chromium runtime; use --with-deps only when the user also approved system-library installation. Rerun the preflight and start deck work only after it passes.

Build Workflow

1. Run --init-workspace and read references/research-first.md. Before HTML authoring, semantically choose the evidence burden from the audience, decision, uncertainty, and requested explanatory depth. Do not use keyword matching or static parsing. Fill drafts/research-brief.md as the reasoning source of truth; analytical work must explain metric relevance, competing explanations, anomalies, and decision implications, while deep technical work must trace mechanisms, boundaries, tradeoffs, and failure modes.
2. Inspect supplied files and relevant authoritative sources, then read references/audience-story-routing.md. Build the decision question tree, evidence-and-reasoning ledger, and question-linked storyboard. Every slide must carry an incoming question, answer, evidence IDs, so what, next question, and explicit connection from the prior slide. For every image-worthy slide, also record the intended visual job, preferred unique factual asset, source or search target, and the fallback composition if no strong asset is found. The fallback must be omit and redesign, not a weak drawing, generic substitute, repeated photo, or empty media promise. Keep exact facts, citations, user decisions, terminology, open limits, story order, and visual decisions in the brief. On resume, reread the locked brief before the deck source.
3. Run exactly one dedicated AI editorial review of the initial research and storyboard before HTML authoring. As part of that pass, read the proposed slide headlines alone in sequence and reject any headline that narrates the author's work instead of stating the audience-facing answer or implication. Record every finding together in drafts/research-storyboard-review.md, apply one consolidated revision, then run lock_research_storyboard.py. Do not rerun or reopen this editorial review during implementation, rendering, visual QA, or finalization. Read references/performance-debugging.md, start the persistent research timer immediately after workspace initialization, and use the atomic transition command at every real boundary: research → storyboard → editorial-review → editorial-revision → asset-selection → asset-production → implementation → common-preflight → render-automation → ai-review → final-review. Only one manual stage may be active. research means evidence gathering only; asset-selection means evaluating and choosing images; asset-production means downloading, generating, converting, and recording provenance. External publication or Notion capture is outside this production timing contract.
4. Read references/quality-bar.md, references/theme-taxonomy.md, references/theme-playbook.md, references/theme-gallery.md, references/theme-typography.md, references/cover-design.md, and references/design-contract.md; read references/designer-reference-sources.md when external visual research would improve the direction. Treat scripts/theme_registry.json as the canonical selector inventory; its theme names and theme-gallery.md headings must match exactly. Classify all six semantic axes—job, evidence, density, emotional register, surface family, and focal anchor—and pass them explicitly to select_visual_direction.py with --job, --evidence, --density, --emotional-register, --surface-family, and --focal-anchor. Do not use raw keyword, substring, or topic-noun matching as a routing substitute. When recent related decks or gallery thumbnails are available, inspect three to five and record their surface, title anchor, hero form, type character, accent strategy, and cover family as signatures to avoid. Run the selector with --output WORKSPACE/drafts/design-contract.json; do not hand-write or edit the generated contract. Treat the primary and alternatives as a candidate set, then use design judgment across subject, purpose, audience, language, evidence, and available authentic assets. Lock the strongest candidate; selecting a non-primary candidate requires its exact --select-theme and a concrete --selection-reason. The locked theme, cover family, surface, title anchor, hero form, type direction, palette direction, and generated semantic color-token pairs are one indivisible constraint: use every foreground/background pair together, never override only its foreground or only its background. Do not invent a new post-selection theme name, including Systems Blueprint, or splice in another direction's palette and component language. Retired registry directions must never be selected, imitated, or reintroduced through aliases. Write a separate cover brief, compare at least two materially different slide-1 compositions inside the locked grammar, and implement the stronger one. Plan several body composition families and record one data-composition-family per slide. Unless the user supplied a brand type system, infer an attractive language- and topic-appropriate pairing without asking a separate font question.
5. Read references/style-presets.md. Copy assets/runtime-shell.html to the output path. Replace all placeholder sections while preserving the stage fitter and navigation runtime. Replace the shell's sample design metadata with the exact body attributes and contract ID from drafts/design-contract.json; the shell has no art direction. Replace its neutral font variables and styling with the locked theme system.
6. Read references/media-strategy.md, then plan official/supplied/sourced/generated assets and diagrams. During storyboarding, explicitly mark slides where a visual would materially improve comprehension, subject recognition, scale, context, emotional focus, attention reset, or chapter rhythm. Unless the user explicitly requests a pure-HTML, image-free, or typography/diagram-only deck, search for relevant sourced photographs or factual imagery before settling the visual plan. Use what earns its place; omit imagery where it adds no information. Classify each meaningful visual role as factual subject/evidence or illustrative support. When the deck introduces an existing named or released person, group, game, product, place, event, interface, or work, complete the factual asset search before considering ImageGen; generated art must never stand in for the real subject. When an image generator is already available, use it without an extra permission round for a defined non-factual atmosphere, concept, hypothetical scenario, or decorative role that improves the audience experience. Decide semantically whether the audience needs to see real products, facilities, equipment, people, organisms, tissue, experiments, interfaces, or places. Apply a strict visual-value gate to every custom map, illustration, decorative SVG, and generated support image: use it only when it communicates a necessary relationship more clearly than a sourced asset or an image-free layout and can reach professional reference quality at full-slide size. Never invent geography, landmarks, routes, scale, or decorative pseudo-maps. If the result is amateur, unverifiable, generic, or merely fills space, do not draw it; use an authoritative map, a relevant sourced photograph, or omit it and redesign the slide. Read references/architecture-diagrams.md when systems, flows, deployment, integrations, or trust boundaries matter.
7. Implement the cover and densest Korean/body-copy slide first, optionally the closing slide, and mark them data-common-preflight="cover|dense|closing". Run python3 scripts/validate_common_preflight.py OUTPUT.html to render only those two or three slides twice across the canonical profiles. Fix and freeze shared CSS, local Korean fonts, stage scaling, and navigation before finishing the remaining slides. Then implement the other semantic <section class="slide" data-title="…" data-composition-family="…"> elements. Put the selected headline register on <body> as data-headline-register="direct-technical|decision|evocative" and keep each visible <h1> or <h2> exactly equal to its slide's data-title after whitespace normalization. Never repeat one composition family three slides in a row. Keep generic card-grid, component-wall, or dashboard families to at most two slides per ten; reserve data-dashboard-intent="evidence" for a slide that literally shows a real dashboard. Give every slide exactly one direct .slide-media and .slide-content child. Keep meaningful copy and non-croppable visuals in the content-safe layer. When media and content mirror the same card or frame across those layers, bind the pair with data-frame-id="name" and data-frame-for="name" so rendered edges are checked. Mark a genuinely intentional mismatch only on the exact elements with a supported data-overlap-intent; never exempt a whole slide.
8. Create OUTPUT-notes.md from assets/speaker-notes-template.md. Use the exact slide number and title. Include purpose/audience, natural 30–90 second talk track, emphasis, transition, and source/caveat guidance without repeating slide text.
9. If the user requested the optional study guide, create OUTPUT-guide.md from assets/slide-guide-template.md. This is a standalone technical or subject-matter companion for a reader who cannot hear the presentation. Add a short primer, prerequisites, or terminology section before the slide sections only when it materially helps the intended reader; omit empty boilerplate. Use the exact slide number and title. Explain not only what is visible, but also the background, intermediate reasoning, mechanism, component responsibilities, operating conditions, practical examples, tradeoffs, failure modes, and terminology that the slide omitted for space. Supply only details supported by the locked brief or authoritative sources; never invent missing facts. Lead with the answer, define unfamiliar terms at first use, explain one causal step at a time, and use a concrete example where abstraction would otherwise remain hard to grasp. Do not circle the point with long introductions, repeated summaries, inflated phrasing, or jargon chains. For a pipeline or architecture diagram, trace data or control flow from entry to destination and explain what each node transforms, filters, stores, or decides. For a chart or comparison, explain the metric, denominator, assumptions, interpretation, and what must not be concluded. The prose must stand alone without the presentation, but every slide capture must appear immediately above that slide's explanation. Do not include presenter cues, a full read-aloud script, visual-reading instructions, or a paraphrase of the visible labels in place of subject explanation.
   • Keep the reader HTML navigable: generate a slide index linked to numbered sections on wide screens and collapse it into normal flow on narrow screens. Treat this as document structure, not deck-theme inheritance.
   • Group every level-three explanation heading with its following paragraphs, lists, tables, or callouts in one semantic subsection. Give subsections visible spacing, a subtle surface or rule, and clear indentation so readers can scan where one explanation ends and the next begins. Preserve the grouping in narrow layouts and print without forcing a specific deck color theme.
   • Render Markdown tables as semantic <table> elements. Use a fixed or bounded layout, wrapping cells, repeated print headers, and row-level break protection. Never leave pipe-table source visible or allow a table to widen the page.
   • Keep unfamiliar technical terms only when they are needed. Define each at first use with a short, concrete sentence, then use one consistent term. Replace abstract noun chains with named actors and actions.
10. Before rendering any requested Korean study guide, invoke humanize-korean as a mandatory final prose pass after all facts and explanations are complete. For a guide longer than the companion's per-call limit, split it into coherent chunks of at most 5,000 characters without splitting a slide section, humanize each chunk, verify facts and ordering, then reassemble it. Copy the humanized text and its HUMANIZE-SUMMARY evidence into OUTPUT-guide.md; do not render or deliver a Korean guide without that evidence. Then run node scripts/render_slide_guide.js OUTPUT.html OUTPUT-guide.md to create sibling readable OUTPUT-guide.html and OUTPUT-guide.pdf outputs plus local capture assets. In Quick Draft this Chromium call is guide production only, not deck validation. Settle visible copy from the locked research brief, polish the other Korean slide copy and notes once, review for semantic drift, then run freeze_authoring_state.py as documented in research-first.md. This copy freeze may be refreshed after a text repair; the research/storyboard editorial review must not be rerun. Do this before the first Full Validation render.

• Before writing the PDF, fail on broken captures or horizontally overflowing tables. In print CSS, hide sticky navigation and the slide index, start each numbered slide section on a new page, keep figures and table rows intact where possible, and use explicit A4 page margins with background printing enabled.

11. For Quick Draft, deliver immediately after implementation without validation evidence. For Full Validation, run python3 scripts/validate_all.py OUTPUT.html --mode full --phase prepare. The first prepare starts a durable 60-minute validation cycle bound to the selected visual grammar. Ordinary fixes, failed renders, shared-CSS changes, and metadata edits do not reset it. When the user fully rejects the current theme and the locked selected visual grammar genuinely changes with full impact, start one fresh cycle with --restart-validation-session theme-invalidated; the invalidated cycle remains in session history and its elapsed time is not charged to the replacement theme. The parallel-safe deterministic checks run with bounded concurrency and finish as a group; they do not stop at the first failure. If any fail, read the complete <workspace>/validation-failures.json report before editing. Every validation subprocess and phase wall clock is appended to <workspace>/workflow-timing.json; add --debug-timing when live millisecond diagnostics are useful. Review slide 1 before ordinary batches. Every gradient, image-backed contrast, or split-background warning creates a hash-bound warning review that must state whether the color boundary crosses text, labels, or shapes. Fill only the generated primary batches from the structured output of reviewers that actually opened every assigned full-size capture, then run --phase verify and --phase finalize-prepare. Never create or run a helper script that assigns reviewer identities, copies required_ai_profiles into inspected_profiles, bulk-fills observations, changes every check to PASS, or marks batches complete. If an actual image-inspection call cannot be made, stop with validation incomplete; a plausible review record is not a substitute. Finalize-prepare generates at most 16 normal captures per contact sheet for one fast deck-level overview plus at most five standard or six high-risk full-size cross-review slides, without rerendering. Complete the overview, score, and generated cross-review batches from the independent editor's returned findings, then run --phase finalize-verify.
12. On a deterministic failure, do not fix the first message and immediately rerun. Group the complete report by repair_lane, then use parallel agents only for lanes with disjoint file ownership. Notes may own only OUTPUT-notes.md; the guide lane may own only OUTPUT-guide.md; media provenance may own only assets and sources.json; the main agent retains sole ownership of shared HTML/CSS/runtime and integrates every lane. Never give two writers the same file. After all independent repairs are integrated, rerun prepare once. On later prepare calls, the typed classifier automatically discovers changed slides even when --slides is omitted. Pure copy, image, or slide-local CSS refreshes only affected slides; structure/order changes add neighbors; real shared CSS/runtime changes require a fresh common preflight and one full render. An unchanged-source rerender is forbidden: treat intermittent pixels as renderer failure instead of retrying until a favorable capture appears. Treat rendered pixels as truth; never synthesize PASS records or override reviewer FAIL.
13. Stop any active workflow timer, run python3 scripts/workflow_timer.py --workspace WORKSPACE report, and use the stage totals to disclose the actual bottleneck when turnaround was material. Deliver the deck HTML, notes, requested study-guide Markdown/HTML/PDF, sources cache, asset provenance, selected mode, and only the checks actually performed. Report the validation workspace and timing report separately; never present them as deliverables.

Full Validation controls assurance depth, not research breadth, art direction, or visual-media variety. It must not turn an image-worthy presentation into a chart-and-SVG report. For 20–25 slides, target 45 minutes. At the 60-minute deadline, stop all ordinary deck work, scoring, finalization, approval, publication, and deployment. The only exception is the mandatory slide-1 gate: if the current cover still needs a source fix, rerun prepare --mode full --slides 1 --cover-rescue; after the actual full-size AI inspection is recorded, run --phase cover-verify. This exception never marks Full Validation complete. A failed or pending cover, an unresolved cover warning, or an expired session blocks approval and deployment even when the rest of the deck looks usable. Preserve current evidence and report validation incomplete with unresolved findings.

Companion Skill Routing

• Inspect the skills already available in the current agent session before drafting. Never install or configure a missing optional companion during deck work without explicit consent.
• Availability is sufficient consent to use humanize-korean when its routing rule matches. Do not ask whether to use it after it is installed.
• A requested Korean study guide has a hard dependency on humanize-korean. Check availability as soon as the user opts in. If it is missing, ask for installation consent and stop guide finalization until it is available; do not replace this required pass with a manual approximation. For Korean slide copy and presenter notes outside the guide, use humanize-korean when available and otherwise follow korean-copy.md manually.
• Build technical diagrams directly with semantic HTML/CSS or self-contained inline SVG. Read references/architecture-diagrams.md for diagram selection, construction, accessibility, and validation rules.
• Keep source facts, boundaries, relationships, and protocol labels in the research brief. Do not install or fetch a separate diagram companion during deck work unless the user explicitly asks for one.

Story And Copy

• Give every slide one main claim and one communication job.
• Build the question-linked slide-role table in the research brief with audience, incoming question, answer, evidence IDs, so what, next question, decision job, detail level, main visual, and transition.
• Write audience-facing headlines as findings, decisions, tensions, or necessary questions—not as narration of what the author compared, checked, reviewed, analyzed, or sampled. In report decks, phrases equivalent to “10 items were compared,” “10 launches were confirmed,” or “32 titles were reviewed” belong in an eyebrow, subtitle, metric label, methodology box, or source line. The headline must say what the evidence means, such as concentration in the top two, ten launches in the half-year, or a platform sample not representing the whole market. A procedural slide may use an action headline only when teaching that procedure is its explicit communication job.
• Choose the headline register from the presentation job. Technical shares, engineering seminars, workshops, runbooks, and training decks default to direct technical headlines. Executive decision decks may use implication or decision headlines. Brand, culture, entertainment, keynote, and explicitly emotional narratives may use an evocative register when atmosphere is part of the communication job.
• Direct technical headlines may be short. Use one of three forms: a concrete question (곡선은 왜 늘어났나, 파라미터를 왜 의심하나), a literal topic/action label (Hubble Flow 필드 읽기), or an explicit result/boundary (OpenBao OIDC로 Hubble UI 접근을 인증하고 namespace 권한은 별도로 제어한다). Name the actual system, product, protocol, interface, command, parameter, graph, field, or operational object needed to identify the slide. Do not force every technical answer into an aphoristic A가 아니라 B, A지만 B, or A일 뿐 construction. Put metaphor, tension, or memorable phrasing in a subtitle or speaker notes unless the deck's chosen register is genuinely evocative.
• In direct-technical decks, prefer noun phrases and compact comparison labels for configuration, architecture, field-reference, and comparison slides: Static vs Dynamic Exporter is better than Static Exporter와 Dynamic Exporter의 설정·변경 방식을 비교한다. Reserve full -다 sentences for a result, boundary, or decision that genuinely benefits from a declarative claim. Never use declarative endings on three consecutive titles, and keep them to at most 40% of the deck.
• Before HTML authoring, read only the slide headlines in order. Reject any sequence that sounds like a work log, table-of-contents label, method note, or chart caption; the headline-only outline must still communicate the report's argument.
• Mixed executive, business, and engineering audiences often need decision context and impact before architecture, but derive the sequence from the request rather than applying that example mechanically.
• For Korean decks, read references/korean-copy.md. Prefer established Korean names and natural spoken Korean. Keep English for official names, standards, acronyms, or a small secondary label.
• Validate unstable or consequential facts against authoritative sources. For market-specific prices, availability, schedules, regulation, or launch information, read references/source-locality.md and use the target region.

Art Direction

• Translate the theme into type, surfaces, shapes, imagery, information density, and motion, not color alone.
• Treat slide 1 as the deck's highest-priority art-direction decision. It must establish the literal subject, opening promise, and visual tone within roughly three seconds; do not spend the visual ambition only on body slides.
• Give slide 1 a dedicated full-size refinement pass after its first settled render. Inspect subject authenticity, focal crop, title wrapping, type contrast, color integration, depth, logo and metadata placement, edge details, and navigation clearance. A cover for an existing named subject needs an authentic identity anchor; generated scenery may support it but cannot replace it.
• Choose typography proactively from the language, subject, audience, and room. Declare --font-display, --font-body, and --font-mono; use a deliberate display/body contrast when the theme benefits from it. Do not ship the shell's neutral font stack unchanged or fall back to bare system-ui as the final art direction.
• Use theme-typography.md to define real local faces, language coverage, weight roles, and theme-specific cautions. Treat the listed faces as licensed starting points, not mandatory downloads.
• Use only weights present in the selected local font files and keep font-synthesis: none. Bundle a real bold/variable face instead of synthetic Korean bold. Every <strong> or <b> must remain visibly distinct through a supported weight or another deliberate cue; do not reset it to the parent's weight and color.
• Use the theme taxonomy and gallery as optional vocabulary, not a template library or closed taxonomy. Classify the communication job, evidence medium, density, emotional register, surface family, and focal anchor before selecting a named direction. Never select from the topic noun alone; combine compatible grammar or write a bespoke theme contract when that produces a better deck.
• Once design-contract.json is locked, treat the selected result as binding for that deck. If the direction must change, rerun the selector and replace the contract before authoring; do not silently reinterpret Swiss Signal, Mission Control, or another named direction into an unselected hybrid.
• Treat selector-generated semantic colors as paired foreground/background roles. Apply both members of a pair together; foreground-only and background-only overrides are prohibited because they invalidate the generated contrast relationship.
• Classify the communication job before mapping a subject to a theme. For travel, distinguish consumer magazine, premium hospitality, documentary reportage, and expedition records; ordinary leisure guides default to Destination Magazine rather than Field Notes.
• Test the longest title and densest body copy in the actual writing system before committing to typography.
• Treat rendered line quality as geometry, not taste alone. Display copy must not leave one or two Korean characters or punctuation stranded on a final line, adjacent glyph rows must not collide, and persistent navigation must not cover captions or footer text. Fix copy, width, font size, or line-height before AI review rather than approving a box that technically contains broken text.
• Do not ship generic demo styling, repeated three-card layouts, decorative gradient blobs, or a recognizable reference deck copied pixel for pixel.
• Prefer no visual to a low-quality visual. A custom map, illustration, or decorative diagram that is geographically unverifiable, visually amateur, generic, misleading, or weaker than a sourced photograph is a blocking quality defect, not harmless decoration. Remove it and rebalance the composition when no professional-quality replacement is available.
• Promotional, entertainment, product, travel, event, and narrative decks normally need meaningful raster imagery across the story. Technical, market, industrial, and research decks need the right mix of sourced real-world or scientific imagery, data, diagrams, states, and flows. Do not treat rigor as a reason to hide a physical or observable subject behind charts and SVGs.
• Use whitespace for hierarchy, not as a substitute for composition. Sparse-keynote pacing belongs to intentional hero, quote, vision, or chapter beats. For ordinary technical, report, workshop, and evidence slides, roughly 55–85% meaningful safe-frame occupancy is a review heuristic; for covers, roughly 60–85% is appropriate unless a full-bleed image or isolated artifact deliberately owns the field. These ranges guide judgment and are not validator quotas.
• Match every container to its information load. A large bordered or filled box with only a heading, one sentence, or a few short bullets is an underfilled container and a quality defect. Shrink it to its content, remove the surface and use open alignment, or earn the area with meaningful imagery, data, comparison, process, or annotation. Do not stretch sparse facts into equal-height cards merely to fill a grid.

Asset Contract

1. Inspect user-supplied assets first and copy selected files into a descriptive local assets folder.
2. When several independent sourced assets are needed, fetch and transcode them with bounded concurrency instead of a serial download loop. Keep one result record per asset, cap concurrency to avoid remote throttling or local memory pressure, and fail each asset independently so one broken URL does not hide the status of the rest.
3. Read references/asset-discovery.md. For named people, groups, brands, products, released games, events, institutions, places, or projects, search official photos, screenshots, title art, packaging, logos, and other factual imagery first, then widen discovery through topic-specific archives, creator accounts, visual-search platforms, social posts, photo communities, and fan communities. A generated lookalike is not a fallback for unsuccessful discovery. Do not stop after one official page or one generic image query. For fan-art-heavy work, use the search targets as checkpoints and avoid indefinite research. Preserve aspect ratio, clear space, signatures, and marks.
4. For games, animation, characters, and fan-art-heavy decks, read references/fan-art-budget.md. Internal/private decks may record the discovery URL and visible creator handle without reverse-origin tracing. Public or commercial decks require verified reuse rights or a safer official, licensed, supplied, or original replacement; reduce the number of works instead of extending research beyond the agreed turnaround.
5. For slides claiming a named fictional character or real person, read references/identity-review.md. Ground each subject with a separate official, licensed, or supplied local WebP reference and visible cues, then annotate every meaningful subject image. Identity review is automatically activated by subject metadata and character/person/profile markup; data-identity-review="required" is explicit documentation, not the only trigger. Filenames, folders, alt text, captions, and source tags are not identity evidence.
6. Read references/image-generation.md when original raster imagery would improve the story. Use a configured image-generation tool only for non-factual atmosphere, concepts, scenarios, or decoration. Its absence does not fail the browser preflight or block ordinary deck work. Never install or configure a generator without consent, and do not generate a real idol, celebrity, historical person, released game, gameplay screen, product, place, artwork, logo, interface, event, or evidence image as a substitute for sourced material. Set every generated raster use's data-media-purpose to one of atmosphere, concept, scenario, or decorative; source_cache.py --check rejects generated subject, evidence, and identity roles.
7. Every raster image referenced by the deliverable must be WebP. Keep SVG only for genuine vector logos, icons, and editable diagrams. WebP conversion does not repair a thumbnail, blur, ringing, block artifacts, or prior upscaling. Prefer source pixels at least 1.25× the maximum rendered device-pixel size and replace visibly soft assets even when the intrinsic dimensions technically pass.
8. Use <img>, <picture>, or SVG <image> with local paths. Do not hide raster ownership in global CSS backgrounds.
9. Classify media as decorative, meaningful, or mixed. Decorative media may use cover; logos, title art, products, posters, screenshots, diagrams, character art, and edge-important key visuals use contain. Mixed media may use a covered backdrop plus a contained foreground copy.
10. Avoid stretching and careless reuse. Give distinct slides distinct primary images by default. A continuity asset may appear twice only when the two appearances have different narrative roles, one is clearly subordinate, and both uses carry the same non-empty data-repeat-ok token with thumbnail plus hero|detail roles. Cropping, resizing, recompressing, recoloring, or re-encoding one photo does not create a new asset or a new visual idea.
11. Maintain sources.json schema 2 with local path, hash, asset roles, source kind, URL where applicable, verification time, and credit. data-identity-reference files are cache entries even when not rendered and must use an authoritative source kind. Run source_cache.py --update before researching a revision and revisit only needs-review records.
12. Placeholders may exist only in the private authoring workspace. Do not knowingly deliver visible labels such as PLACE NOTE, image-here instructions, dummy assets, empty image frames, or generic substitute graphics standing in for an expected place, product, person, character, venue, or event image. Full Validation must block them automatically; Quick Draft relies on authoring discipline and provides no validation assurance. Acquire or generate an appropriate asset, redesign the slide without that visual promise, or disclose the limitation before delivery; never disguise missing work as a finished card.

Runtime And Interaction

• The canonical stage is always 1280×720. Scale it uniformly from window.visualViewport.width/height, falling back to document.documentElement.clientWidth/clientHeight. Include visualViewport.offsetLeft/offsetTop when centering, and anchor navigation, progress, and edge-click regions to that same visible area so 150% browser zoom cannot move controls off-screen. Never reshape the composition to match arbitrary browser aspect ratios.
• Do not calculate fit from window.innerWidth or window.innerHeight alone. Do not place meaningful content outside the 1280×720 safe canvas.
• Preserve keyboard navigation, edge clicks, hashes, Home/End, Page Up/Down, direct numeric page input, fullscreen, and print behavior.
• Keep the navigation order: previous icon, integrated current/total counter, next icon, fullscreen icon. Do not add the slide title to the panel. Theme only the navigation tokens unless the user requests a different interaction model.
• Keep page numerals, separator, icons, and CTA contents geometrically centered with grid/flex and tabular numerals.
• Make anything that looks interactive work with semantic buttons or links, focus states, and accessible names. Avoid redundant in-slide utility navigation when persistent controls already provide it.
• Keep final animation around 300–600ms and respect reduced motion. Validation disables motion only inside Chromium capture.

Content Fit

• Fit content by editing, splitting, simplifying, or changing layout before shrinking type.
• Keep body copy at least 16px and code at least 13px on the logical 1280×720 canvas unless the user explicitly requires denser material.
• Keep UTF-8 throughout. Replacement characters and mojibake are blocking defects.
• No text, logo, key visual, diagram, screenshot, badge, or control may cross the safe canvas or be hidden behind another layer.
• No rendered glyph or text element may leave its nearest painted parent box, even when both remain inside the slide viewport and CSS overflow is visible. Long code, labels, badges, and unbroken identifiers must wrap, shrink within the allowed minimum, or receive more space.
• Treat annotation, caveat, source, footnote, and footer bands as protected layout regions. Mark custom rails with data-protected-region, reserve their row or column in normal flow, and never stagger nearby cards into them with transforms, relative offsets, or negative margins. The text_bounds gate blocks painted cards, panels, tiles, boxes, bands, and transformed structural layers that cross these regions.
• Separate media/content layers that visually form one card must share the same rendered frame. The layer-alignment gate blocks mirrored classes and explicit frame pairs whose edges diverge; supported data-overlap-intent values are reserved for deliberate underlays and bleeds, not geometry fixes.
• No visible placeholder, temporary asset label, empty media promise, or generic fallback graphic may remain. completion is a blocking visual verdict, not a minor quality-score deduction.
• Check rendered geometry rather than trusting CSS intent. Read references/visual-qa.md for the visual inspection checklist.
• Inspect relationships, not only bounds. Media that remains inside the slide still fails when it crosses a divider, label, caption, text region, control, or the intended edge of its card. Also fail subject imagery that is technically contained but visually unusable because intrinsic whitespace makes it tiny or an oversized inset dominates the composition.

Deliverable

Report:

• exact deck HTML, notes, requested study-guide Markdown/HTML/PDF, and sources.json paths;
• slide count and selected validation mode;
• audience/story choice and selected theme;
• controls and typography;
• official, supplied, sourced, and generated asset provenance;
• checks actually performed and any limitation.

For Edit Only, explicitly state that no new deck render or validation was run. Never present old evidence as current. For Quick Draft, state that the deck was created without browser validation rendering, automated validation, AI visual review, or a quality score. If Chromium was used to produce requested guide captures and its PDF, disclose that narrow production use and state that it is not validation. For Full Validation, report reviewer count, review risk, quality score, and unresolved limitations. Do not claim independent review when reviewer records were authored by the same agent without a real separate inspection of the current capture hashes.

References And Tools

• references/validation-contract.md: semantic contract for mode, render, AI review, reviewer count, incremental validation, and finalization. Exact profiles, checks, batch size, and sampling values live in scripts/validation_contract.json.
• references/audience-story-routing.md: audience-aware story order.
• references/theme-taxonomy.md, references/theme-playbook.md, and references/theme-gallery.md: six-axis semantic routing, exact registry theme names, and composition vocabulary.
• references/design-contract.md: selector locking, HTML binding, composition-family declarations, and anti-hybrid validation.
• references/cover-design.md: first-slide planning, art direction, media, typography, and blocking review criteria.
• references/style-presets.md: canonical stage, media safety, navigation, and responsive fit.
• references/quality-bar.md: full-validation scoring rubric.
• references/slide-by-slide-review.md: how to inspect rendered evidence and fill review records.
• references/visual-qa.md: visual defect checklist.
• references/identity-review.md: canonical-reference contract for named character and person imagery.
• references/architecture-diagrams.md: editable technical diagrams.
• references/media-strategy.md: semantic decision rules for real-world, scientific, screenshot, chart, and diagram coverage.
• references/source-locality.md: region-specific factual sourcing.
• references/asset-discovery.md: broad, topic-aware image discovery and original-source tracing.
• references/fan-art-budget.md: bounded fan-art search, provenance, processing, and validation limits.
• references/performance-debugging.md: persistent stage timing, live diagnostics, report reading, and bottleneck interpretation.
• references/research-first.md: semantic research-depth selection, analytical and deep-technical evidence burdens, question-linked storyboarding, and the exactly-once pre-authoring editorial review.
• scripts/validate_all.py: canonical prepare, verify, finalize-prepare, and finalize-verify entrypoint.
• scripts/workflow_timer.py: manual production-stage timer and aggregate timing report.
• scripts/lock_research_storyboard.py: hash-lock the single editorial review and consolidated research/storyboard revision before HTML authoring.
• scripts/validate_deck.py, validate_placeholders.py, validate_speaker_notes.py, validate_image_reuse.py, validate_interactions.py, and validate_browser_e2e.js: deterministic deliverable, completion, and real-browser behavior checks.
• scripts/render_slides.js and validate_visual_review.py: Chromium evidence, true page-scale zoom, and adaptive review validation.
• scripts/render_slide_guide.js: optional study-guide slide capture, readable HTML, and PDF production; never validation evidence.
• scripts/check_environment.py: non-mutating Python, Node.js, Playwright, and Chromium preflight.
• scripts/theme_registry.json: canonical named-theme inventory and selector metadata; gallery headings must match its theme names and order.
• scripts/select_visual_direction.py: registry-driven theme/cover-family diversification from six explicit semantic axes and recent signatures to avoid.
• scripts/validate_design_contract.py: hash-bound enforcement of the locked selector result and deck metadata.
• scripts/install_browser_dependencies.py: explicit-consent, user-scoped Playwright/Chromium installer.
• scripts/measure_container_density.js: rendered warning detector for oversized low-information surfaces.
• scripts/source_cache.py: hash-bound raster provenance cache.