Clarify README wording and Quadlet reference rules.

Rewrite the README in plainer language and document podman-systemd.unit.5.md as the gold standard when Quadlet-specific behavior is unclear.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -2,44 +2,58 @@
 
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
-A skill for migrating `docker run` commands and Docker Compose-style deployments into maintainable Podman Quadlet units.
+A skill that helps turn `docker run` commands and Docker Compose setups into Podman Quadlet files you can review, adjust, and apply.
 
 ## What it does
 
-- translates `docker run` and Compose-style inputs into Quadlet-oriented designs
-- writes generated artifacts to the current directory by default so they can be reviewed before being applied
-- helps decide between `.container`, `.pod`, `.network`, `.volume`, and `.build`, with a pod-first bias for multi-container services
-- preserves `.env` / `env_file` workflows when appropriate
-- reduces large env templates into a small set of high-impact deployment questions
-- can generate helper scripts with `install.sh` as the canonical apply step, plus `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh`
-- identifies required repo-local support files such as mounted config, init assets, and helper scripts that must ship with the result
-- validates env completeness before claiming runnable output
-- encourages explicit finalize and execution checklists for support files and env completeness
-- explains rootless vs rootful apply targets, deployment notes, and validation steps
+- 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
+- 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
 
-- prefer the lightest operating mode that matches the request
-- separate planning, review, and generation into explicit phases
+- use the simplest mode that fits the request
+- keep planning, review, and file generation as separate steps
 - do not invent deployment-specific values
-- make lossy mappings explicit
-- prefer maintainable output over mechanical one-to-one translation
-- default to review-first output in the current directory before installation
-- prefer pod-first topology over preserving bridge networking when pod grouping expresses the intent cleanly
-- ensure runtime-required support files remain in the reviewed current-directory deliverable set and are referenced from Quadlet via absolute host paths, rather than being copied by `install.sh` into the Quadlet unit directory
+- 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
+- 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
 
-- `advice`: explain mappings or review source inputs without writing final artifacts
-- `design`: perform planning and finalize review, then stop before runnable artifact generation
-- `generate`: produce approved runnable artifacts after planning and finalize review
+- `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
+
+## Workflow
+
+The workflow has three phases: `Planning`, `Finalize`, and `Execution`.
+
+- `advice` usually stays in `Planning` or answers a focused question directly
+- `design` includes `Planning` and `Finalize`
+- `generate` includes all three phases
+
+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.
 
 ## References
 
 - `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 repository discovery and canonical input selection
+- `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
 

README.zh-CN.md

@@ -2,44 +2,58 @@
 
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
-一个 skill，用来将 `docker run` 命令和 Docker Compose 风格部署迁移为可维护的 Podman Quadlet 单元。
+一个 skill，用来把 `docker run` 命令和 Docker Compose 配置转换成可审阅、可调整、可应用的 Podman Quadlet 文件。
 
 ## 功能概览
 
-- 将 `docker run` 和 Compose 风格输入转换为面向 Quadlet 的设计
-- 默认先把生成产物写到当前目录，便于审查后再应用
-- 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择，并对多容器服务默认偏向 pod-first 拓扑
+- 将 `docker run` 命令和 Docker Compose 配置转换成 Podman Quadlet 文件
+- 默认先把生成文件写到当前目录，方便你在安装前先审阅
+- 只有在你已经指定其他位置，或现有文件会发生冲突时，才询问输出位置
+- 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择；对有关联的多容器服务，通常优先用 pod
 - 在合适时保留 `.env` / `env_file` 工作流
-- 将大型 env 模板归纳为少量高影响部署问题
-- 可生成辅助脚本，其中 `install.sh` 是规范的 apply 步骤，另可生成 `uninstall.sh`、`reload.sh`、`start.sh`、`stop.sh`、`restart.sh`
-- 会识别并交付运行所需的 repo 内配套文件，例如挂载配置、初始化资源和辅助脚本
-- 在声称结果可运行前，会检查环境变量完整性，而不是只做 env 摘要
-- 鼓励在 finalize 与 execution 阶段显式使用 support files 与 env completeness 检查清单
-- 说明 rootless / rootful 应用目标路径、部署说明与验证步骤
+- 把庞杂的 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-first 拓扑而不是保留 bridge 网络
-- 将运行必需文件复制到各自正确的主机路径，而不只是复制到 Quadlet 单元目录
+- 如果映射会带来行为变化，要明确说出来
+- 优先产出容易理解、容易维护的结果
+- 先把文件写到当前目录审阅，再决定是否安装
+- 对多容器服务，如果用 pod 更清晰，就优先用 pod
+- 运行仍需要的额外文件保留在已审阅的输出中，并通过主机上的绝对路径引用，而不是复制进 Quadlet 单元目录
 
 ## 运行模式
 
-- `advice`：解释映射方式或审查输入，不写最终产物
-- `design`：执行 planning 和 finalize 审阅，但在生成可运行产物前停止
-- `generate`：在 planning 和 finalize 审阅通过后，生成已批准的可运行产物
+- `advice`：解释映射方式、审查输入，或回答定向问题，不写最终文件
+- `design`：执行 planning 和最后一轮交互式审阅，但在生成可运行文件前停止
+- `generate`：执行 planning、最后一轮交互式审阅和 execution，然后生成已批准的可运行文件
+
+## 工作流
+
+工作流分为三个阶段：`Planning`、`Finalize`、`Execution`。
+
+- `advice` 通常停留在 `Planning`，或直接回答一个聚焦的问题
+- `design` 包含 `Planning` 和 `Finalize`
+- `generate` 包含全部三个阶段
+
+Planning 用来收集并确认仍未决定的部署问题。
+Finalize 是在这些问题讨论清楚之后进行的对话式审阅。
+只有在用户批准这次审阅后，才进入 Execution。
 
 ## 文档说明
 
 - `SKILL.md`：运行模式、工作流和高层规则
 - `references/compose-mapping.md`：Compose 字段映射与拓扑决策
 - `references/env-strategy.md`：env 处理、完整性校验与 typo 检测
-- `references/github-repo-intake.md`：仓库发现与 canonical 输入选择
+- `references/github-repo-intake.md`：说明 skill 如何找到正确的仓库入口
 - `references/deployment-notes.md`：部署说明
 - `references/validation.md`：验证与排障
 

SKILL.md

@@ -17,7 +17,7 @@ This skill helps you:
 - translate `docker run` flags and Compose service fields into Quadlet units
 - choose between `.container`, `.pod`, `.network`, `.volume`, and `.build`, with a pod-first bias for multi-container services
 - decide whether values belong in `Environment=` or `EnvironmentFile=`
-- write reviewable output to the current directory by default before the user applies it to a live Quadlet search path
+- write reviewable output to the current directory by default, unless the user requested another output directory or an existing-file conflict requires a decision before writing
 - generate helper scripts with `install.sh` as the canonical apply script name, plus `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` when producing runnable artifacts
 - identify required repo-local companion files such as config files, templates, seed data, or initialization assets that must be shipped alongside Quadlet output for the deployment to run correctly
 - validate env completeness before claiming runnable output, including missing required keys and suspicious env-key mismatches
@@ -30,8 +30,8 @@ This skill helps you:
 Choose the lightest mode that satisfies the user's request.
 
 - `advice`: explain mappings, review source inputs, answer targeted migration questions, or sketch a recommended structure without writing final artifacts
-- `design`: perform `Planning` and `Finalize`, produce `QUADLET-FINALIZE.md`, but stop before writing runnable artifacts
-- `generate`: perform `Planning`, `Finalize`, and `Execution`, then write the approved runnable artifacts
+- `design`: perform `Planning` and interactive `Finalize` review, then stop before writing runnable artifacts
+- `generate`: perform `Planning`, interactive `Finalize` review, and `Execution`, then write the approved runnable artifacts
 
 Do not force `generate` mode when the user only wants explanation, review, or a partial conversion.
 
@@ -90,6 +90,9 @@ Tasks in this phase:
    - volume mode selection: named volume, bind mount, or anonymous volume
    - rootless vs rootful deployment mode
    - whether secrets should stay in env files or be moved elsewhere
+   - whether to opt into `AutoUpdate=registry` when the approved image strategy uses fully qualified registry images and the user wants runnable output
+   - whether a user-requested non-default output directory should override the current-directory default
+   - how to resolve any existing-file conflicts in the chosen output directory before writing runnable artifacts
 
 Do not silently invent deployment-specific values. If the repository or compose file provides placeholders, defaults, or examples, read the surrounding documentation and comments yourself, infer the intended meaning, and only ask the user to confirm the values that materially affect deployment.
 
@@ -98,21 +101,22 @@ Do not assume runnable output is complete when Quadlet files exist but required
 
 When many variables exist, do not hand the raw `.env.example` back to the user for manual review. Your job is to digest it, reduce it, and produce a concise checklist of high-impact decisions. Prioritize the variables that are required to produce a safe and runnable output.
 
-At the end of planning, summarize what you learned and what you intend to generate, then explicitly ask the user whether anything should be changed or added before you move to the next phase.
+At the end of planning, summarize what you learned, state the proposed output location, state whether `AutoUpdate=registry` is in scope, and explicitly ask the user whether anything should be changed or added before you move to finalize review.
 
 Planning is also the phase where you must actively ask the user for the unresolved high-impact decisions you identified.
+If the approved runnable path would use fully qualified registry image references, ask before finalize whether the user wants to opt into `AutoUpdate=registry`.
+If the image strategy does not yield a fully qualified registry image reference, do not force or imply that `AutoUpdate=registry` is available.
+If the user did not request a different output directory, treat the current working directory as the default deliverable location and say so explicitly during planning instead of asking an unnecessary directory question.
+If the user already requested another output directory, honor that request unless it conflicts with a higher-priority source of truth.
+If files that would be written already exist in the chosen output directory, stop before writing and ask the user whether to overwrite, update selectively, or choose a different location.
 
-Do not defer first-time decision gathering into `QUADLET-FINALIZE.md`.
+Do not defer first-time decision gathering into finalize review.
 
-If decisions are still unresolved, stop in planning and ask the user directly. Do not write `QUADLET-FINALIZE.md` yet.
+If decisions are still unresolved, stop in planning and ask the user directly. Do not enter finalize review yet.
 
 ### Finalize phase
 
-Goal: consolidate the decisions already made in planning into one internally consistent design snapshot and ask the user to review it.
-
-The output of this phase must be written to a Markdown file named `QUADLET-FINALIZE.md`.
-
-This filename is fixed. Do not rename it per project.
+Goal: consolidate the decisions already made in planning into one internally consistent design snapshot and ask the user to review it in conversation.
 
 This phase starts only after planning-phase questions have been asked and the user has had a chance to answer or explicitly say there is nothing more to add.
 
@@ -151,6 +155,7 @@ Tasks in this phase:
    - for images of the form `name[:tag]` with no namespace, normalize to `docker.io/library/name[:tag]`
    - for images of the form `namespace/name[:tag]` with no registry, normalize to `docker.io/namespace/name[:tag]`
    - if the source clearly points to another registry such as `ghcr.io`, `quay.io`, or a private registry, preserve that registry explicitly
+   - if the approved image strategy uses fully qualified registry images and the user opted in earlier, include `AutoUpdate=registry` in the finalized design snapshot; otherwise leave it out
 
 4. Freeze the environment strategy.
    - use `Environment=` for a small number of stable non-sensitive values
@@ -169,8 +174,9 @@ Tasks in this phase:
    - suspicious env-key mismatches or typo candidates
    - missing required repo-local support files or directories
    - mismatch between requested deployment mode and selected file locations
+   - existing-file conflicts in the chosen output directory and the agreed handling for them
 
-At the end of finalize, write `QUADLET-FINALIZE.md` and ask the user to review it before you start writing the final artifacts.
+At the end of finalize, present the finalized design snapshot in conversation and ask the user to review it before you start writing the final artifacts.
 
 Before finalizing, use this checklist template:
 
@@ -178,36 +184,14 @@ Before finalizing, use this checklist template:
 - [ ] support files classified as upstream-preserved, locally generated, or locally rewritten
 - [ ] env keys classified into satisfied, unresolved, default-derived, and typo-suspect states
 - [ ] finalized file list reflects everything the runtime needs, not just Quadlet units
+- [ ] output location and any existing-file conflicts have an explicit plan
 - [ ] any remaining placeholders are explicit and understood as non-runnable until filled
 
+Finalize review is a review conversation, not a questionnaire and not a required markdown file. It should summarize decisions that were already discussed in planning.
 
-`QUADLET-FINALIZE.md` is a review artifact, not a questionnaire. It should summarize decisions that were already discussed in planning.
+Do not start execution until the user has reviewed and confirmed the finalize snapshot or provided requested edits.
 
-If `QUADLET-FINALIZE.md` already exists, read it first and update it intentionally. Do not blindly overwrite it without checking whether it reflects a prior review round that should be preserved or revised.
-
-When the design has materially changed, replace outdated sections so the file remains a single current review snapshot rather than an append-only log.
-
-`QUADLET-FINALIZE.md` should include:
-
-- source inputs you chose and why
-- selected services and omitted optional services
-- pod layout
-- naming prefix
-- image strategy
-- volume strategy
-- env strategy
-- env completeness status, including unresolved required variables and suspicious typo candidates
-- repo-local support files and directories that must be copied, preserved, or rendered for the deployment to run
-- which support files come from upstream unchanged versus which are generated or rewritten locally
-- the intended apply target directory for rootless or rootful deployment
-- the intended host-side destination paths for required support files, scripts, config trees, and initialization assets
-- only the minimal placeholders that still cannot be resolved without user secrets or environment-specific values
-- detected conflicts and how they were resolved
-- the list of files that will be created in execution phase, including generated Quadlet files, any env file or env delta, and helper scripts such as `install.sh`, `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` when applicable; do not introduce a parallel `apply.sh` name unless the user explicitly asks for it
-
-Do not start execution until the user has reviewed and confirmed `QUADLET-FINALIZE.md` or provided requested edits.
-
-Do not use `QUADLET-FINALIZE.md` as the first place where the user sees important choices. Those choices should already have been raised in planning.
+Do not use finalize review as the first place where the user sees important choices. Those choices should already have been raised in planning.
 
 ### Execution phase
 
@@ -231,7 +215,7 @@ Tasks in this phase:
 6. Generate deployment notes or validation guidance only when they materially help the user operate the result.
 7. Generate a README only when the user explicitly wants a self-contained handoff artifact or a packaged deliverable.
 
-Execution should follow the approved contents of `QUADLET-FINALIZE.md`. If the implementation reveals a material conflict with the finalized design, stop and return to planning rather than silently diverging.
+Execution should follow the approved finalize snapshot. If the implementation reveals a material conflict with the finalized design, stop and return to planning rather than silently diverging.
 
 Before calling the result runnable, pass this gate:
 
@@ -249,6 +233,7 @@ Use this execution checklist template:
 - [ ] support files, scripts, and config trees map to the correct host-side destination paths
 - [ ] runnable-output gate passed before describing the result as runnable
 - [ ] helper scripts operate on the same reviewed artifact set that finalize approved
+- [ ] chosen output directory still matches the approved plan and no new file conflicts appeared before writing
 
 
 If you generate a README or operational notes, use the same language as the user unless the user explicitly asks for another language.
@@ -274,6 +259,8 @@ Stop and ask the user before finalizing or generating runnable output when any o
 - image strategy versus local build strategy is materially ambiguous
 - a lossy mapping would change runtime behavior in a way that matters
 - the requested deployment mode conflicts with the intended output location or operator model
+- the user requested a non-default output directory but the resulting deliverable layout or operator model is still ambiguous
+- files that would be written already exist in the chosen output directory and the overwrite/update strategy is not yet approved
 - required repo-local support files or directories referenced by mounts, docs, commands, or scripts have not been identified confidently
 - required runtime files are known but are still missing from the planned deliverable set
 - required env values for minimal service startup are still missing from the final env sources
@@ -286,11 +273,13 @@ Do not keep moving forward by guessing through these gaps.
 Decide early whether the deployment is rootless or rootful, because this changes the apply target path and some operational guidance.
 
 - By default, generate reviewable artifacts in the current working directory first.
+- If the user explicitly requests another output directory for the reviewable artifact set, use that directory instead of forcing the current working directory.
 - For rootless deployments, the default apply target directory is `~/.config/containers/systemd/` unless the user has a reason to use another supported path.
 - For rootful deployments, the default apply target directory is `/etc/containers/systemd/` unless the user asks for a different placement.
 - For rootless long-running services, remind the user about lingering if relevant. See `references/deployment-notes.md`.
 
-When you need authoritative details about supported search paths, unit semantics, option names, or debugging, read `references/podman-systemd.unit.5.md`.
+When you need authoritative details about supported search paths, unit semantics, option names, generated-service behavior, or debugging, read `references/podman-systemd.unit.5.md`.
+If a Quadlet mapping, option meaning, or supported behavior is unclear or seems to conflict with higher-level guidance, treat `references/podman-systemd.unit.5.md` as the gold standard for Quadlet-specific behavior and align the result to it.
 
 ## Reference routing
 
@@ -312,7 +301,9 @@ This skill is not a blind converter. For runnable output, collaborate tightly wi
 - Read the docs, comments, and example values yourself, then present the user with a reduced set of concrete decisions and a candidate env result.
 - Ask the user to choose optional services and pod grouping early when the source project offers many containers or feature profiles.
 - Ask the user which volume mode they want before finalizing storage mappings.
-- Ask these questions before writing `QUADLET-FINALIZE.md`, not inside it.
+- Ask whether to opt into `AutoUpdate=registry` before finalize only when the approved image strategy actually supports it.
+- Do not ask a first-time "which output directory?" question when the default current working directory is acceptable; say the default plainly and only ask when the user already asked for a different location or an existing-file conflict requires a choice.
+- Resolve these questions before finalize review, not during execution.
 - Preserve placeholders when the user has not provided final values yet.
 - Distinguish between upstream example values and user-confirmed production values.
 
@@ -340,7 +331,7 @@ At minimum, mention the need to:
 ## Anti-examples
 
 - do not dump a large `.env.example` back to the user as the primary review artifact
-- do not introduce first-time critical decisions inside `QUADLET-FINALIZE.md`
+- do not introduce first-time critical decisions only during finalize review
 - do not force pod topology when a standalone `.container` is the simpler correct result
 - do not keep generating through unresolved deployment-critical unknowns
 

references/deployment-notes.md

@@ -4,11 +4,18 @@ Use this file when the user wants deployment-ready instructions alongside genera
 
 ## Delivery flow
 
-1. Generate the reviewable artifacts in the current working directory.
-2. Review the generated Quadlet files, env files, helper scripts, and any required repo-local support files or directories.
-3. Use `install.sh` to copy only the reviewed Quadlet unit files into the chosen Quadlet directory.
-4. Use `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` to manage the deployed services.
-5. Use `uninstall.sh` when the user wants to remove the installed reviewed Quadlet unit files without broad Podman cleanup.
+For `design` mode, stop after the user reviews the finalize snapshot in conversation.
+For `generate` mode, continue only after the user has reviewed and confirmed the finalize snapshot or requested edits.
+
+1. Generate the reviewable artifacts in the current working directory by default, or in another user-requested output directory.
+2. Resolve high-impact planning questions with the user before freezing the design.
+3. Review the finalized design snapshot together with the generated Quadlet files, env files, helper scripts, and any required repo-local support files or directories.
+4. Use `install.sh` to copy only the reviewed Quadlet unit files into the chosen Quadlet directory.
+5. Run the appropriate `daemon-reload` command.
+6. Use `start.sh`, `stop.sh`, and `restart.sh` to manage the deployed services.
+7. Use `uninstall.sh` when the user wants to remove the installed reviewed Quadlet unit files without broad Podman cleanup.
+
+Do not start execution until the user has reviewed and confirmed the finalize snapshot or requested edits.
 
 ## Apply target directory
 
@@ -28,16 +35,14 @@ See `podman-systemd.unit.5.md` for the full search-path matrix.
 
 - `install.sh`: canonical apply script; copy only reviewed Quadlet unit files into the selected Quadlet target directory
 - do not generate a separate `apply.sh` by default; reserve that alternate name only when the user explicitly asks for it
-- `uninstall.sh`: remove the installed reviewed Quadlet unit files from the selected Quadlet target directory, stopping affected services first when needed
-- `reload.sh`: run the appropriate `daemon-reload` command after installation changes
-- `start.sh`: start the generated units; when the topology uses a `.pod`, start the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of also starting each child container service individually
-- `stop.sh`: stop the generated units; when the topology uses a `.pod`, stop the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of duplicating per-container stop commands for its child containers
-- `restart.sh`: restart the generated units after reload or config changes; when the topology uses a `.pod`, restart the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of also restarting each child container service individually
+- `install.sh` must not start, stop, restart, or reload services as a side effect
+- `uninstall.sh`: remove the installed reviewed Quadlet unit files from the selected Quadlet target directory
+- `uninstall.sh` should stop affected services before removing their installed unit files, and should not delete support files from the current-directory deliverable set, unrelated files, shared directories, named volumes, images, or Podman objects unless the user explicitly asks for broader cleanup
+- `reload.sh`: run only the appropriate `daemon-reload` command after installation changes
+- `start.sh`, `stop.sh`, `restart.sh`: manage services only and must not silently install or overwrite reviewed files
+- when a generated topology includes `<name>.pod` plus child containers linked with `Pod=<name>.pod`, helper scripts should use the pod service as the lifecycle entrypoint; derive that service name from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of duplicating per-container lifecycle commands for child units
 
 Keep installation separate from service-management scripts so the user can review generated files before applying them.
-`install.sh` should copy reviewed Quadlet unit files into the chosen Quadlet target directory only, and should not start, stop, restart, or reload services as a side effect.
-`uninstall.sh` should remove only the installed reviewed Quadlet unit files, stop affected services before removal when needed, and leave the support files in the current-directory deliverable set, unrelated files, shared directories, named volumes, images, and Podman objects alone unless the user explicitly asks for broader cleanup.
-`reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` should not silently install or overwrite reviewed files.
 Do not use `ServiceName=` as an application connection target. It controls the generated systemd unit name only. When services communicate over a shared network outside a single pod namespace, prefer container names, pod names, or explicit `NetworkAlias=` values.
 Within a single pod, use `127.0.0.1` / `localhost` for container-to-container communication instead of generating `AddHost=` entries whose purpose is sibling-container discovery.
 If a service inside the pod must accept connections from sibling containers, ensure its effective listen address is reachable within the shared pod namespace, typically `127.0.0.1` or `0.0.0.0`. When the upstream service exposes this through environment variables or similar runtime configuration, preserve or generate that setting explicitly.
@@ -57,11 +62,12 @@ Execution checklist template before install:
 
 - [ ] all reviewed artifacts are present in the current-directory deliverable tree
 - [ ] required support files and directories are included alongside the Quadlet and env artifacts
-- [ ] unit files map to the intended Quadlet directory
+- [ ] every `EnvironmentFile=` path resolves to an actual reviewed file
 - [ ] support files remain in the current-directory deliverable tree at the absolute paths referenced by mounts and scripts
-- [ ] startup-critical env keys are present in the final env sources
+- [ ] startup-critical env keys are present, or explicitly marked as unresolved placeholders
 - [ ] any unresolved values are clearly marked as intentionally non-runnable placeholders
-- [ ] service-management scripts operate on the same reviewed artifact set that will be installed
+- [ ] service-management scripts operate on the same reviewed artifact set that finalize approved
+- [ ] runnable-output gate passed before describing the result as runnable
 
 ## Rootless operational notes
 
@@ -95,7 +101,7 @@ Use the timeout especially when first start may need to pull large images or bui
 
 ## Useful optional enhancements
 
-- `AutoUpdate=registry` for opt-in automatic image refresh workflows
+- `AutoUpdate=registry` for opt-in automatic image refresh workflows when the approved image strategy uses fully qualified registry images
 - explicit `.volume` or `.network` units when the user wants declarative infrastructure instead of implicit Podman objects
 
 ## Output language

references/validation.md

@@ -4,11 +4,12 @@ Use this file when the user asks how to verify or troubleshoot generated Quadlet
 
 ## Basic deployment flow
 
-1. Review the generated files in the current working directory and confirm the expected Quadlet units, env files, helper scripts, and required repo-local support files exist.
-2. Run `install.sh` to copy only the reviewed Quadlet unit files into the target Quadlet directory.
-3. Run the appropriate reload command.
-4. Start the relevant units and inspect their status.
-5. If needed, run `uninstall.sh` to remove the installed reviewed artifact set before regenerating or abandoning the deployment.
+1. Review the generated files in the current working directory by default, or in another user-requested output directory, and confirm the expected Quadlet units, env files, helper scripts, and required repo-local support files exist.
+2. Confirm the user has already reviewed the finalize snapshot and approved execution, or requested edits that were incorporated before writing runnable artifacts.
+3. Run `install.sh` to copy only the reviewed Quadlet unit files into the target Quadlet directory.
+4. Run the appropriate reload command.
+5. Start the relevant units and inspect their status.
+6. If needed, run `uninstall.sh` to remove the installed reviewed artifact set before regenerating or abandoning the deployment.
 
 If the user requested an alternate apply script name explicitly, substitute that name where needed, but treat `install.sh` as the default documentation path.
 
@@ -59,20 +60,25 @@ systemd-analyze --user verify <unit>.service
 Before calling the result runnable, verify that:
 
 - every referenced `EnvironmentFile=` exists at the path referenced by the installed unit
-- required env keys are actually present in the final env sources
+- required env keys are actually present in the final env sources, or are explicitly surfaced as unresolved placeholders
 - bind-mounted files and directories exist at the absolute paths referenced by the generated Quadlet files
 - bind-mounted file-versus-directory shape still matches the source input
+- if `AutoUpdate=registry` is enabled, the generated unit uses a fully qualified image reference
 - when sibling containers in the same pod must connect to a service, its effective listen address is reachable within the pod namespace (`127.0.0.1` or `0.0.0.0`, unless upstream docs require another reachable bind address)
 - repo-local entrypoint or helper scripts referenced by the container exist and are executable when needed
 - initialization assets such as `init.sql`, seeds, bootstrap files, or config templates are present where the deployment expects them
+- service-management scripts operate on the same reviewed artifact set that finalize approved
 
 Runnable-output gate checklist template:
 
 - [ ] the support-file set is complete
+- [ ] every `EnvironmentFile=` path resolves to an actual reviewed file
 - [ ] env completeness check passed against the actual final env sources
+- [ ] startup-critical env keys are present, or explicitly marked as unresolved placeholders
 - [ ] unit files are installed in the intended Quadlet directory
 - [ ] support files remain available at the absolute paths expected by mounts and scripts
 - [ ] bind-mounted file-versus-directory shape still matches the source input
+- [ ] if `AutoUpdate=registry` is enabled, the generated unit uses a fully qualified image reference
 - [ ] intra-pod service listeners that must accept sibling-container traffic are reachable on `127.0.0.1` or `0.0.0.0`, unless upstream docs require another reviewed bind address
 - [ ] service-management scripts operate on the same artifact set that was reviewed
 - [ ] no required support file, env key, or typo-suspect mismatch remains unresolved
@@ -82,6 +88,7 @@ Do not call the result runnable until every item above is checked.
 ## Common failure causes
 
 - unsupported Quadlet option for the installed Podman version
+- `AutoUpdate=registry` was enabled but the image reference is not fully qualified
 - bind-mount source directory missing
 - files were generated but `install.sh` has not yet copied the unit files into the target rootless or rootful unit directory
 - wrong rootless or rootful apply target directory