init

references/env-strategy.md

@@ -0,0 +1,165 @@
+# Environment Strategy
+
+Use this file whenever the migration includes `.env`, `env_file`, Compose interpolation, or inline `-e` flags.
+
+## Goals
+
+- preserve source-of-truth for variables
+- avoid leaking secrets into generated Quadlet files by default
+- keep resulting units readable
+- report missing variables explicitly
+- reduce large upstream env templates into a small set of user decisions
+
+## Default rules
+
+The agent should actively interpret the env template and its comments. Do not offload the entire env review back to the user.
+
+### Prefer `Environment=` when
+
+- there are only a few variables
+- values are stable and not sensitive
+- keeping everything in one file materially improves readability
+
+### Prefer `EnvironmentFile=` when
+
+- the source already uses `.env` or `env_file`
+- variables are numerous
+- variables contain secrets or deployment-specific values
+- the same env file is shared by multiple services
+
+## Sensitive-value heuristic
+
+Treat names containing these substrings as sensitive unless the user tells you otherwise:
+
+- `PASSWORD`
+- `TOKEN`
+- `SECRET`
+- `KEY`
+- `PRIVATE`
+- `PASS`
+
+Default behavior:
+
+- do not inline them in `Environment=`
+- keep them in `EnvironmentFile=` or generate a placeholder sample file instead
+
+## Compose interpolation
+
+Common forms:
+
+- `${VAR}`
+- `${VAR:-default}`
+- `${VAR-default}`
+
+Strategy:
+
+- if the actual value source is present, resolve it and document where it came from
+- if only a default is available, note that the value is default-derived
+- if the variable is missing, list it as unresolved
+
+Do not fabricate values.
+
+## Agent responsibility
+
+When the source project ships a large `.env.example` or multiple env templates:
+
+- read the comments and deployment docs yourself
+- determine which values can safely stay at documented defaults
+- determine which values are true deployment decisions and must be confirmed with the user
+- prepare a candidate `.env` or env delta instead of asking the user to read the whole template manually
+
+The user should only need to answer the small number of high-impact questions that cannot be discovered locally.
+
+## Minimal examples
+
+### Inline stable values
+
+Source intent:
+
+```yaml
+environment:
+  APP_ENV: production
+  APP_PORT: "8080"
+```
+
+Reasonable result shape:
+
+```ini
+[Container]
+Environment=APP_ENV=production
+Environment=APP_PORT=8080
+```
+
+Use this when there are only a few non-sensitive structural values.
+
+### Preserve env-file workflow
+
+Source intent:
+
+```yaml
+env_file:
+  - .env
+```
+
+Reasonable result shape:
+
+```ini
+[Container]
+EnvironmentFile=/opt/myapp/.env
+```
+
+Use this when the source already relies on an env file, especially for secrets or many variables.
+
+### Large template reduced to a candidate env
+
+Source intent:
+
+- upstream ships `.env.example`
+- only a few values are true deployment decisions
+
+Recommended behavior:
+
+- keep documented defaults that are safe to preserve
+- ask the user only for high-impact values such as domain, storage path, or database password
+- generate a candidate `.env` or env delta with clear placeholders for the unresolved items
+
+## Output patterns
+
+### Small inline set
+
+```ini
+[Container]
+Environment=APP_ENV=production
+Environment=APP_PORT=8080
+```
+
+### External env file
+
+```ini
+[Container]
+EnvironmentFile=/opt/myapp/myapp.env
+```
+
+### Mixed pattern
+
+Use this when a few values are structural and the rest are secret or deployment-specific.
+
+```ini
+[Container]
+Environment=APP_ENV=production
+EnvironmentFile=/opt/myapp/myapp.env
+```
+
+## Missing-variable reporting
+
+When variables cannot be resolved, report them as a concrete checklist.
+
+Example:
+
+- missing `DB_PASSWORD`
+- missing `IMMICH_VERSION`
+- missing `UPLOAD_LOCATION`
+
+If the user asks for scaffolding, generate a sample env file with obvious placeholders.
+
+Even when the user does not explicitly ask for scaffolding, produce a candidate env result when that materially advances the migration.