-
{% endblock %}
\ No newline at end of file
diff --git a/docs/configuration.md b/docs/configuration.md
index 9b31a26..66a7b5b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,9 +1,12 @@
-# Configuration methods
+# UI Configuration
-Currently, the only available configuration method is YAML in your `configuration.yaml` file. In the future, we will also add limited UI configuration for the most common configurations (Authentik, Authelia and Pocket-ID). Advanced users will need to use the YAML configuration in any case.
+If you want to use the (limited) UI configuration method, please see [the README](../README.md).
# YAML Configuration
-For now, this integration is configured using YAML in your `configuration.yaml` file. By default, only two fields are required:
+
+You can configure this integration using YAML in your `configuration.yaml` file. All features of the integrations will always be available within the YAML configuration.
+
+By default, only two fields are required:
```yaml
auth_oidc:
@@ -157,7 +160,6 @@ Here's a table of all options that you can set:
| `features.automatic_person_creation` | `boolean` | No | `true` | Automatically creates a person entry for new user profiles created by this integration. Recommended if you would like to assign presence detection to OIDC users. |
| `features.disable_rfc7636` | `boolean`| No | `false` | Disables PKCE (RFC 7636) for OIDC providers that don't support it. You should not need this with most providers. |
| `features.include_groups_scope` | `boolean` | No | `true` | Include the 'groups' scope in the OIDC request. Set to `false` to exclude it. |
-| `features.disable_frontend_changes` | `boolean` | No | `false` | Set to `true` to disable all changes made to the HA frontend for better compatbility with future HA versions, or if you are not comfortable with injecting Javascript into the existing frontend code. |
| `features.force_https` | `boolean` | No | `false` | Set to `true` to force all URLs generated to use `https` instead of automatically determining based on the request scheme or `X-Forwarded-Proto`. |
| `claims.display_name` | `string` | No | `name` | The claim to use to obtain the display name.
| `claims.username` | `string` | No | `preferred_username` | The claim to use to obtain the username.
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 0000000..4b2c2d5
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,41 @@
+# Frequently Asked Questions
+
+## What are the values of this project? Why would I choose this integration over alternatives?
+
+Provides a **stable and secure** OpenID Connect (OIDC) implementation for Home Assistant through a custom component/integration. With this integration, you can create a single-sign-on (SSO) environment in your self-hosted application stack / homelab.
+
+The core values for this integration are:
+
+1. **Security**: strict adherence to the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html), [RFC 6749 (OAuth2)](https://datatracker.ietf.org/doc/html/rfc6749), [RFC 7519 (JWT)](https://datatracker.ietf.org/doc/html/rfc7519), [RFC 7636 (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) and [RFC 9700 (OAuth2 Security Best Practices)](https://datatracker.ietf.org/doc/html/rfc9700) as well as a focus on security tests in the automated test suite.
+2. **Stability**: minimal patching of the core Home Assistant code such that updates of HA are less likely to break the integration and leave you without a way to login.
+3. **Accessibility**: the integration should work for everyone as much as possible with default settings, regardless of your preferred authentication method.
+
+**TLDR**: *Login to Home Assistant with this integration should 'just work', every time, for everyone in your household ([even your dad](https://github.com/home-assistant/architecture/issues/832#issuecomment-1328052330)), securely.*
+
+## Is the integration stable?
+
+Yes, this integration has been tested in production environments for multiple years and has almost full automated test coverage to test both security and regressions. Security issues as well as dependency updates are actively monitored through automated pipelines and [a security policy is available here](./SECURITY.md).
+
+## What does this integration not do (yet)?
+
+The integration is currently very suitable for homelab use, but not for enterprise use, because these specs/todos have not been implemented yet:
+
+- [OpenID Connect Session Management 1.0](https://openid.net/specs/openid-connect-session-1_0.html): users that are disabled at the IdP do not get logged out in Home Assistant until their refresh token expires/they logout manually
+- [OpenID Connect Front-Channel Logout 1.0](https://openid.net/specs/openid-connect-frontchannel-1_0.html): logout in Home Assistant does not automatically log the user out at the IdP
+- [OpenID Connect Back-Channel Logout 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-backchannel-1_0.html)
+- *Open TODO*: Permissions are only set upon first login (https://github.com/christiaangoossens/hass-oidc-auth/discussions/187), as permission changes would necessitate revoking refresh tokens/implementing session management
+- Other RFC's and best practices with regards to token expiration and revocation in the app itself
+
+These features are hard to implement correctly within a custom integration, as they involve the full authentication lifecycle. Home Assistant does currently implement some features to see which refresh tokens were issued (and thus which sessions are open), which work well with this integration, but lacks any further security focussed features.
+
+For home use where users rarely change permissions/status, these features aren't commonly required. However, if you would like to help implement any of these specifications (while sticking to the value of 'Stability' and minimal Home Assistant core code patching), feel free to create a PR.
+
+## Why does this integration only allow for sign-in on mobile with a device code?
+Several attempts have been made at implementing a direct mobile sign-in, but due to many issues (which can be found in https://github.com/orgs/home-assistant/discussions/48 and https://github.com/christiaangoossens/hass-oidc-auth/discussions/95), an approach was chosen that works for all setups and all authentication methods. The mobile apps now show a code, which can be entered into either the Chrome (Android)/Safari (iOS) apps on the mobile device or on another computer, after which the app automatically links and continues with the setup.
+
+If you would like to make another attempt at implementing direct sign-in anyway, please submit a PR.
+
+## I am using a proxy setup where my reverse proxy authenticates users
+This integration is intended to be public-facing (as most OIDC apps). If you are authenticating users at the reverse proxy level (such as if you are migrating from https://github.com/BeryJu/hass-auth-header), **you should remove this authentication layer after installing this integration.**.
+
+In general, make sure to set your Home Assistant configuration correctly for your reverse proxy as well (see https://www.home-assistant.io/integrations/http/#reverse-proxies). It is important that the original visitor IP is passed through to Home Assistant for optimal security.
\ No newline at end of file
diff --git a/docs/usage.md b/docs/usage.md
index 65401c7..f07d633 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,84 +1,3 @@
-# How do I use the OIDC Integration for Home Assistant?
+# Usage Guide
-Here's a step by step guide to use the integration:
-
-### Step 1: HACS
-Install the integration through [HACS](https://hacs.xyz/). You can add it automatically using the button below, or use the Github URL and type `Integration` in the manual Custom Repository add dialog.
-
-[](https://my.home-assistant.io/redirect/hacs_repository/?owner=christiaangoossens&repository=hass-oidc-auth&category=Integration)
-
-
-### Step 2: Configuration of the integration
-The integration is currently configurable through YAML only. See the [Configuration Guide](./configuration.md) for more details or pick your OIDC provider below (additional providers are available in the Configuration Guide):
-
-|
- Use a code from another device
-
-
-
On your other device, open the Home Assistant app. You will see a +
Use a code from another device
+On your other device, open the Home Assistant app. You will see a 6-digit code.
Input that code here and click Approve to login on the other device.
@@ -60,7 +57,6 @@ Approve login on the other device -
| 
|