Rewrite README docs for user-facing usage

README.md

@@ -2,69 +2,65 @@
 
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
-A skill that helps turn `docker run` commands and Docker Compose setups into Podman Quadlet files you can review, adjust, and apply.
+Quadlet Migrator is a skill for converting Docker-based deployment input into Podman Quadlet output.
 
-## What it does
+## What It Does
 
-- converts `docker run` commands and Docker Compose setups into Podman Quadlet files
+- converts `docker run` commands into Quadlet units
-- writes the generated files to the current directory first so you can review them before installing them
+- converts Docker Compose setups into Quadlet deployments
-- asks about the output location only when you already requested another location or existing files would conflict
+- analyzes self-hosting deployment files in GitHub repositories
-- helps choose between `.container`, `.pod`, `.network`, `.volume`, and `.build`, usually preferring a pod for related multi-container services
+- keeps env files, mounted config, initialization assets, and helper scripts when they are part of the deployment
-- avoids adding explicit runtime naming directives such as `PodName=`, `ServiceName=`, `ContainerName=`, and `NetworkName=` by default unless the user asks for them or a reviewed requirement depends on them
+- turns large env templates into a short list of deployment decisions
-- avoids adding `User=`, `Group=`, or `UserNS=keep-id` by default unless the source explicitly requires them or the user is working through permission or ownership behavior
+- provides deployment, validation, and troubleshooting guidance
-- keeps `.env` / `env_file` workflows when they still fit the deployment
-- turns large env templates into a short list of decisions the user actually needs to make
-- can generate helper scripts such as `install.sh`, `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh`
-- finds files from the current project that the service still needs when it runs, such as mounted config, setup data, and helper scripts
-- checks that env files are complete before calling the result runnable
-- asks the user to confirm important deployment choices during planning, then uses clear review and execution checklists
-- can optionally plan `AutoUpdate=registry` when the chosen image uses a complete image name that includes the registry, such as `docker.io/...` or `ghcr.io/...`
-- explains rootless vs rootful install paths, deployment notes, and validation steps
 
-## Design principles
+## When To Use It
 
-- use the simplest mode that fits the request
+Use this skill when you want to:
-- keep planning, review, and file generation as separate steps
-- do not invent deployment-specific values
-- call out behavior changes when a mapping is lossy
-- prefer output that is easy to understand and maintain
-- write files to the current directory for review before installation
-- prefer pod-based grouping when it is the clearest fit for a multi-container service
-- let Quadlet and Podman derive runtime names unless reviewed requirements justify explicit naming fields
-- avoid runtime identity-mapping fields unless they are actually needed for the reviewed deployment
-- keep required extra files in the reviewed output and point to them with absolute paths on the host machine instead of copying them into the Quadlet unit directory
 
-## Operating modes
+- move a service from Docker to Podman Quadlet
+- convert a Compose stack into a Quadlet layout
+- review a repository's self-hosting deployment files
+- generate files for review before installation
+- validate or troubleshoot generated Quadlet files
 
-- `advice`: explain the mapping, review source inputs, or answer targeted questions without writing final files
+## How To Use It
-- `design`: do planning and a final interactive review, then stop before generating runnable files
-- `generate`: do planning, the final interactive review, and execution, then generate the approved runnable files
 
-## Workflow
+1. Give it an input:
+   - a `docker run` command
+   - a Compose file or Compose project
+   - a GitHub repository URL
+   - existing Quadlet files that need review or cleanup
+2. Say what you want:
+   - mapping advice
+   - a deployment design
+   - reviewable runnable output
+3. Confirm deployment-specific values such as domains, host paths, credentials, storage choices, or optional services.
+4. Review the generated output before applying it.
 
-The workflow has three phases: `Planning`, `Finalize`, and `Execution`.
+## Example Requests
 
-- `advice` usually stays in `Planning` or answers a focused question directly
+```text
-- `design` includes `Planning` and `Finalize`
+Convert this docker run command into Quadlet and explain the mapping.
-- `generate` includes all three phases
 
-Planning is where unresolved deployment decisions are gathered and confirmed with the user.
+Review this compose.yaml and propose a Podman Quadlet layout.
-Finalize is a review step in the conversation after those decisions have been discussed.
-Execution starts only after the user approves that review.
 
-## References
+Generate reviewable Quadlet files from this repository's self-hosting deployment.
 
-- `SKILL.md` contains the operating modes, workflow, and high-level rules
+Help me migrate this stack to rootless Podman and keep the env-file workflow.
-- `references/compose-mapping.md` covers field mapping and topology decisions
+```
-- `references/env-strategy.md` covers env handling, completeness validation, and typo detection
-- `references/github-repo-intake.md` covers how the skill finds the right repository entry point
-- `references/deployment-notes.md` covers deployment guidance
-- `references/validation.md` covers validation and troubleshooting
-- `references/template/` contains simple helper-script templates for stable prefix-based Quadlet file handling and lifecycle management
 
-## Limitations
+## Typical Output
 
-This skill does not claim perfect equivalence between Docker Compose semantics and Podman Quadlet semantics.
+- Quadlet unit files
+- env files or env deltas
+- helper scripts for install, reload, start, stop, restart, and uninstall
+- deployment notes and validation guidance
+
+## Notes
+
+- Review generated output before installation.
+- Confirm deployment-specific values instead of guessing them.
+- Call out behavior changes when Docker Compose and Quadlet do not map cleanly.
 
 ## License
 

README.zh-CN.md

@@ -2,69 +2,65 @@
 
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
-一个 skill，用来把 `docker run` 命令和 Docker Compose 配置转换成可审阅、可调整、可应用的 Podman Quadlet 文件。
+Quadlet Migrator 是一个把 Docker 部署输入转换为 Podman Quadlet 输出的 skill。
 
-## 功能概览
+## 功能
 
-- 将 `docker run` 命令和 Docker Compose 配置转换成 Podman Quadlet 文件
+- 将 `docker run` 命令转换为 Quadlet 单元文件
-- 默认先把生成文件写到当前目录，方便你在安装前先审阅
+- 将 Docker Compose 配置转换为 Quadlet 部署结果
-- 只有在你已经指定其他位置，或现有文件会发生冲突时，才询问输出位置
+- 分析 GitHub 仓库中的自托管部署文件
-- 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择；对有关联的多容器服务，通常优先用 pod
+- 在部署需要时保留 env 文件、挂载配置、初始化资产和辅助脚本
-- 默认不添加 `PodName=`、`ServiceName=`、`ContainerName=`、`NetworkName=` 这类显式运行时命名字段，除非用户要求或审阅后的需求确实依赖它们
+- 将庞杂的 env 模板整理成少量部署决策
-- 默认不添加 `User=`、`Group=`、`UserNS=keep-id`，除非源配置明确要求，或用户正在处理权限 / 属主相关行为
+- 提供部署、验证和排障指引
-- 在合适时保留 `.env` / `env_file` 工作流
-- 把庞杂的 env 模板收敛成用户真正需要确认的少量问题
-- 可生成辅助脚本，例如 `install.sh`、`uninstall.sh`、`reload.sh`、`start.sh`、`stop.sh`、`restart.sh`
-- 识别服务运行时仍需要的项目内文件，例如挂载配置、初始化数据和辅助脚本
-- 在声称结果可运行前，检查 env 文件是否完整
-- 在 planning 阶段先确认关键部署决策，并在审阅和执行阶段使用清晰的检查清单
-- 当所选镜像使用包含仓库地址的完整镜像名时，例如 `docker.io/...` 或 `ghcr.io/...`，可选规划 `AutoUpdate=registry`
-- 说明 rootless / rootful 安装路径、部署说明和验证步骤
 
-## 设计原则
+## 适用场景
 
-- 用能满足需求的最简单模式
+适合在这些场景中使用：
-- 将 planning、审阅、生成文件分成独立步骤
-- 不虚构部署相关取值
-- 如果映射会带来行为变化，要明确说出来
-- 优先产出容易理解、容易维护的结果
-- 先把文件写到当前目录审阅，再决定是否安装
-- 对多容器服务，如果用 pod 更清晰，就优先用 pod
-- 默认让 Quadlet 和 Podman 自行派生运行时名称，只有在审阅后确认确有必要时才显式命名
-- 默认避免引入运行时身份映射字段，只有在当前部署确实需要时才添加
-- 运行仍需要的额外文件保留在已审阅的输出中，并通过主机上的绝对路径引用，而不是复制进 Quadlet 单元目录
 
-## 运行模式
+- 将服务从 Docker 迁移到 Podman Quadlet
+- 将 Compose 栈转换为 Quadlet 布局
+- 审查仓库中的自托管部署文件
+- 先生成文件审阅，再决定是否安装
+- 验证或排查生成后的 Quadlet 文件
 
-- `advice`：解释映射方式、审查输入，或回答定向问题，不写最终文件
+## 使用方式
-- `design`：执行 planning 和最后一轮交互式审阅，但在生成可运行文件前停止
-- `generate`：执行 planning、最后一轮交互式审阅和 execution，然后生成已批准的可运行文件
 
-## 工作流
+1. 提供一种输入：
+   - 一条 `docker run` 命令
+   - 一个 Compose 文件或 Compose 项目
+   - 一个 GitHub 仓库 URL
+   - 一组需要审查或清理的现有 Quadlet 文件
+2. 说明你的目标：
+   - 映射建议
+   - 部署设计
+   - 可审阅的可运行结果
+3. 确认域名、主机路径、凭据、存储方案或可选服务等部署取值。
+4. 在应用前审阅生成结果。
 
-工作流分为三个阶段：`Planning`、`Finalize`、`Execution`。
+## 示例请求
 
-- `advice` 通常停留在 `Planning`，或直接回答一个聚焦的问题
+```text
-- `design` 包含 `Planning` 和 `Finalize`
+把这条 docker run 命令转换成 Quadlet，并解释映射关系。
-- `generate` 包含全部三个阶段
 
-Planning 用来收集并确认仍未决定的部署问题。
+审查这个 compose.yaml，并给出一个 Podman Quadlet 布局方案。
-Finalize 是在这些问题讨论清楚之后进行的对话式审阅。
-只有在用户批准这次审阅后，才进入 Execution。
 
-## 文档说明
+根据这个仓库的自托管部署生成可审阅的 Quadlet 文件。
 
-- `SKILL.md`：运行模式、工作流和高层规则
+帮我把这套服务迁移到 rootless Podman，并保留 env-file 工作流。
-- `references/compose-mapping.md`：Compose 字段映射与拓扑决策
+```
-- `references/env-strategy.md`：env 处理、完整性校验与 typo 检测
-- `references/github-repo-intake.md`：说明 skill 如何找到正确的仓库入口
-- `references/deployment-notes.md`：部署说明
-- `references/validation.md`：验证与排障
-- `references/template/`：用于稳定处理 Quadlet 文件与 lifecycle 管理的简洁 helper script 模板目录
 
-## 限制
+## 常见产物
 
-本 skill 不保证 Docker Compose 语义与 Podman Quadlet 语义完全等价。
+- Quadlet 单元文件
+- env 文件或 env 增量文件
+- 用于 install、reload、start、stop、restart、uninstall 的辅助脚本
+- 部署说明与验证指引
+
+## 说明
+
+- 在安装前审阅生成结果。
+- 对部署相关取值先确认，再生成结果。
+- Docker Compose 与 Quadlet 不完全等价时，要明确说明行为变化。
 
 ## 许可证