Clarify Quadlet pod lifecycle and networking rules

Document uninstall script behavior and align pod service naming, addressing, and AddHost guidance with podman-systemd semantics.

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

README.md

@@ -11,7 +11,7 @@ A skill for migrating `docker run` commands and Docker Compose-style deployments
 - 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 `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh`
+- 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

README.zh-CN.md

@@ -11,7 +11,7 @@
 - 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择，并对多容器服务默认偏向 pod-first 拓扑
 - 在合适时保留 `.env` / `env_file` 工作流
 - 将大型 env 模板归纳为少量高影响部署问题
-- 可生成辅助脚本，其中 `install.sh` 是规范的 apply 步骤，另可生成 `reload.sh`、`start.sh`、`stop.sh`、`restart.sh`
+- 可生成辅助脚本，其中 `install.sh` 是规范的 apply 步骤，另可生成 `uninstall.sh`、`reload.sh`、`start.sh`、`stop.sh`、`restart.sh`
 - 会识别并交付运行所需的 repo 内配套文件，例如挂载配置、初始化资源和辅助脚本
 - 在声称结果可运行前，会检查环境变量完整性，而不是只做 env 摘要
 - 鼓励在 finalize 与 execution 阶段显式使用 support files 与 env completeness 检查清单

SKILL.md

@@ -18,7 +18,7 @@ This skill helps you:
 - 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
-- generate helper scripts with `install.sh` as the canonical apply script name, plus `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` when producing runnable artifacts
+- 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
 - work closely with the user to confirm deployment-specific environment values and operational choices
@@ -126,7 +126,12 @@ Tasks in this phase:
    - if one logical service contains multiple containers, prefer keeping them in the same `.pod` so they share one network namespace
    - even when the source Compose topology uses bridge networking, prefer pod-based grouping over preserving bridge semantics mechanically
    - containers in the same `.pod` can communicate over `127.0.0.1` / `localhost` because they share a network namespace
-   - containers in different pods must not be treated as reachable via `127.0.0.1` / `localhost`; if you split the topology across multiple pods, use container naming, pod naming, or service-level addressing instead
+   - when `Pod=` is set, never generate `AddHost=` entries whose purpose is sibling-container discovery inside that pod; intra-pod communication must use `127.0.0.1` / `localhost` instead
+   - `AddHost=` remains a host-to-IP override, not an intra-pod service-discovery mechanism; because upstream Quadlet supports `AddHost=` in both `[Container]` and `[Pod]`, do not claim that `Pod=` categorically forbids `AddHost=` unless the upstream reference says so for the specific case
+   - when containers are attached with `Pod=<name>.pod`, treat the pod's generated systemd service as the primary lifecycle unit; derive that service name from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name. Starting that pod service brings up the pod-managed containers, so do not add redundant per-container start commands for those child units in helper scripts
+   - containers in different pods must not be treated as reachable via `127.0.0.1` / `localhost`; if you split the topology across multiple pods or preserve a shared bridge network, use container names, pod names, or explicit `NetworkAlias=` values on the shared network instead
+   - `ServiceName=` controls the generated systemd unit name only and must not be treated as an application-facing network address
+   - `PodName=` controls the Podman pod name only and may be part of the chosen addressing strategy, but it does not determine the systemd service name
    - if one pod is not practical because of port conflicts or clearly incompatible groupings, split the result into a small number of pods rather than forcing an awkward topology
    - avoid `.network` / bridge-first designs unless pod topology cannot express the intended deployment cleanly
 
@@ -194,7 +199,7 @@ When the design has materially changed, replace outdated sections so the file re
 - 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`, `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
+- 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.
 
@@ -208,12 +213,15 @@ Tasks in this phase:
 
 1. Generate the Quadlet files in the current working directory by default so the user can review them before applying them.
 2. Generate the env file or env delta only when needed for runnable output.
-3. Generate helper scripts such as `install.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` when they materially help the user apply and operate the result.
+3. Generate helper scripts such as `install.sh`, `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` when they materially help the user apply and operate the result.
    - Use `install.sh` as the default and canonical script name for applying the reviewed artifact set.
    - Do not also generate `apply.sh` unless the user explicitly asks for that alternate name.
    - `install.sh` should copy only Quadlet unit files into the chosen Quadlet target directory. It should copy env files, mounted config, scripts, and other required runtime support files into the correct host-side paths the deployment actually expects.
    - `install.sh` should not start, stop, restart, or reload services as a side effect.
+   - `uninstall.sh` should remove only the previously installed reviewed artifact set from the chosen Quadlet target directory and the corresponding host-side runtime support-file paths.
+   - `uninstall.sh` should stop affected services before removing their installed units or runtime support files, and should not delete unrelated files, shared directories, named volumes, images, or Podman objects unless the user explicitly asks for that broader cleanup.
    - `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` should manage services only and should not silently install or overwrite files.
+   - when a generated topology includes `<name>.pod` plus child containers linked with `Pod=<name>.pod`, make the pod service the lifecycle entrypoint in helper scripts; derive that service name from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name. Do not emit redundant `systemctl start/stop/restart` lines for each child container that is already managed through the pod service.
 4. If the deployment depends on repo-local support files or directories, generate or copy those reviewed artifacts into the current-directory deliverable set as well.
 5. Do not claim runnable output until the final env sources and support-file set are complete enough for minimal startup.
 6. Generate deployment notes or validation guidance only when they materially help the user operate the result.
@@ -227,7 +235,7 @@ Before calling the result runnable, pass this gate:
 - every referenced `EnvironmentFile=` exists in the deliverable set and contains the required keys
 - startup-critical env values are either present or explicitly unresolved
 - suspected env typos have been resolved or surfaced to the user
-- install, reload, and service-management scripts match the approved artifact set
+- install, uninstall, reload, and service-management scripts match the approved artifact set
 
 Use this execution checklist template:
 
@@ -323,7 +331,7 @@ At minimum, mention the need to:
 - `docker run` for a single web service -> often `advice` or `generate` with one `.container`
 - small Compose app with api and db -> usually `design` or `generate`, often one `.pod` plus child containers
 - GitHub repo with `.env.example` and multiple profiles -> start in `Planning`, reduce the env questions, then move to `Finalize`
-- review-first runnable output -> `generate` often writes Quadlet files plus `install.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` into the current directory, with `install.sh` as the canonical apply step
+- review-first runnable output -> `generate` often writes Quadlet files plus `install.sh`, `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` into the current directory, with `install.sh` as the canonical apply step
 
 ## Anti-examples
 

references/compose-mapping.md

@@ -58,8 +58,12 @@ Use this file when converting `docker-compose.yml` or `compose.yaml` into Quadle
 - If the source uses bridge networking for containers that can reasonably live in one pod, collapse that topology into one `.pod` so the containers share one network namespace.
 - Create a `.network` unit only when services must be split across pods, or when explicit network isolation or custom network management is materially required.
 - Containers in the same `.pod` can communicate over `127.0.0.1` / `localhost` because they share a network namespace.
+- When `Pod=` is set, never generate `AddHost=` entries whose purpose is sibling-container discovery inside that pod; intra-pod communication should use `127.0.0.1` / `localhost` instead.
+- `AddHost=` is a host-to-IP override, not an intra-pod service-discovery mechanism. Upstream Quadlet documents `AddHost=` in both `[Container]` and `[Pod]`, so do not describe `Pod=` as a blanket prohibition on `AddHost=` unless the upstream reference explicitly requires that for the case at hand.
 - Containers in different pods must not be treated as reachable via `127.0.0.1` / `localhost`.
-- When splitting services across multiple pods, use container names, pod names, or service-level addressing across the shared network, or publish ports to the host boundary when that is the intended access pattern.
+- When splitting services across multiple pods or preserving a shared bridge network, use container names, pod names, or explicit `NetworkAlias=` values on the shared network, or publish ports to the host boundary when that is the intended access pattern.
+- `ServiceName=` controls the generated systemd unit name only and must not be used as an application-facing network address.
+- `PodName=` controls the Podman pod name only; it can participate in the chosen addressing strategy, but it does not determine the systemd service name.
 
 ### `environment`
 
@@ -174,7 +178,7 @@ If the project is a simple single-container deployment with no real need for pod
 
 If one pod is not practical because of port conflicts or clearly incompatible groupings, split the result into a small number of pods rather than forcing an awkward topology.
 
-When services are split across multiple pods, do not rely on `127.0.0.1` / `localhost` for cross-pod communication. Use container names, pod names, or other service-level addressing on the shared network instead.
+When services are split across multiple pods, do not rely on `127.0.0.1` / `localhost` for cross-pod communication. Use container names, pod names, or explicit `NetworkAlias=` values on the shared network instead.
 
 Avoid preserving bridge networks by default when pod grouping already expresses the intended communication pattern well.
 

references/deployment-notes.md

@@ -8,6 +8,7 @@ Use this file when the user wants deployment-ready instructions alongside genera
 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 unit files into the chosen Quadlet directory. Copy env files and any other required runtime support files into the correct host-side paths the deployment expects.
 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 artifact set without broad Podman cleanup.
 
 ## Apply target directory
 
@@ -27,14 +28,18 @@ 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, and copy env files plus any other required runtime support files into the correct host-side paths
 - 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 artifact set from the selected Quadlet target directory and corresponding host-side runtime support-file paths, stopping affected services first when needed
 - `reload.sh`: run the appropriate `daemon-reload` command after installation changes
-- `start.sh`: start the generated units
-- `stop.sh`: stop the generated units
-- `restart.sh`: restart the generated units after reload or config 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
 
 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 and place required runtime support files into their correct host-side destinations only, and should not start, stop, restart, or reload services as a side effect.
+`uninstall.sh` should remove only the installed reviewed artifact set, stop affected services before removal when needed, and leave 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.
 
 ## Review checklist before install
 

references/validation.md

@@ -8,6 +8,7 @@ Use this file when the user asks how to verify or troubleshoot generated Quadlet
 2. Run `install.sh` to copy only the reviewed unit files into the target Quadlet directory and place required runtime support files into the correct host-side paths.
 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.
 
 If the user requested an alternate apply script name explicitly, substitute that name where needed, but treat `install.sh` as the default documentation path.