quadlet-migrator-skill/references/validation.md

# Validation

Use this file when the user asks how to verify or troubleshoot generated Quadlet units.

## Basic deployment flow

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.

### Rootless

```bash
systemctl --user daemon-reload
systemctl --user start <unit>
systemctl --user status <unit>
```

### Rootful

```bash
systemctl daemon-reload
systemctl start <unit>
systemctl status <unit>
```

## Generator debugging

Use the Podman systemd generator dry run when units fail to appear or options look unsupported.

```bash
/usr/lib/systemd/system-generators/podman-system-generator --dryrun
```

For rootless debugging:

```bash
/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
```

## Systemd verification

```bash
systemd-analyze verify <unit>.service
```

For user units:

```bash
systemd-analyze --user verify <unit>.service
```

## Support-file and env checks

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, 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

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
- unresolved env file path
- required env key missing from the final env file
- likely env-key typo or mismatch between source docs and final env output
- required repo-local config, init assets, or helper scripts missing from the installed artifact set
- permissions on rootless bind mounts
- readiness assumptions hidden behind `depends_on`

## Troubleshooting posture

When validation fails, report:

- what generated successfully
- what was applied successfully
- what failed to generate, apply, or start
- whether the issue is syntax, unsupported feature, path resolution, installation path, missing support files, missing env keys, or permissions

## Relationship to execution phase

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.