Update docs to reflect task locations

Author: Martin Jackson

README.md

@@ -11,6 +11,8 @@ loading local secrets files into VP secrets stores.
 
 ## SS CSI workload auth notes
 
+SS CSI task files live in **`roles/vault_utils/tasks/ss_csi/`**; paths below match **`include_tasks`** from the role (**`ss_csi/<file>`** relative to **`tasks/`**).
+
 `vault_utils` can read `ssCsiWorkloadAuth` entries from clustergroup values and
 create Vault Kubernetes auth roles for hub and spoke workloads.
 
@@ -46,11 +48,11 @@ and a merged **`clusterGroup.managedClusterGroups`**. It collects:
 
 Rows are appended to **`_ss_csi_all_entries`**, split into hub vs spoke using
 the computed **`cluster`** field (from stem or managed group when omitted in YAML), then **hub** identities get Vault Kubernetes
-auth roles via **`vault_ss_csi_apply_one_hub_sscsi_role.yaml`**. Spoke rows are
-normalized to **`vault_path`** later in the play (**`vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml`**
+auth roles via **`ss_csi/vault_ss_csi_apply_one_hub_sscsi_role.yaml`**. Spoke rows are
+normalized to **`vault_path`** later in the play (**`ss_csi/vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml`**
 during **`vault_spokes_init`**) and roles are written on each spoke mount
-(**`vault_ss_csi_apply_one_spoke_sscsi_role.yaml`**). Role names use
-**`<mount>-sscsi-<slug>`**; slugs come from **`vault_ss_csi_compute_role_slug.yaml`**.
+(**`ss_csi/vault_ss_csi_apply_one_spoke_sscsi_role.yaml`**). Role names use
+**`<mount>-sscsi-<slug>`**; slugs come from **`ss_csi/vault_ss_csi_compute_role_slug.yaml`**.
 
 To **inspect** stems and files locally, run **`playbooks/list_clustergroups.yml`**
 or **`playbooks/parse_clustergroup_values.yml`** (see **`roles/clustergroup_discovery/README.md`**).

roles/vault_utils/README.md

@@ -62,13 +62,13 @@ This role can create Vault Kubernetes auth roles from
 
 Implementation is split into **parsing** (load YAML), **extraction** (collect
 `ssCsiWorkloadAuth` rows), and **projection** (normalize and write Vault
-Kubernetes auth roles). Task entry points:
+Kubernetes auth roles). Task files live under **`tasks/ss_csi/`** (other role tasks include them as **`ss_csi/<filename>`**). Entry points:
 
 | Stage | Primary task files |
 | ----- | -------------------- |
-| Parsing | `vault_ss_csi_load_clustergroup_values.yaml` (router), `vault_ss_csi_load_merged_clustergroup_values.yaml`, `vault_ss_csi_load_one_clustergroup_values_fragment.yaml`, `vault_ss_csi_load_clustergroup_values_legacy.yaml` |
-| Extraction | `vault_ss_csi_workload_auth.yaml`, `vault_ss_csi_collect_applications_for_stem.yaml`, `vault_ss_csi_collect_one_application.yaml`, `vault_ss_csi_collect_one_entry.yaml`, `vault_ss_csi_collect_managed_group_application.yaml` |
-| Projection | `vault_ss_csi_apply_one_hub_sscsi_role.yaml`, `vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml` (in `vault_spokes_init`), `vault_ss_csi_apply_one_spoke_sscsi_role.yaml`, `vault_ss_csi_compute_role_slug.yaml` |
+| Parsing | `ss_csi/vault_ss_csi_load_clustergroup_values.yaml` (router), `ss_csi/vault_ss_csi_load_merged_clustergroup_values.yaml`, `ss_csi/vault_ss_csi_load_one_clustergroup_values_fragment.yaml`, `ss_csi/vault_ss_csi_load_clustergroup_values_legacy.yaml` |
+| Extraction | `ss_csi/vault_ss_csi_workload_auth.yaml`, `ss_csi/vault_ss_csi_collect_applications_for_stem.yaml`, `ss_csi/vault_ss_csi_collect_one_application.yaml`, `ss_csi/vault_ss_csi_collect_one_entry.yaml`, `ss_csi/vault_ss_csi_collect_managed_group_application.yaml` |
+| Projection | `ss_csi/vault_ss_csi_apply_one_hub_sscsi_role.yaml`, `ss_csi/vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml` (in `vault_spokes_init`), `ss_csi/vault_ss_csi_apply_one_spoke_sscsi_role.yaml`, `ss_csi/vault_ss_csi_compute_role_slug.yaml` |
 
 ### Parsing
 
@@ -100,33 +100,33 @@ and `vault_ss_csi_clustergroup_configmap_key_candidates` as needed for your patt
 
 ### Extraction
 
-**`vault_ss_csi_workload_auth.yaml`** (included from `vault_secrets_init.yaml`):
+**`ss_csi/vault_ss_csi_workload_auth.yaml`** (included from `vault_secrets_init.yaml`):
 
 1. Parses **`_vault_ss_csi_values_root`** into **`_vault_ss_csi_cluster_apps`**
    and **`_vault_ss_csi_managed_cluster_groups`** (merged views).
 2. Ensures **`_vault_ss_csi_apps_by_stem`** exists: after a multi-stem merge it is
    filled by fragments; for legacy single-document load it is set to
    `{ <main>: <applications> }`.
 3. Walks **`clustergroup_load_order`** (or `[main]` if unset) via
-   **`vault_ss_csi_collect_applications_for_stem.yaml`**: for each stem, every
+   **`ss_csi/vault_ss_csi_collect_applications_for_stem.yaml`**: for each stem, every
    application that defines **`ssCsiWorkloadAuth`** is passed to
-   **`vault_ss_csi_collect_one_entry.yaml`**. Omit **`cluster`** in values: Ansible
+   **`ss_csi/vault_ss_csi_collect_one_entry.yaml`**. Omit **`cluster`** in values: Ansible
    sets **`cluster`** to **`hub`** when the stem is the main clustergroup, else to
    the **stem string** (entries under `values-<managed>.yaml` default to that managed context).
-4. Walks merged **`managedClusterGroups`** via **`vault_ss_csi_collect_managed_group_application.yaml`**
+4. Walks merged **`managedClusterGroups`** via **`ss_csi/vault_ss_csi_collect_managed_group_application.yaml`**
    (omit **`cluster`**: nested apps default to the group **`name`**, else the group YAML key).
 
 ### Projection
 
 Collected rows become **`_ss_csi_all_entries`**, then:
 
 - **Hub mount** (`auth/<vault_hub>/role/...`): entries whose computed **`cluster`** is
-  `hub`, `local-cluster`, or empty — **`vault_ss_csi_apply_one_hub_sscsi_role.yaml`**
-  runs on the hub (**`vault_ss_csi_compute_role_slug.yaml`** for slug).
+  `hub`, `local-cluster`, or empty — **`ss_csi/vault_ss_csi_apply_one_hub_sscsi_role.yaml`**
+  runs on the hub (**`ss_csi/vault_ss_csi_compute_role_slug.yaml`** for slug).
 - **Spoke mounts**: other entries stay in **`_ss_csi_spoke_entries_raw`** until
-  **`vault_spokes_init`** runs **`vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml`**
+  **`vault_spokes_init`** runs **`ss_csi/vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml`**
   (match ACM / ESO, set internal **`cluster`** to **`vault_path`**), then
-  **`vault_ss_csi_apply_one_spoke_sscsi_role.yaml`** per spoke.
+  **`ss_csi/vault_ss_csi_apply_one_spoke_sscsi_role.yaml`** per spoke.
 
 Vault Kubernetes auth **role names** use the form **auth mount + `-sscsi-` + slug**. They must satisfy
 Vault path rules (non-empty slug, no trailing `-`, bounded length on some versions).

secrets-initialization-and-vault-unseal.md

@@ -10,7 +10,7 @@ This document describes how Vault and application secrets are bootstrapped when
   1. **`pattern_settings`** — Resolves `pattern_dir` (extra var, `PATTERN_DIR`,
      then `PWD` / `pwd`) and loads `values-global.yaml` (including
      `main.clusterGroupName` as `main_clustergroup`). When `pattern_settings` is
-     not in the play, **`vault_ss_csi_workload_auth`** repeats the same
+     not in the play, **`ss_csi/vault_ss_csi_workload_auth.yaml`** repeats the same
      `pattern_dir` resolution and, if needed, reads `values-global.yaml` under
      that directory to set `main_clustergroup` / `main_clustergroupname` before
      loading merged clustergroup values.
@@ -111,23 +111,23 @@ Summary:
 SS CSI workload auth runs from **`include_tasks: ss_csi/vault_ss_csi_workload_auth.yaml`**
 (inside **`vault_secrets_init.yaml`**). The pipeline is:
 
-1. **Parsing** — **`vault_ss_csi_load_clustergroup_values.yaml`** chooses merged
+1. **Parsing** — **`ss_csi/vault_ss_csi_load_clustergroup_values.yaml`** chooses merged
    multi-stem loading (**`vault_ss_csi_aggregate_clustergroup_sources`**, default
    true) or **legacy** single-document loading. Merged mode runs
    **`clustergroup_discovery`** then, for each stem in **`clustergroup_load_order`**,
    loads **`ConfigMap` `values-<stem>`** (then optional **`values-<stem>.yaml|yml`**
    under **`pattern_dir`**) and merges **`clusterGroup.applications`** and
    **`clusterGroup.managedClusterGroups`**. See **`roles/vault_utils/README.md`**
-   (SS CSI) for variables and task filenames.
+   (SS CSI) for variables and task filenames under **`tasks/ss_csi/`**.
 2. **Extraction** — Builds per-stem **`_vault_ss_csi_apps_by_stem`** and collects
    **`ssCsiWorkloadAuth`** from **`clusterGroup.applications`** per stem (omit
    **`cluster`** in values: main stem resolves to **hub**; other stems to the
    **stem name**) and from merged **`clusterGroup.managedClusterGroups.*.applications`**
    (omit **`cluster`**; defaults to managed group **`name`** or YAML key).
-3. **Projection** — Hub-classified rows get **`vault_ss_csi_apply_one_hub_sscsi_role`**;
+3. **Projection** — Hub-classified rows get **`ss_csi/vault_ss_csi_apply_one_hub_sscsi_role.yaml`**;
    spoke rows are normalized to **`vault_path`** during **`vault_spokes_init`**
-   (**`vault_ss_csi_normalize_spoke_entries_to_vault_path`**) and written with
-   **`vault_ss_csi_apply_one_spoke_sscsi_role`**.
+   (**`ss_csi/vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml`**) and written with
+   **`ss_csi/vault_ss_csi_apply_one_spoke_sscsi_role.yaml`**.
 
 **Defaults:** ConfigMaps live in **`openshift-gitops`** unless
 **`vault_ss_csi_clustergroup_configmap_namespace`** is changed; YAML is read from
@@ -136,10 +136,10 @@ data keys in **`vault_ss_csi_clustergroup_configmap_key_candidates`** unless
 **`clusterGroup`**. Set **`vault_ss_csi_clustergroup_values_from_configmap`** to
 false to force file-only reads. When **`vault_ss_csi_fallback_local_clustergroup_file`**
 is true, missing or unusable cluster data falls back to local files as implemented
-in **`vault_ss_csi_load_one_clustergroup_values_fragment.yaml`** / legacy tasks.
+in **`ss_csi/vault_ss_csi_load_one_clustergroup_values_fragment.yaml`** / legacy tasks.
 
 **Spoke cluster ID and charts:** Omit **`cluster`** in pattern `ssCsiWorkloadAuth` lists; Ansible derives it from stem or managed group. Before applying SS CSI roles on spokes,
-`**vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml`** rewrites each spoke row so **`cluster` equals `vault_path`**
+**`ss_csi/vault_ss_csi_normalize_spoke_entries_to_vault_path.yaml`** rewrites each spoke row so **`cluster` equals `vault_path`**
 (spoke FQDN) for every cluster that has External Secrets token data (`esoToken`).
 That matches Vault Kubernetes auth mounts and ESO.
 Pattern charts that render **`SecretProviderClass`** via **vp-sscsi-spc** should keep **`global.clusterDomain`** set to that same FQDN on the spoke; the library builds **`spec.parameters.roleName`** as **`<vaultKubernetesMountPath>-sscsi-<roleSlug>`**, using the FQDN mount path (not a short clustergroup label).