docs: enhance Frontegg authentication documentation with detailed setup instructions and visual aids

- Expanded the Frontegg section to include comprehensive setup steps, benefits, and troubleshooting guidance.
- Introduced multiple new images to illustrate the configuration process, application settings, and user interface elements for better clarity.
- Improved overall documentation structure to facilitate easier navigation and understanding for users integrating Frontegg with Palmr.

apps/docs/content/docs/3.1-beta/oidc-authentication/frontegg.mdx

@@ -3,10 +3,322 @@ title: Frontegg
 icon: Egg
 ---
 
-## Frontegg
+import { ZoomableImage } from "@/components/ui/zoomable-image";
 
-### Prerequisites
+Frontegg is one of Palmr's officially supported OIDC providers, offering enterprise-grade authentication through Frontegg's identity platform. This integration allows users to sign in to Palmr using Frontegg's comprehensive authentication system, making it perfect for enterprise organizations, applications requiring advanced security features, and teams that need centralized identity management with modern developer experience.
 
-- Frontegg Application
-- Frontegg OAuth Client ID and Secret
-- Frontegg OAuth Redirect URI
+<ZoomableImage src="/assets/v3/oidc/frontegg/sign-in-with-frontegg.png" alt="Sign in with Frontegg" />
+
+## Why use Frontegg authentication?
+
+Frontegg authentication provides several advantages for enterprise and developer-focused organizations:
+
+- **Modern developer experience** - Clean APIs, comprehensive SDKs, and developer-friendly tools
+- **Enterprise-grade security** - Advanced security features like MFA, adaptive authentication, and threat detection
+- **Centralized identity management** - Single platform to manage users across multiple applications
+- **Compliance ready** - Built-in compliance with GDPR, SOC 2, and other enterprise standards
+- **Advanced customization** - Themes, flows, and custom branding capabilities
+
+---
+
+## Prerequisites
+
+Before configuring Frontegg authentication, ensure you have:
+
+- **Frontegg account** - Ability to create applications and manage tenants
+- **Admin privileges in Palmr** - Required to configure OIDC settings
+- **Domain configuration** - For production deployments with custom domains
+
+> **Note:** Frontegg is pre-configured as an official provider in Palmr, which means the technical configuration is handled automatically. You only need to provide your OAuth credentials.
+
+---
+
+## Setting up Frontegg Application
+
+### Creating a Frontegg application
+
+To get started with Frontegg authentication, you'll need to create an application in your Frontegg Admin Portal.
+
+1. **Navigate to Frontegg Admin Portal**: Go to [https://portal.frontegg.com/development/applications](https://portal.frontegg.com/development/applications) for example. (Development environment) for production environment you need to go to [https://portal.frontegg.com/production/applications](https://portal.frontegg.com/production/applications) - This can change depending on your environment.
+
+<ZoomableImage src="/assets/v3/oidc/frontegg/frontegg-admin.png" alt="Frontegg Admin Portal" />
+
+2. **Create new application**: Click **"Create new"**
+
+3. **Fill application details**:
+   - **Name**: Enter a descriptive name like "Palmr File Sharing"
+   - **Description**: Add a clear description of your Palmr instance
+   - **Type**: Choose **"Web"** for web-based Palmr instances
+   - **Frontend stack**: Choose **"React"** for web-based Palmr instances
+   - **App URL**: Add the URL of your Palmr instance, see table below for the example of the URL.
+
+   | Environment | URL                                                                |
+   | ----------- | ------------------------------------------------------------------ |
+   | Production  | `https://yourdomain.com/api/auth/providers/frontegg/callback`      |
+   | Development | `http://localhost:3000/api/auth/providers/frontegg/callback`       |
+   | Custom Port | `https://yourdomain.com:5487/api/auth/providers/frontegg/callback` |
+
+   > **Note:** Replace `yourdomain.com` with your actual domain name in all production and custom port URLs.
+
+<ZoomableImage
+  src="/assets/v3/oidc/frontegg/application-details.png"
+  alt="Frontegg Application Details"
+  legend="This is a fake application, you have to use your own."
+/>
+
+5. **Create application**: Click **"Create"** to generate your Frontegg application
+
+### Configuring application settings
+
+After creating your application, you'll need to get the settings that Palmr will use. You gonna be redirected to the application page, where you can see the application details.
+
+<ZoomableImage
+  src="/assets/v3/oidc/frontegg/application-page.png"
+  alt="Frontegg Application Page"
+  legend="This is a fake application, you have to use your own."
+/>
+
+### Getting OAuth credentials
+
+Now you'll get the credentials that Palmr will use to authenticate with Frontegg.
+
+1. **Copy Domain**: Note your Frontegg domain (e.g., `your-tenant.frontegg.com`) - You can find it in the application page at field **"Login URL"**. But copy just the domain, without the path.
+
+2. **Copy Client ID**: You can find it in the application page at field **"ID"** in the application page.
+
+3. **Copy Client Secret**: You can find it in the application page at field **"API key"** in the application page.
+
+In Frontegg we finished the configuration, but we need to configure Palmr to use it.
+
+---
+
+## Configuring Palmr
+
+### Accessing OIDC settings
+
+To configure Frontegg authentication in Palmr, you need administrator access to the settings panel.
+
+1. **Login as administrator**: Sign in to Palmr with an admin account
+
+2. **Access settings**: Click your profile picture in the header and select **Settings**
+
+3. **Navigate to authentication**: Find and click on the **Authentication Providers** configuration section
+
+<ZoomableImage src="/assets/v3/oidc/auth-providers.png" alt="Palmr Authentication Providers" />
+
+### Enabling Frontegg provider
+
+Frontegg comes pre-configured as an official provider, so the setup process is streamlined.
+
+1. **Locate Frontegg provider**: Find Frontegg in the list of available providers
+
+2. **Enable the provider**: Toggle the status to **Enabled**
+
+<ZoomableImage src="/assets/v3/oidc/frontegg/enabled-frontegg.png" alt="Palmr Frontegg Provider Enabled" />
+
+After enabling the provider, click on the pen icon to configure the provider.
+
+3. **Configure credentials**:
+   - **Provider URL**: Paste your Frontegg domain (e.g., `https://your-tenant.frontegg.com`) - It's the same **Login URL** you copied in the previous step.
+   - **Client ID**: Paste the Client ID from Frontegg application - It's the same **ID** you copied in the previous step.
+   - **Client Secret**: Paste the Client Secret from Frontegg application - It's the same **API key** you copied in the previous step.
+   - **Scopes**: Add the scopes you want to use. The default scopes are `openid`, `profile`, and `email`. You don't need to change this, but you can if you want.
+
+<ZoomableImage
+  src="/assets/v3/oidc/frontegg/edit-frontegg.png"
+  alt="Edit Frontegg Provider"
+  legend="This is a fake application, you have to use your own."
+/>
+
+### Advanced configuration options
+
+Configure additional settings to customize the authentication behavior:
+
+**Auto Registration**: Enable this to automatically create user accounts when someone authenticates for the first time.
+
+**Sort Order**: Control where the Frontegg login button appears relative to other authentication providers.
+
+**Icon**: you can choose the icon you want to use for the Frontegg login button (default is `TbEggs`).
+
+<ZoomableImage src="/assets/v3/oidc/frontegg/frontegg-icon.png" alt="Frontegg Icon" />
+
+> **Developer tip:** Frontegg authentication works great for organizations requiring modern developer experience and enterprise-grade security features.
+
+---
+
+## Account linking
+
+By default, if a user is already registered in Palmr with their Frontegg email, they will be automatically linked to their Palmr account.
+
+> **Note:** You can't disable account linking. If you want to unlink a user from their Frontegg account, you need to delete the user from Palmr.
+
+---
+
+## Technical configuration
+
+Frontegg's technical configuration is handled automatically, but understanding the setup can help with troubleshooting:
+
+```yaml
+Provider Type: OAuth 2.0 with OIDC Discovery
+Issuer URL: https://your-tenant.frontegg.com
+Authorization Endpoint: /oauth/authorize
+Token Endpoint: /oauth/token
+UserInfo Endpoint: /oauth/userinfo
+Scopes: openid profile email
+```
+
+### Field mappings
+
+Palmr automatically maps Frontegg user information to local user accounts:
+
+- **User ID**: Maps from Frontegg's `sub` field
+- **Email**: Maps from Frontegg's `email` field
+- **Full Name**: Maps from Frontegg's `name` field
+- **First Name**: Maps from Frontegg's `given_name` field
+- **Last Name**: Maps from Frontegg's `family_name` field
+- **Avatar**: Maps from Frontegg's `picture` field
+- **Username**: Maps from Frontegg's `preferred_username` field
+
+### Frontegg-specific features
+
+- **Custom Claims**: Can include custom user metadata and app metadata
+- **Themes Support**: Can customize authentication UI with custom themes
+- **Multi-factor Authentication**: Supports Frontegg's MFA features
+- **Enterprise SSO**: Integrates with SAML, LDAP, and other enterprise systems
+- **Modern APIs**: Clean REST APIs and comprehensive SDKs
+
+---
+
+## Testing the configuration
+
+### Verifying the setup
+
+After configuring Frontegg authentication, test the integration to ensure everything works correctly.
+
+1. **Check login page**: Navigate to your Palmr login page and verify the "Sign in with Frontegg" button appears
+
+2. **Test authentication flow**: Click the Frontegg sign-in button and complete the authentication process
+
+3. **Verify user creation**: Confirm that a new user account is created (if auto-registration is enabled)
+
+### Login flow verification
+
+The complete authentication process should work as follows:
+
+1. **User clicks "Sign in with Frontegg"**: The browser redirects to Frontegg's authorization page
+2. **User authenticates**: User completes authentication through Frontegg (login, MFA, etc.)
+3. **Frontegg redirects back to Palmr**: User returns to Palmr with authentication tokens
+4. **Palmr creates or updates user**: User account is automatically managed with Frontegg information
+5. **User accesses Palmr**: User is logged in with their Frontegg identity
+
+---
+
+## Troubleshooting common issues
+
+### Redirect URI mismatch error
+
+**Error message**: `invalid_redirect_uri`
+
+**Cause**: The redirect URI in your request doesn't match what's configured in Frontegg application.
+
+**Solution**:
+
+1. Check the exact URL in the error message
+2. Add this exact URL to your Frontegg application's redirect URIs
+3. Ensure you include the correct protocol (http/https) and port
+4. Remove any trailing slashes unless they're in the callback URL
+
+### Access denied error
+
+**Error message**: `access_denied`
+
+**Cause**: User denied permissions or the application isn't properly configured.
+
+**Solution**:
+
+1. Verify that your Frontegg application requests the correct scopes
+2. Check that users are granting permissions during the authorization flow
+3. Ensure your application is not restricted or disabled
+4. Verify the application has proper permissions set up
+
+### Invalid client error
+
+**Error message**: `invalid_client`
+
+**Cause**: Incorrect Client ID, Client Secret, or Domain.
+
+**Solution**:
+
+1. Double-check that you've copied the credentials correctly from Frontegg
+2. Ensure there are no extra spaces or characters in the credentials
+3. Verify you're using the correct domain format (e.g., `your-tenant.frontegg.com`)
+4. Generate a new Client Secret if necessary
+
+### Domain configuration issues
+
+**Error message**: Domain not found or invalid
+
+**Cause**: Incorrect Frontegg domain or tenant configuration.
+
+**Solution**:
+
+1. Verify your Frontegg domain is correct (e.g., `your-tenant.frontegg.com`)
+2. Check that your Frontegg tenant is active and not suspended
+3. Ensure you're using the correct region for your tenant
+4. Verify DNS resolution for your Frontegg domain
+
+### Custom claims not available
+
+**Cause**: Custom claims not properly configured in Frontegg.
+
+**Solution**:
+
+1. Check Frontegg custom claims configuration
+2. Verify that custom claims are included in the ID token
+3. Ensure the claims are properly formatted and accessible
+4. Test with a user that has the expected custom claims
+
+---
+
+## Security best practices
+
+### Credential management
+
+- **Never expose secrets**: Keep your Client Secret secure and never commit it to version control
+- **Rotate credentials regularly**: Generate new Client Secrets periodically for enhanced security
+- **Use environment variables**: Store sensitive configuration in environment variables, not config files
+- **Monitor access logs**: Regularly review authentication logs for suspicious activity
+
+### Scope and permission management
+
+- **Minimal scopes**: Only request `openid`, `profile`, and `email` scopes as required by Palmr
+- **User consent**: Ensure users understand what permissions they're granting
+- **Regular audits**: Review which users have connected their Frontegg accounts
+- **Access reviews**: Periodically check user access and remove inactive accounts
+
+### Production considerations
+
+- **Use HTTPS**: Always use HTTPS in production environments
+- **Configure proper domains**: Use production domains in Frontegg application settings
+- **Test thoroughly**: Verify the complete authentication flow before going live
+- **Plan for failures**: Have fallback authentication methods available
+
+---
+
+## Next steps
+
+With Frontegg authentication configured, you might want to:
+
+- **Configure additional providers**: Set up other OIDC providers for more authentication options
+- **Customize user management**: Fine-tune auto-registration and admin assignment rules
+- **Review security settings**: Ensure your authentication setup meets your security requirements
+- **Monitor usage**: Keep track of authentication patterns and user activity
+
+For more information about OIDC authentication in Palmr, see the [OIDC Authentication overview](/docs/3.1-beta/oidc-authentication).
+
+## Useful resources
+
+- [Frontegg Documentation](https://docs.frontegg.com)
+- [Frontegg OAuth 2.0 Guide](https://docs.frontegg.com/oauth2)
+- [Frontegg OpenID Connect](https://docs.frontegg.com/openid-connect)
+- [Frontegg Admin Portal](https://admin.frontegg.com)