@litfamily/litopencode 1.0.16 → 1.0.17

package/skills/lit-docx/references/components.md

@@ -0,0 +1,253 @@
+# Page components and the directive syntax
+
+The Markdown source may hold six fenced directives: `cover`, `callout`, `sidebar`, `pullquote`,
+`keyfigures` and `columns`, plus a `<!-- column-break -->` marker inside `columns`. The converter splits
+them out before Markdown sees the text, so a fence never reaches the page. Everything else in the source
+is ordinary Markdown: headings, paragraphs, lists, pipe tables, images and captions.
+
+This file gives the exact syntax the converter accepts, what each directive produces, which tonalities
+draw it, and the budget that keeps a document from turning into a page of boxes. A directive that is
+valid but not drawn by the chosen tonality, or that falls outside the budget, is not lost: its content is
+set as ordinary text, with its `title=` as a bold lead line.
+
+## The budget
+
+Most documents need no component at all beyond the page-1 block. A component earns its place when it
+carries content that does not belong in the running order of the text: a decision the reader must make,
+a warning that interrupts a procedure, definitions consulted out of sequence, the three numbers a summary
+stands on. The rules:
+
+- **Three kinds at most** beyond headings, paragraphs, lists, tables and figures. The kinds counted are
+  callout, sidebar, keyfigures and columns. A fourth kind in the source is set as plain text.
+- **One key-figure strip per document**, placed in the summary, with three or four real metrics that are
+  comparable and each carry a basis (period, source or method). A second strip becomes a bulleted list. A
+  strip is never a list of facts that are not measurements ("two sites", "phase 1").
+- **Callouts about one per four pages**, for out-of-sequence content only: a decision request, a warning,
+  a definition the reader needs before the next step. The converter estimates the page count and draws
+  that many callouts, never fewer than one; a pack may cap the number lower (Brief and Proposal draw one).
+  When the source has more callouts than the budget, the converter keeps a `kind=key` callout first, then
+  warnings, then notes, each group in source order; the rest are set as text.
+- **No pull quotes.** Every pack has them off. A pull quote that repeats a sentence of the body is
+  dropped with a note; any other pull quote is set as a normal paragraph.
+- **Sidebars in Manual only.**
+- **Two columns only for balanced blocks.** The parts of a `columns` block must be within 20 % of each
+  other in length, counted in characters without spaces or Markdown marks. An unbalanced block is set as
+  one column with the break removed.
+- **No box inside a box.** `columns` is refused inside a callout or sidebar; nesting a callout inside a
+  callout is legal syntax but defeats the purpose of either.
+- **A purpose line on the direction card** for every component the source uses. No line, no component.
+
+The gate's `component.budget` check fails a tonality document with more than three kinds, more than one
+key-figure strip, any pull quote, or key figures on a cover page.
+
+## Grammar
+
+```text
+::: <name> [positional] [key=value] [key="value with spaces"]
+<body: Markdown, which may contain further directives>
+:::
+```
+
+- The opening line is three or more colons, a space, the directive name and its attributes.
+- The closing line is the same number of colons on a line of its own. To put one directive inside
+  another, give the outer fence more colons (`::::`) than the inner one.
+- Values without spaces need no quotes (`kind=warning`, `width=third`). Values with spaces use double
+  quotes (`title="Decision requested"`). A literal double quote inside a value is written `\"`.
+- An unknown directive name, an unknown attribute, a repeated attribute, an unclosed fence and a closing
+  fence with nothing open are all errors. The converter stops and names what it accepts; it does not
+  guess.
+- Fenced code blocks are left alone: a `:::` line inside a code fence is text.
+
+Attributes each directive accepts:
+
+| Directive | Positional | Attributes |
+|---|---|---|
+| `cover` | none | `kicker`, `variant`, `image` |
+| `callout` | none | `kind` (required), `title` |
+| `sidebar` | none | `title`, `width`, `float` |
+| `pullquote` | none | `cite` |
+| `keyfigures` | none | `cols` |
+| `columns` | `1`, `2` or `3` | `gap`, `rule` |
+
+## Which tonality draws what
+
+| Tonality | cover block | callout | sidebar | keyfigures | columns |
+|---|---|---|---|---|---|
+| Report | masthead | yes | text | yes | yes |
+| Brief | masthead | yes, one | text | text | yes |
+| Manual | control block | yes | yes | text | yes |
+| Proposal | cover page | yes, one | text | yes | yes |
+| Memo | memo block | text | text | text | text |
+| Journal | masthead | yes | text | text | already two columns |
+
+"Text" means the content is set in the flow: a callout or sidebar as its bold title and body, key figures
+as a bulleted list with each basis in parentheses after the label. A short block set this way is kept on one
+page.
+
+## `::: cover`
+
+```markdown
+::: cover kicker="시설 운영 보고 2026-4호"
+본문 첫 쪽 제목 아래에 둘 한두 문장의 안내.
+:::
+```
+
+The cover directive must be the first block of the body, straight after the frontmatter. It carries the
+page-1 extras; the title, subtitle, byline, date and notice come from the frontmatter, and a cover with no
+frontmatter `title:` is an error. What the block becomes depends on the tonality's title block, not on
+the directive:
+
+- **Masthead** (Report, Brief, Journal): a series line with the kicker on the left and the date on the
+  right, the title, the subtitle, the byline, one rule, the notice, then the body text of the directive as
+  a lead set half a point above the body size.
+- **Cover page** (Proposal): the kicker, the title in the upper third, a short rule, the subtitle and the
+  lead on a page of their own; byline, date and notice at the foot of that page. The body starts on the
+  next page as page 1.
+- **Memo block** (Memo): the kicker as the label (default 메모 or Memo), the title, and the rows of the
+  body lines that start with `To:`, `From:`, `Date:`, `Subject:`, `Cc:` or their Korean forms `받는 사람:`,
+  `보내는 사람:`, `날짜:`, `제목:`, `참조:`. Several pairs may share one line separated by ` · `. The
+  frontmatter date is inserted after the sender when no date row is given.
+- **Control block** (Manual): the title, the subtitle and a two-column block of document, owner,
+  organisation and issue date (문서, 작성 부서, 기관, 시행일), filled from `short_title` (or `title`),
+  `author`, `organization` and `date`. The kicker is printed above the title without a date.
+
+An empty directive (opening and closing line only, or only a kicker) is valid; leave the directive out
+altogether when there is no kicker and no lead.
+
+`variant=` accepts `typographic`, `band`, `split` and `masthead` and rejects anything else, but every
+tonality draws its own typographic block whatever the variant says; omit it. `image=` is accepted and not
+drawn: covers carry no pictures. A `keyfigures` block placed inside a cover (with a longer outer fence) is
+moved to the summary when the tonality draws key figures and left out with a note otherwise, because key
+figures never stand on a cover.
+
+## `::: callout kind=<note|key|warning> [title="…"]`
+
+```markdown
+::: callout kind=key title="결정 요청"
+2027년 추가 예산 2,150만 원과 급속기 예약제 시행을 승인해 주시기 바랍니다.
+:::
+```
+
+One callout style per document: a single-cell box with a 0.75 pt rule above and a 0.5 pt rule below, no
+side rules, no fill, the title in bold ink at body size, the body in the body face. The rules take the
+pack's accent where the pack lists `callout_rule` among its accent places (Report, Brief, Manual,
+Proposal) and ink otherwise. The box does not split across pages and keeps with what follows.
+
+The three kinds differ in label and priority, not in look. Default labels are 참고 / 핵심 / 주의 in Korean
+and Note / Key point / Warning in English; a `title=` replaces the label and is almost always better.
+
+- `kind=key` is the decision request or the one conclusion the reader must take away. In a Brief, the
+  first key callout moves to the top of the body, straight under the title block. In other tonalities it
+  usually closes the document.
+- `kind=warning` interrupts a procedure: a hazard, an irreversible step, a combination that must not
+  happen. Manual is its natural home.
+- `kind=note` holds a definition or a reading aid the text depends on but does not argue.
+
+A callout earns its place when removing it would leave the reader without a decision or a safety fact.
+A summary restated in a box, a "tip", or a second copy of the conclusion does not.
+
+## `::: sidebar [title="…"] [width=third|half] [float=right|left|none]`
+
+```markdown
+::: sidebar title="이 절차서의 용어" width=third float=right
+**보관소**: 지하 1층 B-104호 임시 보관 시설.
+
+**인계**: 용기를 넘기고 대장에 서명하는 절차.
+:::
+```
+
+Manual only. A box beside the text with a 0.75 pt hairline down its left side in the pack's accent, no
+fill, body text at table size (about 92 % of the body). Defaults are a third of the text width floating
+right. A sidebar inside a two-column body does not float.
+
+The converter measures the text between the sidebar and the next heading. When that text is shorter than
+the box, the next heading would start beside it, so the sidebar loses its float and stands full width in
+the flow. To keep a floating sidebar, place it at the start of a section with two or three paragraphs
+after it, as the Manual example does under its first h2. A good sidebar holds definitions, contact
+numbers or reference values the reader looks up while following the main text; a sidebar that repeats
+the text beside it is padding.
+
+## `::: pullquote [cite="…"]`
+
+Accepted by the parser and drawn by no tonality. A pull quote that repeats a sentence already in the body
+is dropped and the converter prints `Note: line N: the pull quote repeats the body and is left out`. Any
+other pull quote becomes an ordinary paragraph. Write the sentence in the body instead.
+
+## `::: keyfigures [cols=2|3|4]`
+
+```markdown
+::: keyfigures
+- **1,050MWh** 연간 예상 발전량
+  - 일평균 발전시간 3.6시간 가정, 공장 사용량의 11%
+- **1억 5,900만 원** 연간 순절감액
+  - 평균 단가 165원/kWh, 유지비 1,400만 원 차감
+- **5.8년** 단순 회수 기간
+  - 총사업비 9억 2,000만 원 기준
+:::
+```
+
+The body is one list. Each item is `- **figure** label`, where the bold figure contains at least one
+digit. An indented `- ` line under an item is that item's basis: the period, the source or the
+assumption. One to eight items are accepted; three or four is the useful range. `cols=` sets the number
+per row (default 3 in Report and Proposal, at most 4, never more than the number of items).
+
+The strip is drawn as one borderless row with an ink hairline over each figure, the figure in bold at the
+h2 size (one step above the body, never a display number), the label at table size and the basis at note
+size in muted ink. Drawn in Report and Proposal; elsewhere the items become a bulleted list with the basis
+in parentheses after the label.
+
+Place the strip inside the summary, after its first paragraph. The figures must also appear in the text
+or a table, with the same values and rounding: a reader who checks the 4,360만 원 in the strip against the
+cost table must find 4,360. Metrics in one strip should be comparable in kind (outputs, costs, rates)
+and drawn from the same period.
+
+## `::: columns <1|2|3> [gap=<mm>] [rule=true]`
+
+```markdown
+::: columns 2
+**방안 A. 전체 협력사 월 2회.** 196곳 모두에 매월 10일과 25일 지급을 적용한다. …
+<!-- column-break -->
+**방안 B. 중소 협력사만 월 2회.** 연 매출 100억 원 미만 148곳에만 적용한다. …
+:::
+```
+
+With a `<!-- column-break -->` marker, each part goes in its own cell of one borderless row, tops aligned,
+with the gap split between the cells; `rule=true` draws a hairline between them. Without a marker, the
+block becomes a balanced column section that flows into as many columns as asked. `gap` is in
+millimetres (the pack default is 6 mm).
+
+Columns stand at the top level only, never inside a callout or sidebar, and the marker is an error
+anywhere outside a `columns` block. The balance rule applies to the parts separated by markers: two
+options of 119 and 107 characters pass; a paragraph beside a one-line note does not. Use columns for two
+parallel things the reader compares: two options, before and after, two sites. A list split in half to
+save space is not a comparison.
+
+## Table captions and table styles
+
+A table caption is the paragraph immediately before the table, written `표 1. 제목` in Korean or
+`Table 1. Title` in English. There must be no other paragraph between the caption and the table. The
+converter keeps the caption with the table, sets Korean captions as `<표 1> 제목` with the label in bold,
+and bolds `Table 1.` in English. Figure captions written `그림 1. 제목` become `[그림 1] 제목`.
+
+A caption may end with `{style=booktabs}`, `{style=banded}`, `{style=light-grid}` or
+`{style=header-fill}`. Every tonality draws booktabs regardless and prints a note when another style is
+named; the attribute only matters on the plain profile. Leave it out.
+
+## Source and note lines
+
+A paragraph straight after a table that starts with `주:`, `자료:`, `출처:`, `Note:`, `Notes:`, `Source:`
+or `Sources:` is set as a note line: note size, muted ink, kept with the table. Korean `출처:` is
+rewritten as `자료:`. Order them `주:` first, then `자료:`, each as its own paragraph (separate them with a
+blank line, or the two lines merge into one paragraph with a line break).
+
+## Misuse the gate will not catch
+
+The gate counts components; it does not read them. These pass every check and still read as
+machine-made:
+
+- A callout in every section, each restating the section's first paragraph.
+- Key figures that are not measurements, or figures with no basis line.
+- A key-figure strip whose numbers differ from the table that carries the same quantity.
+- Two columns holding unrelated content because the page "looked empty".
+- A sidebar of definitions nobody needs, added because the Manual allows one.
+- A `kind=warning` callout used for emphasis in a document with no hazard.

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

@@ -0,0 +1,234 @@
+# Choosing a direction before writing
+
+A Word document built by this skill takes its page structure from one of six tonality packs in
+`templates/tonalities/`: Report, Brief, Manual, Proposal, Memo and Journal. The pack decides what stands
+on page 1, how the summary is set, whether headings carry numbers, which page components the source may
+use, what the running head carries and whether a contents list appears. Colour plays almost no part:
+every pack sets text and headings in near-black ink, and four of the six allow one muted accent on two
+kinds of element at most.
+
+The pack is chosen before a line of the Markdown source is written, because the choice changes the
+source itself. A Brief wants its first section written as three or four paragraphs that each open with
+a finished sentence. A Manual wants numbered steps. A Proposal wants a budget table and one decision box.
+Rewriting a Report source into a Brief after the fact usually means rewriting most of it.
+
+This file covers the decision: the inputs, the mapping from document type to candidates, how content
+signals reorder the candidates, the direction card that records the choice, the dials, and what to do
+when the request names a journal instead of a look.
+
+## Two cases that skip the choice
+
+**A named publisher.** When the user names a journal or publisher profile (Elsevier, ACS, IEEE, Nature,
+or the Korean generic profile by name), the document goes down the publisher path and no tonality is
+picked. Convert with `python3 <skill>/run.py md-to-docx draft.md draft.docx --publisher elsevier` and gate
+with `python3 <skill>/run.py qa draft.docx --source draft.md --publisher elsevier --kind manuscript`. The
+converter refuses `--tonality` together with `--publisher`, and it also stops when the frontmatter holds
+`tonality:` while `--publisher` is given. A manuscript keeps the publisher's own section order, heading
+case and caption style; nothing in this file applies to it.
+
+**A bare request.** A bare `lit` request for a report, or any request that gives a topic and nothing
+else, asks no questions. Pick the tonality from the tables below, write the direction card, build the
+document and say in the reply which tonality was used and which two were considered. A question about
+format, font or look costs the user a round trip and almost never changes the outcome; the card makes the
+choice visible so the user can redirect it in one sentence.
+
+An explicit request that asks for a different look ("make it a one-page brief instead", "use the manual
+layout") overrides the tables. So does a frontmatter `tonality:` line the user wrote. The skill keeps the
+user's choice even when the signals point elsewhere, and says so on the card.
+
+## The three inputs
+
+**Document type.** What the user calls the document and what it is for: a results report, a briefing for
+a decision, an operating procedure, a funding or investment proposal, a notice or memo, a long-form essay
+or research summary. Korean requests often name the type directly (보고서, 검토 보고, 절차서, 제안서,
+안내문, 기획서). When the type is ambiguous, the purpose decides: a document that asks a reader to approve
+something within days is a Brief or a Memo even if the user said "report".
+
+**Reader.** Who reads it and how. A department head deciding on a budget reads the first page and the
+decision box. A technician following a procedure reads one section at a time with the document open on a
+bench. A committee member reads a long paper at a desk. The reader sets the length budget and whether the
+summary must stand alone.
+
+**Content signals.** What the source material actually holds: how many tables, how many figures, how much
+prose, how many numbered procedures or warnings, which language, and the expected length. When the user
+supplies files, count these from the files. When the skill writes the content itself, count them from the
+outline before drafting.
+
+## Document type to candidates
+
+Each row lists the candidates in order; the first is the default. The dials are each pack's own values
+(the `dials:` line of its YAML), which the converter uses unless told otherwise.
+
+| Document type or wording | Candidates, default first | Pack dials of the default |
+|---|---|---|
+| Results report, analysis, periodic report (보고서, 결과 보고, 분석, 실적) | Report, Brief, Manual | density 9, variance 5 |
+| Decision briefing of one to three pages (검토 보고, 현황 보고, 개조식 보고) | Brief, Memo, Report | density 9, variance 3 |
+| Procedure, guide, manual, onboarding (절차서, 매뉴얼, 가이드, 운영 지침) | Manual, Report | density 9, variance 6 |
+| Proposal, plan, pitch, funding request (제안서, 기획서, 계획서, 사업 계획) | Proposal, Report, Brief | density 8, variance 6 |
+| Notice, memo, letter of one or two pages (안내문, 공지, 메모, 협조 요청) | Memo, Brief | density 9, variance 2 |
+| Essay, white paper, newsletter, research summary not for a journal | Journal, Report | density 9, variance 6 |
+| Manuscript for a named journal | that publisher profile | none |
+
+## Signals that reorder the candidates
+
+Signals change the order inside a row. They never pull in a tonality from outside the row: a proposal with
+many tables becomes a Report-first proposal, not a Manual.
+
+| Signal in the source or outline | Effect on the order |
+|---|---|
+| Four or more tables, or tables make up more than about 30 % of the blocks | Report or Manual moves up |
+| Three or more figures | Proposal or Journal moves up |
+| Under about 900 words, or the user says one or two pages | Memo or Brief moves up |
+| English, mostly continuous prose, few tables | Journal moves up |
+| Many warnings, numbered procedures or check items | Manual moves up |
+| A single decision the reader must make, with a deadline | Brief moves up, and the decision goes in a `kind=key` callout |
+| A budget table and a schedule | Proposal moves up |
+
+When two signals pull in opposite directions, the purpose wins. A forty-row data appendix attached to a
+two-page decision is still a Brief; the appendix becomes a second document or a short table of the five
+rows the decision depends on.
+
+## What each tonality sets
+
+Read this table when two candidates seem equally good. Two tonalities chosen for the same source should
+differ in at least three of these columns, which is also what the gate's `--compare` mode checks.
+
+| Tonality | Page 1 | Summary form | Heading numbers | Components it accepts | Running head | Contents |
+|---|---|---|---|---|---|---|
+| Report | masthead title block, series line with date | prose, optional key-figure strip | Korean Ⅰ. / 1. / 가., English 1 / 1.1 | keyfigures, callout, columns | footer: short title left, folio right | from about five pages |
+| Brief | compact masthead, decision box directly under it | numbered points ① to ④, bold lead sentence each | none; each h1 opens under a hairline | callout (one), columns | footer: folio right | never |
+| Manual | title over a document-control block | prose | 1 / 1.1 | callout, sidebar, columns | header: short title; footer: folio right | from about five pages |
+| Proposal | separate typographic cover page | prose with one key-figure strip | none | keyfigures, callout (one), columns | footer: folio centred | never |
+| Memo | label, subject as title, To / From / Date rows | prose | none | none | footer: folio right, from page 2 | never |
+| Journal | masthead with byline, abstract, keywords | prose (abstract above) | 1 / 1.1 | callout | header: short title left, folio right | never |
+
+No tonality prints a running head on the page that carries the title block; the Proposal prints none on
+its cover and starts the folio at 1 on the first body page.
+
+## The direction card
+
+Before building, write a direction card. It goes in the reply (short form) and in the task's build log
+(full form). It is the record of why the document looks the way it does, and it is the checklist the
+draft is written against.
+
+The card has eight lines:
+
+1. **Type.** The document type in the user's words, plus the purpose in one clause.
+2. **Reader.** Who reads it and how far they read.
+3. **Tonality and two alternatives.** The chosen pack, then two candidates from the same row with the
+   reason each lost.
+4. **Reason from signals.** The counted signals that decided the order: table count, figure count, word
+   estimate, language, procedures, decision.
+5. **Dials.** Density and variance, normally the pack's values. Any change is stated with its reason.
+6. **Page 1 and headings.** What the title block or cover holds (kicker, subtitle, byline, notice, lead
+   sentence) and how headings are treated (numbered or not, the hairline in a Brief).
+7. **Components.** Each component the source will use, with a one-line purpose. A component without a
+   purpose line is not used. Headings, paragraphs, lists, tables and figures are not components and are
+   not listed.
+8. **Wrong if.** One sentence naming the fact that would make this direction the wrong one. This is the
+   line a reviewer checks first.
+
+A full card for the Korean report among the worked examples:
+
+```text
+Direction card
+Type: 시설 운영 결과 보고서 (사내 충전소 1년 실적과 2027년 예산 승인)
+Reader: 경영지원본부장과 재무팀. 요약과 결정 요청을 먼저 읽고 표는 필요한 곳만 확인
+Tonality: Report
+  Alternative Brief: 결정 사항은 하나지만 근거 표가 5개라 3쪽 안에 들어가지 않음
+  Alternative Manual: 절차 문서가 아님
+Signals: 표 5개, 그림 0개, 약 3,400자, 한국어, 결정 요청 1건
+Dials: density 9, variance 5 (팩 기본값)
+Page 1: masthead, series line "시설 운영 보고 2026-4호" with date, subtitle, byline, notice under the rule
+Headings: Ⅰ. / 1. numbered in ink, no rules
+Components:
+  keyfigures: 요약의 1년 실적 세 가지(충전 횟수, 기당 일평균, 순운영비), 각각 기준 표기
+  callout key: 2027년 추가 예산 승인 요청
+Wrong if: 독자가 이미 실적을 알고 있어 결정 요청만 필요하다면 Brief가 맞다
+```
+
+The short form in the reply is two or three sentences: the tonality, the two alternatives and the reason
+in plain words. For example: "Built as a Report (numbered sections, contents from five pages, one
+key-figure strip). A Brief was the alternative if only the budget decision mattered; a Manual does not fit
+a results document."
+
+## The dials
+
+Each pack carries two dials, both integers from 1 to 10. The converter accepts them from the command line
+(`--density 8`) or from frontmatter (`density: 8`), and prints the values it used in its success line, for
+example `[tonality=Report, density=9, variance=5, locale=ko]`.
+
+**Density** is the dial that changes the page. It selects the margins and the body leading:
+
+| Density | Margins top / bottom / sides (mm) | Korean body pitch | English body pitch |
+|---|---|---|---|
+| 1 to 2 | 30 / 32 / 30 | 185 % of size | 140 % |
+| 3 to 4 | 28 / 30 / 28 | 185 % | 140 % |
+| 5 to 6 | 27 / 29 / 27 | 180 % | 137 % |
+| 7 | 26 / 28 / 26 | 180 % | 137 % |
+| 8 | 26 / 28 / 26 | 175 % | 133 % |
+| 9 | 25 / 27 / 25 | 175 % | 133 % |
+| 10 | 24 / 26 / 25 | 175 % | 133 % |
+
+Density 3 or lower also adds half a point to the body size. The side margins never drop under 25 mm, so
+the text block on A4 stays at 160 mm or narrower whatever the dial says.
+
+**Variance** describes how far the layout may depart from the pack's plainest form: how freely the source
+mixes components, side-by-side blocks and figure sizes. The converter validates it and prints it, and in
+this engine version no layout value is computed from it. It belongs on the card as a statement of intent:
+a variance of 2 or 3 means the author keeps to paragraphs, tables and at most one box; 6 means the author
+may use the full component set the pack allows, within the budget.
+
+**Moving a dial.** Move either dial by at most 2 from the pack value without asking, and state the change
+and its reason on the card. A density of 7 for a Report that will be read on paper by older readers is a
+reasonable unasked change; a density of 3 for the same Report changes its character and needs the user's
+word. Density cannot rescue a document that is too long for its tonality: a Brief that runs to five pages
+at density 10 is a Report.
+
+## Saying it and keeping it
+
+The card is written once, before the build, and changed only when the build shows the direction was
+wrong. If the gate reports `component.variety` on a four-page Report, the fix is to add a component the
+card already justifies or to cut the document to three pages, not to add a box with no purpose. If the
+rendered pages show a Brief spilling to four pages, the direction was wrong; rewrite as a Report and
+update the card's Wrong-if line to say what happened.
+
+Record the card in the task's build log next to the conversion line and the qa JSON. When the user asks
+why the document looks as it does, the card is the answer.
+
+## Comparing two directions
+
+When the user wants to see alternatives, build the same source in two tonalities and compare them:
+
+```bash
+python3 <skill>/run.py md-to-docx draft.md report.docx --tonality Report
+python3 <skill>/run.py md-to-docx draft.md brief.docx --tonality Brief
+python3 <skill>/run.py qa report.docx --source draft.md --compare brief.docx
+```
+
+The compare run fails with `tonality.structure` when the two documents differ in fewer than three of the
+six structural features (title block, summary form, heading numbering, component set, running head,
+contents). Two packs that pass this still need a human look at the first pages of each; the check proves
+the structures differ, not that both are good. A source written for one tonality rarely reads well in
+another, so a comparison is a decision aid, not a deliverable.
+
+## Failure patterns
+
+- **Choosing by colour.** The packs are not themes. Choosing Proposal "because it looks warmer" gives a
+  separate cover page and a centred folio to a document that needed numbered sections.
+- **A Report for everything.** The default row is a starting point. A one-page notice set as a Report
+  gets a contents check, a series line and Roman numerals it has no use for.
+- **Asking instead of choosing.** A bare request gets a built document and a card, not a menu.
+- **A component without a purpose line.** If the card cannot say what a callout is for in one line, the
+  content belongs in a paragraph.
+- **Overriding the user.** A frontmatter `tonality:` written by the user, or an explicit instruction,
+  stays even when the signals disagree; the card notes the disagreement.
+- **Mixing paths.** A tonality and a publisher in the same run is refused by the converter. A journal
+  submission never takes a tonality, and a tonality document is never gated with `--kind manuscript`.
+
+## Where to look next
+
+- `components.md`: the directive syntax the converter accepts and the component budget.
+- `page-composition.md`: the page, the type, Korean conventions and pagination.
+- `tonalities/<name>.md`: one sheet per pack, with a short source fragment.
+- `examples/`: nine complete sources across all six tonalities, each converted and gated.

package/skills/lit-docx/references/examples/01-report-ko.md

@@ -0,0 +1,160 @@
+---
+title: 사내 전기차 충전소 1년 운영 결과
+subtitle: 한빛정밀 본사·평택공장 충전기 36기의 이용, 비용, 전력 부하
+author: 한빛정밀 총무팀 시설파트
+organization: 한빛정밀(가상 기업)
+date: 2026-10-05
+short_title: 전기차 충전소 1년 운영 결과
+notice: "예시 데이터: 회사, 설비, 금액, 이용 수치는 모두 가정이다."
+tonality: Report
+---
+
+::: cover kicker="시설 운영 보고 2026-4호"
+:::
+
+# 요약
+
+본사와 평택공장에 설치한 충전기 36기는 2025년 10월부터 1년 동안 1만 2,480회 충전을 처리했다. 기당 하루 평균 0.95회로 계획치 0.8회를 넘었고, 직원 부담 요금을 반영한 순운영비는 계획보다 13% 적었다.
+
+::: keyfigures
+- **1만 2,480회** 누적 충전 횟수
+  - 2025. 10.~2026. 9., 충전 관리 시스템 집계
+- **0.95회** 기당 하루 평균 충전
+  - 역일 기준, 계획 0.8회
+- **4,360만 원** 연간 순운영비
+  - 전기요금·유지보수에서 직원 부담금 차감, 계획 5,010만 원
+:::
+
+문제는 이용이 고르지 않다는 점이다. 평택공장 완속기 22기 중 6기는 주차장 북쪽 끝에 있어 가동률이 18%에 그쳤고, 본사 급속기 2기는 출근 시간대 대기 행렬이 평균 4.2대까지 늘었다. 여름철 오후에는 충전 부하가 공장 계약전력의 여유분을 잠식해 두 차례 충전 출력을 강제로 낮췄다.
+
+2027년에는 충전기를 더 늘리기보다 배치와 시간대 운영을 바꾸는 데 예산을 쓴다. 북쪽 완속기 6기를 출입구 쪽으로 옮기고, 급속기에는 1회 40분 제한과 예약제를 도입하며, 오후 1시부터 4시까지는 완속기 출력을 7kW에서 3.5kW로 낮추는 부하 관리를 상시 적용한다.
+
+# 사업 개요
+
+충전소는 직원 전기차 보급 지원 계획의 첫 단계로 설치했다. 사업 목적은 출퇴근 차량의 전환을 돕는 동시에 공장 전력 계약을 바꾸지 않는 범위에서 충전 수요를 흡수하는 것이었다.
+
+## 설치 현황
+
+설치는 2025년 9월에 마쳤고 10월 1일부터 유료 운영을 시작했다. 본사는 방문객 주차장과 겹치지 않도록 지하 2층에, 평택공장은 직원 주차장 두 곳에 나누어 배치했다.
+
+표 1. 사업장별 충전기 설치 현황
+
+| 사업장 | 급속 100kW (기) | 완속 7kW (기) | 합계 (기) |
+|---|---:|---:|---:|
+| 본사 지하 2층 | 2 | 10 | 12 |
+| 평택공장 동측 주차장 | 2 | 8 | 10 |
+| 평택공장 북측 주차장 | 0 | 12 | 12 |
+| 평택공장 정문 | 0 | 2 | 2 |
+| 합계 | 4 | 32 | 36 |
+
+자료: 총무팀 시설파트 설비 대장(예시)
+
+## 요금과 이용 규칙
+
+직원 부담 요금은 kWh당 급속 250원, 완속 150원으로 정했다. 외부 공용 충전소 요금의 약 3분의 2 수준이다. 사번 인증 카드로만 충전할 수 있고, 충전 완료 후 30분이 지나면 분당 100원의 점유 요금을 부과한다.
+
+# 이용 실적
+
+1년 동안 등록한 직원 차량은 412대로 시작 시점 236대에서 75% 늘었다. 충전 횟수는 분기마다 증가했으며, 겨울철에는 배터리 효율 저하로 1회 충전량이 커졌다.
+
+## 분기별 충전 횟수와 충전량
+
+표 2. 분기별 충전 실적
+
+| 구분 | 2025년 4분기 | 2026년 1분기 | 2026년 2분기 | 2026년 3분기 |
+|---|---:|---:|---:|---:|
+| 급속 충전 횟수 (회) | 610 | 742 | 805 | 868 |
+| 완속 충전 횟수 (회) | 1,944 | 2,310 | 2,512 | 2,689 |
+| 총 충전량 (MWh) | 58.4 | 73.9 | 70.2 | 74.6 |
+| 등록 차량 (대) | 271 | 318 | 367 | 412 |
+
+주: 충전 횟수는 5분 미만 세션을 제외한 값이다.
+
+자료: 충전 관리 시스템 월간 보고서(예시)
+
+급속 충전은 전체 횟수의 24%였지만 전력량으로는 31%를 차지했다. 완속기는 주간 근무자가 출근 직후 꽂아 두고 점심 이후 옮기는 방식으로 하루 두 차례 쓰이는 경우가 많았다.
+
+## 충전기별 가동률 편차
+
+가동률은 충전기가 실제로 전력을 공급한 시간을 영업일 근무 시간 10시간으로 나눈 값이다. 완속기 32기의 평균은 45%였으나 위치별 차이가 컸다.
+
+표 3. 위치별 완속기 가동률
+
+| 위치 | 기수 (기) | 평균 가동률 (%) | 최저 가동률 (%) |
+|---|---:|---:|---:|
+| 본사 지하 2층 | 10 | 58 | 49 |
+| 평택공장 동측 | 8 | 52 | 44 |
+| 평택공장 북측 남쪽 열 | 6 | 39 | 31 |
+| 평택공장 북측 북쪽 열 | 6 | 18 | 11 |
+| 평택공장 정문 | 2 | 47 | 45 |
+
+자료: 충전 관리 시스템 세션 기록(예시)
+
+북쪽 열 6기는 생산동 출입구까지 걸어서 7분 거리다. 설문에 응한 이용자 128명 중 61%가 "가깝지 않으면 다른 충전기가 빌 때까지 기다린다"고 답했다.
+
+# 비용과 전력 부하
+
+운영비는 전기요금, 유지보수 계약, 통신·관리 시스템 이용료로 구성된다. 직원 부담금은 전기요금의 약 71%를 회수했다.
+
+## 연간 운영비
+
+표 4. 연간 운영비 계획과 실적
+
+| 항목 | 계획 (만 원) | 실적 (만 원) | 차이 (만 원) |
+|---|---:|---:|---:|
+| 전기요금 | 6,120 | 7,040 | 920 |
+| 유지보수 계약 | 1,800 | 1,800 | 0 |
+| 관리 시스템·통신 | 540 | 540 | 0 |
+| 직원 부담금 회수 | -3,450 | -5,020 | -1,570 |
+| 순운영비 | 5,010 | 4,360 | -650 |
+
+주: 직원 부담금 회수는 비용에서 차감하는 값이므로 음수로 적었다.
+
+자료: 재무팀 계정별 원장(예시)
+
+전기요금이 계획을 넘은 것은 이용량이 많아서다. 같은 이유로 회수액도 늘었고, 결과적으로 순운영비는 650만 원 줄었다.
+
+## 여름철 피크와 출력 제한
+
+평택공장의 계약전력 여유분은 약 600kW다. 2026년 7월 29일과 8월 12일 오후에는 생산 설비 부하와 충전 부하가 겹쳐 여유분이 80kW 아래로 떨어졌고, 시설파트가 완속기 전체 출력을 수동으로 3.5kW로 낮췄다. 두 날 모두 충전 중단은 없었지만 해당 시간대 충전량은 평소의 절반 수준이었다.
+
+평택공장 완속기 22기가 오후 1시부터 4시 사이에 동시에 7kW로 충전하면 154kW가 된다. 여유분이 줄어드는 날에는 이 부하만으로 피크 요금 구간을 넘기므로, 2027년 6월 전까지 관리 시스템에 자동 출력 제한을 설정한다.
+
+# 운영상 문제와 대응
+
+1년 동안 접수한 민원과 장애는 모두 57건이었다. 이 가운데 장기 점유가 23건으로 가장 많았고, 인증 카드 오류 14건, 충전기 고장 11건, 기타 9건 순이었다.
+
+## 장기 점유
+
+점유 요금을 도입한 뒤에도 완속기에 하루 종일 주차하는 사례가 남았다. 점유 요금을 받는 시점부터 이동까지 걸린 시간의 중앙값은 2026년 1분기 74분에서 3분기 38분으로 줄었다.
+
+## 고장과 복구 시간
+
+고장 11건의 평균 복구 시간은 2.6영업일이었다. 급속기 통신 모듈 교체처럼 부품 수급이 필요한 경우에는 최대 9영업일이 걸렸다.
+
+# 2027년 운영 계획
+
+2027년 예산은 충전기 추가 설치 대신 배치 조정과 운영 규칙 개선에 배정한다. 새로 필요한 비용은 이설 공사와 관리 시스템 기능 추가를 합해 2,150만 원이다.
+
+## 배치 조정
+
+북측 북쪽 열 완속기 6기를 생산동 출입구 앞 주차 구역으로 옮긴다. 이설 공사는 생산 휴무일인 2027년 2월 첫째 주에 진행하며 공사비는 1,480만 원으로 추산했다.
+
+## 급속기 예약제와 시간 제한
+
+본사 급속기 2기에 30분 단위 예약과 1회 40분 제한을 적용한다. 대기 행렬이 긴 오전 8시부터 10시까지는 예약 차량만 충전한다.
+
+표 5. 2027년 추가 예산
+
+| 항목 | 금액 (만 원) | 시기 |
+|---|---:|---|
+| 북측 완속기 6기 이설 | 1,480 | 2027년 2월 |
+| 예약·시간 제한 기능 | 420 | 2027년 3월 |
+| 자동 출력 제한 기능 | 250 | 2027년 5월 |
+| 합계 | 2,150 | |
+
+자료: 시설파트 견적 비교표(예시)
+
+::: callout kind=key title="결정 요청 사항"
+2027년 추가 예산 2,150만 원과 급속기 예약제 시행을 승인해 주시기 바랍니다. 승인되면 2월 이설 공사부터 순서대로 착수하고, 6월에 시행 효과를 중간 보고합니다.
+:::