jupytermind 0.3.0

package/.github/skills/presentation-planner/references/customizing-design-templates.md

@@ -0,0 +1,160 @@
+# Customizing presentation design templates
+
+Use this guide to adapt a packaged design for one presentation or to add a
+new reusable design to kotonoha. Design templates are YAML specifications;
+they are not `.pptx` theme files and do not replace the host's PPTX creation
+skill.
+
+## Choose between a deck override and a packaged template
+
+Use a **deck override** when one presentation needs different colors, type,
+spacing, or component behavior. Copy a packaged design into:
+
+```text
+.presentation/<deck-slug>/design-spec.yaml
+```
+
+Use a **new packaged template** only when the design will be reused across
+multiple presentations or teams. Add it under:
+
+```text
+skills/presentation-planner/assets/design-templates/<template-id>.yaml
+```
+
+Do not edit a packaged template merely to customize one deck; that changes
+future presentations and makes upgrades harder to compare.
+
+## Copy and identify an adapted design
+
+1. Copy the closest packaged YAML file to the deck directory.
+2. Set `base_template` to the packaged template's original `id`.
+3. Change `id` to a deck-specific value such as
+   `<deck-slug>:<base-template>`.
+4. Keep every documented top-level key from
+   `design-spec-schema.md`.
+5. Record intentional changes under `deviations`.
+
+Example:
+
+```yaml
+id: migration-proposal:executive-proposal
+base_template: executive-proposal
+deviations:
+  - "Use the customer-approved heading font."
+  - "Increase the table row limit from 7 to 9 for the appendix."
+```
+
+## Change colors by semantic role
+
+Change the meaning-bearing token rather than replacing colors wherever they
+appear.
+
+```yaml
+colors:
+  background: "#FFFFFF"
+  surface: "#F3F3F3"
+  text_primary: "#1B1B1B"
+  text_secondary: "#505050"
+  accent: "#005A9E"
+  accent_soft: "#E5F1FB"
+  border_neutral: "#8A8886"
+  positive: "#107C10"
+  warning: "#8A5A00"
+  critical: "#A4262C"
+```
+
+The packaged designs expose Microsoft's corporate logo colors as brand
+tokens:
+
+```yaml
+brand_red: "#F25022"
+brand_green: "#7FBA00"
+brand_blue: "#00A4EF"
+brand_yellow: "#FFB900"
+```
+
+Keep the following rules when changing the palette:
+
+- Keep `background` white unless the presentation requirement explicitly
+  overrides the packaged visual direction.
+- Maintain at least the declared `minimum_contrast_ratio` for text.
+- Do not use the four logo colors for small text on white without checking
+  the actual contrast.
+- Give `brand_yellow` and other low-contrast chart series a direct label plus
+  pattern or marker encoding.
+- Never use color as the only way to communicate status or series identity.
+- Keep categorical charts to the packaged three-series sequence where
+  possible; use pattern, marker, or shape encoding for additional series.
+
+## Change typography and spacing
+
+Update font families only when the target environment has them or the PPTX
+skill can embed or substitute them predictably.
+
+```yaml
+typography:
+  heading_font: "Aptos Display"
+  body_font: "Aptos"
+  title_size_pt: 30
+  body_size_pt: 18
+
+spacing:
+  outer_margin_percent: 6
+  content_gap_percent: 2
+  card_padding_percent: 2
+```
+
+- Keep body text at or above `accessibility.minimum_body_size_pt`.
+- Use percentages for margins and gaps instead of absolute object
+  coordinates.
+- Record required font substitutions in `deviations`.
+
+## Change components and slide patterns
+
+Use only values documented in `design-spec-schema.md`.
+
+```yaml
+components:
+  tables:
+    header_fill: accent_soft
+    header_text: text_primary
+    maximum_rows: 7
+  charts:
+    style: direct-label
+    gridlines: minimal
+    direct_labels_required: true
+    series_outline: background
+```
+
+`slide_patterns` declares supported presentation intents, not PowerPoint
+layout names or coordinates. Add a pattern only when the handoff can describe
+its information structure and the PPTX skill can render it without
+template-specific code in `presentation-planner`.
+
+## Validate an adapted design before handoff
+
+Check all of the following:
+
+- The YAML parses successfully.
+- All top-level keys from `design-spec-schema.md` remain present.
+- Every token reference resolves to a key under `colors`.
+- Text and table-header foreground/background pairs meet the contrast floor.
+- Chart series remain distinguishable without color alone.
+- `id`, `base_template`, and `deviations` describe the adaptation accurately.
+- The PPTX handoff points to the adapted file, not the packaged base file.
+
+If the renderer cannot implement a token or component value, update the
+design spec with an explicit fallback. Do not add PPTX generation code to
+this skill.
+
+## Add a reusable packaged template
+
+When adding a new base template:
+
+1. Add `<template-id>.yaml` under `assets/design-templates/`.
+2. Add the template to the selection table in `SKILL.md`.
+3. Document its intended and unsuitable use cases.
+4. Add the filename to the packed-artifact test in `test/install.test.js`.
+5. Update `CHANGELOG.md`.
+6. Run the repository tests, Markdown lint, YAML schema checks, and contrast
+   checks before committing.

package/.github/skills/presentation-planner/references/design-spec-schema.md

@@ -0,0 +1,72 @@
+# Design specification schema
+
+Each packaged YAML design uses the following stable top-level keys.
+
+| Key | Purpose |
+|---|---|
+| `id` | Unique specification identifier; change it for an adapted deck |
+| `base_template` | Packaged template ID from which the spec was adapted |
+| `intent` | Presentations this design supports |
+| `canvas` | Aspect ratio, dimensions, safe area, and grid |
+| `colors` | Semantic color tokens and chart sequence |
+| `typography` | Font families, sizes, weights, and line spacing |
+| `spacing` | Margins, gaps, and density limits |
+| `components` | Cards, callouts, tables, charts, and diagrams |
+| `slide_patterns` | Supported layout intents, not binary PPTX layouts |
+| `accessibility` | Contrast, minimum type, alt text, and color-use rules |
+| `constraints` | Rules the PPTX skill must not violate |
+| `deviations` | Deliberate differences from the packaged base template |
+
+## Portable component vocabulary
+
+Use only these renderer-independent values unless a deviation explains the
+fallback:
+
+| Field | Allowed values |
+|---|---|
+| `corner_radius` | `none`, `small`, `medium`, `large` |
+| `shadow` | `none`, `subtle`, `medium` |
+| `charts.style` | `direct-label`, `technical`, `analytical` |
+| `charts.gridlines` | `none`, `subtle`, `minimal` |
+| `charts.series_outline` | `none` or an exact key under `colors` |
+| `charts.direct_labels_required` | `true` or `false` |
+| `connector_style` | `simple`, `orthogonal`, `curved` |
+| `cards.border` | `none` or an exact key under `colors` |
+| `tables.header_fill` | `none` or an exact key under `colors` |
+| `tables.header_text` | an exact key under `colors` |
+
+Values that reference a color token must exactly match a key under `colors`,
+for example `accent_soft`, not a display label such as `accent-soft`.
+Do not assume that `accent` text is readable on `accent_soft`; validate the
+actual foreground/background pair against `minimum_contrast_ratio`.
+
+The packaged designs expose Microsoft's four corporate logo colors as
+`brand_red`, `brand_green`, `brand_blue`, and `brand_yellow`. Treat them as
+brand or decorative tokens, not as an automatic categorical chart palette.
+Do not use them for small text on white unless the actual pair passes the
+contrast threshold; `brand_yellow` requires a direct label plus pattern or
+marker encoding on a white canvas.
+
+The packaged categorical `chart_sequence` is intentionally capped at three
+well-separated series: dark Microsoft blue, Microsoft red, and neutral gray.
+When a chart needs more than three series, add pattern, marker, or shape
+encoding instead of appending the remaining logo colors.
+
+`charts.series_outline: background` separates adjacent stacked, pie, or area
+segments; it does not make a light fill visible against the canvas. Use
+direct labels and pattern or marker encoding for light series.
+
+Nested typography and component keys may be omitted when irrelevant. A
+renderer must use its documented defaults for missing optional keys rather
+than treating every packaged template as an identical nested schema.
+
+## Adaptation rules
+
+- Keep the documented top-level keys stable. Optional nested keys may vary by
+  presentation intent.
+- Use brand colors only after assigning semantic roles such as `accent`,
+  `positive`, `warning`, and `critical`.
+- Do not specify absolute object coordinates. Layout engines differ; use
+  proportions, alignment, safe areas, and maximum element counts.
+- Prefer one dominant visual hierarchy per slide.
+- Record all changes from the packaged template under `deviations`.

package/.github/skills/presentation-planner/references/handoff-contract.md

@@ -0,0 +1,49 @@
+# PPTX handoff contract
+
+Use this structure for
+`.presentation/<deck-slug>/pptx-handoff.md`.
+
+## Inputs
+
+- Brief: `<path>/presentation-brief.md`
+- Scenario: `<path>/presentation-scenario.md`
+- Slide outline: `<path>/slide-outline.md`
+- Design specification: `<path>/design-spec.yaml`
+- Source materials: `<paths>`
+
+## Output
+
+- PPTX path: `<path>/<filename>.pptx`
+- Aspect ratio: `<16:9 / 4:3 / custom>`
+- Expected slide count: `<count or range>`
+
+## Rendering requirements
+
+- Preserve slide order and assertion titles.
+- Preserve the approved scenario stages and audience reasoning journey.
+- Require every slide to map to at least one scenario stage; preserve
+  multi-stage mappings recorded with ` / ` in the outline.
+- Treat evidence and citation fields as content requirements.
+- Apply semantic design tokens from `design-spec.yaml`.
+- Add speaker notes where specified.
+- Add alt text or an equivalent description for informative visuals.
+- Do not invent quantitative claims or citations.
+
+## Required visual QA
+
+- Render every slide to an image or thumbnail.
+- Check clipping, overlap, off-canvas objects, font substitution, and
+  unreadable contrast.
+- Check charts for legible labels, units, legends, and source notes.
+- Check diagrams for readable flow direction and connector attachment.
+- Report every deviation from the outline or design specification.
+
+## Completion report
+
+Return:
+
+1. Output path and final slide count
+2. Visual QA result
+3. Missing or substituted assets/fonts
+4. Deviations from the scenario, outline, or design and their reasons
+5. Remaining manual-review items

package/.github/skills/presentation-planner/references/responsibility-boundary.md

@@ -0,0 +1,32 @@
+# Responsibility boundary with the PPTX creation skill
+
+`presentation-planner` and the host's PPTX skill are complementary.
+
+| Concern | presentation-planner | PPTX creation skill |
+|---|---:|---:|
+| Audience, outcome, and decision | Owns | Consumes |
+| Scenario and audience reasoning journey | Owns | Preserves |
+| Storyline and slide sequence | Owns | Preserves |
+| Assertion titles and evidence mapping | Owns | Renders |
+| Design tokens and layout intent | Owns | Implements |
+| `.pptx` binary creation and editing | Never | Owns |
+| python-pptx/PptxGenJS/COM code | Never | Owns |
+| Theme/layout extraction from an existing PPTX | Requests and consumes summary | Owns |
+| Rendering and thumbnails | Never | Owns |
+| Overlap, clipping, and font checks | Defines acceptance criteria | Executes |
+| Speaker notes insertion | Specifies content | Implements |
+
+## Conflict rule
+
+If both skills could act, `presentation-planner` runs first and creates the
+handoff package. The PPTX skill starts only after the planning artifacts are
+complete. For a simple mechanical edit to an existing presentation where
+the storyline and design are unchanged, skip `presentation-planner` and use
+the PPTX skill directly.
+
+## Failure rule
+
+If the PPTX skill cannot implement a requested visual instruction, it must
+report the constraint and proposed fallback. The planning skill may update
+the design spec or slide outline, but it must not work around the constraint
+by manipulating the PPTX binary itself.

package/.github/skills/presentation-planner/references/scenario-templates.md

@@ -0,0 +1,55 @@
+# Presentation scenario templates
+
+A presentation scenario defines the audience's reasoning journey between the
+brief and the slide-by-slide outline. It is not a script and does not repeat
+all slide content. It records the assertions, evidence, transitions,
+objections, and final action that make the deck persuasive and coherent.
+
+## Artifact boundary
+
+| Artifact | Question it answers |
+|---|---|
+| `presentation-brief.md` | Who is the audience, and what outcome is required? |
+| `presentation-scenario.md` | What reasoning journey moves them to that outcome? |
+| `slide-outline.md` | Which slides deliver each assertion and piece of evidence? |
+| `design-spec.yaml` | Which visual system expresses the content? |
+| `pptx-handoff.md` | How must the PPTX skill generate and validate the deck? |
+
+Do not use the scenario as a second slide outline. A scenario stage may span
+several slides, or two stages may share one slide when the argument remains
+clear.
+
+## Choose a template
+
+| Template | Use when | Avoid when |
+|---|---|---|
+| `executive-decision.md` | The audience must approve an option, investment, roadmap, or policy | The goal is purely educational |
+| `technical-briefing.md` | The audience must understand or review architecture and technical behavior | The deck is primarily KPI analysis |
+| `data-report.md` | Findings, trends, research, or experiments must support an action | Credible data is unavailable |
+
+Copy the closest template to
+`.presentation/<deck-slug>/presentation-scenario.md`, then remove stages that
+do not advance the required outcome. Do not add stages or slides merely to
+match the template.
+
+If none fits, create `presentation-scenario.md` from the generic fallback in
+`SKILL.md`, preserving the same stage, audience-question, assertion, evidence,
+transition, and suggested-slide-range fields used by packaged templates.
+
+## Adaptation rules
+
+- Express each stage as an assertion the audience must accept.
+- Record the audience question answered by each stage.
+- Map factual claims to sources or mark them as assumptions.
+- State the transition: why accepting one stage makes the next relevant.
+- Include objections, uncertainty, and trade-offs before the final action.
+- Keep the final decision or call to action singular and testable.
+- Set suggested slide counts only as planning ranges, never quotas.
+
+## Validation
+
+- Reading only stage assertions reconstructs the argument.
+- Every stage changes what the audience knows, believes, or is ready to do.
+- Evidence strength matches the certainty of the assertion.
+- The slide outline maps every slide to a scenario stage.
+- No slide introduces a new conclusion absent from the approved scenario.