LearnAIHubC · LearnAIHubC · Jul 15, 2026
diff --git a/README.en.md b/README.en.md
@@ -38,7 +38,7 @@ LearnDeck is designed for that moment when you already have knowledge, but need
 - **Clearer structure** with sections, key points, examples, and takeaways
 - **Polished pages** that feel ready for lessons, workshops, reports, and sharing
 - **Editable delivery** so you can keep refining the wording, flow, and style
-- **Multiple visual styles** such as clean, academic, warm, bold, or dark
+- **Custom visual direction** derived from your brief, audience, brand, or reference image
 - **Reusable knowledge assets** that can grow into courses, training decks, or study reviews
 
 ## Install
@@ -57,8 +57,29 @@ To update an existing installation:
 npx --yes github:LearnAIHubC/LearnDeck --force
 ```
 
+## Direct HTML to PPTX
+
+LearnDeck's default creative workflow does not require an intermediate JSON plan or a fixed layout list:
+
+`your content + visual direction → model-designed HTML/CSS → browser geometry → editable PPTX`
+
+The model designs each slide around its message and keeps the deck coherent with shared colors, typography, spacing, and visual motifs. The existing JSON generator remains available only as a deterministic legacy option.
+
+To convert a model-authored HTML deck directly:
+
+```bash
+node scripts/html_to_ppt.js \
+  --input templates/learn-deck-polished-style.html \
+  --out-dir output \
+  --name learn-deck-polished-style
+```
+
+The bundled HTML is a seven-slide composition library, not a required sequence or content schema. Keep its visual language while selecting and reshaping only the pages that fit the user's material.
+
 ## Showcase Templates
 
+- [Open the seven-slide polished HTML style library](templates/learn-deck-polished-style.html)
+- [Download the polished editable PPTX style template](templates/learn-deck-polished-style.pptx)
 - [Download the English editable PPTX template](templates/learn-deck-showcase-en.pptx)
 - [Download the Chinese editable PPTX template](templates/learn-deck-showcase-zh.pptx)
 

diff --git a/README.md b/README.md
@@ -1,122 +1,181 @@
-# LearnDeck
+<div align="center">
 
-<p align="center">
-  <a href="README.zh-CN.md">简体中文</a> · English
-</p>
+<h1>LearnDeck</h1>
 
-<p align="center">
-  <img src="assets/learn-deck-cover-en.png" alt="LearnDeck editable PPT showcase template" width="900">
+<h3>Model-designed HTML → polished, editable PowerPoint</h3>
+
+<p>
+  Turn a topic, outline, notes, or source material into a coherent presentation.<br>
+  The model designs each slide in HTML/CSS, then LearnDeck rebuilds it as editable PPTX objects.
 </p>
 
-<p align="center">
-  <strong>Let AI create PPTs in one click.</strong><br>
-  Turn knowledge into clear, polished, editable presentation decks.
+<p>
+  <a href="README.zh-CN.md">简体中文</a>
+  ·
+  <a href="templates/learn-deck-polished-style.html">HTML style library</a>
+  ·
+  <a href="templates/learn-deck-polished-style.pptx">Editable PPTX</a>
 </p>
 
----
+<p>
+  <img src="https://img.shields.io/badge/version-0.4.0-6549E9?style=flat-square" alt="Version 0.4.0">
+  <img src="https://img.shields.io/badge/Codex-Skill-2F72F2?style=flat-square" alt="Codex Skill">
+  <img src="https://img.shields.io/badge/HTML_to_PPTX-editable-0AA49D?style=flat-square" alt="Editable HTML to PPTX">
+  <img src="https://img.shields.io/badge/license-MIT-FF6B21?style=flat-square" alt="MIT License">
+</p>
 
-## What Is LearnDeck?
+<img src="assets/learn-deck-cover-en.png" alt="LearnDeck turns source content into a polished editable presentation" width="100%">
 
-LearnDeck is an AI presentation companion for learning content.
+</div>
 
-It helps you turn a topic, outline, notes, course material, article summary, or rough idea into a clear, beautiful, editable PPT. Instead of starting from a blank deck, you start with knowledge. LearnDeck helps shape that knowledge into a presentation people can follow.
+## Why LearnDeck
 
-The idea is simple: let AI create the first high-quality PPT for you, then keep the result easy to revise, personalize, and reuse.
+Most presentation generators make you choose between a rigid schema and a flattened screenshot. LearnDeck takes a different route:
 
-## Why It Exists
+| Design follows the message | The result stays editable | Quality is visually verified |
+| --- | --- | --- |
+| The model authors the final HTML/CSS directly. No fixed layout enum is required. | Text, cards, shapes, gradients, and icons are rebuilt as separate PowerPoint objects. | Chromium audits the DOM before conversion; the final PPTX is rendered once for delivery QA. |
 
-Learning content often has enough substance, but turning it into a deck takes time:
+The default creative pipeline does **not** require an intermediate JSON slide plan:
 
-- You need a clear order for the ideas
-- You need pages that are easy to scan
-- You need a polished look that feels presentation-ready
-- You need the result to stay editable after generation
-- You need something that works for teaching, training, reporting, or sharing
+```text
+content + visual direction
+        ↓
+model-designed HTML/CSS
+        ↓
+browser DOM audit
+        ↓
+browser-measured geometry
+        ↓
+editable PowerPoint objects
+        ↓
+contact-sheet + full-size visual QA
+```
 
-LearnDeck is designed for that moment when you already have knowledge, but need a deck that makes it easier to teach and easier to understand.
+## Latest seven-slide style system
 
-## Who It Is For
+<p align="center">
+  <img src="assets/learn-deck-polished-overview.png" alt="Seven-slide LearnDeck polished composition library" width="100%">
+</p>
 
-- Teachers, instructors, and workshop hosts
-- Course creators and knowledge creators
-- Teams preparing internal training or onboarding material
-- Learners and researchers turning notes into reports
-- Anyone who wants AI to turn scattered knowledge into a presentable PPT
+This showcase includes a cover, statement page, relationship map, timeline, comparison, data story, and action close. It is a **composition library, not a mandatory sequence or fixed content template**. The user's content still determines the slide count, structure, visual emphasis, and layout of every page.
 
-## What You Get
+## Quick start
 
-- **One-click PPT generation** from a topic, outline, notes, or learning material
-- **Clearer structure** with sections, key points, examples, and takeaways
-- **Polished pages** that feel ready for lessons, workshops, reports, and sharing
-- **Editable delivery** so you can keep refining the wording, flow, and style
-- **Multiple visual styles** such as clean, academic, warm, bold, or dark
-- **Reusable knowledge assets** that can grow into courses, training decks, or study reviews
+### 1. Install the Skill
 
-## Install
+```bash
+npx --yes github:LearnAIHubC/LearnDeck
+```
 
-Run:
+Restart Codex, then invoke `$learn-deck`. To refresh an existing installation:
 
 ```bash
-npx --yes github:LearnAIHubC/LearnDeck
+npx --yes github:LearnAIHubC/LearnDeck --force
 ```
 
-Then restart Codex and use `$learn-deck`.
+### 2. Describe the presentation you want
 
-To update an existing installation:
+```text
+Use $learn-deck to turn my onboarding notes into a concise 10-slide deck.
+Use a calm editorial style with generous whitespace and a clear data story.
+Keep every text box, shape, gradient, and icon editable in PowerPoint.
+```
+
+You can provide a topic, outline, document, course material, study notes, brand direction, or reference image. LearnDeck derives the visual language from the request instead of forcing the content into a preset card count.
+
+### 3. Audit the DOM before conversion
 
 ```bash
-npx --yes github:LearnAIHubC/LearnDeck --force
+node scripts/html_to_ppt.js \
+  --input path/to/deck.html \
+  --dom-audit-only
 ```
 
-## Showcase Templates
+This Chromium preflight checks slide and text overflow, declared overlap/containment rules, unexpected single-line wrapping, centered text, centered SVG icons, chart labels, and text safety inside circles and compact cards. It produces structured errors without generating screenshots.
 
-- [Download the English editable PPTX template](templates/learn-deck-showcase-en.pptx)
-- [Download the Chinese editable PPTX template](templates/learn-deck-showcase-zh.pptx)
+### 4. Keep revising the same HTML
 
-The cover and workflow images in this README are rendered from these actual editable decks.
+The generated HTML remains the source of truth. When the content or style changes, LearnDeck edits that HTML, reconverts the PPTX, rerenders the previews, and checks the result again.
 
-## What Can You Create?
+## What stays editable
 
-LearnDeck is especially useful for:
+| HTML/CSS source | PowerPoint output |
+| --- | --- |
+| Headings, paragraphs, labels, and bullets | Separate editable text boxes |
+| Cards, panels, pills, borders, and circles | Native PowerPoint shapes |
+| Linear gradients and quiet decorative accents | Editable gradient and shape objects |
+| Inline SVG icons | Separate icon objects, with SVG sources preserved |
+| Browser positions and dimensions | Rebuilt on a 16:9 PowerPoint canvas |
 
-- Course introductions and lesson outlines
-- Classroom slides and learning cards
-- Internal training decks
-- Learning progress reports
-- Study group and book club presentations
-- Methodology explainers
-- Product or business knowledge training
-- Research summaries and knowledge reviews
+The converter favors **editable, separated elements** over a single full-slide screenshot.
 
-If your goal is to help people understand something more clearly, LearnDeck gives you a strong first deck.
+## DOM first, final render once
 
-## The Experience
+LearnDeck separates fast structural validation from final presentation validation:
 
-1. **Bring content**: start with a topic, outline, notes, article summary, or course material
-2. **Let AI shape it**: organize the message into titles, key points, examples, and takeaways
-3. **Create PPT**: get a coherent deck with a clean visual style and a clear learning rhythm
-4. **Edit freely**: adjust wording, tone, brand, sequence, and classroom style
+1. **Browser DOM preflight, no screenshots** — catches overflow, overlap, wrapping, centering, icon, chart-label, circle, pill, and card failures before a PPTX is written.
+2. **Final contact-sheet review** — checks narrative flow, composition variety, density, whitespace, hierarchy, color, and page-to-page consistency.
+3. **Final full-size slide review** — checks PowerPoint-specific clipping, wrapping, reconstruction, fine alignment, contrast, and chart labels.
 
-<p align="center">
-  <img src="assets/learn-deck-flow-en.png" alt="LearnDeck editable HTML-to-PPTX workflow slide" width="900">
-</p>
+The DOM audit replaces repeated draft screenshots, but not the final render: PowerPoint and LibreOffice can use different font metrics and object geometry from Chromium. If a problem appears, the original HTML is edited and the relevant audit/conversion loop runs again.
+
+Generate the same QA assets manually with:
+
+```bash
+node scripts/render_pptx_preview.js \
+  --input output/deck-name-editable.pptx \
+  --out-dir output/deck-name-qa
+```
+
+## Convert HTML directly
+
+Use any converter-compatible local HTML deck or URL:
+
+```bash
+node scripts/html_to_ppt.js \
+  --input templates/learn-deck-polished-style.html \
+  --out-dir output \
+  --name learn-deck-polished-style
+```
+
+The output is `output/learn-deck-polished-style-editable.pptx`. The legacy JSON generator remains available for deterministic compatibility, but it is not the default creative path.
+
+## Included templates
+
+- [Seven-slide polished HTML style library](templates/learn-deck-polished-style.html)
+- [Seven-slide polished editable PPTX](templates/learn-deck-polished-style.pptx)
+- [English editable showcase PPTX](templates/learn-deck-showcase-en.pptx)
+- [Chinese editable showcase PPTX](templates/learn-deck-showcase-zh.pptx)
 
-## Why The Name LearnDeck?
+Use the templates to study converter-compatible visual grammar: palette relationships, typography, spacing rhythm, corner radii, borders, shadows, and decorative motifs. Do not copy their sample content or treat their boxes as a schema.
 
-“Learn” stands for learning content, knowledge sharing, and teaching moments.
+## Good fits
 
-“Deck” stands for a complete presentation that can be taught, shared, edited, and reused.
+- Courses, lessons, workshops, and classroom slides
+- Internal training, onboarding, and enablement decks
+- Research summaries, reports, and knowledge reviews
+- Product explainers and methodology presentations
+- Reference-image-driven presentations that still need editable objects
 
-LearnDeck is not just a slide maker. It is a learning-deck partner that helps knowledge become a complete presentation with flow, clarity, and visual polish.
+## Development
+
+Requirements: Node.js 18 or newer. Final visual preview generation also uses LibreOffice, Poppler (`pdftoppm`), and `sharp`.
+
+```bash
+npm test
+npm pack --dry-run
+```
 
-## Vision
+The smoke test covers direct HTML conversion, DOM-audit failures, layout guards, multiline text handling, and legacy JSON compatibility.
 
-LearnDeck aims to make high-quality learning decks easier to create.
+## Project links
 
-It is for people who have ideas, notes, expertise, or teaching material, but do not want to spend most of their time shaping structure and polishing pages. A good PPT should help the presenter speak clearly and help the audience understand easily.
+- [Report an issue](https://github.com/LearnAIHubC/LearnDeck/issues)
+- [LINUX DO](https://linux.do/) — a community for technology enthusiasts
 
-LearnDeck exists to make that bridge lighter, faster, and more beautiful.
+<div align="center">
 
-## 友情链接
+If LearnDeck helps you turn knowledge into clearer presentations, consider starring the repository.
 
-- [LINUX DO](https://linux.do/) —— 新的理想型社区，技术爱好者的聚集地。
+</div>
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -44,7 +44,7 @@ LearnDeck 的交付结果更像是一套“学习型演示稿”，而不是普
 - **更清楚的内容结构**：主题、章节、重点、案例和结论被整理得更有层次
 - **更适合讲解的节奏**：页面顺序围绕学习者的理解路径展开
 - **更有质感的视觉表达**：版式干净，重点突出，适合课堂、培训和汇报
-- **更多风格选择**：可选择清爽、学术、暖色、大胆、深色等方向
+- **按需求定制视觉**：根据受众、品牌、内容和参考图动态设计风格
 - **更方便修改的结果**：后续可以继续调整文字、页面顺序和表达方式
 - **更容易复用的材料**：同一套内容可以延展成课程、培训、分享或复盘
 
@@ -64,8 +64,29 @@ npx --yes github:LearnAIHubC/LearnDeck
 npx --yes github:LearnAIHubC/LearnDeck --force
 ```
 
+## HTML 直接生成 PPTX
+
+LearnDeck 默认的创作链路不需要中间 JSON，也不限制在固定版式列表里：
+
+`你的内容 + 视觉要求 → 模型逐页设计 HTML/CSS → 浏览器真实坐标 → 可编辑 PPTX`
+
+模型会根据每页要表达的信息设计构图，再用共享的配色、字体、间距和视觉元素保持整套演示稿一致。现有 JSON 生成器仅作为需要确定性批量输出时的兼容选项保留。
+
+模型生成 HTML 后，可直接转换：
+
+```bash
+node scripts/html_to_ppt.js \
+  --input templates/learn-deck-polished-style.html \
+  --out-dir output \
+  --name learn-deck-polished-style
+```
+
+内置 HTML 是一套七页构图样本库，不是必须照搬的顺序、内容模板或固定版式。生成时保留视觉语言，只选择并重构适合用户内容的页面。
+
 ## 展示模板
 
+- [查看七页精致浅色 HTML 构图样本库](templates/learn-deck-polished-style.html)
+- [下载精致浅色可编辑 PPTX 风格模板](templates/learn-deck-polished-style.pptx)
 - [下载中文可编辑 PPTX 模板](templates/learn-deck-showcase-zh.pptx)
 - [下载英文可编辑 PPTX 模板](templates/learn-deck-showcase-en.pptx)