mdpr-skill

# mdpr-skill ## Purpose Use this skill as the optional Codex companion for MDPR. MDPR remains the deterministic presentation runtime; this skill provides semantic hints, review findings, and rule/config improvement guidance around MDPR outputs and intermediate representations. ## Core Boundary - When the local CLI is available, start by reading branch-local guidance with `node bin/mdpr-skill.js docs bootstrap --dense` and then the narrow topic for the task, such as `docs boundaries --dense`, `docs template-fill --dense`, `docs media --dense`, `docs preflight --dense`, or `docs review --dense`. This mirrors the agent-ready CLI-docs pattern used by Astryx while keeping MDPR-specific runtime ownership intact. - Let MDPR own parsing, slide splitting, recipes, layout, coordinates, geometry, typography, colors, z-order, arrows, effects, exact icon assets, renderer object IDs, and final PPTX objects. - Keep agent output weak, semantic, evidence-based, and schema-valid. - Express fixes as Markdown cleanup, MDPR rulebook changes, config changes, deterministic policy changes, or approval-bound proposals. - Preserve the ability to build the same deck with all agent hints disabled. - Do not mutate source Markdown unless the user explicitly asks for a cleaned source draft. - Treat media policy as a hard handoff boundary: `imageUse: "no-image"` means no generated-image candidates, and `iconUse: "no-new-icons"` means no icon keyword candidates. If conflicting candidates appear, emit preflight warnings and rely on MDPR runtime diagnostics as the authoritative accept/ignore result. - Treat all runtime-owned fields as forbidden in hints and review artifacts: coordinates, geometry, crop/cropRect, raw colors, typography, z-order, exact icons, final image paths, renderer objects, recipe/variant/layout IDs, and copied PowerPoint object IDs. ## MDPR Runtime Sync Boundary Use the local MDPR checkout as the source of truth when this skill is being updated for a revised MDPR runtime. - Treat MDPR schemas as mirrored contracts, not skill-owned inventions. Before claiming compatibility with a revised MDPR checkout, run the schema-sync gate against the target MDPR path. - Record the MDPR checkout path, commit hash or version, schema-sync command, and validation timestamp in review notes or artifacts before claiming compatibility with a revised MDPR runtime. Do not treat `.cache/mdpr` or any specific commit as a permanent assumption. - Treat MDPR's `validation.polish` manifest field as the deterministic post-AI PPT polish gate. LLM notes may explain or triage polish concerns, but MDPR owns the pass/fail result for font hierarchy, layout composition, highlight pages, cover treatment, detail QA, and theme-gallery evidence. - Treat MDPR's `job-state validate/status` and `generated-assets validate` commands as runtime mirror checks for the same contracts that `mdpr-skill` can create or inspect. - Keep `mdpr-skill` changes compatible with MDPR's no-agent runtime: all generated hints, edit intents, change requests, and review artifacts must be optional inputs or review evidence. Useful local commands: ```bash git -C <mdpr-path> rev-parse HEAD node bin/mdpr-skill.js gate validate-schema-sync --mdpr-path <mdpr-path> node <mdpr-path>/packages/cli/dist/index.js job-state validate <job-state.json> --json node <mdpr-path>/packages/cli/dist/index.js generated-assets validate <generated-assets.json> --json ``` Substitute the actual MDPR checkout and artifact paths, and verify referenced files exist before treating results as compatibility evidence. ## LLM-Assisted PPTX Review Boundary Use LLM judgment only for semantic, narrative, evidence, and review-note assistance. It must not override MDPR validation or replace deterministic overflow, text clipping, overline, coherence, spacing, type, radius, shadow, raw-hex, editability, or renderer gates. When an LLM review mentions these issues, ground the note in an MDPR report finding, rendered evidence path, manifest field, or explicit source excerpt. Treat the LLM note as triage or explanation only; MDPR validation remains the source of truth for pass/fail status and release gating. When reviewing revised-MDPR outputs, explicitly check whether the build manifest records `validation.polish`. Missing, stale, and failing status must come from MDPR build/validate output, MDPR manifest metadata, or MDPR-reported source hash/build metadata, not from LLM judgment. If `validation.polish` is missing, stale, or failing according to those MDPR-owned signals, recommend an MDPR runtime or validation-policy fix rather than presenting the LLM review as a release gate substitute. The `review` command mirrors a positive `validation.polish.requiredFailureCount` as an error finding with type `MDPR_POLISH_GATE_FAILED`, the failed required chapter names, and `runtimeOwner: MDPR`. Do not emit that finding when the required failure count is zero. Example MDPR-owned check after the runtime has built or validated a deck: ```bash node <mdpr-path>/packages/cli/dist/index.js validate <deck.md> --visual --coherence --json ``` ## Main Workflows ### Semantic Hints Use when a deck, Slide Element IR, Presentation IR, or ambiguous Markdown would benefit from compact semantic guidance. - Suggest intent, grouping, importance, evidence-bound icon-search keywords as structured icon keyword candidates, key-message priority, content split, readability, template-use, and media-policy semantics. - When a user provides or references an existing PPTX/POTX/theme and does not explicitly ask for a new visual system, default to `template-fill`: preserve master slides, placeholders, and the existing theme frame. Do not add new cards, surfaces, icons, images, or style systems in this mode. - In `template-fill`, treat the supplied PPTX/POTX slide master as the primary visual system. Do not pass `--theme-style`, `--theme-color`, `--theme-harmony`, `--theme-gallery`, `--design`, theme packs, or source-neutral DESIGN imports unless the user explicitly asks to transform the visual system. For the current `mdpresent` CLI, the safe default is `mdpresent build deck.md --to pptx --out dist --template master.pptx` plus validation; adding MDPR theme flags is a duplicate-theme risk. - In `template-fill`, do not synthesize slide-bottom "key message", "caution", "takeaway", or similar callout bands unless the source deck or template has an explicit placeholder for them. Keep safety notes as normal body content, presenter notes, or review notes instead of adding a new visual layer. - In `template-fill`, do not override template typography or text colors. Avoid explicit font-family, font-color, raw RGB/hex, decorative fills, or custom line colors in agent-created PowerPoint bridge output; use the existing placeholder defaults, slide master, and PowerPoint theme bindings. - If `template-fill` or explicit media policy sets `imageUse: "no-image"` or `iconUse: "no-new-icons"`, remove conflicting generated-image or icon keyword candidates before handoff; keep only a preflight warning if the conflict is useful review evidence. - Suggest generated-image candidates only when the source contains image evidence or the user explicitly requests a generated asset. A large or ambiguous icon is not enough by itself. Positive permission requires generated-asset workflow intent, `imageSearch: "explicit-request-only"`, and request/instruction evidence bound to the candidate. - Default image search to disabled. Use source-image-only guidance when source images exist, and explicit-request-only guidance when the user asks for image generation or search. - Default icon use to no-new-icons in template-fill workflows. Icon keyword candidates are allowed only as semantic search terms when the workflow permits icons, and each candidate must carry element/source evidence rather than an exact icon name, file path, placement, or style. - For dense or wordy content, prefer semantic `contentSplitCandidates` and `readabilityCandidates` before visual decoration. - In review and comparison evidence, do not synthesize a one-line subtitle that repeats the title, an automatic title underline, an isolated bottom rule, or a takeaway band unless the source or template assigns it a real content role. Keep structural card borders and data separators only when they clarify an actual group or comparison. - Judge lines by semantic role and repetition, not by presence alone. Do not flag a card border or data separator that carries grouping meaning. Flag a continuous rail that duplicates per-item accents, an unassigned title/bottom rule, or deck-wide separator repetition only with rendered before/after evidence showing that removal improves hierarchy without losing grouping. - Revalidate the rendered PPTX visually instead of inferring quality from the source or manifest alone. Inspect every exported slide for clipping, sparse continuation pages, repeated numbering, misleading decoration, and stale or partial export frames; record remaining weaknesses instead of styling them away in the evidence deck. - For sparse continuation pages, distinguish wrong topology from disproportionate region height. Verify the current rendered topology first; when a short source-backed row already exists, recommend content-measured runtime sizing rather than another layout, extra copy, or decoration. MDPR owns the sizing rule, while mdpr-skill records before/after evidence and source preservation. - Preserve heading and list ancestry in comparison corpora and review evidence. Promote content to paired columns or a native table only when two source groups are explicit siblings under comparison-bearing ancestry such as current/improved or before/after. A flat peer list is not enough evidence for A/B accents. Keep a negative control so hierarchy detection cannot turn two unrelated sections into a semantic comparison. - Verify the semantic block and selected preset before writing a sparse-page regression. Pipeline diagram nodes are not list items: when their rendered cards are oversized, test the `diagram` block and `pipeline` region, preserve node/edge mappings, and re-export PowerPoint. Reject a passing unit fixture if the current rendered slide does not change; that is a validator false positive. - Treat `16pt` as the current MDPR generated-text visual floor, including list and diagram number badges. Apply it to text-bearing regions, including code, captions, tables, charts, and diagrams; image-only and empty decorative regions do not emit glyphs and must not create a font-floor finding. Verify the runtime manifest and actual PPTX runs; do not assume code or caption needs a smaller exception, and do not prescribe an exact replacement size from the skill side. - When MDPR exposes `validation.fontEnvironment`, distinguish a proven missing family from `FONT_ENVIRONMENT_UNAVAILABLE`, and cite the recorded probe source. A passing host catalog check is evidence for that export host only. When `embedding.performed` is false, do not claim portability. When it is true, require MDPR-owned EOT part paths, source hashes, `fsType`, and complete family/style coverage before describing the PPTX as portable. Treat the font EULA as an external responsibility even when `fsType` permits embedding. When MDPR exposes `embedding.licenseEvidence`, distinguish exact post-render SHA-256 binding from legal sufficiency: require `complete: true` before describing a distribution workflow as evidence-complete, and preserve `legalDetermination: external`. Do not create license evidence, do not reinterpret its license terms, select font files, embed them from the skill, or duplicate MDPR's `--require-font-installed`, `--require-font-embedded`, `--font-license-evidence`, or `--require-font-license-evidence` pass/fail decisions. - For Korean decks and mixed Korean/English decks, prevent awkward wrapping as source cleanup: shorten claim titles, replace long inline tool names with a shorter label plus detail in notes, split long bullets into label/detail pairs, and move secondary evidence to speaker notes or a follow-up slide. Do not prescribe exact manual line breaks, font sizes, or coordinates; MDPR owns final typography and wrapping. - Treat paragraph marker handling as MDPR-owned runtime behavior. Current MDPR normalizes dash and bullet-like lines such as `-item`, `•`, `·`, `–`, `—`, `−`, `ㆍ`, and `▪` into stable list structure while preserving `---` slide breaks, pipeline arrows, negative-number prose, year-leading prose such as `2026. Roadmap`, fenced code, indented code, and raw `<pre>` blocks. Real ordered lists keep source numbering through MDPR splitting. mdpr-skill may suggest source cleanup or readability notes around these markers, and may consume MDPR source-cleanup diagnostics when available, but must not encode marker-specific layout or rendering decisions. - Keep hints compatible with `agent-hint.json`-style weak semantic input. - Validate that hints do not encode final rendering choices. - Prefer minimal hints over broad restatement of the source. - Run a preflight mindset inspired by reference skills such as `taste-skill`: one primary key message per slide by default, no broad restatement of every source block, no contradictory template-fill media/icon candidates, and no decorative hints that MDPR can already derive deterministically. For recursive Pro/RDD loops, reject duplicate or vague TODO proposals before import unless they name concrete files, acceptance checks, validation, and new evidence. - Ground primary key-message candidates with `evidenceRefs` or `claimRef` when available. Treat ungrounded primary emphasis as a preflight warning, not as a final slide design instruction. - Require explicit user/request/approval evidence before using `style-transform`. Existing PPTX/POTX/theme workflows stay `template-fill` unless the user asks to change the visual system. Useful local commands when the repo CLI is available: ```bash node bin/mdpr-skill.js hint --source-sha256 <64hex> --out .mdpresent/proposals/agent-hint.json node bin/mdpr-skill.js hint --selection-context .mdpresent/ppt/selection-context.json --markdown deck.md --out .mdpresent/proposals/agent-hint.json ``` ### Review Reports Use when reviewing generated MDPR artifacts, manifests, preview images, review reports, or handoff artifacts. - Report visual concerns with evidence paths. - Flag template-fill risks such as master-theme evidence missing, placeholder preservation evidence missing, slide-scoped placeholder mismatches, rasterized template-fill output, images without source/request, generated assets whose provenance is not bound to the asset or slide, undeclared image search, new icon substitution, dense content, overly long copy, duplicate theme application from MDPR theme flags, and awkward Korean/English wrapping visible in rendered previews. - Distinguish source Markdown problems from MDPR runtime/rulebook problems. - Turn repeated visual issues into deterministic MDPR rule or config recommendations. - Keep the output actionable for MDPR maintainers. - Reference MDPR manifest `validation.polish` when discussing post-AI PPT polish quality, and keep that manifest field as the release gate. Useful local command: ```bash node bin/mdpr-skill.js review --manifest dist/mdpresent-manifest.json --out .mdpresent/review/review-report.json ``` ### Narrative Spine Review Use when source Markdown needs content-level review before MDPR renders or rebuilds a deck. - Read Markdown, optional MDPR manifest summaries, and optional source notes. - Emit claim-title and section-flow suggestions only. - Include provenance such as source path, manifest slide count, heading text, or source-note excerpt. - Do not emit layout IDs, placeholder IDs, coordinates, colors, typography, renderer object IDs, or pass/fail validation decisions. Useful local command: ```bash node bin/mdpr-skill.js narrative --markdown deck.md --manifest dist/mdpresent-manifest.json --source-notes notes.md --out .mdpresent/review/narrative-review.json ``` ### Template Layout Intent Review Use when a PPTX template has been summarized as a layout catalog and the deck needs semantic layout-intent hints before MDPR chooses any actual layout. - Read layout names and placeholder roles from a layout catalog or template summary. - Emit semantic intents such as comparison, chart-focus, evidence, or section-divider. - Treat existing PowerPoint master slides as the theme source when the workflow is `template-fill`. Ask for preservation evidence; do not transform the master, copy exact placeholder IDs, or choose final layouts. - Include provenance through the catalog path, layout label, and placeholder roles. - Do not emit placeholder coordinates, placeholder IDs, layout IDs, layout selection decisions, colors, typography, or renderer object IDs. Useful local command: ```bash node bin/mdpr-skill.js layout-intent --layout-catalog template-layout-catalog.json --out .mdpresent/review/layout-intent.json ``` ### LLM-Assisted Content Review Helpers Use when the source needs semantic or editorial review before MDPR renders, or when MDPR-rendered evidence needs a human-readable review artifact. - `speaker-notes`: draft presenter notes and reviewer comments from Markdown and optional source notes. - `citations`: flag missing citations, stale sources, and unsupported claims from source metadata. - `rendered-preview`: consume MDPR-generated PNG/contact-sheet paths and emit visual concern notes only. Validate these artifacts with `validateRenderedPreviewCritiqueBoundary` when available; the notes may cite slide labels, rendered image paths, contact sheets, and MDPR finding IDs, but must not prescribe exact coordinates, fonts, colors, icons, image paths, crops, copied master/layout IDs, z-order, or renderer object IDs. - `accessibility`: draft alt text, plain-language, acronym expansion, and audience-fit suggestions. - `evidence-ledger`: map slide claims to source metadata and MDPR evidence IDs. - For readability and Korean decks, recommend shorter claim titles, fewer bullets, and moving detail to notes as content suggestions only. Do not pick font sizes or exact line breaks. - Prefer MDPR-provided source-cleanup diagnostics over re-deriving parser heuristics. Use raw Markdown marker heuristics only as a conservative fallback when no MDPR cleanup diagnostics were supplied. These helpers may cite source paths, headings, rendered image paths, MDPR finding IDs, source IDs, and evidence IDs. They must not emit coordinates, colors, typography, z-order, geometry, renderer object IDs, or pass/fail validation decisions. For source-neutral style references, prefer `DESIGN.md` frontmatter `sourceNeutral: true` with semantic tone, density, layout intent, decoration, and image-policy sections only. Do not include literal hex colors, exact fonts, copied PowerPoint master/layout IDs, exact icons, image paths, crops, or renderer object IDs; MDPR owns final theme binding and template preservation. Useful local commands: ```bash node bin/mdpr-skill.js speaker-notes --markdown deck.md --source-notes notes.md --out .mdpresent/review/speaker-notes.json node bin/mdpr-skill.js citations --markdown deck.md --sources sources.json --as-of 2026-06-27 --out .mdpresent/review/citation-review.json node bin/mdpr-skill.js rendered-preview --images rendered-images.json --out .mdpresent/review/rendered-preview-review.json node bin/mdpr-skill.js accessibility --markdown deck.md --audience "executive review" --out .mdpresent/review/accessibility-review.json node bin/mdpr-skill.js evidence-ledger --markdown deck.md --sources sources.json --mdpr-evidence mdpr-evidence.json --out .mdpresent/review/evidence-ledger.json ``` ### Change Requests And Override Proposals Use when an agent or PowerPoint bridge flow needs to record a proposed change without applying it directly to MDPR runtime output. - Emit `mdpr-change-request-v1` proposals for agent hints, edit intents, policy suggestions, pack candidates, or user-override candidates. - Keep change requests in `proposed` state until the user explicitly approves or rejects them. - Require approval metadata before any pack or override candidate is treated as a runtime input. - Use `edit override-candidate` only for bounded split preferences such as `splitBy`, `forceSingleSlide`, or `maxDensity`. It must not encode coordinates, colors, recipes, variants, or final layout decisions. - Prefer `ppt propose --markdown` when a PowerPoint selection context is tied to Markdown; this rejects stale source hashes before creating hints or change requests. Useful local commands: ```bash node bin/mdpr-skill.js edit override-candidate --source-sha256 <64hex> --slide-ref slide-3 --instruction "split dense evidence into smaller slides" --split-by h3 --out .mdpresent/proposals/split.override.json node bin/mdpr-skill.js ppt propose --selection-context .mdpresent/ppt/selection-context.json --markdown deck.md --out .mdpresent/proposals/ppt-selection.change-request.json --hints-out .mdpresent/proposals/ppt-selection.agent-hint.json node bin/mdpr-skill.js change approve .mdpresent/proposals/ppt-selection.change-request.json --approved-by <user-or-reviewer-id> --approved-at <ISO-8601> --out .mdpresent/proposals/ppt-selection.approved.change-request.json node bin/mdpr-skill.js change reject .mdpresent/proposals/ppt-selection.change-request.json --out .mdpresent/proposals/ppt-selection.rejected.change-request.json ``` ### Production Override And PDF Boundary Use when a revised MDPR runtime supports production override application or PDF output paths. - `mdpr-skill` may propose user-approved override candidates and review resulting artifacts. - MDPR owns applying production overrides, PDF output, renderer behavior, validation, and pass/fail decisions. - Do not encode final layout, coordinates, colors, recipes, variants, renderer object IDs, or PDF rendering decisions in skill output. ### Generator Comparison Boundary PptxGenJS, python-pptx, and other PPTX generators are comparison points only. Use them to describe capability vocabulary or benchmark context; do not add them as dependencies, fallback renderers, or alternate runtimes. MDPR remains the deterministic runtime. ### Codex PPT Compatibility Mapping Use when a user asks to support or match `codex-ppt-skill` capabilities in MDPR or `mdpr-skill`. - Treat `codex-ppt` as an image-based workflow reference, not as an alternate MDPR renderer. - Map each feature to an MDPR-native rail: runtime, proposal, review, orchestration, bridge, or generated visual asset rail. - Keep `coverage.unmappedFeatureCount` at `0` before claiming implementation coverage. - Preserve the output-model distinction: `codex-ppt` produces full-slide image PPTX; MDPR defaults to editable PPTX/HTML/PDF. - Use the compatibility map to create MDPR runtime TODOs for missing surfaces such as theme-pack registries, generated-asset provider metadata, slide task packets, and job-state tracking. - Use `codex-ppt slide-tasks` when a user needs codex-ppt-style per-slide jobs around an MDPR build. These packets are for single-slide review or repair proposals and must remain free of geometry, renderer object ids, exact colors, z-order, and final layout decisions. - Use `codex-ppt job-state` after task packet export when a workflow needs long-running slide review/repair state. `recorded` and `accepted` updates require artifact/report evidence, and `blocked` updates require a blocker reason; never treat chat text alone as completion evidence. - Use `codex-ppt generated-assets validate` for generated visual asset provider and quality metadata. The manifest records provider id, model, prompt hash, source input hashes, size, quality, background, transparency policy, and output provenance without secrets and without becoming a full-slide renderer. - Cross-check MDPR's mirrored validators for `mdpr-job-state-v1` and `mdpr-generated-assets-v1` when the revised MDPR runtime is available.