@litfamily/litopencode 1.0.16 → 1.0.17

package/skills/lit-pptx/references/density-and-fill.md

@@ -0,0 +1,283 @@
+# Density and fill
+
+LitOpenCode decks are dense by default. Every pack ships at density 10, the compact step, because
+the user's standing verdict on earlier rounds was that slides held too little ("더 빽빽하게"). This
+file explains what the density dial changes, the readable floors nothing goes below, what the
+engine does when a slide comes out short, what the source has to contain so a slide fills with
+substance, and how the gate measures the result.
+
+The one-line rule: **fill a slide with facts the reader needs, never with size or decoration.**
+The engine will not invent content and will not enlarge type on the compact step, so a short
+source produces a visibly short slide and a gate finding. The fix is always in the source.
+
+## The density dial
+
+`density:` in the frontmatter (1-10) overrides the pack default for one deck. The skill may lower
+it by up to 2 without asking (record it on the direction card); a bigger move needs the user's
+word. Each step selects a row of `DENSITY_BANDS` in `scripts/lib/grid-resolver.js`:
+
+| Density | Grid (16:9 side margin) | Ramp: body / label / source pt | Item / group / block gap | Padding | Min table row | Lines per text column | Empty band allowed | Type step-up to fill |
+|---|---|---|---|---|---|---|---|---|
+| 1-2 | airy (60) | presented: 18 / 14 / 12 | 18 / 36 / 48 | 24 | 36 | 6 | 28 % | yes |
+| 3-4 | standard (48) | presented: 18 / 14 / 12 | 12 / 24 / 36 | 24 | 32 | 8 | 24 % | yes |
+| 5-6 | standard (48) | reading: 14 / 12 / 10 | 6 / 18 / 24 | 18 | 24 | 12 | 18 % | yes |
+| 7-8 | dense (36) | reading: 14 / 12 / 10 | 6 / 12 / 24 | 12 | 22 | 16 | 14 % | yes |
+| 9 | dense (36) | reading: 14 / 12 / 10 | 6 / 12 / 24 | 12 | 20 | 18 | 12 % | no |
+| 10 | compact (24) | compact: 13 / 11 / 9 | 6 / 12 / 18 | 12 | 18 | 22 | 12 % | no |
+
+Titles stay at 26 pt (display 36, cover 44) from density 5 upward, so lowering density changes the
+body, not the hierarchy. The compile prints the dials and grid it used on its first line:
+`Tonality night · density 10 · variance 6 · 16:9 compact grid`.
+
+### What the compact step adds
+
+- **Grid.** On 16:9: 24 pt margins, twelve 54 pt columns, 24 pt gutters (24 + 12 x 54 + 11 x 24 + 24 =
+  960). On 4:3: 24 pt margins, 45 pt columns, 12 pt gutters.
+- **Title zone.** A top-rule title frame is as tall as its lines, its rule 6 pt under it, and the body
+  18 pt under the rule, so a one-line title leaves the body from about y 92 instead of 120. A band
+  keeps its 108 pt height and the body follows at 120. Side-rail and bottom-anchor are unchanged.
+- **No type inflation.** Step-up is off: on density 9 and 10 the engine never sets body text a ramp
+  step larger to fill space. Comparisons, headed rows and agendas stay at body size too.
+- **More per slide.** KPI rows hold up to six figures; chart slides also show the chart's values as a
+  small table where it fits; comparison rows draw a criteria column; process rows read across;
+  references step down and run in two columns before they overflow.
+
+### When to lower it
+
+Lower to 8 or 9 (body 14 pt, dense grid) for a deck projected in a large room or read from the back
+of a hall: a keynote over about 40 people, a classroom without individual screens. Keep 10 for
+anything read on a screen or a desk, which is most decks. Never lower density to hide a thin
+source; that only moves the empty band from the gate to the reader.
+
+## Readable floors
+
+Nothing on the compact step goes below these sizes, and nothing in a source can ask it to:
+
+| Text | Floor | Compact size |
+|---|---|---|
+| Body text, takeaways, step text | 12 pt | 13 pt |
+| Table cells, captions, labels | 11 pt | 11 pt |
+| Source and note strip | 9 pt | 9 pt |
+
+The engine reaches density by cutting margins, gaps and padding, not by shrinking type below these.
+If a slide's content does not fit at these sizes, the engine first drops leads to body size and
+gaps to the item gap; if it still overflows, the gate reports the overflowing frame and the slide
+must be split or cut. Never use `::: box` with a tiny `role` to squeeze text in.
+
+## The source strip
+
+Any line in a content slide's text that starts with `출처:`, `자료:`, `주:`, `Source:` or `Note:` is
+lifted out of the takeaways and set at the foot of the body at source size, full width, under a
+hairline where the pack draws hairlines. The strip costs the takeaway column nothing and puts the
+provenance where a reader looks for it.
+
+- Write `출처:` / `Source:` on every content slide that carries a figure: who measured it, over
+  what period, from which document.
+- Add `주:` / `Note:` when a definition changes the reading: how a ratio is computed, what counts as
+  a failure, which baseline a delta uses.
+- Closings keep these lines inside their next-step device rather than in a strip.
+- The strip text is 9 pt and the gate's empty-band check (OF-109) ignores text that small, so a
+  strip does not count as filling the body. It is evidence, not filler.
+
+## The sample-data notice
+
+When any figure, name or photograph in the deck is invented or stands in for the real one, say so in
+the frontmatter:
+
+```yaml
+notice: 예시 데이터 · 실제 수치로 바꿔 쓰는 샘플
+```
+
+The engine sets this line as a small tag in the footer zone of every slide, in the pack's colours.
+Name the sample status in the reply as well. Never leave bracketed placeholders (a company name or "to be decided"
+in square brackets) in a source; write a plausible labelled sample instead, or leave the item out.
+
+## Fill policies: what the engine does with a short slide
+
+After laying a content slide out, the engine measures the empty band between the last content and
+the body floor. If it is larger than the band the density allows (12 % at density 10), it tries the
+pack's `fill-order` one policy at a time, keeping a policy only when it fills more without
+overflowing:
+
+| Policy | What it does | On density 10 |
+|---|---|---|
+| `step-up` | Body text one ramp step larger | Off |
+| `distribute` | Item gaps one step up (to at most 24 pt), group and block gaps one step up (to at most 48 pt) | On |
+| `anchor-visual` | The chart, image or table takes the room left; a KPI card row turns into figure rows | On |
+| `change-family` | A better family for the content | Never automatic; the log asks you to do it |
+
+Each pack orders these differently. Ledger, gazette and chalk effectively spread first (their
+`step-up` is off at density 10); atlas, paper and night let the visual take the room first; studio
+lists a family change first and signal second; the engine never changes a family by itself, so
+those two fall through to letting the visual take the room and then spreading. The compile log prints
+one `fill:` line per slide that started short:
+
+```text
+fill: slide 4 band 0.29 -> 0.24 (distribute)
+fill: slide 6 band 0.20 -> 0.20 (none: nothing on the slide can grow; choose a fuller family)
+```
+
+The second line is the important one. It means the slide is short because the source is short, and
+no policy can help. Add the facts the slide is missing (next section) or move the content to a
+family that suits its amount; `layout-families.md` lists what each family expects.
+
+Some families also spread on their own when the body is short: headed points become rows, agenda
+rows spread down to the floor, timeline room is shared above and below the axis, table takeaways
+move under the table, references spread with rules. These moves never add words.
+
+### A short column beside a full one
+
+A column can stand empty beside a full one even when the body reaches the floor: two short
+takeaways beside a chart, a source line at the column's foot and nothing between them. The engine
+reads each text or picture column against the column beside it (its tallest empty band, from the
+top of the pair down to where the longer column ends) and fills a column that leaves more than 40 %
+of the body empty. It tries, in order, and only by layout:
+
+1. The visual takes columns: the takeaway column narrows (down to three columns) and wraps onto more
+   lines while the chart or picture grows; a picture keeps taking columns while either side leaves a
+   fifth of the body empty. Takeaways never get a smaller size for it.
+2. The points step up to lead size when they fit and keep twelve glyphs a line.
+3. The room left is shared between the points, at most a sixth of the body per gap.
+4. Two or three short points beside a chart that still leave the column empty run under the chart,
+   side by side, and the chart with its values takes the body's width.
+5. A short sidebar note first takes a narrower column at body size; if the main column still runs
+   far past it, the note stands across the top at lead size and the main points run in two columns
+   under it. Under a side title the note stands in the rail.
+6. Beside figure rows (kpi-row, big-number) the takeaways' column is read down to the body floor,
+   since the rows stop where their spacing ends: short points run under the rows, or share the room
+   beside them when running under would leave a band between rows and points.
+7. A title under which a column still stays empty is unfit for the slide when another title fits.
+
+The source strip closing a column counts as a block but never hides the band above it, and the
+chart's values table under the takeaways moves and is read with their column. The gate reads the
+same way (OF-115). When a slide still fails, the source is short: one more real takeaway,
+the values the chart stands on, or a family that suits the amount.
+
+## What to write per slide
+
+A dense slide is a slide that answers the reader's next question before it is asked. For every
+content slide, check the source holds these five things; most short slides miss two of them.
+
+1. **Basis.** What the number is measured on: per building, per 1,000 kg of water, at 0.1 MPa,
+   weighted by effort, a 1 % request sample.
+2. **Comparison.** Against what: plan, last year, the previous quarter, a target, the other option,
+   the baseline model.
+3. **Period.** When: 2026년 7~9월, weeks 35-40, January to September, as of 30 September.
+4. **Source.** Who produced it: the `출처:` / `Source:` line.
+5. **Implication.** What it means or what happens next: the takeaway, the decision it supports, the
+   follow-up date.
+
+Counts that make a slide read as finished at density 10:
+
+| Element | Target |
+|---|---|
+| KPI row | 4-6 figures, each with a basis row (`계획 대비 +4.1%`, `target 99.95%`) |
+| Table | 5-8 body rows, a totals row where the rows add up |
+| Comparison | 3-4 labelled criteria rows, the same labels on both sides |
+| Chart | 5-9 categories, a caption, 2-4 takeaways, a source line |
+| Timeline | 5-6 events with owners, 2-3 takeaways |
+| Text slide | 5-6 headed points or 4-6 groups with sub-points |
+| Method | a formula line plus 4-5 terms with one or two sub-points each |
+| References | 8-10 entries, sources then definitions |
+| Closing | 3-5 asks or decisions with amounts or dates and owners |
+
+### A short slide and the same slide filled
+
+Short (compiles, but the band is empty and the reader has questions):
+
+```text
+---
+layout: chart-insight
+
+## 월별 출고 건수
+
+::: chart type=column
+| 월 | 출고 |
+|---|---|
+| 7월 | 131 |
+| 8월 | 137 |
+| 9월 | 144 |
+:::
+
+- 출고가 늘었음
+```
+
+Filled (same slide job; every added line comes from the source material, none from imagination):
+
+```text
+---
+layout: chart-insight
+
+## 월별 출고 건수, 2025년과 2026년 비교
+
+::: chart type=column unit="만 건"
+| 월 | 2025년 | 2026년 |
+|---|---|---|
+| 7월 | 118 | 131 |
+| 8월 | 124 | 137 |
+| 9월 | 133 | 144 |
+> 월별 출고 건수, 2025년과 2026년 비교 (예시 데이터)
+:::
+
+- 세 달 모두 전년보다 8~11% 많았고, 9월이 분기 최대
+- 9월 증가분의 70%가 이천 센터 자동 분류기 가동 뒤 처리량
+- 4분기 성수기에는 평시의 1.6배까지 늘어날 전망
+- 출처: 예시 물류 WMS 출고 실적(2025년 7월~2026년 9월)
+- 주: 출고 건수는 반품 재출고를 제외한 주문 기준
+```
+
+The first version also breaks two rules on its own: the title has no comparison or period, and the
+takeaway is a bare claim (`늘었음`) with no figure.
+
+### Numbers stay honest
+
+- No hero numerals. The engine caps every number it sets (KPI values, big-number panels, cover
+  figures, closing keys, section numerals) at the title size of the ramp; do not try to get around
+  that with a `box` or `shape`.
+- A figure is never larger than the title, and a figure without a basis is not a KPI.
+- Signed deltas carry their sign and unit (`+4.1%`, `−3.6%`, `+0.5%p`, `▲ 12%`). In signal, where
+  the accent is red, losses keep the ink colour and rely on the `▼` sign.
+- Keep one unit per column; put the unit in the header or the chart's `unit=`.
+- Round to what the source supports and keep the rounding consistent within a slide.
+
+## How the gate measures density
+
+`node <skill>/run.mjs qa deck.pptx` reports three density-related findings. Only HIGH findings and
+the composition failure fail the gate; read the MEDIUM ones as a to-do list.
+
+- **OF-109, empty band (per slide).** The largest vertical gap between content blocks on a content
+  slide, measured from under the title to 0.55 in above the bottom edge (or above a bottom title),
+  ignoring text of 10.5 pt or less, which means the source strip and captions do not count. A gap of
+  25 % or more is MEDIUM, over 35 % is HIGH. Cards are measured the same way inside themselves.
+  Typical causes: a method slide with three short terms, a sidebar-note with six lines of main text,
+  a closing summary with four one-line items, a timeline with one takeaway.
+- **OF-112, deck median band.** Each content slide's empty band against the density's cap (12 % at
+  density 10) is MEDIUM; a deck whose median band exceeds 20 % fails.
+- **Composition fill (`low_content_fill`).** An older whole-slide check: on every slide except the
+  first and the last, the area of text, tables, charts and pictures that start between 1.7 in and
+  6.7 in from the top must cover at least 12 % of the content area. Blocks that start higher than
+  1.7 in are not counted at all. On the compact step a top title's body starts near 1.3 in, so a
+  slide whose table and takeaways both start at the top can fail even when it looks full. The
+  remedies that worked on the example decks:
+  - give a `table-insight` slide three or four takeaways, so they either run beside the table at
+    length or move under it in two columns;
+  - give a `ledger-table` slide three or four takeaways under the table;
+  - give a mid-deck `statement` slide its one support line;
+  - give a `dashboard-grid` four panels, so the second row starts lower;
+  - or put the title at the bottom (`title: bottom-anchor` where the pack allows it), since the
+    bottom title itself is counted.
+
+Other checks that interact with density: OF-102 flags a line measure over 38 Hangul or 90 Latin
+characters (HIGH) or a narrow column under 10 characters a line over three lines (MEDIUM); OF-101
+flags too many accent hues on one slide; the layout inventory flags any text frame whose estimated
+text height exceeds the frame. Shorten the text; do not reach for smaller type.
+
+## A density pass, in order
+
+1. Compile. Read every `fill:` line ending in `none` and every `note:` line.
+2. Run the gate. List OF-109 HIGH slides and any `low_content_fill` slides.
+3. For each, add the missing basis, comparison, period, source or implication from the source
+   material. If the material has nothing more, change the family to one that suits the amount
+   (`layout-families.md`) or merge the slide with its neighbour.
+4. Recompile and rerun the gate until it exits 0. MEDIUM findings may remain; HIGH may not.
+5. Render and look at the pages. A passing gate is not a visual review.

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

@@ -0,0 +1,249 @@
+# Choosing a direction before the first slide
+
+A LitOpenCode deck is drawn from a tonality pack: palette roles, a type ramp, the title treatments
+the pack allows, the layout families it lists, its cover, section and closing variants, and two
+dials. Eight packs ship in `templates/tonalities/`. The engine never guesses a look on its own, so
+the first decision of every build is which pack to compile under. This file is the procedure for
+making that decision quickly, recording it, and telling the user what was chosen.
+
+The step costs a few minutes and saves the most expensive failure in slide work: a deck that is
+correct slide by slide but wrong as a whole, because a stage pitch was set as a dense reading
+document or a briefing paper was set as a keynote.
+
+## What the step produces
+
+1. One tonality id written into the deck's frontmatter (`tonality: ledger`).
+2. Two named alternatives, with the reason each one lost.
+3. The density and variance the deck compiles at, and any move away from the pack default.
+4. A direction card kept in the task's working notes (the build log), and a two or three sentence
+   summary of it in the reply.
+
+Nothing else is decided here. Layout families per slide come next, while outlining; they are
+recorded on the card because a pack that cannot carry a planned slide is a wrong pack.
+
+## No questions on a bare request
+
+A bare request ("발표자료 만들어 줘", "make a deck from these notes", a bare `lit` slide request)
+gets no question about colours, fonts or style. Read the request and any sources, pick the
+direction yourself, build the whole deck, and say in the reply what was chosen and what the
+alternatives were. The user corrects a finished deck faster than they answer an abstract style
+question.
+
+Ask only in two cases:
+
+- the user has explicitly left the look open and wants to see options ("어떤 느낌이 좋을지 모르겠어",
+  "show me a few styles"): build the compare strip below instead of asking in words;
+- a dial would have to move by more than 2 from the pack default to meet the brief (see "Dials").
+
+## Step 1: read four facts off the brief
+
+Infer each fact when the brief does not state it, and write the inference on the card so the user
+can correct it later.
+
+| Fact | What to settle | Why it matters |
+|---|---|---|
+| Deck type | One of the eight types below, or the nearest one | Gives the starting candidate order |
+| Delivery | Spoken in a room, sent ahead and read alone, or both | Read decks favour Gazette and Ledger; stage decks favour Signal and Night |
+| Room | Lit office, screen share, dark hall, printed handout | A dark hall pulls Night forward; print rules Night out |
+| Language | Korean, English or mixed | Korean glyphs take about twice the width of Latin letters, which tightens title budgets |
+
+## Step 2: start from the deck type
+
+Each deck type has an ordered shortlist. The first entry wins when no signal in step 3 moves it.
+All eight packs default to density 10; the variance shown is each pack's own default.
+
+| Deck type | First choice | Second | Third |
+|---|---|---|---|
+| Pitch or proposal (투자·제안) | signal (v6) | studio (v8) | atlas (v7) when the product is physical and photographed |
+| Management review (경영·사업 실적) | ledger (v5) | gazette (v4) when circulated in Korean before the meeting | night (v6) when presented on a stage screen |
+| Research talk (연구 발표) | paper (v5) | night (v6) for a large dark auditorium | chalk (v6) for a tutorial-style talk |
+| Lecture or training (강의·교육) | chalk (v6) | paper (v5) | studio (v8) for a public lecture with images |
+| Data review (데이터·지표 리뷰) | night (v6) | ledger (v5) | paper (v5) when the review is a written analysis |
+| Image-led showcase (제품·현장·포트폴리오) | atlas (v7) | studio (v8) | signal (v6) for a launch moment |
+| Korean reading brief (보고서형 덱) | gazette (v4) | ledger (v5) | none |
+| Status update (주간·월간 보고) | ledger (v5) | gazette (v4) | night (v6) |
+
+A request that fits none of these takes the nearest type, and the card says "other, treated as
+status update" or similar.
+
+## Step 3: measure the outline and reorder
+
+Write a rough outline first: one line per slide naming its job and the visual it needs (table,
+chart, image, numbers, steps, prose). Count on that outline, not on the raw notes. Apply the rules
+in this order; ties keep the deck-type order, so the same source always lands on the same pack.
+
+| Rule | Fires when | Move |
+|---|---|---|
+| Named by the user | The brief or an earlier turn names a tonality | Use it. Still write the card and still name two alternatives |
+| Legacy template named | The brief names AZURE-PRO, AZURE-A2Z, BOILERPLATE-PRETENDARD or BOILERPLATE-A2Z | Compile with `--template` as named; offer two tonalities as alternatives |
+| Read, not presented | "미리 배포", "보고서", "sent ahead", "for the board pack" | gazette to the front for Korean, ledger otherwise |
+| Table-heavy | 30 % or more of slides hold a table | ledger or gazette up one place |
+| Chart-heavy | 30 % or more of slides hold a chart | ledger, night or paper up one place |
+| Image-heavy | 30 % or more of slides hold a photograph or screenshot | atlas or studio up one place; gazette down one place |
+| Long bodies | average body over about 150 Hangul or 300 Latin characters per content slide | gazette or ledger up; signal down |
+| Short bodies | average body under about 40 Hangul or 80 Latin characters | signal or studio up |
+| Citations | numbered references, DOIs, a references slide | paper up one place |
+| Teaching shape | definitions, equations, or a how-it-works sequence of three or more steps | chalk or paper up one place |
+| Dark room | keynote hall, demo day, stage | night up one place |
+| Missing carrier | the pack has no family or title that can carry a planned slide | drop that pack from the shortlist |
+
+The last rule overrides taste. The packs differ in what they can draw:
+
+- ledger, gazette and atlas have no `statement` title treatment; a statement slide there is set as
+  a top title, the largest the pack has, and the compile log says so;
+- atlas lists no table, chart or references family; an outline with a results table does not fit
+  it, however many photographs it also has;
+- gazette lists no chart family; a chart-led Korean report belongs to ledger;
+- signal lists no `ledger-table`, `dashboard-grid` or `references-appendix`;
+- night lists no image family at all, so a photograph-led slide does not fit it, and its two
+  closings are a statement and a decision box;
+- only atlas and studio carry `image-full`, and only atlas, studio and paper have a cover that uses
+  a photograph.
+
+Run `node <skill>/run.mjs compile --list-layouts <tonality>` to see a pack's exact families, the
+treatments each family takes in that pack, and its cover, section and closing variants.
+
+### A worked case
+
+A Korean seminar on battery recycling for an industry association, 25 minutes, projected in a lit
+conference room, with nine content slides planned: three charts, two tables, two process
+diagrams, one photograph and a references slide.
+
+- Deck type: research talk, so paper, night, chalk.
+- Chart share 3/9 = 33 %: paper (already first) stays first.
+- Table share 2/9 = 22 %: does not fire.
+- References slide present: paper up (already first).
+- Two process slides of four steps each: chalk up one place, above night.
+- The room is lit: night gets no lift.
+
+Result: paper, alternatives chalk and night. The card says chalk would fit better if the audience
+were students rather than practitioners.
+
+## Step 4: the direction card
+
+Write the card before the first slide and keep it with the task's notes. It is working evidence,
+not slide content, and it is shown to the user only in summary unless they ask for it.
+
+```text
+DIRECTION
+  deck type      research talk (연구 발표), industry seminar, 25 min, lit room
+  delivery       presented; file shared afterwards
+  tonality       paper            alternatives: chalk, night
+  reason         figures and citations carry the talk; 33 % chart slides, references present
+  signals        chart share, citations, teaching shape (moved chalk above night)
+  dials          density 10, variance 5 (pack defaults)
+  role map       content top-rule | data top-rule | data-takeaway bottom-anchor | definition side-rail
+  families       cover-index, section-rule, text-column, method, figure-academic, chart-insight x2,
+                 table-insight, comparison, closing-summary-list, references-appendix
+  wrong if       the audience is students: chalk's step rhythm and definition boxes teach better
+```
+
+Every line is required. If you cannot fill `tonality` and `reason`, stop and ask; there is no
+silent default look. The `wrong if` line is the first thing a reviewer checks: when it turns out to
+be true, rebuild under the alternative it names rather than patching slides.
+
+Copy the role map from the tonality sheet (`tonalities/<id>.md`). The engine may still give a slide
+another treatment the family allows when that slide fills better under it, and the variety pass
+may move one slide to add a layout; the compile log prints each move (`variety: slide 3 drawn
+under bottom-anchor ...`) and a `Treatments:` line with the final choice per slide.
+
+## Step 5: tell the user
+
+In the reply, next to the delivered files, say the choice, the reason and the two alternatives in
+plain words. Keep it short; the card itself stays in the notes.
+
+> paper 톤으로 만들었습니다. 그림과 인용이 발표를 끌고 가는 자료라서입니다. 수강생 대상이라면
+> chalk, 어두운 대강당이라면 night도 맞습니다.
+
+> Built in Signal: a live pitch with one idea per slide. Studio would suit a slower editorial
+> story; Atlas would suit a product that is mostly photographed.
+
+Name sample data as sample data in the same reply when the deck uses any (see `notice:` in
+`density-and-fill.md`).
+
+## Dials
+
+Two integers in the frontmatter override the pack defaults for one deck.
+
+```yaml
+density: 9
+variance: 6
+```
+
+- **density** (1-10) chooses the grid, the type ramp, the gaps and padding, the minimum table row,
+  and how much empty band a content slide may leave. Every pack defaults to 10, the compact step.
+  For a deck projected to a room of more than about 40 people, lowering it to 8 or 9 (body 14 pt,
+  dense grid) is the usual move. See `density-and-fill.md`.
+- **variance** (1-10) caps how many distinct title treatments one deck mixes: 2 at variance 1-3,
+  3 at 4, 4 at 5-6, 5 at 7 and above, never more than the pack lists. Variance under 4 is only for
+  a user who asks for a uniform deck; the gate then reports the low variety as MEDIUM instead of
+  passing it silently.
+
+The skill may move either dial by at most 2 from the pack default without asking, and the card
+records the move ("density 8, lowered 2 for a 300-seat hall"). A larger move needs the user's
+word. `node <skill>/run.mjs compile` prints the dials it used on its first line
+(`Tonality ledger · density 10 · variance 5 · 16:9 compact grid`); check that line against the card.
+
+Two neighbouring keys are not dials but belong to the same decision:
+
+- `canvas: 4:3` switches every pack to its 4:3 grid (all eight list both canvases);
+- `faces: a2z` (or `--faces a2z`) switches the display and numeral faces to A2Z. Pretendard is the
+  default in every pack, and A2Z is used only when the user asks for it.
+
+## The compare strip
+
+When the user wants to see options, render the first three slides of the same source under the
+chosen pack and the two alternatives, and show the nine pages as three labelled rows before writing
+the rest of the deck. The content and order are identical in every row; only the pack changes.
+
+```sh
+# strip.md: the deck's frontmatter plus its first three slides
+for t in paper chalk night; do
+  node <skill>/run.mjs compile strip.md --tonality "$t" --pptx "strip-$t.pptx"
+  node <skill>/run.mjs qa "strip-$t.pptx"
+done
+# then render each strip deck to page images as the skill's render step describes, and show them
+```
+
+`--tonality` overrides the frontmatter, so one strip source serves all three rows. A strip of
+three slides is below the gate's variety thresholds (OF-110 starts at eight slides, OF-111 at
+three content slides), so the deck-level checks do not judge it; judge the strip by eye. Do not argue for a row in the message beyond the card's reason. When the
+user picks, change the card's reason to "picked by the user from the strip" and build the deck.
+
+Do not build a strip for a bare request. It is a response to an explicit wish to compare, not a
+default step.
+
+## Legacy templates
+
+AZURE-PRO, AZURE-A2Z, BOILERPLATE-PRETENDARD and BOILERPLATE-A2Z keep their names and their single
+look. Use one only when the user names it or an existing source already says `template:`. Compile
+with `--template <NAME>`; a `title:` key on any slide is then an error, because a legacy template
+has one title look. The gate treats a legacy deck's variety checks (OF-110, OF-111) and the label
+check (OF-114) as MEDIUM: the user asked for one look, so low variety is reported, not failed. The
+reply still names two tonalities as alternatives.
+
+## Failure patterns this step prevents
+
+- **Same pack for every topic.** If the last three decks in a session all compiled under one pack
+  and the briefs differ, rerun step 3 honestly.
+- **Pack picked for its colour.** The colour is the least important part of a pack. Choose by
+  delivery, content shape and the families the outline needs.
+- **A pack that cannot carry the outline.** Discovered at compile time as a log note such as
+  `slide 6: table-insight is not a atlas layout family ... drawn with its own geometry`. That slide
+  then borrows geometry from outside the pack; change the pack or the slide's job.
+- **Silent dial moves.** A density of 6 written into the frontmatter without a card line is the
+  same as a silent style change.
+- **Asking instead of building.** A bare request answered with "which style do you prefer?" has
+  failed the step.
+- **Choosing by example deck.** The worked examples in `examples/` show what each pack looks like
+  with real content; they are not templates to copy. Write the user's deck from the user's facts.
+
+## Where to go next
+
+- `tonalities/<id>.md`: what each pack is for, its role map, families and variants.
+- `title-treatments.md`: the eight title treatments and how a slide gets one.
+- `layout-families.md`: what each family holds and what the source must contain for it.
+- `density-and-fill.md`: the density steps, readable floors, fill policies and what to write per
+  slide so the gate passes on substance rather than padding.
+- `examples/`: twelve compiled decks across all eight packs, each passing
+  `node <skill>/run.mjs qa`.