@cyber-dash-tech/revela 0.18.15 → 0.19.0

package/plugins/revela/skills/revela-design/SKILL.md

@@ -9,34 +9,39 @@ Use this skill when the user asks to create, customize, edit, validate, package,
 
 ## Contract
 
-- Designs define deck visual systems: rules, foundation, layouts, components, chart rules, and preview coverage.
+- Designs define deck visual systems: rules, foundation, layouts, components, chart rules, and page-template foundation styling.
+- CSS-native designs include `design.css` as the executable visual source. `DESIGN.md` explains the design contract; `design.css` styles the stable template DOM classes.
+- Designs should define executable visual contracts, not only mood, fonts, and palettes. Capture grid/safe-area, spacing scale, type scale, surface behavior, chart tokens, component states, and preview fixtures in the design package.
 - Designs may include package-owned `assets/**` such as cover or closing backgrounds; design tools surface these as design elements, not source evidence.
 - When the user uploads or provides logo, cover, closing, background, texture, brand image, or similar design material, store it inside the design package with `revela_design_draft_create.assets`; use paths under `assets/**` only.
-- Generated `preview.html` must actually reference uploaded design assets with package-relative `assets/...` paths rather than describing them only in text.
+- Design previews are generated from Revela's built-in page-template preview plus the draft or installed `design.css`.
 - Default authoring is workspace draft first, then validate, then install only when appropriate.
 - Direct user-level creation is reserved for explicit create/install-now requests.
 - Shareable design archives are `.tar` or `.tar.gz`; install archives only from trusted local paths.
 - Do not use domain tools for visual design work.
-- Do not generate deck HTML while authoring a design.
+- Do not write `decks/*.html` while authoring a design. Use `revela_design_preview` to generate a workspace-local design preview.
 
 ## Required Tools
 
 For status, inspection, activation, or selection:
 
 1. Call `revela_design_list`.
-2. Call `revela_design_read`, `revela_design_inventory`, `revela_design_read_layout`, or `revela_design_read_component` as needed.
+2. Call `revela_design_read`, `revela_design_inventory`, `revela_design_read_layout`, `revela_design_read_component`, or `revela_page_template_foundation` as needed.
 3. Call `revela_design_activate` only when the user asks to use a design.
 
 For new or edited designs:
 
 1. Call `revela_design_list`.
 2. Read the requested base design or active design with `revela_design_read`.
-3. Draft complete `DESIGN.md` and complete `preview.html` content.
-4. Call `revela_design_draft_create`; when uploaded or local design material exists, pass `assets: [{ path: "assets/...", contentBase64|content|sourcePath }]` so the files are written into the draft package.
-5. Call `revela_design_draft_validate`.
-6. If validation fails, revise the draft content and repeat draft create/validate.
-7. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
-8. Call `revela_design_activate` only when the user asks to make it active.
+3. Call `revela_design_inventory` and inspect its `pageTemplates` summary.
+4. Call `revela_page_template_foundation` for any built-in page templates the design should style or preview.
+5. Draft complete `DESIGN.md` and complete `design.css` content.
+6. Call `revela_design_draft_create` with `designCss`; when uploaded or local design material exists, pass `assets: [{ path: "assets/...", contentBase64|content|sourcePath }]` so the files are written into the draft package.
+7. Call `revela_design_draft_validate`.
+8. Call `revela_design_preview` for the draft and inspect the generated preview in Browser.
+9. If validation or preview review fails, revise the draft content and repeat draft create/validate/preview.
+10. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
+11. Call `revela_design_activate` only when the user asks to make it active.
 
 For sharing or installing design archives:
 
@@ -52,17 +57,22 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 
 - Use a kebab-case design name.
 - `DESIGN.md` must include valid frontmatter and complete design marker sections.
+- `design.css` should be present for CSS-native designs and is the only executable CSS source for package-owned template styling.
 - Include design rules, foundation guidance, at least one layout, and at least one component.
+- In `@design:foundation`, document the design contract: grid columns or layout rails, safe area, spacing/baseline scale, typography scale, surfaces/borders/shadows, and chart tokens when charts are supported.
+- Use page-template foundation as the starting point for built-in template styling. Style template classes, but do not remove structural classes or `data-template-slot` semantics.
+- Layouts must declare stable slots and use grid/flex structure as the source of alignment. Avoid one-off absolute positioning that bypasses the declared layout contract.
+- Components should describe normal, dense, and long-copy behavior where relevant. Chart, table, media, and source-note components need stable container dimensions.
 - Optional assets must live under `assets/**`; reference them as package-relative paths like `assets/cover-background.png`.
 - `DESIGN.md` may reference package assets in rules, layouts, or components with `assets/...`; do not reference workspace `assets/` media manifest entries for design-owned visuals.
-- `preview.html` must use the fixed Revela preview canvas contract and visibly preview the design.
-- If design assets are present, `preview.html` must visibly use the saved `assets/...` files, for example a cover hero background or logo image.
-- Preview must include cover and closing examples and showcase every component.
+- `revela_design_preview` must generate the visual preview; do not hand-write package `preview.html` for ordinary CSS-native design drafts.
+- If design assets are present, the generated preview should visibly use the saved `assets/...` files when the design CSS references them.
+- Generated preview should show the built-in page templates with normal, dense, chart/table, timeline, image, and source-note-like states.
 - Preserve source inspiration and limitations explicitly; do not copy copyrighted design text or assets into the package.
 
 ## Outputs
 
-- Design draft path/status or installed design name.
+- Design draft path/status, generated preview path/status, or installed design name.
 - Archive path/status when packaging or installing a shareable design.
 - Asset metadata surfaced by read/inventory tools when `assets/**` exists.
 - Saved asset paths and intended uses, for example `assets/cover-background.png -> cover hero background`.
@@ -74,5 +84,6 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 
 - Do not write `deck-plan.md`.
 - Do not write `decks/*.html`.
+- Do not patch `decks/_revela-design/**/design.css`; those files are regenerated deck-local snapshots.
 - Do not install or activate a design unless the user requested that outcome.
 - Do not invent licenses, asset provenance, or brand permissions.

package/plugins/revela/skills/revela-helper/SKILL.md

@@ -12,7 +12,7 @@ Use this skill when the user asks what Revela is, what the current workspace sta
 - This is a read-only helper and orientation surface.
 - `revela` is the main workflow router; this skill explains status and capabilities.
 - It may inspect runtime, design, domain, and workspace artifact status.
-- It must not perform research, write files, create `spec.md`, create `deck-plan.md`, generate decks, open Review UI, or export artifacts.
+- It must not perform research, write files, create `spec.md`, create `deck-plan.md`, generate decks, open deck browser views, or export artifacts.
 - Keep the answer short and operational.
 
 ## Preconditions
@@ -46,7 +46,7 @@ Report:
   - `spec.md` exists but no `researches/`: run `revela-research`.
   - Research exists but no `deck-plan.md`: continue `revela-research` to the Planning Handoff.
   - Valid `deck-plan.md` but no deck artifact: run `revela-make-deck`.
-  - Existing deck artifact: run `revela-review` or `revela-export` depending on the user goal.
+  - Existing deck artifact: surface the HTML deck as a website card/link for Codex Browser native annotation, or run `revela-export` for PDF/PPTX/PNG.
 
 ## Must Not
 
@@ -54,5 +54,5 @@ Report:
 - Do not do external web research.
 - Do not generate or repair `spec.md`.
 - Do not generate or repair `deck-plan.md`.
-- Do not generate, review, patch, or export deck artifacts.
+- Do not generate, annotate, patch, or export deck artifacts.
 - Do not create, install, or activate designs or domains; route those requests to `revela-design` or `revela-domain`.

package/plugins/revela/skills/revela-make-deck/SKILL.md

@@ -12,9 +12,12 @@ Use this skill when the user asks to make, generate, render, or update a Revela
 - Deck execution planning comes from canonical `deck-plan.md`.
 - Local materials, material reviews, `researches/`, `assets/`, and user intent provide source context.
 - Slide argument copy comes from `deck-plan.md` `Claim`, `Reasoning`, and `Audience takeaway` fields when present; raw findings are evidence/source context, not default body copy.
-- Active/requested design tools define valid layouts, slots, components, nesting hints, and HTML writing rules.
+- Active/requested design tools define valid layouts, slots, components, nesting hints, structure contracts, and HTML writing rules.
+- Built-in page template tools define semantic page templates, foundation/scaffold HTML, editable slots, stable DOM contracts, and template QA contracts.
+- Deck-local `decks/_revela-design/**/design.css` files are generated design snapshots. Do not patch them during deck making; regenerate the deck foundation or enter the design workflow instead.
 - Active/requested domain guidance may inform communication framing, but it is not source evidence.
 - Generated artifacts live under `decks/*.html`.
+- After final Artifact QA passes, reply with the generated HTML deck as a standalone website link/card that opens in Codex Browser for native browsing and annotation.
 - Do not require a Narrative Vault before generating a deck.
 - This skill does not own normal plan authoring; `revela-research` owns source preparation and `deck-plan.md` planning handoff.
 - `deck-plan.md` is required for normal deck generation.
@@ -42,14 +45,19 @@ Before render preflight:
 1. Call `revela_design_list`.
 2. Call `revela_design_read` with `section: "rules"` for the active/requested design.
 3. Call `revela_design_inventory`.
+4. Call `revela_list_page_templates` when the deck-plan uses `template` fields or when adding a new page.
+5. For each template used in the current batch, call `revela_page_template_foundation` before creating or editing scaffold HTML.
+6. Review each component's `contract` field. Components with structure contracts must be planned from structured content and rendered with the required internal DOM/classes, not simplified freehand markup.
 
 Before HTML writing:
 
 1. Call `revela_read_deck_plan`.
 2. Read the returned `htmlWritingBatches`.
-3. Call `revela_design_read_layout` for each layout used in the current batch.
-4. Call `revela_design_read_component` for each component used in the current batch.
-5. Fetch chart rules before creating or modifying ECharts.
+3. For new slides with `template`, call `revela_render_template_scaffold` or `revela_add_template_scaffold`, then bounded-edit only the inserted slide's `data-template-slot` regions.
+4. Use `revela_render_template_slide` / `revela_add_template_slide` only as a compatibility path for existing full `Template Content` JSON plans.
+5. For legacy slides without `template`, call `revela_design_read_layout` for each layout used in the current batch.
+6. For legacy slides without `template`, call `revela_design_read_component` for each component used in the current batch. For contract components, treat the returned CSS/HTML as executable grammar and preserve the required root, descendant, item, and alternating classes.
+7. Fetch chart rules before creating or modifying ECharts.
 
 ## Plan Preflight And Repair
 
@@ -61,6 +69,7 @@ Allowed plan repairs are limited to technical diagnostics from `revela_read_deck
 - Invalid or missing `sourceLinks` field structure, without adding new unsupported source links.
 - Layout, slot, component, or `children` names that do not match `revela_design_inventory`.
 - Component nesting fixes such as using `box.children` when the selected component model requires nested semantic groups.
+- Missing or misspelled built-in `template` ids reported by `revela_read_deck_plan`.
 
 Do not redesign the argument structure, add new slides, remove supported slides, rewrite claims, or add source links that were not reviewed or saved by `revela-research`. If normal plan authoring is needed, stop and send the user back to `revela` routing or `revela-research` Planning Handoff.
 
@@ -74,19 +83,24 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 2. Read `htmlWritingBatches` before any HTML write. `revela_read_deck_plan` is QA/diagnostics, not a writer.
 3. For new HTML files, call `revela_create_deck_foundation`.
 4. Use the deck-plan's `Claim`, `Reasoning`, and `Audience takeaway` as the primary slide copy. Keep finding text in source notes, captions, evidence charts, or speaker notes unless the plan explicitly calls for a direct evidence quote.
-5. Generate one `htmlWritingBatches` entry at a time.
-6. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
-7. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
-8. Patch slides into the foundation between Revela slide markers.
-9. Preserve positive 1-based `data-slide-index` values.
-10. Every slide must have exactly one direct `.slide-canvas` child.
-11. Keep the HTML valid after each write.
-12. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing, review, or export.
+5. For template slides, use the deck-plan `template` to create a scaffold with `revela_add_template_scaffold`; use `Template Content` only as seed or compatibility input, not as the final authoring interface.
+6. After scaffold insertion, bounded-edit the current slide HTML: preserve `.slide`, `.slide-canvas`, `data-template`, required template classes, and `data-template-slot` semantics.
+7. Visual slots may be replaced by image, chart, table, or diagram containers only when the replacement keeps a clear semantic container for QA and export.
+8. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
+9. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
+10. Patch slides into the foundation between Revela slide markers.
+11. Preserve positive 1-based `data-slide-index` values.
+12. Every slide must have exactly one direct `.slide-canvas` child.
+13. Keep the HTML valid after each write.
+14. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing or export.
+15. After the final `revela_run_deck_qa` passes with zero hard errors, reply with a standalone Markdown link to the generated HTML deck artifact so Codex renders an Open in Browser website card.
+16. Prefer an absolute `file://` URL for the card. If the card or direct file navigation is unavailable, start a read-only local static server from the workspace root and use the exact `http://127.0.0.1:<port>/decks/<file>.html` URL.
 
 ## Outputs
 
 - `decks/*.html`.
 - Artifact QA status.
+- Website card/link for the QA-passed HTML deck.
 - Unresolved render/design issues and any plan diagnostics that require `revela-research` Planning Handoff.
 
 ## Must Not
@@ -96,6 +110,7 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 - Do not write a new `deck-plan.md` when it is missing.
 - Do not use design inventory names, slots, or components that were not returned by the active/requested design tools.
 - Do not use a slot that does not belong to the selected layout.
+- Do not delete template required classes or slots during bounded edits. If the required structure cannot be satisfied, choose a simpler valid template/component or stop with the contract issue.
 - Do not patch more than 5 slide sections in one HTML write.
 - Do not invent source links, quotes, URLs, page references, caveats, or licenses.
 - Do not write remote image candidates directly into deck HTML; save them as workspace assets first.

package/plugins/revela/skills/revela-research/SKILL.md

@@ -49,6 +49,7 @@ Use this skill when the user asks to start from a goal, inspect local materials,
     - Call `revela_design_list`.
     - Call `revela_design_read` with `section: "rules"` for the active/requested design.
     - Call `revela_design_inventory`.
+    - When a chosen component has a `contract` field, preserve that contract in the visual brief/render notes so Make Deck renders the required internal structure instead of a simplified lookalike.
     - Write `deck-plan.md` directly from reviewed materials, saved findings, assets, user intent, active domain framing, and active design vocabulary.
     - Call `revela_read_deck_plan` after writing `deck-plan.md`.
     - If diagnostics report `sourceLinks`, layout, slot, component, or `children` issues, patch `deck-plan.md` directly and call `revela_read_deck_plan` again.

package/skill/SKILL.md

@@ -143,6 +143,9 @@ Rules for the slide plan:
 - Use exact layout names from the Layout Index and exact component names from
   the Component Index. Use only slots returned by the selected layout inventory.
   Do not invent layout, slot, or component names.
+- Components marked in the Component Index Contract column have mandatory
+  internal structure. Preserve their required DOM/classes in render notes and
+  HTML generation; do not describe them as generic visual ideas.
 - Use `box.children` when several child components support one semantic idea.
   Do not duplicate a child component both inside `box.children` and as a
   separate top-level component plan entry.
@@ -217,8 +220,11 @@ Before writing or materially changing HTML:
    layout names, comma-separated.
 5. Call `revela-designs` with `action: "read"` and `component` set to all
    required component names, comma-separated.
-6. Fetch `section: "chart-rules"` before using ECharts.
-7. Do not update legacy `requiredInputs`; design fetching is an execution step,
+6. For any component with a Contract marker, copy the fetched component
+   structure closely and keep its required root, descendant, item, and
+   alternating classes.
+7. Fetch `section: "chart-rules"` before using ECharts.
+8. Do not update legacy `requiredInputs`; design fetching is an execution step,
    not a workflow permission gate.
 
 Never generate HTML from memory or prior knowledge of a design. Copy the fetched
@@ -279,6 +285,9 @@ The active design defines a closed vocabulary of layouts and components.
 
 - Every slide must use exactly one layout class from the Layout Index.
 - Every content block must use component classes from the Component Index.
+- Contract components must satisfy their fetched structure contract. Do not
+  replace a timeline, roadmap, chart frame, or other structured component with
+  a visual approximation that only resembles it.
 - Do not invent layout classes, component names, CSS variables, custom grids, or
   custom visual effects.
 - Do not define new class rules in the deck `<style>` block unless the fetched