Refine default Quadlet naming and identity rules

README.md

@@ -10,6 +10,8 @@ A skill that helps turn `docker run` commands and Docker Compose setups into Pod
 - writes the generated files to the current directory first so you can review them before installing them
 - asks about the output location only when you already requested another location or existing files would conflict
 - helps choose between `.container`, `.pod`, `.network`, `.volume`, and `.build`, usually preferring a pod for related multi-container services
+- avoids adding explicit runtime naming directives such as `PodName=`, `ServiceName=`, `ContainerName=`, and `NetworkName=` by default unless the user asks for them or a reviewed requirement depends on them
+- avoids adding `User=`, `Group=`, or `UserNS=keep-id` by default unless the source explicitly requires them or the user is working through permission or ownership behavior
 - keeps `.env` / `env_file` workflows when they still fit the deployment
 - turns large env templates into a short list of decisions the user actually needs to make
 - can generate helper scripts such as `install.sh`, `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh`
@@ -28,6 +30,8 @@ A skill that helps turn `docker run` commands and Docker Compose setups into Pod
 - prefer output that is easy to understand and maintain
 - write files to the current directory for review before installation
 - prefer pod-based grouping when it is the clearest fit for a multi-container service
+- let Quadlet and Podman derive runtime names unless reviewed requirements justify explicit naming fields
+- avoid runtime identity-mapping fields unless they are actually needed for the reviewed deployment
 - keep required extra files in the reviewed output and point to them with absolute paths on the host machine instead of copying them into the Quadlet unit directory
 
 ## Operating modes

README.zh-CN.md

@@ -10,6 +10,8 @@
 - 默认先把生成文件写到当前目录，方便你在安装前先审阅
 - 只有在你已经指定其他位置，或现有文件会发生冲突时，才询问输出位置
 - 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择；对有关联的多容器服务，通常优先用 pod
+- 默认不添加 `PodName=`、`ServiceName=`、`ContainerName=`、`NetworkName=` 这类显式运行时命名字段，除非用户要求或审阅后的需求确实依赖它们
+- 默认不添加 `User=`、`Group=`、`UserNS=keep-id`，除非源配置明确要求，或用户正在处理权限 / 属主相关行为
 - 在合适时保留 `.env` / `env_file` 工作流
 - 把庞杂的 env 模板收敛成用户真正需要确认的少量问题
 - 可生成辅助脚本，例如 `install.sh`、`uninstall.sh`、`reload.sh`、`start.sh`、`stop.sh`、`restart.sh`
@@ -28,6 +30,8 @@
 - 优先产出容易理解、容易维护的结果
 - 先把文件写到当前目录审阅，再决定是否安装
 - 对多容器服务，如果用 pod 更清晰，就优先用 pod
+- 默认让 Quadlet 和 Podman 自行派生运行时名称，只有在审阅后确认确有必要时才显式命名
+- 默认避免引入运行时身份映射字段，只有在当前部署确实需要时才添加
 - 运行仍需要的额外文件保留在已审阅的输出中，并通过主机上的绝对路径引用，而不是复制进 Quadlet 单元目录
 
 ## 运行模式

SKILL.md

@@ -16,6 +16,8 @@ This skill helps you:
 - discover Docker deployment entry points from a GitHub repository URL
 - 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
+- avoid explicit naming directives such as `PodName=`, `ServiceName=`, `ContainerName=`, and `NetworkName=` by default; rely on Quadlet and Podman derived names unless the user explicitly asks for custom naming or a reviewed requirement depends on it
+- avoid introducing `User=`, `Group=`, or `UserNS=keep-id` by default; only preserve or add runtime identity mapping when the source explicitly requires it or when the user is addressing permission or ownership behavior
 - decide whether values belong in `Environment=` or `EnvironmentFile=`
 - 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, using the reviewed shell templates under `references/template/` as the default source
@@ -129,12 +131,13 @@ Tasks in this phase:
    - if the project is a simple single-container deployment, a standalone `.container` is the default
    - 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
+   - do not add `PodName=`, `ServiceName=`, `ContainerName=`, or `NetworkName=` by default; use Quadlet's derived names unless the user explicitly asked for custom runtime naming or a reviewed requirement depends on it
    - containers in the same `.pod` can communicate over `127.0.0.1` / `localhost` because they share a network namespace
    - when services in the same `.pod` must accept connections from sibling containers, ensure they listen on `127.0.0.1` or `0.0.0.0`; if they listen only on another interface, sibling containers in the pod may not be able to reach them
    - when the upstream service supports configuring the listen address via environment variables or equivalent runtime settings, preserve or generate the necessary configuration instead of assuming the default bind address is correct
    - 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
+   - 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. Do not introduce `ServiceName=` merely to simplify helper scripts. 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
@@ -162,6 +165,7 @@ Tasks in this phase:
    - use `EnvironmentFile=` for bulk variables, secrets, or values already sourced from `.env` / `env_file`
    - if Compose interpolation references variables that are missing, report them explicitly and prepare a candidate env file with placeholders or suggested defaults instead of delegating the entire review back to the user
    - treat variable names containing `PASSWORD`, `TOKEN`, `SECRET`, `KEY`, `PRIVATE`, or `PASS` as sensitive by default and avoid inlining unless the user explicitly wants that
+   - do not introduce `User=`, `Group=`, or `UserNS=keep-id` as part of the default generated shape; only preserve or add them when the source explicitly requires a runtime identity mapping or when the user is addressing permission or ownership behavior
    - do not treat a variable as satisfied unless it is present in an actual final source such as `Environment=`, the final `EnvironmentFile=`, or an explicitly preserved default
    - if a likely required startup variable is still absent from the final output, keep it unresolved instead of downgrading it to an informational note
    - if referenced env keys and final env keys contain likely near-match typos, call them out explicitly before execution

references/compose-mapping.md

@@ -7,6 +7,7 @@ Use this file when converting `docker-compose.yml` or `compose.yaml` into Quadle
 - Model each service first, then decide how to group all resulting containers into one or more `.pod` units.
 - Prefer maintainable Quadlet output over mechanical one-to-one translation.
 - Keep names stable and predictable. Generated filenames should use a shared project prefix.
+- Do not add explicit runtime naming directives such as `PodName=`, `ServiceName=`, `ContainerName=`, or `NetworkName=` by default. Let Quadlet and Podman derive runtime names unless the user explicitly asks for custom naming or a reviewed requirement depends on it.
 - When one deliverable set includes multiple Quadlet files, keep that shared prefix consistent so helper shell scripts can match them by shared-prefix globbing such as `<prefix>*`, instead of hardcoding exact filenames or assuming a fixed file count.
 
 ## Field strategy
@@ -60,6 +61,7 @@ Use this file when converting `docker-compose.yml` or `compose.yaml` into Quadle
 - If the source uses a default network only, you often do not need a `.network` unit at all.
 - 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.
+- Do not add `NetworkName=` by default. Let Quadlet derive the network name unless the user explicitly asks for a custom network name or a reviewed requirement depends on it.
 - Containers in the same `.pod` can communicate over `127.0.0.1` / `localhost` because they share a network namespace.
 - When services in the same `.pod` must accept connections from sibling containers, ensure they listen on `127.0.0.1` or `0.0.0.0`; if they listen only on another interface, sibling containers in the pod may not be able to reach them.
 - When the upstream service supports configuring the listen address via environment variables or equivalent runtime settings, preserve or generate the necessary configuration instead of assuming the default bind address is correct.
@@ -67,6 +69,7 @@ Use this file when converting `docker-compose.yml` or `compose.yaml` into Quadle
 - `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 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.
+- Do not add `ServiceName=` or `PodName=` by default. If they are omitted, use Quadlet's derived names unless the user explicitly asks for custom runtime naming or a reviewed requirement depends on it.
 - `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.
 
@@ -110,8 +113,9 @@ Use this file when converting `docker-compose.yml` or `compose.yaml` into Quadle
 
 ### `user`
 
-- Map to `User=` and `Group=` in `[Container]` only when it is a container runtime user mapping, not a systemd service user.
+- Do not add `User=` or `Group=` by default. Map them in `[Container]` only when the source explicitly requires a container runtime user mapping or when the user is addressing permission or ownership behavior, and not as a systemd service user substitute.
 - Do not use systemd `User=` to try to make a rootless Quadlet run as another login user.
+- Do not add `UserNS=keep-id` by default. Consider it only when the user is working through rootless permission or ownership behavior and the reviewed topology benefits from preserving host identity semantics.
 
 ### unsupported or risky fields
 

references/deployment-notes.md

@@ -41,9 +41,10 @@ See `podman-systemd.unit.5.md` for the full search-path matrix.
 - `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
+- 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. Do not add `ServiceName=` merely to simplify helper scripts, and do not duplicate per-container lifecycle commands for child units
 
 Keep installation separate from service-management scripts so the user can review generated files before applying them.
+Do not add explicit runtime naming directives such as `PodName=`, `ServiceName=`, `ContainerName=`, or `NetworkName=` by default. Use Quadlet's derived names unless the user explicitly asks for custom naming or a reviewed requirement depends on it.
 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.
@@ -73,7 +74,7 @@ Execution checklist template before install:
 ## Rootless operational notes
 
 - Bind mounts may hit UID/GID mismatches.
-- For pod-based deployments that should preserve host ownership semantics, consider `UserNS=keep-id` on `[Pod]` when appropriate.
+- Do not add `User=`, `Group=`, or `UserNS=keep-id` by default. Consider them only when the user is working through container permission or ownership behavior, or when the source explicitly requires that runtime identity mapping.
 - If the service must survive logout, mention lingering:
 
 ```bash