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>

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.