diff --git a/AGENTS.md b/AGENTS.md
index 6bc9688..b29abdf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,7 @@
- `fix: handle missing image API key`
- `docs: clarify installation steps`
- Commit messages, PR titles, changelog entries, and release notes must be written in English.
-- Documentation changes that affect README content must update both `README.md` and `README_en.md` in sync.
+- Documentation changes must update all existing language versions in sync, including repository README files and the usage documentation site.
## Changelog
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d5fcc92..d76dc73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ Release notes are generated from this file. Keep changelog entries in English.
### Documentation
- Add a Korean translation of the README (`README_ko.md`) and a language badge linking to it from `README.md` and `README_en.md`. (#90)
+- Replace README language badges with a consistent text-based language switcher across all translations. (#91)
+- Add complete English and Korean versions of the Docsify usage documentation with localized navigation, search, and pagination. (#91)
## 0.5.5
diff --git a/README.md b/README.md
index 51d9b86..c0b501f 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
# Codex PPT Skill
-[](README_en.md) [](README_ko.md) [](https://ningzimu.github.io/codex-ppt-skill/#/) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
+**简体中文** · [English](README_en.md) · [한국어](README_ko.md)
+
+[](https://ningzimu.github.io/codex-ppt-skill/#/) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
一个面向 Codex 的 PPT 生成 skill，也可在 Claude Code、OpenClaw、Hermes Agent 等支持 `SKILL.md` 的 agent 中使用；在这些非 Codex 环境中通常需要配置 `gpt-image-2`、第三方生图 API 或 OpenAI 兼容格式的生图接口。它把文章、报告、论文、课程笔记等内容转换成“整页图片式”的演示文稿：先规划大纲和视觉风格，再生成每页幻灯片图片，最后用本地脚本组装为 `.pptx`。
diff --git a/README_en.md b/README_en.md
index cbb9fcd..872866c 100644
--- a/README_en.md
+++ b/README_en.md
@@ -1,6 +1,8 @@
# Codex PPT Skill
-[](README.md) [](README_ko.md) [](https://ningzimu.github.io/codex-ppt-skill/#/) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
+[简体中文](README.md) · **English** · [한국어](README_ko.md)
+
+[](https://ningzimu.github.io/codex-ppt-skill/#/en/) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
A Codex skill for generating PowerPoint decks. It can also be used in Claude Code, OpenClaw, Hermes Agent, and other agents that support `SKILL.md`; these non-Codex environments usually require configuring `gpt-image-2`, a third-party image API, or an OpenAI-compatible image generation endpoint. It turns articles, reports, papers, course notes, and other source materials into image-based presentations: first plan the outline and visual style, then generate each full-slide image, and finally assemble the images into a `.pptx` file with a local script.
diff --git a/README_ko.md b/README_ko.md
index 998d502..1f7cd6f 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -1,6 +1,8 @@
# Codex PPT Skill
-[](README.md) [](README_en.md) [](https://ningzimu.github.io/codex-ppt-skill/#/) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
+[简体中文](README.md) · [English](README_en.md) · **한국어**
+
+[](https://ningzimu.github.io/codex-ppt-skill/#/ko/) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
PowerPoint 덱을 생성하는 Codex용 skill입니다. Codex 외에도 Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md`를 지원하는 다른 에이전트에서도 사용할 수 있으며, 이런 비(非)Codex 환경에서는 보통 `gpt-image-2`, 서드파티 이미지 API, 또는 OpenAI 호환 이미지 생성 엔드포인트 설정이 필요합니다. 이 skill은 글, 리포트, 논문, 강의 노트 등의 원본 자료를 "한 페이지 통이미지" 형식의 프레젠테이션으로 변환합니다. 먼저 개요와 시각 스타일을 기획하고, 각 슬라이드를 전면 이미지로 생성한 뒤, 마지막에 로컬 스크립트로 이미지들을 `.pptx` 파일로 조립합니다.
diff --git a/docs/_navbar.md b/docs/_navbar.md
new file mode 100644
index 0000000..4f66424
--- /dev/null
+++ b/docs/_navbar.md
@@ -0,0 +1,4 @@
+- 语言
+ - **简体中文**
+ - [English](/en/)
+ - [한국어](/ko/)
diff --git a/docs/en/README.md b/docs/en/README.md
new file mode 100644
index 0000000..6fb5483
--- /dev/null
+++ b/docs/en/README.md
@@ -0,0 +1,61 @@
+# Codex PPT Skill Documentation
+
+Codex PPT is a presentation-generation skill built for Codex. It also works with agents that support `SKILL.md`, including Claude Code, OpenClaw, and Hermes Agent. It turns articles, reports, papers, course notes, or rough ideas into image-based presentations: first planning the outline and visual style, then generating each complete slide as an image, and finally assembling the images into a `.pptx` file.
+
+## How to Read This Documentation
+
+If you just want to get started quickly, begin with the [Quick Start](/en/quickstart.md).
+
+If you need to install the skill, configure models, or connect it to different agents, see [Installation and Configuration](/en/installation.md).
+
+If you want to understand the complete generation process, confirmation checkpoints, and quality control, see the [Standard Workflow](/en/workflow.md).
+
+If you are already using the skill and have encountered a problem, see the [FAQ](/en/faq.md).
+
+## Pages
+
+- [Quick Start](/en/quickstart.md): The shortest path for first-time users, example commands, and output files.
+- [Design Philosophy](/en/design.md): Why the skill uses image-based presentations, staged confirmation, and a two-skill design.
+- [Installation and Configuration](/en/installation.md): Installation and update methods for Codex, OpenClaw, Claude Code, and Hermes Agent, plus API/CLI fallback configuration.
+- [Standard Workflow](/en/workflow.md): The complete process, from confirming the outline, style, backend, and sample slide to generating and assembling the full deck.
+- [Styles and Personal Style Library](/en/styles.md): Previews of the 12 built-in styles, reproducing a style from reference materials, and saving styles you like to your personal style library for long-term reuse.
+- [FAQ](/en/faq.md): Common questions about editability, API keys, sample slides, inserting source materials, and revising individual slides.
+- [Example Prompts](/en/prompts.md): Reusable prompts for turning articles into presentations, thesis defenses, executive reports, specified styles, and single-slide revisions.
+
+## Key Features
+
+- Image-based presentation generation: Each slide is a complete 16:9 slide image, ideal for scenarios that require strong visual expression and a consistent style.
+- Staged confirmation workflow: Confirm the outline, visual style, image-generation method, and sample slide before generating the full deck to reduce rework.
+- 12 built-in styles: Options include clean professional, scientific defense, hand-drawn technical explanation, McKinsey-style, party and government red, and teaching courseware. See [Styles and Personal Style Library](/en/styles.md).
+- Style matching from reference materials: The skill can review a user-provided presentation, PDF, or screenshots, understand the visual style of each page, and generate a similar style.
+- Personal style library: Styles you like can be saved to `~/.codex-ppt-skill/references/`, outside the skill installation directory. They remain available after skill updates and can be reused by name in future projects.
+- Place specified source materials on designated slides: You can assign original paper figures, experiment results, architecture diagrams, or screenshots to specific slides.
+- Multiple agent environments: In addition to Codex, the skill works with agents that support `SKILL.md`, including Claude Code, OpenClaw, and Hermes Agent.
+- Automatic PowerPoint assembly: The skill generates `outline.md`, individual slide images, and `speech.md`, then assembles everything into a `.pptx` file.
+- Third-party API support for text models and the `gpt-image-2` image-generation model.
+- Companion speaker notes: Speaker notes are generated and inserted into the PowerPoint notes pages by default.
+- Targeted post-generation edits for specific slides that need improvement. See the [FAQ](/en/faq.md).
+
+## Use Cases
+
+- Turning technical articles into presentation decks
+- Turning papers, research reports, or survey materials into presentations
+- Turning course notes into teaching slides
+- Product introductions, business reports, and project summaries
+- Thesis defenses, project applications, midterm reviews, and final acceptance presentations
+- Image-based presentations that require a consistent visual language
+
+## Important Notes
+
+Codex PPT generates image-based presentations. They offer strong visual consistency, but the text, charts, and shapes on a slide cannot be edited individually as they can in a traditional PowerPoint file.
+
+If you need to convert the result into an editable presentation, you can use [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill) after generation.
+
+You cannot use this skill without access to the `gpt-image-2` image-generation model. See [Installation and Configuration](/en/installation.md).
+
+## Related Links
+
+- GitHub repository: https://github.com/ningzimu/codex-ppt-skill
+- ClawHub page: https://clawhub.ai/ningzimu/codex-ppt
+- Use case showcase: https://github.com/ningzimu/codex-ppt-skill/issues/34
+- Editable presentation conversion skill: https://github.com/ningzimu/image-to-editable-ppt-skill
diff --git a/docs/en/_navbar.md b/docs/en/_navbar.md
new file mode 100644
index 0000000..67cbfc9
--- /dev/null
+++ b/docs/en/_navbar.md
@@ -0,0 +1,4 @@
+- Languages
+ - [简体中文](/)
+ - **English**
+ - [한국어](/ko/)
diff --git a/docs/en/_sidebar.md b/docs/en/_sidebar.md
new file mode 100644
index 0000000..6dc4894
--- /dev/null
+++ b/docs/en/_sidebar.md
@@ -0,0 +1,8 @@
+* [Documentation Home](/en/README.md)
+* [Quick Start](/en/quickstart.md)
+* [Design Philosophy](/en/design.md)
+* [Installation and Configuration](/en/installation.md)
+* [Standard Workflow](/en/workflow.md)
+* [Styles and Personal Style Library](/en/styles.md)
+* [FAQ](/en/faq.md)
+* [Example Prompts](/en/prompts.md)
diff --git a/docs/en/design.md b/docs/en/design.md
new file mode 100644
index 0000000..a48edd6
--- /dev/null
+++ b/docs/en/design.md
@@ -0,0 +1,41 @@
+# Design Philosophy
+
+Codex PPT Skill reflects some of my thinking about using AI to create presentations.
+
+The most important thing about AI-generated presentations is not speed, but having a controllable process that produces usable results.
+
+That is why I split the process into several steps:
+
+1. Read the article, paper, report, or Markdown file
+2. Generate an outline so the user can confirm the slide count, titles, and focus of each slide
+3. Confirm the overall visual style
+4. Generate one sample slide to check whether the text, layout, and style are suitable
+5. After the sample is approved, generate the complete image-based presentation slide by slide
+6. Assemble the slides into a `.pptx` file and add the script to the notes for convenient presentation reference
+
+## Why Generate an Image-Based Presentation First?
+
+Not every scenario requires editability. For technical talks, course notes, book-sharing sessions, paper reviews, or less formal reports, a presentation made from full-slide images is often sufficient and offers better visual consistency.
+
+If presentation generation and editable presentation conversion are tightly coupled from the beginning, the process becomes heavy. While the outline, style, and sample slide are still being revised, adding editable-structure reconstruction makes the workflow slower, more expensive, and harder to control.
+
+That is why I split the process into two skills:
+
+- One generates high-quality image-based presentations
+- The other converts an image-only presentation into an editable presentation when needed
+
+I believe it is more reliable to agree on the content and visual direction first, confirm that the generated results are under control, and only then decide whether editable conversion is necessary.
+
+## Improvements Based on Community Feedback
+
+This skill also includes several improvements based on community feedback:
+
+- Supports the image-generation capability included with Codex subscriptions
+- Also supports image-generation models through APIs
+- Works in agent environments including Codex, Claude Code, and OpenClaw
+- Supports parallel generation with sub-agents to speed up multi-slide presentation creation
+- Includes guidance for multiple built-in styles, so you can get good results without writing advanced prompts
+- Supports using reference images or existing presentations to generate a new presentation in a similar style
+- Preserves user-provided source images such as paper figures, experiment result charts, and screenshots wherever possible, reducing the risk of AI redrawing them incorrectly
+
+My goal is not to produce a 20-slide presentation with one click. It is to make AI presentation creation feel more like a real workflow: establish the structure, choose the style, approve a sample, then generate the complete deck and inspect the results.
diff --git a/docs/en/faq.md b/docs/en/faq.md
new file mode 100644
index 0000000..3c80344
--- /dev/null
+++ b/docs/en/faq.md
@@ -0,0 +1,67 @@
+# FAQ
+
+## Q: Is the Generated Presentation Editable?
+
+No. Codex PPT generates image-based presentations in which every slide is a complete slide image. The visual result is more consistent, but the text, charts, and shapes on a slide cannot be edited individually as they can in a traditional PowerPoint file. After generation, if you need to adjust the content or visuals, the recommended approach is to continue in the same conversation and ask the AI to revise the specific slide.
+
+Unless necessary, do not convert the presentation into an editable format unless you have sufficient Codex credits.
+
+If you need an editable presentation, try [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill) after generation. However, `image-to-editable-ppt-skill` is currently experimental. It currently supports only ChatGPT Plus / Pro subscribers using Codex and does not support other agents. If its results are unstable, wait for future update announcements.
+
+Note: The image-to-editable skill currently consumes a large number of tokens. It is not friendly to Plus users, while Pro users can use it more freely.
+
+## Q: Does It Support Other Agents?
+
+Yes. Codex PPT is a `SKILL.md`-based skill. In addition to Codex, it works with agents that support `SKILL.md`, including Claude Code, OpenClaw, and Hermes Agent.
+
+This skill is developed and tested primarily with Codex, so Codex offers the best compatibility and is recommended.
+
+Different agents have different image-generation capabilities and tool interfaces. Outside Codex, you will usually need to configure `gpt-image-2` or a third-party OpenAI-compatible image-generation API. See [Installation and Configuration](/en/installation.md), and let the AI guide you through setup based on your current environment.
+
+## Q: How Do I Update the Skill to the Latest Version?
+
+Rerun the installation command to overwrite the installed skill with the latest version, or ask your agent to update it for you, then restart the agent. API key configuration and your personal style library are stored outside the skill installation directory and are preserved during updates. See [Installation and Configuration](/en/installation.md) for the commands.
+
+## Q: Why Does the First Sample Slide Look Good While Later Slides Look Worse or Use a Different Style?
+
+This usually means the sample slide's style was not passed consistently to later slides, or the prompts, backend, or sub-agent execution method changed during generation.
+
+Under normal conditions, once a sample slide is approved, later slides should inherit the same visual language, including the color palette, typographic character, layout density, illustration approach, and image-generation backend. If later slides clearly drift, ask the AI to check whether every slide received the sample as a style reference, whether the same image-generation method was recorded and reused, whether a sub-agent switched to another generation method without permission, and whether individual slide prompts are too broad.
+
+Do not regenerate the entire deck. First select one or two slides with obvious drift and ask the AI to regenerate them using the approved sample as a reference. Explicitly require it to "preserve the sample slide's visual style, use the same image-generation backend, and maintain the same layout density."
+
+## Q: What Should I Do If the Generated Presentation Looks Bad?
+
+First confirm that your `gpt-image-2` model can generate images correctly. If the model is unavailable, returns abnormal quality, or a third-party API or relay service does not correctly support `gpt-image-2`, the output quality will be significantly worse.
+
+After confirming that the model works, ask the AI to address specific issues such as inconsistent styling, text that is too small, overcrowded layouts, unattractive colors, or illustrations that do not match the topic. It is best to regenerate one sample slide first and continue with the full deck only after you are satisfied.
+
+## Q: What Should I Do If the Generated Slide Images Are Blurry?
+
+Codex subscribers use the built-in image-generation tool by default. Its generated images have a relatively low resolution, which currently cannot be specified manually. For higher-resolution images, use the `gpt-image-2` API instead—the API/CLI fallback—and configure the API key, base URL, and model name. See [Installation and Configuration](/en/installation.md).
+
+With the API/CLI fallback, the script defaults to 2K resolution in a 16:9 landscape format. If the image is still blurry, especially on slides with substantial text, ask the AI to generate it at 4K resolution.
+
+## Q: Why Confirm the Outline First?
+
+Because most presentation rework comes from structural problems. Confirming the slide count, titles, order, and key points first prevents you from discovering that the content direction is wrong only after every image has been generated.
+
+## Q: Why Generate a Sample Slide First?
+
+The sample slide establishes the visual baseline for the complete presentation. After it is approved, later slides can inherit the same color palette, typographic character, density, and visual language.
+
+## Q: Do I Need to Configure an API Key in Codex?
+
+If Codex's built-in image-generation tool is available, you usually do not need to configure an API key. You need to configure `OPENAI_API_KEY`, an optional `OPENAI_BASE_URL`, and a model name only when you choose the API/CLI fallback.
+
+## Q: Can I Insert Original Paper Figures or Architecture Diagrams?
+
+Yes. During the outline stage, specify the slide number and purpose for each image, and state whether it is strict source material or a style reference. For paper figures, experiment result charts, screenshots, and architecture diagrams, preserve the original information, labels, axes, values, and arrow relationships wherever possible.
+
+## Q: What Should I Do If One Slide Looks Bad?
+
+Revise only that slide first. Tell the agent the specific issue—for example, the text is too small, the hierarchy is unclear, the color palette is unsuitable, the visual is overcrowded, or a concept is represented inaccurately.
+
+## Q: Can I Save My Own Styles?
+
+Yes. Give the agent presentation screenshots, a PDF, or a complete presentation that you like and ask it to analyze the style. Once you are satisfied with the generated result, ask the agent to save the style to your personal style library at `~/.codex-ppt-skill/references/`. The library is stored outside the skill installation directory, so it is preserved when the skill is updated or reinstalled. If a personal style shares a name with a built-in style, the personal style takes precedence. See [Styles and Personal Style Library](/en/styles.md).
diff --git a/docs/en/installation.md b/docs/en/installation.md
new file mode 100644
index 0000000..42768d5
--- /dev/null
+++ b/docs/en/installation.md
@@ -0,0 +1,98 @@
+# Installation and Configuration
+
+## One-Sentence Installation
+
+The recommended approach is to send the following sentence directly to Codex and let it install the skill for you:
+
+```text
+Please install this codex-ppt skill for me: https://github.com/ningzimu/codex-ppt-skill
+```
+
+## Manual Installation for Codex
+
+Run the following command to install the `codex-ppt` skill in Codex's global skills directory:
+
+```bash
+npx -y skills@latest add ningzimu/codex-ppt-skill \
+ --skill codex-ppt \
+ --agent codex \
+ --global
+```
+
+Restart Codex after installation so the new skill takes effect.
+
+You can also download `codex-ppt-skill-v*.zip` from [GitHub Releases](https://github.com/ningzimu/codex-ppt-skill/releases), extract it, place the included `codex-ppt` folder at `~/.codex/skills/codex-ppt`, and restart Codex.
+
+If you are developing this repository locally, you can symlink the skill directory into the Codex skills directory for real-time testing:
+
+```bash
+mkdir -p ~/.codex/skills
+ln -s /path/to/codex-ppt-skill/skills/codex-ppt ~/.codex/skills/codex-ppt
+```
+
+## OpenClaw Installation
+
+```bash
+openclaw skills install codex-ppt
+```
+
+If you use OpenClaw's skill allowlist, add `codex-ppt` to the allowlist.
+
+## Claude Code / Hermes Agent
+
+Claude Code:
+
+```bash
+npx -y skills@latest add ningzimu/codex-ppt-skill \
+ --skill codex-ppt \
+ --agent claude-code \
+ --global
+```
+
+Hermes Agent:
+
+```bash
+npx -y skills@latest add ningzimu/codex-ppt-skill \
+ --skill codex-ppt \
+ --agent hermes-agent \
+ --global
+```
+
+Common destination directories are `~/.claude/skills/codex-ppt` for Claude Code and `~/.hermes/skills/codex-ppt` for Hermes Agent. During local development, you can likewise use a symlink instead of copying the directory.
+
+## Updating the Skill
+
+The recommended approach is to send the following sentence directly to your agent and let it update the skill for you:
+
+```text
+Please update the codex-ppt skill to the latest version. The repository is: https://github.com/ningzimu/codex-ppt-skill
+```
+
+For a manual update, rerun the installation command above for the relevant agent. This overwrites the installed skill with the latest version. Alternatively, download the latest `codex-ppt-skill-v*.zip` from [GitHub Releases](https://github.com/ningzimu/codex-ppt-skill/releases), extract it, and replace the existing `codex-ppt` directory. Restart the agent after the update.
+
+Updates are safe: runtime configuration such as API keys is stored in `~/.codex-ppt-skill/.env`, while your personal style library is stored in `~/.codex-ppt-skill/references/`. Both are outside the skill installation directory, so updating or reinstalling the skill will not remove them. See the [Releases page](https://github.com/ningzimu/codex-ppt-skill/releases) or the repository's `CHANGELOG.md` for the changes in each version.
+
+## Image-Generation Model Configuration
+
+You cannot use this skill without access to the `gpt-image-2` model. The skill depends heavily on the `gpt-image-2` image-generation model.
+
+## How Do I Know Whether I Have Access to `gpt-image-2`?
+
+- If you subscribe to ChatGPT Plus or Pro, you have access to the `gpt-image-2` model by default. Codex includes a built-in image-generation tool.
+- If you access Codex through a third-party relay API, ask it to generate an image containing complex Chinese text, such as a poem written in running script. Check whether the image is generated successfully and whether the Chinese characters contain errors. If everything works, no further configuration is required.
+- If neither option works, you will need to purchase access to a relay API that provides the `gpt-image-2` model.
+
+You usually do not need to configure the image-generation model manually. While you use Codex PPT, the AI automatically detects the image-generation backend. If none is available, it will ask you to configure an image-generation backend API and guide you through the setup.
+
+## Notes on Third-Party APIs
+
+This skill includes a script compatible with OpenAI's official image-generation interface. If you use a third-party `gpt-image-2` relay API, try providing:
+
+- The relay service's base URL
+ - If the relay service gives an endpoint such as `https://xxx/v1/images/generations`, set the base URL to `https://xxx/v1`.
+ - If the relay service already gives `https://xxx/v1`, do not append another layer, which would produce `.../v1/v1`.
+ - For official OpenAI, `OPENAI_BASE_URL` can be omitted; the default is the official `https://api.openai.com/v1`.
+- The relay service's API key
+- The exact `gpt-image-2` model name used by the relay service
+
+After providing this information to the AI, ask it to generate an image. If it still does not work, the relay service may use a custom image-generation scheme that is not fully compatible with the OpenAI image API. Send the relay service's official image-generation documentation to the AI so it can learn the interface and adapt the image-generation script.
diff --git a/docs/en/prompts.md b/docs/en/prompts.md
new file mode 100644
index 0000000..b5df4f8
--- /dev/null
+++ b/docs/en/prompts.md
@@ -0,0 +1,45 @@
+# Example Prompts
+
+## Turn an Article into a Presentation
+
+```text
+Please use the codex-ppt skill to turn /path/to/article.md into a Chinese presentation of about 10 slides. The audience is an internal technical team.
+```
+
+## Turn a Paper into a Thesis Defense Presentation
+
+```text
+Please use the codex-ppt skill to turn this paper into a 12-slide Chinese thesis defense presentation. Use a scientific defense style. The structure should cover the research background, method, experiments, results, limitations, and conclusion. Preserve the model architecture diagram and the main experiment result figures from the paper on the corresponding slides.
+```
+
+## Specify a Visual Style
+
+```text
+Please use the codex-ppt skill to generate a presentation. Use the PDF I uploaded as the visual style reference: large titles, generous whitespace, a black-white-gray palette, and small red accents, with the overall feel of a business magazine feature. Review every page image in the material in detail to understand its style, then generate the presentation in a similar style.
+```
+
+## Specify a Built-in Style
+
+```text
+Please use the codex-ppt skill to turn this material into a 10-slide presentation. Use the built-in "Hand-Drawn Technical Explanation" style, with hand-drawn lines, structured diagrams, lightweight annotations, and clear concept breakdowns. It should be suitable for explaining technical principles and popularizing knowledge.
+```
+
+You can also replace the style name with another built-in option such as "Clean Professional," "Scientific Defense," "Data Dashboard," "E-Ink Magazine," or "Creative Magazine."
+
+## Specify the Slide Count and Source Materials
+
+```text
+Please use the codex-ppt skill to turn this material into a 15-slide presentation. Use architecture.png on slide 4 and benchmark-results.png on slide 9.
+```
+
+## Revise One Slide
+
+```text
+Slide 6 is too dense, and its title is not clear enough. Regenerate only slide 6, preserve the style of the complete presentation, and reorganize the content into a clearer three-part structure.
+```
+
+## Save a Style to the Personal Style Library
+
+```text
+I really like the visual style of this presentation. Save it to the codex-ppt personal style library for future reuse. Include the color palette, typographic character, layout rules, illustration/chart style, and suitable use cases in the description.
+```
diff --git a/docs/en/quickstart.md b/docs/en/quickstart.md
new file mode 100644
index 0000000..ac9c26b
--- /dev/null
+++ b/docs/en/quickstart.md
@@ -0,0 +1,35 @@
+# Quick Start
+
+## Who This Is For
+
+This page is for first-time Codex PPT users. All you need is an article, report, outline, paper, or set of course notes. Then ask your agent to use the `codex-ppt` skill to generate a presentation.
+
+## Shortest Way to Get Started
+
+First install the skill by following [Installation and Configuration](/en/installation.md). Then use the skill directly in Codex to create your presentation.
+
+```text
+Please use the codex-ppt skill to turn /path/to/article.md into a Chinese presentation of about 10 slides.
+```
+
+If you already know the intended style and use case, be more specific:
+
+```text
+Please use the codex-ppt skill to turn this technical article into a 12-slide Chinese presentation. Use a clean, professional style suitable for an internal technical talk. Slide 5 must use the architecture diagram I provided, and slide 8 must preserve the experiment results figure.
+```
+
+## Recommendations for Your First Use
+
+- Ask the agent to generate `outline.md` first, then confirm the slide count, titles, and key points for each slide.
+- Do not skip sample-slide confirmation. Review one slide before generating the full deck.
+- If one slide is unsatisfactory, revise only that slide instead of regenerating the entire deck.
+- If you have a reference presentation, screenshot, or PDF, ask the agent to analyze its style before generating the new presentation.
+
+## Generated Outputs
+
+You will usually receive:
+
+- `outline.md`: Presentation outline
+- `origin_image/slide_XX.png`: Final image for each slide
+- `speech.md`: Speaker notes for each slide
+- `{presentation-name}.pptx`: Final PowerPoint file
diff --git a/docs/en/styles.md b/docs/en/styles.md
new file mode 100644
index 0000000..6a3c733
--- /dev/null
+++ b/docs/en/styles.md
@@ -0,0 +1,59 @@
+# Styles and Personal Style Library
+
+Codex PPT draws its visual styles from two sources: the **built-in styles** shipped with the skill and your **personal style library**, which is stored locally and remains intact when the skill is updated.
+
+## Built-in Styles
+
+The skill includes 12 built-in style references, so you can get started without knowing how to write prompts. When creating a presentation, simply name the style you want. For example:
+
+```text
+Please use the codex-ppt skill to turn this material into a 10-slide presentation using the built-in "Hand-Drawn Technical Explanation" style.
+```
+
+| Clean Professional | Creative Magazine |
+| --- | --- |
+|  |  |
+| E-Ink Magazine | Data Dashboard |
+|  |  |
+| Retro Flat Illustration | Hand-Drawn Technical Explanation |
+|  |  |
+| Hand-Drawn Whiteboard | Warm Handmade |
+|  |  |
+| Scientific Defense | McKinsey-Style |
+|  |  |
+| Party and Government Red | Teaching Courseware |
+|  |  |
+
+A style is a visual system—including color palette, typographic character, layout density, and illustration language—not a fixed template. Within one style, each slide's layout changes according to its content role, so the slides do not all look identical.
+
+## Reproducing the Style of Reference Materials
+
+If the built-in styles do not meet your needs, provide a style reference you like: one screenshot, several screenshots, or a complete presentation or PDF. Ask the agent to analyze the colors, layout, typography, and visual elements before generating a new presentation in the same style:
+
+```text
+Please use the codex-ppt skill to generate a presentation. Use the PDF I uploaded as the visual style reference. Review every page image in detail to understand its style, then generate the presentation in a similar style.
+```
+
+Note: By default, only the style is reproduced, not the content. Unless you explicitly request it, text and data from the reference material will not be copied into the new presentation.
+
+## Personal Style Library
+
+If you are satisfied with a generated presentation's style—whether it is a custom style you developed or a style reproduced from reference material—you can ask the agent to save it for direct reuse:
+
+```text
+I really like the visual style of this presentation. Please save it to my personal style library.
+```
+
+Key points about how saving works:
+
+- **Storage location**: Your personal style library is located at `~/.codex-ppt-skill/references/` and can be moved using the `CODEX_PPT_HOME` environment variable. It is stored **outside** the skill installation directory, so updating or reinstalling the skill will not overwrite or remove your personal styles.
+- **Automatic discovery**: No registration is required after saving. The next time you choose a presentation style, the agent automatically scans your personal style library and lists your styles alongside the built-in styles.
+- **Personal styles take precedence**: If a personal style has the same name as a built-in style, your personal style is used. You can use this behavior to customize a built-in style by saving an adjusted version under the same name.
+- **Reuse by name**: In the future, simply name the style—for example, "Generate this presentation using the 'Dark Data Technology' style."
+
+After generation, if a deck uses a custom or adjusted style, the agent will also mention in its final report that you can save it. There is no need to save an unmodified built-in style again.
+
+## Related Pages
+
+- [Example Prompts](/en/prompts.md): Complete prompts for choosing a built-in style, matching a reference style, and saving a style.
+- [FAQ](/en/faq.md): What to do when the style drifts or a slide is unsatisfactory.
diff --git a/docs/en/workflow.md b/docs/en/workflow.md
new file mode 100644
index 0000000..0faed0b
--- /dev/null
+++ b/docs/en/workflow.md
@@ -0,0 +1,69 @@
+# Standard Workflow
+
+## Overview
+
+The Codex PPT workflow emphasizes staged confirmation. Instead of immediately generating the entire presentation, it first confirms the outline, style, image backend, and sample slide to reduce rework.
+
+## Stage 1: Review the Source Material
+
+The agent first determines:
+
+- The topic and central argument
+- The target audience
+- The presentation objective
+- The required slide count
+- Content that must be included or excluded
+- Whether any image assets are required
+
+## Stage 2: Confirm the Outline
+
+The agent generates `outline.md`, which usually includes:
+
+- Slide number
+- Slide title
+- 3-5 key points per slide
+- The role of each slide, such as cover, agenda, concept explanation, process, comparison, data evidence, or summary
+- Optional visual ideas
+- Required image assets and how they will be used
+
+No final slide images, `speech.md`, or `.pptx` file should be generated before the outline is approved.
+
+## Stage 3: Confirm the Visual Style
+
+The agent proposes 2-3 style directions and recommends one. Candidates come from the 12 built-in styles, including clean professional, scientific defense, hand-drawn technical explanation, McKinsey-style, party and government red, and teaching courseware, as well as your personal style library. The agent can also reproduce a style from screenshots, a PDF, or a presentation you provide. See [Styles and Personal Style Library](/en/styles.md) for complete style previews.
+
+After a style is selected, the entire presentation should maintain a consistent visual language, while individual slide layouts may vary according to the content.
+
+## Stage 4: Confirm the Image-Generation Backend
+
+The Codex built-in image-generation tool is preferred. The workflow switches to `scripts/image_gen.py` only when the built-in tool is unavailable, the user explicitly requests an API/CLI fallback, or the current capability cannot satisfy the request.
+
+Once the image backend is confirmed, the entire presentation should use the same backend without switching midway.
+
+## Stage 5: Generate and Confirm a Sample Slide
+
+Generate one sample slide first and check:
+
+- Whether the text is clear
+- Whether the style matches expectations
+- Whether the information density is appropriate
+- Whether the colors and layout are stable
+- Whether the design can scale to the full presentation
+
+Generate the full deck only after the sample slide is approved.
+
+## Stage 6: Batch Generation
+
+After the sample slide is approved, the agent generates `origin_image/slide_XX.png` one slide at a time. In environments that support sub-agents, one sub-agent generates each slide in parallel to speed up multi-slide production. Every slide follows the same style and image-generation backend approved for the sample.
+
+## Stage 7: Quality Review and Fixes
+
+Before assembly, the agent reviews every slide for text clarity, consistency with the outline, clipped content, visual consistency, unnecessary page numbers, and overlapping elements. Slides with serious issues are regenerated using stricter prompts, while minor local issues are preferably corrected with targeted image-editing tools.
+
+## Stage 8: Speaker Notes and Assembly
+
+The agent generates the speaker notes in `speech.md`, then uses `assemble_ppt.py` to assemble the presentation into a `.pptx` file. The speaker notes are automatically added to the notes section of each slide.
+
+## Stage 9 (Optional): Save the Style
+
+If the presentation uses a custom or adjusted style, the agent notes in the final report that you can save it to your personal style library and reuse it by name in the future. See [Styles and Personal Style Library](/en/styles.md).
diff --git a/docs/index.html b/docs/index.html
index 06adf75..b5e8dbb 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -2,7 +2,7 @@
- Codex PPT Skill 文档
+ Codex PPT Skill Docs
@@ -121,26 +121,63 @@
+
diff --git a/docs/ko/README.md b/docs/ko/README.md
new file mode 100644
index 0000000..5ee0b45
--- /dev/null
+++ b/docs/ko/README.md
@@ -0,0 +1,61 @@
+# Codex PPT Skill 문서
+
+Codex PPT는 Codex용 PPT 생성 skill이며, Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md`를 지원하는 agent에서도 사용할 수 있습니다. 글, 보고서, 논문, 수업 노트 또는 거친 아이디어를 이미지형 프레젠테이션으로 변환합니다. 먼저 개요와 시각 스타일을 설계하고, 각 슬라이드의 완성 이미지를 차례로 생성한 뒤, 마지막으로 `.pptx` 파일로 조립합니다.
+
+## 문서 읽는 순서
+
+빠르게 시작하려면 먼저 [빠른 시작](/ko/quickstart.md)을 읽으세요.
+
+설치, 모델 설정 또는 여러 agent 연동 방법이 필요하다면 [설치 및 설정](/ko/installation.md)을 읽으세요.
+
+전체 생성 과정, 확인 단계와 품질 관리를 이해하려면 [표준 워크플로](/ko/workflow.md)를 읽으세요.
+
+사용 중 문제가 생겼다면 [자주 묻는 질문](/ko/faq.md)을 확인하세요.
+
+## 하위 문서
+
+- [빠른 시작](/ko/quickstart.md): 처음 사용할 때의 가장 짧은 절차, 예시 명령과 결과물 안내.
+- [설계 철학](/ko/design.md): 이미지형 PPT, 단계별 확인, 두 skill의 역할 분담을 채택한 이유.
+- [설치 및 설정](/ko/installation.md): Codex, OpenClaw, Claude Code, Hermes Agent의 설치 및 업데이트 방법과 API/CLI fallback 설정.
+- [표준 워크플로](/ko/workflow.md): 개요 확인, 스타일 확인, 백엔드 확인, 샘플 슬라이드 확인부터 전체 생성과 조립까지의 완전한 과정.
+- [스타일 및 개인 스타일 라이브러리](/ko/styles.md): 12가지 내장 스타일 미리보기, 참고 자료의 스타일 재현, 마음에 드는 스타일을 개인 스타일 라이브러리에 저장해 장기적으로 재사용하는 방법.
+- [자주 묻는 질문](/ko/faq.md): 편집 가능 여부, API key, 샘플 슬라이드, 이미지 삽입, 개별 슬라이드 수정 등 자주 묻는 문제.
+- [예시 프롬프트](/ko/prompts.md): 글을 PPT로 변환, 논문 발표, 경영진 보고, 스타일 지정, 개별 슬라이드 수정 등에 바로 재사용할 수 있는 프롬프트.
+
+## 주요 기능
+
+- 이미지형 PPT 생성: 각 페이지가 완성된 16:9 슬라이드 이미지로 만들어져, 강한 시각적 표현과 일관된 스타일이 필요한 상황에 적합합니다.
+- 단계별 확인 절차: 개요, 시각 스타일, 이미지 생성 방식과 샘플 슬라이드를 먼저 확인한 뒤 전체 PPT를 생성해 재작업을 줄입니다.
+- 12가지 내장 스타일: 손그림 기술 설명, 연구 발표, 깔끔한 전문 스타일, McKinsey 스타일, 당·정 홍보용 레드 스타일, 교육용 코스웨어 등 다양한 방향을 제공합니다. 자세한 내용은 [스타일 및 개인 스타일 라이브러리](/ko/styles.md)를 참고하세요.
+- 참고 자료 기반 스타일 재현: 사용자가 제공한 PPT, PDF 또는 스크린샷을 읽고 각 페이지의 이미지 스타일을 이해한 뒤 유사하게 생성할 수 있습니다.
+- 개인 스타일 라이브러리 축적: 마음에 드는 스타일을 `~/.codex-ppt-skill/references/`에 저장할 수 있습니다. skill 설치 디렉터리 외부에 보관되므로 skill을 업데이트해도 사라지지 않으며, 이후 이름으로 바로 재사용할 수 있습니다.
+- 지정 이미지 삽입: 논문 원본 이미지, 실험 결과 그래프, 아키텍처 다이어그램 또는 스크린샷을 특정 슬라이드에 사용하도록 지정할 수 있습니다.
+- 여러 agent 환경 지원: Codex 외에도 Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md`를 지원하는 agent에서 사용할 수 있습니다.
+- PowerPoint 자동 조립: `outline.md`, 각 슬라이드 이미지, `speech.md`를 생성하고 최종적으로 `.pptx` 파일로 조립합니다.
+- 서드파티 API를 통한 텍스트 모델 및 `gpt-image-2` 이미지 생성 모델 사용 지원.
+- PPT 발표 대본 생성을 지원하며, 기본적으로 PPT 메모 영역에 자동 삽입합니다.
+- 생성 후 만족스럽지 않은 특정 슬라이드만 선택적으로 수정할 수 있습니다. 자세한 내용은 [자주 묻는 질문](/ko/faq.md)을 참고하세요.
+
+## 활용 사례
+
+- 기술 문서를 발표용 PPT로 변환
+- 논문, 연구 보고서 또는 조사 자료를 프레젠테이션으로 변환
+- 수업 노트를 강의 자료로 변환
+- 제품 소개, 비즈니스 보고, 프로젝트 회고
+- 연구 발표, 프로젝트 신청, 중간 점검, 최종 검수
+- 일관된 시각 언어가 필요한 이미지형 프레젠테이션
+
+## 중요 안내
+
+Codex PPT는 이미지형 PPT를 생성합니다. 시각적 일관성은 높지만, 슬라이드 안의 텍스트, 차트와 도형을 기존 PPT처럼 개별적으로 편집할 수는 없습니다.
+
+편집 가능한 PPT로 추가 변환해야 한다면 생성 후 [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill)을 사용할 수 있습니다.
+
+`gpt-image-2` 이미지 생성 모델을 사용할 권한이 없다면 이 skill을 사용할 수 없습니다. 자세한 내용은 [설치 및 설정](/ko/installation.md)을 참고하세요.
+
+## 관련 링크
+
+- GitHub 저장소: https://github.com/ningzimu/codex-ppt-skill
+- ClawHub 페이지: https://clawhub.ai/ningzimu/codex-ppt
+- 사용 사례 전시: https://github.com/ningzimu/codex-ppt-skill/issues/34
+- 편집 가능한 PPT 변환 skill: https://github.com/ningzimu/image-to-editable-ppt-skill
diff --git a/docs/ko/_navbar.md b/docs/ko/_navbar.md
new file mode 100644
index 0000000..7ebd396
--- /dev/null
+++ b/docs/ko/_navbar.md
@@ -0,0 +1,4 @@
+- 언어
+ - [简体中文](/)
+ - [English](/en/)
+ - **한국어**
diff --git a/docs/ko/_sidebar.md b/docs/ko/_sidebar.md
new file mode 100644
index 0000000..c194ca7
--- /dev/null
+++ b/docs/ko/_sidebar.md
@@ -0,0 +1,8 @@
+* [문서 홈](/ko/README.md)
+* [빠른 시작](/ko/quickstart.md)
+* [설계 철학](/ko/design.md)
+* [설치 및 설정](/ko/installation.md)
+* [표준 워크플로](/ko/workflow.md)
+* [스타일 및 개인 스타일 라이브러리](/ko/styles.md)
+* [자주 묻는 질문](/ko/faq.md)
+* [예시 프롬프트](/ko/prompts.md)
diff --git a/docs/ko/design.md b/docs/ko/design.md
new file mode 100644
index 0000000..af20a5e
--- /dev/null
+++ b/docs/ko/design.md
@@ -0,0 +1,41 @@
+# 설계 철학
+
+Codex PPT Skill에는 AI로 PPT를 만드는 방법에 대한 저의 생각이 담겨 있습니다.
+
+AI로 PPT를 만들 때 가장 중요한 것은 속도가 아니라, 과정을 통제할 수 있고 결과물을 실제로 사용할 수 있는가입니다.
+
+그래서 과정을 다음 단계로 나누었습니다.
+
+1. 글, 논문, 보고서 또는 Markdown 읽기
+2. 개요를 생성하고 사용자에게 페이지 수, 제목과 각 페이지의 핵심 내용을 확인받기
+3. 전체 시각 스타일 확인하기
+4. 샘플 슬라이드 1장을 생성해 텍스트, 레이아웃과 스타일의 완성도 확인하기
+5. 샘플 슬라이드가 승인되면 전체 이미지형 PPT를 페이지별로 생성하기
+6. 마지막으로 `.pptx`로 조립하고 발표 대본을 메모에 넣어 발표할 때 참고할 수 있도록 하기
+
+## 이미지형 PPT를 기본으로 먼저 만드는 이유
+
+모든 상황에서 편집 가능한 PPT가 필요한 것은 아니기 때문입니다. 기술 공유, 수업 노트, 독서 모임, 논문 해설 또는 비교적 비공식적인 보고라면 전체 페이지가 이미지인 PPT로도 충분하며, 시각적 일관성도 더 좋습니다.
+
+처음부터 “PPT 생성”과 “편집 가능한 PPT로 변환”을 강하게 결합하면 과정이 지나치게 무거워집니다. 초기에 개요, 스타일과 샘플 슬라이드를 계속 수정하는 단계에서 편집 구조 복원까지 도입하면 오히려 더 느리고, 비싸며, 통제하기 어려워집니다.
+
+그래서 두 개의 skill로 나누었습니다.
+
+- 하나는 고품질 이미지형 PPT 생성을 담당합니다.
+- 다른 하나는 필요한 경우 이미지형 PPT를 편집 가능한 PPT로 다시 변환합니다.
+
+먼저 내용과 시각적 방향을 충분히 논의하고 생성 결과를 통제할 수 있는지 확인한 뒤 편집 가능한 형태로 변환할지 결정하는 편이 더 안정적이라고 생각합니다.
+
+## 커뮤니티 피드백을 반영한 개선
+
+이 skill에는 커뮤니티 피드백을 반영한 다음과 같은 개선도 포함되어 있습니다.
+
+- Codex 회원용 내장 이미지 생성 기능 지원
+- API를 통한 이미지 생성 모델 연동 지원
+- Codex, Claude Code, OpenClaw 등 여러 agent 환경에서 사용 가능
+- 하위 agent의 병렬 생성을 지원해 여러 페이지의 PPT 생성 속도 향상
+- 다양한 내장 스타일 가이드를 제공해 고급 prompt를 작성하지 못해도 준수한 결과 생성
+- 참고 이미지 또는 기존 PPT와 유사한 스타일의 새 PPT 생성 지원
+- 논문 이미지, 실험 결과 그래프, 스크린샷 등 사용자가 제공한 원본 이미지를 최대한 보존해 AI가 임의로 다시 그리지 않도록 개선
+
+제가 만들고 싶은 것은 “한 번 눌러 20페이지 PPT를 만드는 기능”이 아닙니다. AI로 PPT를 만드는 일을 실제 업무 흐름에 더 가까운 과정으로 만드는 것입니다. 먼저 구조를 정하고, 스타일을 정한 다음, 샘플 슬라이드를 확인하고, 마지막으로 일괄 생성과 자체 검사를 진행합니다.
diff --git a/docs/ko/faq.md b/docs/ko/faq.md
new file mode 100644
index 0000000..5924acd
--- /dev/null
+++ b/docs/ko/faq.md
@@ -0,0 +1,67 @@
+# 자주 묻는 질문
+
+## Q: 생성되는 PPT는 편집할 수 있나요?
+
+아닙니다. Codex PPT는 이미지형 PPT를 생성하며, 각 페이지가 하나의 완성된 슬라이드 이미지입니다. 시각 효과는 더 일관되지만 슬라이드 안의 텍스트, 차트와 도형을 기존 PPT처럼 개별적으로 편집할 수는 없습니다. 생성 후 내용이나 시각 효과를 조정해야 한다면 같은 대화에서 AI에게 특정 페이지를 계속 수정하도록 요청하는 것을 권장합니다.
+
+꼭 필요하지 않다면 편집 가능한 PPT로 변환하지 마세요. Codex 사용량이 충분한 경우에만 고려하세요.
+
+편집 가능한 PPT로 추가 변환해야 한다면 생성 후 [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill)을 사용해 볼 수 있습니다. 다만 `image-to-editable-ppt-skill`은 현재 테스트 버전이며, ChatGPT Plus / Pro 회원이 Codex에서 사용하는 경우만 지원하고 다른 agent는 지원하지 않습니다. 결과가 불안정하다면 이후 업데이트 안내를 기다려 주세요.
+
+주의: 이미지에서 편집 가능한 PPT로 변환하는 skill은 현재 token을 많이 사용하므로 Plus 사용자에게 부담이 큽니다. Pro 사용자는 자유롭게 사용해도 됩니다.
+
+## Q: 다른 agent도 지원하나요?
+
+지원합니다. Codex PPT 자체는 `SKILL.md` 기반 skill이므로 Codex 외에도 Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md`를 지원하는 agent에서 사용할 수 있습니다.
+
+이 skill은 Codex 환경에서 개발 및 테스트되어 Codex와의 호환성이 가장 좋으므로 우선 사용을 권장합니다.
+
+각 agent의 이미지 생성 기능과 도구 인터페이스가 서로 다르다는 점에 유의해야 합니다. Codex에서 사용하지 않는 경우 일반적으로 `gpt-image-2` 또는 서드파티 OpenAI 호환 형식의 이미지 생성 API를 설정해야 합니다. 구체적인 설정 방법은 [설치 및 설정](/ko/installation.md)을 참고하고, 사용 중 AI가 현재 환경에 맞게 설정을 안내하도록 하세요.
+
+## Q: skill을 최신 버전으로 업데이트하려면 어떻게 하나요?
+
+설치 명령을 다시 실행하면 최신 버전으로 덮어쓸 수 있습니다. agent에게 직접 업데이트를 요청한 뒤 agent를 재시작해도 됩니다. API key 설정과 개인 스타일 라이브러리는 모두 skill 설치 디렉터리 외부에 저장되므로 업데이트해도 사라지지 않습니다. 구체적인 명령은 [설치 및 설정](/ko/installation.md)을 참고하세요.
+
+## Q: 첫 샘플 슬라이드는 괜찮았는데 이후 페이지의 품질이 떨어지거나 스타일이 달라지는 이유는 무엇인가요?
+
+보통 “샘플 슬라이드 스타일”이 이후 페이지에 안정적으로 전달되지 않았거나, 이후 페이지 생성 중 프롬프트, 백엔드 또는 하위 agent의 실행 방식이 변경되었기 때문입니다.
+
+정상적인 경우 샘플 슬라이드를 확인한 뒤 후속 페이지는 색상, 글꼴 분위기, 레이아웃 밀도, 일러스트 방식과 이미지 생성 백엔드를 포함한 동일한 시각 언어를 이어받아야 합니다. 후속 페이지가 눈에 띄게 달라진다면 AI에게 다음을 확인하도록 요청할 수 있습니다. 샘플 슬라이드를 각 페이지의 스타일 참고 자료로 전달했는지, 같은 이미지 생성 방식을 기록하고 계속 사용했는지, 하위 agent가 임의로 다른 생성 방식을 선택했는지, 각 페이지의 프롬프트가 지나치게 광범위하지 않은지 확인하세요.
+
+권장 해결 방법은 전체를 다시 만들지 않고 눈에 띄게 달라진 페이지 1~2개를 먼저 선택해 승인된 샘플 슬라이드를 참고하여 다시 생성하는 것입니다. 이때 “샘플 슬라이드와 동일한 시각 스타일, 이미지 생성 백엔드와 레이아웃 밀도를 유지할 것”을 명확히 요청하세요.
+
+## Q: 생성된 PPT가 보기 좋지 않으면 어떻게 하나요?
+
+먼저 `gpt-image-2` 모델로 이미지가 정상적으로 생성되는지 확인하세요. 모델 자체를 사용할 수 없거나 비정상적인 품질의 결과를 반환하거나, 서드파티 API / 프록시 서비스가 `gpt-image-2`를 제대로 지원하지 않으면 생성 품질이 크게 떨어집니다.
+
+모델을 사용할 수 있는지 확인한 뒤 스타일 불일치, 너무 작은 텍스트, 지나치게 빽빽한 페이지, 조화롭지 않은 색상, 주제와 맞지 않는 일러스트 등 구체적인 문제를 AI에게 수정하도록 하세요. 샘플 슬라이드 1장을 먼저 다시 생성하고 만족한 뒤 전체 생성을 계속하는 것을 권장합니다.
+
+## Q: 생성된 슬라이드 이미지가 흐리면 어떻게 하나요?
+
+Codex 회원은 기본적으로 내장 이미지 생성 도구를 사용합니다. 이 도구로 생성한 이미지의 해상도는 비교적 낮으며 현재 수동으로 지정할 수 없습니다. 더 높은 해상도가 필요하다면 `gpt-image-2` API 방식으로 생성해야 합니다. 즉, API key, base URL과 모델명을 설정하는 API/CLI fallback을 사용합니다. 자세한 내용은 [설치 및 설정](/ko/installation.md)을 참고하세요.
+
+API/CLI fallback에서는 스크립트의 기본 해상도가 2K 16:9 가로 화면입니다. 이미지가 여전히 흐리다면, 특히 텍스트가 많은 페이지에서는 AI에게 4K 해상도로 생성하도록 요청할 수 있습니다.
+
+## Q: 개요를 먼저 확인해야 하는 이유는 무엇인가요?
+
+PPT 재작업 비용은 주로 구조 문제에서 발생하기 때문입니다. 페이지 수, 제목, 순서와 각 페이지의 핵심 내용을 먼저 확인하면 모든 이미지 생성 후에야 내용 방향이 잘못되었다는 사실을 발견하는 상황을 피할 수 있습니다.
+
+## Q: 샘플 슬라이드를 먼저 생성해야 하는 이유는 무엇인가요?
+
+샘플 슬라이드는 전체 PPT의 시각적 기준입니다. 샘플 슬라이드를 확인한 뒤 후속 페이지는 동일한 색상, 글꼴 분위기, 밀도와 시각 언어를 이어받을 수 있습니다.
+
+## Q: Codex에서 API key를 설정해야 하나요?
+
+Codex 내장 이미지 생성 도구를 사용할 수 있다면 보통 API key를 설정할 필요가 없습니다. API/CLI fallback을 선택할 때만 `OPENAI_API_KEY`, 선택적 `OPENAI_BASE_URL`과 모델명을 설정해야 합니다.
+
+## Q: 논문 원본 이미지나 아키텍처 다이어그램을 삽입할 수 있나요?
+
+가능합니다. 개요 단계에서 이미지가 들어갈 페이지 번호와 용도를 명확히 하고, 엄격하게 유지해야 하는 입력 자료인지 스타일 참고 자료인지 설명하는 것이 좋습니다. 논문 이미지, 실험 결과 그래프, 스크린샷과 아키텍처 다이어그램은 원본 정보, 레이블, 축, 수치와 화살표 관계를 최대한 보존해야 합니다.
+
+## Q: 특정 페이지의 결과가 좋지 않으면 어떻게 하나요?
+
+해당 페이지만 우선 수정하세요. 텍스트가 너무 작음, 계층이 불분명함, 색상이 어울리지 않음, 이미지가 지나치게 빽빽함 또는 특정 개념의 표현이 부정확함 등 구체적인 문제를 agent에게 알려 주세요.
+
+## Q: 나만의 스타일을 저장할 수 있나요?
+
+가능합니다. 마음에 드는 PPT 스크린샷, PDF 또는 전체 PPT를 agent에게 전달해 분석하게 한 뒤 만족스러운 결과가 나오면 해당 스타일을 개인 스타일 라이브러리(`~/.codex-ppt-skill/references/`)에 저장하도록 요청할 수 있습니다. 스타일 라이브러리는 skill 설치 디렉터리 외부에 저장되므로 skill을 업데이트하거나 다시 설치해도 사라지지 않습니다. 내장 스타일과 이름이 같다면 개인 스타일이 우선합니다. 자세한 내용은 [스타일 및 개인 스타일 라이브러리](/ko/styles.md)를 참고하세요.
diff --git a/docs/ko/installation.md b/docs/ko/installation.md
new file mode 100644
index 0000000..62c545d
--- /dev/null
+++ b/docs/ko/installation.md
@@ -0,0 +1,98 @@
+# 설치 및 설정
+
+## 한 문장으로 설치하기
+
+아래 문장을 Codex에 직접 보내 설치를 맡기는 것을 권장합니다.
+
+```text
+이 codex-ppt skill을 설치해 주세요. 링크: https://github.com/ningzimu/codex-ppt-skill
+```
+
+## Codex 수동 설치
+
+명령줄에서 다음 명령을 실행해 `codex-ppt` skill을 Codex의 전역 skills 디렉터리에 설치합니다.
+
+```bash
+npx -y skills@latest add ningzimu/codex-ppt-skill \
+ --skill codex-ppt \
+ --agent codex \
+ --global
+```
+
+설치 후 Codex를 재시작하면 새 skill이 적용됩니다.
+
+[GitHub Releases](https://github.com/ningzimu/codex-ppt-skill/releases)에서 `codex-ppt-skill-v*.zip`을 다운로드해 압축을 푼 뒤, 그 안의 `codex-ppt` 폴더를 `~/.codex/skills/codex-ppt`에 넣고 Codex를 재시작하는 방법도 있습니다.
+
+이 저장소를 로컬에서 개발하는 경우, 실시간으로 수정 사항을 테스트할 수 있도록 skill 디렉터리를 Codex skills 디렉터리에 심볼릭 링크로 연결할 수 있습니다.
+
+```bash
+mkdir -p ~/.codex/skills
+ln -s /path/to/codex-ppt-skill/skills/codex-ppt ~/.codex/skills/codex-ppt
+```
+
+## OpenClaw 설치
+
+```bash
+openclaw skills install codex-ppt
+```
+
+OpenClaw의 skill allowlist를 사용하는 경우 허용 목록에 `codex-ppt`를 추가해야 합니다.
+
+## Claude Code / Hermes Agent
+
+Claude Code:
+
+```bash
+npx -y skills@latest add ningzimu/codex-ppt-skill \
+ --skill codex-ppt \
+ --agent claude-code \
+ --global
+```
+
+Hermes Agent:
+
+```bash
+npx -y skills@latest add ningzimu/codex-ppt-skill \
+ --skill codex-ppt \
+ --agent hermes-agent \
+ --global
+```
+
+일반적인 대상 디렉터리는 Claude Code의 경우 `~/.claude/skills/codex-ppt`, Hermes Agent의 경우 `~/.hermes/skills/codex-ppt`입니다. 로컬 개발 시에는 복사 대신 심볼릭 링크를 사용할 수도 있습니다.
+
+## skill 업데이트
+
+아래 문장을 사용 중인 agent에게 직접 보내 업데이트를 맡기는 것을 권장합니다.
+
+```text
+codex-ppt skill을 최신 버전으로 업데이트해 주세요. 저장소: https://github.com/ningzimu/codex-ppt-skill
+```
+
+수동으로 업데이트할 때는 위에서 해당 agent에 맞는 설치 명령을 다시 실행하면 설치된 skill이 최신 버전으로 덮어써집니다. 또는 [GitHub Releases](https://github.com/ningzimu/codex-ppt-skill/releases)에서 최신 `codex-ppt-skill-v*.zip`을 다운로드해 압축을 풀고 기존 `codex-ppt` 디렉터리를 교체할 수 있습니다. 업데이트 후 agent를 재시작하면 적용됩니다.
+
+업데이트는 안전합니다. API key 등의 런타임 설정은 `~/.codex-ppt-skill/.env`에, 개인 스타일 라이브러리는 `~/.codex-ppt-skill/references/`에 저장되며 모두 skill 설치 디렉터리 외부에 있습니다. 따라서 skill을 업데이트하거나 다시 설치해도 사라지지 않습니다. 각 버전의 변경 사항은 [Releases 페이지](https://github.com/ningzimu/codex-ppt-skill/releases) 또는 저장소의 `CHANGELOG.md`에서 확인할 수 있습니다.
+
+## 이미지 생성 모델 설정
+
+`gpt-image-2` 모델 사용 권한이 없다면 이 skill을 사용할 수 없습니다. 이 skill은 `gpt-image-2` 이미지 생성 모델에 크게 의존합니다.
+
+## `gpt-image-2` 사용 권한 확인 방법
+
+- ChatGPT Plus 또는 Pro 멤버십을 구독 중이라면 기본적으로 `gpt-image-2` 모델을 사용할 수 있습니다. Codex에는 이미지 생성을 위한 내장 도구가 있습니다.
+- 서드파티 프록시 API로 Codex를 사용하는 경우, 행서체로 시 한 편을 써 달라는 요청처럼 복잡한 중국어 텍스트가 포함된 이미지를 생성하게 해 보세요. 이미지가 정상적으로 생성되는지, 생성된 이미지의 중국어 글꼴에 오류가 없는지 확인하세요. 모두 정상이라면 별도 설정이 필요 없습니다.
+- 위 두 방법 모두 사용할 수 없다면 `gpt-image-2` 모델 사용 권한을 제공하는 프록시 API를 직접 구매해야 합니다.
+
+보통 이미지 생성 모델을 수동으로 설정할 필요는 없습니다. Codex PPT를 사용하는 동안 AI가 이미지 생성 백엔드를 자동으로 감지합니다. 사용할 수 없는 경우 이미지 생성 백엔드 API 설정이 필요하다는 안내와 함께 설정 과정을 도와줍니다.
+
+## 서드파티 API 유의 사항
+
+이 skill에는 OpenAI 공식 이미지 생성 방식을 지원하는 스크립트가 포함되어 있습니다. 서드파티 `gpt-image-2` 프록시 API를 사용하는 경우 다음 정보를 제공해 보세요.
+
+- 프록시 서비스의 base URL
+ - 프록시 서비스에서 제공한 예시가 `https://xxx/v1/images/generations`라면 base URL에는 `https://xxx/v1`을 입력합니다.
+ - 프록시 서비스에서 이미 `https://xxx/v1`을 제공했다면 한 단계를 더 추가하지 마세요. 그렇지 않으면 `.../v1/v1`이 됩니다.
+ - OpenAI 공식 서비스를 사용하는 경우 `OPENAI_BASE_URL`을 입력하지 않아도 됩니다. 기본값은 공식 주소인 `https://api.openai.com/v1`입니다.
+- 프록시 서비스의 API key
+- 프록시 서비스의 구체적인 `gpt-image-2` 모델명
+
+위 정보를 AI에 제공한 뒤 이미지 생성을 시도하세요. 실행되지 않는다면 사용하는 프록시 서비스에 OpenAI 이미지 생성 인터페이스와 완전히 호환되지 않는 자체 이미지 생성 방식이 있을 수 있습니다. 프록시 서비스의 공식 이미지 생성 문서를 AI에 전달해 스크립트를 학습하고 조정하도록 하세요.
diff --git a/docs/ko/prompts.md b/docs/ko/prompts.md
new file mode 100644
index 0000000..b2e231c
--- /dev/null
+++ b/docs/ko/prompts.md
@@ -0,0 +1,45 @@
+# 예시 프롬프트
+
+## 기본 글을 PPT로 변환
+
+```text
+codex-ppt skill을 사용해서 /path/to/article.md를 약 10페이지 분량의 한국어 PPT로 만들어 주세요. 대상 청중은 사내 기술팀입니다.
+```
+
+## 논문을 발표용 PPT로 변환
+
+```text
+codex-ppt skill을 사용해서 이 논문을 12페이지 분량의 한국어 발표용 PPT로 만들어 주세요. 연구 발표 스타일로 제작하고, 연구 배경, 방법, 실험, 결과, 한계와 요약을 포함해 구성하세요. 논문의 모델 아키텍처 다이어그램과 주요 실험 결과 그래프는 해당 페이지에 반드시 유지해야 합니다.
+```
+
+## 시각 스타일 지정
+
+```text
+codex-ppt skill을 사용해 PPT를 생성해 주세요. 시각 스타일은 제가 업로드한 PDF를 참고하세요. 큰 제목, 넓은 여백, 검정·흰색·회색을 기본색으로 하고 소량의 빨간색을 강조색으로 사용해 전체적으로 비즈니스 잡지 특집 페이지처럼 만들어 주세요. 제공한 자료의 각 페이지 이미지를 자세히 읽고 스타일을 충분히 이해한 뒤, 그 스타일을 재현해 생성해 주세요.
+```
+
+## 내장 스타일 지정
+
+```text
+codex-ppt skill을 사용해서 이 자료를 10페이지 PPT로 만들어 주세요. 내장된 「손그림 기술 설명 스타일」을 사용해 손그림 선, 구조화된 도식, 가벼운 주석과 명확한 개념 분해로 내용을 표현하고, 기술 원리 설명과 지식 전달에 적합하게 만들어 주세요.
+```
+
+스타일 이름을 「깔끔한 전문 스타일」, 「연구 발표 스타일」, 「데이터 대시보드 스타일」, 「전자 잉크 매거진 스타일」, 「창의적 매거진 스타일」 등 다른 내장 스타일로 바꿀 수도 있습니다.
+
+## 페이지 수와 이미지 지정
+
+```text
+codex-ppt skill을 사용해서 이 자료를 15페이지 PPT로 만들어 주세요. 4페이지에는 architecture.png를, 9페이지에는 benchmark-results.png를 사용하세요.
+```
+
+## 개별 슬라이드 수정
+
+```text
+6페이지의 정보가 너무 빽빽하고 제목이 명확하지 않습니다. 전체 PPT의 스타일은 유지하면서 6페이지만 다시 생성하고, 내용을 더 명확한 세 부분 구조로 나누어 주세요.
+```
+
+## 개인 스타일 라이브러리에 스타일 저장
+
+```text
+이 PPT의 시각 스타일이 마음에 듭니다. 나중에 재사용할 수 있도록 codex-ppt의 개인 스타일 라이브러리에 저장해 주세요. 설명에는 색상, 글꼴 분위기, 레이아웃 규칙, 일러스트/차트 스타일과 적합한 활용 사례를 포함하세요.
+```
diff --git a/docs/ko/quickstart.md b/docs/ko/quickstart.md
new file mode 100644
index 0000000..0a3228e
--- /dev/null
+++ b/docs/ko/quickstart.md
@@ -0,0 +1,35 @@
+# 빠른 시작
+
+## 대상 독자
+
+이 페이지는 Codex PPT를 처음 사용하는 분을 위한 안내입니다. 글, 보고서, 개요, 논문 또는 수업 노트를 준비한 뒤 agent에게 `codex-ppt` skill로 PPT를 생성해 달라고 요청하면 됩니다.
+
+## 가장 간단한 사용 방법
+
+먼저 skill을 설치하세요. 자세한 내용은 [설치 및 설정](/ko/installation.md)을 참고하세요. 그런 다음 Codex에서 이 skill을 사용해 바로 PPT를 만들 수 있습니다.
+
+```text
+codex-ppt skill을 사용해서 /path/to/article.md를 약 10페이지 분량의 한국어 PPT로 만들어 주세요.
+```
+
+원하는 스타일과 용도를 이미 알고 있다면 더 구체적으로 작성할 수 있습니다.
+
+```text
+codex-ppt skill을 사용해서 이 기술 문서를 12페이지 분량의 한국어 발표용 PPT로 만들어 주세요. 사내 기술 공유에 어울리는 깔끔하고 전문적인 스타일로 제작하고, 5페이지에는 제가 제공한 아키텍처 다이어그램을 반드시 사용하며, 8페이지에는 실험 결과 그래프를 반드시 유지해 주세요.
+```
+
+## 처음 사용할 때의 권장 사항
+
+- 먼저 agent가 `outline.md`를 생성하도록 하고, 페이지 수, 제목과 각 페이지의 핵심 내용을 확인하세요.
+- 샘플 슬라이드 확인을 건너뛰지 마세요. 한 페이지의 결과를 먼저 확인한 뒤 전체 PPT를 일괄 생성하세요.
+- 특정 페이지가 마음에 들지 않으면 전체를 다시 만들기보다 해당 페이지만 우선 수정하세요.
+- 참고할 PPT, 스크린샷 또는 PDF가 있다면 먼저 agent가 스타일을 분석한 뒤 새 PPT를 생성하도록 하세요.
+
+## 생성 결과
+
+최종적으로 보통 다음 파일을 받게 됩니다.
+
+- `outline.md`: PPT 개요
+- `origin_image/slide_XX.png`: 각 슬라이드의 최종 이미지
+- `speech.md`: 각 슬라이드의 발표 메모
+- `{PPT名称}.pptx`: 최종 PowerPoint 파일
diff --git a/docs/ko/styles.md b/docs/ko/styles.md
new file mode 100644
index 0000000..a6085d9
--- /dev/null
+++ b/docs/ko/styles.md
@@ -0,0 +1,59 @@
+# 스타일 및 개인 스타일 라이브러리
+
+Codex PPT의 시각 스타일은 두 곳에서 가져옵니다. skill과 함께 배포되는 **내장 스타일**과, 로컬 컴퓨터에 저장되어 skill을 업데이트해도 사라지지 않는 **개인 스타일 라이브러리**입니다.
+
+## 내장 스타일
+
+skill에는 12가지 참고 스타일이 내장되어 있어 프롬프트를 잘 작성하지 못해도 바로 시작할 수 있습니다. PPT를 만들 때 다음 예시처럼 스타일 이름을 직접 말하면 됩니다.
+
+```text
+codex-ppt skill을 사용해서 이 자료를 10페이지 PPT로 만들고, 내장된 「손그림 기술 설명 스타일」을 사용해 주세요.
+```
+
+| 깔끔한 전문 스타일 | 창의적 매거진 스타일 |
+| --- | --- |
+|  |  |
+| 전자 잉크 매거진 스타일 | 데이터 대시보드 스타일 |
+|  |  |
+| 복고풍 플랫 일러스트 스타일 | 손그림 기술 설명 스타일 |
+|  |  |
+| 손그림 화이트보드 스타일 | 따뜻한 핸드메이드 스타일 |
+|  |  |
+| 연구 발표 스타일 | McKinsey 스타일 |
+|  |  |
+| 당·정 홍보용 레드 스타일 | 교육용 코스웨어 스타일 |
+|  |  |
+
+스타일은 색상, 글꼴의 분위기, 레이아웃 밀도와 일러스트 언어로 이루어진 하나의 시각 시스템이지, 고정된 템플릿이 아닙니다. 같은 스타일에서도 각 페이지의 레이아웃은 콘텐츠 역할에 따라 달라지므로 모든 페이지가 똑같아 보이지 않습니다.
+
+## 참고 자료의 스타일 재현
+
+내장 스타일로 요구 사항을 충족할 수 없다면 마음에 드는 스타일 참고 자료를 제공할 수 있습니다. 스크린샷 한 장이나 여러 장, 또는 전체 PPT/PDF도 가능합니다. 먼저 agent가 참고 자료의 색상, 레이아웃, 글꼴과 시각 요소를 분석한 뒤 해당 스타일로 새 PPT를 생성하도록 하는 것을 권장합니다.
+
+```text
+codex-ppt skill을 사용해 PPT를 생성해 주세요. 시각 스타일은 제가 업로드한 PDF를 참고하세요. 제공한 자료의 각 페이지 이미지를 자세히 읽고 스타일을 충분히 이해한 뒤, 그 스타일을 재현해 생성해 주세요.
+```
+
+주의: 기본적으로 스타일만 재현하고 내용은 재사용하지 않습니다. 명시적으로 요청하지 않는 한 참고 자료의 텍스트와 데이터는 새 PPT에 옮겨지지 않습니다.
+
+## 개인 스타일 라이브러리
+
+생성된 PPT의 스타일이 마음에 든다면 조정한 사용자 지정 스타일이든 참고 자료에서 재현한 스타일이든 agent에게 저장하도록 요청해 나중에 바로 재사용할 수 있습니다.
+
+```text
+이 PPT의 시각 스타일이 마음에 듭니다. 개인 스타일 라이브러리에 저장해 주세요.
+```
+
+저장 방식의 주요 특징은 다음과 같습니다.
+
+- **저장 위치**: 개인 스타일 라이브러리는 `~/.codex-ppt-skill/references/`에 있습니다(`CODEX_PPT_HOME` 환경 변수로 위치 변경 가능). skill 설치 디렉터리 **외부**에 있으므로 skill을 업데이트하거나 다시 설치해도 개인 스타일을 덮어쓰거나 잃지 않습니다.
+- **자동 검색**: 저장 후 별도로 등록할 필요가 없습니다. 다음에 PPT 스타일을 선택할 때 agent가 개인 스타일 라이브러리를 자동으로 검색해 내장 스타일과 함께 표시합니다.
+- **같은 이름 우선 적용**: 개인 스타일이 내장 스타일과 같은 이름이면 개인 스타일이 우선합니다. 이 기능을 이용해 내장 스타일을 사용자화할 수도 있습니다. 같은 이름으로 조정된 버전을 저장하면 기본 효과를 덮어씁니다.
+- **재사용 방법**: 이후에는 스타일 이름을 직접 말하면 됩니다. 예: “『다크 데이터 테크 스타일』로 이 PPT를 생성해 주세요.”
+
+생성이 끝난 뒤 이 deck이 사용자 지정 또는 조정된 스타일을 사용했다면 agent도 최종 보고에서 스타일을 저장할 수 있다고 안내합니다. 수정하지 않은 내장 스타일은 다시 저장할 필요가 없습니다.
+
+## 관련 문서
+
+- [예시 프롬프트](/ko/prompts.md): 내장 스타일 지정, 참고 스타일 재현, 스타일 저장을 위한 전체 프롬프트.
+- [자주 묻는 질문](/ko/faq.md): 스타일이 달라지거나 페이지가 마음에 들지 않을 때의 처리 방법.
diff --git a/docs/ko/workflow.md b/docs/ko/workflow.md
new file mode 100644
index 0000000..1fbbf34
--- /dev/null
+++ b/docs/ko/workflow.md
@@ -0,0 +1,69 @@
+# 표준 워크플로
+
+## 개요
+
+Codex PPT의 워크플로는 단계별 확인을 중요하게 생각합니다. 처음부터 전체 PPT를 바로 생성하지 않고 개요, 스타일, 이미지 백엔드와 샘플 슬라이드를 먼저 확인해 재작업 비용을 줄입니다.
+
+## 단계 1: 입력 자료 읽기
+
+agent는 먼저 다음 내용을 파악합니다.
+
+- 주제와 핵심 관점
+- 대상 청중
+- 발표 목적
+- 페이지 수 요구 사항
+- 반드시 포함하거나 제외해야 하는 내용
+- 필수 이미지 자료의 유무
+
+## 단계 2: 개요 확인
+
+agent가 `outline.md`를 생성하며, 일반적으로 다음 내용을 포함합니다.
+
+- Slide 번호
+- 각 페이지의 제목
+- 핵심 내용 3~5개
+- 표지, 목차, 개념 설명, 흐름, 비교, 데이터 근거, 요약 등의 페이지 역할
+- 선택적 시각 아이디어
+- 필수 이미지 자료와 용도
+
+개요를 확인하기 전에는 최종 slide 이미지, `speech.md` 또는 `.pptx`를 생성하지 않아야 합니다.
+
+## 단계 3: 시각 스타일 확인
+
+agent가 2~3가지 스타일 방향을 제안하고 하나를 추천합니다. 후보 스타일은 12가지 내장 스타일(깔끔한 전문 스타일, 연구 발표 스타일, 손그림 기술 설명 스타일, McKinsey 스타일, 당·정 홍보용 레드 스타일, 교육용 코스웨어 스타일 등)과 개인 스타일 라이브러리에서 가져옵니다. 사용자가 제공한 스크린샷, PDF 또는 PPT를 바탕으로 스타일을 재현할 수도 있습니다. 전체 스타일 미리보기는 [스타일 및 개인 스타일 라이브러리](/ko/styles.md)를 참고하세요.
+
+스타일을 선택한 뒤에는 전체 PPT가 일관된 시각 언어를 유지해야 하지만, 각 슬라이드의 레이아웃은 내용에 따라 달라질 수 있습니다.
+
+## 단계 4: 이미지 생성 백엔드 확인
+
+Codex 내장 이미지 생성 도구를 우선 사용합니다. 내장 도구를 사용할 수 없거나, 사용자가 API/CLI fallback을 명시적으로 요청하거나, 현재 기능으로 요구 사항을 충족할 수 없는 경우에만 `scripts/image_gen.py`로 전환합니다.
+
+이미지 백엔드를 확인한 뒤에는 전체 PPT에서 일관되게 유지하고 중간에 바꾸지 않아야 합니다.
+
+## 단계 5: 샘플 슬라이드 생성 및 확인
+
+먼저 샘플 슬라이드 1장을 생성해 다음을 확인합니다.
+
+- 텍스트가 선명한지
+- 스타일이 기대와 맞는지
+- 페이지 밀도가 적절한지
+- 색상과 레이아웃이 안정적인지
+- 전체 PPT로 일괄 확장하기에 적합한지
+
+샘플 슬라이드가 승인된 뒤 전체를 일괄 생성합니다.
+
+## 단계 6: 일괄 생성
+
+샘플 슬라이드 확인 후 agent는 각 페이지의 `origin_image/slide_XX.png`를 생성합니다. 하위 agent를 지원하는 환경에서는 각 하위 agent가 한 페이지씩 병렬로 생성해 여러 페이지의 제작 속도를 높입니다. 모든 페이지는 승인된 샘플 슬라이드와 동일한 스타일 및 이미지 생성 백엔드를 사용합니다.
+
+## 단계 7: 품질 검사 및 수정
+
+조립하기 전에 agent는 각 페이지의 텍스트 선명도, 개요와의 일치 여부, 내용 잘림, 스타일 일관성, 불필요한 페이지 번호와 요소 겹침 등을 검사합니다. 심각한 문제가 발견된 페이지는 더 엄격한 프롬프트로 다시 생성하고, 작은 국소 문제는 이미지 편집 기능으로 우선 수정합니다.
+
+## 단계 8: 발표 대본 및 조립
+
+`speech.md` 발표 대본을 생성한 뒤 `assemble_ppt.py`를 사용해 `.pptx`로 조립합니다. 발표 대본은 각 PPT 슬라이드의 메모 영역에 자동으로 입력됩니다.
+
+## 단계 9(선택): 스타일 저장
+
+이 PPT가 사용자 지정 또는 조정된 스타일을 사용한 경우, agent는 최종 보고에서 해당 스타일을 개인 스타일 라이브러리에 저장해 이후 이름으로 바로 재사용할 수 있다고 안내합니다. 자세한 내용은 [스타일 및 개인 스타일 라이브러리](/ko/styles.md)를 참고하세요.