Refine finalize review and output prompting rules.

Align the Quadlet migrator skill with a conversation-based finalize flow, default current-directory output, and opt-in AutoUpdate planning only when fully-qualified registry images support it.

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

README.md

@@ -8,13 +8,15 @@ A skill for migrating `docker run` commands and Docker Compose-style deployments
 
 - 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
+- asks about the output location only when the user requested another location or an existing-file conflict requires a decision
 - 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
+- encourages explicit planning questions plus finalize and execution checklists for support files and env completeness
+- supports opt-in `AutoUpdate=registry` planning when the approved image strategy uses fully qualified registry images
 - explains rootless vs rootful apply targets, deployment notes, and validation steps
 
 ## Design principles
@@ -31,8 +33,20 @@ A skill for migrating `docker run` commands and Docker Compose-style deployments
 ## 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
+- `design`: perform planning and interactive finalize review, then stop before runnable artifact generation
+- `generate`: produce approved runnable artifacts after planning, interactive finalize review, and execution
+
+## Workflow
+
+The full workflow has three explicit phases: `Planning`, `Finalize`, and `Execution`.
+
+- `advice` usually stays in `Planning` or gives a targeted answer without entering all phases
+- `design` uses `Planning` and `Finalize`
+- `generate` uses all three phases
+
+Planning must ask the user to confirm unresolved high-impact decisions before moving forward.
+Finalize happens as an interactive review in conversation after those planning questions have already been discussed.
+Execution starts only after the user has reviewed and confirmed the finalize review or requested edits.
 
 ## References
 

README.zh-CN.md

@@ -8,13 +8,15 @@
 
 - 将 `docker run` 和 Compose 风格输入转换为面向 Quadlet 的设计
 - 默认先把生成产物写到当前目录，便于审查后再应用
+- 只有在用户已要求其他位置，或现有文件冲突需要决策时，才询问输出位置
 - 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择，并对多容器服务默认偏向 pod-first 拓扑
 - 在合适时保留 `.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 检查清单
+- 鼓励在 planning 阶段显式提出高影响问题，并在 finalize 与 execution 阶段使用 support files 与 env completeness 检查清单
+- 当已批准的镜像策略使用 fully qualified registry images 时，可规划 opt-in 的 `AutoUpdate=registry`
 - 说明 rootless / rootful 应用目标路径、部署说明与验证步骤
 
 ## 设计原则
@@ -26,13 +28,25 @@
 - 优先输出可维护的结果，而不是机械一比一转换
 - 默认先输出到当前目录供审查，再执行安装
 - 当 pod 分组已经能清晰表达意图时，优先采用 pod-first 拓扑而不是保留 bridge 网络
-- 将运行必需文件复制到各自正确的主机路径，而不只是复制到 Quadlet 单元目录
+- 确保运行所需的 support files 保留在已审阅的当前目录交付集中，并通过绝对主机路径被 Quadlet 引用，而不是由 `install.sh` 复制进 Quadlet 单元目录
 
 ## 运行模式
 
 - `advice`：解释映射方式或审查输入，不写最终产物
-- `design`：执行 planning 和 finalize 审阅，但在生成可运行产物前停止
-- `generate`：在 planning 和 finalize 审阅通过后，生成已批准的可运行产物
+- `design`：执行 planning 和交互式 finalize 审阅，但在生成可运行产物前停止
+- `generate`：在 planning、交互式 finalize 审阅和 execution 之后，生成已批准的可运行产物
+
+## 工作流
+
+完整工作流分为三个明确阶段：`Planning`、`Finalize`、`Execution`。
+
+- `advice` 通常停留在 `Planning`，或给出不进入全流程的定向答复
+- `design` 使用 `Planning` 和 `Finalize`
+- `generate` 使用全部三个阶段
+
+Planning 必须先向用户确认仍未解决的高影响决策，之后才能继续。
+Finalize 会在这些 planning 问题已经讨论过之后，以对话方式进行交互式审阅。
+只有在用户审阅并确认 finalize 审阅结果或提出修改后，才能进入 Execution。
 
 ## 文档说明
 

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,6 +273,7 @@ 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`.
@@ -312,7 +300,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 +330,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