mixdog 1.0.10 → 1.0.12

package/src/defaults/skills/pdf/SKILL.md

@@ -26,20 +26,23 @@ A PDF is a fixed rendering to read faithfully or a document to produce: a new do
 6. Close a read-only session when done; anything that changed the file ends with `action:'finalize' session:<id> review:true`.
 
 ## Create
-**Default — HTML for a new document**: a new PDF is written as one HTML document and printed with `office action:'author' path:<file.pdf> script:<html>`; read `references/html.md` before writing the HTML. The browser lays out CSS (grid, flex, inline SVG charts, Hangul line breaks) far better than blocks can. Choose the kind of document first (`references/html.md` §1):
-- **Designed pages — the default for anything a reader judges by its look**: a report, proposal, one-pager, brochure, certificate, or handout. Each sheet is one `<section class="slide">` under the pptx skill's own frame: load the `pptx` skill (Skill name:"pptx") and follow its brief, direction, composition, writing, and HTML route as written, with the differences `references/html.md` §2 lists. `author` runs the deck's gates, measured audit, and receipt on the pages, then prints the HTML itself; finalize takes the deck's scored critique.
-- **Flowing text**: a contract, manual, letter, or long report the browser paginates by itself (`references/html.md` §3-§9).
+**Step 1 — design for the content and reader**: choose the structure, type, palette, and density for the intended use. Existing files, templates, and brand requirements take precedence. `${MIXDOG_SKILL_DIR}/../pptx/references/concepts.md` is optional inspiration, not a required selection; `concept:` is optional free text. Neither a prescribed motif nor a fixed colour, whitespace, or layout ratio is required.
+
+**Default — HTML for a new document**: write the layout in HTML/CSS and print with `office action:'author' path:<file.pdf> script:<html>`; read `references/html.md` first. The browser handles grid, flex, inline SVG, and Hangul line breaks. Choose the page model from the content (`references/html.md` §1), not a style catalogue:
+- **Designed pages**: a document a reader judges by its look and meets page by page — a brochure, one-pager, certificate, handout, proposal or report built as composed spreads. Each sheet is one `<section class="slide">` under the pptx skill's own frame: load the `pptx` skill (Skill name:"pptx") and follow its brief, direction, composition, writing, and HTML route as written, with the differences `references/html.md` §2 lists. `author` runs the deck's gates, measured audit, and receipt on the pages, then prints the HTML itself; finalize takes the deck's scored critique.
+- **Flowing text**: a document whose text the browser paginates by itself — a contract, manual, letter, essay, or a long report with running prose and tables (`references/html.md` §3-§9).
 
 The blocks below stay for two cases: a fillable form (the browser prints form controls as pictures, never as fields — or print the page from HTML and add the fields with `add_form_field`), and a small document generated from data with no design of its own. With no local Chrome or Edge, `author` fails with `html_failed` naming the launch error, and the blocks are the route.
 
 **Blocks route**:
-- Plan the reading purpose, type hierarchy, margins and page flow, then specify block styles directly. The writer supplies flow, not an art direction. `design.profile` explicitly opts into a preset; otherwise it does not inject a palette or redesign supplied blocks. A representative page is optional when it resolves a real design uncertainty.
+- Plan the reading purpose, type hierarchy, margins and page flow, then specify block styles directly. The writer supplies flow, not an art direction. `design.profile` explicitly opts into a preset; otherwise it does not redesign supplied blocks. Its default ink is a neutral one; `properties.palette` (below) sets the concept's colours for the blocks that carry colour. A representative page is optional when it resolves a real design uncertainty.
 - `office action:'create' path:<file.pdf> format:'pdf' blocks:[...] fields:[...] properties:{ title, author, subject, keywords, pageSize:'a4'|'letter'|[w,h], orientation, margin, fontPath, pageNumbers, footer }`, then render and review before finalizing.
 - Blocks: `{ type:'heading', text, level:1-3, size }`, `{ type:'paragraph', text, size, color, after }` (`\n` breaks a line; unspaced text wraps by character), `{ type:'list', items:[…], marker, ordered:true, indent }` (the marker is drawn with a hanging indent, so never type `• ` into a paragraph), `{ type:'table', rows, headers, columnWidths:[weights], columnAlignments:['left','right'], rowHeight, fontSize, headerFill, headerColor }` (the header row repeats after a page break; cells wrap and rows grow; without `columnAlignments` a column of figures — `₩2,400,000` and `$120` included — is set right and a label column — including `1호`, `2호` — stays left; the anatomy is the Word one: a bold header on a rule, hairlines between rows, no vertical rules, `grid:true` for the full cell grid; `headers:false` for a table with no header row, such as the totals under an invoice's lines — give that block the `x` and `width` of the figure columns it closes, so each total stands under its column rather than across the page from its label; `totalRow:true` sets the last row bold under a rule), `{ type:'image', path, width, height, align:'center'|'right' }` (PNG or JPEG; fits the text width unless sized), `{ type:'pagebreak' }`.
-  The document anatomy beyond prose, each one block the writer flows the same on every page: `{ type:'cover', eyebrow, title, subtitle, meta:[…] }` (the title group of the first page — eyebrow in the accent, title, subtitle, meta lines, one rule under; the summary follows on the same page unless a `pagebreak` says otherwise), `{ type:'stats', items:[{ value, label }] }` (several figures with one cause on one baseline, equal columns, one rule under — at most four, and every value is a fact with a source), `{ type:'callout', label, text, fill }` (a tinted field with its label above the text: the conclusion, a warning, the ask; never split across pages), `{ type:'quote', text, attribution }` (someone else's words behind a rule in the accent, the attribution a caption under), `{ type:'chart', categories:[…], values:[…], chartType:'bar'|'column', unit, highlight, title, height }` (one series drawn by the page in the document's face: `bar` lays the bars across — a ranking, its names on the left — and `column` stands them up for periods left to right; every bar carries its value (`unit` follows the number: `'건'`, `'%'`), there is no grid, and `highlight` — an index or a category — takes the accent while the other bars recede; values are zero or more, one per category; a `caption` right after it travels with it), `{ type:'caption', text }` (the small muted line under a table, picture, or chart: what it shows and its source), `{ type:'rule' }` (a hairline between sections). Body copy leads at 1.5× its size so Hangul lines breathe; a heading keeps 1.2× and never ends a page. A report is: cover → callout (the conclusion) or stats → headings with prose, tables with captions → quote where a voice carries the point → closing callout (the ask); an essay is headings and prose alone.
+  The document anatomy beyond prose, each one block the writer flows the same on every page: `{ type:'cover', eyebrow, title, subtitle, meta:[…] }` (the title group of the first page — eyebrow in the accent, title, subtitle, meta lines, one rule under; the summary follows on the same page unless a `pagebreak` says otherwise), `{ type:'stats', items:[{ value, label }] }` (several figures with one cause on one baseline, equal columns, one rule under — at most four, and every value is a fact with a source), `{ type:'callout', label, text, fill }` (a tinted field with its label above the text: the conclusion, a warning, the ask; never split across pages), `{ type:'quote', text, attribution }` (someone else's words behind a rule in the accent, the attribution a caption under), `{ type:'chart', categories:[…], values:[…], chartType:'bar'|'column', unit, highlight, title, height }` (one series drawn by the page in the document's face: `bar` lays the bars across — a ranking, its names on the left — and `column` stands them up for periods left to right; every bar carries its value (`unit` follows the number: `'건'`, `'%'`), there is no grid, and `highlight` — an index or a category — takes the accent while the other bars recede; values are zero or more, one per category; a `caption` right after it travels with it), `{ type:'caption', text }` (the small muted line under a table, picture, or chart: what it shows and its source), `{ type:'rule' }` (a hairline between sections). Body copy leads at 1.5× its size so Hangul lines breathe; a heading keeps 1.2× and never ends a page. Which of these a document uses follows its genre: a decision report may open on a cover and a callout or stats strip, a letter or essay is headings and prose alone, a data log is a table with captions; a callout, quote, or closing ask appears only where the content has that job, and the order is not fixed.
+  `properties.palette: { accent, muted, field, line }` (six-digit hex without `#`, all optional) overrides the writer's default ink for the cover eyebrow and rule, callout, quote rule, stats, chart bars, and table header and rules: `accent` the one emphasis colour, `muted` captions and labels, `field` the tinted callout and stat ground, `line` rules and hairlines. Take the four from the chosen concept's roles (`accent`, `muted`, `tint`, `line`).
   A form the reader fills travels with the copy that introduces it: `{ type:'field', name, label, fieldType:'text|checkbox|radio|dropdown|optionlist', height }` and `{ type:'fieldRow', items:[{ name, label, type }], gutter }` flow like any other block (a `checkbox` or `radio` is drawn as a square with its label beside it, a typed box with its label above; a `radio` with `options:[…]` is a question — its label above, the options in one row, each mark with its own words beside it; a `caption` right after a field block travels with its last row), so the writer fixes the page and the coordinates where the reader meets them, and a heading is never left on the page before its own boxes. Fields passed in `fields:[…]` keep the absolute `page`/`x`/`y` they were given, which is what stamping a form onto a scan needs.
   The block list is checked before anything is written: an unknown `type`, a block named with `kind`, an unknown field, or a missing `rows`/`items`/`text` is refused with every fault at once, instead of flowing as an empty paragraph. The writer flows and paginates; `pageNumbers` is on for multi-page output (`N / total`, bottom right) unless set `false`.
-- Fonts: the standard fonts cover Latin only. Korean, CJK, Cyrillic, or Greek text embeds a Unicode font found on the system (Malgun Gothic on Windows, Nanum/DejaVu/Noto on Linux); `properties.fontPath` chooses one, the result's `font.path` says which was used, and `action:'detect'` names it beforehand as `portable.pdfUnicodeFont`. When none is installed the call fails with the hint: ask for a font file rather than transliterating.
+- Fonts: the standard fonts cover Latin only. Korean, CJK, Cyrillic, or Greek text embeds a Unicode font found on the system (for example Malgun Gothic or Noto on Windows, Nanum/DejaVu/Noto on Linux); a PDF embeds what it drew with, so the reader needs no font. `properties.fontPath` chooses one, the result's `font.path` says which was used, and `action:'detect'` names it beforehand as `portable.pdfUnicodeFont`. When none is installed the call fails with the hint: ask for a font file rather than transliterating.
 - Form fields: `{ name, label, type:'text|checkbox|radio|dropdown|optionlist', page, x, y, width, height, value, options, multiline, maxLength, fontSize, labelSize, required, readOnly }` — a PDF field is a bare box, so `label` is the caption drawn above it (without one the page reaches the reader as unnamed rectangles), and the box may be written as `rect:[x, y, width, height]`; the layout is linted before writing — missing or duplicate names and out-of-page boxes fail, overlaps and boxes too small to use (under 24 × 12 pt typed, 8 × 8 pt marks) come back as `formIssues` on the result. A field that belongs with the copy around it is better declared as a `field` or `fieldRow` block, which flows with that copy instead of holding a page number the text may have moved off.
 
 ## Edit

package/src/defaults/skills/pdf/references/html.md

@@ -1,16 +1,16 @@
 # HTML route (PDF)
 
-Owns the default route for a new PDF: the model writes one HTML document and passes it as `author`'s `script`; a local Chrome or Edge lays it out under the document's own `@page` rules, the runtime checks it, and the browser prints it — text stays text, headings become bookmarks, the file is tagged. Everything else in SKILL.md (render, finalize, the rules) applies unchanged.
+The default route for a new PDF: the model writes HTML/CSS for the content and intended reader, without selecting a preset, and passes it as `author`'s `script`. A local Chrome or Edge lays it out under the document's own `@page` rules, the runtime checks it, and the browser prints it — text stays text, headings become bookmarks, and the file is tagged. Inspect the printed pages for breaks, clipping, missing content, and readability before finalizing.
 
 ## 1. Two kinds of document
 The HTML itself says which one it is: `<section class="slide">` pages make it designed pages (§2); anything else flows (§4-§8).
 | | Designed pages (§2) | Flowing text (§4-§8) |
 |---|---|---|
-| For | reports, proposals, one-pagers, brochures, certificates, handouts — anything judged by its look | contracts, manuals, letters, long running text |
+| For | one-pagers, brochures, certificates, handouts, proposals and reports composed as spreads — anything judged by its look and taken in page by page | contracts, manuals, letters, essays, and reports of running prose and tables |
 | Pages | one `section.slide` per sheet, composed like a slide | the browser paginates the flow |
 | Frame | the pptx skill's: brief, plan and facts gates, geometry gate, measured audit, receipt, scored critique | this file's checks and the per-page critique of SKILL.md |
 
-**Default — designed pages** whenever the document has a cover, key figures, or pages a reader takes in at a glance; flowing text when the content is read straight through and its length decides the page count.
+**The route follows the page model, not a concept id**: designed pages when each sheet is a composed unit or a fixed page count is needed; flowing text when the content is read straight through and its length decides the page count. Either can be a report.
 
 ## 2. Designed pages — the deck's frame
 Load the `pptx` skill and follow it as written for the brief (SKILL.md §3: `subject/audience/action`, `directions`, `style`, `facts`, `slide plan`), the workflow, `direction.md`, `composition.md`, `writing.md`, and its HTML route (`references/html.md`); the PDF differs only here:
@@ -18,7 +18,7 @@ Load the `pptx` skill and follow it as written for the brief (SKILL.md §3: `sub
 - **Type in pt**: here 1 px is 0.75 pt (the deck's canvas runs 0.5 pt per px), so take the pptx references' roles, not their px. A page is read in the hand, not projected: the `text` reading mode of `direction.md` §1, body 9.5–11 pt, captions 7.5–8.5 pt (the audit's print floors: body 9 pt, a one-line caption or note 7 pt, never the deck's screen 12 / 9 pt), page titles 20–32 pt, a hero numeral 60 pt and up; the plan's `hero` promise reads 40 pt+, `statement` 22 pt+. Margins 15–20 mm.
 - **Charts are `data-chart`**, written exactly as the pptx HTML route's §5 (type, labels, values or series, colors, min/max, format, labelColor, size in pt, legend, grid, valueAxis, categoryAxis, gap, stacked, hole, plot): the deck frame reads it as a native chart (a plan line names it `chart`), and the runtime draws the same spec as an inline SVG on the page before it prints, value labels as text. A chart no spec covers (a dumbbell, an annotated line) is an inline `<svg>` drawn from the facts' values and named `picture` in the plan. `<table>` (`table`), `<img>`, and `data-icon` print as drawn.
 - **Every page prints**: each `section.slide` goes on its own sheet and stays displayed in print (never hide the inactive ones in CSS); `aside.notes` is not printed. Pages that print onto more sheets than there are slides are refused.
-- **No margin boxes**: with `margin: 0` there is nowhere for `@page` page numbers — set the folio and running head inside the slide, as the deck sets its page number. `h1`–`h3` still become bookmarks.
+- **No margin boxes**: with `margin: 0` there is nowhere for `@page` page numbers — set the folio and running head inside the slide, as the deck sets its page number, if the concept's chrome has them at all (a brand or statement page carries none). `h1`–`h3` still become bookmarks.
 - **What comes back**: `designedPages: true`, the deck's `audit` (`status` pass/fail, top targets), `receipt` (with the printed pages' render readings), `render.contactSheet`, and `logs`; a later `render` on the session returns the receipt and contact sheet again, and `qa` adds the brief's readings (`plan_count_mismatch`, `fact_without_locator`). Refusals are the deck's: `html_failed`, `geometry_gate`, `plan_gate`, `facts_gate`. There is no `render.compare`: the PDF is the browser's own print.
 - **Finalize** takes the pptx skill's critique (its SKILL.md §5), one entry per page keyed `page` (or `slide`): `verdict`, the five scores, a page-specific `note`, `fixes`, `checks`; an anchor page carries `role`. An error the audit found holds finalize until the HTML is fixed and authored again.
 - Copy that outgrows its page is split onto another page or cut (the deck's rule); content whose length should decide the page count is flowing text instead.
@@ -35,29 +35,34 @@ Load the `pptx` skill and follow it as written for the brief (SKILL.md §3: `sub
 **Hard rule — pictures are local**: `<img src>` is a file beside the PDF (relative paths resolve from its folder) or a `data:` URI; a web URL is refused, and so is a picture that did not load. There is no network: no CDN fonts, scripts, or stylesheets. → runtime `layout_gate` (`remote_image`, `image_missing`)
 **Hard rule — nothing wider than the page**: a table, a code block, a picture, or a row of cards wider than the printable width is cut at the margin by print. Give pictures `max-width: 100%`, let tables wrap their cells (`table-layout: fixed` with column widths in %), and wrap long code. A box inside a container with `overflow: hidden` is the container's business and is not reported. → runtime `layout_gate` (`overflow_x`)
 - A full-bleed cover before a flowing body uses a named page: `@page cover { margin: 0 }` with `.cover { page: cover; break-after: page; }`.
-**Default — the brief and its facts**: an optional `<!-- BRIEF` … `-->` comment at the top, one `key: value` per line (`subject/audience/action`, `sources`, `facts: F1 2,400건 — 운영 시트 B4 · F2 …`). When it is present, every figure the printed pages show that no fact carries comes back in `facts` (`pages[].figures`); it is reported, not refused — answer it by adding the fact with its source or correcting the figure. `facts: sample — <why>` marks every figure illustrative, and the delivery says so. Dates, page counters, and small ordinals are not figures.
+**Default — the brief and its facts**: an optional `<!-- BRIEF` … `-->` comment at the top, one `key: value` per line (`subject/audience/action`, optionally `concept: <free text>` (`concepts.md` §1), `sources`, `facts: F1 2,400건 — 운영 시트 B4 · F2 …`). When it is present, every figure the printed pages show that no fact carries comes back in `facts` (`pages[].figures`); it is reported, not refused — answer it by adding the fact with its source or correcting the figure. `facts: sample — <why>` marks every figure illustrative, and the delivery says so. Dates, page counters, and small ordinals are not figures.
 
 ## 5. Flowing text: pages and breaks
-- **Running head, foot, and page numbers** live in the `@page` margin boxes, never in the body: `@page { @bottom-right { content: counter(page) " / " counter(pages); font: 8.5pt 'Malgun Gothic'; color: #6B7280; } @top-left { content: "분기 운영 보고서"; … } }`. `counter(page)` works only there. Turn them off on a cover with `@page :first { @bottom-right { content: none } }` or the named cover page.
-- **Breaks**: `h1, h2, h3 { break-after: avoid; }` keeps a heading with what follows; `figure, table.compact, .callout, .card, tr { break-inside: avoid; }` keeps a unit whole; `p, li { orphans: 2; widows: 2; }`; `thead { display: table-header-group; }` repeats a long table's header on every page; `break-before: page` opens a chapter on a new sheet. A block that may not break but is taller than a page breaks anyway — the result warns `unbreakable_too_tall`; shorten it or let it break. A kept block that moves on leaves the page before it short: `qa` and finalize report a page before the last whose body stops above 70% of its height as `page_bottom_empty`, so keep only short units whole.
+- **Running head, foot, and page numbers** are a choice of the concept, and when present live in the `@page` margin boxes, never in the body. `counter(page)` works only there. Pick one variant (none is also right for a letter, a short document, or a statement piece), with the face and colour from the concept's roles:
+  - running head top-right, folio bottom-right (a long filed report): `@page { @top-right { content: "분기 운영 보고서"; font: 8.5pt <face>; color: <muted>; } @bottom-right { content: counter(page) " / " counter(pages); font: 8.5pt <face>; color: <muted>; } }`
+  - centred folio alone (a manual, an essay): `@page { @bottom-center { content: counter(page); font: 9pt <face>; color: <muted>; } }`
+  - folio only on the inside edge, small (an editorial piece): `@page :left { @bottom-left { content: counter(page); … } } @page :right { @bottom-right { content: counter(page); … } }`
+  - none: no margin boxes at all (a letter, a notice).
+  Turn them off on a cover with `@page :first { @top-right { content: none } @bottom-right { content: none } }` (naming every box the document sets) or the named cover page.
+- **Breaks**: `h1, h2, h3 { break-after: avoid; }` keeps a heading with what follows; `figure, table.compact, .callout, .card, tr { break-inside: avoid; }` keeps a unit whole; `p, li { orphans: 2; widows: 2; }`; `thead { display: table-header-group; }` repeats a long table's header on every page; `break-before: page` opens a chapter on a new sheet. A block that may not break but is taller than a page breaks anyway — the result warns `unbreakable_too_tall`; shorten it or let it break. A kept block that moves on leaves the page before it short: `qa` and finalize report a page before the last whose body stops above 70% of its height as `page_bottom_empty`, so keep only short units whole. A deliberate chapter or section break that leaves a page short is fine when the finalize critique says it is deliberate.
 - **Backgrounds print**. A colour field or band behind a section prints as drawn; `position: fixed` repeats on every page, so use it only for a deliberate watermark or edge band.
 - **Bookmarks** come from `h1`–`h3`: keep heading levels true to the structure (one `h1` for the title, `h2` per section), and never fake a heading with a styled `div`. A heading set on two lines with `<br>` keeps the space in its bookmark.
 - **Not in the browser**: running heads taken from the content (`string-set`), table-of-contents page numbers (`target-counter()`), footnotes (`float: footnote`), and `leader()`. A contents list names the sections without page numbers (the bookmarks carry the navigation), and notes are endnotes.
 
 ## 6. Text and fonts (both kinds)
 - Set `word-break: keep-all; overflow-wrap: break-word` on `body`, `text-wrap: pretty` on prose, `text-wrap: balance` on headings; wrap a name that must not break in `white-space: nowrap`.
-- Faces: the browser embeds what it drew with, so a face must be installed on this machine — `'Malgun Gothic'` on Windows, `'Noto Sans KR'` / `'Noto Serif KR'` where installed, Latin system faces. A face that is missing falls back silently: list the installed face first and a generic family last, and check the render.
-- Sizes in `pt` or `mm`: body 10–11.5 pt with `line-height` 1.55–1.7 for Hangul, captions and running heads 8–9 pt, headings by a clear step (title ~24–32 pt, section ~15–18 pt). Measure: 30–40 Hangul characters per line for body copy; a full-width A4 column runs long, so a report body often sits in a narrower column beside a side rail for captions or key figures.
-- Contrast 4.5:1 for body text, 3:1 for 14 pt bold and up. A weight renders only if the face has it (Malgun Gothic has regular and bold); a missing weight is synthesized or rounded.
+- Faces: the browser embeds what it drew with, so the reader needs no font — but the face must be installed on this machine. Choose from the concept's menu (`concepts.md` §5): a sans (`'Noto Sans KR'`, `'Malgun Gothic'`), a serif (`'Noto Serif KR'`, `'Batang'`), or a serif-over-sans mix, with a Latin face named beside it. A face that is missing falls back silently: list the installed face first and a generic family last, and check the render.
+- Sizes in `pt` or `mm` (the one document scale, shared with Word): body 10–11 pt with `line-height` 1.6–1.7 for Hangul, captions and running heads 8.5–9 pt, headings by a clear step (title ~24–32 pt, section ~15–18 pt, subsection 12–13 pt). Measure: 30–40 Hangul characters per line for body copy; a full-width A4 column runs long, so a report body often sits in a narrower column beside a side rail for captions or key figures.
+- Contrast 4.5:1 for body text, 3:1 for 14 pt bold and up. A weight renders only if the face has it (Malgun Gothic has regular and bold; Noto families carry more); a missing weight is synthesized or rounded.
 
 ## 7. Tables, charts, pictures
-- **Tables** are real `<table>` with `<thead>`: a bold header on a rule, hairlines between rows, no vertical rules unless the grid carries meaning; figures right-aligned with `font-variant-numeric: tabular-nums`, labels left; a total row bold under a rule. A caption under it says what it shows and its source.
+- **Tables** are real `<table>` with `<thead>`; the treatment is the concept's — ruled (bold header on a rule, hairlines between rows), zebra (alternating `tint` rows, no rules), open (one rule under the header, wide rows), or a full grid (forms, parameter tables) — and no vertical rules unless the grid carries meaning; figures right-aligned with `font-variant-numeric: tabular-nums`, labels left; a total row set apart. The first listed is not a default. A caption under it says what it shows and its source.
 - **Charts** are `data-chart` on an empty, sized element (the spec of §2), drawn by the runtime as SVG before printing; a chart no spec covers is an inline `<svg>` with numbers computed from one set of values (bar length = value / max × width), not typed separately. Either way: direct value labels, no gridline clutter, the subject's bar or point in the accent and the rest receding, the unit in the format (`"#,##0\"건\""`). JavaScript runs, but a chart library must be inlined, since nothing loads from the network.
 - **Pictures**: `<img>` with `alt`, `max-width: 100%`, `object-fit` for a crop. A generated picture is mood or illustration, never evidence (figures, screenshots, and product UI are real or absent). Flowing text has no `data-icon`: draw icons as inline SVG (designed pages have it, §2).
 
 ## 8. Flowing text: design pass
 Designed pages take the pptx skill's design pass instead. Before writing flowing HTML, plan once and check the plan against the defaults:
-1. **Plan** from the subject and the sources: palette of 4–6 hex values with roles (paper, ink, muted ink, one accent with one job, one tint for fields); type roles in pt; the grid (margins, column, side rail); the document anatomy — cover or title block → the conclusion first (a callout or a row of key figures) → sections with their evidence → the closing ask.
+1. **Plan** from the subject and the sources, in the chosen concept (`concepts.md`): the palette roles (`paper`, `ink`, `muted`, `line`, `tint`, `accent`, optional `accent2`) as CSS custom properties; type roles in pt from the face menu; the grid (margins, column, side rail); the anatomy the genre calls for — a report may lead with its conclusion, an essay with its first paragraph, a letter with the sender block, a manual with contents. Emphasis carriers are a choice: a boxed note, a tinted band, a margin note, a left-rule quote, an oversized numeral, or no callout; the first listed is not a default. Write this document's stylesheet fresh.
 2. **Check**: one anchor per page (the first thing the eye lands on is that page's claim); three tiers of space (inside a unit < between units < around sections); proximity carries relation (a label nearer its value than the next value); decoration never stands in for content. Avoid the generated look unless the brief asks for it: cream paper with a serif and a terracotta accent, an all-caps tracked label over every heading, identical rounded cards with one soft shadow, gradient washes, centred everything.
 
 ## 9. Review

package/src/defaults/skills/pptx/SKILL.md

@@ -16,7 +16,7 @@ Use `office` to create, redesign, and review PowerPoint decks. Read this guide
 before the first deck operation. A new deck is written as HTML slides by default
 (`references/html.md`); the pptxgenjs script and its kit remain the second route.
 
-The model designs; the runtime measures. The kit supplies editable primitives, not a required visual style. Facts, safety, file integrity, legibility, and current rendered review remain mandatory. Palette, typography scales, spacing ladders, layout recipes, and stylistic avoid lists are defaults: adapt them to the audience, brand, or reference deck rather than sacrificing the result to match a recipe. Existing accessible product assets and user materials precede generated imagery; the runtime has no photo library.
+The model designs; the runtime converts and measures. Write HTML/CSS for the actual content, audience, and use, not to fill a predefined layout. Facts, safety, file integrity, legibility, and current rendered review remain mandatory. Palette, typography, spacing, motifs, density, repetition, and layout recipes in the references are optional examples, not requirements or acceptance criteria. Neither a named concept nor a style score proves quality. Existing accessible product assets and user materials precede generated imagery; the runtime has no photo library.
 
 ## 0. Route by task
 | Task | Route | Done when |
@@ -30,8 +30,9 @@ Prerequisites: the Office capability (`metadata.requires`) — its portable back
 ## 1. Load routing
 | File | Owns | Read when |
 |---|---|---|
-| `references/direction.md` | reading mode, argument mode, visual styles, representative direction trials, palette from a seed, typography | always, before the brief |
-| `references/composition.md` | the page brief, relationship atoms, composition lenses, page recipes, starting structures, spacing, lines and surfaces, rhythm, text, device menu, component specs, icons, machine tells | always, before the slide plan |
+| `references/concepts.md` | optional examples of palette, type, and document treatments | only when examples help resolve an open design choice; no id must be selected |
+| `references/direction.md` | reading modes, argument structures, and visual direction examples | when the reading mode or direction is unclear |
+| `references/composition.md` | relationship vocabulary, composition examples, and script-kit devices | when a page needs composition help or a script-kit device |
 | `references/writing.md` | sentence rules, one register, the notation of numbers, dates, money, and units, room for translation, the read-back | always, before the copy (§2 step 2) |
 | `references/html.md` | the HTML route: the document contract, the brief as an HTML comment, what CSS converts to, text and fonts, `data-chart`, icons and SVG, the `images:` plan, the one-shot design pass and the generated-look list, review with `render.compare` | always for a new deck on the HTML route, before the plan; it replaces `kit-index.md` there |
 | `references/kit-index.md` | every helper of `kit.md`, `charts.md`, and `pictures.md` by signature, defaults, and the guidance above it, with the kit's rules — read it instead of those files' code: tokens, `palette()`, `typography()`, masters, measured text (`reading()` and `columns()` for the commentary beside or under a carrier — both refuse a block that would cross the foot; `avail(top)` measures the height first), the anchors of a deck without pictures (`poster()`, `numeralBeat()`, `motif()`, `orb()` — the beat's one hero object; `display()` and `dateline()` for the editorial text page on paper; `emph:` for the headline's contrast phrase), layout by weight, shapes (`stage()` — the context field a structure stands on; `shareDown(top, columnsH(...))` when the reading sits under it, `readingH()` to register a reading to its row, `loop(s, st, …)` / `hub(s, st, …)` for radii from the stage), the relationship structures (timeline, steps, hub, loop, merge, tiers, lanes, quadrants, venn, quote, brace groups) | always on the script route, before the script |
@@ -40,11 +41,11 @@ Prerequisites: the Office capability (`metadata.requires`) — its portable back
 | `references/review.md` | representative direction trials, source questions, independent image review | for a new visual direction, substantive redesign, or quality comparison |
 
 ## 2. Workflow
-1. Read the always-loaded references; add `pictures.md` only on its trigger (chart helpers are in the index). Before choosing a visual direction, identify the available brand assets, product views, and reference deck (`direction.md` §4). For a product pitch, select the real view or artifact that demonstrates the benefit before substituting a generic diagram. No generation lane does not imply no pictures. **Default — the picture lane is checked, not assumed**: when the plan wants a picture no supplied asset covers, load the `image` skill and `list` its lanes before authoring, so the deck knows whether one can be generated at all. A picture is generated only where the user asked for one or the claim needs the artifact itself; a signed-in lane is not a reason to add imagery. With no lane the picture is omitted, the page anchors on the drawn devices instead (`spot()`, `orb()`, `poster()`, `motif()`), and the delivery says the deck went without generated pictures. Done when the brief names each selected asset and its source, or explains why typography or a conceptual diagram is more faithful.
+1. Read the HTML contract and writing guide; load other references only for the decisions they help. Identify supplied brand assets, product views, and reference material. For a product pitch, prefer the real artifact that demonstrates the benefit to an interchangeable diagram. When an illustration is needed and authorized but no supplied asset covers it, load the `image` skill and check its lanes; do not assume generation is available or add imagery merely because it is. Without it, choose a faithful text or drawn explanation and disclose any unmet image requirement. Done when selected assets and their sources are known.
 2. Ground: with source material, read it and write the fact sheet (each figure with its page or cell) before any outline; then the outline as assertion titles that read as one argument in sequence (`references/writing.md` for the sentence and notation rules). Done when every figure the outline will show has a fact line with a locator (§3).
    **Hard rule — copy is rewritten, never reinvented**: slide copy is condensed from the source in the deck's language with the source's own vocabulary; entity names, product names, figures, and abbreviations stay in their original form; a figure the source does not contain is not on the slide. → runtime `number_without_fact` for figures; wording → manual
-3. Direct: define plausible directions, then compare two rendered compositions of the same representative content when the direction is open (`direction.md` §4; `references/review.md`). Select by reader understanding and visual craft, not style names; a fixed template or small edit keeps its approved direction. A preferred color alone does not settle composition. Use the kit palette and type as starting points, or adapt its tokens to the brand before creating slides. Done when the brief records the selection and the visible reason, not merely a named style.
-4. Plan each slide before any geometry (`composition.md` §0): job, relationship, move, composition, carriers, texture, rhythm. Decide what the reader should understand from the visual itself; choose the relevant evidence or a faithful visual explanation before arranging the remaining copy. Content over the mode's budget is split or cut, never squeezed. Then the deck's sequence in the brief's `rhythm:` line (`composition.md` §7: the marks — cover, section fields, closing — 5-13 evidence pages apart, the page grammar turning about every other page, never the same grammar on five in a row, a quiet page answered by colour within two), checked in the receipt's `deck.shape` before the render. Done when every slide has its plan line (§3).
+3. Direct: choose the reading order, type, palette, density, and structure for this request. Supplied templates and brand requirements take precedence. A `concept:` line is optional free text, not a catalogue selection. Related deliverables share facts and any requested identity, not necessarily layouts. Compare representative rendered pages only when it resolves a real uncertainty; an existing approved direction needs no contest. Done when the design has a reason grounded in the content and reader.
+4. Plan each slide's purpose, relationships, composition, and carriers in the brief (§3). Describe the layout in ordinary words, without selecting a recipe. Use as much space and repetition as the content needs: a comparison series may repeat a layout, a statement may be sparse, and an evidence page may be dense. Preserve the facts and qualifications; split content when it cannot remain readable rather than shrinking or deleting evidence. Done when every slide has a plan line describing what it actually carries.
 5. HTML route: the brief (§3) as a `<!-- BRIEF -->` comment, then one `<section class="slide">` per page, written after the design pass of `references/html.md` §8; the rest of this step is the script route. Script: the brief (§3) as a comment block, then `deck({ style, hue, accentHue?, mode, script, pairing, fonts })` — the brief's style id is passed here, not only written down — then the slides. The runtime runs the kit — the code blocks of `kit.md`, `charts.md`, and `pictures.md` — before the script, so the script never pastes a helper (it may redefine one). Each slide is measured down before it is drawn — `const top = head(…)`, `avail(top)` for the height left, `shareDown(top, columnsH(…))` / `readingH()` when a row or rail shares it, then the carrier on the stage or column those give (`composition.md` §4 "measure down before drawing"; the helpers refuse under their floors and name the fix, so no y or h is guessed) — and drawn spine → nodes → connectors → labels → garnish; every text box is measured (`MEASURE` through the kit helpers).
 6. `office action:'author' path:<deck.pptx> script:<html or pptxgenjs script>` (a source that opens with `<` is read as HTML; `overwrite:true` when re-authoring the same path) writes the file, opens the session, and returns three things (the HTML route adds `render.compare`, the HTML beside the PPTX render per page):
    - **pages** — every slide rendered and one contact sheet of the whole deck (unless `render:false`); the rendered pages come back as `images[]` (`page`, `path`) with the sheet as `contactSheet` (its file is always written; its image is attached past four slides, since a shorter deck's pages already show the sequence), and `pageCount` says how many the deck has;
@@ -70,6 +71,7 @@ Prerequisites: the Office capability (`metadata.requires`) — its portable back
 ```
 // BRIEF
 // subject/audience/action: <what this deck must make someone do>
+// concept: <optional free-text design intent; no catalogue id required>
 // reading mode: presentation | balanced | text · argument mode: pyramid | narrative | instructional | showcase | briefing
 // directions: A <style, seed hue, pairing, motif — one-sentence note> · B <…> · selected: <A|B> · why: <visible reason from trial, or fixed-template constraint>
 // style: <direction.md §3 id or custom> · palette: hue <deg> [· accent hue <deg>] · accent: <hex> · type: MODE <mode> → body <pt> · script: ko | ja | zh | latin · pairing: serif | weight | concord · fonts: noto | safe

package/src/defaults/skills/pptx/references/composition.md

@@ -2,14 +2,14 @@
 
 Owns how one slide is composed once the direction exists (`direction.md`). This is vocabulary the author composes with, not a catalog the slide picks from: there is no slide type to select, only a page job, a relationship, and a composition move the author decides before writing a coordinate. `kit.md` draws the core page, `charts.md` adds native data carriers, and `pictures.md` adds the picture families.
 
-Rule strength as in `direction.md`: **Hard rule** (with `→ runtime \`code\`` or `→ manual`), **Default**, **Reference**.
+Use this file as optional vocabulary and script-kit guidance. Layout recipes, density targets, rhythm intervals, type sizes, and decorative treatments are examples, not quotas for an HTML-authored page. Semantic relationships, explicit carrier promises, legibility, and the kit's actual geometry constraints still apply.
 
 ## 0. The page brief — decided before geometry (one plan line per slide)
 Each slide's plan line in the brief (`SKILL.md` §3) names, in this order:
 - **job** — cover · section · claim · evidence · process · comparison · structure · picture · closing (what the page does for the reader).
 - **relationship** — the atom the content carries (§1), or `none` for a focal claim.
 - **move** — what the reader now believes, decides, or does. **Hard rule — every slide states its move**: a slide that cannot state it is an outline defect — cut it or merge it, never decorate around it. → manual
-- **composition** — the page-scale move (§2 lens + §3 recipe in ordinary words: "one dark field on the left third holding the number; evidence hangs from a vertical rule on the right").
+- **composition** — describe the intended arrangement in ordinary words; no lens or recipe must be selected.
 - **carriers** — what carries the content: chart · table · picture · hero · statement · quote · specimen · diagram · prose · list (`author` refuses a page that does not carry what its line named: `plan_promise_missing`, `SKILL.md` §3).
 - **texture** — prose · list · specimen · keywords (§8).
 - **rhythm** — anchor · dense · breathing (§7).
@@ -50,7 +50,7 @@ Before coordinates, name the move the page makes and the jobs it serves (surface
 ## 3. Page recipes — back to front, omit every layer without a job (Reference)
 | Page job | Back-to-front stack | Stop when |
 |---|---|---|
-| cover | hero field — a full accent or dark field (Naver, Sequoia), a full-bleed picture under a scrim (Samsung, NVIDIA), or paper with a wordmark and one illustration field (Kakao) → optional scrim or wash → one purposeful contour or motif at full size (`motif()`) → kicker + title + one line (date · author), never a list. Without a picture the title itself is the anchor: `poster()` sets the claim at poster scale on the field (Sequoia, a16z), and the one hero object stands on the right third — `orb()`, the lit sphere half the page tall that 13 of 26 measured mock covers carry (the object 0.26-0.67 of the canvas; a motif at low alpha reads as background and a beat without an object measures 0) | copy is safe and title and field read as one object |
+| cover | hero field — a full accent or dark field (Naver, Sequoia), a full-bleed picture under a scrim (Samsung, NVIDIA), or paper with a wordmark and one illustration field (Kakao) → optional scrim or wash → one purposeful contour or motif at full size (`motif()`) → kicker + title + one line (date · author), never a list. Without a picture the title itself is the anchor: `poster()` sets the claim at poster scale on the field (Sequoia, a16z), and the one hero object stands on the right third — a picture, a drawn artifact, a `motif()` at full size, or a numeral (not `orb()`: the glowing sphere is on the generated-look list, `html.md` §8, and stays a script-route device for a brief that asks for it; the object 0.26-0.67 of the canvas — a motif at low alpha reads as background and a beat without an object measures 0) | copy is safe and title and field read as one object |
 | section | the cover's field again with the section name (Sequoia), a progressive agenda on the dark field with the current section lit (`agenda()`, the Coatue device), the section's number at 220 pt beside its claim (`numeralBeat()`, its default `size`; the a16z opener — every section a different accent field), or the label alone on paper (Kakao), or the section on its own picture — `picture()` full-bleed under a `scrim()`, the number and name in the scrim's light (the photo section of the Sequoia and Coatue decks; the one section device that carries a picture, so a photo deck's marks are not its cover repeated) → restrained wash → the motif at half size. Three devices, one deck: the section marks vary between them, never the same beat repeated | the deck language is recognizable and the reader knows where the deck is |
 | claim | quiet field → the statement or number at scale → one emphasis run or attribution → air where it gives the focal element room (below or beside, entering high). On paper the editorial hero (the frontier text page, measured across 26 rendered mock pages, September 2026): kicker → `display()` at cover size on two lines over 45-60% of the width → the deck line at lead size → a `statBand()` of three or four peers, or the one hero object (a picture, a product, a disc) on the right third → `dateline()` and the source closing the corners. Such a page measures only 0.02-0.09 largest object; the headline at 4-5 × the body, the strip under it, and the four corners are what separate it — never a card under the text | 40-60% of the canvas is deliberately empty |
 | evidence | title (+ sub line) on the open canvas, the source line at the foot → native chart/table/leaders filling the body between them, 40-60% of the canvas → the legend, a hero figure, or the kicker in the rail → optional takeaway on the dark field | the claim is native and the evidence is the largest element |
@@ -58,7 +58,7 @@ Before coordinates, name the move the page makes and the jobs it serves (surface
 | comparison | matched planes seamed by weight → optional shared wash or divider → matched labels → one difference marker on one side only | crop, elevation, and paint stay symmetric unless asymmetry is the claim |
 | structure | one field or outline → hierarchy by nesting, indentation, or scale → labels registered to their unit | placement alone communicates with color stripped |
 | picture | the picture family from `pictures.md` §2 — on a body page almost always the artifact row (`tiles()`: three or four screenshots, stills, or clippings on one baseline, a label and a caption each) or the collage (`clippings()`); the full-bleed photograph under a scrim is a cover or section device → modifier → native type on the calm zone | the captions say what each artifact proves; text sits on a scrim or beside the picture, never on it bare |
-| closing | the cover's field echoed (every reference deck closes on its cover's field: Samsung's photo, Naver's green, NVIDIA's swoosh, Kakao's mascot) → echoed contour or gradient, the motif at a corner, the cover's hero object at half size (`orb()`) → the ask or the thanks as the one line, in the on-dark accent (`poster()` at a step under the cover's size) → contact/meta | the ask is the most legible line |
+| closing | the cover's field echoed (every reference deck closes on its cover's field: Samsung's photo, Naver's green, NVIDIA's swoosh, Kakao's mascot) → echoed contour or gradient, the motif at a corner, the cover's hero object at half size → the ask or the thanks as the one line, in the on-dark accent (`poster()` at a step under the cover's size) → contact/meta | the ask is the most legible line |
 
 ## 4. Starting structures — relationship → geometry (Reference, first placements only)
 Canvas 13.33 × 7.5 in, margin `M` 0.6; safe area x 0.6-12.73, y 0.6-6.9. Proportion follows information weight; these are first placements, not slots.

package/src/defaults/skills/pptx/references/concepts.md

@@ -0,0 +1,168 @@
+# Design concepts
+
+Optional inspiration for decks, Word documents, PDFs, and Excel report sheets. The model designs from the request and content; it does not have to select an entry here. These examples group palette, type, headings, tables, emphasis, charts, chrome, and density to illustrate possibilities, not to prescribe templates or acceptable styles.
+
+Every palette formula, face menu, ratio, and treatment below is a reference example. Adapt, combine, or ignore it; no catalogue id, prescribed colour scheme, or difference from an unrelated document is required.
+
+## 1. How to use the examples
+- Start with what the reader needs to understand, decide, or fill in and how they will use the file.
+- Preserve supplied templates, brand requirements, and the conventions of files being edited.
+- `concept:` may describe a design intent in free text or be omitted; it is not a quality gate.
+- Share facts and requested identity across a package, while adapting each format's structure to its job.
+- Reuse a layout when it helps comparison or a series; vary it when the content needs a different reading path. Novelty alone is not a goal.
+- If comparing directions resolves a real uncertainty, compare representative rendered pages for reader understanding, not catalogue membership.
+- Names such as `ink`, `line`, and `accent` in recipes mean roles in the author's palette, not compulsory values from this file.
+
+## 2. Palette roles and deriving them
+Roles: `paper` (the page ground), `ink` (body and headings), `muted` (captions, labels, sources), `line` (rules and hairlines), `tint` (a quiet field behind a callout, band, or banded row), `accent` (the one colour with one job — the claim, the key figure, the subject's mark), and optionally `accent2` (a second voice with its own job: the alert, the comparison series, the second subject). Hex is six digits; in CSS `#`, in office operations without. Contrast: body ink on paper ≥ 4.5:1, `muted` ≥ 4.5:1 for text, accent as text ≥ 4.5:1 (`direction.md` §5).
+
+Start from a **seed hue** (the subject, the brand, the mood), then pick a scheme — vary it between concepts and artifacts, do not always take the complement:
+| Scheme | accent hue vs seed | Reads as | Fits |
+|---|---|---|---|
+| mono | the seed itself, one saturation step above the neutrals | calm, disciplined | quiet-minimal, letter-memo, formal-report |
+| analogous | seed ± 20-40° | cohesive, warm or cool throughout | formal-report, technical-reference, data-dashboard |
+| complement | seed + 180° | high contrast, one loud mark | keynote-statement, brand-campaign, editorial-magazine |
+| split | seed + 150° and + 210° (accent and accent2) | lively, still ordered | data-dashboard, brand-campaign, dark-tech |
+
+Derivation, with the seed hue h: `paper` = h at S 2-8%, L 97-100% (a dark concept: S 10-25%, L 5-10%); `ink` = h at S 15-30%, L 8-16% (dark concept: L 90-96%); `muted` = h at S 10-20%, L 38-46% (dark: L 60-68%); `line` = h at S 8-15%, L 84-90% (dark: L 16-22%); `tint` = the accent's hue at S 25-45%, L 93-96% (dark: L 10-14%); `accent` = S 55-85%, L 32-48% for text use, the same hue a step brighter (L ≈ 50%) for a mark that carries no type; `accent2` the same recipe at its own hue. Neutrals are tinted toward the seed, never pure 000000/FFFFFF unless the concept is a statement or a form. A state colour (good / caution / bad) is a separate, fixed hue pair — green and red words beside their glyph — not the accent.
+
+## 3. The concepts
+Each entry: **Fits** (signals) · **Palette** (scheme and one example) · **Type** (Korean / Latin) · **Heading** · **Table** · **Emphasis** · **Chart** · **Chrome** · **Density**. Faces are installed with Windows/Office or are the provisioned Noto families (§5).
+
+### formal-report
+- **Fits**: a board, regulator, client, or committee reading at a desk; decisions, audits, annual or quarterly reports, proposals with evidence; the reader may file it.
+- **Palette**: mono or analogous. `paper FFFFFF · ink 1C2321 · muted 5E6A66 · line D3DAD6 · tint E8F0ED · accent 1F5E4B` (seed 160°).
+- **Type**: Korean Noto Sans KR or Malgun Gothic, headings bold; Latin Calibri or Segoe UI. A serif body (Noto Serif KR / Cambria) suits a legal or academic variant.
+- **Heading**: numbered assertion headings, bold, a step per level; title block left-aligned with a rule under it.
+- **Table**: bold header on a rule, hairlines between rows, figures right-aligned, a total row set apart; a tint band only on the header when the callout uses the same tint.
+- **Emphasis**: a boxed note or tinted band for the conclusion — or none; the finding can lead as the first paragraph in bold.
+- **Chart**: quiet bars/lines, direct value labels, the subject in `accent`, the rest `muted`/`line`.
+- **Chrome**: running head and "n / N" folio are right for a long, filed document; a short one needs only a folio or nothing.
+- **Density**: dense, 30-40 Hangul characters per line, generous heading space.
+
+### editorial-magazine
+- **Fits**: features, newsletters, thought-leadership, annual-review stories, explainers written to be read for pleasure; a point of view and a narrative, not a decision table.
+- **Palette**: complement or split, one saturated accent used large. `paper FFFFFF · ink 161616 · muted 6A6A6A · line CFCFCB · tint F1EEE8 · accent C8102E · accent2 0B3C5D`.
+- **Type**: serif display over sans body — Korean Noto Serif KR headings, Noto Sans KR body; Latin Georgia or Cambria headings, Calibri body. A large size contrast (headline 4× body on the opener).
+- **Heading**: oversized opener, a deck line, section heads in the serif; drop cap or a numeral as the anchor; a short kicker is allowed where it names something, not over every heading.
+- **Table**: open — no vertical rules, thin rule under the header only, generous row space; used sparingly.
+- **Emphasis**: pull quote across the column, a margin note, an oversized numeral; no callout box.
+- **Chart**: annotated on the data (a labelled event, a bracket), accent on the point the story turns on.
+- **Chrome**: folio and section name small at the foot, or only on the inside edge; none on the opener.
+- **Density**: airy, 2-column or measure-limited text with side column; images carry pages.
+
+### data-dashboard
+- **Fits**: operational status, KPI reviews, monitoring, a surface scanned in under a minute and returned to; many figures, few paragraphs.
+- **Palette**: analogous with a warm `accent2` reserved for the alert. `paper F4F6F8 (canvas) · card FFFFFF · ink 0F1B2D · muted 5A677A · line DCE1E8 · tint E6EEF8 · accent 0A7EA4 · accent2 F2A33A`.
+- **Type**: Korean Noto Sans KR / Malgun Gothic; Latin Segoe UI with tabular figures (`font-variant-numeric: tabular-nums`); big numerals in bold.
+- **Heading**: small, functional labels over modules; the page title short.
+- **Table**: compact rows, zebra or hairline, sparkline/bar cells, status cell with word + glyph; figures right-aligned.
+- **Emphasis**: KPI cards (figure over label, delta beside it), the one off-target figure in `accent2`.
+- **Chart**: several small charts on a grid sharing scales; direct labels; light grid allowed.
+- **Chrome**: a header strip with period and refresh date; a footer source line; no folio on a one-screen sheet.
+- **Density**: high; cards on a grid with a consistent gutter.
+
+### quiet-minimal
+- **Fits**: considered internal notes, design or research write-ups, product principles, anything where restraint signals confidence and the content is short.
+- **Palette**: mono; the accent is barely above the neutrals or equals ink. `paper FFFFFF · ink 222222 · muted 8A8A8A · line E6E6E6 · tint F6F6F6 · accent 3A5A78`.
+- **Type**: one family — Korean Noto Sans KR (regular body, bold heading); Latin Calibri Light / Segoe UI Light for headings where light weights exist, regular elsewhere.
+- **Heading**: modest size, weight and space do the work; no rules, no labels.
+- **Table**: no fills, one hairline under the header, wide row spacing; or a list instead of a table.
+- **Emphasis**: a bold sentence or an indented paragraph; no boxes.
+- **Chart**: single series, one accent point, no axis lines.
+- **Chrome**: none, or a lone page number in `muted`.
+- **Density**: low; wide margins, short lines, more white than ink.
+
+### keynote-statement
+- **Fits**: a pitch, a launch, a vision or all-hands deck, a poster or one-page announcement; one claim per page, read from a distance or in seconds.
+- **Palette**: complement, high contrast, large flat fields. `paper FFFFFF · ink 0B0B0B · muted 6B6B6B · line E2E2E2 · tint FFF1EB · accent FF4F1F · accent2 FFD400` (or the inverted dark field with `ink` as paper).
+- **Type**: Korean Noto Sans KR ExtraBold (its own family) for display, regular for support; Latin Arial Black or Bahnschrift display with Calibri support; headline-to-body ratio 4-5 on the statement pages only.
+- **Heading**: the claim is the page; one or two lines, broken at a phrase.
+- **Table**: avoided; a three-row comparison at most, large type.
+- **Emphasis**: one phrase of the headline in `accent`, a numeral at hero size, a colour field behind a single sentence.
+- **Chart**: one chart per page, one highlighted bar or point, the takeaway stated in the title.
+- **Chrome**: none, or a tiny brand mark and number in the corner.
+- **Density**: very low; 40-60% of the page deliberately empty.
+
+### letter-memo
+- **Fits**: correspondence, memos, notices, cover letters, minutes, policy statements; a person writes to a person and the text is the point.
+- **Palette**: mono and nearly colourless; one restrained accent for the letterhead only. `paper FFFFFF · ink 202020 · muted 666666 · line BBBBBB · tint F3F3F3 · accent 6B2D3C`.
+- **Type**: serif or conventional — Korean Noto Serif KR or 바탕 (Batang) body, or Malgun Gothic for a modern memo; Latin Cambria, Georgia, or Times New Roman.
+- **Heading**: letterhead/sender block, then the subject line in bold; section labels (if any) are run-in bold.
+- **Table**: a plain ruled grid for a schedule or a list of attendees; top and bottom rule only for short ones.
+- **Emphasis**: bold or underline in the sentence; a numbered list for actions; no callouts.
+- **Chart**: normally none.
+- **Chrome**: sender block and date at the top, "n / N" only past one page; no running head.
+- **Density**: moderate; letter proportions, 1.5-1.7 line height, signature space.
+
+### technical-reference
+- **Fits**: manuals, specs, API or process documentation, runbooks, standards, anything looked up rather than read through, with code, parameters, and warnings.
+- **Palette**: analogous, cool-neutral with a warning hue. `paper FFFFFF · ink 1A1F24 · muted 5C6670 · line C9D1D9 · tint F0F3F6 (code ground) · accent 00796B · accent2 C2410C (warning)`.
+- **Type**: Korean Noto Sans KR / Malgun Gothic; Latin Segoe UI body, Consolas for code, names, and parameters (the Korean text stays in its own face).
+- **Heading**: numbered sections (1.2.3), bold, stable levels; every section findable.
+- **Table**: full grid or banded rows, a header fill, a parameter / type / meaning layout; monospace in the name column.
+- **Emphasis**: labelled notes (Note / Warning) as boxed notes with a left rule or glyph, code blocks on `tint`.
+- **Chart**: schematic diagrams and flow charts in line work; value charts rare.
+- **Chrome**: running head with document and version, folio "n / N", section name; contents list at the front.
+- **Density**: high and regular; consistent rhythm so the eye can scan.
+
+### form-intake
+- **Fits**: applications, intake and registration forms, checklists, order sheets, inspection records, anything a person fills in.
+- **Palette**: mostly neutral, high contrast, field fills that read as "type here". `paper FFFFFF · ink 1E1E1E · muted 666666 · line 8C8C8C · tint EAF2E3 (fill-in) · accent 2E6B34`.
+- **Type**: Korean Malgun Gothic or Noto Sans KR; Latin Arial or Calibri; labels in `muted` small caps-free sentence case, entered values in `ink`.
+- **Heading**: numbered groups of fields with a short instruction line.
+- **Table**: the form is a table — label cell and entry cell, visible rules (`line`), entry cells on `tint`; checkboxes as real squares.
+- **Emphasis**: required marks, a single instruction box, a signature line.
+- **Chart**: none.
+- **Chrome**: form title and id at top, page "n / N", a return-to line at the foot.
+- **Density**: moderate; entry cells tall enough to write in; nothing decorative.
+
+### brand-campaign
+- **Fits**: brochures, campaign one-pagers, event programmes, product launches, invitations, certificates; the look is the message and a brand or mood exists.
+- **Palette**: the brand's own colours as roles, else complement or split, with a large colour field. `paper FFFDFB · ink 1D1A31 · muted 635F78 · line E9E4EE · tint FDE9E1 · accent E4572E · accent2 17BEBB`.
+- **Type**: the brand face when the recipient has it; otherwise Korean Noto Sans KR ExtraBold display over Noto Sans KR, or Noto Serif KR for a gentler brand; Latin Trebuchet MS, Century Gothic, or Georgia.
+- **Heading**: display type with personality, set against a picture or colour field; sections can change field colour.
+- **Table**: a styled list or two-column spec, a pricing grid with an accented column; rarely a data table.
+- **Emphasis**: a colour field, a badge, a large numeral, a tilted or cropped shape; the call to action as a button-shaped block.
+- **Chart**: infographic-style, illustrated, few numbers, brand colours.
+- **Chrome**: logo/wordmark placement, a footer with contact; no running head.
+- **Density**: varied by page; one page may be a single picture and a line.
+
+### dark-tech
+- **Fits**: engineering and product-technology audiences, developer tools, security, AI or infrastructure briefings, night-mode dashboards; screens rather than paper.
+- **Palette**: dark ground, one luminous accent, `accent2` for a second series. `paper 0B0F14 · ink E8EDF2 · muted 8B97A5 · line 222B36 · tint 131A22 · accent 3DDC97 · accent2 7C5CFF`. Keep the accent off large fields and body text: it is the mark.
+- **Type**: Korean Noto Sans KR; Latin Bahnschrift or Segoe UI, Consolas for labels, figures, and code.
+- **Heading**: bold sans, tight leading, a short monospace label where it names a module or version (not over every heading).
+- **Table**: no fills, `line` rules only, monospaced figures; header in `muted`.
+- **Emphasis**: the accent on one figure or phrase, a thin bracket frame or glow behind one metric; a callout is a `tint` card with a 1 px `line` border.
+- **Chart**: luminous lines on the dark ground, accent for the subject, `muted` for the rest.
+- **Chrome**: small status line at the top or foot (version, date); page number in `muted`.
+- **Density**: medium-high with generous dark margins. For print, invert to a light ground rather than printing the dark field.
+
+## 4. Translation per format
+For the chosen concept, the format carries the same roles with its own anatomy. `STYLE` is the nearest `kit.md` `STYLES` id for the script route (`deck({ style })`), and the HTML route's visual language to start from (`direction.md` §3).
+| Concept | Deck (HTML, 1920 × 1080) | Word document | Flowing PDF | Designed PDF (`section.slide` pages) | Excel report sheet | STYLE |
+|---|---|---|---|---|---|---|
+| formal-report | assertion titles on paper, evidence slides with chart + commentary, text mode; accent on one object per page | numbered headings, boxed note or lead paragraph, ruled tables, running head + folio when long | `@page` running head + folio margin boxes, ruled tables, narrow column + side rail for captions | cover, key-figures page, evidence pages in the sheet's margins; folio in the slide | title block, metric strip, ruled table, one native chart; print area one page wide | data-journalism |
+| editorial-magazine | serif headline over sans, rail or column text, pull-quote and numeral pages, one picture-led page | serif headings, pull quote, two-column section, open tables | `@page` folio at the foot only, columns, drop cap, no boxed notes | full-bleed opener, feature spreads with image and margin note | story-led report: headline cell, short insight cells beside the chart, few tables | editorial |
+| data-dashboard | KPI card rows, small multiples, table + chart, balanced mode | landscape sections with KPI table strip, compact zebra tables, small charts | landscape `@page`, KPI strip, compact tables, header strip | one-screen dashboard page on a grid of cards | KPI cards, charts beside tables, conditional formats; the default archetype for a dashboard | data-journalism |
+| quiet-minimal | few words per slide, wide margins, one accent point | one family, no boxes, space-only hierarchy, no running head | wide margins, no `@page` boxes or a lone folio | sparse pages, one idea each | plain title, a table with one hairline, gridlines off | swiss-minimal |
+| keynote-statement | one claim per slide at display size, colour fields, hero numerals | a poster-like cover page then plain text; rarely long | one-page announcement: large type, a colour band; no margin boxes | full-bleed claim pages, a numeral or phrase in accent | a summary sheet with 3-4 oversized figures; no more | swiss-minimal |
+| letter-memo | rarely a deck; a single "message" slide at most | letterhead block, subject line, plain paragraphs, signature, no running head | the same on letter/A4 with `@page` margins and a folio only past one page | rarely designed; a one-page notice with letterhead | rarely a sheet; a cover note row above a table | swiss-minimal |
+| technical-reference | blueprint diagrams, code panels, text mode | numbered headings, labelled notes, monospace cells, contents field | running head with version, folio, contents list, code blocks on `tint` | architecture diagram pages, reference cards | parameter table, change log, one summary sheet; formulas stay native | blueprint |
+| form-intake | rarely; a checklist slide | fields as tables (label / entry), real checkboxes, instruction box; fill with the native route when it is a template | printed form with ruled entry cells | not used for fillable forms (the browser prints controls as pictures) | input sheet: legend, example row, validation, unlocked fill cells | soft-rounded |
+| brand-campaign | colour-field pages, picture-led, badge and big numeral, CTA closing | brochure-like cover, colour band headings, styled lists; limited by Word's flow | folded-leaflet style with named cover `@page`, bands, no margin boxes | full-bleed designed pages, field colours change per spread | a branded summary sheet with colour header and a few charts | photo-editorial |
+| dark-tech | dark theme throughout, glow behind one metric, bracket frames | light variant: dark title band, light body (Word prints on white); `tint` code panels | light ground for print; dark cover page via named `@page` | dark pages for screen reading | dark header band and light grid, accent on the KPIs | dark-tech |
+If the nearest STYLE does not fit the page, use `custom` and write the five columns of `direction.md` §3 yourself.
+
+## 5. Face menu per script
+Faces named here are installed with Windows/Office or are the provisioned Noto families. A PDF embeds the fonts it drew with, so any installed face is safe there. Word, PowerPoint, and Excel write the face name into the file: the runtime warns when a face is not one the recipient is sure to have (an advisory, not a block), and a recipient without it sees a substitute — say so in the delivery, or choose from the safe column.
+| Script / pairing | Display / heading | Body | Figures, code | Notes |
+|---|---|---|---|---|
+| Korean sans | Noto Sans KR (700), Noto Sans KR ExtraBold, Malgun Gothic (bold) | Noto Sans KR, Malgun Gothic | same family; Consolas for code | one face for Hangul and digits so the two share a baseline |
+| Korean serif | Noto Serif KR (700), 바탕 (Batang) | Noto Serif KR, 바탕 | same family | Hangul has no italic: use weight, colour, or a rule |
+| Korean mixed | Noto Serif KR headings | Noto Sans KR body | Noto Sans KR | serif display over sans body (editorial); keep the two Latin faces in step with them |
+| Latin sans | Segoe UI Semibold, Bahnschrift, Arial, Trebuchet MS, Century Gothic, Calibri | Calibri, Segoe UI, Arial | tabular figures; Consolas for code | Calibri and Segoe UI are in every Office install |
+| Latin serif | Georgia, Cambria, Palatino Linotype, Times New Roman, Bookman Old Style | Cambria, Georgia | Georgia has old-style figures: use Cambria for tables | serif body suits letters and essays |
+| Latin mixed | Georgia or Cambria heading | Calibri or Segoe UI body | Consolas for labels | the editorial pairing |
+Set Latin and East Asian faces together (Word `name` + `nameEastAsia`, CSS `font-family` listing both). Pair them deliberately: a Latin face beside a Korean face renders figures in the Latin one, and a Hangul line next to Latin digits can print at two apparent sizes — in a Korean-led document with many figures, set both in the Korean face; a distinct Latin face is for headings and Latin-led content.

package/src/defaults/skills/pptx/references/direction.md

@@ -2,7 +2,7 @@
 
 Owns what the deck decides before full-deck composition: who reads it and how (§1), how it argues (§2), how it looks (§3), which direction the representative trial supports (§4), its colors (§5) and type (§6). `composition.md` owns the page, `kit.md` owns the code.
 
-Rule strength: **Hard rule** (objective failure, with its check: `→ runtime \`code\`` when the review raises that code, `→ manual` when only the render shows it), **Default** (a sensible choice; override with a reason), **Reference** (vocabulary; no single right answer). An unlabeled line is a Default.
+This is an optional design reference. Reading modes, palettes, type scales, style menus, and numeric composition targets are examples, not required selections or acceptance criteria. Existing brand requirements, faithful content, legibility, and format constraints take precedence. No style score can replace inspection of the converted pages.
 
 ## 1. Reading mode — decides density before anything else
 **Default — derive from delivery**: live projection and launches lean presentation; async review, approval, and leave-behinds lean text; hybrid review leans balanced.
@@ -45,7 +45,8 @@ A style is shape language, composition geometry, decoration density, whitespace,
 | brutalist | raw structure, heavy rules, irregular columns | masthead numeral crossing column rules; heavy full-bleed rule bars; one grid cell inverted to solid ink as the focal cell | none; weight is the decoration | flat, hard |
 | custom | write the five columns yourself | — | — | — |
 
-**Reference — choosing**: compare the subject's own edge, corner, opening, angle, or layering logic with each style's shape language before settling on rectangles and circles; a topic word never selects a row. Expressive print or hand-drawn looks (zine, memphis, chalkboard, pixel) need prepared artwork the runtime does not have.
+**Reference — choosing**: compare the subject's own edge, corner, opening, angle, or layering logic with each style's shape language before settling on rectangles and circles; a topic word never selects a row. On the script route, expressive print or hand-drawn looks (zine, memphis, chalkboard, pixel) need prepared artwork the kit does not draw; on the HTML route they are CSS, inline SVG, and `images:` plans, and are available (`html.md` §8).
+**Default — a concept is optional guidance, not a gate**: `concepts.md` offers design concepts as a vocabulary. The plan's `concept:` line is optional free text (a concept id and a reason from subject, audience, purpose, or your own words); the runtime does not require it. When you name one, it fixes palette scheme, type pairing, heading, table, emphasis, and chrome; the style below is the nearest kit vocabulary for the script route (`concepts.md` §4 names it per concept). A deck, document, and workbook of one package share whatever direction is chosen.
 
 ## 4. Select from a representative visual trial
 **Default — compare the open decisions on actual pages**: for a new direction, render two materially different compositions of the same representative content before building the whole deck (`review.md`). Each has a coherent reading mode, argument, palette, type, and treatment, but differs in how the message becomes visible. Choose by fidelity and reading clarity, or reject both; do not force a winner or rebuild every page twice. A supplied template, approved direction, or small factual edit skips the trial. Record the candidates and visible reason in the brief (`SKILL.md` §3); runtime candidate-count readings remain advisory.
@@ -57,13 +58,13 @@ A style is shape language, composition geometry, decoration density, whitespace,
 ## 5. Palette — from the subject, through one seed
 **Hard rule — contrast**: body text ≥ 4.5:1; text ≥ 18 pt or bold ≥ 14 pt ≥ 3:1; white on an accent block ≥ 3:1. Accent is never body text. Meaning never rides on color alone. → runtime `low_contrast` (saved colors), `low_visual_contrast` (render); color-only meaning → manual
 **Hard rule — colors are 6 hex digits without `#`**; alpha in the hex corrupts the file (`transparency: 0-100` on fills and images, `opacity: 0-1` on shadows). → runtime package validation fails at finalize
-**Default — one hue family for the neutrals, the accent on its counter hue**: the kit's `palette({ hue })` derives the whole ladder from one seed hue — ink, body, muted, the three lines (lineSubtle, line, lineStrong — `composition.md` §6), paper, paperAlt, dark, darkAlt, onDark, onDarkMuted — with adjacent steps 10-25% apart in lightness and backgrounds within ±20° of the hue, and puts the accent (accent, accentDeep, tint, onDarkAccent) on `counterHue(hue)`: navy 225 → coral 15, indigo 250 → gold 40, forest 125 → amber 25, teal 185 → amber 30, berry 335 → gold 40, terracotta 8 → teal 198. The accent is the deck's second hue and its only saturated color on type and fields, on small areas; a state mark (below) is the one other saturated form. `accentHue: hue` keeps a single-hue deck (swiss-minimal, brutalist, blueprint, a brand that owns one color), and a brief may name any accent hue. Proportion starts at 60/30/10 (field / support / accent). The extremes are tinted, never 000000/FFFFFF.
+**Default — one hue family for the neutrals, the accent on its counter hue**: the kit's `palette({ hue })` derives the whole ladder from one seed hue — ink, body, muted, the three lines (lineSubtle, line, lineStrong — `composition.md` §6), paper, paperAlt, dark, darkAlt, onDark, onDarkMuted — with adjacent steps 10-25% apart in lightness and backgrounds within ±20° of the hue, and puts the accent (accent, accentDeep, tint, onDarkAccent) on `counterHue(hue)` — the complement scheme; `accentHue` overrides it for an analogous, split, or mono scheme, which `concepts.md` §2 says when each fits, so the complement is one choice and not the default of every deck. The accent is the deck's second hue and its only saturated color on type and fields, on small areas; a state mark (below) is the one other saturated form. `accentHue: hue` keeps a single-hue deck (swiss-minimal, brutalist, blueprint, a brand that owns one color), and a brief may name any accent hue. Proportion starts at 60/30/10 (field / support / accent). The extremes are tinted, never 000000/FFFFFF.
 **Default — four state colors, each with a word**: `T.state.positive | warning | critical | informative` say better / caution / worse / note — a verdict cell, a delta, a badge, a callout — and each comes in three forms: `solid` fills a mark (a dot, a delta arrow, a bar), `weak` is the field under a state word, `text` is the word on paper, paperAlt, or its own weak field (each ≥ 4.5:1; solid ≥ 3:1 on paper). The state hues are fixed (green 150, amber 40, red 5, blue 215), not derived from the seed, so a state means the same thing in every deck; a deck uses the states its content has, never all four for variety; a state's word or glyph always stands beside its color (the kit's `tone('positive')` pairs the field and the word for `badge()`, `callout()`, and `table({ verdict, tones })`).
 **Hard rule — a state's solid form never sits under type**: type takes the `text` form (dark, restrained) on the `weak` field; the saturated form is the mark, so the deck's saturated hue on type stays the accent. → runtime `accent_hue_overuse` (saturated hue families on text-bearing shapes)
 **Default — the accent has a type form and a mark form**: `T.accent` is the word (darkened to 4.5:1 on paper — a kicker, an emphasis run, a hero numeral); `T.accentFill` is the mark (S ≥ 0.78, L ≈ 0.5, ≥ 2:1 on paper — the reference marks sit at 1.3-2.6:1) that the one bar, disc, dot, or band takes; a mark that carries type (a badge, an active chevron, a numbered node) takes the `T.accentLabel` pair — the bright fill where white or ink reads on it at 4.5:1, else the type form under white. A bar painted with the type form reads as mud; a word set on a mid amber fails contrast. `T.accentFill` covers 3-20% of a content page and belongs to the object the title names; everything else it could have coloured is `T.mark` gray.
 **Reference — measured colour** (ten frontier decks, September 2026, saturated pixels of every page): each deck has one bright accent that carries 53-98% of its saturated ink (Sequoia green 165°/S 1.0/L 0.3 98%, Evans red 0°/0.75/0.6 94%, Coatue blue 210°/0.75/0.5 93%, Naver green 135°/0.75/0.6 87%, Samsung navy 225°/0.5/0.2 83%, NVIDIA green 75°/0.75/0.4 67%, Kakao yellow 60°/1.0/0.6 39% + a pink 28%); at most two hues exceed 10% of it (Kakao four — a brand with a mascot). Saturated pixels cover 3-22% of a page (median 10%); dark pages are 0-33% of a deck (Samsung a third, NVIDIA 13%, Coatue 10%, most under 5%); pale tinted fields cover under 2% of a page.
 **Default — saturation by area**: large fields S ≤ 20%, text S ≤ 25%, the accent S 60-90% and only on small areas; projected decks read 10-15% more saturated than the screen.
-**Reference — temperature by subject**: tech/finance cool blues (hue 205-240), education/growth greens (100-160), health cyans (170-190), creative/marketing warm oranges and pinks (10-40), academic indigos (230-260). Seeds that have worked: navy 225 + ice accent 210; forest 125 + moss 90; coral 358 + navy 230; terracotta 8 + sage 150; teal 185 + mint 165; berry 335 + cream 40; slate 210 + cherry 350. If the colors would work on any other deck, choose again.
+**Default — how to choose the seed and the scheme**: the seed hue comes from what exists first — the brand's own colour, the product or place the deck is about, a colour in the supplied pictures or screenshots, the mood the concept calls for (`concepts.md`) — and only then from taste. Pick the scheme (mono, analogous, complement, split; `concepts.md` §2) for the concept, not from a subject-to-hue table: no subject owns a hue, and a hue chosen because "finance means blue" is how decks come to look alike. Check it by asking whether the same colours would work on any other deck; if so, choose again. Record the seed, scheme, and reason in the brief's `palette:` field.
 
 ## 6. Typography
 **Default — reliable families first**: Noto Sans/Serif (including KR, SC, TC, JP), Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook, Malgun Gothic, Microsoft YaHei, and Yu Gothic are practical starting points. Brand fonts are allowed when available to the recipient and renderer. If substitution changes metrics, use a compatible face or leave extra room and disclose the preview limitation; do not claim reliable fit from an approximate render. → runtime `unsafe_font_family`, `font_family_overuse` are compatibility diagnostics