@litfamily/litgrok 1.0.13 → 1.0.15

package/.grok/skills/lit-pptx/references/tonalities/paper.md

@@ -0,0 +1,127 @@
+# Paper
+
+Paper is a journal page on a screen. Ink on white, hairlines instead of fills, figures first with
+numbered captions, booktabs tables, and one deep crimson kept for the proposed method. The cover is a
+title page: a heavy rule, the title, a hairline, the authors, the place and the date. Nothing on a
+Paper slide is decoration; every mark is a rule, a figure or a word.
+
+**Choose it** for research talks, thesis defences, technical reviews and written analyses: decks
+built on figures, tables and citations, often with a references slide. **It is wrong** for a sales or
+launch room, where the restraint reads as cold, and for decks that need an agenda, a KPI row, a
+timeline or a process, none of which Paper carries.
+
+## Tokens
+
+| Role | Value |
+|---|---|
+| ground / surface | `#FFFFFF` / `#F5F5F6` |
+| ink / ink-muted / line | `#111418` / `#50565E` / `#C9CDD2` |
+| accent / accent-deep / accent-tint | `#8C1C2B` / `#5E121C` / `#F6E6E8` |
+| field / on-field | `#111418` / `#FFFFFF` |
+| positive / negative | `#1E6B3A` / `#50565E` |
+| chart series | `#8C1C2B`, `#111418`, `#50565E`, `#2E5E8A` (series order, first is the proposed method) |
+| faces | Pretendard Bold for titles and display, Regular for body and numerals |
+| figures | tabular |
+| radius / edge | 0 / border |
+
+Density 10, compact ramp. Variance 5 allows four treatments, which is all Paper has.
+
+**Tables**: booktabs (a heavy rule above the header, a light one under it, a heavy one at the foot),
+no fills, numbers right-aligned and tabular, totals bold. **Charts**: hairline gridlines, direct
+labels, colour by series order with the proposed method first, no annotation. **Pictures** never
+bleed, crop or take a frame.
+
+## Titles by role
+
+| Role | Default | Also allowed |
+|---|---|---|
+| content | `top-rule` | `side-rail` (text-column) |
+| data | `top-rule`; a comparison is a ruled table under `top-rule` (the pack's `structure`, kept even when the deck already leans on it) | `side-rail`, `bottom-anchor` |
+| data-takeaway | `bottom-anchor` | `top-rule`, `side-rail` |
+| image | `bottom-anchor` | `top-rule`, `side-rail` |
+| statement | `statement` | `top-rule` (quote) |
+| definition | `side-rail` | `top-rule` |
+| reference | `top-rule` | — |
+
+The top-rule title rests on a full-width hairline; Paper has no short accent bar.
+
+## Families and variants
+
+figure-academic, figure-pair, method, chart-insight, full-chart, table-insight, comparison, quote,
+statement, text-column, references-appendix.
+
+- Covers: `cover-index` (the title beside the part list; needs two or more sections, since Paper has
+  no agenda family), `cover-typographic` (the journal title page), `cover-split-image`.
+- Sections: `section-rule` (an index page with this part marked), `section-field`.
+- Closings: `closing-summary-list` (findings, limits, next experiment with owner and date),
+  `closing-ask`.
+- Display: statements sit between two hairlines; big-number panels are outlined in ink; closings set
+  the next step under a rule.
+
+Decoration: hairline rules and box outlines only.
+
+## Do
+
+- Number every figure and table and give each caption its condition and source: "Figure 2. Logger
+  positions at k = 12, test district (sample)".
+- Use `figure-academic` for a figure that needs reading: observation, limitation, implication.
+- Reserve crimson for one thing across the whole talk: the proposed method's series, row or label.
+- Put the method on a `method` slide with the objective and each term defined.
+- End with references and the definitions the talk relies on, eight to ten lines.
+
+## Avoid
+
+- The short accent bar under a title.
+- Coloured card fills.
+- Figures without numbered captions.
+- The accent on anything other than the proposed method.
+- Bullets longer than about 60 characters beside a figure under a bottom title; that column is three
+  grid columns wide.
+
+## Two worked slides
+
+Both are trimmed for reading. Complete slides of the same kind in the example decks carry the
+extra rows, groups and takeaways that fill a compact page and pass the gate.
+
+A results table with the reading beside it:
+
+```markdown
+---
+layout: table-insight
+
+## Detection and localisation by logger budget
+
+| Loggers (k) | Detected | Top-3 segment hit | Median error |
+|---|---|---|---|
+| 4 | 71 % | 38 % | 610 m |
+| 8 | 84 % | 55 % | 390 m |
+| 12 | 91 % | 68 % | 240 m |
+| 16 | 94 % | 74 % | 190 m |
+| 24 | 96 % | 79 % | 150 m |
+
+> Table 1. Results over 6,800 simulated leaks, night demand (sample data)
+
+- Gains flatten after k = 16
+- At k = 12 the median search radius is 240 m
+- Source: sample simulation study, October 2026 (sample)
+---
+```
+
+A numbered figure with its reading:
+
+```markdown
+---
+layout: figure-academic
+
+## 시험 관망과 압력계 배치
+
+![압력계 12대 배치, 시험 구역 (예시) | 출처: 예시 그림](assets/example-b.png)
+
+- **관찰** 절반이 구역 중심이 아닌 긴 송수관 위에 놓인다
+- **한계** 야간 수요 기준으로 맞춘 배치다
+- **의미** 접근이 쉬운 지점을 골라도 정확도 손실이 작다
+- 출처: 예시 수리 모형, 2025년 소화전 시험으로 보정 (예시)
+---
+```
+
+Full deck: `examples/03-research-talk-paper-en.md`.

package/.grok/skills/lit-pptx/references/tonalities/signal.md

@@ -0,0 +1,118 @@
+# Signal
+
+Signal is for a room that listens: a pitch, a launch, a proposal presented live. One idea per slide,
+set large on white, with a single hot red that belongs to the subject. Titles take display size,
+figures stand on red panels, and a statement page is allowed for a real quotation. The density is
+still 10: the large title is offset by full evidence underneath.
+
+**Choose it** for pitches and launches presented in person, and when content slides are short
+(around 40 Korean glyphs or 80 Latin characters of argument each) but every slide still has figures
+behind it. **It is wrong** when the audience studies the file afterwards, when tables make up most of
+the content (Signal has no `ledger-table` and no dashboard), and when the deck needs an agenda, a
+timeline or long itemised text, none of which the pack carries.
+
+## Tokens
+
+| Role | Value |
+|---|---|
+| ground / surface | `#FFFFFF` / `#F4F4F5` |
+| ink / ink-muted / line | `#15131A` / `#55525C` / `#D4D4D8` |
+| accent / accent-deep / accent-tint | `#C8361A` / `#6E1A0C` / `#FBE7E2` |
+| field / on-field | `#C8361A` / `#FFFFFF` |
+| positive / negative | `#1E7A3F` / `#15131A` (a loss keeps the ink and carries its ▼) |
+| chart series | `#C8361A`, `#15131A`, `#6B6870`, `#2F6F8F` |
+| faces | Pretendard Bold for display, titles and figures; Regular for body and labels |
+| figures | proportional |
+| radius / edge | 0 / fill |
+
+Density 10, compact ramp (title 26, display 36). Variance 6 allows four treatments; the pack has four.
+
+**Tables**: open style, no header fill, a rule above and below, numbers right-aligned, totals bold;
+the row whose first cell appears in the title is tinted red-pale as the row the slide is about.
+**Charts**: no gridlines, direct labels, the red on the highlighted series, annotations allowed.
+**Pictures** may bleed and crop.
+
+## Titles by role
+
+| Role | Default | Also allowed |
+|---|---|---|
+| content | `top-plain-large` | `top-rule`, `bottom-anchor` (by family) |
+| data | `top-rule` | `top-plain-large`, `bottom-anchor` |
+| data-takeaway | `top-plain-large` | `top-rule`, `bottom-anchor` |
+| sequence | `top-rule` | `top-plain-large` |
+| image | `bottom-anchor` | `top-plain-large`, `top-rule` |
+| statement | `statement` | — |
+
+`top-plain-large` sets the title at 36 pt in two lines of about 20 Korean glyphs; write titles that
+fit, or the engine moves the slide to `top-rule`.
+
+## Families and variants
+
+statement, big-number, image-split, asymmetric-feature, process, kpi-row, chart-insight, full-chart,
+comparison, table-insight, quote.
+
+- Covers: `cover-numeral` (a year or real figure above the title), `cover-typographic` (drawn as a
+  drench: the whole page red, the title low), `cover-split-field` (half the page red).
+- Sections: `section-field`, `section-numeral`.
+- Closings: `closing-statement` (one sentence, no table), `closing-ask` (the ask as action rows with
+  the next step on a red band). Use `closing-ask` whenever there is money, a decision or a date.
+- Display: statements stand open on white; big numbers sit on the red field with white figures.
+
+Decoration: colour field, hairline rules, real numerals. No cards.
+
+## Do
+
+- Write the title as the topic, then let the first takeaway say the claim in one line.
+- Use `big-number` for two to four related figures, each with its basis; the red panel carries them.
+- Put the product on an `image-split` or `asymmetric-feature` early, so the room sees the thing.
+- Keep lists to four items; a fifth goes to the next slide or into a table.
+- Use `comparison` with matching criteria labels for "today versus with us".
+
+## Avoid
+
+- Red for losses; a loss is ink with ▼.
+- More than two lines of display text on any slide.
+- Cards and boxed bullet groups.
+- A statement slide that holds a claim; claims go in the body of a content slide.
+
+## Two worked slides
+
+Both are trimmed for reading. Complete slides of the same kind in the example decks carry the
+extra rows, groups and takeaways that fill a compact page and pass the gate.
+
+Pilot figures on the red panel, with their evidence:
+
+```markdown
+---
+layout: big-number
+
+## 시범 운영 6개월 핵심 지표
+
+| 폐기 비율 변화 | 유료 전환율 | 월 이탈률 |
+|---|---|---|
+| −3.3%p | 83% | 1.8% |
+| 8.9% → 5.6% | 시범 12곳 중 10곳 | 유료 전환 후 3개월 평균 |
+
+- 시범 매장 한 곳당 월 폐기 금액이 평균 47만 원 줄었다
+- 이탈한 매장 두 곳은 모두 폐업이 사유였다
+- 출처: 예시 스타트업 시범 운영 기록, 2026년 4-9월 (예시)
+---
+```
+
+A short process, each step saying what happens:
+
+```markdown
+---
+layout: process
+
+## From order to restock suggestion
+
+- **1. Sales sync** menu sales arrive from the till every 15 minutes
+- **2. Stock deduction** recipes convert each sale into ingredient use
+- **3. Count correction** the closing count fixes the gap between book and shelf
+- **4. Order suggestion** tomorrow's bookings and weekday patterns set the quantity
+- Source: sample service design document v0.9, September 2026 (sample)
+---
+```
+
+Full deck: `examples/01-pitch-signal-ko.md`.

package/.grok/skills/lit-pptx/references/tonalities/studio.md

@@ -0,0 +1,123 @@
+# Studio
+
+Studio is an editorial spread. The 12-column grid shows through hairlines between columns, titles
+take a side rail or open a page at display size, splits are asymmetric, real figures run on tinted
+panels, and a dark ochre points at one thing per slide. It mixes the most title treatments of any
+pack, so a deck feels laid out page by page rather than filled from one template.
+
+**Choose it** for narratives that combine pictures and figures: a pitch for a physical product, a
+portfolio, a public lecture, an annual story. **It is wrong** for dense data reviews, where its
+open layouts starve tables (Studio has no table family), and for read-alone briefings.
+
+## Tokens
+
+| Role | Value |
+|---|---|
+| ground / surface | `#FFFFFF` / `#F2F2F0` |
+| ink / ink-muted / line | `#141414` / `#525252` / `#D2D2CE` |
+| accent / accent-deep / accent-tint | `#8A5A00` / `#4D3200` / `#F5ECD9` |
+| field / on-field | `#141414` / `#FFFFFF` |
+| positive / negative | `#1E7A3F` / `#B3261E` |
+| chart series | `#8A5A00`, `#141414`, `#525252`, `#3B5F7F` |
+| faces | Pretendard Bold for titles, display and figures; Regular for body |
+| figures | proportional |
+| radius / edge | 0 / fill |
+
+Density 10, compact ramp. **Variance 8 allows all five treatments**, and the engine uses them.
+
+**Tables** (inside KPI rows and timelines): open style, a 2 pt rule under the header, no fills,
+numbers right-aligned. **Charts**: no gridlines, direct labels, the ochre on the highlighted series,
+annotations allowed. **Pictures** bleed and crop freely, with no frame.
+
+## Titles by role
+
+| Role | Default | Also allowed |
+|---|---|---|
+| content | `side-rail` | `top-plain-large` (text-two-column takes only this) |
+| data | `top-plain-large` | `side-rail`, `bottom-anchor` |
+| data-takeaway | `side-rail` | `bottom-anchor`, `top-plain-large` |
+| sequence | `side-rail` in the pack map | the timeline takes `top-plain-large` or `bottom-anchor` |
+| image | `side-rail`: the picture across columns 5-12, its facts in the rail under the title | `top-plain-large`, `bottom-anchor`, `overlay` (image-full only) |
+| statement | `statement` | — |
+
+## Families and variants
+
+asymmetric-feature, big-number, image-split, image-full, photo-grid, text-two-column, chart-insight,
+kpi-row, timeline, comparison, statement.
+
+- Covers: `cover-split-image` (the title beside the deck's first picture), `cover-rail`,
+  `cover-numeral` (a year in the title or date, e.g. "포트폴리오 2026").
+- Sections: `section-numeral`, `section-rail`. A single section with no agenda draws no numeral and
+  sets its title as a statement over the slides it opens.
+- Closings: `closing-contact-split` (action rows beside a dark field holding each amount or date, the
+  next step as a band meeting it), `closing-summary-list`.
+- Display: a statement stands between two hairlines on the open page (a short rail beside it stood
+  empty); big-number panels use the ochre
+  tint; closings put the next step on a dark band.
+
+Decoration: column hairlines, real numerals, rail fill, colour field, caption band.
+
+## Captions
+
+The cover borrows the deck's first picture with its caption, and `image-full` sets its caption on a
+panel, where the gate reads caption and source. Leave the number out of the caption: the engine
+numbers figures in deck order.
+
+## Do
+
+- Let large figures be real figures: a `big-number` panel of two or three values with their basis.
+- Use asymmetric splits: `asymmetric-feature` with five short bullets beside a large picture.
+- Give `text-two-column` four to six groups with two or three sub-points each; flat bullets leave the
+  page half empty at density 10 (example 10).
+- Alternate full-bleed pages with split pages and a grid of three.
+- Close with `closing-contact-split` when there is money to ask for, keyed by the amount column.
+
+## Avoid
+
+- Large numerals that are not real figures.
+- Column hairlines running through text.
+- Two side-rail slides with the same split in a row.
+- Centred body text.
+
+## Two worked slides
+
+Both are trimmed for reading. Complete slides of the same kind in the example decks carry the
+extra rows, groups and takeaways that fill a compact page and pass the gate.
+
+A feature told by one large picture and a narrow column:
+
+```markdown
+---
+layout: asymmetric-feature
+
+## A refill station inside a neighbourhood grocer
+
+![Station with six products in 0.9 m of shelf width (sample) | Source: sample photo](assets/example-a.png)
+
+- **What it is** a self-service dispenser for six cleaning products
+- **How it works** customers bring any bottle; the scale reads the tare
+- **Price** 25-35 % below the same product in a new bottle
+- **Store share** 18 % of refill revenue goes to the grocer
+---
+```
+
+Figures as a panel with their evidence:
+
+```markdown
+---
+layout: big-number
+
+## 스테이션당 단위 경제성
+
+| 월 매출 | 월 공헌이익 | 회수 기간 |
+|---|---|---|
+| 119만 원 | 31만 원 | 19개월 |
+| 월 412회 리필 기준 | 매장 몫과 재고 차감 후 | 설치비 590만 원 |
+
+- 9월 시범 평균이며 전망치가 아니다
+- 월 500회 리필이면 회수 기간은 14개월로 줄어든다
+- 출처: 예시 시범 운영 손익, 2026년 9월 (예시)
+---
+```
+
+Full decks: `examples/09-pitch-studio-en.md`, `examples/10-image-led-studio-ko.md`.

package/.grok/skills/lit-pptx/scripts/compile-deck.js

@@ -88,7 +88,7 @@ function compileDeck(source) {
 // export exists to prevent.
 const BUNDLED_FONTS = [
   { match: /Pretendard/i, dir: "pretendard-font/public/static",
-    files: ["PretendardGOV-Regular.otf", "PretendardGOV-Bold.otf"] },
+    files: ["Pretendard-Regular.otf", "Pretendard-Bold.otf"] },
   { match: /에이투지체/, dir: "fonts/a2z-font",
     files: ["A2Z-Regular.otf", "A2Z-Bold.otf"] },
 ];
@@ -144,11 +144,23 @@ async function resolveAndRender(ast, templateName, outputs, options = {}) {
     throw new Error("layout-resolver module not available. Cannot resolve layouts.");
   }
 
-  const templateObj = templateRegistry.loadTemplate(templateName);
+  // A tonality (flag or frontmatter) is a design direction read from a pack; without one the named
+  // template loads as a legacy pack and keeps its own look.
+  const meta = (ast.deck && ast.deck.metadata) || {};
+  const tonality = options.tonality || meta.tonality || null;
+  const templateObj = tonality
+    ? templateRegistry.loadTonality(tonality, { density: meta.density, variance: meta.variance, canvas: meta.canvas, faces: options.faces || meta.faces })
+    : templateRegistry.loadTemplate(templateName);
+  if (tonality) {
+    const d = templateObj.pack.dials;
+    console.log(`Tonality ${templateObj.pack.id} · density ${d.density} · variance ${d.variance} · ${d.canvas} ${templateObj.pack.grid.name} grid` +
+      (templateName && templateName !== tonality ? ` (template ${templateName} not used)` : ""));
+  }
+  const can = (capability) => templateRegistry.hasCapability(templateObj, capability);
 
-  // Font override (azure-style templates): swap the whole font system regardless
-  // of which template was chosen. Applied before accent (independent of colour).
-  if (options.font && templateObj.template && templateObj.template.render_style === "azure") {
+  // Font override (templates with the font-swap capability): swap the whole font system
+  // regardless of which template was chosen. Applied before accent (independent of colour).
+  if (options.font && can("font-swap")) {
     const { applyFont, KEYS } = require("./lib/font-map");
     if (KEYS.includes(options.font)) {
       applyFont(templateObj, options.font);
@@ -159,10 +171,10 @@ async function resolveAndRender(ast, templateName, outputs, options = {}) {
   const resolved = layoutResolver.resolve(ast, templateObj);
   if (options.sourceDir) resolved.sourceDir = options.sourceDir;
 
-  // Custom accent recolor (azure-style templates only): derive a WCAG-safe
+  // Custom accent recolor (templates with the recolor capability): derive a WCAG-safe
   // palette from the accent hex, override template tokens + hardcoded decoration
   // colors, and regenerate the gradient circle PNGs in the new hue.
-  if (options.accent && templateObj.template && templateObj.template.render_style === "azure") {
+  if (options.accent && can("recolor")) {
     const { derivePalette, defaultToDerivedMap } = require("./lib/derive-palette");
     const { genGradientAssets } = require("./lib/gen-gradient-assets");
     const os = require("os");
@@ -200,11 +212,11 @@ async function resolveAndRender(ast, templateName, outputs, options = {}) {
     console.log(`Accent ${options.accent} → primary ${derived.primary} (white-contrast ${derived._ratios.whiteOnPrimary}:1)`);
   }
 
-  // Blurred gradient-mesh background (azure-style): ambient wash on cover/closing/
+  // Blurred gradient-mesh background (mesh-background capability): ambient wash on cover/closing/
   // content (light) and a deep textured wash on section dividers (dark). Uses the
   // ACTIVE palette (so it respects --accent). The dark mesh sits ABOVE the base
   // section fill rect, so qa_deck still resolves the (dark) fill behind white text.
-  if (options.bg === "mesh" && templateObj.template && templateObj.template.render_style === "azure") {
+  if (options.bg === "mesh" && can("mesh-background")) {
     const { genMeshBg } = require("./lib/gen-bg");
     const os = require("os");
     const dims = templateObj.template.dimensions || {};
@@ -278,8 +290,36 @@ if (require.main === module) {
     }
     process.exit(0);
   }
+  if (args[0] === "--list-tonalities") {
+    const reg = require("./lib/template-registry");
+    for (const id of reg.listTonalities()) {
+      const p = reg.loadPack(id);
+      console.log(`${id} — ${p.intent} [density ${p.density}, variance ${p.variance}; ${p.treatments.join(", ")}]`);
+    }
+    for (const name of reg.listTemplates()) console.log(`${name} (legacy template)`);
+    process.exit(0);
+  }
   if (args[0] === "--list-layouts" && args[1]) {
     const reg = require("./lib/template-registry");
+    if (reg.listTonalities().includes(String(args[1]).toLowerCase())) {
+      // A tonality lists its families with the titles each can take there, and its variants.
+      const G = require("./lib/grid-resolver");
+      const p = reg.loadPack(args[1]);
+      console.log(`${p.id} — ${p.intent}`);
+      console.log(`treatments: ${p.treatments.join(", ")}`);
+      console.log("layout families:");
+      for (const f of p["layout-families"]) {
+        console.log(`  ${f} [${G.familyAllows(f).filter((t) => p.treatments.includes(t)).join(", ")}]`);
+      }
+      console.log(`covers: ${p.covers.join(", ")}`);
+      console.log(`sections: ${p.sections.join(", ")}`);
+      console.log(`closings: ${p.closings.join(", ")}`);
+      process.exit(0);
+    }
+    if (!reg.listTemplates().includes(args[1])) {
+      console.error(`Unknown tonality or template "${args[1]}". Tonalities: ${reg.listTonalities().join(", ")}; legacy templates: ${reg.listTemplates().join(", ")}`);
+      process.exit(1);
+    }
     const t = reg.loadTemplate(args[1]);
     const layouts = (t.mapping && t.mapping.layouts) || {};
     const caps = (t.capabilities && t.capabilities.supported_blocks) || {};
@@ -295,10 +335,13 @@ if (require.main === module) {
   if (args.length === 0) {
     console.error("Usage:");
     console.error("  node compile-deck.js --list-templates");
-    console.error("  node compile-deck.js --list-layouts <template>");
+    console.error("  node compile-deck.js --list-tonalities");
+    console.error("  node compile-deck.js --list-layouts <template or tonality>");
     console.error("  node compile-deck.js <input.md> [--ast out.json]");
     console.error("  node compile-deck.js <input.md> --template <name> --html out.html");
     console.error("  node compile-deck.js <input.md> --template <name> --pptx out.pptx");
+    console.error("  node compile-deck.js <input.md> --tonality <id> --pptx out.pptx   (or tonality: in the frontmatter)");
+    console.error("  node compile-deck.js <input.md> --tonality <id> --faces a2z --pptx out.pptx   (A2Z faces on request; Pretendard by default)");
     console.error("  node compile-deck.js <input.md> --template <name> --ast out.json --html out.html --pptx out.pptx");
     console.error("  node compile-deck.js <input.md> --template <name> --export-viz-context ctx.json");
     process.exit(1);
@@ -310,10 +353,12 @@ if (require.main === module) {
   let htmlPath = null;
   let pptxPath = null;
   let embedFonts = false;
+  let facesFlag = null;
   let accent = null;
   let font = null;
   let bg = null;
   let vizContextPath = null;
+  let tonalityFlag = null;
 
   for (let i = 1; i < args.length; i++) {
     if (args[i] === "--embed-fonts") { embedFonts = true; continue; }
@@ -321,6 +366,8 @@ if (require.main === module) {
     if (args[i] === "--font" && args[i + 1]) { font = args[i + 1]; i++; continue; }
     if (args[i] === "--bg" && args[i + 1]) { bg = args[i + 1]; i++; continue; }
     if (args[i] === "--export-viz-context" && args[i + 1]) { vizContextPath = args[i + 1]; i++; continue; }
+    if (args[i] === "--tonality" && args[i + 1]) { tonalityFlag = args[i + 1]; i++; continue; }
+    if (args[i] === "--faces" && args[i + 1]) { facesFlag = args[i + 1]; i++; continue; }
     if (args[i] === "--ast" && args[i + 1]) {
       astPath = args[i + 1];
       i++;
@@ -339,13 +386,14 @@ if (require.main === module) {
     }
   }
 
-  // If --html or --pptx is requested, --template is required
-  if ((htmlPath || pptxPath || vizContextPath) && !templateName) {
-    console.error("Error: --template is required when using --html, --pptx or --export-viz-context");
+  const source = fs.readFileSync(inputPath, "utf-8");
+
+  // A render needs a design: --template, --tonality, or a tonality: line in the frontmatter.
+  const frontTonality = (source.match(/^---[ \t]*\n([\s\S]*?)\n---/) || ["", ""])[1].match(/^tonality:[ \t]*(\S+)/m);
+  if ((htmlPath || pptxPath || vizContextPath) && !templateName && !tonalityFlag && !frontTonality) {
+    console.error("Error: --template or --tonality (or tonality: in the frontmatter) is required when using --html, --pptx or --export-viz-context");
     process.exit(1);
   }
-
-  const source = fs.readFileSync(inputPath, "utf-8");
   const sourceDir = path.dirname(path.resolve(inputPath));
 
   (async () => {
@@ -374,12 +422,12 @@ if (require.main === module) {
       }
 
       // Resolve and render if template + output formats specified
-      if (templateName && (htmlPath || pptxPath || vizContextPath)) {
+      if (htmlPath || pptxPath || vizContextPath) {
         await resolveAndRender(ast, templateName, {
           html: htmlPath,
           pptx: pptxPath,
           vizContext: vizContextPath,
-        }, { sourceDir, accent: effectiveAccent, font: effectiveFont, bg: effectiveBg });
+        }, { sourceDir, accent: effectiveAccent, font: effectiveFont, bg: effectiveBg, tonality: tonalityFlag, faces: facesFlag });
 
         // Optional: embed bundled fonts into the PPTX for a self-contained deck.
         if (embedFonts && pptxPath) {