feat: add various adapter documentation and update completion adapter interface

Co-authored-by: Copilot <copilot@github.com>

Author: ivictbor

adminforth/documentation/docs/tutorial/05-Adapters/01-email-adapters.md

@@ -0,0 +1,21 @@
+# Email Adapters
+
+Used to send emails.
+
+[Email adapter base class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/EmailAdapter.ts#L17)
+
+## AWS SES Email Adapter
+
+```bash
+pnpm i @adminforth/email-adapter-aws-ses
+```
+
+Enables email delivery via [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/), suitable for high-volume, programmatic email sending.
+
+## Mailgun Email Adapter
+
+```bash
+pnpm i @adminforth/email-adapter-mailgun
+```
+
+Allows sending transactional or marketing emails using [Mailgun](https://www.mailgun.com/), a developer-friendly email service.

adminforth/documentation/docs/tutorial/05-Adapters/02-oauth2-adapters.md

@@ -0,0 +1,53 @@
+# OAuth2 Adapters
+
+Used to authenticate users via OAuth 2.0 providers.
+
+[OAuth2Adapter source class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/OAuth2Adapter.ts#L9)
+
+## Google OAuth Adapter
+
+```bash
+pnpm i @adminforth/google-oauth-adapter
+```
+
+Supports Google sign-in to allow users to authenticate using their Google or Google Workspaces accounts.
+
+## GitHub OAuth Adapter
+
+```bash
+pnpm i @adminforth/github-oauth-adapter
+```
+
+Enables authentication via GitHub accounts, useful for developer tools and open-source apps.
+
+## Facebook OAuth Adapter
+
+```bash
+pnpm i @adminforth/facebook-oauth-adapter
+```
+
+Allows users to log in with Facebook credentials. Facebook OAuth is commonly used for social media integrations.
+
+## Keycloak OAuth Adapter
+
+```bash
+pnpm i @adminforth/keycloak-oauth-adapter
+```
+
+Connects AdminForth to an open-source [Keycloak](https://www.keycloak.org/) identity provider for enterprise-grade SSO (Single Sign-On).
+
+## Microsoft OAuth Adapter
+
+```bash
+pnpm i @adminforth/microsoft-oauth-adapter
+```
+
+Supports login through Microsoft accounts including Azure AD, Office365, and Outlook.com.
+
+## Twitch OAuth Adapter
+
+```bash
+pnpm i @adminforth/twitch-oauth-adapter
+```
+
+Adds support for Twitch authentication, useful for streaming or creator-oriented platforms.

adminforth/documentation/docs/tutorial/05-Adapters/03-image-generation-adapters.md

@@ -0,0 +1,25 @@
+# Image Generation Adapters
+
+Used for image-generating AI tools.
+
+[ImageGenerationAdapter source class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/ImageGenerationAdapter.ts#L32)
+
+## OpenAI Image Generation Adapter
+
+```bash
+pnpm i @adminforth/image-generation-adapter-openai
+```
+
+Uses OpenAI image generation models such as DALL·E, `gpt-image-1`, and `gpt-image-1.5` to generate images from text prompts.
+
+Up to the winter 2026 OpenAI models are one of the most powerful image generation models available, especially GPT-Image-1.5, which is why we started with them.
+
+## Gemini (Nano Banana) Image Generation Adapter
+
+```bash
+pnpm i @adminforth/image-generation-adapter-nano-banana
+```
+
+Uses the latest `gemini-3.1-flash-image-preview` model for instant image generation with text descriptions.
+
+This model is the top of the Nano Banana line as of 2026, combining the speed of the Flash series with the improved detail of version 3.1. The adapter lets you integrate the advanced capabilities of previous models into your interface and generate precise visuals even for specific or complex prompts.

adminforth/documentation/docs/tutorial/05-Adapters/04-storage-adapters.md

@@ -0,0 +1,21 @@
+# Storage Adapters
+
+Used for storing files.
+
+[StorageAdapter source class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/StorageAdapter.ts#L8)
+
+## Amazon S3 Storage Adapter
+
+```bash
+pnpm i @adminforth/storage-adapter-amazon-s3
+```
+
+Stores uploaded files in [Amazon S3](https://aws.amazon.com/s3/), providing scalable cloud storage. It can be forked and customized to work with S3-compatible services such as MinIO, Wasabi, or other third-party S3 providers.
+
+## Local Storage Adapter
+
+```bash
+pnpm i @adminforth/storage-adapter-local
+```
+
+Stores files locally on the server filesystem. It is suitable for development or small self-hosted setups, but cloud storage is generally a better production option for reliability and scalability.

adminforth/documentation/docs/tutorial/05-Adapters/05-ai-completion-adapters.md

@@ -0,0 +1,167 @@
+# AI Completion Adapters
+
+Used for AI-powered text completion.
+
+[CompletionAdapter source class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/CompletionAdapter.ts#L16)
+
+Feel free to fork and implement other models, including Anthropic, Google Gemini, or any other AI model that supports text completion.
+
+## Common `complete()` signature
+
+All completion adapters implement the same `complete()` method signature from the shared `CompletionAdapter` interface.
+
+```ts
+complete({
+  content: string,
+  maxTokens: number,
+  outputSchema?: any,
+  reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh',
+  tools?: CompletionTool[],
+  onChunk?: (
+    chunk: string,
+    event?: {
+      type: 'output' | 'reasoning';
+      delta: string;
+      text: string;
+      source?: 'summary' | 'text';
+    },
+  ) => void | Promise<void>,
+})
+```
+
+`reasoningEffort` is optional and defaults to `low` in the adapter implementation.
+
+## Using `json_schema`
+
+All completion adapters accept structured output through the shared `outputSchema` field in the request object. The example below uses the OpenAI adapter, but the same request shape is common for all completion adapters.
+
+```ts
+const adapter = new CompletionAdapterOpenAIResponses({
+  openAiApiKey: process.env.OPENAI_API_KEY as string,
+  model: 'gpt-5-mini',
+});
+
+const prompt = 'What is the capital of France? return json';
+
+adapter.complete({
+  content: prompt,
+  maxTokens: 200,
+  outputSchema: {
+    name: 'capital_response',
+    schema: {
+      type: 'object',
+      properties: {
+        capital: { type: 'string' },
+      },
+      required: ['capital'],
+    },
+  },
+}).then((resp) => {
+  console.log(resp);
+});
+```
+
+
+## Using streaming output and reasoning events
+
+All completion adapters accept `onChunk` inside the request object. The example below uses the OpenAI adapter, but the callback signature is common for all completion adapters.
+
+Streaming reasoning events depend on the selected model and provider response.
+
+```ts
+const adapter = new CompletionAdapterOpenAIResponses({
+  openAiApiKey: process.env.OPENAI_API_KEY as string,
+  model: 'gpt-5-mini',
+});
+
+await adapter.complete({
+  content: 'Think step by step and write a short answer about how ABS brakes work',
+  maxTokens: 300,
+  reasoningEffort: 'medium',
+  onChunk: async (chunk, event) => {
+    if (!event) return;
+
+    if (event.type === 'reasoning') {
+      console.log('Reasoning chunk:', event.delta);
+      return;
+    }
+
+    console.log('Output chunk:', event.delta);
+  },
+});
+```
+
+Then output will be like:
+
+```ts
+{ content: '{"capital":"Paris"}', finishReason: 'stop' }
+```
+
+
+## OpenAI Responses Completion Adapter
+
+```bash
+pnpm i @adminforth/completion-adapter-openai-responses
+```
+
+Integrates AdminForth with OpenAI's Responses API to provide AI-powered completion and conversational features.
+
+The older `@adminforth/completion-adapter-open-ai-chat-gpt` package is deprecated. Use this package instead.
+
+```ts
+import CompletionAdapterOpenAIResponses from '@adminforth/completion-adapter-openai-responses';
+
+new CompletionAdapterOpenAIResponses({
+  openAiApiKey: process.env.OPENAI_API_KEY as string,
+  model: 'gpt-5.2',
+  extraRequestBodyParameters: {
+    temperature: 0.7,
+    reasoning: {
+      effort: 'medium',
+    },
+  },
+}),
+```
+
+You can specify any GPT model you need. The default is `gpt-5-nano`.
+
+This adapter uses the OpenAI `responses` API.
+
+## Google Gemini Completion Adapter
+
+```bash
+pnpm i @adminforth/completion-adapter-google-gemini
+```
+
+Integrates AdminForth with Google Gemini models to provide AI-powered completion and conversational features.
+
+```ts
+import CompletionAdapterGoogleGemini from '@adminforth/completion-adapter-google-gemini';
+
+new CompletionAdapterGoogleGemini({
+  geminiApiKey: process.env.GEMINI_API_KEY as string,
+  model: 'gemini-3-pro-preview',
+  extraRequestBodyParameters: {
+    temperature: 0.7,
+  },
+}),
+```
+
+You can specify any Gemini model you need. The default is `gemini-3-flash-preview`.
+
+## Adding extra request body params
+
+There might be cases where you want to add extra body params to the request sent to the AI provider. For those cases you can use `extraRequestBodyParameters`:
+
+```ts
+import CompletionAdapterGoogleGemini from '@adminforth/completion-adapter-google-gemini';
+
+new CompletionAdapterGoogleGemini({
+  geminiApiKey: process.env.GEMINI_API_KEY as string,
+  model: 'gemini-3-pro-preview',
+  extraRequestBodyParameters: {
+    temperature: 0.7,
+    responseMimeType: 'application/json',
+  },
+}),
+```

adminforth/documentation/docs/tutorial/05-Adapters/06-image-analysis-adapters.md

@@ -0,0 +1,15 @@
+# Image Analysis Adapters
+
+Used for AI-powered image analysis.
+
+[ImageVisionAdapter source class](https://github.com/devforth/adminforth/blob/1efdc19e3bb7a5fc3b19106704e4ae8bb7c73276/adminforth/types/adapters/ImageVisionAdapter.ts#L1)
+
+These adapters can analyze image content, extract text from images, identify objects, describe scenes, and provide detailed image insights.
+
+## OpenAI Vision Adapter
+
+```bash
+pnpm install @adminforth/image-vision-adapter-openai --save
+```
+
+Integrates AdminForth with OpenAI to provide advanced AI-powered image analysis. It can describe image content, read and extract text from images, identify objects and people, and provide detailed visual insights.

adminforth/documentation/docs/tutorial/05-Adapters/07-key-value-adapters.md

@@ -0,0 +1,59 @@
+# Key-value Adapters
+
+Key-value adapters are used to store data in a key-value format. They provide a simple and efficient way to manage data where quick access to values based on unique keys is required.
+
+[Key-value adapter source class](https://github.com/devforth/adminforth/blob/86bb9236fed9e844fdb07688318c050641f9eb1c/adminforth/types/adapters/KeyValueAdapter.ts#L6)
+
+## RAM Adapter
+
+```bash
+pnpm i @adminforth/key-value-adapter-ram
+```
+
+The RAM adapter is a simple in-memory key-value store. It keeps data in process memory, so it is not suitable for multi-process deployments because each process would have its own isolated store. In that case you need a centralized KV adapter such as Redis.
+
+Pros:
+
+- Simplest to use and does not require an external daemon.
+
+Cons:
+
+- Suitable for single-process installations only.
+
+## Redis Adapter
+
+```bash
+pnpm i @adminforth/key-value-adapter-redis
+```
+
+Redis uses in-memory storage with $O(1)$ get complexity. It is a great fit for lightweight workloads that fit in RAM, and it also works well for multi-process or replica-based installations as a centralized store. If persistence across restarts is important, configure Redis persistence separately.
+
+```ts
+import RedisKeyValueAdapter from '@adminforth/key-value-adapter-redis';
+
+const adapter = new RedisKeyValueAdapter({
+  redisUrl: '127.0.0.1:6379',
+});
+
+adapter.set('test-key', 'test-value', 120);
+```
+
+## LevelDB Adapter
+
+```bash
+pnpm i @adminforth/key-value-adapter-leveldb
+```
+
+LevelDB uses disk storage with $O(\log n)$ get complexity. It is a good fit for large or persistent KV datasets that still require fast lookups but do not efficiently fit in RAM. This is a single-process adapter only, so multiple admin processes should not point to the same LevelDB directory.
+
+You can use replicas with isolated disks, but in that case the state will also be isolated between replicas.
+
+```ts
+import LevelDBKeyValueAdapter from '@adminforth/key-value-adapter-leveldb';
+
+const adapter = new LevelDBKeyValueAdapter({
+  dbPath: './testdb',
+});
+
+adapter.set('test-key', 'test-value', 120);
+```

adminforth/documentation/docs/tutorial/05-Adapters/08-captcha-adapters.md

@@ -0,0 +1,17 @@
+# Captcha Adapters
+
+Used to add captcha to the login screen.
+
+[Captcha adapter source class](https://github.com/devforth/adminforth/blob/65153408a119314dad339f452700e0937952034a/adminforth/types/adapters/CaptchaAdapter.ts#L5)
+
+## Cloudflare Adapter
+
+```bash
+pnpm i @adminforth/login-captcha-adapter-cloudflare
+```
+
+## reCaptcha Adapter
+
+```bash
+pnpm i @adminforth/login-captcha-adapter-recaptcha
+```