@taloswork/ose-shared 0.1.11 → 0.1.12

package/skills/document/theme-system.md

@@ -1,102 +1,110 @@
 # Theme V2 — composable deck design system
 
-Theme V2 separates five decisions that the old pack model coupled together:
+This file is the single source for **which entries take Theme V2, what it adds, and
+the spec fields that control it**. Theme V2 separates five decisions:
 
 1. **Theme** (`style`) — palette, typography, background and family identity.
-2. **Component profile** — cards, metrics, pricing, quotes, tables, badges and data UI.
-3. **Media style** — product/device, editorial photo, collage, illustration or cinematic treatment.
-4. **Art direction** — large color fields, pattern language, decorative geometry and page atmosphere.
-5. **Layout + recipe** — content geometry per slide and narrative order per deck.
-
-`theme-system.json` binds every existing catalog id to one component profile, one
-default media style and one art direction. A deck can override only the media treatment;
-art direction remains part of the Theme identity and layout selection stays separate.
-
-Component profiles: `clean`, `glass`, `editorial`, `poster`, `organic`, `luxury`.
-They alter radius, border weight, depth, surface behavior, label typography and emphasis
-patterns across the full semantic component contract (cards, KPI, proof, pricing, quote,
-table, chart, workflow, funding and CTA).
-
-Media styles: `clean-product`, `device-stage`, `editorial-photo`, `cutout-collage`,
-`illustrated`, `cinematic`, `spatial-3d`. They can be changed independently for a deck or
-a bespoke page while the Theme's color, type, background and component grammar remain.
-
-Art directions: `geometric-pop`, `gradient-mesh`, `editorial-cut`, `collage-paper`,
-`illustrated-doodle`, `cinematic-depth`, `luxury-ornament`, `technical-grid`,
-`maximalist-blocks`. The renderer injects a decoration-only backdrop canvas for these
-profiles. Each uses the selected family's full `--c1`…`--c4` ramp rather than only its
-accent, so Theme differences include composition and motif—not merely hue.
+2. **Component profile** — `clean` · `glass` · `editorial` · `poster` · `organic` ·
+   `luxury`: radius, border weight, depth, surfaces, labels and emphasis across the
+   semantic components (cards, KPI, proof, pricing, quote, table, chart, workflow,
+   funding, CTA).
+3. **Media style** — `clean-product` · `device-stage` · `editorial-photo` ·
+   `cutout-collage` · `illustrated` · `cinematic` · `spatial-3d`. The only layer a deck
+   may override (`mediaStyle` / `--media-style`); colour, type, background and component
+   grammar stay the Theme's.
+4. **Art direction** — `geometric-pop` · `gradient-mesh` · `editorial-cut` ·
+   `collage-paper` · `illustrated-doodle` · `cinematic-depth` · `luxury-ornament` ·
+   `technical-grid` · `maximalist-blocks`: a decoration-only backdrop canvas that uses
+   the family's whole `--c1`…`--c4` ramp. Part of the Theme identity — not overridable.
+5. **Layout + recipe** — content geometry per slide (layouts/README.md) and narrative
+   order per deck (`recipes/`). Never chosen by the Theme.
+
+`theme-system.json` binds every catalog id to one component profile, one default media
+style and one art direction.
+
+## Which entries take it — classic-v1 vs V2
+
+- Entries in a `catalog.json` collection with `renderMode:"classic-v1"` (today
+  `original-13`, frozen at commit `7306d8e5`; its `entryIds` are the list) render V1: omit `themeVersion`, `mediaStyle`, `decorRhythm`, per-slide
+  `scene`/`decorDensity` and every layout in `layouts/profiles.json.themeV2Layouts`;
+  render with `--style <id>` and never `--theme-v2`. `deck-build` (exit 64) and
+  `html2pptx` reject the attempt. They keep current bug/font/contrast fixes; samples and
+  fidelity baselines are V1.
+- Every other newly authored deck sets `"themeVersion":2` and renders with
+  `--style <id> --theme-v2 [--media-style <id>]`. `--theme-v2` needs a catalog id
+  (not an explicit style directory or a user style); `--media-style` needs `--theme-v2`.
+- The ten `themeV2Layouts` use the semantic component contract and require
+  `themeVersion:2`; every older layout works in both. `themeVersion:2` never changes
+  which layout a slide uses.
+- Under `--theme-v2` html2pptx does not auto-pick a shared backdrop variant (the art
+  direction owns the backdrop); an explicit `--backdrop` still wins.
 
 ## Page scenes and deck rhythm
 
-`deck-build` maps each slide intent to one visual scene: `hero`, `content`, `data`,
-`media` or `closing`. The scene controls which art-direction motifs remain visible;
-`decorDensity` (`low`, `medium`, `high`) controls their combined intensity. With the
-default `decorRhythm:"auto"`, adjacent high-intensity pages are softened, long medium
-runs receive a low beat, and repeated scenes cycle deterministic motif variants.
-
-Authors normally provide only `intent`. Use a per-slide `scene` or `decorDensity` only
-for a deliberate override. Set top-level `decorRhythm:"steady"` to keep the intent
-profile's density unchanged. These fields require `themeVersion:2` and never select or
-rewrite a layout.
+`deck-build` maps each slide's `intent` to one scene — `hero`, `content`, `data`,
+`media` or `closing` — which decides the art-direction motifs shown; `decorDensity`
+(`low`/`medium`/`high`) sets their intensity. With the default `decorRhythm:"auto"`,
+adjacent high-intensity pages are softened, long medium runs get a low beat and
+repeated scenes cycle motif variants. Normally give only `intent`; a per-slide `scene`
+or `decorDensity` is a deliberate override, and top-level `decorRhythm:"steady"` keeps
+each intent's density. These fields require `themeVersion:2` and never pick a layout.
 
 ```json
 {
-  "style": "cool",
+  "style": "neon-cyber",
   "scenario": "发布会",
   "themeVersion": 2,
-  "decorRhythm": "auto",
   "mediaStyle": "device-stage",
   "layoutPack": "none",
   "slides": [
-    {"intent":"problem", "layout":"pitch-problem", "slots":{}},
-    {"intent":"product-demo", "layout":"product-device", "slots":{}}
+    {"intent": "problem", "layout": "pitch-problem", "slots": {
+      "eyebrow": "THE PROBLEM", "title": "对账每月吃掉财务团队一周", "stat": "38h", "stat_label": "每月人工对账", "stat_note": "50 家受访客户中位数",
+      "point1_title": "数据分散", "point1_body": "银行、ERP、表格三处来源",
+      "point2_title": "规则靠人记", "point2_body": "例外处理无沉淀",
+      "point3_title": "出错难追溯", "point3_body": "审计时逐笔翻查",
+      "footer": "", "pageno": ""}},
+    {"intent": "product-demo", "layout": "product-device", "slots": {
+      "eyebrow": "PRODUCT", "title": "一键完成三方对账", "body": "接入银行流水与 ERP，规则自动匹配，例外进入待办",
+      "feature1": "自动匹配 95% 流水", "feature2": "例外一键分派", "feature3": "全程留痕可审计",
+      "media_label": "", "screen_title": "对账工作台", "screen_note": "",
+      "footer": "", "pageno": ""}}
   ]
 }
 ```
 
-`deck-build` emits the matching render command:
+Every slot is filled (`""` blanks one on purpose): an omitted slot renders the layout's
+demo copy and `deck-build` warns. The build result's `next` is the matching render
+command:
 
 ```sh
-html2pptx deck.html out.pptx --style cool --theme-v2 --media-style device-stage
+html2pptx deck.html out.pptx --style neon-cyber --theme-v2 --media-style device-stage
 ```
 
+## Layout selection and packs
+
+Match content to layouts through `layouts/profiles.json` (intent → candidates, density,
+item cap, media requirement) — `deck-plan` does it for you. `deck-build` warns when an
+explicit layout is outside the intent's candidates and errors on an unknown intent.
+
+`layoutPack` is independent of the Theme. `kind:"pack"` entries (`packs/README.md`)
+ship same-name signature layouts: a spec that omits `layoutPack` keeps the legacy
+behaviour (a pack style implicitly uses them); new specs state `layoutPack:"<pack>"`
+or `"none"` (shared layouts only).
+
+`recipes/` hold pitch narratives as roles, not fixed pages, so one story renders in
+any Theme.
+
 ## Compatibility
 
-- Existing `{style:"cool"}` specs and `html2pptx --style cool` calls remain V1 and
-  render exactly as before.
-- `catalog.json` collection `original-13` freezes the initial roster at commit
-  `7306d8e5` with `renderMode:"classic-v1"`. Those entries keep current bug/font/contrast
-  fixes but reject `themeVersion:2`, `--theme-v2`, media overrides, scene controls and
-  Theme V2-only layouts. Their samples and fidelity cover baselines are rendered in V1.
-- `themeVersion:2` adds component, media and art-direction layers; it does not change
-  the selected layout.
-- Existing `{style:"press-room"}` keeps the legacy implicit same-name layout pack.
-  New specs should state `layoutPack:"press-room"` or `layoutPack:"none"` explicitly.
-- `--theme <theme.json>` is a different legacy document recolor path and is not Theme V2.
-
-## Content-first layout selection
-
-Use `layouts/profiles.json`. Match `intent`, then check density, item capacity and media
-requirement before selecting a candidate. `deck-build` warns when a slide's explicit
-layout is outside the candidate list and errors on unknown intents. It never forces a
-layout merely because a visual Theme was selected.
-
-The ten layouts listed in `themeV2Layouts` use the new semantic component contract and
-therefore require `themeVersion:2`; `deck-build` rejects a V1 attempt before writing HTML.
-All pre-existing layouts remain valid in both V1 and V2.
-
-Pitch recipes live in `recipes/`. They describe narrative roles, not fixed visual pages,
-so the same fundraising story can render in a clean consulting Theme, neon product Theme
-or editorial Theme without changing its content contract.
-
-## Coverage and provenance
-
-The 18 pitch intents cover problem, solution, product, market, competition, business
-model, pricing, traction, go-to-market, economics, financials, proof, team, ask and close.
-The visual archetypes are clean-room abstractions informed by broad category patterns,
-including the SlidesCarnival pitch-deck index: geometric color fields, gradient/3D depth,
-editorial cropping, paper collage, illustration/doodles, ornament, grids and maximalist
-blocks. Do not copy third-party template assets or page geometry. SlidesCarnival templates
-are CC BY 4.0 and embedded photos may carry separate licenses; importing an actual template
-requires preserving attribution and asset credits.
+- `{style:"<id>"}` without `themeVersion`, and `html2pptx --style <id>` without
+  `--theme-v2`, stay V1 and render exactly as before.
+- `--theme <theme.json>` is the legacy document-recolor path, not Theme V2, and it does
+  not repaint a `--style` deck (the skin's tokens win).
+
+## Provenance
+
+The 18 pitch intents (problem … ask, close) and the visual archetypes are clean-room
+abstractions of broad category patterns (incl. the SlidesCarnival index). Do not copy
+third-party template assets or page geometry; SlidesCarnival templates are CC BY 4.0
+and their photos may carry separate licenses — importing one requires keeping
+attribution and asset credits.

package/skills/document/themes/README.md

@@ -9,14 +9,14 @@
 
 | 主题 | 配对家族 | 基调 | 适用场景 |
 |---|---|---|---|
-| **cool-tech**（默认） | `cool` | 深海军蓝 + 蓝青辉光(深色 deck) | 科技/发布/pitch/keynote —— 默认酷炫 |
+| **cool-tech** | `cool` | 深海军蓝 + 蓝青辉光(深色 deck) | 科技/发布/pitch/keynote |
 | **apple-keynote** | `apple` | 纯黑 + 单色近白(深色 deck) | 产品发布、keynote、极简演示:超大字、大留白、无彩色 |
 | **mckinsey-consulting** | `mckinsey` | 白底 + 深藏青 + 克制亮蓝 | 咨询/战略汇报、评审、董事会;**报告/docx 默认** |
 | **anthropic-clay** | `anthropic` | 奶油底 + 赤陶珊瑚(暖) | AI/产品、温暖人文品牌、研究分享:衬线标题、有深度 |
 | **black-gold** | `black-gold` | 纯黑 + 金辉光 + 衬线金字 | 金融/年报/路演/奢侈品/高端商务 |
 | **hand-drawn** | `hand-drawn` | 纸感 + 手绘描边 + 马克笔色 | 创意/头脑风暴/教学/工作坊 |
 | **mono** | `mono` | 纯白 + 黑灰 + 细线 + 大留白 | 极简/高端/设计;**clean/light 默认** |
-| **warm-editorial** | `warm` | 奶油 + 陶土橙 + 衬线 | 品牌/咨询/报告暖调 |
+| **warm-editorial** | —(无同名 deck 风格) | 奶油 + 陶土橙 + 衬线 | 品牌/咨询/报告暖调 |
 | **ivory-gold** | `ivory-gold` | 奶油底 + 青铜金 Anton 粗体大写标题 + 黑色反色区块 | 奢华极简/品牌手册/路演/高端零售 |
 | **cinereel** | `cinereel` | 黑底/照片底 + 白色 Anton 粗体大写(无色相)+ 常驻胶片取景框 | 影视/创意作品集/音乐传媒行业/幕后花絮 |
 | **magazine-ink** | `magazine-ink` | 瓷白底 + 靛蓝 Noto Serif SC 衬线大标题 + 无阴影无卡片盒 | 人文分享/行业观察/商业发布/杂志感演讲 |
@@ -26,9 +26,11 @@
 白纸 + 品牌色标题。具名"风格"主题只设 `fonts.heading`(Latin 标题生效、CJK 自动回退,
 正文留空走引擎栈保 CJK)。
 
-**用户自建主题放 `themes/custom/`**(资源更新永不触碰;选型时优先查它),文件名
-kebab-case、带 `bestFor`。确认过的偏好写入 agent memory,下次直接用(见 rewrite.md
-"Picking a theme")。
+**用户自建主题保存到 `$TALOS_DOC_STYLES_DIR/themes/<名>.json`**(kebab-case、带
+`bestFor`),之后用 `--theme <名>` 按名字套用。这是用户自己的风格目录,跨会话保留、所有
+专家共用;**不要写进 skill 目录**——它是带完整性校验的安装包,内容一变就会被隔离重装,
+写进去的文件随之丢失。确认过的偏好写入 agent memory,下次直接用(见 rewrite.md
+"Themes" 的 Choosing with the user)。
 
 > 更多纯配色变体(arctic-frost / ocean-depths / golden-hour / chinese-ink 等 17 套)已
 > **退役到 `apps/admin/data/deck-template-backup/retired-themes/`** —— 它们只是同布局换色,

package/skills/document/vision.md

@@ -6,8 +6,9 @@ loses.
 
 ## Steps
 
-1. `bin/pdf-render file.pdf <pages>` — `<pages>` is a single page (`4`) or a
-   range (`2-6`). It writes PNGs and prints their paths.
+1. `bin/pdf-render.cjs file.pdf <pages> [scale]` — `<pages>` is `4`, `2-6`, `3,7-8`
+   or `all`; PNGs land beside the PDF (`<stem>_p<N>.png`) and their paths are printed.
+   Keep the default scale `2` for formulas and fine print; `1` is enough for layout.
 2. Look at each PNG. For:
    - **Formulas** → transcribe to LaTeX from the image.
    - **Tables** → read the table structure directly; report values row/column.
@@ -25,9 +26,11 @@ render that page here and read it visually instead.
 When the model has **no** image modality but the page is scanned, OCR the raster
 instead of guessing:
 
-1. `bin/pdf-render file.pdf <page>` → PNG.
-2. `bin/ocr <page.png> [lang]` → `{ text, confidence }`. Report low confidence
-   honestly. Set `$TALOS_TESSDATA` to a dir to cache/serve language data offline.
+1. `bin/pdf-render.cjs file.pdf <page>` → PNG.
+2. `bin/ocr.cjs <page.png> [lang]` → `{ text, confidence }` (`lang` default `eng`).
+   Report low confidence honestly. Chinese: `chi_sim` (or `chi_sim+eng` for mixed
+   text; `chi_tra` traditional). `eng` and `chi_sim` are bundled and work offline;
+   other languages download once into `$TALOS_TESSDATA`.
 
 Prefer vision when it is available — OCR loses layout and struggles with
 formulas. Use OCR only as the text-only fallback.

package/skills/document/xlsx.md

@@ -7,7 +7,7 @@ files.
 ## Steps
 
 1. `bin/xlsx-query file.xlsx --summary` → per-sheet shape (name, row/col counts,
-   headers). Decide which sheet + column the question is about.
+   `headerRow`, headers). Decide which sheet + column the question is about.
 2. Aggregate: `bin/xlsx-query file.xlsx --agg <sheet> <column> <op>` where `op` ∈
    `sum | avg | min | max | count | count-nonempty`. `<column>` may be a header
    label or a 1-based index.
@@ -16,31 +16,21 @@ files.
 
 ## Notes / boundaries
 
-- Non-numeric cells are ignored by `sum/avg/min/max`; `value:null` means no
-  numeric cells qualified — report that rather than guessing 0.
+- The header row is detected: the first mostly-text row (of the first ~10) whose next
+  row has numbers, so a title row above the table is skipped — check `headerRow`;
+  `--header-row N` (1-based sheet row) overrides it.
+- `--agg` leaves total rows out — a cell reading 合计 / 总计 / 小计 / Total / Subtotal /
+  Sum, or a `SUM` over the same column — and lists them in `excludedRows`;
+  `--include-totals` keeps them.
+- Numbers: numeric cells use their stored value (a cell shown as `15%` is 0.15). In
+  text cells `¥ ￥ $ € £`, commas, spaces and a trailing `元` are stripped; `15%` → 0.15,
+  `(300)` → −300. Sums/averages are rounded to 15 significant digits (no `0.1+0.2` noise).
+- Non-numeric cells are ignored by `sum/avg/min/max` and listed in `skippedCells`
+  (first 20; `skippedCellCount` is the total); `value:null` means no numeric cells
+  qualified — report that rather than guessing 0.
 - A missing/misnamed column returns `value:null` with `colIdx:-1`; check headers
   first via `--summary`.
-- Currency/percent strings (`$1,200`, `15%`) are coerced to numbers.
 - For pivots or multi-column math beyond these ops, read rows with `--sample`
   and compute in a short script, or ask for the specific cut.
-
-## Writing formulas (the repair loop — mandatory)
-
-When you GENERATE or EDIT a spreadsheet, use live formulas (`"=SUM(A2:A9)"`),
-never precomputed values — the file must recalculate when the user edits data.
-Then close the loop:
-
-1. `bin/xlsx-recalc.cjs out.xlsx out.xlsx` — evaluates every formula and caches
-   results (openpyxl-class writers leave them blank).
-2. The output's `errors` array must be **empty**. Any `#DIV/0!`, `#REF!`, `#N/A`
-   → fix the formula (guard divisors with IF, correct the range) and re-run
-   recalc. **Never deliver a spreadsheet with formula errors**, and never
-   "fix" one by replacing the formula with a hardcoded value.
-
-## Known engine limits (HyperFormula vs LibreOffice recalc)
-
-`xlsx-recalc` covers ~400 functions — all common math/stat/text/date/lookup.
-Known gaps vs a full Excel/LibreOffice engine: some exotic financial functions
-and dynamic-array spilling. If recalc reports `#NAME?` on a function you know is
-valid Excel, that is an engine limit — say so and compute that cell's value via
-`xlsx-query`/script instead of guessing.
+- **Generating or editing** a workbook (formulas, the `xlsx-recalc` repair loop) →
+  rewrite.md "Formulas".