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
-- writes the generated files to the current directory first so you can review them before installing them
-- asks about the output location only when you already requested another location or existing files would conflict
-- helps choose between `.container`, `.pod`, `.network`, `.volume`, and `.build`, usually preferring a pod for related multi-container services
-- 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
-- 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
-- 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
+- converts `docker run` commands into Quadlet units
+- converts Docker Compose setups into Quadlet deployments
+- analyzes self-hosting deployment files in GitHub repositories
+- keeps env files, mounted config, initialization assets, and helper scripts when they are part of the deployment
+- turns large env templates into a short list of deployment decisions
+- provides deployment, validation, and troubleshooting guidance
 
-## Design principles
+## When To Use It
 
-- use the simplest mode that fits the request
-- 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
+Use this skill when you want to:
 
-## 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
-- `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
+## How To Use It
 
-## 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
-- `design` includes `Planning` and `Finalize`
-- `generate` includes all three phases
+```text
+Convert this docker run command into Quadlet and explain the mapping.
 
-Planning is where unresolved deployment decisions are gathered and confirmed with the user.
-Finalize is a review step in the conversation after those decisions have been discussed.
-Execution starts only after the user approves that review.
+Review this compose.yaml and propose a Podman Quadlet layout.
 
-## References
+Generate reviewable Quadlet files from this repository's self-hosting deployment.
 
-- `SKILL.md` contains the operating modes, workflow, and high-level rules
-- `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
+Help me migrate this stack to rootless Podman and keep the env-file workflow.
+```
 
-## 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