slidemark 0.1.0__tar.gz

slidemark-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+# GitHub Actions minutes are limited on this private repo. The daily routine already runs ruff + the full
+# pytest suite locally before every push, so CI runs once a day on the latest main (and on demand),
+# not on every push. Re-add `push:` only if the repo becomes public or gets more minutes.
+on:
+  schedule:
+    - cron: "0 23 * * *" # 08:00 JST, after the 02:45 JST routine run
+  workflow_dispatch:
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv venv --python ${{ matrix.python }} .venv
+      - run: uv pip install -e ".[dev,html]" --python .venv
+      - run: .venv/bin/playwright install --with-deps chromium
+      - run: .venv/bin/ruff check .
+      - run: .venv/bin/ruff format --check .
+      - run: .venv/bin/pytest -q --cov=slidemark --cov-report=term:skip-covered

slidemark-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: publish
+# Publishes the package to PyPI through Trusted Publishing (OpenID Connect): no API token is stored.
+# PyPI side: project `slidemark`, owner `LeDat98`, repository `SlideMark`, workflow `publish.yml`,
+# environment `pypi`. GitHub side: Settings > Environments > `pypi` (add the owner as a required reviewer
+# so a release is approved by hand). Runs on a published GitHub release or on demand; the version comes
+# from `pyproject.toml`, so bump it and tag `vX.Y.Z` first.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - run: uv venv .venv && uv pip install --python .venv dist/*.whl
+      - run: .venv/bin/slidemark version
+      - run: printf '# Hello\n- one\n- two\n' | .venv/bin/slidemark build - -o /tmp/smoke.pptx
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/slidemark
+    permissions:
+      id-token: write # the OIDC token PyPI trusts
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

slidemark-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+/out/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+.claude/worktrees/
+.hypothesis/

slidemark-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes. Versions follow semver once 0.1.0 is published.
+
+## 0.1.0 (2026-10-07)
+
+### Design freedom
+- DL3d lane A (foreign-deck round trip): span attributes `[420億円]{size=28 bold=true color=primary}` (exact pt, mixed sizes / colours in one line: paragraphs, list items, `@rows`, table cells, headings, KPI values; the importer writes them back, `importer/runs.py`), per-card stripe colours `box.stripe=a,b,c` / `item.stripe` / `kpi.stripe` + `.stripe_h` / `.stripe.side` / `{stripe=teal}`, number headings `@4 num=text` / `## 01 {.num}` / `box.num.color=a,b,c`, number tiles `@kpi tile`, `cover.bottom.bar`, readable ink on a box with its own `{fill=}`, `<br>` in table cells without a warning; `examples/25-roundtrip-forms.md`.
+- DL2 lane G: `kpi.band=<color>` (`kpi.band.color`, `kpi.band.size`: a header band behind the label of every `.kpi` card) and `kpi.unit.size=22` (`kpi.unit.color`: the trailing unit of a KPI value in its own run size, `Run.size`); `sizes: kpi=NN` now sets the KPI number size (it was a silent no-op) and counts as an explicit size; KPI value width estimates measure the unit at its own size; t2 / t3 ports re-done with every form that exists.
+- DL3b part 1 (composition vocabulary): `@timeline` (h / v, marks), `@vs` (verdict, winner), `@matrix` (axis labels + arrows), `@funnel`, `@pyramid`, `@cycle`, `@agenda`, `@statement`, each one `@word` line with secondary keys (`dir=` `marks=` `x=` `y=` `align=` `valign=` + `size=` `fill=` `gap=`) and `<form>.*` tokens; native custom-geometry stages and arc arrows; importer round trip; `examples/23-vocabulary.md`.
+- DL2 lane F: `@items` / `box.items=cards` (item cards), `@num` (numbered heading badges), `heading.rule`, `title.rule2`, `@rows plain` with `rows.glyph` / `rows.stripe`, cover `bar@edge` / `rule_w` / `rule_pos` / `stripes`, `render.chevron_shape` as a list, `table.num_pad`, `kpi.fill` / `kpi.line`; lint reads a KPI label against a tall stripe.
+- No fixed look: every color, font, size, spacing, band, card style and layout constant is a token
+  (`slidemark tokens`); built-in themes are YAML presets (`src/slidemark/presets/`); `theme: none` is a neutral canvas.
+- Header token lines `colors:` `fonts:` `sizes:` `style:` (new classes such as `hero.fill=` too), validated with
+  did-you-mean hints; shorthands `border="0.75pt solid #B08D57"`, `fill=none`, `shadow=none`.
+- ` ```css ` fences (deck or slide): 34 CSS properties mapped to native PowerPoint (gradients, shadows, per-side
+  borders, letter-spacing, text-transform, rotation, grid templates, table cell styles), selector matching.
+- `@html` slides and `slidemark build deck.html`: Chromium layout converted to native shapes (gradients, shadows,
+  rotation, ellipses, pills, simple inline SVG); theme tokens as CSS custom properties.
+- `@free` slides: explicit `{x y w h}` positions, no automatic arrangement.
+- The design source (tokens, CSS, HTML) survives `slidemark import` (customXml part).
+
+### Syntax
+- Headings as structure (`#` slide, `##` box), one `@` grid line (`@3`, `@2x2`, `@1:2`, `@aab/aac`), `@end`.
+- Components: `.kpi` boxes, callouts `> [!note|tip|warn|caution]`, badges `[x]{.badge}`, connectors `@ a>b a-b`,
+  `flow` arrows, `chevron` steps.
+- Charts as CSV fences (10 kinds) with options `legend labels fmt min max colors axis`; tables with merges and
+  options `widths align header hcol .zebra`; CSV edge cases (quotes, `1,240`, `12%`, full-width digits, `▲`).
+- SVG images (`![x](a.svg)`, ` ```svg `): native Office SVG with a PNG fallback, sanitized.
+- Video/audio: `![alt](x.mp4)` / `.mp3` embed native media (poster, `autoplay`, `loop`).
+- ` ```html {render=native} `: any HTML/CSS laid out in Chromium and converted to native shapes.
+- ` ```math ` → native OMML equations; ` ```mermaid ` flowcharts → native shapes + connectors; HTML subset input.
+- Lenient input: Marp/Slidev/Markdown variants accepted with warnings and did-you-mean hints.
+
+### Layout and rendering
+- Auto arrangement, 12-column tracks, full-width rows below a grid, sparse-slide growth and vertical balance.
+- Consulting-grade layout: top-anchored body, content-sized cards/chevrons/trees/table columns, distinct chart
+  palettes with contrast-aware data labels.
+- Bounded layout search (≤ 6 candidates scored like the design critic; rule choice wins ties).
+- Real font metrics, autofit with `min_font_size`, CJK measurement and kinsoku line breaking.
+- Themes `default`, `midnight`, `jp-business`; user `.pptx`/`.potx`/`.yaml` themes with native footer and
+  slide-number placeholders.
+
+### Tooling
+- CLI: `build`, `check` (`--format json`, layout linter), `preview`, `docs [topic]`, `schema`, `skill install`,
+  JSON and HTML deck input.
+- Linter: overflow, off-slide, overlap, contrast, tiny-text, alt, connector-crosses, missing-end.
+- Skill: `SKILL.md` (≤ 1,500 tokens) + 5 reference pages (≤ 800 tokens each).
+- Bench: token corpus + gate, layout-inference metric, agent eval harness.
+- `slidemark review` (design critique + score), `slidemark check --fix` (mechanical source repairs).
+- `.pptx` import round trip: 98% of 111 decks lossless (OMML → LaTeX, transitions, build, sections, code
+  language); foreign python-pptx decks import at 0.975 fidelity.
+- `python -m slidemark.xsd deck.pptx`: ECMA-376 schema validation (markup compatibility resolved to the
+  fallback); `bench/xsd_fuzz.py` validates fuzzed decks. CI on Python 3.10–3.12 with a coverage report.
+- `build` prints one fit line per slide (form used, text size asked->reached, free space, attributes that took or
+  were ignored; `--quiet` / `fit: off`) and warns `attr-ignored` for attributes and `style:` tokens the layout does
+  not honour, with the form that works. `{.kpi h= y=}` on a lone KPI row pins the whole row.

slidemark-0.1.0/CLAUDE.md

@@ -0,0 +1,55 @@
+# SlideMark: notes for coding sessions
+
+Python library: token-efficient Markdown/HTML → native, editable .pptx for AI agents.
+Design: `docs/PROPOSAL.md`. Plan: `docs/PLAN.md`. Syntax: `docs/SYNTAX.md`.
+
+## Before you start
+1. Read `docs/LESSONS.md` (known bugs, pitfalls, fixes). It is short on purpose.
+2. Check today's tasks in `docs/PLAN.md`.
+3. Read `docs/AGENT_COST.md`: what to optimize (model calls first, then output tokens, then input).
+
+## Setup and commands
+```bash
+uv venv .venv && uv pip install -e ".[dev,html]" --python .venv   # html = Playwright; Chromium is pre-installed in the cloud env
+.venv/bin/pytest -q                 # all tests
+.venv/bin/ruff check . && .venv/bin/ruff format --check .
+.venv/bin/python bench/count_tokens.py --record   # token metrics, append to bench/history.jsonl
+.venv/bin/python scripts/gallery.py               # rebuild examples -> docs/gallery PNGs + README section
+```
+Previews use the repo's `src/slidemark/fonts/fonts.conf` (Meiryo / Yu Gothic -> IPAPGothic, Arial / Inter -> Liberation
+Sans, Georgia -> Liberation Serif) so renders and goldens are the same everywhere: `docs/RENDERING.md`. Optional:
+`apt-get install fonts-noto-cjk` (~60 MB) gives a real bold CJK face, but goldens are made without it.
+
+## Architecture (contract: `src/slidemark/ir.py`)
+`parser/` Markdown → `Deck` · `layout/` `Slide` → `list[Placed]` (absolute EMU) · `render/` → .pptx ·
+`theme.py` design tokens · `units.py` lengths. The renderer never decides positions; layout never touches pptx.
+Changing `ir.py` affects every module: keep changes additive and update all users in the same commit.
+
+## Definition of Done (every feature)
+docs entry with shortest example → parser test → fuzz-safe (no crash, diagnostic instead) → render test
+(reopen the .pptx and assert) → opens in LibreOffice → golden/gallery image looks right → lint rule if it can
+break the visual → bench has no token regression. Mark progress in `docs/FEATURES.md`.
+
+## Workflow
+- **Language: everything in the repo is English** (code, comments, docs, commit messages, logs) **except
+  `README.md`, which is Vietnamese.** `scripts/gallery.py` must keep the README text Vietnamese.
+  Slide *content* in `examples/` and `bench/corpus/` may be Japanese/Vietnamese on purpose (test data).
+- Push straight to `main` (allowed by the owner). No pull requests needed.
+- GitHub Actions minutes are limited (private repo): CI runs once a day (08:00 JST) and on demand, not on push.
+  Always run ruff + the full pytest suite locally before pushing; push once per wave, not per commit.
+- Runs are led by an Opus orchestrator, last ≥ 2 hours, and use at most 2 Sonnet subagents at a time
+  (lane A front, lane B back), in waves; see "Run routine" in `docs/PLAN.md`.
+
+## Rules
+- **Design freedom first (`docs/DESIGN_FREEDOM.md`).** Never hard-code a visual decision: colors, fonts, sizes,
+  spacing, bands, card looks and layout constants are tokens an agent can override from the deck (tokens, CSS or
+  HTML). Built-in themes are YAML presets in the public token schema, with no theme-specific code paths.
+- Token cost is the main product metric, and it means the cost of the whole agent run to an accepted deck
+  (`docs/AGENT_COST.md`): model calls first, then output tokens, then input. SKILL.md must be all an agent
+  reads. New syntax must be the shortest unambiguous form that adds no lookup and no decision; measure it.
+- Never raise on bad user input: append a `Diagnostic` with a one-line, actionable `hint`.
+- Dense Japanese business slides (many boxes, 10–12pt text, tables, arrows, footnotes) are a first-class
+  target. Always test CJK text (`<a:ea>` font, full-width width ≈ 1em).
+- When you hit a bug, pitfall or non-obvious fix, add one line to `docs/LESSONS.md`.
+- When you verify a usage pattern that saves agents tokens or retries, add it to `docs/AGENT_TIPS.md`.
+- Every working day ends with: tests green, `scripts/gallery.py` run, README gallery updated, bench recorded.

slidemark-0.1.0/PKG-INFO

@@ -0,0 +1,384 @@
+Metadata-Version: 2.5
+Name: slidemark
+Version: 0.1.0
+Summary: Token-efficient Markdown/HTML to native, editable PowerPoint for AI agents
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: budoux>=0.7
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pygments>=2.17
+Requires-Dist: python-pptx>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pypdfium2>=4.20; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: tiktoken>=0.7; extra == 'dev'
+Provides-Extra: html
+Requires-Dist: playwright>=1.40; extra == 'html'
+Provides-Extra: preview
+Requires-Dist: pypdfium2>=4.20; extra == 'preview'
+Description-Content-Type: text/markdown
+
+# SlideMark
+
+Thư viện Python giúp AI Agent tạo file PowerPoint (.pptx) **native, chỉnh sửa được** chỉ bằng cách viết văn bản
+theo cú pháp riêng của SlideMark: ngắn gọn, tốn ít token và hỗ trợ cả slide dày đặc kiểu Nhật.
+
+> Trạng thái: đang phát triển (đã xong 7 ngày nền móng, đang leo các cấp L2 → L4). Mục tiêu từng cấp L1 → L7: [docs/TARGETS.md](docs/TARGETS.md).
+
+## Cài đặt
+
+```bash
+pip install slidemark            # thư viện + CLI `slidemark`
+pip install "slidemark[html]"    # thêm Playwright nếu dùng khối HTML (cần `playwright install chromium`)
+```
+
+Dùng nhanh: viết `deck.md` theo cú pháp bên dưới rồi chạy `slidemark build deck.md -o deck.pptx`.
+Xem trước ảnh PNG (`slidemark preview`) cần LibreOffice cài sẵn trên máy.
+
+## Ví dụ
+
+```markdown
+theme: jp-business
+lang: ja
+
+# 新規事業の検討状況と今後の方針
+> 3つの課題を解決し、2027年度の黒字化を目指す
+@aab/aac
+## 現状
+- 売上：12.4億円（前年比 +8%）
+## 課題
+- 解約率が ==2.1%== に上昇
+## 施策
+1. 導入テンプレートの整備
+※ 出所：社内CRMデータ
+```
+
+- `#` mở slide mới, mỗi `##` là một box, các box tự sắp xếp.
+- `@aab/aac` là layout lưới viết trong 1 dòng.
+- `>` dưới tiêu đề là thông điệp chính, dòng `※` là chú thích nguồn.
+
+Cú pháp đầy đủ: [docs/SYNTAX.md](docs/SYNTAX.md).
+
+## Tính năng chính
+
+- Box, lưới `@`, KPI `{.kpi}`, callout `> [!warn]`, badge `[x]{.badge}`, mũi tên nối `@ a>b`, chevron/flow.
+- 10 loại biểu đồ native từ CSV (nhãn, legend, định dạng số), bảng có gộp ô, công thức toán (OMML),
+  sơ đồ Mermaid → shape native, HTML → native (hoặc ảnh dự phòng qua Chromium).
+- Theme `default`, `midnight`, `jp-business` hoặc template `.pptx/.potx` của bạn; hiệu ứng xuất hiện, chuyển slide, section.
+- **Thiết kế tự do:** không có giao diện cố định. Theme chỉ là preset token (YAML); agent tự khai báo màu, font,
+  cỡ chữ, bo góc, gradient, bóng đổ bằng vài dòng `colors:` / `fonts:` / `sizes:` / `style:`, bằng khối ` ```css `
+  (34 thuộc tính CSS → shape gốc), hoặc viết cả slide bằng HTML (`@html`, `build deck.html`) và vẫn ra shape sửa được.
+- `slidemark check` kiểm tra tràn chữ, chồng lấn, tương phản, alt ảnh… và gợi ý cách sửa trên 1 dòng (JSON được).
+- `slidemark docs` / `skill install`: tài liệu cho agent, SKILL.md ≤ 1.500 token.
+
+```bash
+pip install -e .
+slidemark check deck.md && slidemark build deck.md -o deck.pptx
+slidemark skill install      # cài skill cho Claude Code
+```
+
+Windows: `slidemark preview` / `review --png` tự tìm LibreOffice trong `C:\Program Files\LibreOffice`; nếu cài chỗ khác,
+đặt biến môi trường `SLIDEMARK_SOFFICE` trỏ tới `soffice.exe`. Build .pptx không cần LibreOffice.
+
+## So sánh với python-pptx (cùng đề, 5 / 15 / 25 slide)
+
+Cùng một agent (Sonnet), cùng đề bài, mỗi bên chạy 1 lần, đo từ lúc nhận yêu cầu đến lúc có file .pptx đạt yêu cầu
+(2026-10-06). Chi tiết, mã nguồn hai bên đặt cạnh nhau và ảnh slide: [docs/COMPARE.md](docs/COMPARE.md).
+
+| Số slide | Lần gọi model (SlideMark / python-pptx) | Thời gian | Token output | Chi phí |
+|---|---|---|---|---|
+| 5 | 4 / 8 | 18 s / 86 s | 1,4k / 10,1k | 32% |
+| 15 | 5 / 11 | 40 s / 140 s | 6,7k / 18,2k | 40% |
+| 25 | 7 / 10 | 70 s / 198 s | 7,5k / 41,5k | 32% |
+
+### Thiết kế là quyết định của agent (2026-10-07)
+
+SlideMark hỗ trợ quyết định thiết kế chứ không thay agent quyết định. Từ wave 3, SKILL.md yêu cầu agent nêu rõ
+lựa chọn của mình cho cả deck (`colors:` `fonts:` `sizes:` `style:` `footer:`) và từng slide (dạng, một điểm
+nhấn, ghi đè vị trí/cỡ/màu khi cần); `build` cảnh báo `design-none` / `design-slide` và in dòng
+`design: colors fonts sizes style footer; 14/14 slides decided form+emphasis+values`. Không có lựa chọn nào được coi là "đúng"
+(`docs/DESIGN_REQUIRED.md`, `docs/DESIGN_FREEDOM.md`).
+
+Cùng đề 15 slide, giám khảo thiết kế chấm mù (Opus, cùng một vòng):
+
+| Deck | Điểm | Lần gọi | Thời gian | Chi phí | Token mã nguồn |
+|---|---|---|---|---|---|
+| SlideMark sau AC7 (nêu quyết định, build in bản đồ fit từng slide) | **3,5** / 3,0 (2 lần chạy) | 4 / 5 | 29 s / 39 s | 29% / 35% | 1,5k / 1,4k |
+| SlideMark wave 3 (nêu quyết định, chưa có bản đồ fit) | 3,5 | 9 | 90 s | 61% | 1,6k |
+| SlideMark wave 2 (chỉ nội dung) | 3,0 | 5 | 36 s | 34% | 1,3k |
+| python-pptx | 2,5 / 3,0 | 11 | 140 s | 100% | 5,3k |
+
+Bản đồ fit: `build` in một dòng cho mỗi slide (`slide 2: lead + 4 kpi cards 72% of body, value 48->29pt (shrunk to
+fit), free 16% below`) nên agent biết quyết định của mình có hiệu lực không mà không cần mở ảnh; thuộc tính bị bỏ qua
+báo `attr-ignored` kèm dạng đúng. Mục tiêu AC7–AC9 (≤ 5 lần gọi, chi phí và thời gian ≤ 50% python-pptx) đã đạt.
+
+Toàn bộ thiết kế mà agent python-pptx tự viết (64 quyết định) nêu lại được trong SlideMark với 43% token
+(`bench/lengthbench/t2/slidemark-ported/REPORT.md`, `docs/DESIGN_COVERAGE.md`).
+
+## Ảnh slide mẫu (cập nhật hằng ngày)
+
+<!-- gallery:start -->
+Cập nhật: 2026-10-07 · commit `2d3e402` · tạo tự động bởi `scripts/gallery.py`.
+
+### Cơ bản: tiêu đề, danh sách, box, bảng, biểu đồ
+
+Nguồn: [`examples/01-basics.md`](examples/01-basics.md)
+
+![01-basics slide 1](docs/gallery/01-basics/slide-01.png)
+![01-basics slide 2](docs/gallery/01-basics/slide-02.png)
+![01-basics slide 3](docs/gallery/01-basics/slide-03.png)
+![01-basics slide 4](docs/gallery/01-basics/slide-04.png)
+
+### Slide dày đặc kiểu Nhật (jp-business)
+
+Nguồn: [`examples/02-jp-dense.md`](examples/02-jp-dense.md)
+
+![02-jp-dense slide 1](docs/gallery/02-jp-dense/slide-01.png)
+![02-jp-dense slide 2](docs/gallery/02-jp-dense/slide-02.png)
+
+### Báo cáo tiếng Việt
+
+Nguồn: [`examples/03-vi-report.md`](examples/03-vi-report.md)
+
+![03-vi-report slide 1](docs/gallery/03-vi-report/slide-01.png)
+![03-vi-report slide 2](docs/gallery/03-vi-report/slide-02.png)
+![03-vi-report slide 3](docs/gallery/03-vi-report/slide-03.png)
+
+### Tiếng Nhật: KPI, badge, bảng kết quả, mũi tên nối
+
+Nguồn: [`examples/04-jp-kpi.md`](examples/04-jp-kpi.md)
+
+![04-jp-kpi slide 1](docs/gallery/04-jp-kpi/slide-01.png)
+![04-jp-kpi slide 2](docs/gallery/04-jp-kpi/slide-02.png)
+
+### Tiếng Nhật: quy trình chevron + bảng, luồng phê duyệt
+
+Nguồn: [`examples/05-jp-process.md`](examples/05-jp-process.md)
+
+![05-jp-process slide 1](docs/gallery/05-jp-process/slide-01.png)
+![05-jp-process slide 2](docs/gallery/05-jp-process/slide-02.png)
+
+### Tiếng Nhật: biểu đồ thị trường, bảng so sánh đối thủ
+
+Nguồn: [`examples/06-jp-market.md`](examples/06-jp-market.md)
+
+![06-jp-market slide 1](docs/gallery/06-jp-market/slide-01.png)
+![06-jp-market slide 2](docs/gallery/06-jp-market/slide-02.png)
+
+### Tiếng Nhật: sơ đồ tổ chức, ma trận rủi ro
+
+Nguồn: [`examples/07-jp-org.md`](examples/07-jp-org.md)
+
+![07-jp-org slide 1](docs/gallery/07-jp-org/slide-01.png)
+![07-jp-org slide 2](docs/gallery/07-jp-org/slide-02.png)
+
+### Tiếng Nhật: kế hoạch trung hạn, lộ trình
+
+Nguồn: [`examples/08-jp-roadmap.md`](examples/08-jp-roadmap.md)
+
+![08-jp-roadmap slide 1](docs/gallery/08-jp-roadmap/slide-01.png)
+![08-jp-roadmap slide 2](docs/gallery/08-jp-roadmap/slide-02.png)
+![08-jp-roadmap slide 3](docs/gallery/08-jp-roadmap/slide-03.png)
+
+### Theme tối (midnight): KPI, biểu đồ, Mermaid, công thức, code
+
+Nguồn: [`examples/09-midnight-tech.md`](examples/09-midnight-tech.md)
+
+![09-midnight-tech slide 1](docs/gallery/09-midnight-tech/slide-01.png)
+![09-midnight-tech slide 2](docs/gallery/09-midnight-tech/slide-02.png)
+![09-midnight-tech slide 3](docs/gallery/09-midnight-tech/slide-03.png)
+![09-midnight-tech slide 4](docs/gallery/09-midnight-tech/slide-04.png)
+![09-midnight-tech slide 5](docs/gallery/09-midnight-tech/slide-05.png)
+![09-midnight-tech slide 6](docs/gallery/09-midnight-tech/slide-06.png)
+
+### Template .pptx của người dùng, ảnh (cover crop), biểu đồ, callout
+
+Nguồn: [`examples/10-template.md`](examples/10-template.md)
+
+![10-template slide 1](docs/gallery/10-template/slide-01.png)
+![10-template slide 2](docs/gallery/10-template/slide-02.png)
+![10-template slide 3](docs/gallery/10-template/slide-03.png)
+
+### Tiếng Nhật: bộ 9 slide tư vấn dày đặc (tóm tắt, KPI, tổ chức, lộ trình, rủi ro)
+
+Nguồn: [`examples/11-jp-consulting.md`](examples/11-jp-consulting.md)
+
+![11-jp-consulting slide 1](docs/gallery/11-jp-consulting/slide-01.png)
+![11-jp-consulting slide 2](docs/gallery/11-jp-consulting/slide-02.png)
+![11-jp-consulting slide 3](docs/gallery/11-jp-consulting/slide-03.png)
+![11-jp-consulting slide 4](docs/gallery/11-jp-consulting/slide-04.png)
+![11-jp-consulting slide 5](docs/gallery/11-jp-consulting/slide-05.png)
+![11-jp-consulting slide 6](docs/gallery/11-jp-consulting/slide-06.png)
+![11-jp-consulting slide 7](docs/gallery/11-jp-consulting/slide-07.png)
+![11-jp-consulting slide 8](docs/gallery/11-jp-consulting/slide-08.png)
+![11-jp-consulting slide 9](docs/gallery/11-jp-consulting/slide-09.png)
+
+### HTML/CSS → shape gốc (đo bằng Chromium), logo SVG, công thức
+
+Nguồn: [`examples/12-html-svg-math.md`](examples/12-html-svg-math.md)
+
+![12-html-svg-math slide 1](docs/gallery/12-html-svg-math/slide-01.png)
+![12-html-svg-math slide 2](docs/gallery/12-html-svg-math/slide-02.png)
+
+### Thiết kế tự do: thương hiệu tối, gradient, bóng đổ (theme: none + token)
+
+Nguồn: [`examples/13-brand-aurora.md`](examples/13-brand-aurora.md)
+
+![13-brand-aurora slide 1](docs/gallery/13-brand-aurora/slide-01.png)
+![13-brand-aurora slide 2](docs/gallery/13-brand-aurora/slide-02.png)
+![13-brand-aurora slide 3](docs/gallery/13-brand-aurora/slide-03.png)
+
+### Thiết kế tự do: thương hiệu sáng, font serif, màu đất nung (token)
+
+Nguồn: [`examples/14-brand-terracotta.md`](examples/14-brand-terracotta.md)
+
+![14-brand-terracotta slide 1](docs/gallery/14-brand-terracotta/slide-01.png)
+
+### Slide HTML toàn trang (@html) + slide SlideMark dùng chung token
+
+Nguồn: [`examples/15-html-mixed.md`](examples/15-html-mixed.md)
+
+![15-html-mixed slide 1](docs/gallery/15-html-mixed/slide-01.png)
+![15-html-mixed slide 2](docs/gallery/15-html-mixed/slide-02.png)
+![15-html-mixed slide 3](docs/gallery/15-html-mixed/slide-03.png)
+
+### Tiếng Nhật: chiến lược dịch vụ, Gantt, quyết định
+
+Nguồn: [`examples/16-jp-strategy.md`](examples/16-jp-strategy.md)
+
+![16-jp-strategy slide 1](docs/gallery/16-jp-strategy/slide-01.png)
+![16-jp-strategy slide 2](docs/gallery/16-jp-strategy/slide-02.png)
+![16-jp-strategy slide 3](docs/gallery/16-jp-strategy/slide-03.png)
+![16-jp-strategy slide 4](docs/gallery/16-jp-strategy/slide-04.png)
+![16-jp-strategy slide 5](docs/gallery/16-jp-strategy/slide-05.png)
+![16-jp-strategy slide 6](docs/gallery/16-jp-strategy/slide-06.png)
+![16-jp-strategy slide 7](docs/gallery/16-jp-strategy/slide-07.png)
+![16-jp-strategy slide 8](docs/gallery/16-jp-strategy/slide-08.png)
+![16-jp-strategy slide 9](docs/gallery/16-jp-strategy/slide-09.png)
+![16-jp-strategy slide 10](docs/gallery/16-jp-strategy/slide-10.png)
+
+### Thiết kế tự do bằng CSS fence: phong cách tạp chí
+
+Nguồn: [`examples/17-editorial-css.md`](examples/17-editorial-css.md)
+
+![17-editorial-css slide 1](docs/gallery/17-editorial-css/slide-01.png)
+![17-editorial-css slide 2](docs/gallery/17-editorial-css/slide-02.png)
+![17-editorial-css slide 3](docs/gallery/17-editorial-css/slide-03.png)
+![17-editorial-css slide 4](docs/gallery/17-editorial-css/slide-04.png)
+![17-editorial-css slide 5](docs/gallery/17-editorial-css/slide-05.png)
+
+### Thiết kế tự do: thương hiệu xanh chanh
+
+Nguồn: [`examples/18-brand-lime.md`](examples/18-brand-lime.md)
+
+![18-brand-lime slide 1](docs/gallery/18-brand-lime/slide-01.png)
+![18-brand-lime slide 2](docs/gallery/18-brand-lime/slide-02.png)
+![18-brand-lime slide 3](docs/gallery/18-brand-lime/slide-03.png)
+![18-brand-lime slide 4](docs/gallery/18-brand-lime/slide-04.png)
+
+### Tiếng Việt: bộ tư vấn theo thương hiệu (theme: none)
+
+Nguồn: [`examples/19-vi-consulting-brand.md`](examples/19-vi-consulting-brand.md)
+
+![19-vi-consulting-brand slide 1](docs/gallery/19-vi-consulting-brand/slide-01.png)
+![19-vi-consulting-brand slide 2](docs/gallery/19-vi-consulting-brand/slide-02.png)
+![19-vi-consulting-brand slide 3](docs/gallery/19-vi-consulting-brand/slide-03.png)
+![19-vi-consulting-brand slide 4](docs/gallery/19-vi-consulting-brand/slide-04.png)
+![19-vi-consulting-brand slide 5](docs/gallery/19-vi-consulting-brand/slide-05.png)
+
+### Tiếng Nhật: bộ 11 slide dày đặc (biểu đồ cầu, Gantt, ghi chú biểu đồ)
+
+Nguồn: [`examples/20-jp-retail-dense.md`](examples/20-jp-retail-dense.md)
+
+![20-jp-retail-dense slide 1](docs/gallery/20-jp-retail-dense/slide-01.png)
+![20-jp-retail-dense slide 2](docs/gallery/20-jp-retail-dense/slide-02.png)
+![20-jp-retail-dense slide 3](docs/gallery/20-jp-retail-dense/slide-03.png)
+![20-jp-retail-dense slide 4](docs/gallery/20-jp-retail-dense/slide-04.png)
+![20-jp-retail-dense slide 5](docs/gallery/20-jp-retail-dense/slide-05.png)
+![20-jp-retail-dense slide 6](docs/gallery/20-jp-retail-dense/slide-06.png)
+![20-jp-retail-dense slide 7](docs/gallery/20-jp-retail-dense/slide-07.png)
+![20-jp-retail-dense slide 8](docs/gallery/20-jp-retail-dense/slide-08.png)
+![20-jp-retail-dense slide 9](docs/gallery/20-jp-retail-dense/slide-09.png)
+![20-jp-retail-dense slide 10](docs/gallery/20-jp-retail-dense/slide-10.png)
+![20-jp-retail-dense slide 11](docs/gallery/20-jp-retail-dense/slide-11.png)
+
+### Tiếng Nhật: pitch tối thiết kế bằng CSS/HTML
+
+Nguồn: [`examples/21-jp-dark-pitch.md`](examples/21-jp-dark-pitch.md)
+
+![21-jp-dark-pitch slide 1](docs/gallery/21-jp-dark-pitch/slide-01.png)
+![21-jp-dark-pitch slide 2](docs/gallery/21-jp-dark-pitch/slide-02.png)
+![21-jp-dark-pitch slide 3](docs/gallery/21-jp-dark-pitch/slide-03.png)
+![21-jp-dark-pitch slide 4](docs/gallery/21-jp-dark-pitch/slide-04.png)
+
+### Tiếng Anh: kế hoạch ra mắt, chevron khớp cột bảng, ghi chú biểu đồ (hl=, note=)
+
+Nguồn: [`examples/22-en-launch-plan.md`](examples/22-en-launch-plan.md)
+
+![22-en-launch-plan slide 1](docs/gallery/22-en-launch-plan/slide-01.png)
+![22-en-launch-plan slide 2](docs/gallery/22-en-launch-plan/slide-02.png)
+![22-en-launch-plan slide 3](docs/gallery/22-en-launch-plan/slide-03.png)
+![22-en-launch-plan slide 4](docs/gallery/22-en-launch-plan/slide-04.png)
+![22-en-launch-plan slide 5](docs/gallery/22-en-launch-plan/slide-05.png)
+![22-en-launch-plan slide 6](docs/gallery/22-en-launch-plan/slide-06.png)
+![22-en-launch-plan slide 7](docs/gallery/22-en-launch-plan/slide-07.png)
+
+### Từ vựng bố cục: @timeline, @vs, @matrix, @funnel, @pyramid, @cycle, @agenda, @statement
+
+Nguồn: [`examples/23-vocabulary.md`](examples/23-vocabulary.md)
+
+![23-vocabulary slide 1](docs/gallery/23-vocabulary/slide-01.png)
+![23-vocabulary slide 2](docs/gallery/23-vocabulary/slide-02.png)
+![23-vocabulary slide 3](docs/gallery/23-vocabulary/slide-03.png)
+![23-vocabulary slide 4](docs/gallery/23-vocabulary/slide-04.png)
+![23-vocabulary slide 5](docs/gallery/23-vocabulary/slide-05.png)
+![23-vocabulary slide 6](docs/gallery/23-vocabulary/slide-06.png)
+![23-vocabulary slide 7](docs/gallery/23-vocabulary/slide-07.png)
+![23-vocabulary slide 8](docs/gallery/23-vocabulary/slide-08.png)
+![23-vocabulary slide 9](docs/gallery/23-vocabulary/slide-09.png)
+![23-vocabulary slide 10](docs/gallery/23-vocabulary/slide-10.png)
+
+### Từ vựng bố cục 2: iconlist, quote, split, proscons, progress, harvey, heatmap, pins
+
+Nguồn: [`examples/24-vocabulary-2.md`](examples/24-vocabulary-2.md)
+
+![24-vocabulary-2 slide 1](docs/gallery/24-vocabulary-2/slide-01.png)
+![24-vocabulary-2 slide 2](docs/gallery/24-vocabulary-2/slide-02.png)
+![24-vocabulary-2 slide 3](docs/gallery/24-vocabulary-2/slide-03.png)
+![24-vocabulary-2 slide 4](docs/gallery/24-vocabulary-2/slide-04.png)
+![24-vocabulary-2 slide 5](docs/gallery/24-vocabulary-2/slide-05.png)
+![24-vocabulary-2 slide 6](docs/gallery/24-vocabulary-2/slide-06.png)
+![24-vocabulary-2 slide 7](docs/gallery/24-vocabulary-2/slide-07.png)
+![24-vocabulary-2 slide 8](docs/gallery/24-vocabulary-2/slide-08.png)
+![24-vocabulary-2 slide 9](docs/gallery/24-vocabulary-2/slide-09.png)
+
+### 25-roundtrip-forms
+
+Nguồn: [`examples/25-roundtrip-forms.md`](examples/25-roundtrip-forms.md)
+
+![25-roundtrip-forms slide 1](docs/gallery/25-roundtrip-forms/slide-01.png)
+![25-roundtrip-forms slide 2](docs/gallery/25-roundtrip-forms/slide-02.png)
+![25-roundtrip-forms slide 3](docs/gallery/25-roundtrip-forms/slide-03.png)
+![25-roundtrip-forms slide 4](docs/gallery/25-roundtrip-forms/slide-04.png)
+![25-roundtrip-forms slide 5](docs/gallery/25-roundtrip-forms/slide-05.png)
+![25-roundtrip-forms slide 6](docs/gallery/25-roundtrip-forms/slide-06.png)
+![25-roundtrip-forms slide 7](docs/gallery/25-roundtrip-forms/slide-07.png)
+<!-- gallery:end -->
+
+## Tài liệu
+
+| File | Nội dung |
+|---|---|
+| [docs/SYNTAX.md](docs/SYNTAX.md) | Cú pháp |
+| [docs/PLAN.md](docs/PLAN.md) | Kế hoạch 7 ngày và quy trình chạy hằng ngày |
+| [docs/TARGETS.md](docs/TARGETS.md) | Mục tiêu L1–L7 |
+| [docs/AGENT_TIPS.md](docs/AGENT_TIPS.md) | Mẹo cho Agent khi dùng thư viện |
+| [docs/LESSONS.md](docs/LESSONS.md) | Lỗi đã gặp và cách giải quyết |
+| [docs/DAILY_LOG.md](docs/DAILY_LOG.md) | Nhật ký hằng ngày |