diff --git a/README.md b/README.md
index 1ac2f05..db271b2 100644
--- a/README.md
+++ b/README.md
@@ -290,13 +290,23 @@ The file will be copied as-is to the application directory without Jinja2 proces
 
 ## Configuration Reference
 
+### Required Externals
+
+These variables have no defaults and must be set by the calling playbook (typically as group_vars or host_vars). They are consumed by the defaults shown further down; if you override every derived variable that uses them, you can leave the corresponding external unset.
+
+| Variable | Description | Consumed by |
+|----------|-------------|-------------|
+| `host_root_path` | Base directory on the **target host** under which each app's directory is created (e.g. `/srv/apps`, `/opt/docker`) | `app_dir` |
+| `backup_path` | Base directory on the **controller** where fetched backup archives are stored (e.g. `~/backups`) | `app_backup_path` |
+| `app_roles_path` | Absolute path to the roles directory that contains your per-app shim roles; used so this role can locate the shim role's `templates/` directory (e.g. `{{ playbook_dir }}/roles`) | `app_templates_path` |
+| `app_role_name` | Name of the per-app shim role that depends on this one (e.g. `my-app`, `jellyfin`); combined with `app_roles_path` to find its `templates/` directory | `app_templates_path` |
+
 ### Core Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `app_name` | Required | Unique application instance name |
-| `role_name` | Required | Role name for template paths |
-| `app_dir` | `{{ host_root_path }}/{{ app_name }}` | Application directory |
+| `app_dir` | `{{ host_root_path }}/{{ app_name }}` | Application directory on the target host |
 | `app_uid` | `{{ ansible_facts.user_uid }}` | File ownership UID |
 | `app_gid` | `{{ ansible_facts.user_gid }}` | File ownership GID |
 | `app_permission_mode` | `"0640"` | File permission mode |