diff --git a/ansible-role/README.md b/ansible-role/README.md
new file mode 100644
index 0000000..cff0948
--- /dev/null
+++ b/ansible-role/README.md
@@ -0,0 +1,76 @@
+# dangerousthings.authforge
+
+Ansible role that installs and configures [AuthForge](https://github.com/dangerousthings/authforge),
+the FIDO2 / U2F / TOTP MFA stack for Ubuntu, on fleet hosts.
+
+The role:
+
+1. Adds the `ppa:dangerousthings/authforge` PPA.
+2. Installs `authforge-daemon`, `authforge-pam`, and `authforge-cli` (and
+   optionally `authforge-gui` for desktop fleets).
+3. Renders a TOML fleet policy file at `/etc/authforge/policy.d/90-fleet.conf`
+   from your variables.
+4. Restarts `authforge-daemon.service` whenever the policy file changes.
+5. Seeds first-login pending-enrollment flags via `authforgectl pending set`.
+
+The role talks to AuthForge exclusively through `authforgectl` and the
+documented config-file shape - it does not touch daemon state directly.
+
+## Requirements
+
+- Target host: Ubuntu 22.04 (jammy) or 24.04 (noble).
+- Control host: Ansible 2.14 or newer.
+- The host must be able to reach `ppa.launchpad.net` (or your internal
+  mirror - override `authforge_ppa` to point at it).
+
+## Role variables
+
+All variables and their defaults live in `defaults/main.yml`.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `authforge_install_gui` | `false` | Also install the `authforge-gui` package (only useful on desktop fleets). |
+| `authforge_ppa` | `ppa:dangerousthings/authforge` | Source PPA. Override to use an internal mirror. |
+| `authforge_stacks` | `{}` | Map of PAM stack name to `{ mode, methods }`. `mode` is one of `disabled`, `optional`, `required`. `methods` is a list e.g. `["fido2", "totp"]`. |
+| `authforge_storage_backend` | `per-user` | Credential storage backend. `per-user` writes under each user's home; `central` uses `authforge_storage_central_path`. |
+| `authforge_storage_central_path` | `""` | Path for the central storage backend. Ignored when `authforge_storage_backend` is `per-user`. |
+| `authforge_firstrun_methods` | `["fido2"]` | Methods accepted during first-login enrollment. |
+| `authforge_firstrun_deadline_hours` | `0` | Hours before an unenrolled pending user is locked out. `0` disables the deadline. |
+| `authforge_pending_users` | `[]` | List of `{ user, methods }` to mark as pending-enrollment. |
+
+## Example playbook
+
+```yaml
+- hosts: workstations
+  become: true
+  roles:
+    - role: dangerousthings.authforge
+      vars:
+        authforge_stacks:
+          sudo:
+            mode: required
+            methods: [fido2]
+          sshd:
+            mode: optional
+            methods: [fido2, totp]
+        authforge_pending_users:
+          - user: alice
+            methods: [fido2]
+```
+
+A runnable copy lives at `examples/playbook.yml`.
+
+## Idempotence notes
+
+- The `apt_repository`, `apt`, `template`, and `file` tasks are all
+  idempotent; only the `authforgectl pending set` loop is forced to
+  `changed_when: true` because the CLI does not currently expose a clean
+  "is this user already pending?" check that's cheap to call from Ansible.
+  Running `pending set` against an already-pending user is a no-op on
+  the daemon side.
+- The handler restarts `authforge-daemon` only when the policy file
+  contents actually change.
+
+## License
+
+Apache-2.0. Same as the rest of AuthForge.
diff --git a/ansible-role/examples/playbook.yml b/ansible-role/examples/playbook.yml
new file mode 100644
index 0000000..0cd8481
--- /dev/null
+++ b/ansible-role/examples/playbook.yml
@@ -0,0 +1,31 @@
+---
+# Example playbook that applies the dangerousthings.authforge role to a
+# fleet of headless Ubuntu workstations.
+#
+# Run from the parent of this `ansible-role/` directory with:
+#
+#   ansible-playbook -i inventory ansible-role/examples/playbook.yml
+#
+# (You'll need the role linked into your roles_path, or to install it from
+# Galaxy as `dangerousthings.authforge`.)
+
+- name: Roll out AuthForge to engineering workstations
+  hosts: workstations
+  become: true
+  roles:
+    - role: dangerousthings.authforge
+      vars:
+        authforge_install_gui: false
+        authforge_stacks:
+          sudo:
+            mode: required
+            methods:
+              - fido2
+        authforge_storage_backend: per-user
+        authforge_firstrun_methods:
+          - fido2
+        authforge_firstrun_deadline_hours: 72
+        authforge_pending_users:
+          - user: alice
+            methods:
+              - fido2