@litfamily/litgrok 1.0.13 → 1.0.15

package/.grok/skills/lit-pptx/references/direction-step.md

@@ -0,0 +1,211 @@
+# Direction step
+
+A deck's look is decided once, before the first slide is written, and it is decided as data: one of
+the eight tonality packs in `templates/tonalities/<id>/pack.yaml`. The pack fixes the palette roles,
+the type ramp, the title treatments each slide role may take, the layout families the engine will
+draw, the cover, section and closing variants, and the density and variance dials. Skipping this
+step leaves the engine without a design and the deck without a reason for looking the way it does.
+
+The step produces three things: a direction card in the build log, a `tonality:` line in the deck
+frontmatter, and two or three sentences in the reply that name the choice and two alternatives. A
+bare request (`lit 발표자료 만들어줘`, "make me a deck on X") asks the user nothing. The skill
+infers what it needs, writes the inference on the card, and lets the user correct it afterwards.
+
+## What to settle first
+
+Write down four facts. Take them from the brief when it says them and infer them from the request
+and the sources when it does not.
+
+| Fact | Question it answers | Typical inference |
+|---|---|---|
+| Deck type | What job does the deck do? | "투자 유치" → pitch; "분기 실적" → business review; "주간 보고" → status update |
+| Setting | Who looks at it, where, for how long? | a board at a desk, a hall with a stage screen, a class reviewing the file later |
+| Delivery | Presented live, read alone, or both? | "미리 배포", "보고서형", "circulate" → read; "keynote", "demo day" → presented |
+| Language | Korean, English or mixed? | the language of the request, unless the sources or the user say otherwise |
+
+Pretendard Regular and Bold are the only faces this skill ships. Every pack draws with them, so the
+direction never depends on a font the machine might lack. Hierarchy comes from size, weight, colour
+and placement.
+
+## Candidates by deck type
+
+Start from the row for the deck type. The first name is the default when no signal below moves it.
+
+| Deck type | First choice | Second | Third, and when |
+|---|---|---|---|
+| Pitch (투자·제안) | signal | studio | atlas, when the product is a physical thing to show |
+| Business review (실적 보고) | ledger | gazette, when circulated in Korean before the meeting | night, when shown on a stage screen |
+| Research talk (연구 발표) | paper | night, for a keynote hall | chalk, for a tutorial |
+| Lecture (강의·교육) | chalk | paper | studio, for a public lecture |
+| Data-heavy review (데이터 리뷰) | night | ledger | paper, for a written analysis |
+| Image-led (제품·현장·포트폴리오) | atlas | studio | signal, for a launch |
+| Korean briefing (보고서형 덱) | gazette | ledger | — |
+| Status update (주간·월간 보고) | ledger | gazette | night |
+
+## Count the outline, then reorder
+
+Draft the outline before choosing: one line per slide with its message and the visual it needs (a
+table, a chart, a picture, a list, a sequence). Then count. Apply the rows below from top to bottom;
+when two packs tie, the deck-type order breaks the tie, so the same outline always yields the same
+choice.
+
+| Signal | Fires when | Effect |
+|---|---|---|
+| User's choice | the brief or an earlier turn names a tonality | use it, still write the card |
+| Named template | the brief names an enrolled template such as AZURE-PRO | use that template, offer two tonalities as alternatives |
+| Read, not presented | the brief says the file is sent ahead or filed | gazette (Korean) or ledger (any language) moves to first |
+| Tables | 30 % or more of content slides hold a table | ledger and gazette up one place |
+| Charts | 30 % or more hold a chart | ledger, night and paper up one place |
+| Pictures | 30 % or more hold a photo or screenshot | atlas and studio up one place; gazette down one |
+| Long bodies | over about 150 Korean glyphs or 300 Latin characters per content slide | gazette and ledger up; signal down |
+| Short bodies | under about 40 Korean glyphs or 80 Latin characters per content slide | signal and studio up; density stays 10 |
+| Citations | numbered references, DOIs or a references slide | paper up one place |
+| Teaching structure | definitions, a formula, or a sequence of three or more steps taught in order | chalk up one place, paper up one |
+| Dark room | keynote, stage, demo day | night up one place |
+| Coverage gap | a pack has no family for a slide the outline needs | drop that pack |
+
+The coverage row decides more often than it seems. Read `--list-layouts <id>` against the outline:
+
+| Pack | Has no family for |
+|---|---|
+| ledger | pictures (no image family) |
+| signal | agenda, timeline, running text |
+| atlas | tables, charts |
+| chalk | charts, KPI rows, timelines |
+| paper | agenda, KPI rows, timelines, process steps |
+| gazette | charts, pictures |
+| studio | tables |
+| night | tables (KPI rows and charts only), pictures, running text |
+
+A ten-slide deck with four charts cannot be a chalk or gazette deck, however well the rest fits. A
+deck with a 2×2 option matrix needs ledger or gazette.
+
+**Worked case.** A Korean monthly status update built from a project tracker, eleven slides. The
+type gives ledger, gazette, night. Three of nine content slides hold a table (33 %), so ledger and
+gazette each move up one: no change in order. Bodies average 170 glyphs, so the long-body row fires
+for both again. The brief says "월간 보고서로 배포", so the read row puts gazette first. The outline
+has no chart, which costs gazette nothing. Result: gazette; alternatives ledger and night. Example
+`12-status-update-gazette-ko.md` is a deck of this kind.
+
+## The direction card
+
+The card records the decision and why. Fill every field; a build that cannot name its tonality and
+its reason stops and asks instead of guessing a look.
+
+```text
+Direction card
+  Deck type        status update (월간 보고), read before the monthly steering meeting
+  Setting          eight executives, on laptops and printed, about ten minutes each
+  Language         Korean
+  Tonality         gazette        alternatives: ledger, night
+  Reason           read rather than presented; 33 % table slides; bodies near 170 glyphs
+  Signals          read-not-presented, tables, long bodies
+  Dials            density 10, variance 4 (pack defaults)
+  Titles by role   content band · data top-rule · data-takeaway side-rail · sequence kicker-numeral
+  Families         cover-index, agenda, summary-box-list, ledger-table, table-insight, section-rule,
+                   text-column, matrix-2x2, timeline, closing-ask
+  Wrong if         the deck is presented to a room; ledger's top titles and KPI rows suit that better
+```
+
+The "wrong if" line names the fact that would overturn the choice. A reviewer checks it first. If it
+turns out true, rebuild under the alternative it names and update the card.
+
+**Dials.** Density (1-10) and variance (1-10) start at the pack defaults: density 10 in every pack,
+variance between 4 (gazette) and 8 (studio). The skill may move either dial by up to 2 on its own and
+records the move on the card. A larger move needs the user's word. Lower density to 8 for a deck shown
+to a large room; raise variance when the deck is long and its slide jobs repeat. Variance under 4 is
+for a user who asks for a uniform deck. Set the dials in the frontmatter (`density: 8`,
+`variance: 6`) so the source carries the decision. `density-and-fill.md` says what each step changes.
+
+**Titles and families.** The role-to-title map comes straight from the pack's sheet in
+`references/tonalities/`; each outline line gets one family from the pack's own list. The engine may draw a slide under another allowed title when the body fills
+better there, and the compile log says so.
+
+## Say it in the reply
+
+Name the tonality, the reason, and the two alternatives in plain words, in the user's language:
+
+> gazette로 만들었습니다. 회의 전에 읽는 월간 보고이고 표가 슬라이드의 3분의 1을 넘어서입니다.
+> 발표 화면에 띄운다면 ledger, 어두운 회의실이라면 night도 맞습니다.
+
+> Built in ledger: the deck is a weekly status read on screen, and a third of its slides are tables.
+> Gazette fits if it circulates in Korean; night fits a stage screen.
+
+Keep the sentences short. The card stays in the build log; the reply carries only the decision.
+
+## Build log
+
+Write the log beside the source. It is working evidence, delivered only when the user asks for the
+audit trail.
+
+```text
+deck.md          source, with tonality: in the frontmatter
+deck.build.md    direction card, compile output (note:, variety:, fill:, Treatments: lines), gate JSON summary
+deck.pptx        compiled deck
+```
+
+Compile and gate from the project root:
+
+```bash
+node .grok/skills/lit-pptx/scripts/compile-deck.js deck.md --pptx deck.pptx
+node .grok/skills/lit-pptx/scripts/run.mjs qa_deck.py deck.pptx
+```
+
+The first line of the compile output repeats the direction (`Tonality gazette · density 10 ·
+variance 4 · 16:9 compact grid`); paste it into the log under the card.
+
+## Comparing looks
+
+When the user asks to see options, or says the look is open ("어떤 느낌이 좋을지 모르겠어요",
+"show me a few styles"), build the cover and the first two content slides under the chosen pack and
+the two alternatives. Keep content and order identical; change only the `tonality:` line.
+
+```bash
+for t in gazette ledger night; do
+  sed "s/^tonality: .*/tonality: $t/" strip.md > "strip-$t.md"
+  node .grok/skills/lit-pptx/scripts/compile-deck.js "strip-$t.md" --pptx "strip-$t.pptx"
+done
+```
+
+If `soffice` is available, convert each strip to PDF and show the three rows of three pages. If it
+is not, say the comparison is unrendered and describe each strip from its pack sheet. The user's
+pick becomes the card's reason ("chosen from the comparison"); then build the full deck.
+
+## Enrolled templates
+
+The templates in `templates/enrolled/` keep their single fixed look. `--list-tonalities` lists them
+as legacy templates after the eight packs. Use one only when the user names it or an existing source
+already says `template:`. The card names the template, the reply still offers two tonalities, and
+the gate reports its variety and band checks as advisories, because a named template asks for one
+look on purpose.
+
+## Mistakes this step prevents
+
+- Choosing by topic ("a startup, so signal") without counting the outline.
+- A reply that names one look, or none.
+- A reason that restates the deck type instead of naming the signals.
+- A pack that cannot draw a slide the outline needs; the compile prints `note: slide N: <family> is
+  not a <pack> layout family`, and the fix is another family or another pack.
+- Moving a dial by three or more without asking.
+- Swapping the tonality after the build without updating the card and the reply.
+
+## Example decks
+
+Twelve complete decks live in `examples/`, each verified to compile and pass the gate under its
+pack. Open the one whose deck type and language match the job before drafting. The picture slides name `assets/example-a.png`, `assets/example-b.png` and
+`assets/example-c.png`; put real images at those paths, or change the paths, before compiling.
+
+| File | Deck type | Tonality | Alternatives |
+|---|---|---|---|
+| `01-pitch-signal-ko.md` | pitch | signal | studio, atlas |
+| `02-business-review-ledger-ko.md` | business review | ledger | gazette, night |
+| `03-research-talk-paper-en.md` | research talk | paper | night, chalk |
+| `04-lecture-chalk-ko.md` | lecture | chalk | paper, studio |
+| `05-data-review-night-en.md` | data-heavy review | night | ledger, paper |
+| `06-image-led-atlas-en.md` | image-led field report | atlas | studio, signal |
+| `07-briefing-gazette-ko.md` | Korean briefing | gazette | ledger |
+| `08-status-update-ledger-en.md` | status update | ledger | gazette, night |
+| `09-pitch-studio-en.md` | pitch for a physical product | studio | signal, atlas |
+| `10-image-led-studio-ko.md` | image-led portfolio | studio | atlas, signal |
+| `11-business-review-night-en.md` | business review on a stage screen | night | ledger, gazette |
+| `12-status-update-gazette-ko.md` | status update, circulated in Korean | gazette | ledger, night |

package/.grok/skills/lit-pptx/references/layout-families.md

@@ -0,0 +1,193 @@
+# Layout families
+
+Each slide does one job, and each job has a shape the engine knows how to draw: that shape is a
+layout family. You write its name after `layout:`; the pack then supplies the titles it may take and
+the look of its tables, charts and rules. There are 28 content families and 20 cover, section and closing variants. No pack
+carries all of them. Each pack lists the ones that suit its character, and a slide that asks for a
+family outside that list is drawn with the family's own geometry and a `note:` line, which is a
+signal to change the family or the pack.
+
+Choose the family from what the slide must do, never from what the previous slide used. Variety in
+a deck comes from slides doing different jobs; the gate's OF-111 check reads the compiled file and
+fails a deck whose content slides share one composition too often.
+
+List what a pack offers before writing:
+
+```bash
+node .grok/skills/lit-pptx/scripts/compile-deck.js --list-tonalities
+node .grok/skills/lit-pptx/scripts/compile-deck.js --list-layouts gazette
+```
+
+The second command prints each family with the titles it may take under that pack, then the cover,
+section and closing variants.
+
+## Content families
+
+| Family | Job | What the source gives it | Packs |
+|---|---|---|---|
+| `text-column` | itemised text that keeps a reading measure | `- **head** text` lines with `(1)` `(2)` sub-points | atlas, chalk, gazette, paper |
+| `text-two-column` | a longer itemised body split in two | four to six bold-headed groups; the engine splits at a group boundary | gazette, ledger, studio |
+| `summary-box-list` | a boxed conclusion over its evidence | `::: key-message` (one or two lines), then bold-headed groups | gazette |
+| `sidebar-note` | a point with a fenced note beside it; a note too short for its column stands across the top at lead size with the points in two columns under it, and under a side title it stands in the rail | bold-headed groups, then `::: main-box` holding the definition or the usual mistake | chalk |
+| `agenda` | the deck's parts, numbered | `- **Part** what it covers`, three to six lines | chalk, gazette, ledger |
+| `statement` | a quotation or a display-led page the user asked for | the `##` line is the sentence; one body line becomes the support line | atlas, chalk, night, paper, signal, studio |
+| `quote` | a quotation with its source | a line opening with `“`, then a line opening with `—` | chalk, paper, signal |
+| `kpi-row` | four to six headline figures | a two-row table: values, then each figure's basis; then takeaways and a source line | atlas, ledger, night, signal, studio |
+| `kpi-over-chart` | figures above the trend that explains them | the KPI table, then a `::: chart` block, then one takeaway and a source line | ledger, night |
+| `dashboard-grid` | two or three small charts read together | two or three `::: chart` blocks, then one takeaway and a source line | ledger, night |
+| `table-insight` | a table with its reading beside it | a pipe table, a `>` caption, two or three takeaways, a source line | chalk, gazette, ledger, paper, signal |
+| `ledger-table` | a full-width table that is the evidence | a table of five to eight rows and up to six columns, caption, takeaways under it | gazette, ledger |
+| `matrix-2x2` | options on two axes | a 3 × 3 table: corner `효과 \ 난이도`, two column heads, two row heads; cells `item · detail · owner` | gazette, ledger |
+| `comparison` | two sides read across shared criteria | `:::: columns 1fr 1fr`, each `::: col` with `- **side**` and `(1) 기준: …` items | all eight |
+| `chart-insight` | a chart with its reading | a `::: chart` block with a `>` caption, two to four takeaways, a source line | ledger, night, paper, signal, studio |
+| `full-chart` | one chart across the page | a `::: chart` block and a source line | ledger, night, paper, signal |
+| `big-number` | two to four related figures as a data panel | a KPI table (labels, values, basis row), then evidence bullets | ledger, night, signal, studio |
+| `process` | three to five steps in order | `- **1. 단계** what happens`; plain bullets after the steps are takeaways | chalk, signal |
+| `step-diagram` | steps taught one at a time | as `process` | chalk |
+| `timeline` | dated events on one axis | a `시점 \| 할 일 \| 담당` table (or Date, Milestone, Owner), caption, takeaways | atlas, gazette, ledger, night, studio |
+| `method` | a formula or figure with its terms | a formula line or an image, then `- **term** meaning` lines | chalk, night, paper |
+| `image-full` | one photograph as the page | one image whose alt text is the caption | atlas, studio |
+| `image-split` | a picture beside its explanation | an image, then bold-headed bullets | atlas, chalk, signal, studio |
+| `photo-grid` | a row of two or three pictures | the images on consecutive lines, then a single sentence | atlas, studio |
+| `figure-pair` | two states of one subject (before/after, A/B) | two images, then one or two measured lines | atlas, paper |
+| `figure-academic` | a journal figure and how to read it | an image captioned `Figure N.`, then bullets headed observation, limitation, implication | paper |
+| `asymmetric-feature` | one large picture and a narrow text column | an image, then four or five short bullets | atlas, signal, studio |
+| `references-appendix` | sources and definitions, one a line | `- [1] …` lines, eight to ten entries | gazette, ledger, paper |
+
+Old layout names still compile under a tonality: `content` and `main` become `text-column`,
+`summary` becomes `comparison`, `closing` becomes `closing-statement`, and `cover` or `section` take
+the pack's first variant.
+
+## Source details that decide the result
+
+- **Charts.** `::: chart type=column unit="억 원"` around a pipe table: categories in the first
+  column, one column per series, a `>` caption inside the block. Types: bar, column, line, area, pie,
+  doughnut, stacked. The chart is native and editable; on the compact step its values also appear as
+  a small table beside the takeaways when they fit (up to eight rows and four columns).
+- **Captions.** A `>` line after a table or inside a chart block is its caption; say what is shown,
+  the unit, the period, and "(예시 데이터)" or "(sample data)" for sample values.
+- **Source strip.** A body line that opens with `출처:`, `자료:`, `주:`, `Source:` or `Note:` is set as a
+  strip at source size, so it costs the takeaways no room. Under a side title it closes the rail;
+  beside a chart, table or picture it closes the takeaway column on the floor, so the column runs as
+  long as the visual; elsewhere it runs across the foot of the body. A takeaway column that still
+  stops halfway down the visual beside it fails the gate (OF-115): add the source or a note line, or
+  the takeaway the slide lacks. The gate reads the largest empty band inside the column, so a strip
+  at the foot under two short points still fails; see density-and-fill.md for how the engine fills it.
+- **Run-in labels.** A point may open with a bold label: `- **요약:** 앱에서 맡기면 …`, `- **Basis:**
+  1.0 L/min feed`. Write the colon; the engine adds one when the label ends without a separator,
+  because a bold word running into its sentence reads as part of it. A bold line with nothing after
+  it is a group heading and takes none. The gate fails a hand-set label without a separator (OF-118).
+- **Pictures.** `![caption | 출처: …](assets/name.png)`. The text before `|` is the caption, the rest
+  its source. Write the caption without a number: the engine prefixes `도 N.` on a Korean deck and
+  `Figure N.` otherwise, and drops a `도/그림/Figure/Table N.` you typed. The gate wants every figure's
+  caption and source beside it: under the picture, or on the panel laid over a full-bleed photograph
+  and the picture a cover borrows (examples 06, 09 and 10).
+- **Covers take no blocks.** A cover slide holds only its `#` title (and notes). `cover-split-image`
+  and `cover-full-image` borrow the deck's first picture; `cover-figures` borrows its first KPI row;
+  `cover-index` borrows the agenda.
+- **Bullets beside a picture are narrow.** Under a bottom title the takeaways run in columns 10-12;
+  keep each under about 60 Latin characters or 30 Korean glyphs, and captions under about 70.
+
+## Covers, sections and closings
+
+Name a variant on the `layout:` line (`layout: cover-band`). The engine draws it when the pack lists
+it and the deck holds what it needs; otherwise it takes the pack's first variant it can draw and
+prints `note: slide 1: drawn as …`.
+
+| Variant | What it shows | Needs | Packs |
+|---|---|---|---|
+| `cover-typographic` | the title drawn with the pack's cover device | nothing | atlas, chalk, gazette, ledger, night, paper, signal |
+| `cover-figures` | the title over the deck's headline figures | a KPI row in the deck | ledger, night |
+| `cover-index` | the title beside the deck's parts | an agenda, or two or more sections | gazette, ledger, paper |
+| `cover-numeral` | a year or real figure at title size above the title | a year or figure in the title or date | chalk, night, signal, studio |
+| `cover-split-field` | half the page in the accent field | nothing | signal |
+| `cover-split-image` | the title beside the first picture | a picture in the deck | atlas, paper, studio |
+| `cover-full-image` | the first picture full-bleed, title on a panel | a picture | atlas |
+| `cover-band` | the title under a strong head band, the parts across the page | nothing | gazette |
+| `cover-rail` | the title in a left rail | nothing | chalk, studio |
+| `section-field` | the part title on a colour field | nothing | atlas, night, paper, signal |
+| `section-numeral` | the part number beside the part title | nothing | chalk, ledger, night, signal, studio |
+| `section-rule` | with an agenda, an index page with this part marked | nothing | gazette, ledger, paper |
+| `section-rail` | the part title in the rail | nothing | chalk, studio |
+| `section-band` | the part index in the band, the part title under it | nothing | gazette |
+| `section-image` | the part title on the section's own picture | a picture on that slide | atlas |
+| `closing-ask` | the ask as title, its table as action rows, the next step on the floor | a table or bullets | atlas, chalk, gazette, ledger, paper, signal |
+| `closing-decision-box` | a boxed decision line over the items to approve | one decision bullet, then a table if there are items | gazette, ledger, night |
+| `closing-statement` | one closing sentence | no table or picture | night, signal |
+| `closing-summary-list` | the takeaways numbered down the page | bullets | chalk, paper, studio |
+| `closing-contact-split` | action rows beside a field holding each row's amount or date | a table or bullets, plus a next-step line | atlas, studio |
+
+A closing title names the ask ("시드 투자 15억 원 사용 계획", "Decisions for the November peak"). The
+body carries what is to be decided, the amount or deadline, the owner, and the next step with its
+date. "감사합니다" or "Questions?" alone is not a closing.
+
+## Display devices
+
+A cover or a section page holds a handful of words, so a pack's `display:` key names the device that
+gives such a page its weight. A device frames what the source already says; it never
+adds words or figures.
+
+| Device | Draws | Packs |
+|---|---|---|
+| cover `drench` | the field over the whole page, title anchored low | signal |
+| cover `plate` | a field plate over a little under half the page, title on it | atlas |
+| cover `rail` / `band` | the pack's `cover-rail` / `cover-band` | chalk / gazette |
+| cover `figures` | `cover-figures` when a KPI row exists, else the plain cover | ledger |
+| cover `numeral` | `cover-numeral` with the year | night |
+| cover `rules` | a journal title page: heavy rule, title, hairline, presenter, place and date | paper |
+| statement `open` / `drench` / `rules` / `offset` | the sentence alone; on the field over the whole page; between hairlines; beside a short rail | signal, night / chalk, atlas / paper, studio / no pack (the rail beside a quote stood empty) |
+| number `field` / `tint` / `outline` | the panel behind a big number | signal / atlas, chalk, ledger, night, studio / gazette, paper |
+| closing `band` / `box` / `rules` | the next step on the floor as a field band, a tinted or outlined box, or under a rule | atlas, night, signal, studio / chalk, gazette, ledger / paper |
+| `index: true` | sections show the deck's parts with this one marked | gazette, ledger, paper |
+
+## What the engine does with the source
+
+- A title that needs two lines is split so both lines are about as wide, never leaving one word
+  alone below; figures are glued to their counter ("15억 원", "4 분기", "다섯 곳").
+- Line breaks in body text and table cells are placed by the engine at spaces, so "51점" or "(10월" is
+  never split between digit and unit by the renderer, and a short parenthetical such as "(▲ +3.9%)" (up to
+  16 characters) is never split inside.
+- Section numerals come from the agenda: write the section title exactly as its agenda head and the
+  page shows "02 / 04". With no agenda the sections are counted; a lone section gets no numeral at
+  all, and its title is set large over the titles of the next slides.
+- A closing's table becomes action rows keyed by the amount column (each row gets a bar for its share
+  of the total), else by the date column. A `합계` or `Total` row is never an action row.
+- A big number is a panel of two to four figures, one row each (value, label, basis), never larger
+  than title size, seven of twelve columns wide, with the evidence beside it.
+- Dark devices that do not fill the page (plates, rails, panels) stay under half its area, so the
+  pack's ground still reads as the page colour.
+- In tables of signal and night, the row whose first cell appears in the slide title is tinted as
+  the row the slide is about.
+
+## Families under different titles
+
+The same family changes shape with its title, which is where a lot of a deck's variety comes from:
+
+- With a `side-rail` title, figures from a KPI table stack as rows, process steps run downward, and a
+  chart fills columns 5-12 from top to floor. The rail under the title carries the slide's supporting
+  content: a comparison's criteria labels, a visual's takeaways (a step up, at lead size, when body
+  size leaves the rail more than 40 % empty), a values table and the source strip. A table gives up
+  its takeaways only when its rows, opened, still fill the body. A slide whose rail would stay more
+  than 40 % empty takes another title unless `title: side-rail` pins it, and the gate fails that
+  rail (OF-115).
+- With a `bottom-anchor` title, the chart, figure or panel owns the zone from y 36 to 24 pt above the
+  title, and the title's last line stands on the body floor.
+- Beside a visual, takeaways that leave their column more than 40 % empty are set a step up (lead)
+  when they still fit; compact process rows that leave a quarter of the body's width empty do the same.
+- Under `band`, the body starts at y 120 and runs to the floor at reading size.
+- A `quote` under `statement` sets the quotation as the page's sentence and the source as support.
+
+## Reading the compile log
+
+```text
+note: slide 4: timeline is not a chalk layout family (step-diagram, process, …); drawn with its own geometry
+note: slide 1: cover-figures cannot be drawn (the deck has no row of headline numbers)
+note: slide 1: drawn as cover-typographic
+variety: slide 3 drawn under top-rule so the deck carries 6 layouts
+fill: slide 6 band 0.19 -> 0.19 (none: nothing on the slide can grow; choose a fuller family)
+```
+
+Treat every `note:` as a request the pack could not honour. Change the source: pick a family from the
+pack's list, shorten the title, or go back to `direction-step.md` and choose another pack.
+A `variety:` line is the engine keeping the deck varied and needs no action. A `fill:` line that
+ends in "choose a fuller family" is covered in `density-and-fill.md`.

package/.grok/skills/lit-pptx/references/title-treatments.md

@@ -0,0 +1,134 @@
+# Title treatments
+
+A title treatment is where a slide's title sits and what is drawn with it. The engine has eight,
+each with one fixed frame, so every slide under a treatment puts its title in the same spot. A deck
+reads as designed when it uses three to five of them and each one always marks the same kind of
+slide: a reader learns "the side rail means a chart with its reading" in two slides.
+
+## Two rules for every title
+
+**A title is a topic label.** Think of it as the heading of a table of contents: what is shown, in
+what measure, for which period when that matters:
+"권역별 대여소 이용 현황", "On-time delivery by region, Q3 2026". The claim goes in the body, as the
+first takeaway, the first point, the boxed summary or the caption. The gate's OF-114 check fails a
+title or cover subtitle that reads as a sentence:
+
+- Korean: the last word ends in -다, -니다, -요 forms or -죠, or in a nominalised claim (-음 after a
+  past or future stem, 있음, 없음, or -함/-됨 on a word other than 포함). "보고 순서" passes;
+  "매출 증가함" and "목표를 달성했다" fail.
+- English: a final period, an auxiliary (is, are, was, has, will …), or a finite verb after the
+  first word: past forms (grew, rose, fell, improved, exceeded …) and a few third-person forms that
+  seldom act as nouns (beats, exceeds, improves, grows …). Plural nouns such as "leads", "works" or
+  "cuts" and hyphenated compounds such as "cut-over" stay labels: "Milestones to cut-over" passes,
+  "Revenue rose 12%" fails.
+- A question, a title that opens with a quotation mark, and a trailing parenthesis are not read as
+  claims.
+
+**No eyebrow, no decorative numeral.** Nothing small sits above a title. A numeral next to a title is
+a real part, step or recommendation number, drawn by `kicker-numeral` or a section variant; it is
+never added for texture.
+
+## The eight
+
+Geometry is for 16:9 on the compact grid (density 10: 24 pt margins, 54 pt columns, 24 pt gutters,
+title 26 pt, display 36 pt). Budgets are Korean glyphs per line; Latin text takes about 1.7 times as
+many characters.
+
+| Treatment | Title frame | Drawn with it | Body zone | Budget |
+|---|---|---|---|---|
+| `top-rule` | columns 1-12 at y 36, title size | an accent rule one column wide, or a full-width hairline in packs without `accent-rule`, 6 pt under the title | 18 pt under the rule (y ≈ 92 for one line) to the floor at 486 | 2 lines of about 35 |
+| `top-plain-large` | columns 1-10 at y 36, display size | nothing | 18 pt under the title (y ≈ 108 for one line) | 2 lines of about 20 |
+| `side-rail` | columns 1-4 from y 36, title size | a filled rail (surface, or the field with white type in chalk) where the pack has `rail-fill`, else a hairline after column 4 | columns 5-12, from y 36; the rail under the title carries the criteria labels, the takeaways and the source | 4 lines of about 10 |
+| `band` | inside a full-width band 108 pt tall, columns 1-11 | the band in the field colour, title in `on-field` | y 120 to the floor | 2 lines of about 32 |
+| `statement` | columns 1-10, centred near y 303, display size | an optional support line under it | none | 3 lines of about 20 |
+| `overlay` | lower left on a dark panel (columns 1-7) over a full-bleed picture; the panel is as tall as the title and its caption and stands on the page foot | the panel and the picture's caption | none: the picture is the content | 2 lines of about 19 |
+| `kicker-numeral` | columns 3-12 at y 48, with a cover-size numeral in columns 1-2 | the numeral in the accent | y 120 to the floor | 1 line of about 27 |
+| `bottom-anchor` | columns 1-9, its last line on the body floor at 486 (a one-line title leaves no band under it) | a hairline 12 pt above the title where the pack has `hairline-rule` | y 36 to 24 pt above the title for the visual; columns 10-12 beside the title stay clear | 2 lines of about 24 |
+
+`kicker-numeral` needs a real number: a step, a ledger part, the part a section opened. An agenda is
+not one: its rows carry the numbers, and a count beside its title read as a stray section number, so
+the agenda takes another title (the gate fails a numeral there, OF-119). Without a number the engine
+cannot draw it and picks another title.
+
+## How a slide gets its title
+
+The family sets the slide role: text families are `content`; tables, KPI rows, comparisons and
+matrices are `data`; charts and big numbers are `data-takeaway`; processes, steps and timelines are
+`sequence`; picture families are `image`; statements and quotes are `statement`; `method` is
+`definition`; references are `reference`. The pack's `role-defaults` map gives each role a default
+treatment. A pack may also give one family its own title under `structure`: Paper draws a comparison
+under `top-rule` as a ruled table, Chalk sets the comparison's criteria on its board rail under
+`side-rail`. That title comes before the role default and holds even when the deck already leans on
+it, so two tonalities of one source differ in structure, not only in colour. When the role default
+is a bottom title the slide may not take (a table), the pack's next treatment stands in.
+
+For each slide the engine tries every treatment that both the family and the pack accept and that
+the title fits. The role default is the pack's structure, so it stays unless another treatment fills
+the body better by a tenth of the zone (by 0.15 when neither fills it) or the default cannot be drawn
+without overflow; a side rail that would stay more than 40 % empty also gives way. Two deck-level passes follow: no title zone may
+hold more than 40 % of the content slides, and the deck must carry enough distinct layouts for the
+composition check. Each move is printed:
+
+```text
+variety: slide 5 drawn under side-rail so no title zone covers more than 40 % of the content slides
+Treatments: 2:band 3:top-rule 4:band 5:top-rule 7:side-rail 8:top-rule 9:band 10:top-rule 11:band
+```
+
+The variance dial caps how many treatments one deck mixes: 2 at variance 3 or lower, 3 at 4, 4 at
+5-6, 5 at 7 and above, never more than the pack has.
+
+Closings with a table or a decision take only top titles (`top-rule`, `band`, `top-plain-large`).
+Covers and sections draw their own variant's title and refuse a `title:` key.
+
+## Pinning a title
+
+Put `title: <treatment>` on the line after `layout:` when a slide must take a particular treatment.
+The compile stops with a message naming the allowed list if the treatment is unknown, not in the pack,
+not allowed by the family, or cannot hold the title:
+
+```markdown
+---
+layout: comparison
+title: side-rail
+
+## 재배치 대안 비교
+```
+
+Pin sparingly. The usual reasons are a low-variance pack that needs a different partition to pass
+the composition check (example 07 pins its agenda to `top-rule` and its comparison to `side-rail`),
+or a comparison whose rows leave a column hollow under the role default (example 04).
+
+## Choosing well
+
+- **A chart or table with a reading** wants `side-rail` or `bottom-anchor`: the visual takes the full
+  height and the title labels it from beside or below.
+- **A page that is read** (briefing, status) wants `band` or `top-rule`, the most predictable heads.
+- **A real sequence** wants `kicker-numeral`; a list with no order never gets a numeral.
+- **A full-bleed photograph** takes `overlay`, and only on `image-full`. A large picture with a short
+  label beneath takes `bottom-anchor`.
+- **`statement`** is for a quotation (the `quote` family) or a display-led deck the user asked for. A
+  single claim on an empty page is not a slide; it becomes the boxed summary or the first takeaway of
+  a content slide.
+
+Never move a title with a placed `box`. The frame is the treatment; a nudged title is a ninth,
+broken treatment, and OF-113 fails it.
+
+## What the gate checks
+
+The gate classifies each title from the compiled file by geometry and companions and compares that
+with the `title@<treatment>` name the engine writes on the shape; the name alone is never accepted.
+
+- **OF-110**: a deck of eight or more slides shows at least three treatments (covers and sections
+  not counted) and no more than the variance dial allows; every title is drawn as it is named.
+- **OF-113**: slides under one treatment keep one frame (within 1 pt; a statement compares x and
+  width only, a bottom title x, width and its bottom edge, because it stands on the floor).
+- **OF-115**: a bottom title that ends more than 12 pt above the body floor fails, and so does a side
+  rail more than 40 % empty under its title. What stands in the rail under the title belongs to the
+  rail: it neither changes the side-rail reading nor counts as a body column. A text or picture column
+  whose largest empty band, read beside a longer column, passes 40 % of the body fails as well; a
+  source strip at the column's foot counts as a block but does not hide the band above it.
+- **OF-119**: an agenda title stands without a numeral beside it.
+- **OF-114**: titles and the cover subtitle are labels, as above.
+
+On an enrolled template these findings are advisory, because the user asked for one fixed title
+position.