diff --git a/gnome-integration/README.md b/gnome-integration/README.md
new file mode 100644
index 0000000..a925057
--- /dev/null
+++ b/gnome-integration/README.md
@@ -0,0 +1,73 @@
+# authforge-gnome-integration
+
+Optional integration glue that surfaces the AuthForge GUI from inside
+`gnome-control-center`'s **Users** panel, so administrators and end users can
+reach FIDO2/U2F/TOTP enrollment from the same place they already manage
+account password and login options.
+
+## What this package ships
+
+A single XDG `.desktop` file installed to
+`/usr/share/applications/io.dangerousthings.AuthForge.UsersPanel.desktop`.
+
+The file is tagged with `X-GNOME-Settings-Panel=user-accounts`, which is the
+mechanism `gnome-control-center` (GNOME 46 / 47) uses to discover third-party
+"helpers" for a specific settings panel. Entries with this key appear inside
+the Users panel as an inline launcher rather than as a top-level app.
+
+`NoDisplay=true` keeps the entry out of the normal application grid — the
+full-fat AuthForge launcher (shipped by `authforge-gui`) already handles that
+case. This overlay exists *only* to provide the in-Settings hook.
+
+`OnlyShowIn=GNOME;` prevents KDE / Xfce / etc. from picking the entry up.
+Those desktops have their own settings frameworks and their own integration
+stories (out of scope for v1).
+
+## Why a `.desktop` overlay and not a JS extension?
+
+A GNOME Shell / `gnome-control-center` JS extension could in theory inject a
+richer widget directly into the Users panel. We considered it and chose the
+`.desktop` overlay instead because:
+
+- **Cross-version stability.** The internal panel layout and JS API change
+  between GNOME releases (44 → 45 → 46 → 47 all moved things). A `.desktop`
+  hook is a stable freedesktop-spec mechanism that has worked unchanged for
+  years.
+- **Packaging simplicity.** No GJS source, no shell-extension manifest, no
+  per-version compatibility matrix. Just a file in
+  `/usr/share/applications/`.
+- **Lowest-risk.** A miswritten extension can crash the whole shell. A
+  miswritten `.desktop` file is a no-op.
+
+JS-extension support is therefore **deferred** until upstream GNOME exposes
+a stable cross-version "embed a third-party page in the Users panel" API. If
+that ever lands we can ship it as a follow-up package; the `.desktop` overlay
+will continue to work alongside it as a graceful-degradation fallback.
+
+## Verifying the integration works
+
+After installing `authforge-gnome-integration` (which depends on
+`authforge-gui` and `gnome-control-center`):
+
+1. Log out and back in (or `killall gnome-shell` on X11) to refresh the
+   desktop-file cache, *or* run
+   `update-desktop-database /usr/share/applications`.
+2. Open **Settings** (`gnome-control-center`).
+3. Navigate to **Users**.
+4. Select a user account. The detail pane should now show a
+   **"Configure security…"** entry alongside the existing password / autologin
+   controls. Activating it launches the AuthForge GUI.
+
+If the entry does not appear, sanity-check with:
+
+```
+desktop-file-validate /usr/share/applications/io.dangerousthings.AuthForge.UsersPanel.desktop
+gtk-launch io.dangerousthings.AuthForge.UsersPanel
+```
+
+The first command must report no errors; the second must launch the GUI.
+
+## Files
+
+- `io.dangerousthings.AuthForge.UsersPanel.desktop` — the overlay entry,
+  installed to `/usr/share/applications/` by the deb.
diff --git a/gnome-integration/io.dangerousthings.AuthForge.UsersPanel.desktop b/gnome-integration/io.dangerousthings.AuthForge.UsersPanel.desktop
new file mode 100644
index 0000000..ac1f14c
--- /dev/null
+++ b/gnome-integration/io.dangerousthings.AuthForge.UsersPanel.desktop
@@ -0,0 +1,13 @@
+[Desktop Entry]
+Name=Configure security…
+GenericName=Authentication keys & MFA
+Comment=Manage U2F/FIDO2 keys and authentication policy for this account
+Exec=authforge
+Icon=io.dangerousthings.AuthForge
+Terminal=false
+Type=Application
+NoDisplay=true
+X-GNOME-Settings-Panel=user-accounts
+X-GNOME-Single-Window=true
+OnlyShowIn=GNOME;
+Keywords=mfa;u2f;fido2;passkey;totp;security;