Tighten Quadlet support-file and mount rules

Make install scripts manage only Quadlet units, keep support files in the reviewed working tree via absolute paths, and preserve file-versus-directory bind mount shape from source inputs.

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

README.md

@@ -26,7 +26,7 @@ A skill for migrating `docker run` commands and Docker Compose-style deployments
 - 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
-- copy runtime-required files to their correct host-side destinations, not just into the Quadlet unit directory
+- 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
 
 ## Operating modes
 

SKILL.md

@@ -138,6 +138,8 @@ Tasks in this phase:
 2. Freeze the storage strategy.
    - named volume, bind mount, or anonymous volume per storage use case
    - bind mounts must end up as absolute host paths
+   - preserve bind-mount shape from the source input: a file bind mount must stay a file bind mount, and a directory bind mount must stay a directory bind mount
+   - do not widen a file mount into a directory mount, or collapse a directory mount into a file mount, unless the source is genuinely ambiguous or the upstream deployment docs explicitly require a different reviewed mapping
 
 3. Freeze the image strategy.
    - prefer upstream prebuilt registry images when they already exist and local build is not required for correctness
@@ -216,10 +218,10 @@ Tasks in this phase:
 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 copy only Quadlet unit files into the chosen Quadlet target directory. Required env files, mounted config, scripts, and other runtime support files should remain in the reviewed current-directory deliverable set and be referenced from Quadlet via absolute host paths.
    - `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.
+   - `uninstall.sh` should remove only the previously installed reviewed Quadlet unit files from the chosen 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 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.
@@ -321,7 +323,7 @@ When the user wants runnable output, provide the relevant deployment notes from
 At minimum, mention the need to:
 
 - review the generated files in the current directory
-- apply the reviewed files into the correct Quadlet directory and host-side runtime paths
+- apply the reviewed Quadlet files into the correct Quadlet directory while keeping support files in the current directory at the absolute paths referenced by the units
 - run `systemctl daemon-reload` or `systemctl --user daemon-reload`
 - create required bind-mount directories before first start
 - verify generator output or systemd unit validity when startup fails

references/compose-mapping.md

@@ -46,6 +46,8 @@ Use this file when converting `docker-compose.yml` or `compose.yaml` into Quadle
 
 - Bind mounts become `Volume=HOST:CONTAINER[:OPTIONS]`.
 - Normalize relative host paths against the Compose file directory and emit absolute paths in the final Quadlet output.
+- Preserve bind-mount shape from the source input: a file bind mount must stay a file bind mount, and a directory bind mount must stay a directory bind mount.
+- Do not widen a file mount into a directory mount, or collapse a directory mount into a file mount, unless the source is genuinely ambiguous or the upstream deployment docs explicitly require a different reviewed mapping.
 - Named volumes can remain referenced by name, but when the user wants explicit infrastructure-as-code, create matching `.volume` units.
 - Ask the user which volume mode they want when the source does not make the intended persistence model obvious.
 - If a bind mount points to a repo-local file or directory, include that source in the reviewable deliverable set unless the user explicitly wants a host-managed external path instead.

references/deployment-notes.md

@@ -6,9 +6,9 @@ Use this file when the user wants deployment-ready instructions alongside genera
 
 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 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.
+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 artifact set without broad Podman cleanup.
+5. Use `uninstall.sh` when the user wants to remove the installed reviewed Quadlet unit files without broad Podman cleanup.
 
 ## Apply target directory
 
@@ -26,17 +26,17 @@ See `podman-systemd.unit.5.md` for the full search-path matrix.
 
 ## Helper scripts
 
-- `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
+- `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 artifact set from the selected Quadlet target directory and corresponding host-side runtime support-file paths, stopping affected services first when needed
+- `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
 
 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.
+`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.
@@ -57,7 +57,7 @@ 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
-- [ ] support files map to the correct host-side runtime paths for mounts and scripts
+- [ ] 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
 - [ ] 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
@@ -78,7 +78,7 @@ sudo loginctl enable-linger <username>
 - Normalize relative source paths against the source Compose file directory or the directory the user specifies.
 - Emit absolute host paths in generated Quadlet files when using bind mounts.
 - Explain the resolved absolute path if the source used `./...`.
-- If the source project bind-mounts repo-local files or directories, make sure the installed artifact set preserves the required contents and places them at the correct host-side paths expected by the mounts.
+- If the source project bind-mounts repo-local files or directories, make sure the reviewed current-directory deliverable set preserves the required contents and that the generated Quadlet files reference their absolute paths correctly.
 
 ## Recommended service defaults
 

references/validation.md

@@ -5,7 +5,7 @@ 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 unit files into the target Quadlet directory and place required runtime support files into the correct host-side paths.
+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.
@@ -58,9 +58,10 @@ systemd-analyze --user verify <unit>.service
 
 Before calling the result runnable, verify that:
 
-- every referenced `EnvironmentFile=` exists at the installed path
+- every referenced `EnvironmentFile=` exists at the path referenced by the installed unit
 - required env keys are actually present in the final env sources
-- bind-mounted files and directories exist after installation
+- 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
 - 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
 
@@ -69,7 +70,8 @@ Runnable-output gate checklist template:
 - [ ] the support-file set is complete
 - [ ] env completeness check passed against the actual final env sources
 - [ ] unit files are installed in the intended Quadlet directory
-- [ ] support files are installed at the host-side runtime paths expected by mounts and scripts
+- [ ] support files remain available at the absolute paths expected by mounts and scripts
+- [ ] bind-mounted file-versus-directory shape still matches the source input
 - [ ] service-management scripts operate on the same artifact set that was reviewed
 - [ ] no required support file, env key, or typo-suspect mismatch remains unresolved
 
@@ -79,7 +81,7 @@ Do not call the result runnable until every item above is checked.
 
 - unsupported Quadlet option for the installed Podman version
 - 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 and the required runtime support files into their host-side paths
+- 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
 - unresolved env file path
 - required env key missing from the final env file
@@ -99,6 +101,6 @@ When validation fails, report:
 
 ## Relationship to execution phase
 
-Validation belongs after the files are written in the execution phase and applied to a valid Quadlet directory and the correct host-side runtime paths.
+Validation belongs after the files are written in the execution phase, the Quadlet units are applied to a valid Quadlet directory, and the referenced support files remain available at the absolute host paths used by the generated units.
 
 Before execution, the skill should already have completed planning and finalize review with the user. Do not treat validation as a substitute for design review.