Update to Clara

{
  "description": "Build or revise source-faithful, cinematic, animated standalone HTML slide decks for Clara or Codex from Word, PDF, Markdown, spreadsheet, case-workspace, or mixed source materials. Use for a premium HTML presentation, web deck, animated talk, responsive keynote-style deck, speaker notes, preservation-aware HTML deck changes, or an alternative to PPTX/PDF that must remain self-contained and browser-presentable.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 254
    },
    {
      "relative_path": "assets/deck-engine/deck.css",
      "size_in_bytes": 27970
    },
    {
      "relative_path": "assets/deck-engine/deck.js",
      "size_in_bytes": 13996
    },
    {
      "relative_path": "assets/deck-engine/shell.html",
      "size_in_bytes": 3086
    },
    {
      "relative_path": "assets/deck-engine/starter-slides.html",
      "size_in_bytes": 10828
    },
    {
      "relative_path": "assets/layout-library/layouts.css",
      "size_in_bytes": 10613
    },
    {
      "relative_path": "assets/layout-library/registry.json",
      "size_in_bytes": 20736
    },
    {
      "relative_path": "assets/layout-library/starter-deck-plan.json",
      "size_in_bytes": 3094
    },
    {
      "relative_path": "assets/layout-library/templates/assertion.html",
      "size_in_bytes": 622
    },
    {
      "relative_path": "assets/layout-library/templates/chapter-transition.html",
      "size_in_bytes": 505
    },
    {
      "relative_path": "assets/layout-library/templates/closing-decision.html",
      "size_in_bytes": 535
    },
    {
      "relative_path": "assets/layout-library/templates/decision-gates.html",
      "size_in_bytes": 417
    },
    {
      "relative_path": "assets/layout-library/templates/editorial-cover.html",
      "size_in_bytes": 591
    },
    {
      "relative_path": "assets/layout-library/templates/evidence-register.html",
      "size_in_bytes": 434
    },
    {
      "relative_path": "assets/layout-library/templates/evidence-split.html",
      "size_in_bytes": 1002
    },
    {
      "relative_path": "assets/layout-library/templates/image-led.html",
      "size_in_bytes": 690
    },
    {
      "relative_path": "assets/layout-library/templates/items/closing-action.html",
      "size_in_bytes": 216
    },
    {
      "relative_path": "assets/layout-library/templates/items/comparison-point.html",
      "size_in_bytes": 199
    },
    {
      "relative_path": "assets/layout-library/templates/items/decision-gate.html",
      "size_in_bytes": 238
    },
    {
      "relative_path": "assets/layout-library/templates/items/evidence-entry.html",
      "size_in_bytes": 296
    },
    {
      "relative_path": "assets/layout-library/templates/items/evidence-point.html",
      "size_in_bytes": 195
    },
    {
      "relative_path": "assets/layout-library/templates/items/metric.html",
      "size_in_bytes": 261
    },
    {
      "relative_path": "assets/layout-library/templates/items/process-step.html",
      "size_in_bytes": 253
    },
    {
      "relative_path": "assets/layout-library/templates/items/roadmap-phase.html",
      "size_in_bytes": 298
    },
    {
      "relative_path": "assets/layout-library/templates/items/scenario-row.html",
      "size_in_bytes": 290
    },
    {
      "relative_path": "assets/layout-library/templates/items/timeline-step.html",
      "size_in_bytes": 362
    },
    {
      "relative_path": "assets/layout-library/templates/metric-contrast.html",
      "size_in_bytes": 427
    },
    {
      "relative_path": "assets/layout-library/templates/paired-comparison.html",
      "size_in_bytes": 1047
    },
    {
      "relative_path": "assets/layout-library/templates/process-flow.html",
      "size_in_bytes": 426
    },
    {
      "relative_path": "assets/layout-library/templates/roadmap.html",
      "size_in_bytes": 422
    },
    {
      "relative_path": "assets/layout-library/templates/scenario-matrix.html",
      "size_in_bytes": 434
    },
    {
      "relative_path": "assets/layout-library/templates/timeline.html",
      "size_in_bytes": 423
    },
    {
      "relative_path": "assets/layout-library/templates/visual-takeaway.html",
      "size_in_bytes": 697
    },
    {
      "relative_path": "references/evidence-bindings.md",
      "size_in_bytes": 8408
    },
    {
      "relative_path": "references/quality-bar.md",
      "size_in_bytes": 5095
    },
    {
      "relative_path": "references/revision-workflow.md",
      "size_in_bytes": 2792
    },
    {
      "relative_path": "references/static-compatibility.md",
      "size_in_bytes": 1796
    },
    {
      "relative_path": "references/structured-authoring.md",
      "size_in_bytes": 6704
    },
    {
      "relative_path": "scripts/browser_qa_html_deck.py",
      "size_in_bytes": 73385
    },
    {
      "relative_path": "scripts/build_html_deck.py",
      "size_in_bytes": 25583
    },
    {
      "relative_path": "scripts/build_layout_gallery.py",
      "size_in_bytes": 39162
    },
    {
      "relative_path": "scripts/compare_html_deck_revision.py",
      "size_in_bytes": 1322
    },
    {
      "relative_path": "scripts/compose_html_deck.py",
      "size_in_bytes": 40763
    },
    {
      "relative_path": "scripts/content_ledger.py",
      "size_in_bytes": 10987
    },
    {
      "relative_path": "scripts/data_visuals.py",
      "size_in_bytes": 24253
    },
    {
      "relative_path": "scripts/evidence_bindings.py",
      "size_in_bytes": 62967
    },
    {
      "relative_path": "scripts/html_deck_revision.py",
      "size_in_bytes": 63986
    },
    {
      "relative_path": "scripts/init_html_deck.py",
      "size_in_bytes": 4840
    },
    {
      "relative_path": "scripts/inspect_html_deck.py",
      "size_in_bytes": 1002
    },
    {
      "relative_path": "scripts/validate_html_deck.py",
      "size_in_bytes": 47352
    },
    {
      "relative_path": "scripts/validate_revision_map.py",
      "size_in_bytes": 1227
    }
  ],
  "name": "html-deck",
  "skill_md_contents": "---\nname: html-deck\ndescription: Build or revise source-faithful, cinematic, animated standalone HTML slide decks for Clara or Codex from Word, PDF, Markdown, spreadsheet, case-workspace, or mixed source materials. Use for a premium HTML presentation, web deck, animated talk, responsive keynote-style deck, speaker notes, preservation-aware HTML deck changes, or an alternative to PPTX/PDF that must remain self-contained and browser-presentable.\n---\n\n<!-- CLARA_OPENAI_ONBOARDING_BEGIN -->\nOnboarding is optional. Continue ordinary professional work immediately,\nincluding direct specialist invocation, without checking or completing a local\nonboarding profile. Missing, unfinished, inaccessible or corrupt onboarding state,\nor unavailable voice/window controls, must never block ordinary work. Do not\nautomatically start, resume or repeatedly offer onboarding.\nOnly for a user-requested tutorial or a native teaching handoff, read\n`../clara/references/local-onboarding.md`. A verified paired lesson worker\nexecutes only its bound lesson and token; never bypass tutorial validation.\nTutorial profiles, progress, examples and feedback remain local; never send a\nchange request, stamp a tutorial receipt or call hosted interviews for a tutorial.\nCurrent user requests take precedence over saved preferences.\n<!-- CLARA_OPENAI_ONBOARDING_END -->\n\n# HTML Deck\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n\nCreate a decision-ready HTML presentation with bespoke editorial craft and a\nrepeatable authoring, provenance, revision, and browser-QA system. Keep source\nmaterial authoritative. Use motion to clarify meaning, not decorate it.\n\n## Non-negotiables\n\n- Preserve names, numbers, periods, dates, qualifications, examples, and\n  advisory logic. Never make a deck prettier by making it less true.\n- For a Clara case, build only after the Advisory Intelligence Loop and from\n  `advisory_workpaper.md`, `presentation_storyline.md`, relevant sources, and\n  advisor judgement actually supplied. Keep material evidence gaps visible.\n- Keep user data and outputs outside plugin source. Put the work folder and\n  deliverables beside the user's project outputs or in the requested folder.\n- Produce a dependency-free `index.html`: no CDN, web font, remote script,\n  analytics, tracking, or required network request.\n- Publish below a lowercase 64-character hexadecimal directory by default and\n  include `noindex,nofollow,noarchive` unless discovery is requested.\n- Use Clara's shared fixed 16:9 runtime. Letterbox rather than stretch. Every\n  slide needs a stable ID, audience-facing title, and speaker notes.\n- Keep operator chrome outside slide content. Persistent visual page numbers\n  and decorative counters are prohibited; the auto-hiding HUD may show state.\n- Preserve keyboard, touch, reduced-motion, accessibility, and print behavior.\n- Treat a difficult URL as convenient obscurity, not access control.\n\n## Retain bound build artifacts\n\nContent-addressed build directories under `<output_root>/<sha256>/` must remain\nin place once their appearances are bound to the claim register. Never delete a\nprevious bound build after rebuilding; retain superseded builds alongside new\nones. Claim appearances are append-only and refer to the exact original bytes.\nBefore any proposed cleanup, run from the plugin root:\n\n```bash\npython scripts/advisory_evidence_lineage.py check-safe-to-delete <case_dir> <path>\n```\n\nA nonzero exit blocks cleanup when this case references the path or a file below\nit, or its lineage cannot be checked. A zero exit means only that this case has\nno bound appearance there; check every other case using that output root too.\nThe command is read-only and does not prevent manual filesystem deletion.\n\n\n## Decision boundary\n\nThe model owns semantic work: source interpretation, storyline, claims,\nqualifications, layout choice, visual type, analytical filters and periods,\nspeaker notes, and editorial judgement.\n\nDeterministic helpers own mechanically verifiable work: schema and ID checks,\nsafe text handling, density/fragment limits, numerical rendering from supplied records,\nprovenance links, content addressing, preservation fingerprints, browser\ngeometry/interactions, packaging, and report generation. A helper must never\ninvent a claim, choose a period, or decide which visual tells the story.\n\n## Workflow\n\n### 1. Check the runtime and establish source truth\n\nFrom the Clara plugin root, run the dependency check before any helper:\n\n```bash\npython scripts/check_dependencies.py\n```\n\nRead source material with the appropriate document, spreadsheet, PDF, or\nbrowser capability. For each intended slide, define:\n\n- stable slide ID, audience-facing title, and purpose in the spoken argument;\n- exact claims, values, periods, labels, units, and qualifications;\n- whether each claim is fact, assumption, target, forecast, probability,\n  illustrative output, judgement, or open question;\n- source-backed or speaker-judgement basis;\n- visual mechanism, notes intent, and evidence IDs.\n\nWrite the storyline as an argument, not a table of contents. Open with the real\ntension, move through evidence and choices, and end with a decision, action, or\nquestion. Delete pages that repeat or exist only because a layout is available.\n\n### 2. Initialize editable work\n\n```bash\npython skills/html-deck/scripts/init_html_deck.py \\\n  --work-dir <project-output-folder>/html-deck-work \\\n  --title \"<deck title>\" \\\n  --subtitle \"<one-line promise>\" \\\n  --author \"<speaker or firm>\" \\\n  --eyebrow \"<talk or engagement label>\" \\\n  --language it\n```\n\nThe initializer creates:\n\n- `deck.json` — publication metadata;\n- `deck-plan.json` — structured narrative/layout plan;\n- `content-ledger.json` — slide, claim, and source provenance;\n- `slides.html` — editable composed slide markup;\n- `custom.css` — deck-specific styling.\n\nThe initial content is a guide, not a finished deck. Replace all `REPLACE THIS`\ncontent and reconcile the plan and ledger before building.\n\n### 3. Author through the layout registry\n\nRead [references/quality-bar.md](references/quality-bar.md) and\n[references/structured-authoring.md](references/structured-authoring.md).\nFor any production number, date, percentage, count, currency amount, table\ncell, or chart mark, also read\n[references/evidence-bindings.md](references/evidence-bindings.md) and use the\nsource-bound v2 plan/ledger contract. Do not copy business values into a v1\nplan.\nInspect `assets/layout-library/registry.json`; choose layouts from their\nnarrative roles, not by keyword matching.\n\nWhen layout selection is uncertain, generate the complete preview gallery:\n\n```bash\npython skills/html-deck/scripts/build_layout_gallery.py \\\n  --output-dir <project-output-folder>/layout-gallery\n```\n\nIt renders all 15 layouts at 1280×720, 1024×768, and 390×844 and writes\n`layout-previews.json` with screenshot paths. It is a mechanical preview, not a\nlayout recommendation.\n\nEdit `deck-plan.json` and `content-ledger.json`, then compose:\n\n```bash\npython skills/html-deck/scripts/compose_html_deck.py \\\n  <project-output-folder>/html-deck-work/deck-plan.json \\\n  --output-dir <project-output-folder>/html-deck-work \\\n  --force\n```\n\nThe composer emits stable QA roles, provenance attributes, fragments,\n`slides.html`, and the shared layout CSS. Its bundled `data_visual` renderer\nsupports bar, line, scatter, bubble, waterfall, timeline, and table components.\nSupply already-selected and correctly filtered data. The renderer deliberately\ndoes not filter time, combine years, or make analytical choices.\n\nFor a v2 plan, first seal `evidence-bundle.json` with\n`scripts/evidence_bindings.py seal`. Composition also writes\n`resolved-deck-plan.json`, `resolved-content-ledger.json`, and\n`evidence-ledger.json`. The same central binding can feed prose, claims, metric\ncards, tables, and prepared visual data without numeric transcription.\n\nPrefer registered layouts. Set `allow_bespoke_html: true` only when the required\nmechanism genuinely cannot fit the library. Bespoke markup remains body-only\nand is still subject to escaping, executable-attribute, and resource checks.\n\nAfter composition, use `custom.css` only for deck-specific semantic needs. Do\nnot fork the shared engine for one deck. Keep one visual idea per slide, direct\nlabel data, reserve warning color for actual risk, and keep delivery detail in\nspeaker notes.\n\n### 4. Build and run static validation\n\n```bash\npython skills/html-deck/scripts/build_html_deck.py \\\n  <project-output-folder>/html-deck-work \\\n  --output-root <project-output-folder> \\\n  --package <project-output-folder>/<descriptive-name>.zip \\\n  --report <project-output-folder>/<descriptive-name>-validation.json \\\n  --case-dir <case-dir>\n```\n\nThe builder recompiles a source-bound v2 deck and requires byte equality with\nits editable HTML, generated/shared CSS, resolved documents, and evidence\nledger. It then compiles a standalone file, applies the runtime idempotently,\nembeds the publication-safe content and evidence ledgers, computes SHA-256, writes\n`<output-root>/<64-hex-sha256>/index.html`, validates those exact bytes, and\ncreates a canonical ZIP. Errors block delivery. Rebuild ZIPs from work sources;\nnever edit generated packages.\n\nFor a deck that belongs to a Clara advisory case, `--case-dir` is mandatory.\nEvery content-ledger claim must already exist as an active claim in the shared\nadvisory claim register with the same statement. After the content-addressed\nstandalone HTML is written, the builder records its exact hash and claim locator\nas an output appearance. It does not infer claims from HTML. The option remains\noptional only for a standalone talk deck that does not belong to an advisory\ncase.\n\nLegacy v1 quantitative content fails by default. The\n`--allow-unverified-quantitative-content` flag exists only for explicit\nillustrative galleries or legacy material; it leaves\n`evidence.status: not_verified` and is never acceptable for a source-backed\nreport.\n\nRun static validation alone while iterating:\n\n```bash\npython skills/html-deck/scripts/validate_html_deck.py \\\n  <64-hex-slug>/index.html\n```\n\n### 5. Run strict automated browser QA\n\n```bash\npython skills/html-deck/scripts/browser_qa_html_deck.py \\\n  <64-hex-slug>/index.html \\\n  --output-dir <project-output-folder>/browser-qa \\\n  --report <project-output-folder>/browser-qa.json \\\n  --warnings-as-errors\n```\n\nThe default viewport set covers 1280×720, 1920×1080, 1024×768, and 390×844.\nThe report checks each slide's geometry, overflow, declared-role collisions,\nconsole/page errors and warnings, navigation, fragments, overview, notes,\nEscape, reduced motion, and print behavior. It emits full-slide screenshots, a\nscreenshot index, and print-preview PDF. Missing Playwright/browser support is\n`blocked` with exit code 2, never a pass.\n\nReview the complete screenshot index and print preview. The automated gate\ncannot judge source fidelity, hierarchy, decision usefulness, meaningful\nmotion, or whether a chart communicates the intended mechanism. Fix every\nclipping, collision, weak contrast, unreadable label, or decorative animation;\nthen rebuild and rerun both gates.\n\n#### Narrow static-deck compatibility exception\n\nThe normal authoring and delivery contract remains the strict Clara stage\nprofile above. Use `--profile static` only when an external, already-specified\ndeck contract must remain linked/static, such as a controlled format benchmark\nor a preservation-bound legacy import. It is not an authoring shortcut and does\nnot waive source fidelity or visual QA. Follow\n[references/static-compatibility.md](references/static-compatibility.md) and run\nboth the static validator and browser QA in that profile.\n\n### 6. Use revision mode for existing Clara HTML decks\n\nFor a requested deck change, read\n[references/revision-workflow.md](references/revision-workflow.md). Inspect the\nbaseline, create a hash-bound revision map, classify every slide, give each edit\ntarget a reason, validate the map, edit a copy, and compare before/after:\n\n```bash\npython skills/html-deck/scripts/inspect_html_deck.py \\\n  <baseline> --report <output>/baseline-inventory.json\n\npython skills/html-deck/scripts/validate_revision_map.py \\\n  <baseline> <revision-map.json> \\\n  --report <output>/revision-map-validation.json\n\npython skills/html-deck/scripts/compare_html_deck_revision.py \\\n  <baseline> <revised> \\\n  --revision-map <revision-map.json> \\\n  --report <output>/revision-comparison.json\n```\n\nThe comparator enforces untouched/protected slide and component fidelity,\nslide-local provenance, declared global resources, order, IDs, and actual\ntarget changes. It applies only to Clara stage decks/work folders. After a pass,\nbuild and browser-QA the revised deck exactly as above.\n\nFor a case-bound deck, HTML checks are not the final advisory gate. After the\nmodel-led `clara:advisory-deliverable-validator` package is complete for the\nexact final HTML, write the delivery receipt:\n\n```bash\npython scripts/verify_advisory_html_delivery.py \\\n  <case-dir> <64-hex-slug>/index.html \\\n  <project-output-folder>/validation/validation_audit.json \\\n  --output <project-output-folder>/advisory_html_delivery_receipt.json\n```\n\nThe receipt fails closed unless the current workpaper checkpoint and registers,\nexact deck appearances, static report, browser-QA report, and advisory validator\naudit all refer to the same current bytes. It does not judge support or\nrecommendation quality.\n\n## Codex-Native Run UX\n\nBefore write-heavy work, show a compact Run Intake table with sources, audience,\nlanguage, work folder, output root, privacy, and notes requirement. Ask only for\nmaterial unresolved choices. Use a Decision Table only for choices that would\nmaterially change the result. Use a short checklist for source truth, plan and\nledger, composition, build, browser QA, semantic review, and delivery.\n\nBefore building, show one execution checkpoint naming work folder, output root, slide\ncount, package, static report, and browser-QA report. Default to keeping the\neditable work folder, plan, ledger, content-addressed HTML, ZIP, static report,\nscreenshots, and browser report. This Default output policy is the normal run;\nthese artifacts are not choices to propose when the user has already requested\na complete deck. Never edit generated ZIPs by hand; rebuild them from source.\n\n## Delivery\n\nReturn an Artifact Card with:\n\n- clickable `index.html` and ZIP package;\n- editable work folder, `deck-plan.json`, and `content-ledger.json`;\n- for quantitative work, the sealed evidence bundle, resolved plan/ledger, and\n  `evidence-ledger.json`;\n- static validation and browser-QA reports;\n- for a case-bound deck, the `advisory_html_delivery_receipt.json` ready result;\n- screenshot index and print preview;\n- revision inventory/map/comparison when revision mode was used;\n- slide count and source materials used;\n- deliberately accepted residual issues, if any.\n\nInclude this user-facing revision affordance in the delivery: **“Want to revise\nthis deck? Tell Clara: ‘Record feedback on this deck.’”** When the user invokes\nit, route to `deck-correction`; do not ask them to open the hosted capture URL or\nimport its download manually.\n\nFor a case-bound deck, do not state that it is ready to publish or deliver\nwithout a `ready` delivery receipt for the exact final bytes. State that the\ndeck is ready to publish, not already published, unless an authorized\npublishing step actually occurred. Create `codex_run_review.md` only when a run\nis blocked, a fallback was accepted, or a repeated failure needs a local\nhandoff note.\n"
}