Add VSCode launch configuration standardization and documentation

AGENTS.md

@@ -147,6 +147,18 @@ Cache-related plugins (`cache_cargo`, `cache_node`, `cache_python`, etc.) manage
 
 ---
 
+## Query: "add/change VS Code debug launch configurations"
+
+| Scope | Path |
+|---|---|
+| All containers | `defaults/main.yml → devcontainer_defaults.vscode_launch_configurations` |
+| All python containers | `defaults/main.yml → devcontainer_plugins.python.vscode_launch_configurations` |
+| One container | `group_vars/all.yml → devcontainers[name=X].vscode_launch_configurations` |
+
+Renders to `<container_root>/.vscode/launch.json` (outside `.devcontainer/` — the Dev Container spec's `customizations.vscode` has no `launch` key). Only written when the merged list is non-empty. List merges are append-only (no override-by-name) — do not add plugin-level defaults that depend on per-project assumptions (binary names, entry files). See `roles/devcontainer_sync/defaults/main.yml → devcontainer_plugins.python` / `.django` / `.rust` for examples.
+
+---
+
 ## Query: "add an install step"
 
 | Scope | Path |

README.md

@@ -120,6 +120,7 @@ List values are merged with Ansible's `append_rp` behavior, preserving order whi
 
 - `plugins`
 - `vscode_extensions`
+- `vscode_launch_configurations`
 - `mounts`
 - `run_args`
 - `post_start_commands`
@@ -128,6 +129,8 @@ List values are merged with Ansible's `append_rp` behavior, preserving order whi
 - `initialize_commands`
 - `install_steps`
 
+List merges are append-only — there is no override-by-name. A plugin default that turns out wrong for a specific project can't be replaced per-container, only appended alongside. Keep plugin-level list defaults (especially `vscode_launch_configurations`) free of per-project assumptions (binary names, entry files, package names) for this reason.
+
 Scalar values such as `image`, `name`, `path`, `python_version`, and `update_remote_user_uid` are replaced by the container entry.
 
 The effective merge order is:
@@ -208,7 +211,7 @@ When `devcontainer_sync_backup_existing_dir` is enabled, a changed role-managed
 - `install.sh`
 - `aws_configure.sh` when the AWS plugin is selected
 
-Changes only to `.editorconfig` or files from `files/` do not trigger a whole-directory backup. `.editorconfig` and extra files use Ansible's individual file backup behavior when `devcontainer_sync_backup` is enabled.
+Changes only to `.editorconfig`, `.vscode/launch.json`, or files from `files/` do not trigger a whole-directory backup. `.editorconfig`, `.vscode/launch.json`, and extra files use Ansible's individual file backup behavior when `devcontainer_sync_backup` is enabled. `.vscode/launch.json` is only rendered when the merged `vscode_launch_configurations` list is non-empty for that container.
 
 Use `make rm-bak WORKSPACE_ROOT=/path/to/projects` to remove timestamped directory backups.