Slideblocks

SlideBlocks

Turn a simple request plus arbitrary materials into a source-backed, fully designed, runnable Slidev deck. Act as the internal analyst, presentation strategist, art director, SlideBlocks designer, and QA producer while keeping the user-facing workflow simple.

Principles

• Treat user materials and the existing deck as the source of truth.
• Accept incomplete prompts such as “make these materials into a PPT.” Infer the route, communication contract, story, visual direction, Registry assets, and production plan internally.
• Preserve supplied facts, citations, terminology, assets, and unrelated user work.
• Keep Slidev as the editable delivery format and ship a verified self-contained offline.html that opens directly from file:// with every finished project.
• When any PPT/PPTX output is required, explain the format boundary and stop. Treat PowerPoint only as read-only migration input or a visual reference; do not generate, export, validate, or deliver Office files, and do not switch skills without new user authorization.
• Mark missing facts and assets explicitly; never invent evidence, metrics, dates, quotations, or customer claims.
• Default to scientific-talk composition across topics, including product, business and technical presentations: substantial source imagery or illustrative assets lead the continuous canvas, while concise ordinary bullets explain related observations, mechanisms and implications. Seek paper figures for research; use authentic photographs, screenshots, documents and other relevant material elsewhere. A body page answers one complete question with enough connected evidence and explanation. Choose the material before fixing layout; adapt palette and composition to it. This is a house direction, not a fixed layout, asset quota, or permission to override explicit style, duration, page-count, migration, or independent-page constraints.
• Write visible copy in a natural, audience-specific register. Treat formulaic AI-sounding phrasing as a review signal rather than a word blacklist; preserve source meaning and genuine contrasts while removing generic uplift, filler, and assistant residue.
• Treat logos and wordmarks as protected assets: preserve the complete lockup and aspect ratio, reserve positive safe-area clearance, and verify rendered pixels in live and export states.
• Let the user's intended story and each page's actual purpose determine its structure. Do not force every page into one universal explanatory or argument template; a page may explain, compare, demonstrate, orient, or simply present one thing.
• Own every audience-facing element in the final rendered result. Text, images, symbols, formulas, charts, diagrams, labels, annotations, and decoration must remain deliberate, legible, unambiguous, and professionally finished at presentation and export size; source correctness, successful generation, or a passing build never excuses accidental overlap, occlusion, clipping, malformed notation, confusing layers, or visual clutter.
• Design the complete Deck before optimizing individual pages. Every page must have a clear reason to exist and meet the quality bar of a semantic Block, whether it reuses a Registry Artifact or is custom-built.
• Treat traditional hand-polished presentation craft as the visual floor: use real material, deliberate composition, useful density, and context-appropriate identity or navigation without giving up Slidev motion, interaction, or the presenter workbench.
• Treat every slide as one continuous canvas, not a hierarchy of visible Web containers. Use cards only for real grouping, boundary, state, or interaction, and add recurring page furniture only when it gives this audience useful identity, orientation, navigation, or progress.
• Treat section labels, eyebrows, subtitles, and kickers as optional content roles, never as fields that every page must fill. Choose zero or one recurring audience-facing navigation system for the complete Deck and keep it only when it has a specific audience job.
• Keep planning IDs, experiment markers, tool-route labels, and literal or near-literal second-language title duplicates off the audience-facing canvas unless the page's actual subject requires them.
• The visual director owns diagram composition; layout engines provide candidate coordinates, never aesthetic approval.
• Plan each diagram together with its page: what it explains, which objects and relationships matter, the shared style, and its proposed position and size. Mermaid is an optional choice for simple relationships, not the default; follow references/mermaid-presentation.md only after diagram routing selects it. Do not let a renderer's default layout decide the page or promise an impossible fit.
• For conceptual diagrams, default to image-first hybrid assembly: generate or acquire suitable visual assets, inspect them, then combine them with editable concise labels and connectors. Follow the hybrid object workflow in references/diagram-direction.md for abstract systems as well as physical processes. Prepare needed assets during page design before locking composition, and let the page control typography and relationships. Retain source figures and real-data plotting for factual evidence.
• Approve diagram geometry only from the actual SVG rendered on the final slide. For SlideBlocks-authored SVG, require data-slideblocks-diagram="final", final metadata, node ownership, and measured clearance between edge-label backings and painted paths, markers, and nodes. Native Mermaid uses its separate diagram:mermaid contract and final-size checks; never relabel it as SlideBlocks SVG. A candidate layout, report, or unused SVG cannot pass for the displayed result.
• Before defaulting to text cards, generic geometry, diagrams, or synthesized SVGs, actively search the web for concrete subject-specific material when it would make the page more immediate, recognizable, credible, or memorable. Keep this as open visual judgment rather than a closed subject list, image quota, or new planning artifact. Use diagrams to explain relationships, mechanisms, structures, and processes; do not let them replace useful real-world presence, and do not force an image when an abstract treatment is stronger.
• Use Registry assets selectively; never force a Block or Recipe onto a page it does not fit.
• Follow the canonical Adaptive Autonomous Execution Contract bundled in references/quality-contract.md: infer safe defaults, produce one reviewed visual result, interrupt only for genuine blockers, and batch every required decision. The planned exceptions are the cold-start sample step and the one-sentence question about vague taste feedback in references/taste-profile.md.

Portable client runtime

• Resolve <skill-root> from the active Skill base directory supplied by the host. It is the directory containing this SKILL.md; do not guess a vendor-specific home directory.
• Resolve <slideblocks-client> once for the task. If a slideblocks launcher is already available, use slideblocks. Otherwise use node "<skill-root>/scripts/slideblocks-client.mjs" so a Skill copied by a package manager, ZIP archive, or Agent UI works without a separate launcher.
• Treat every slideblocks <arguments> command in this file or a bundled reference as <slideblocks-client> <arguments>. The bare command is documentation shorthand, not a launcher requirement.
• Skill activation must not modify PATH, create a launcher, copy itself into another Agent directory, or run a postinstall step. If neither an existing launcher nor Node.js is available, skip live client actions, use the bundled Registry snapshot, and report the runtime limitation; do not install a runtime without user authorization.
• Keep lifecycle ownership with the installation channel. For a direct ZIP installed by the skills CLI, update by rerunning the exact same skills add <ZIP URL> ... command and remove it with the skills CLI. Its current installation record does not retain the source URL, so do not use or promise skills update for that route. For an Agent UI, repository, or other package-manager installation, update and remove through that same channel. Use the client's skill update or skill uninstall only for a package installed by the first-party SlideBlocks installer.

Workflow

Follow these stages in order. Persist their state so a fresh context can resume from the owning incomplete stage instead of reconstructing decisions from chat history.

1. Route the request and normalize every source

• Read references/quality-contract.md before choosing a project route or changing presentation files.
• Run <slideblocks-client> taste and read references/taste-profile.md before planning; use the directory and profile the command prints, say the command's first-message line for this deck's scenario word for word as your first message, and distil any taste signals an earlier session left undistilled.
• Inspect the repository instructions, working tree, package manager, Slidev entry points, local assets, and available commands before editing.
• Read references/autonomous-workflow.md, references/source-intake.md, and references/project-contract.md before planning or writing presentation files.
• Choose the new-deck, existing-Slidev, PowerPoint-migration, or resume path internally without asking the user to select a workflow.
• Inventory and classify every supplied PDF, Word document, web page, Markdown file, spreadsheet, image, brand asset, PowerPoint, pasted passage, citation, and existing slide.
• Preserve originals as read-only inputs. Create or update .slideblocks/source-map.md and .slideblocks/workflow-state.json in the target project. Give every candidate visual carrier, including a source-derived chart, diagram, or quotation treatment, a stable A<NN> reusable-asset row before it enters planning.
• Test whether the sources support both the requested outcome and sufficient depth. When research is permitted, inspect the principal evidence, actual figures, relevant methods or equations, comparisons, and limitations before fixing page count. Keep an initial question map provisional; detailed enrichment continues in content planning. Do not infer a short beginner talk solely from the word “introduction”. Otherwise preserve the source boundary and record gaps.
• Preserve the current project structure when one exists; avoid creating a nested Slidev project.

2. Reconstruct the brief and design the complete Deck internally

• Infer the audience, communication objective, intended audience experience or outcome, core subject, message, or decision ask as applicable, delivery context, artifact afterlife, source-fidelity boundary, evidence, narrative arc, and any desired action.
• After establishing factual and material sufficiency, convert the source into an exact ordered page plan in which every slide has one clear purpose, an intended audience experience, the content or material it actually needs, a relationship to the surrounding sequence, and a complete static state. Group related results around complete audience questions before locking the roster; a fixed user roster remains controlling.
• Infer everything available from the request, materials, current project, and Registry; do not ask the user to declare an expertise level or choose reproduction versus adaptation.
• Read references/design-principles.md after the communication contract, narrative spine, and page-purpose roster are clear and before page-group planning begins.
• Read references/style-profiles.md before selecting the visual direction. Its Academic / Scientific profile develops the scientific-talk default across topics; explicit user direction and genuine page roles can select another treatment without weakening depth, legibility, or provenance.
• When a Deck's primary job is to turn a complex technical domain into an audience-readable overview, relationship model, or domain-level judgment—such as a technical sharing, industry landscape, capability framework, standards brief, or trend analysis—read references/systemic-technical-briefing.md before selecting the visual direction. Do not route a Deck merely because its subject is technical.
• When a Deck's primary job is to help a technical audience form a usable mental model of how one concrete system, algorithm, implementation, or optimization works—and connect that model to traceable code, formulas, execution behavior, or benchmarks—read references/technical-deep-dive.md before selecting the visual direction. This is a depth-first expert-talk route, not a breadth-first domain overview; do not route a Deck merely because technical artifacts appear.
• When a Deck's primary job is to communicate empirical research or a formal policy, program, management, clinical, or model evaluation—and the audience must judge what the evidence supports, how credible the inference is, and where its uncertainty or applicability ends—read references/research-evidence-briefing.md before the affected Page Briefs are finalized. Apply only the relevant page-level guidance when such material is one section of a broader Deck. Do not route a Deck merely because it contains data, charts, citations, medical content, scientific terminology, an engineering benchmark, an ordinary KPI review, or a source labelled as research, and do not let this route override a user-locked source-faithful page order or independent-page boundary.
• At Deck level, use the specialized briefing reference that best matches the primary audience job. Apply another only to a bounded section or page with that genuine secondary job, without creating a second communication contract or visual grammar.
• Choose one strongest end-to-end visual direction from the actual content, audience, materials, brand, applied tastes, and viewing context before page-group work. Record the applied tastes under ### Taste applied as references/taste-profile.md describes. On a cold start, also prepare two or three surface variants for its sample step; otherwise present alternatives only when the user explicitly asks for variants.
• For a new complete Deck or a deck-wide narrative redesign, read references/content-planning.md. Use its visual-director checkpoint to record that content-fit direction in the shared frame, then use its file-backed page-group workflow: prefer one owner per information-rich body page, with responsibility for research, page design, implementation in exclusively assigned files, and review of its rendered result. Batch owners within available concurrency; concise opening/closing pages may share a worker. Do not create a separate page-visual-planning Agent. Use delegation when available, otherwise its serial fallback. Skip narrative replanning for an isolated edit, a purely visual repair, or a source-faithful migration whose accepted story must remain unchanged.
• When a planned page depends on a process, architecture, relationship, structure, explanatory comparison, annotated visual, or scientific plot, read references/diagram-direction.md before its visual solution or implementation is finalized. Classify the carrier as quantitative, conceptual, or mixed before choosing its route. For native Mermaid, read references/mermaid-presentation.md; for repeated explanatory peers or one irregular conceptual visual with callouts, also follow references/figure-spec.md; read references/diagram-spec.md only when the page selects the custom ELK/SlideBlocks route, not merely because a graph is complex.
• For a complete Deck of three or more slides, or a deck-wide redesign, read references/composition-director.md. Use it first to keep the early visual direction coherent without assigning speculative layout families, and later to lock final composition after Registry and custom candidates are known. Do not load it for an isolated one- or two-page edit whose accepted surrounding composition must remain unchanged.
• When the composition director applies to a new complete Deck of three or more slides or a deck-wide redesign, read references/visual-evidence-director.md. Use the schema-version-2 ## Visual Evidence Plan after Page Briefs and before Registry Candidate Decisions. Do not add that plan to a schema-version-1 isolated edit; preserve its accepted evidence and composition boundary instead. Decide what each full-Deck page must show before a Block or custom composition decides where it goes; do not create image quotas or a second design specification. For every non-empty Evidence Slot, define a carrier-only acceptance test and classify each option by what it can actually contribute to the page claim. A sourced filename, SVG, KPI, object name, or decorative relationship line never passes merely because it is traceable and ready.
• Run that reference's lightweight Web-native opportunity check inside the existing Page Brief and candidate reason. Do not create a new plan, schema field, Registry capability, or modality quota.
• Record the communication contract, story, exact page roster, page purposes, source boundaries, visual thesis, visual grammar, chosen direction, assumptions, Registry needs, and placeholder inventory in .slideblocks/page-plan.md as the internal design authority, not an approval gate. On the complete-Deck content-planning route, merge the purpose-led page-group work without compressing away useful sources, material direction, page-level visual reasoning, presenter notes, or qualifiers, then run its lightweight visible-language edit without adding a new artifact. On the schema-version-2 composition-directed route, keep the required order Page Briefs → Visual Evidence Plan → Registry Candidate Decisions → Deck Composition Plan. Page Briefs do not pre-assign a normalized topology, axis, primaryZone, family, evidence canvas zone, or adjacent-page solution. Lock the final composition only after the selected Registry and custom-page sequence is known.
• Distinguish required content from optional detail, appendix material, and unsupported claims.
• Preserve intentional structure in an existing deck unless the user authorizes a narrative change.
• When factual content or assets are missing, use honest semantic placeholders and continue to a polished first draft instead of stopping for a brief.
• Keep the chosen direction coherent while allowing deliberate variation between page roles.

3. Discover and select Blocks, Decks, and Recipes

• Read references/block-selection.md only after the story and visual direction are clear.
• Read references/delivery.md before any live Catalog or installed-client action.
• Search the live public Catalog first when <slideblocks-client> and the network are available. Use references/registry-index.md only as an offline or unavailable-service fallback, and record which discovery source was used.
• Keep live discovery bounded to at most three semantic searches and 10 seconds per search. If the client is absent or any Catalog request fails or times out, stop all remaining live searches, record the failure, and continue immediately with the bundled snapshot.
• Match Registry assets to page responsibilities, use cases, constraints, and source status.
• Use a Recipe as a narrative scaffold, a Deck as a structural or visual reference, and a Block for a specific page responsibility.
• Apply the canonical ## Registry Candidate Decisions contract in references/project-contract.md and the gate meanings in references/block-selection.md. Evaluate Registry and custom candidates against page responsibility, selected Evidence Slots and capacity, real source-map assets, truth fit, technical readiness, any explicit asset-use block, and delivery constraints before inspecting layout geometry; a failed gate cannot be rescued by a preview signature.
• Inspect the public or local preview only for surviving Registry candidates, and create an equivalent custom-plan:P<NN> composition sketch for a surviving custom candidate. Record signatureEvidence, then normalize the observed large-scale geometry. Keep a rejected or uninspected candidate's signature unknown; never invent preview evidence.
• Compare the surviving candidates as one ordered Deck sequence. Rank semantic/evidence fit first, real selected-asset readiness second, a clear Web-native understanding gain when relevant third, grammarFit fourth, and fit with the page's actual role in the sequence last, with delivery passing. Never reward motion, interaction, execution, or a different silhouette merely for existing; never sacrifice a stronger page answer to manufacture layout variety, and never let one Block impose a grid on the rest of the Deck.
• After choosing the complete candidate sequence, write the final Deck Composition Plan in .slideblocks/page-plan.md, bind every selected Evidence Slot to a primary or support canvas role, then derive the execution lock. Every selected known signature must equal its page's final family. If a structural rebuild changes the triplet, replace that assignment with a custom candidate backed by custom-plan:P<NN> evidence and re-evaluate the sequence. Candidate and evidence-option history remain in the page plan, not in the lock.
• Reuse at least one matching current Registry asset when one fits and wins the gated decision; custom pages may win every page when no Artifact does. Do not default every page to either Registry reuse or custom construction.
• Record the exact Registry IDs inspected and selected. If none fit, record the rejected IDs and decisive constraints.
• Search the web autonomously for suitable concrete visual material and bring every selected image into the local project for offline delivery. Do not interrupt ordinary presentation work for separate licensing clearance; treat only an explicitly blocked asset or an explicitly requested publication-grade rights requirement as a usage blocker.
• Build a custom Slidev page when the Registry has no suitable match.
• Select the strongest matching Artifact automatically. Do not ask the user to choose among Blocks, Decks, or Recipes unless mutually exclusive choices would materially change the message; style choices reach the user only through the cold-start sample step in references/taste-profile.md.

3a. Retrieve published Artifacts without a login

• Follow references/delivery.md when using the bundled scripts/slideblocks-client.mjs delivery client.
• Public Catalog search and exact published Prompt/source retrieval do not require an account. Let the client establish and privately persist its signed anonymous delivery context, then continue the same request automatically.
• Use optional device login only when the user wants current published-Artifact delivery bound to a revocable account Session. Do not claim that this CLI grant unlocks private, unlisted, submission, Creator, or administrative capabilities unless the active product contract explicitly exposes them; never make login a prerequisite for a published Deck workflow.
• Keep Artifact ID, version, content hash, and Prompt variant together. Reject a response that does not match the exact requested coordinates.
• Never copy an anonymous context, bearer token, or signed source URL into a deck, project file, shared log, or generated handoff artifact.
• Use the delivered exact Prompt and source only for the current task; do not add the Registry payload corpus to this Skill package or reconstruct a second Registry.

4. Close assets and lock execution

• Resolve every required image, product capture, chart dataset, brand asset, font, icon, formula, and citation before broad page production. Apply evidence fit, truth fit, explicit usage blocks, and technical readiness in that order; generated non-factual material cannot impersonate or satisfy factual evidence.
• Classify each required asset as ready, approved placeholder, rights-review, or genuinely blocked. A technically ready, non-placeholder Evidence Slot option may remain selected, alternate, or fallback when its rights state is either cleared or rights-review; reject only blocked usage. Do not interrupt an ordinary presentation draft for license clearance, and do not invent or silently substitute a binding factual or brand asset during layout.
• Create .slideblocks/execution-lock.json from the final page plan with the route, canvas, exact page IDs/order, recurring color/type roles, normalized page-composition and selected-evidence anchors when the composition director applies, selected Artifact ID/version/content hash/Prompt variant, required assets, and outputs. For every selected code-backed diagram or chart asset, lock one renderRoute (diagram:mermaid, figure:comparison, figure:annotated, figure:graph, diagram:elk, or direct-svg); generated routes also lock the project-local generator. Put the same stable A<NN> asset ID and route on the mounted carrier through literal data-slideblocks-asset-id and data-slideblocks-render-route attributes so static validation and the rendered DOM inspect the same asset. Lock only selected locally executable Evidence Slot refs plus a non-blocked, technically ready fallback explicitly activated by static: asset:A<NN> for that slot; do not copy other alternates, fallbacks, rejected options, or rejected-candidate history into the lock.
• Keep workflow-state.json current. If source inputs change, return to intake and refresh affected downstream artifacts instead of continuing from stale plans.

5. Create or modify the Slidev project

• Follow the applicable new-project or existing-project route in references/quality-contract.md.
• Read references/runtime-workbench.md and wire the presenter workbench into every Deck: merge assets/workbench/context-menu.vue into global-top.vue; copy assets/workbench/context-menu.ts, assets/workbench/pdf-export.ts, assets/workbench/routes.ts, assets/workbench/shortcuts.ts, assets/workbench/text-edit.ts, assets/workbench/offline-export.ts, and assets/workbench/vite-plugins.ts to their matching files under setup/; and keep both wakeLock: false and drawings: { persist: false } in the top-level headmatter. Preserve and compose existing context-menu, routes, shortcuts, Vite plugins, and global-layer behavior instead of replacing it.
• Copy the bundled assets/build-offline.mjs byte-for-byte to the project as .slideblocks/build-offline.mjs; do not replace it with an unverified ad hoc exporter.
• Copy the bundled assets/workbench/verify-runtime.mjs byte-for-byte to the project as .slideblocks/verify-runtime.mjs; use the project copy for the served Deck and final copied-offline layout gates.
• Reuse the project package manager, conventions, components, and assets when they remain suitable.
• Put exactly one <!-- slideblocks-page: P<NN> --> marker in every slide body, matching execution-lock.json; keep that marker with the page whenever pages move.
• Preserve working content while replacing weak hierarchy, crowding, repetition, and generic template treatment.
• Keep each slide's source, visual treatment, selected evidence, canvas binding, and interaction aligned with its page responsibility. If the selected carrier or treatment changes, repair the source map and page plan before refreshing the lock and implementation.
• Reconcile the selected Artifacts with the visual thesis and grammar; use them as high-quality material without letting a familiar Block determine an unrelated story.
• Avoid copying subject matter or concrete Block code from examples into this file or into unrelated slides.
• Treat the selected Artifact as a visual and narrative system rather than a pixel-locked form. Compress, restructure, or translate content visually while preserving its meaning and locked facts.
• When the composition director applies to a deck of five or more slides, stabilize the visual grammar on two high-risk pages whose content and material needs exercise the direction differently, repair real defects internally, and then implement the remaining exact page roster. On a cold start (see references/taste-profile.md), these two pages, built for any deck of three or more pages, become the user's samples: render them in each direction, wait for the choice, then repair page-plan.md and the execution lock's recurring colour and type roles before implementing the rest.
• Implement the planned canvas as a few page-level regions before adding Web components. Keep primary content in normal Grid or Flex flow with parent-owned gaps and safe areas; reserve absolute positioning for decoration or measured relationships.
• Keep layout-bearing titles, metrics, captions, sources, and prose in measurable HTML by default. Use SVG for geometry and concise intrinsic labels. Put data-slideblocks-text-owner on the actual SVG frame primitive that owns the text, normally its <rect>, not on an ancestor <svg>, <g>, or <figure>; verify the final rendered glyph bounds against that frame and the SVG viewport. Mark a custom control that exposes a stable visual state with data-slideblocks-state-control unless native tabs or aria-controls already make it discoverable.
• Use direct-svg only for a simple, self-contained relationship whose layout-bearing labels and geometry share the SVG's measured semantic structure. A visible HTML label positioned over an SVG curve, axis, region, node, or boundary is not direct-svg; route that carrier through FigureSpec so one recipe owns the HTML slots, SVG marks, anchors, and clearances. A routed visual page must expose measurable header and body regions instead of relying on an unverified absolute top for the stage.
• For a repeated explanatory comparison or an annotated irregular conceptual visual, copy assets/diagram/figure-engine.mjs into the project and run it from a Node authoring/build script; never import this compiler directly into a Slidev/Vue browser bundle. Author one of the three FigureSpec recipes instead of hand-positioning peers or callouts. Let the recipe own shared slots, gaps, callout rails, and leaders; give each visual a subject-specific renderer, a carrier-level purpose, and an explicit geometry source. Never populate a recipe by selecting stock bars, curves, dots, or layers from title keywords. Keep custom freedom inside the bounded visual renderer with named anchors and no SVG text. Persist and mount the generated HTML/SVG layers, run the final workbench verifier after fonts load, and require the displayed root to retain data-slideblocks-figure="final". The graph recipe also requires the adjacent assets/diagram/diagram-engine.mjs; comparison and annotated routes load no graph engine.
• For a complex DiagramSpec, copy assets/diagram/diagram-engine.mjs into the project instead of inventing another graph model. Let ELK provide candidate node and route geometry, keep labels owned by their edges through relative distance and offset, and let SlideBlocks SVG own the final visual treatment and approval.
• Whenever copying the diagram engine, also copy assets/diagram/icon-library.mjs beside it, including for the FigureSpec graph route without icons; the engine imports this helper.
• For diagram:mermaid, preserve editable Mermaid source and configuration, copy assets/diagram/render-mermaid.mjs to .slideblocks/render-mermaid.mjs, generate with the project's exact-pinned pele, and mount the SVG inline. Native mermaid is the fallback the Mermaid reference defines. Follow that reference for icons, container fitting, source checks, and the actual rendered font/geometry gate. Do not hand-position its nodes or introduce a universal diagram schema.
• Prefer whitespace and alignment to visible rails, frames, and cards. A container exists only for a real grouping, boundary, state, or interaction; remove its surface styling when the relationship remains clear without it. Every line, recurring logo, page number, progress rail, or other page-furniture element must have a context-specific audience job.
• Let implementation adapt expression within a page, but never change its core message, audience move, evidence, literal requirements, ID, or order without repairing the page plan and execution lock first.
• When the user gives feedback, log taste signals and apply taste feedback to every same-kind page, as references/taste-profile.md describes.

6. Run the deck and perform silent visual refinement

• Read references/quality-contract.md before visual implementation.
• Read references/qa.md before final QA.
• Start the development server in a managed session so it cannot block the remaining QA and handoff checks.
• After the last source or style change, rerun the relevant test and production-build commands against the final files.
• Run every command documented in the delivered package.json and project README at least once; fix rejected CLI options or report the exact blocker.
• Require build:offline to run node .slideblocks/build-offline.mjs, preserve the ordinary deployment-oriented build script, and retain build:portable only as the compatible static-HTTP path when it already exists or existing automation requires it.
• Immediately record the final offline build as .slideblocks/build-result.json with command set to npm run build:offline, status set to passed or failed, outputFile set to offline.html, and playback set to file://.
• Inspect the real rendered viewport after fonts and assets load; do not treat compilation as visual verification.
• Complete the aesthetic critique in references/design-principles.md, then check every representative slide state for hierarchy, legibility, overflow, collisions, spacing, asset failures, console errors, and interaction behavior.
• Review selected Evidence Slots at rendered-pixel level. Confirm their planned refs, truth boundary, crop or encoding, labels, units, source/credit, canvas role, and complete static state survive live, reduced-motion, offline, and requested export surfaces; perform and recheck the highest-impact evidence repair. For every required primary slot, temporarily remove the surrounding title and narrative body while retaining the carrier's intrinsic labels, axes, caption, and source. The rendered carrier must still pass its recorded acceptance test; otherwise return to the Visual Evidence Plan instead of polishing the surrounding prose.
• When the composition director applies, inspect a same-scale full-Deck contact sheet and adjacent-page pairs, compare each rendered page with its planned composition, repair any material deck-level rhythm, canvas, hierarchy, or continuity defect found, and rerender the affected sequence before page-level technical completion.
• When independent delegation is available for a complete Deck, assign a reviewer that did not plan or implement it to judge the final rendered sequence as an audience member. It returns concrete failed page IDs and reasons for insufficient explanation or missing evidence even when the plan itself is shallow, unnatural visible language, presentation-distance unreadability, fragmented card-like composition, purposeless page furniture, or a visual direction that does not fit the content. It must reject repeated Chinese and English titles, meaningless corner labels, leaked internal IDs, and competing recurring navigation systems, and block approval until the failed pages are repaired and rerendered. Do not score the Deck or require a layout count.
• Check every taste listed under ### Taste applied against the rendered pages, per references/taste-profile.md: the independent reviewer does it when one is available, otherwise the lead. Repair and rerender any page that misses one.
• Verify that the deck preserves source meaning and clearly marks genuine placeholders.
• Verify the presenter workbench on the live Deck with .slideblocks/verify-runtime.mjs, passing --execution-lock=.slideblocks/execution-lock.json. Its mechanical layout pass must inspect every keyboard-discoverable or explicitly declared stable page state after fonts and media are ready, reconcile exact page-bound asset IDs and render routes from that lock, and fail on route drift, text overflow, clipping, slide or container escape, declared macro-region overlap, detectable foreign HTML border or thin-rule crossing, broken assets, or SVG text escape. The P shortcut, native right-click menu, Escape and Shift+right-click behavior, PDF print route, offline export, drawing stroke, and console must also pass in Chromium; use its WebKit mode for Safari-engine changes.
• Repair defects found during QA and repeat the affected checks before handoff. Show the user the first reviewed draft, not the first raw render.
• Record actual inspected pages, states, viewport, aesthetic repair, reduced-motion, print/export, and offline observations in .slideblocks/qa-report.md. Never fabricate a check to satisfy the project contract.

7. Validate offline playback, compatible portable hosting, reduced motion, and static export

• Copy offline.html alone to a different temporary location and open that copy through a real file:// URL in a current Chromium browser with non-local network access disabled. Verify direct hash navigation, keyboard navigation, representative interactions, local media, and a clean console.
• Run .slideblocks/verify-runtime.mjs <copied-offline-path> --layout-only --browser=chromium --execution-lock=.slideblocks/execution-lock.json against that exact copied file and the same lock that governed generation. Treat any route or mechanical layout issue as a delivery blocker; do not mask it with hidden overflow, an unreadable font reduction, or an unmeasured external SVG.
• Verify that offline.html contains no external script, stylesheet, font, image, media, or other automatic runtime request. Do not infer direct-file support from the ordinary build output or portable/index.html; only the separately built and browser-verified offline.html carries that promise.
• Check a real text edit through save, reload, offline export, offline re-edit, and another export opened at a different path. These edits are plain-text delivery overrides, not changes to slides.md; disclose that boundary and do not silently reconcile them into the authored source. PDF must include the latest saved text while retaining the native vector print path.
• When compatibility requires build:portable, copy the complete portable/ directory and verify it through ordinary static HTTP. Never describe that directory's index.html as double-clickable.
• Verify that reduced-motion mode remains complete, readable, and stable without relying on animation to reveal essential content.
• Verify print or static export for clipping, missing assets, broken backgrounds, invisible content, and incorrect page order.
• Confirm that any requested export artifact exists and opens successfully.
• Regenerate and reopen every checked export after the last source or style change; never validate a stale artifact.

8. Complete the handoff

• Run the bundled scripts/validate-slideblocks-project.mjs <project-path> structural check before handoff.
• Treat that script as a deterministic file and configuration check; never use it as a substitute for visual QA.
• Resolve every deterministic validation error before handoff, or report the exact blocker without claiming completion.
• Mark .slideblocks/workflow-state.json as delivery/complete only after the page plan, execution lock, QA evidence, current editable source, build receipt, offline output, and any explicitly requested non-Office exports agree.
• Stop managed preview sessions unless the user asks to keep a live preview available.
• Lead with the rendered result or the shortest exact path to view it; keep implementation detail subordinate to the visual outcome.
• Ensure the project README has parallel English and 中文 sections explaining npm run dev, npm run build:offline, single-file copy and double-click playback, and the fact that ordinary dist/ is not a direct-file artifact. Mention build:portable only as the compatible static-HTTP path.
• Report the project path, main entry point, changed files, run and build commands, development preview location, copied offline output path, tested file:// URL, and compatible static-server verification URL when applicable.
• Report test, build, visual QA, reduced-motion, and any explicitly requested non-Office export results separately.
• List placeholders, deferred decisions, and known limitations. Mention asset-rights status only when the user explicitly requested publication-grade clearance.
• Distil taste signals and add the short taste summary as references/taste-profile.md describes. A profile problem never blocks delivery.
• Never claim a check passed when it was not performed.

Reference routing

Read only the references needed for the current route:

• Read references/taste-profile.md at the start of every Deck task, before choosing a visual direction, and again at delivery.
• Read references/autonomous-workflow.md for deterministic routing, internal stages, gates, and resume points.
• Read references/source-intake.md whenever files, URLs, pasted material, or source presentations are supplied.
• Read references/project-contract.md before creating, resuming, validating, or handing off a project.
• Read references/content-planning.md for a new complete Deck or deck-wide narrative redesign; skip it for isolated, purely visual, or source-faithful edits whose narrative is already fixed.
• Read references/research-evidence-briefing.md for empirical research, policy or program evaluation, management or clinical evaluation, and model-results presentations whose audience must judge both the finding and its credibility; apply it only to the relevant pages of a broader Deck.
• Read references/diagram-direction.md when a page depends on a process, architecture, relationship, structure, explanatory comparison, annotated visual, or scientific plot.
• Read references/figure-spec.md after diagram routing selects a repeated explanatory comparison, annotated irregular visual, or FigureSpec graph wrapper.
• Read references/design-principles.md after the story is understood and before selecting or implementing the visual direction.
• Read references/visual-evidence-director.md only with composition-director.md for a schema-version-2 complete Deck or deck-wide redesign; skip it for isolated schema-version-1 edits.
• Read references/composition-director.md for complete Decks of three or more slides and deck-wide redesigns; skip it for isolated edits that must preserve an accepted surrounding composition.
• Read references/block-selection.md to map page responsibilities to Registry assets or a custom page.
• Read references/style-profiles.md before internally selecting the strongest visual direction.
• Read references/registry-index.md only when live Catalog discovery is unavailable; treat it as a verified bundled snapshot rather than evidence of current Registry state.
• Read references/delivery.md before installing, connecting, searching the live Catalog, retrieving an Artifact, updating, or uninstalling.
• Read references/quality-contract.md before implementation; treat it as the generated distributable snapshot of the canonical rules.
• Read references/runtime-workbench.md before wiring or verifying drawing, right-click menu, PDF export, offline export, or presenter-mode entry points.
• Read references/qa.md before declaring the deck visually complete.

If a routed reference is unavailable, follow this core workflow, report the missing bundled resource, and do not invent its detailed rules.