@litfamily/litgravity 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +17 -3
  3. package/README_ko-KR.md +17 -3
  4. package/package.json +1 -1
  5. package/plugin/hooks/lib/lanes.mjs +65 -0
  6. package/plugin/hooks/lib/motion.mjs +34 -5
  7. package/plugin/hooks/lib/reentry.mjs +7 -0
  8. package/plugin/hooks/lib/rewind/brief.mjs +332 -0
  9. package/plugin/hooks/lib/rewind/collect.mjs +328 -0
  10. package/plugin/hooks/lib/rewind/gauge.mjs +55 -0
  11. package/plugin/hooks/lib/rewind/next-step.mjs +77 -0
  12. package/plugin/hooks/lib/rewind/redact.mjs +60 -0
  13. package/plugin/hooks/lib/rewind/transcripts.mjs +211 -0
  14. package/plugin/hooks/lib/routes.mjs +79 -5
  15. package/plugin/hooks/lib/workflow-stack.mjs +213 -0
  16. package/plugin/hooks/post-tool-use.mjs +37 -1
  17. package/plugin/hooks/pre-invocation.mjs +91 -2
  18. package/plugin/hooks/session-start.mjs +26 -3
  19. package/plugin/hooks/stop.mjs +22 -2
  20. package/plugin/hud/looks.mjs +29 -0
  21. package/plugin/hud/render.mjs +234 -12
  22. package/plugin/plugin.json +1 -1
  23. package/plugin/skills/frontend-ui-ux/SKILL.md +12 -1
  24. package/plugin/skills/frontend-ui-ux/kit/components.css +417 -0
  25. package/plugin/skills/frontend-ui-ux/kit/fonts.json +22 -0
  26. package/plugin/skills/frontend-ui-ux/kit/layouts/landing.html +164 -0
  27. package/plugin/skills/frontend-ui-ux/kit/layouts/settings.html +114 -0
  28. package/plugin/skills/frontend-ui-ux/kit/layouts/workspace.html +115 -0
  29. package/plugin/skills/frontend-ui-ux/kit/styles/computational-brutalism.json +227 -0
  30. package/plugin/skills/frontend-ui-ux/kit/styles/field-notes.json +205 -0
  31. package/plugin/skills/frontend-ui-ux/kit/styles/graphite.json +200 -0
  32. package/plugin/skills/frontend-ui-ux/kit/styles/meadow.json +199 -0
  33. package/plugin/skills/frontend-ui-ux/kit/styles/neo-brutalism.json +222 -0
  34. package/plugin/skills/frontend-ui-ux/kit/ui.js +226 -0
  35. package/plugin/skills/frontend-ui-ux/references/house-styles.md +234 -0
  36. package/plugin/skills/frontend-ui-ux/scripts/design-lock.mjs +400 -0
  37. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-lock.mjs +196 -0
  38. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-page.mjs +30 -9
  39. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-rules.mjs +20 -8
  40. package/plugin/skills/frontend-ui-ux/scripts/interface-probe.mjs +42 -9
  41. package/plugin/skills/frontend-ui-ux/scripts/pixel-art.mjs +60 -0
  42. package/plugin/skills/lit-adhd/SKILL.md +157 -0
  43. package/plugin/skills/lit-adhd/references/card-examples.md +101 -0
  44. package/plugin/skills/lit-adhd/references/status-taxonomy.md +32 -0
  45. package/plugin/skills/lit-adhd/scripts/rewind.mjs +5 -0
  46. package/plugin/skills/lit-diagram-drawer/SKILL.md +5 -3
  47. package/plugin/skills/lit-diagram-drawer/references/drawing-rules.md +1 -1
  48. package/plugin/skills/lit-diagram-drawer/references/style-guide.md +21 -12
  49. package/plugin/skills/lit-diagram-drawer/references/type-architecture.md +3 -3
  50. package/plugin/skills/lit-diagram-drawer/references/type-dependency.md +1 -1
  51. package/plugin/skills/lit-diagram-drawer/references/type-tree.md +3 -3
  52. package/plugin/skills/lit-diagram-drawer/references/type-wardley.md +1 -1
  53. package/plugin/skills/lit-diagram-drawer/scripts/diagram-craft-rules.mjs +1 -2
  54. package/plugin/skills/lit-diagram-drawer/scripts/visual-quality.mjs +1 -2
  55. package/plugin/skills/lit-docx/SKILL.md +3 -3
  56. package/plugin/skills/lit-handoff/SKILL.md +1 -0
  57. package/plugin/skills/lit-hijack/SKILL.md +263 -0
  58. package/plugin/skills/lit-hijack/references/capture-and-provenance.md +100 -0
  59. package/plugin/skills/lit-hijack/references/clean-room-build.md +75 -0
  60. package/plugin/skills/lit-hijack/references/distil-and-licence.md +67 -0
  61. package/plugin/skills/lit-hijack/references/gap-and-port-design.md +100 -0
  62. package/plugin/skills/lit-hijack/references/parity-and-report.md +85 -0
  63. package/plugin/skills/lit-hijack/scripts/hijack.mjs +953 -0
  64. package/plugin/skills/lit-plan/SKILL.md +1 -1
  65. package/plugin/skills/lit-pptx/SKILL.md +8 -8
  66. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Bold.ttf +0 -0
  67. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Regular.ttf +0 -0
  68. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/OFL.txt +93 -0
  69. package/plugin/skills/lit-pptx/fonts/provenance.json +32 -1
  70. package/plugin/skills/lit-pptx/references/agents/analyst.md +34 -56
  71. package/plugin/skills/lit-pptx/references/agents/antithesis.md +49 -67
  72. package/plugin/skills/lit-pptx/references/agents/architect.md +38 -51
  73. package/plugin/skills/lit-pptx/references/agents/critic.md +25 -41
  74. package/plugin/skills/lit-pptx/references/agents/synthesizer.md +37 -46
  75. package/plugin/skills/lit-pptx/references/agents/thesis.md +29 -49
  76. package/plugin/skills/lit-pptx/references/anti-slop-checklist.md +119 -145
  77. package/plugin/skills/lit-pptx/references/authoring-guide.md +187 -278
  78. package/plugin/skills/lit-pptx/references/consensus-protocol.md +99 -97
  79. package/plugin/skills/lit-pptx/references/data-display-cookbook.md +36 -137
  80. package/plugin/skills/lit-pptx/references/density-and-fill.md +147 -216
  81. package/plugin/skills/lit-pptx/references/design-system-azure.md +56 -85
  82. package/plugin/skills/lit-pptx/references/direction-step.md +134 -176
  83. package/plugin/skills/lit-pptx/references/examples/01-pitch-signal-ko.md +114 -115
  84. package/plugin/skills/lit-pptx/references/examples/02-pitch-studio-ko.md +66 -66
  85. package/plugin/skills/lit-pptx/references/examples/03-business-review-ledger-ko.md +63 -63
  86. package/plugin/skills/lit-pptx/references/examples/04-business-review-night-en.md +96 -96
  87. package/plugin/skills/lit-pptx/references/examples/05-research-talk-paper-en.md +81 -81
  88. package/plugin/skills/lit-pptx/references/examples/06-lecture-chalk-ko.md +103 -103
  89. package/plugin/skills/lit-pptx/references/examples/07-data-review-night-en.md +100 -98
  90. package/plugin/skills/lit-pptx/references/examples/08-image-led-atlas-ko.md +76 -76
  91. package/plugin/skills/lit-pptx/references/examples/09-briefing-gazette-ko.md +96 -96
  92. package/plugin/skills/lit-pptx/references/examples/10-status-update-ledger-ko.md +80 -80
  93. package/plugin/skills/lit-pptx/references/examples/11-portfolio-studio-en.md +72 -72
  94. package/plugin/skills/lit-pptx/references/examples/12-research-tutorial-chalk-en.md +95 -95
  95. package/plugin/skills/lit-pptx/references/examples/13-engineering-review-computational-brutalism-ko.md +173 -0
  96. package/plugin/skills/lit-pptx/references/examples/14-launch-pitch-neo-brutalism-ko.md +154 -0
  97. package/plugin/skills/lit-pptx/references/examples/15-design-lecture-bauhaus-ko.md +139 -0
  98. package/plugin/skills/lit-pptx/references/examples/16-community-programme-riso-ko.md +158 -0
  99. package/plugin/skills/lit-pptx/references/examples/17-public-data-briefing-newsroom-ko.md +179 -0
  100. package/plugin/skills/lit-pptx/references/interview-protocol.md +83 -102
  101. package/plugin/skills/lit-pptx/references/layout-families.md +161 -265
  102. package/plugin/skills/lit-pptx/references/stages/autopilot.md +30 -70
  103. package/plugin/skills/lit-pptx/references/stages/interview.md +36 -68
  104. package/plugin/skills/lit-pptx/references/stages/plan.md +26 -67
  105. package/plugin/skills/lit-pptx/references/title-treatments.md +93 -145
  106. package/plugin/skills/lit-pptx/references/tonalities/atlas.md +95 -108
  107. package/plugin/skills/lit-pptx/references/tonalities/bauhaus.md +140 -0
  108. package/plugin/skills/lit-pptx/references/tonalities/chalk.md +107 -122
  109. package/plugin/skills/lit-pptx/references/tonalities/computational-brutalism.md +150 -0
  110. package/plugin/skills/lit-pptx/references/tonalities/gazette.md +87 -111
  111. package/plugin/skills/lit-pptx/references/tonalities/ledger.md +96 -125
  112. package/plugin/skills/lit-pptx/references/tonalities/neo-brutalism.md +161 -0
  113. package/plugin/skills/lit-pptx/references/tonalities/newsroom.md +144 -0
  114. package/plugin/skills/lit-pptx/references/tonalities/night.md +104 -131
  115. package/plugin/skills/lit-pptx/references/tonalities/paper.md +114 -130
  116. package/plugin/skills/lit-pptx/references/tonalities/riso.md +137 -0
  117. package/plugin/skills/lit-pptx/references/tonalities/signal.md +96 -103
  118. package/plugin/skills/lit-pptx/references/tonalities/studio.md +81 -112
  119. package/plugin/skills/lit-pptx/scripts/compile-deck.js +4 -6
  120. package/plugin/skills/lit-pptx/scripts/craft_extras.py +135 -91
  121. package/plugin/skills/lit-pptx/scripts/deck_craft.py +1 -1
  122. package/plugin/skills/lit-pptx/scripts/embed_fonts.py +13 -1
  123. package/plugin/skills/lit-pptx/scripts/layout_inventory.py +1 -1
  124. package/plugin/skills/lit-pptx/scripts/learn_template.py +1 -1
  125. package/plugin/skills/lit-pptx/scripts/lib/grid-resolver.js +101 -110
  126. package/plugin/skills/lit-pptx/scripts/lib/layout-resolver.js +9 -15
  127. package/plugin/skills/lit-pptx/scripts/lib/render-pack.js +370 -563
  128. package/plugin/skills/lit-pptx/scripts/lib/slide-grid.js +104 -0
  129. package/plugin/skills/lit-pptx/scripts/lib/template-registry.js +57 -6
  130. package/plugin/skills/lit-pptx/scripts/qa_deck.py +6 -6
  131. package/plugin/skills/lit-pptx/scripts/render_pages.py +31 -0
  132. package/plugin/skills/lit-pptx/scripts/validate_pptx.py +1 -1
  133. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v1.md +167 -191
  134. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v2.md +117 -166
  135. package/plugin/skills/lit-pptx/specs/template-enrollment-contract.md +307 -330
  136. package/plugin/skills/lit-pptx/templates/tonalities/atlas/pack.yaml +1 -1
  137. package/plugin/skills/lit-pptx/templates/tonalities/bauhaus/pack.yaml +98 -0
  138. package/plugin/skills/lit-pptx/templates/tonalities/chalk/pack.yaml +1 -1
  139. package/plugin/skills/lit-pptx/templates/tonalities/computational-brutalism/pack.yaml +99 -0
  140. package/plugin/skills/lit-pptx/templates/tonalities/gazette/pack.yaml +1 -1
  141. package/plugin/skills/lit-pptx/templates/tonalities/ledger/pack.yaml +1 -1
  142. package/plugin/skills/lit-pptx/templates/tonalities/neo-brutalism/pack.yaml +107 -0
  143. package/plugin/skills/lit-pptx/templates/tonalities/newsroom/pack.yaml +99 -0
  144. package/plugin/skills/lit-pptx/templates/tonalities/night/pack.yaml +1 -1
  145. package/plugin/skills/lit-pptx/templates/tonalities/paper/pack.yaml +1 -1
  146. package/plugin/skills/lit-pptx/templates/tonalities/riso/pack.yaml +99 -0
  147. package/plugin/skills/lit-pptx/templates/tonalities/signal/pack.yaml +2 -2
  148. package/plugin/skills/lit-pptx/templates/tonalities/studio/pack.yaml +1 -1
  149. package/plugin/skills/lit-schematic/SKILL.md +114 -0
  150. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/build.mjs +38 -0
  151. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/scene.mjs +133 -0
  152. package/plugin/skills/lit-schematic/examples/journal-adsorption-rig/build.mjs +87 -0
  153. package/plugin/skills/lit-schematic/examples/pid-dosing-skid/build.mjs +85 -0
  154. package/plugin/skills/lit-schematic/references/cutaway-outputs.md +70 -0
  155. package/plugin/skills/lit-schematic/references/isometric-craft.md +101 -0
  156. package/plugin/skills/lit-schematic/references/journal-figures.md +72 -0
  157. package/plugin/skills/lit-schematic/references/kit-api.md +134 -0
  158. package/plugin/skills/lit-schematic/references/pfd-and-layout.md +53 -0
  159. package/plugin/skills/lit-schematic/references/pid-drafting.md +103 -0
  160. package/plugin/skills/lit-schematic/references/pid-symbols.md +163 -0
  161. package/plugin/skills/lit-schematic/references/verification.md +100 -0
  162. package/plugin/skills/lit-schematic/scripts/doctor.mjs +57 -0
  163. package/plugin/skills/lit-schematic/scripts/lib/figure.mjs +81 -0
  164. package/plugin/skills/lit-schematic/scripts/lib/fonts.mjs +27 -0
  165. package/plugin/skills/lit-schematic/scripts/lib/geom.mjs +113 -0
  166. package/plugin/skills/lit-schematic/scripts/lib/interactive.mjs +292 -0
  167. package/plugin/skills/lit-schematic/scripts/lib/isa.mjs +115 -0
  168. package/plugin/skills/lit-schematic/scripts/lib/iso.mjs +719 -0
  169. package/plugin/skills/lit-schematic/scripts/lib/legend-sheet.mjs +162 -0
  170. package/plugin/skills/lit-schematic/scripts/lib/pid.mjs +937 -0
  171. package/plugin/skills/lit-schematic/scripts/lib/png.mjs +132 -0
  172. package/plugin/skills/lit-schematic/scripts/lib/qa-core.mjs +658 -0
  173. package/plugin/skills/lit-schematic/scripts/lib/route.mjs +218 -0
  174. package/plugin/skills/lit-schematic/scripts/lib/sheet.mjs +890 -0
  175. package/plugin/skills/lit-schematic/scripts/lib/svg.mjs +82 -0
  176. package/plugin/skills/lit-schematic/scripts/lib/theme.mjs +115 -0
  177. package/plugin/skills/lit-schematic/scripts/motion.mjs +129 -0
  178. package/plugin/skills/lit-schematic/scripts/qa.mjs +92 -0
  179. package/plugin/skills/lit-schematic/scripts/render.mjs +233 -0
  180. package/plugin/skills/lit-schematic/scripts/scaffold.mjs +60 -0
  181. package/plugin/skills/lit-scientific-visualization/SKILL.md +17 -6
  182. package/plugin/skills/lit-typographic-motion/SKILL.md +58 -48
  183. package/plugin/skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES +13 -2
  184. package/plugin/skills/lit-typographic-motion/engine/blender/runner.py +218 -0
  185. package/plugin/skills/lit-typographic-motion/engine/core/presets.mjs +1 -1
  186. package/plugin/skills/lit-typographic-motion/engine/node/analysis.mjs +65 -1
  187. package/plugin/skills/lit-typographic-motion/engine/node/assets.mjs +298 -0
  188. package/plugin/skills/lit-typographic-motion/engine/node/blender.mjs +143 -0
  189. package/plugin/skills/lit-typographic-motion/engine/node/board.mjs +136 -0
  190. package/plugin/skills/lit-typographic-motion/engine/node/brief.mjs +7 -1
  191. package/plugin/skills/lit-typographic-motion/engine/node/chrome.mjs +9 -12
  192. package/plugin/skills/lit-typographic-motion/engine/node/cover-assets.mjs +5 -3
  193. package/plugin/skills/lit-typographic-motion/engine/node/cover-capture.mjs +7 -6
  194. package/plugin/skills/lit-typographic-motion/engine/node/cover-treatment.mjs +37 -4
  195. package/plugin/skills/lit-typographic-motion/engine/node/cover.mjs +19 -8
  196. package/plugin/skills/lit-typographic-motion/engine/node/done.mjs +45 -6
  197. package/plugin/skills/lit-typographic-motion/engine/node/frame-worker.mjs +7 -5
  198. package/plugin/skills/lit-typographic-motion/engine/node/gallery.mjs +121 -0
  199. package/plugin/skills/lit-typographic-motion/engine/node/host.mjs +34 -0
  200. package/plugin/skills/lit-typographic-motion/engine/node/house.mjs +44 -0
  201. package/plugin/skills/lit-typographic-motion/engine/node/look.mjs +34 -20
  202. package/plugin/skills/lit-typographic-motion/engine/node/pipeline.mjs +19 -9
  203. package/plugin/skills/lit-typographic-motion/engine/node/scaffold.mjs +210 -0
  204. package/plugin/skills/lit-typographic-motion/engine/node/score.mjs +639 -0
  205. package/plugin/skills/lit-typographic-motion/engine/node/sound-cli.mjs +21 -4
  206. package/plugin/skills/lit-typographic-motion/engine/node/sound.mjs +127 -29
  207. package/plugin/skills/lit-typographic-motion/engine/node/stage-capture.mjs +7 -6
  208. package/plugin/skills/lit-typographic-motion/engine/node/stage-gate.mjs +59 -5
  209. package/plugin/skills/lit-typographic-motion/engine/node/stage-qa.mjs +141 -9
  210. package/plugin/skills/lit-typographic-motion/engine/node/stage-serve.mjs +28 -5
  211. package/plugin/skills/lit-typographic-motion/engine/node/stage.mjs +82 -14
  212. package/plugin/skills/lit-typographic-motion/engine/node/styles.mjs +213 -0
  213. package/plugin/skills/lit-typographic-motion/engine/node/treatment.mjs +311 -10
  214. package/plugin/skills/lit-typographic-motion/engine/stage/cover-init.js +14 -2
  215. package/plugin/skills/lit-typographic-motion/engine/stage/init.js +11 -1
  216. package/plugin/skills/lit-typographic-motion/engine/stage/qa.js +6 -1
  217. package/plugin/skills/lit-typographic-motion/engine/stage/stage-kit.js +83 -0
  218. package/plugin/skills/lit-typographic-motion/engine/vendor/three/LICENSE +21 -0
  219. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/environments/RoomEnvironment.js +144 -0
  220. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/geometries/RoundedBoxGeometry.js +155 -0
  221. package/plugin/skills/lit-typographic-motion/engine/vendor/three/three.module.js +54571 -0
  222. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/expected.json +69 -0
  223. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/index.html +139 -0
  224. package/plugin/skills/lit-typographic-motion/recipes/orbit-loop/expected.json +6 -4
  225. package/plugin/skills/lit-typographic-motion/recipes/painted-light/expected.json +4 -2
  226. package/plugin/skills/lit-typographic-motion/recipes/weight-tide/expected.json +7 -5
  227. package/plugin/skills/lit-typographic-motion/references/cover.md +394 -443
  228. package/plugin/skills/lit-typographic-motion/references/craft-loop.md +57 -87
  229. package/plugin/skills/lit-typographic-motion/references/depth.md +122 -0
  230. package/plugin/skills/lit-typographic-motion/references/look.md +94 -129
  231. package/plugin/skills/lit-typographic-motion/references/runtime.md +58 -91
  232. package/plugin/skills/lit-typographic-motion/references/sound.md +130 -99
  233. package/plugin/skills/lit-typographic-motion/references/stage.md +190 -215
  234. package/plugin/skills/lit-typographic-motion/references/studio.md +245 -0
  235. package/plugin/skills/lit-typographic-motion/references/style-bibles.md +108 -97
  236. package/plugin/skills/lit-typographic-motion/references/treatment.md +191 -143
  237. package/plugin/skills/lit-typographic-motion/scripts/motion-doctor.mjs +17 -5
  238. package/plugin/skills/lit-typographic-motion/scripts/motion.mjs +47 -7
  239. package/plugin/skills/lit-typographic-motion/styles/paper.json +41 -0
  240. package/plugin/skills/lit-typographic-motion/styles/swiss-signal.json +41 -0
  241. package/plugin/skills/lit-typographic-motion/styles/terminalcore.json +42 -0
  242. package/plugin/skills/lit-typographic-motion/styles/tidal.json +41 -0
  243. package/plugin/skills/litresearch/SKILL.md +1 -0
  244. package/plugin/skills/readme-studio/SKILL.md +2 -0
  245. package/plugin/skills/review-work/SKILL.md +1 -1
  246. package/plugin/skills/start-work/SKILL.md +1 -1
@@ -1,341 +1,250 @@
1
- # Authoring guide: Markdown to PPTX
1
+ # Authoring Guide (Markdown → PPTX)
2
2
 
3
- This guide teaches the dialect that `scripts/compile-deck.js` reads. A deck is one Markdown file. The
4
- design (colours, type, title frames, decoration) is owned by a tonality pack or by a named legacy
5
- template, so the source carries only structure and words. The formal contract sits in
6
- `specs/markdown-slide-spec-v1.md` and `specs/markdown-slide-spec-v2.md`; the AST shapes sit in the two
7
- JSON schemas next to them. Every command below uses `SKILL_ROOT`, the directory of this skill's `SKILL.md`.
3
+ How to author a deck in the constrained Markdown dialect that `scripts/compile-deck.js` compiles. The tonality pack (or a named legacy template) owns fonts, palette, dimensions and decoration. The full contract is `specs/markdown-slide-spec-v1.md`; this guide is the working reference.
8
4
 
9
- ## 1. Anatomy of a source file
5
+ ## 1. Pick a direction
10
6
 
11
- A source file is a frontmatter block followed by slide chunks. The loader (`scripts/lib/markdown-loader.js`)
12
- works in three steps: it reads the frontmatter, splits the rest on lines that hold only `---`, and reads
13
- the `layout:` line at the top of every chunk.
7
+ A deck compiles under a tonality (a design direction read from a pack) or under a legacy template
8
+ the user named. Choose it with the direction step (`direction-step.md`) before writing slides, and
9
+ put it in the frontmatter so the source carries its own look:
14
10
 
11
+ ```bash
12
+ node "$SKILL_ROOT/scripts/compile-deck.js" --list-tonalities # thirteen tonalities and the legacy templates
13
+ node "$SKILL_ROOT/scripts/compile-deck.js" --list-layouts <tonality> # families, the titles each allows, variants
14
+ node "$SKILL_ROOT/scripts/compile-deck.js" --list-templates # legacy and learned templates
15
+ ```
16
+
17
+ | Tonality | One line |
18
+ |---|---|
19
+ | `ledger` | numbers first, dense, tabular; business reviews and status updates |
20
+ | `signal` | short, bold slides with one hot accent; pitches and launches |
21
+ | `atlas` | pictures carry the deck, titles on panels or under images |
22
+ | `chalk` | teaching: numbered steps, worked examples, marked terms |
23
+ | `paper` | ink on white, figures and booktabs tables, citations |
24
+ | `gazette` | Korean briefing pages: header band, boxed summary, 개조식 evidence |
25
+ | `studio` | editorial grid, asymmetric splits, margin-bar titles, large real numerals |
26
+ | `night` | dark ground for data and technical keynotes |
27
+
28
+ Legacy templates (`AZURE-PRO`, `AZURE-A2Z`, `BOILERPLATE-PRETENDARD`, `BOILERPLATE-A2Z`, or one
29
+ learned from the user's deck) keep their single look and are used only when the user names one.
30
+ Each tonality sheet in `tonalities/` lists its tokens, title treatments, families and two worked
31
+ slides; `examples/` holds complete decks.
32
+
33
+ Font note: every tonality sets the deck in **Pretendard** Regular and Bold by default; hierarchy
34
+ comes from size, weight, colour and placement. The **에이투지체** (A2Z) faces are used only when the
35
+ user or the source asks for them: `faces: a2z` in the frontmatter (or `--faces a2z`) applies the
36
+ pack's `faces-a2z` map. A2Z ships one family *per weight* (`에이투지체 7 Bold`), so weight is chosen
37
+ by family name, never a bold flag. The pack encodes this; you write content.
38
+
39
+ ## 2. Deck skeleton
15
40
  ```markdown
16
41
  ---
17
42
  tonality: ledger
18
- title: 2026년 3분기 시립도서관 이용 현황
19
- date: 2026-10-05
43
+ title: Deck Title
44
+ date: 2026-06-29
20
45
  notice: 예시 데이터 — 실제 수치로 바꿔 주세요
21
46
  ---
22
47
 
23
48
  ---
24
49
  layout: cover-figures
25
50
 
26
- # 2026년 3분기 시립도서관 이용 현황
51
+ # Deck Title
27
52
  ---
28
53
 
29
54
  ---
30
- layout: kpi-row
31
-
32
- ## 3분기 이용 지표
55
+ layout: chart-insight
33
56
 
34
- | 방문자 | 대출 권수 | 신규 회원 | 좌석 점유율 |
35
- |---|---|---|---|
36
- | 18.2만 명 | 41.0만 권 | 6,320명 | 78% |
37
- | 전년 동기 +12% | 전년 동기 +9% | 목표 6,000명 | 목표 75% |
57
+ ## The title names the topic as a label
38
58
 
39
- > 3분기 이용 지표 (예시 데이터)
59
+ ::: chart type=column unit="억 원"
60
+ | 분기 | 매출 | 계획 |
61
+ |---|---|---|
62
+ | 1Q | 1,120 | 1,100 |
63
+ | 2Q | 1,184 | 1,140 |
64
+ > 분기별 매출과 계획, 2026년 (예시 데이터)
65
+ :::
40
66
 
41
- - **요약:** 방문과 대출이 모두 늘었고 신규 회원은 목표를 넘었다
42
- - 좌석 점유율은 개관 이후 처음 목표를 넘었다
43
- - 출처: 예시 이용 통계 시스템, 2026년 9월 말
67
+ - The claim the chart supports, as the first takeaway
68
+ - What it compares with, and over which period
69
+ - What it implies or what happens next
44
70
  ---
45
- ```
46
71
 
47
- This skeleton compiles under `ledger` and passes the gate. The separator is a `---` line, a blank line, and the next `---` that opens the following chunk: the
48
- closing `---` of one slide and the opening `---` of the next slide's `layout:` chunk. A line made only of
49
- three dashes is always a separator, so a horizontal rule inside a slide would cut it in two. Table
50
- separator rows such as `|---|---|` are safe because the dashes share the line with pipes.
72
+ ---
73
+ layout: closing-ask
51
74
 
52
- ### Frontmatter keys
75
+ ## The decision you ask for
53
76
 
54
- The frontmatter is flat `key: value` text (no nesting). `title` is required, and so is one of
55
- `tonality` or `template`.
77
+ | 안건 | 금액 | 결정 시점 |
78
+ |---|---|---|
79
+ | … | … | … |
56
80
 
57
- | Key | Meaning |
58
- |---|---|
59
- | `tonality` | one of the eight pack ids; selects the design when no flag is given |
60
- | `template` | a legacy or learned template name; it is recorded, and the render still needs `--template <NAME>` |
61
- | `title` | deck title |
62
- | `date`, `department`, `presenter` | metadata that cover variants may print |
63
- | `density`, `variance` | dials, 1-10; clamped into range. Move one only when the direction card says so (`direction-step.md`) |
64
- | `canvas` | `16:9` (default) or `4:3`, when the pack lists it |
65
- | `faces` | `a2z` swaps the pack to the A2Z faces; any other value keeps Pretendard |
66
- | `notice` | one tag at the bottom left of every slide; use it whenever values are examples |
67
- | `data` | a data file (or a comma-separated list) whose numbers fill `{{ ... }}` placeholders (section 8) |
68
- | `accent`, `font`, `background` | recolour, font swap and `mesh` background on the Azure legacy templates only |
69
-
70
- Slide-local keys follow the `layout:` line and end at the first blank line. The set is closed to `title:`
71
- (pins one title treatment, `title-treatments.md`) and `variant:` (legacy templates). A line such as
72
- `source: internal data` stays body text, and so does a mistyped `varient:`, which makes the typo visible
73
- on the slide.
74
-
75
- ## 2. Choose the design before writing
76
-
77
- ```sh
78
- node "$SKILL_ROOT/scripts/compile-deck.js" --list-tonalities # eight tonalities, then the legacy templates
79
- node "$SKILL_ROOT/scripts/compile-deck.js" --list-layouts ledger # families with the titles each takes, covers, sections, closings
80
- node "$SKILL_ROOT/scripts/compile-deck.js" --list-layouts AZURE-PRO # a legacy template: layouts, blocks, regions
81
- node "$SKILL_ROOT/scripts/compile-deck.js" --list-templates # legacy and learned templates with their canvas
81
+ - 다음 단계: who does what, by when
82
+ ---
82
83
  ```
84
+ **Separator rule (critical):** a `---` line, then a blank line, then `---` + the next `layout:`. This is how slides are split — see the spec.
83
85
 
84
- | Tonality | One line |
85
- |---|---|
86
- | `ledger` | numbers first, dense and tabular: business reviews, status updates |
87
- | `signal` | short slides, one hot accent: pitches and launches |
88
- | `atlas` | pictures carry the deck: products, places, field work |
89
- | `chalk` | teaching: numbered steps, worked examples, marked terms |
90
- | `paper` | ink on white: figures, booktabs tables, citations |
91
- | `gazette` | Korean briefing pages: header band, boxed summary |
92
- | `studio` | editorial grid, asymmetric splits, large numerals |
93
- | `night` | dark ground for data and technical keynotes |
86
+ Frontmatter keys for the direction: `tonality:`, and `density:` / `variance:` only when the card
87
+ moves a dial. Slide keys after `layout:`: `title: <treatment>` pins one slide's title treatment
88
+ (`title-treatments.md`); `variant:` belongs to legacy templates.
94
89
 
95
- The tonality sheets in `references/tonalities/` list tokens, title treatments, families and two worked
96
- slides; `references/examples/` holds twelve complete decks that pass the gate. Every pack sets the deck
97
- in Pretendard Regular and Bold; hierarchy comes from size, weight, colour and placement. A2Z faces apply
98
- when the user or the source asks (`faces: a2z` or `--faces a2z`), and A2Z weight is chosen by family name
99
- (`에이투지체 7 Bold`), which the pack encodes for you.
90
+ ## 3. Layout families
100
91
 
101
- Legacy templates (`AZURE-PRO`, `AZURE-A2Z`, `BOILERPLATE-PRETENDARD`, `BOILERPLATE-A2Z`, or one learned
102
- from a user's deck) keep their own single look. A legacy deck compiles with `--template <NAME>` on the
103
- command line, and the frontmatter still needs a `template:` or `tonality:` line. A tonality chosen
104
- through `--tonality <id>` overrides the template name.
92
+ Under a tonality, `layout:` names a family (the slide's job) or a cover, section or closing variant.
93
+ `layout-families.md` lists all of them with the source each one reads; `--list-layouts <tonality>`
94
+ shows which the chosen pack carries. Write the source so the slide fills (`density-and-fill.md`):
95
+ a takeaway under every table, evidence under a big number, the next step under an ask.
105
96
 
106
- ## 3. Slide grammar
97
+ Under a legacy template the five original layouts remain: `cover`, `content`, `main` (content plus a
98
+ `::: main-box` callout), `summary` (two grouped blocks) and `closing`; `section` exists on the Azure
99
+ templates. Check `--list-layouts <TEMPLATE>` for the blocks each accepts.
107
100
 
108
- Under a tonality, `layout:` names a family (the slide's job) or a cover, section or closing variant;
109
- `references/layout-families.md` lists them with the source each one reads. Under a legacy template the
110
- original layouts apply: `cover`, `content`, `main` (content plus a `::: main-box` callout), `summary`
111
- (groups under `###` headings), `section`, `closing`, and the open-ended `free`.
101
+ ### Executive/research compositions
112
102
 
113
- | Construct | Syntax | Notes |
114
- |---|---|---|
115
- | Title | `#` on cover and closing, `##` on a content slide | the first heading line becomes the slide title; `###` opens a summary group |
116
- | Bullet | `- text` | one level |
117
- | Group | `- **Heading**` then indented `(1) detail` lines | numbers are typed in parentheses |
118
- | Run-in label | `- **요약:** text` | write the colon; the engine adds one for body bullets, a box needs yours (OF-118) |
119
- | Table | pipe table, header row, separator row | a `>` line right under it is its caption |
120
- | Table link | `[원문](https://example.org/record)` in a cell | becomes an external hyperlink relationship |
121
- | Image | `![caption](path)` on a line of its own | alt text is the visible figure caption |
122
- | Chart | `::: chart type=column unit="억 원"` | section 6 |
123
- | Callout | `::: main-box` | legacy `main` layout |
124
- | Lead | `::: key-message` | a one-line lead under the title where the layout has the region |
125
- | Notes | `::: notes` | footnote or speaker text on legacy layouts |
126
-
127
- Raw HTML (`<div>`, `<span>`, `<table>`, `<style>`), inline `style="..."` attributes and `<script>` stop the
128
- compile with a slide and line number. Layout comes from the template contract, so the source has no CSS
129
- to carry.
130
-
131
- Source lines that open with `출처:`, `자료:`, `주:`, `Source:` or `Note:` leave the takeaway list and
132
- set as a strip at the foot of the body. Put them last.
133
-
134
- ## 4. Titles and captions
135
-
136
- A title names the subject, the measure and the period. The claim opens the body. OF-114 reads the last
137
- word of a Korean title and the verbs of an English one and fails a sentence:
138
-
139
- | Fails | Passes |
140
- |---|---|
141
- | 서가 이용이 지난해보다 늘었다 | 서가 이용 추이, 2025-2026 |
142
- | Revenue grew 18% in Q3. | Revenue by division, Q3 2026 |
103
+ These are semantic compositions of existing v1 blocks, so they remain renderer compatible:
143
104
 
144
- A question and a quotation set as a statement pass. A trailing parenthesis such as `(예시 데이터)` is set
145
- aside before the reading. The cover subtitle follows the same rule.
105
+ 1. **figure plus interpretation**
146
106
 
147
- Captions bind a figure or a table to what it shows:
107
+ ```markdown
108
+ ![Figure 1. Pressure trend | Source: test report, p. 12](assets/pressure.png)
148
109
 
149
- - A table caption is a `>` line directly under the table. The engine numbers it in the deck's language
150
- ("표 1.", "Table 1.") and keeps a number you typed instead of doubling it.
151
- - A figure caption is the image's alt text: `![도 1. 월별 방문자 | 출처: 예시 이용 통계, p. 12](assets/example-a.png)`.
152
- The gate (evidence binding) wants a figure number and a `Source:` or `출처:` in the visible caption of
153
- every picture whose description declares it as a figure or as evidence.
154
- - A figure exported on white and placed on a dark tonality fails OF-117. Save a dark copy beside the
155
- original with `.dark` before the extension (`flow.png` and `flow.dark.png`, side by side in one folder), or
156
- draw the numbers as a native chart.
157
- - Image paths resolve against the deck's own folder first, then the working directory.
110
+ - **Observation** Pressure remained inside the validated band.
111
+ (1) Basis: only one operating condition was sampled.
112
+ (2) Implication: repeat the test before scale-up.
113
+ ```
158
114
 
159
- ## 5. Writing bullets that fill the page
115
+ 2. **table plus decision takeaway** — keep units in headers, quantitative cells compact, ≤6 columns, and add a blockquote caption/source immediately after the table.
116
+ 3. **source capture** — use a legible screenshot with locator/date in the alt text and state in the body what it shows and why it matters.
117
+ 4. **two-record appendix evidence** — show at most two records per slide; include a one-line summary, source locator, and clickable DOI/canonical link when available. In a table cell, write `[원문](https://example.org/record)`; the PPTX renderer emits an external OOXML hyperlink relationship.
160
118
 
161
- Give each content slide the facts a careful reader asks for: the figure, its comparison, its period,
162
- its source and the implication. `density-and-fill.md` explains how the engine places them. Merge two
163
- thin slides into one before adding filler, and put example values under a `notice:` tag.
119
+ Do not write authoring trace or unresolved placeholders. Treat overclaim, jargon, imperative tone, unsupported schedules, hierarchy, and visual density as review-only items to resolve during rendered page review.
164
120
 
165
- ## 6. Charts and KPI rows
121
+ ## 4. Compile
122
+ ```bash
123
+ node "$SKILL_ROOT/scripts/compile-deck.js" deck.md --pptx out.pptx --embed-fonts # tonality: from the frontmatter
124
+ node "$SKILL_ROOT/scripts/compile-deck.js" deck.md --template <TEMPLATE> --pptx out.pptx --embed-fonts # a named legacy template
125
+ ```
126
+ `--embed-fonts` makes the deck self-contained (renders on machines without the font). `--ast out.json` dumps the intermediate AST.
166
127
 
167
- ```markdown
168
- ::: chart type=column unit="억 원"
169
- | 분기 | 매출 | 영업이익 |
170
- |---|---|---|
171
- | 1Q | 1,120 | 101 |
172
- | 2Q | 1,184 | 110 |
173
- > 분기별 매출과 영업이익 (예시 데이터)
174
- :::
128
+ ## 5. Verify (always)
129
+ ```bash
130
+ python3 "$SKILL_ROOT/scripts/qa_deck.py" out.pptx # overflow, contrast, anti-slop, craft floor and the deck output checks; non-zero = FAIL
131
+ python3 "$SKILL_ROOT/scripts/render_pages.py" out.pptx --out-dir renders --pages 5 # then open renders/page-*.png
175
132
  ```
133
+ A clean gate is defect-absence, not quality — read the rendered pages. See `references/anti-slop-checklist.md`.
134
+
135
+ ## 6. Anti-patterns (fix before shipping)
136
+ - Generic titles ("개요"/"Overview") → make them specific.
137
+ - Padding bullets that restate the heading → cut or add real information.
138
+ - Manually adding logos/lines/colors/fonts → the pack or template applies decoration; don't.
139
+ - Positioning a title with a free box → every treatment has one frame; pin a different treatment with `title:` instead.
140
+ - A table, a big number or an ask with nothing under it → add the takeaway, the evidence or the next step (`density-and-fill.md`).
141
+ - Overloaded slides (> ~8 bullets, > ~8 table rows, > 4 items per summary group) → split.
142
+ - A data slide without its basis, comparison, period or source → add them; end with `출처:` (`Source:`).
143
+ - Placeholder/AI-slop wording → gated by `scripts/forbidden-terms.json`.
144
+ - Evidence image with only a filename-like alt → write a numbered caption plus `Source:`/`출처:` so the visible caption stays bound to the figure.
145
+ - Appendix DOI/canonical/raw URL field without a hyperlink → add an actual PowerPoint hyperlink. QA detects the field directly and verifies its external OOXML relationship; no special “link available” phrase is required.
146
+
147
+ ## 7. Bring your own brand
148
+ ```bash
149
+ python3 "$SKILL_ROOT/scripts/learn_template.py" corporate.pptx --name MY-BRAND # extracts fonts/palette/geometry, closed-set verified
150
+ node "$SKILL_ROOT/scripts/compile-deck.js" deck.md --template MY-BRAND --pptx out.pptx --embed-fonts
151
+ ```
152
+ The learned template only references fonts/colors/assets present in your source (off-brand-by-construction).
176
153
 
177
- `type` is `column` (default), `bar`, `line`, `area`, `stacked`, `pie` or `doughnut`; `unit`, `title` and
178
- `labels=false` are optional. The first column holds the categories and each further column is a series
179
- (pie and doughnut read the first series). The block compiles to a `kpi-table` block with a `chart` field,
180
- so any layout that takes a table takes a chart, and a renderer without chart support shows the numbers
181
- as a table. The chart is native, so PowerPoint's Edit Data opens its values.
154
+ ## Run-in labels
182
155
 
183
- One series carries the accent: the latest period, else the measured series beside a plan or target, else
184
- the last column. Put the proposed or current series last when the headers say neither. A headline-number
185
- row is a one-row table of up to six short values, with an optional second row of bases; the first row
186
- holds at most 12 characters per cell and the basis row at most 24. Measured scientific data belongs to
187
- `lit-scientific-visualization`: export the deck's visual system with
188
- `compile-deck.js deck.md --export-viz-context ctx.json` and place the result as a captioned figure.
156
+ A point may open with a bold label: `- **요약:** 앱에서 맡기면 …`, `- **Basis:** 1.0 L/min feed`. Write
157
+ the colon; the engine adds one when the label ends without a separator (`**요약** 앱에서 …` is set as
158
+ "**요약:** 앱에서 …"), because a bold word running into its sentence reads as part of it. A bold line
159
+ with nothing after it is a group heading and takes no colon. The gate fails a run-in label without a
160
+ separator (OF-118). An agenda numbers its own rows, so its title stands without a numeral beside it
161
+ (OF-119).
189
162
 
190
- ## 7. Placement tiers (spec v2)
163
+ ## Placement (spec v2)
191
164
 
192
- Reach for the smallest freedom that says the thing. Every tier gives up a guardrail.
165
+ Reach for the least freedom that says the thing. Each tier gives up a guardrail, and
166
+ the one below it is harder to get right.
193
167
 
194
168
  | Want | Write | Gives up |
195
169
  |---|---|---|
196
- | a different slot in the template's geometry | `::: region name=<region>` | nothing; legacy templates only |
197
- | two or three things side by side | `:::: columns 2fr 1fr gap=0.3` holding `::: col` blocks | you choose the split |
198
- | something the template never planned | `::: box x= y= w= h=` and `::: shape <kind> ...` | all reflow around it |
199
- | a slide with no template furniture | `layout: free` | the template's whole contribution |
200
- | the same layout with other furniture | `variant: split-navy` | nothing; legacy templates only |
170
+ | the template's geometry, a different slot | `::: region name=<region>` | nothing |
171
+ | two things beside each other | `:::: columns 2fr 1fr gap=0.3` with `::: col` inside | portability stays; you choose the split |
172
+ | something the template never anticipated | `::: box x= y= w= h=` and `::: shape <kind> …` | every guardrail — nothing reflows around it |
173
+ | a slide with no template furniture at all | `layout: free` | the template's whole contribution |
174
+ | a different look, same layout | `variant: split-navy` | nothing |
201
175
 
202
- Containers nest by fence length: the outer fence is longer (`::::` holds `:::`). The depth stops at two.
203
- Same-length nesting stops the compile and names the line.
176
+ Containers nest by fence length: the outer fence is longer (`::::` holds `:::`).
177
+ `::: shape` is one line with no closing fence. Shapes sit behind content, boxes on top.
204
178
 
205
- **Columns.** Tracks are ratios and the engine divides the body region between them (`gap` in inches,
206
- default `0.25`). The track count must equal the number of `::: col` blocks. A column holds Markdown
207
- (bullets, a pipe table, an image line) and no directive, so a chart or a box sits outside the columns. On
208
- a legacy template the columns replace the body region, and a bullet written outside them on the same slide
209
- is dropped without a message: put every body line inside a column.
179
+ Full contract: `specs/markdown-slide-spec-v2.md`.
210
180
 
211
- ```markdown
212
- ---
213
- layout: content
181
+ **A slide built with a box, a shape or `layout: free` has to be looked at** — render it,
182
+ gate it, then read the rendered page. The gate reports defects; it does not report that a
183
+ slide reads badly.
214
184
 
215
- ## 접수량과 처리 시간
185
+ ## Charts, KPI cards and sample data
216
186
 
217
- :::: columns 2fr 1fr gap=0.3
218
- ::: col
219
- - **접수량**
220
- (1) 3분기 접수 12,400건
221
- (2) 전분기 대비 +8%
222
- :::
223
- ::: col
224
- ![도 1. 처리 현황](assets/example-a.png)
225
- :::
226
- ::::
227
- ---
228
- ```
229
-
230
- The fragment is one slide taken out of a deck; compiled alone, a slide this short leaves its page
231
- sparse, and in a full deck it sits among fuller slides.
232
-
233
- **Regions.** `::: region name=table` sends its content to a named region of a legacy layout. A name the
234
- layout lacks stops the compile with the list of regions. A region holds one block; two blocks claiming
235
- one region stop the compile and name both exits (`region` or `columns`). Send a captioned picture
236
- through `columns`: inside `region name=image` the alt text also emits a caption block with the same hint,
237
- and the compile stops with `Image source is empty`. Under a tonality the family fixes the regions and a `region` block has no effect.
238
-
239
- **Boxes and shapes.** `::: box x=0.7 y=1.8 w=3.6 h=1.6` takes inches on the template canvas (13.333 x
240
- 7.5 for 16:9) and needs all four numbers. `role=` names a font role of a legacy template; `z=under` or
241
- `z=over` (box default `over`). `::: shape rect x=0.5 y=1.6 w=4 h=2 fill=#E2F0EC z=under` is one line with
242
- no closing fence. Kinds: `rect`, `roundRect`, `pill`, `ellipse`, `ring`, `line`, `text`, `image`. Style
243
- keys: `fill line lw radius rotate text color size align valign char_spacing bold asset dir src note`; an
244
- unknown key stops the compile. A `line` needs `x y w` only and takes its thickness from `lw`.
187
+ Business numbers are drawn here, natively, so they stay editable in PowerPoint
188
+ (right-click → Edit Data):
245
189
 
246
190
  ```markdown
247
- ---
248
- layout: free
249
-
250
- ::: shape rect x=0.5 y=1.6 w=4 h=2 fill=#E2F0EC z=under
251
- ::: box x=0.7 y=1.8 w=3.6 h=1.6
252
- **결론:** 세 가지로 요약한다
191
+ ::: chart type=column unit="억 원"
192
+ | 분기 | 매출 | 영업이익 |
193
+ |---|---|---|
194
+ | 1Q | 1,120 | 101 |
195
+ | 2Q | 1,184 | 110 |
196
+ > 분기별 매출과 영업이익 (예시 데이터)
253
197
  :::
254
- ---
255
- ```
256
-
257
- Placements reach the renderer at the coordinates written. Nothing reflows around them, and a box that
258
- covers a region is a defect the gate reports. Under a tonality `layout: free` draws as `text-column`
259
- with the placements added, so the family's own band checks still apply: a slide of one small box fails
260
- the sparse-slide check and OF-109, and OF-112 reports its empty band. Render a placed slide and read it.
261
-
262
- **Variants.** `variant: split-navy` on `layout: cover` swaps the decoration set and the regions it
263
- displaces, as one unit. AZURE-PRO declares `split-navy` and `minimal` for `cover`, and `rule` for
264
- `section`. An unknown variant stops the compile with the declared list. Under a tonality the family
265
- name already chooses the variant (`cover-figures`, `section-rule`, `closing-ask`).
266
-
267
- ## 8. Data files and placeholders
268
-
269
- When the same number appears on several slides, keep it in one file. `data: numbers.json` (one path, or
270
- a comma-separated list, relative to the source) activates `scripts/office_data.py`: it computes derived
271
- values, runs the declared checks and writes the formatted numbers into the Markdown before compiling.
272
-
273
- ```json
274
- {
275
- "values": {"revenue": 640, "op_income": 48, "op_margin": "=op_income / revenue * 100"},
276
- "tables": {
277
- "quarterly": {"csv": "quarterly.csv", "derive": {"이익률": "=영업이익 / 매출 * 100"}, "format": {"이익률": ".1f"}}
278
- },
279
- "checks": ["quarterly.매출['26년 3Q'] == revenue", "quarterly.영업이익['26년 3Q'] == op_income"]
280
- }
281
198
  ```
282
199
 
283
- A CSV file alone becomes a table named after its stem (first row headers, first column row keys).
284
- Expressions start with `=` in `values` and `derive`; `checks` are plain expressions. Allowed: numbers,
285
- `+ - * / ** %`, comparisons, `and`/`or`/`not`, value names, `table.column` (total row excluded),
286
- `table.column['row key']`, `table['column name']`, and the functions `sum avg min max abs round len
287
- growth(new, old) share(part, whole) approx(a, b, tol)`. `==` compares with a floating-point tolerance.
200
+ `type` is one of `column` (default), `bar`, `line`, `area`, `stacked`, `pie`,
201
+ `doughnut`. The first column holds the categories, every further column is a series;
202
+ pie and doughnut use the first series. The chart takes the table's place on any
203
+ layout that accepts a table and fills the slide down to its caption, which the
204
+ engine numbers "도 N.".
205
+
206
+ One series carries the accent, and it is the same kind of series on every chart of the deck: the
207
+ latest period when every series names one ("2026" over "2025", "Q3" over "Q2"), else the measured
208
+ series beside a plan, target, budget or prior period ("실적" over "계획"), else the last column. Put
209
+ the proposed or current series last when the names say neither. Data labels keep the decimals the
210
+ table writes, so a chart beside a table that says 18.0 says 18.0 too.
211
+
212
+ A figure exported as a picture (a plot or a diagram drawn on white) stands as a white card on a dark
213
+ tonality. Give it a dark variant beside it, named like the file with `.dark` before the extension
214
+ (`assets/flow.png` and `assets/flow.dark.png`): a dark tonality draws the variant, a light one the
215
+ original. Better still, give a plot its numbers as a `::: chart` block, which every tonality draws in
216
+ its own colours. The gate fails a mostly-white picture on a dark ground (OF-117).
217
+
218
+ Headline numbers become KPI cards on the Azure templates (two to four short values), and the
219
+ `kpi-row` family under a tonality: one data row of up to six short values, a second row with each
220
+ figure's basis or comparison, a caption with period and source, the takeaways, and the source line.
221
+ Under a side title, or when the cards would stop high on the page, the values run down the body as
222
+ rows (value, label, basis) with the takeaways beside them.
288
223
 
289
- | Placeholder | Result |
290
- |---|---|
291
- | `{{ revenue }}` | `640`; integers get thousands separators |
292
- | `{{ op_margin \| .1f }}` | `7.5`; any Python format spec after the pipe |
293
- | `{{ growth(revenue, 548) \| +.1f }}%` | `+16.8%` |
294
- | `{{ table:quarterly }}` | the whole table as a pipe table, derived columns and total row included |
295
- | `{{ table:quarterly \| columns=매출,영업이익 no-total }}` | chart-ready form inside a `::: chart` block |
296
-
297
- A failed check stops the compile before any slide is drawn (`Data error: data check failed: ... (left 48,
298
- right 49)`), which is the point: the deck cannot ship a total that disagrees with its parts. Inspect
299
- without compiling:
300
-
301
- ```sh
302
- python3 -B "$SKILL_ROOT/scripts/office_data.py" check deck.md # JSON report; exit 1 on a failed check or unknown name
303
- python3 -B "$SKILL_ROOT/scripts/office_data.py" resolve deck.md # the Markdown with every placeholder filled
304
- ```
224
+ ```markdown
225
+ | 매출 | 영업이익 | 영업이익률 | 영업현금흐름 | 수주 잔고 |
226
+ |---|---|---|---|---|
227
+ | 1,184억 원 | 110억 원 | 9.3% | 96억 원 | 2,310억 원 |
228
+ | 계획 대비 +3.9% | 계획 대비 +10.0% | 계획 대비 +0.5%p | 전년 동기 81억 원 | 전분기 대비 +4% |
305
229
 
306
- ## 9. Compile, gate, look
230
+ > 2026년 3분기(7-9월), 내부 결산 자료 (예시)
307
231
 
308
- ```sh
309
- node "$SKILL_ROOT/scripts/compile-deck.js" deck.md --pptx out.pptx --embed-fonts # tonality from the frontmatter
310
- node "$SKILL_ROOT/scripts/compile-deck.js" deck.md --tonality night --pptx out-night.pptx # another tonality, same source
311
- node "$SKILL_ROOT/scripts/compile-deck.js" deck.md --template AZURE-PRO --pptx out.pptx --embed-fonts # a legacy template
312
- node "$SKILL_ROOT/scripts/compile-deck.js" deck.md --ast out.json # the intermediate AST
313
- python3 "$SKILL_ROOT/scripts/qa_deck.py" out.pptx # exit 0 required; add --sibling out-night.pptx for OF-116
314
- python3 "$SKILL_ROOT/scripts/render_pages.py" out.pptx --out-dir renders --pages 5
232
+ - 매출과 영업이익이 모두 계획을 넘었다
233
+ - 영업현금흐름은 영업이익의 87% 수준이다
234
+ - 수주 잔고는 매출 약 2분기분이다
235
+ - 출처: 예시 기업 내부 결산 자료(2026년 3분기), 2026년 연간 사업 계획
315
236
  ```
316
237
 
317
- `--embed-fonts` embeds the bundled Pretendard (or A2Z) files so the deck renders on a machine without
318
- them. The compile log prints the tonality line, then `note:` lines (a family the pack lacks, a title
319
- that moved), `variety:` lines and `fill:` lines; keep them in the build log. `render_pages.py` converts
320
- through LibreOffice into `renders/page-01.png` and so on, and reports `SKIP` with the reason when
321
- `soffice` is missing, in which case say that the visual pass did not happen. A clean gate means no known
322
- defect. It cannot tell that a slide reads badly, so open the pages. A learned brand template comes from
323
- `python3 "$SKILL_ROOT/scripts/learn_template.py" corporate.pptx --name MY-BRAND`, written to
324
- `.lit-pptx/templates` and referenced only fonts, colours and assets present in the source deck.
238
+ A slide is dense when every block on it says something the reader needs: the figure, what it is
239
+ compared with, the period, where it comes from, and what follows. Write that, and the compact step
240
+ (density 10, every pack's default) sets it at 13 pt in 24 pt margins with the source strip at the
241
+ foot. Never repeat a line to fill a slide; merge thin slides instead.
325
242
 
326
- ## 10. Failures seen most often
243
+ `notice:` in the frontmatter prints one tag at the bottom left of every slide —
244
+ use it whenever values are examples: `notice: 예시 데이터 — 실제 수치로 바꿔 주세요`.
327
245
 
328
- | Symptom | Cause | Fix |
329
- |---|---|---|
330
- | `Slide chunk must start with a 'layout:' directive` | a stray `---` inside a slide, or a chunk holding only the layout line | remove the rule; give the slide a title line |
331
- | `Frontmatter must declare a 'template' or a 'tonality' field` | the key sits after the first slide, or is missing | put it in the opening block |
332
- | `--template or --tonality ... is required` | a legacy deck compiled without the flag | add `--template <NAME>` |
333
- | `layout "x" is neither a layout family nor a legacy layout` | typo or wrong pack | read the printed family list |
334
- | `the full-chart family does not take "side-rail"` | a `title:` pin the family refuses | pick from the printed allowed set |
335
- | `":::: columns" declares 2 track(s) ... but holds 1` | track count differs from `col` blocks | match them |
336
- | a body line vanished on a legacy slide with `columns` | the line sat outside the columns | move it into a `::: col` |
337
- | `block type "title" is not allowed` on `layout: free` | a legacy `free` slide takes notes and placements only | set the title as a `::: box` |
338
- | OF-118 on a box | bold label without a colon inside a box | type `**결론:**` |
339
- | `sparse_slide` and OF-109 on a free slide | one small box on an otherwise empty page | choose a fuller family |
340
- | the same table size on every slide | one family repeated | vary the job: chart, matrix, comparison, timeline |
341
- | a title written as a verdict | claim in the title | move the claim into the first bullet (OF-114) |
246
+ Measured scientific data (instrument output, fitted curves, uncertainty) is still
247
+ drawn by the scientific visualization skill: hand it the deck's visual system
248
+ with `compile-deck.js deck.md --export-viz-context ctx.json` (the tonality comes from the frontmatter) and place the
249
+ result as a captioned figure. Register the font *file* from `ctx.json` rather than the
250
+ family name — a Korean family resolved by name alone renders as boxes.