chore(release): update versions (#611)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.changeset/config.json

@@ -5,13 +5,11 @@
     { "repo": "papra-hq/papra"} 
   ],
   "commit": false,
-  "fixed": [
-    ["@papra/app-client", "@papra/app-server"]
-  ],
+  "fixed": [],
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": [],
+  "ignore": ["@papra/app-client", "@papra/app-server", "@papra/docs"],
   "privatePackages": {
     "tag": true,
     "version": true

.dockerignore

@@ -1,11 +0,0 @@
-node_modules
-.pnp
-.pnp.*
-*.log
-dist
-*.local
-.git
-db.sqlite
-local-documents
-.env
-**/.env

.dockerignore

@@ -0,0 +1 @@
+packages/docker/.dockerignore

.github/workflows/ci-apps-docs.yaml

@@ -1,42 +0,0 @@
-name: CI - Docs
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  ci-apps-docs:
-    name: CI - Docs
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: apps/docs
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm i
-        working-directory: ./
-
-      - name: Run linters
-        run: pnpm lint
-
-      # - name: Type check
-      #   run: pnpm typecheck
-
-      # - name: Run unit test
-      #   run: pnpm test
-
-      - name: Build the app
-        run: pnpm build

.github/workflows/ci-apps-papra-client.yaml

@@ -1,49 +0,0 @@
-name: CI - App Client
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  ci-apps-papra-client:
-    name: CI - Papra Client
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: apps/papra-client
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm i
-        working-directory: ./
-
-      - name: Run linters
-        run: pnpm lint
-
-      - name: Type check
-        run: pnpm typecheck
-
-      - name: Run unit test
-        run: pnpm test
-
-      # Ensure locales types are up to date, must be run before building the app
-      - name: Check locales types
-        run: |
-          pnpm script:generate-i18n-types
-          git diff --exit-code -- src/modules/i18n/locales.types.ts > /dev/null || (echo "Locales types are outdated, please run 'pnpm script:generate-i18n-types' and commit the changes." && exit 1)
-
-      - name: Build the app
-        run: pnpm build
-

.github/workflows/ci-apps-papra-server.yaml

@@ -1,43 +0,0 @@
-name: CI - App Server
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  ci-apps-papra-server:
-    name: CI - Papra Server
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: apps/papra-server
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: |
-          pnpm i --frozen-lockfile
-          pnpm --filter "@papra/app-server^..." build
-
-      - name: Run linters
-        run: pnpm lint
-
-      - name: Type check
-        run: pnpm typecheck
-
-      - name: Run unit test
-        run: pnpm test
-
-      - name: Build the app
-        run: pnpm build

.github/workflows/ci-packages-api-sdk.yaml

@@ -1,41 +0,0 @@
-name: CI - Api SDK
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  ci-packages-api-sdk:
-    name: CI - Api SDK
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: packages/api-sdk
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm i
-
-      - name: Run linters
-        run: pnpm lint
-
-      - name: Type check
-        run: pnpm typecheck
-
-      # - name: Run unit test
-      #   run: pnpm test
-
-      - name: Build the app
-        run: pnpm build

.github/workflows/ci-packages-cli.yaml

@@ -1,44 +0,0 @@
-name: CI - CLI
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  ci-packages-cli:
-    name: CI - CLI
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: packages/cli
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm i
-
-      - name: Build related packages
-        run: cd ../api-sdk && pnpm build
-
-      - name: Run linters
-        run: pnpm lint
-
-      - name: Type check
-        run: pnpm typecheck
-
-      # - name: Run unit test
-      #   run: pnpm test
-
-      - name: Build the app
-        run: pnpm build

.github/workflows/ci-packages-webhook.yaml

@@ -1,41 +0,0 @@
-name: CI - Webhooks
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  ci-packages-webhooks:
-    name: CI - Webhooks
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: packages/webhooks
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm i
-
-      - name: Run linters
-        run: pnpm lint
-
-      - name: Type check
-        run: pnpm typecheck
-
-      - name: Run unit test
-        run: pnpm test
-
-      - name: Build the app
-        run: pnpm build

.github/workflows/ci.yaml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  ci:
+    name: CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm i
+
+      # Build only the packages first to properly run the lint and test first to get faster feedback
+      - name: Build packages
+        run: pnpm -r --parallel -F "./packages/*" build
+
+      - name: Run linters
+        run: pnpm -r --parallel lint
+
+      - name: Type check
+        # Exclude docs as their are some typing issues we are ok with for now
+        run: pnpm -r --parallel -F "!@papra/docs" typecheck
+
+      # Tests are run using vitest projects
+      - name: Run tests
+        run: pnpm test
+
+      # Now build the apps, the longer step, so we do it last as they are more unlikely to fail if the previous steps works
+      - name: Build the apps
+        run: pnpm -r --parallel -F "./apps/*" build
+
+      - name: Ensure no non-excluded files are changed for the whole repo
+        run: git diff --exit-code > /dev/null || (echo "After running the CI, some un-committed changes were detected. Please ensure cleanness before merging." && exit 1)

.github/workflows/release-docker.yaml

@@ -1,9 +1,12 @@
-name: Release new versions
+name: Build and publish Docker images
 
 on:
-  push:
-    tags:
-      - '@papra/app-server@*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g. 0.8.2)'
+        required: true
+        type: string
 
 permissions:
   contents: read
@@ -11,12 +14,9 @@ permissions:
 
 jobs:
   docker-release:
-    name: Release Docker images
+    name: Build and publish Docker images
     runs-on: ubuntu-latest
     steps:
-      - name: Get release version from tag
-        run: echo "RELEASE_VERSION=${GITHUB_REF#refs/tags/@papra/app-server@}" >> $GITHUB_ENV
-    
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
 
@@ -43,26 +43,26 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: ./docker/Dockerfile
-          platforms: linux/amd64,linux/arm64,linux/arm/v7
+          file: ./packages/docker/Dockerfile
+          platforms: linux/amd64,linux/arm64
           push: true
           tags: |
             corentinth/papra:latest-root
-            corentinth/papra:${{ env.RELEASE_VERSION }}-root
+            corentinth/papra:${{ inputs.version }}-root
             ghcr.io/papra-hq/papra:latest-root
-            ghcr.io/papra-hq/papra:${{ env.RELEASE_VERSION }}-root
+            ghcr.io/papra-hq/papra:${{ inputs.version }}-root
 
       - name: Build and push rootless Docker image
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: ./docker/Dockerfile.rootless
-          platforms: linux/amd64,linux/arm64,linux/arm/v7
+          file: ./packages/docker/Dockerfile.rootless
+          platforms: linux/amd64,linux/arm64
           push: true
           tags: |
             corentinth/papra:latest
             corentinth/papra:latest-rootless
-            corentinth/papra:${{ env.RELEASE_VERSION }}-rootless
+            corentinth/papra:${{ inputs.version }}-rootless
             ghcr.io/papra-hq/papra:latest
             ghcr.io/papra-hq/papra:latest-rootless
-            ghcr.io/papra-hq/papra:${{ env.RELEASE_VERSION }}-rootless
+            ghcr.io/papra-hq/papra:${{ inputs.version }}-rootless

.github/workflows/release.yml

@@ -11,20 +11,26 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
+    if: github.repository == 'papra-hq/papra'
     permissions:
       contents: write
       pull-requests: write
       id-token: write
+      actions: write
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      
+
       - name: Install pnpm
         uses: pnpm/action-setup@v4
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
-          cache: 'pnpm'
+          node-version: 24
+          cache: "pnpm"
+
+      # Ensure npm 11.5.1 or later is installed
+      - name: Update npm
+        run: npm install -g npm@latest
 
       - name: Install dependencies
         run: pnpm i
@@ -40,4 +46,12 @@ jobs:
           title: "chore(release): update versions"
         env:
           GITHUB_TOKEN: ${{ secrets.CHANGESET_GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Trigger Docker build
+        if: steps.changesets.outputs.published == 'true' && contains(fromJson(steps.changesets.outputs.publishedPackages).*.name, '@papra/docker')
+        run: |
+          VERSION=$(echo '${{ steps.changesets.outputs.publishedPackages }}' | jq -r '.[] | select(.name=="@papra/docker") | .version')
+          echo "VERSION: $VERSION"
+          gh workflow run release-docker.yaml -f version="$VERSION"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -35,8 +35,13 @@ cache
 *.db-shm
 *.db-wal
 *.sqlite
+*.sqlite-shm
+*.sqlite-wal
 
 local-documents
 ingestion
 .cursorrules
-*.traineddata
+*.traineddata
+
+.eslintcache
+.claude

.nvmrc

@@ -1 +1 @@
-22
+24

CLAUDE.md

@@ -0,0 +1,222 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Papra is a minimalistic document management and archiving platform built as a monorepo using PNPM workspaces. The project includes a SolidJS frontend, HonoJS backend, CLI tools, and supporting packages.
+It's open-source and designed for easy self-hosting using Docker, and also offers a cloud-hosted SaaS version.
+
+## Architecture
+
+### Monorepo Structure
+
+- **apps/papra-server**: Backend API server (HonoJS + Drizzle ORM + Better Auth)
+- **apps/papra-client**: Frontend application (SolidJS + UnoCSS + Shadcn Solid)
+- **apps/docs**: Documentation site (Astro + Starlight)
+- **packages/lecture**: Text extraction library for documents
+- **packages/api-sdk**: API client SDK
+- **packages/cli**: Command-line interface
+- **packages/webhooks**: Webhook types and utilities
+
+### Backend Architecture (apps/papra-server)
+
+The backend follows a modular architecture with feature-based modules:
+
+- **Module pattern**: Each feature lives in `src/modules/<feature>/` with:
+  - `*.repository.ts`: Database access layer (Drizzle ORM queries)
+  - `*.usecases.ts`: Business logic and orchestration
+  - `*.routes.ts`: HTTP route handlers (Hono)
+  - `*.services.ts`: Service layer for external integrations
+  - `*.table.ts`: Drizzle schema definitions
+  - `*.types.ts`: TypeScript type definitions
+  - `*.errors.ts`: Error definitions
+
+- **Core modules**: `app`, `shared`, `config`, `tasks`
+- **Feature modules**: `documents`, `organizations`, `users`, `tags`, `tagging-rules`, `intake-emails`, `ingestion-folders`, `webhooks`, `api-keys`, `subscriptions`, etc.
+
+- **Database**: Uses Drizzle ORM with SQLite/Turso (libsql). Schema is in `*.table.ts` files, migrations in `src/migrations/`
+
+- **Authentication**: Better Auth library for user auth
+
+- **Task system**: Background job processing using Cadence MQ, a custom made queue system (papra-hq/cadence-mq)
+
+- **Document storage**: Abstracted storage supporting local filesystem, S3, and Azure Blob
+
+### Frontend Architecture (apps/papra-client)
+
+- **SolidJS** for reactivity with router (`@solidjs/router`)
+- **Module pattern**: Features in `src/modules/<feature>/` with:
+  - `components/`: UI components
+  - `pages/`: Route components
+  - `*.services.ts`: API client calls
+  - `*.provider.tsx`: Context providers
+  - `*.types.ts`: Type definitions
+
+- **Routing**: Defined in `src/routes.tsx`
+- **Styling**: UnoCSS for atomic CSS with Shadcn Solid components
+- **State**: TanStack Query for server state, local storage for client state
+- **i18n**: TypeScript-based translations in `src/locales/*.dictionary.ts`
+
+### Dependency Injection Pattern
+
+The server uses a dependency injection pattern with `@corentinth/chisels/injectArguments` to create testable services that accept dependencies as parameters.
+
+## Development Commands
+
+### Initial Setup
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build all packages (required before running apps)
+pnpm build:packages
+```
+
+### Backend Development
+
+```bash
+cd apps/papra-server
+
+# Run database migrations
+pnpm migrate:up
+
+# Start development server (localhost:1221)
+pnpm dev
+
+# Run tests
+pnpm test              # All tests
+pnpm test:watch        # Watch mode
+pnpm test:unit         # Unit tests only
+pnpm test:int          # Integration tests only
+
+# Lint and typecheck
+pnpm lint
+pnpm typecheck
+
+# Database management
+pnpm db:studio         # Open Drizzle Studio
+pnpm migrate:create "migration_name"  # Create new migration
+```
+
+### Frontend Development
+
+```bash
+cd apps/papra-client
+
+# Start development server (localhost:3000)
+pnpm dev
+
+# Run tests
+pnpm test
+pnpm test:watch
+pnpm test:e2e          # Playwright E2E tests
+
+# Lint and typecheck
+pnpm lint
+pnpm typecheck
+
+# i18n key synchronization
+pnpm script:sync-i18n-key-order
+```
+
+### Package Development
+
+```bash
+cd packages/<package-name>
+
+# Build package
+pnpm build
+pnpm build:watch       # Watch mode (or pnpm dev)
+
+# Run tests
+pnpm test
+pnpm test:watch
+```
+
+### Root-level Commands
+
+```bash
+# Run tests across all packages
+pnpm test
+pnpm test:watch
+
+# Build all packages
+pnpm build:packages
+
+# Version management (changesets)
+pnpm changeset         # Create changeset
+pnpm version           # Apply changesets and bump versions
+
+# Docker builds
+pnpm docker:build:root
+pnpm docker:build:root:amd64
+pnpm docker:build:root:arm64
+```
+
+### Documentation Development
+
+```bash
+cd apps/docs
+pnpm dev               # localhost:4321
+```
+
+## Testing Guidelines
+
+- Use **Vitest** for all testing
+- Test files: `*.test.ts` for unit tests, `*.int.test.ts` for integration tests
+- Integration tests may use Testcontainers (Azurite, LocalStack)
+- All new features require test coverage
+
+### Writing Good Test Names
+
+Test names should explain the **why** (business logic, user scenario, or expected behavior), not the **how** (implementation details or return values).
+
+**Key principles:**
+- **Describe blocks** should explain the business goal or rule being tested
+- **Test names** should explain the scenario, context, and reason for the behavior
+- Avoid implementation details like "returns X", "should be Y", "calls Z method"
+- Focus on user scenarios and business rules
+- Make tests readable as documentation - someone unfamiliar with the code should understand what's being tested and why
+
+## Code Style
+
+- **ESLint config**: `@antfu/eslint-config` (auto-fix on save recommended)
+- **Conventions**:
+  - Use functional programming where possible
+  - Prefer clarity and maintainability over performance
+  - Use meaningful names for variables, functions, and components
+  - Follow Conventional Commits for commit messages
+- **Type safety**: Strict TypeScript throughout
+
+## i18n
+
+- Language files in `apps/papra-client/src/locales/*.dictionary.ts`
+- Reference `en.dictionary.ts` for all keys (English is fallback)
+- Fully type-safe with TypeScript
+- Update `i18n.constants.ts` when adding new languages
+- Use `pnpm script:sync-i18n-key-order` to sync key order
+- **Branchlet/core**: Uses `@branchlet/core` for pluralization and conditional i18n string templates (variant of ICU message format)
+  - Basic interpolation: `'Hello {{ name }}!'` with `{ name: 'World' }`
+  - Conditionals: `'{{ count, =0:no items, =1:one item, many items }}'`
+  - Pluralization with variables: `'{{ count, =0:no items, =1:{count} item, {count} items }}'`
+  - Range conditions: `'{{ score, [0-50]:bad, [51-75]:good, [76-100]:excellent }}'`
+  - See [branchlet documentation](https://github.com/CorentinTh/branchlet) for more details
+
+## Contributing Flow
+
+1. Open an issue before submitting PRs for features/bugs
+2. Target the `main` branch (continuously deployed to production)
+3. Keep PRs small and atomic
+4. Ensure CI is green (linting, type checking, testing, building)
+5. PRs are squashed on merge
+
+## Key Technologies
+
+- **Frontend**: SolidJS, UnoCSS, Shadcn Solid, TanStack Query, Vite
+- **Backend**: HonoJS, Drizzle ORM, Better Auth, Zod, Cadence MQ
+- **Database**: SQLite/Turso (libsql)
+- **Testing**: Vitest, Playwright, Testcontainers
+- **Monorepo**: PNPM workspaces with catalog for shared dependencies
+- **Build**: esbuild (backend), Vite (frontend), tsdown (packages)

CONTRIBUTING.md

@@ -43,9 +43,9 @@ We welcome contributions to improve and expand the app's internationalization (i
 
 ### Adding a New Language
 
-1. **Create a Language File**: To add a new language, create a YAML file named with the appropriate [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g., `fr.yml` for French) in the [`apps/papra-client/src/locales`](./apps/papra-client/src/locales) directory.
+1. **Create a Language File**: To add a new language, create a TypeScript file named with the appropriate [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) followed by `.dictionary.ts` (e.g., `fr.dictionary.ts` for French) in the [`apps/papra-client/src/locales`](./apps/papra-client/src/locales) directory.
 
-2. **Use the Reference File**: Refer to the [`en.yml`](./apps/papra-client/src/locales/en.yml) file, which contains all keys used in the app. Use it as a base to ensure consistency when creating your new language file. And act as a fallback if a key is missing in the new language file.
+2. **Use the Reference File**: Refer to the [`en.dictionary.ts`](./apps/papra-client/src/locales/en.dictionary.ts) file, which contains all keys used in the app. Use it as a base to ensure consistency when creating your new language file. The English translations act as a fallback if a key is missing in the new language file.
 
 3. **Update the Locale List**: After adding the new language file, include the language code in the `locales` array found in the [`apps/papra-client/src/modules/i18n/i18n.constants.ts`](./apps/papra-client/src/modules/i18n/i18n.constants.ts) file.
 
@@ -53,14 +53,21 @@ We welcome contributions to improve and expand the app's internationalization (i
 
 ### Updating an Existing Language
 
-If you want to update an existing language file, you can do so directly in the corresponding JSON file in the [`apps/papra-client/src/locales`](./apps/papra-client/src/locales) directory. If you're adding or removing keys in the default language file ([`en.yml`](./apps/papra-client/src/locales/en.yml)), please run the following command to update the types (used for type checking the translations keys in the app):
+If you want to update an existing language file, you can do so directly in the corresponding TypeScript file in the [`apps/papra-client/src/locales`](./apps/papra-client/src/locales) directory. The translation keys are now fully type-safe with TypeScript, so you'll get immediate feedback if you add invalid keys or have syntax errors.
 
-```bash
-pnpm script:generate-i18n-types
-```
+> [!TIP]
+> You can use the command `pnpm script:sync-i18n-key-order` to sync the order of the keys in the TypeScript i18n files, it'll also add the missing keys as comments.
 
-- This command will update the file [`locales.types.ts`](./apps/papra-client/src/modules/i18n/locale.types.ts) with the new/removed keys.
-- When developing in papra-client (using `pnpm dev`), the i18n types definition will automatically update when you touch the  [`en.yml`](./apps/papra-client/src/locales/en.yml) file, so no need to run the command above.
+### Using Branchlet for Pluralization and Conditionals
+
+Papra uses [`@branchlet/core`](https://github.com/CorentinTh/branchlet) for pluralization and conditional i18n string templates (a variant of ICU message format). Here are some common patterns:
+
+- **Basic interpolation**: `'Hello {{ name }}!'` with `{ name: 'World' }`
+- **Conditionals**: `'{{ count, =0:no items, =1:one item, many items }}'`
+- **Pluralization with variables**: `'{{ count, =0:no items, =1:{count} item, {count} items }}'`
+- **Range conditions**: `'{{ score, [0-50]:bad, [51-75]:good, [76-100]:excellent }}'`
+
+See the [branchlet documentation](https://github.com/CorentinTh/branchlet) for more details on syntax and advanced usage.
 
 ## Development Setup
 
@@ -81,7 +88,15 @@ We recommend running the app locally for development. Follow these steps:
    pnpm install
    ```
 
-3. Start the development server for the backend:
+3. Build the monorepo packages:
+   
+   As the apps rely on internal packages, you need to build them first.
+
+   ```bash
+   pnpm build:packages
+   ```
+
+4. Start the development server for the backend:
 
    ```bash
    cd apps/papra-server
@@ -91,7 +106,7 @@ We recommend running the app locally for development. Follow these steps:
    pnpm dev
    ```
 
-4. Start the frontend:
+5. Start the frontend:
 
    ```bash
    cd apps/papra-client
@@ -99,7 +114,74 @@ We recommend running the app locally for development. Follow these steps:
    pnpm dev
    ```
 
-5. Open your browser and navigate to `http://localhost:3000`.
+6. Open your browser and navigate to `http://localhost:3000`.
+
+### IDE Setup
+
+#### ESLint Extension
+
+We recommend installing the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for VS Code to get real-time linting feedback and automatic code fixing.
+The linting configuration is based on [@antfu/eslint-config](https://github.com/antfu/eslint-config), you can find specific IDE configurations in their repository.
+
+<details>
+<summary>Recommended VS Code Settings</summary>
+
+Create or update your `.vscode/settings.json` file with the following configuration:
+
+```json
+{
+  // Disable the default formatter, use eslint instead
+  "prettier.enable": false,
+  "editor.formatOnSave": false,
+
+  // Auto fix
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "never"
+  },
+
+  // Silent the stylistic rules in your IDE, but still auto fix them
+  "eslint.rules.customizations": [
+    { "rule": "style/*", "severity": "off", "fixable": true },
+    { "rule": "format/*", "severity": "off", "fixable": true },
+    { "rule": "*-indent", "severity": "off", "fixable": true },
+    { "rule": "*-spacing", "severity": "off", "fixable": true },
+    { "rule": "*-spaces", "severity": "off", "fixable": true },
+    { "rule": "*-order", "severity": "off", "fixable": true },
+    { "rule": "*-dangle", "severity": "off", "fixable": true },
+    { "rule": "*-newline", "severity": "off", "fixable": true },
+    { "rule": "*quotes", "severity": "off", "fixable": true },
+    { "rule": "*semi", "severity": "off", "fixable": true }
+  ],
+
+  // Enable eslint for all supported languages
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "vue",
+    "html",
+    "markdown",
+    "json",
+    "jsonc",
+    "yaml",
+    "toml",
+    "xml",
+    "gql",
+    "graphql",
+    "astro",
+    "svelte",
+    "css",
+    "less",
+    "scss",
+    "pcss",
+    "postcss"
+  ]
+}
+```
+
+</details>
 
 ### Testing
 

README.md

@@ -39,12 +39,9 @@ A live demo of the platform is available at [demo.papra.app](https://demo.papra.
 
 ## Project Status
 
-Papra is currently in **beta**. The core functionality is stable and usable, but you may encounter occasional bugs or limitations. The project is actively developed, with new features being added regularly.
+Papra is under active development, the core functionalities are stable and usable. With lots of features and improvements added regularly. 
 
-- ✅ Core document management features are stable
-- ✅ Self-hosting is fully supported
-- 🚧 Some advanced features are still in development
-- 📝 Feedback and bug reports are highly appreciated
+Feedback and bug reports are highly appreciated to help us improve the platform.
 
 ## Features
 
@@ -61,13 +58,19 @@ Papra is currently in **beta**. The core functionality is stable and usable, but
 - **Content extraction**: Automatically extract text from images or scanned documents for search.
 - **Tagging Rules**: Automatically tag documents based on custom rules.
 - **Folder ingestion**: Automatically import documents from a folder.
-- *In progress:* **i18n**: Support for multiple languages.
-- *Coming soon:* **SDK and API**: Build your own applications on top of Papra.
-- *Coming soon:* **CLI**: Manage your documents from the command line.
+- **CLI**: Manage your documents from the command line.
+- **API, SDK and webhooks**: Build your own applications on top of Papra.
+- **i18n**: Support for multiple languages.
 - *Coming soon:* **Document sharing**: Share documents with others.
 - *Coming soon:* **Document requests**: Generate upload links for people to add documents.
 - *Coming maybe one day:* **Mobile app**: Access and upload documents on the go.
 - *Coming maybe one day:* **Desktop app**: Access and upload documents from your computer.
+- *Coming maybe one day:* **Browser extension**: Upload documents from your browser.
+- *Coming maybe one day:* **AI**: Use AI to help you manage or tag your documents.
+
+## Sponsors
+
+Papra is a free and open-source project, but it is not free to run and develop. If you want to support the project, you can become a sponsor on [GitHub Sponsors](https://github.com/sponsors/corentinth) or [Buy me a coffee](https://buymeacoffee.com/cthmsst). If you are a company, you can also contact me to discuss a sponsorship.
 
 ## Self-hosting
 
@@ -115,6 +118,7 @@ Papra would not have been possible without the following open-source projects:
   - **[HonoJS](https://hono.dev/)**: A small, fast, and lightweight web framework for building APIs.
   - **[Drizzle](https://orm.drizzle.team/)**: A simple and lightweight ORM for Node.js.
   - **[Better Auth](https://better-auth.com/)**: A simple and lightweight authentication library for Node.js.
+  - **[CadenceMQ](https://github.com/papra-hq/cadence-mq)**: A self-hosted-friendly job queue for Node.js, made by Papra.
   - And other dependencies listed in the **[server package.json](./apps/papra-server/package.json)**
 - **Documentation**
   - **[Astro](https://astro.build)**: A great static site generator.
@@ -125,7 +129,7 @@ Papra would not have been possible without the following open-source projects:
   - **[Github Actions](https://github.com/features/actions)**: For CI/CD.
 - **Infrastructure**
   - **[Cloudflare Pages](https://pages.cloudflare.com/)**: For static site hosting.
-  - **[Render](https://render.com/)**: For backend hosting.
+  - **[Fly.io](https://fly.io/)**: For backend hosting.
   - **[Turso](https://turso.tech/)**: For production database.
 
 ### Inspiration

apps/docs/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @papra/docs
 
+## 0.6.1
+
+### Patch Changes
+
+- [#512](https://github.com/papra-hq/papra/pull/512) [`cb3ce6b`](https://github.com/papra-hq/papra/commit/cb3ce6b1d8d5dba09cbf0d2964f14b1c93220571) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added organizations permissions for api keys
+
+## 0.6.0
+
+### Minor Changes
+
+- [#480](https://github.com/papra-hq/papra/pull/480) [`0a03f42`](https://github.com/papra-hq/papra/commit/0a03f42231f691d339c7ab5a5916c52385e31bd2) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added documents encryption layer
+
+## 0.5.3
+
+### Patch Changes
+
+- [#455](https://github.com/papra-hq/papra/pull/455) [`b33fde3`](https://github.com/papra-hq/papra/commit/b33fde35d3e8622e31b51aadfe56875d8e48a2ef) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Improved feedback message in case of invalid origin configuration
+
+## 0.5.2
+
+### Patch Changes
+
+- [#405](https://github.com/papra-hq/papra/pull/405) [`3401cfb`](https://github.com/papra-hq/papra/commit/3401cfbfdc7e280d2f0f3166ceddcbf55486f574) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Introduce APP_BASE_URL to mutualize server and client base url
+
+- [#379](https://github.com/papra-hq/papra/pull/379) [`6cedc30`](https://github.com/papra-hq/papra/commit/6cedc30716e320946f79a0a9fd8d3b26e834f4db) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Updated dependencies
+
+- [#390](https://github.com/papra-hq/papra/pull/390) [`42bc3c6`](https://github.com/papra-hq/papra/commit/42bc3c669840eb778d251dcfb0dd96b45bf6e277) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added API endpoints documentation
+
+- [#402](https://github.com/papra-hq/papra/pull/402) [`1d23f40`](https://github.com/papra-hq/papra/commit/1d23f4089479387d5b87dbcf6d3819f5ee14d580) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Fix invalid domain in json schema urls
+
+## 0.5.1
+
+### Patch Changes
+
+- [#357](https://github.com/papra-hq/papra/pull/357) [`585c53c`](https://github.com/papra-hq/papra/commit/585c53cd9d0d7dbd517dbb1adddfd9e7b70f9fe5) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added a /llms.txt on main website
+
+## 0.5.0
+
+### Minor Changes
+
+- [#337](https://github.com/papra-hq/papra/pull/337) [`1c574b8`](https://github.com/papra-hq/papra/commit/1c574b8305eb7bde4f1b75ac38a610ca0120a613) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added troubleshooting page
+
+### Patch Changes
+
+- [#337](https://github.com/papra-hq/papra/pull/337) [`1c574b8`](https://github.com/papra-hq/papra/commit/1c574b8305eb7bde4f1b75ac38a610ca0120a613) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added `docker compose up` command in dc generator
+
+## 0.4.2
+
+### Patch Changes
+
+- [#322](https://github.com/papra-hq/papra/pull/322) [`f54b8e1`](https://github.com/papra-hq/papra/commit/f54b8e162acd6cfe92241aaa649847fc03ca5852) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Auto computes urls from the provided port
+
+## 0.4.1
+
+### Patch Changes
+
+- [#320](https://github.com/papra-hq/papra/pull/320) [`8ccdb74`](https://github.com/papra-hq/papra/commit/8ccdb748349a3cacf38f032fd4d3beebce202487) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added base url configuration in docker compose generator
+
+## 0.4.0
+
+### Minor Changes
+
+- [#295](https://github.com/papra-hq/papra/pull/295) [`438a311`](https://github.com/papra-hq/papra/commit/438a31171c606138c4b7fa299fdd58dcbeaaf298) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added support for custom oauth2 providers
+
+- [#293](https://github.com/papra-hq/papra/pull/293) [`53bf93f`](https://github.com/papra-hq/papra/commit/53bf93f128b54ad1d3553e18680c87ab23155f8d) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Added a papra docker-compose.yml generator
+
 ## 0.3.1
 
 ### Patch Changes

apps/docs/astro.config.ts

@@ -3,7 +3,9 @@ import starlight from '@astrojs/starlight';
 import { defineConfig } from 'astro/config';
 import starlightLinksValidator from 'starlight-links-validator';
 import starlightThemeRapide from 'starlight-theme-rapide';
+import UnoCSS from 'unocss/astro';
 import { sidebar } from './src/content/navigation';
+
 import posthogRawScript from './src/scripts/posthog.script.js?raw';
 
 const posthogApiKey = env.POSTHOG_API_KEY;
@@ -16,6 +18,7 @@ const posthogScript = posthogRawScript.replace('[POSTHOG-API-KEY]', posthogApiKe
 export default defineConfig({
   site: 'https://docs.papra.app',
   integrations: [
+    UnoCSS(),
     starlight({
       plugins: [starlightThemeRapide(), starlightLinksValidator({ exclude: ['http://localhost:1221'] })],
       title: 'Papra Docs',
@@ -38,7 +41,7 @@ export default defineConfig({
       sidebar,
       favicon: '/favicon.svg',
       head: [
-        // Add ICO favicon fallback for Safari.
+      // Add ICO favicon fallback for Safari.
         {
           tag: 'link',
           attrs: {

apps/docs/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@papra/docs",
   "type": "module",
-  "version": "0.3.1",
+  "version": "0.6.1",
   "private": true,
-  "packageManager": "pnpm@10.9.0",
   "description": "Papra documentation website",
   "author": "Corentin Thomasset <corentinth@proton.me> (https://corentin.tech)",
   "license": "AGPL-3.0-or-later",
@@ -18,23 +17,31 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.34.2",
-    "astro": "^5.7.10",
+    "@astrojs/solid-js": "^5.1.0",
+    "@astrojs/starlight": "^0.34.3",
+    "astro": "^5.8.0",
     "sharp": "^0.32.5",
+    "shiki": "^3.4.2",
     "starlight-links-validator": "^0.16.0",
     "starlight-theme-rapide": "^0.5.0",
+    "tailwind-merge": "^2.6.0",
+    "unocss-preset-animations": "^1.2.1",
+    "yaml": "^2.8.0",
+    "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^3.13.0",
+    "@antfu/eslint-config": "catalog:",
     "@iconify-json/tabler": "^1.1.120",
     "@types/lodash-es": "^4.17.12",
     "@unocss/reset": "^0.64.0",
-    "eslint": "^9.17.0",
+    "eslint": "catalog:",
     "eslint-plugin-astro": "^1.3.1",
-    "figue": "^2.2.2",
+    "figue": "^3.1.1",
     "lodash-es": "^4.17.21",
     "marked": "^15.0.6",
-    "typescript": "^5.7.3"
+    "typescript": "catalog:",
+    "unocss": "0.65.0-beta.2",
+    "vitest": "catalog:"
   }
 }

apps/docs/public/_headers

@@ -0,0 +1,3 @@
+/*
+    X-Frame-Options: DENY
+    X-Content-Type-Options: nosniff

apps/docs/src/assets/app.css

@@ -1,4 +1,38 @@
 :root[data-theme='dark'] {
+    --background: 240 4% 10%;
+    --foreground: 0 0% 98%;
+  
+    --card: 240 4% 8%;
+    --card-foreground: 0 0% 98%;
+  
+    --popover: 240 4% 8%;
+    --popover-foreground: 0 0% 98%;
+  
+    --primary: 77 100% 74%;
+    --primary-foreground: 0 0% 9%;
+  
+    --secondary: 0 0% 14.9%;
+    --secondary-foreground: 0 0% 98%;
+  
+    --muted: 0 0% 14.9%;
+    --muted-foreground: 0 0% 63.9%;
+  
+    --accent: 0 0% 14.9%;
+    --accent-foreground: 0 0% 98%;
+  
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+  
+    --warning: 31 98% 50%;
+    --warning-foreground: 0 0% 98%;
+  
+    --border: 345 4% 17%;
+    --input: 0 0% 89.8%;
+    --ring: 0 0% 3.9%;
+  
+    --radius: 0.5rem;
+
+
     --background-color: #0c0d0f!important;
     --accent-color: #fff!important;
     --foreground-color: #9ea3a2!important;
@@ -55,4 +89,8 @@
 
 .site-title img {
     width: 1.8rem !important;
-} 
+} 
+
+pre.shiki {
+    border-radius: 0.5rem!important;
+}

apps/docs/src/changelog-parser.ts

@@ -0,0 +1,48 @@
+const linesToRemove = [
+  /^# (.*)$/gm, // Remove main title
+  /^### (.*)$/gm, // Remove section titles
+];
+
+export function parseChangelog(changelog: string) {
+  const logs: { entries: {
+    pr: { number: number; url: string };
+    commit: { hash: string; url: string };
+    contributor: { username: string; url: string };
+    content: string;
+  }[]; version: string; }[] = [];
+
+  for (const lineToRemove of linesToRemove) {
+    changelog = changelog.replace(lineToRemove, '');
+  }
+
+  const sections = changelog.match(/## (.*)\n([\s\S]*?)(?=\n## |$)/g) ?? [];
+
+  for (const section of sections) {
+    const version = section.match(/## (.*)\n/)?.[1].trim() ?? 'unknown version';
+
+    const entries = section.split('\n- ').slice(1).map((entry) => {
+      // Example entry:
+      // [#280](https://github.com/papra-hq/papra/pull/280) [`85fa5c4`](https://github.com/papra-hq/papra/commit/85fa5c43424d139f5c2752a3ad644082e61d3d67) Thanks [@CorentinTh](https://github.com/CorentinTh)! - Maybe multiline content
+
+      // Thanks copilot! :sweat-smile:
+      const prMatch = entry.match(/\[#(\d+)\]\((https:\/\/github\.com\/papra-hq\/papra\/pull\/\d+)\)/);
+      const commitMatch = entry.match(/\[`([a-f0-9]{7,40})`\]\((https:\/\/github\.com\/papra-hq\/papra\/commit\/[a-f0-9]{7,40})\)/);
+      const contributorMatch = entry.match(/Thanks \[@([\w-]+)\]\((https:\/\/github\.com\/[\w-]+)\)/);
+      const contentMatch = entry.match(/\)! - (.*)$/s);
+
+      return {
+        pr: prMatch ? { number: Number.parseInt(prMatch[1], 10), url: prMatch[2] } : { number: 0, url: '' },
+        commit: commitMatch ? { hash: commitMatch[1], url: commitMatch[2] } : { hash: '', url: '' },
+        contributor: contributorMatch ? { username: contributorMatch[1], url: contributorMatch[2] } : { username: 'unknown', url: '' },
+        content: contentMatch ? contentMatch[1].trim() : entry.trim(),
+      };
+    });
+
+    logs.push({
+      version,
+      entries,
+    });
+  }
+
+  return logs;
+}

apps/docs/src/components/encryption-key-generator.astro

@@ -0,0 +1,154 @@
+---
+const iconSize = '20';
+const refreshIcon = `<svg xmlns="http://www.w3.org/2000/svg" width="${iconSize}" height="${iconSize}" viewBox="0 0 24 24"><!-- Icon from Tabler Icons by Paweł Kuna - https://github.com/tabler/tabler-icons/blob/master/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20 11A8.1 8.1 0 0 0 4.5 9M4 5v4h4m-4 4a8.1 8.1 0 0 0 15.5 2m.5 4v-4h-4"/></svg>`;
+const copyIcon = `<svg xmlns="http://www.w3.org/2000/svg" width="${iconSize}" height="${iconSize}" viewBox="0 0 24 24"><!-- Icon from Tabler Icons by Paweł Kuna - https://github.com/tabler/tabler-icons/blob/master/LICENSE --><g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="M7 9.667A2.667 2.667 0 0 1 9.667 7h8.666A2.667 2.667 0 0 1 21 9.667v8.666A2.667 2.667 0 0 1 18.333 21H9.667A2.667 2.667 0 0 1 7 18.333z"/><path d="M4.012 16.737A2 2 0 0 1 3 15V5c0-1.1.9-2 2-2h10c.75 0 1.158.385 1.5 1"/></g></svg>`;
+const copiedIcon = `<svg xmlns="http://www.w3.org/2000/svg" width="${iconSize}" height="${iconSize}" viewBox="0 0 24 24"><!-- Icon from Tabler Icons by Paweł Kuna - https://github.com/tabler/tabler-icons/blob/master/LICENSE --><path fill="currentColor" d="M18.333 6A3.667 3.667 0 0 1 22 9.667v8.666A3.667 3.667 0 0 1 18.333 22H9.667A3.667 3.667 0 0 1 6 18.333V9.667A3.667 3.667 0 0 1 9.667 6zM15 2c1.094 0 1.828.533 2.374 1.514a1 1 0 1 1-1.748.972C15.405 4.088 15.284 4 15 4H5c-.548 0-1 .452-1 1v9.998c0 .32.154.618.407.805l.1.065a1 1 0 1 1-.99 1.738A3 3 0 0 1 2 15V5c0-1.652 1.348-3 3-3zm1.293 9.293L13 14.585l-1.293-1.292a1 1 0 0 0-1.414 1.414l2 2a1 1 0 0 0 1.414 0l4-4a1 1 0 0 0-1.414-1.414"/></svg>`;
+---
+
+<div class="key-generator">
+    <div class="key-row">
+        <input type="text" class="key-input" readonly />
+        <button class="cbtn btn-refresh" title="Generate new key">
+            <span set:html={refreshIcon} aria-label="Refresh" />
+        </button>
+        <button class="cbtn btn-copy" title="Copy to clipboard">
+            <span set:html={copyIcon} aria-label="Copy" class="icon-copy" />
+            <span set:html={copiedIcon} aria-label="Copied" class="icon-copied hidden" />
+        </button>
+    </div>
+    <div class="info-text">
+        Generated locally in your browser - no network or server involved
+    </div>
+</div>
+
+<script>
+    function generateKey({ keyInputElement }: { keyInputElement: HTMLInputElement }) {
+      // Generate a 32-byte (256-bit) encryption key
+      const array = new Uint8Array(32);
+      crypto.getRandomValues(array);
+
+      // Convert to hex format
+      const key = Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('');
+      keyInputElement.value = key;
+    }
+
+    function copyToClipboard({ keyInputElement, copyButtonElement, iconCopyElement, iconCopiedElement }: { keyInputElement: HTMLInputElement; copyButtonElement: HTMLButtonElement; iconCopyElement: HTMLSpanElement; iconCopiedElement: HTMLSpanElement }) {
+      keyInputElement.select();
+      keyInputElement.setSelectionRange(0, 64); // For mobile devices
+
+      navigator.clipboard.writeText(keyInputElement.value).then(() => {
+        iconCopyElement.classList.add('hidden');
+        iconCopiedElement.classList.remove('hidden');
+        copyButtonElement.disabled = true;
+
+        setTimeout(() => {
+          iconCopyElement.classList.remove('hidden');
+          iconCopiedElement.classList.add('hidden');
+          copyButtonElement.disabled = false;
+        }, 1_000);
+      }).catch(() => {
+        // Fallback for older browsers
+        document.execCommand('copy');
+      });
+    }
+
+    const keyGenerators = document.querySelectorAll('.key-generator');
+
+    keyGenerators.forEach((keyGenerator) => {
+      const refreshButtonElement = keyGenerator.querySelector('.btn-refresh')!;
+      const copyButtonElement = keyGenerator.querySelector<HTMLButtonElement>('.btn-copy')!;
+      const keyInputElement = keyGenerator.querySelector<HTMLInputElement>('.key-input')!;
+      const iconCopyElement = keyGenerator.querySelector<HTMLSpanElement>('.icon-copy')!;
+      const iconCopiedElement = keyGenerator.querySelector<HTMLSpanElement>('.icon-copied')!;
+
+      generateKey({ keyInputElement });
+
+      refreshButtonElement.addEventListener('click', () => generateKey({ keyInputElement }));
+      copyButtonElement.addEventListener('click', () => copyToClipboard({ copyButtonElement, keyInputElement, iconCopyElement, iconCopiedElement }));
+    });
+</script>
+
+<style>
+    .key-generator {
+        /* background-color: var(--ec-frm-trmBg);
+        border-radius: var(--ec-brdRad);
+        border: 1px solid var(--ec-brdCol);
+        font-family: monospace;
+        max-width: 100%; */
+    }
+
+    .key-row {
+        display: flex;
+        align-items: center;
+    }
+
+    .key-input {
+        flex: 1;
+        background-color: var(--sl-color-black);
+        border: 1px solid var(--sl-color-gray-5);
+        border-radius: 4px 0 0 4px;
+        padding: 8px 12px;
+        font-family: var(--__sl-font-mono, monospace);
+        font-size: 14px;
+        color: var(--sl-color-gray-2);
+        min-width: 0; /* Allow input to shrink */
+        border-right: none;
+    }
+
+    .key-input:focus {
+        outline: none;
+        border-color: var(--ec-frm-inpBrd, #4a9eff);
+        box-shadow: 0 0 0 2px var(--ec-frm-inpBrd, #4a9eff)33;
+    }
+
+    .cbtn {
+        background-color: var(--ec-frm-btnBg);
+        border: 1px solid var(--ec-brdCol);
+        padding: 10px 12px;
+        cursor: pointer;
+        font-size: 16px;
+        transition: all 0.2s ease;
+        min-width: 44px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        margin-top: 0;
+    }
+
+    .cbtn.btn-copy {
+        border-top-left-radius: 0;
+        border-bottom-left-radius: 0;
+        border-top-right-radius: 4px;
+        border-bottom-right-radius: 4px;
+        border-left: none;
+    }
+
+    .cbtn.btn-refresh {
+        border-radius: 0;
+    }
+
+    .cbtn:hover {
+        background-color: var(--sl-color-gray-6)!important;
+    }
+
+    .cbtn:disabled {
+        opacity: 0.6;
+        cursor: not-allowed;
+        transform: none;
+    }
+
+    .btn-refresh:hover:not(:disabled) {
+        background-color: var(--ec-frm-btnBgHover, #3a3a3a);
+    }
+
+    .btn-copy:hover:not(:disabled) {
+        background-color: var(--ec-frm-btnBgHover, #3a3a3a);
+    }
+
+    .info-text {
+        color: var(--ec-frm-txtSecondary, #888888);
+        font-style: italic;
+        margin-top: 0;
+    }
+
+</style>

apps/docs/src/config.data.ts

@@ -1,6 +1,8 @@
 import type { ConfigDefinition, ConfigDefinitionElement } from 'figue';
-import { isArray, isEmpty, isNil } from 'lodash-es';
+import { castArray, isArray, isEmpty, isNil } from 'lodash-es';
+
 import { configDefinition } from '../../papra-server/src/modules/config/config';
+import { renderMarkdown } from './markdown';
 
 function walk(configDefinition: ConfigDefinition, path: string[] = []): (ConfigDefinitionElement & { path: string[] })[] {
   return Object
@@ -33,24 +35,32 @@ const rows = configDetails
 
     const rawDocumentation = formatDoc(doc);
 
+    // The client baseUrl default value is overridden in the Dockerfiles
+    const defaultOverride = path.join('.') === 'client.baseUrl' ? 'http://localhost:1221' : undefined;
+
     return {
       path,
       env,
       documentation: rawDocumentation,
-      defaultValue: isEmptyDefaultValue ? undefined : defaultValue,
+      defaultValue: defaultOverride ?? (isEmptyDefaultValue ? undefined : defaultValue),
     };
   });
 
-const mdSections = rows.map(({ documentation, env, path, defaultValue }) => `
-###  ${env}
+const mdSections = rows.map(({ documentation, env, path, defaultValue }) => {
+  const envs = castArray(env);
+  const [firstEnv, ...restEnvs] = envs;
+
+  return `
+### ${firstEnv}
 ${documentation}
 
 - Path: \`${path.join('.')}\`
-- Environment variable: \`${env}\`
+- Environment variable: \`${firstEnv}\` ${restEnvs.length ? `, with fallback to: ${restEnvs.map(e => `\`${e}\``).join(', ')}` : ''}
 - Default value: \`${defaultValue}\`
 
 
-`.trim()).join('\n\n---\n\n');
+`.trim();
+}).join('\n\n---\n\n');
 
 function wrapText(text: string, maxLength = 75) {
   const words = text.split(' ');
@@ -75,11 +85,15 @@ function wrapText(text: string, maxLength = 75) {
 
 const fullDotEnv = rows.map(({ env, defaultValue, documentation }) => {
   const isEmptyDefaultValue = isNil(defaultValue) || (isArray(defaultValue) && isEmpty(defaultValue)) || defaultValue === '';
+  const envs = castArray(env);
+  const [firstEnv] = envs;
 
   return [
     ...wrapText(documentation),
-    `# ${env}=${isEmptyDefaultValue ? '' : defaultValue}`,
+    `# ${firstEnv}=${isEmptyDefaultValue ? '' : defaultValue}`,
   ].join('\n');
 }).join('\n\n');
 
-export { fullDotEnv, mdSections };
+const sectionsHtml = renderMarkdown(mdSections);
+
+export { fullDotEnv, mdSections, sectionsHtml };

apps/docs/src/content/docs/02-self-hosting/01-using-docker.mdx

@@ -31,6 +31,7 @@ Launch Papra with default configuration using:
 docker run -d \
   --name papra \
   --restart unless-stopped \
+  --env APP_BASE_URL=http://localhost:1221 \
   -p 1221:1221 \
   ghcr.io/papra-hq/papra:latest
 ```
@@ -69,6 +70,7 @@ For production deployments, mount host directories to preserve application data
     docker run -d \
       --name papra \
       --restart unless-stopped \
+      --env APP_BASE_URL=http://localhost:1221 \
       -p 1221:1221 \
       -v $(pwd)/papra-data:/app/app-data \
       --user $(id -u):$(id -g) \

apps/docs/src/content/docs/02-self-hosting/02-using-docker-compose.mdx

@@ -1,6 +1,7 @@
 ---
 title: Using Docker Compose
 slug: self-hosting/using-docker-compose
+description: Self-host Papra using Docker Compose.
 ---
 
 import { Steps } from '@astrojs/starlight/components';

apps/docs/src/content/docs/02-self-hosting/03-configuration.mdx

@@ -1,17 +1,29 @@
 ---
 title: Configuration
 slug: self-hosting/configuration
-
+description: Configure your self-hosted Papra instance.
 ---
 
-import { mdSections, fullDotEnv } from '../../../config.data.ts';
-import { marked } from 'marked';
+import { sectionsHtml, fullDotEnv } from '../../../config.data.ts';
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import { Aside } from '@astrojs/starlight/components';
 import { Code } from '@astrojs/starlight/components';
 
 Configuring your self hosted Papra allows you to customize the application to better suit your environment and requirements. This guide covers the key environment variables you can set to control various aspects of the application, including port settings, security options, and storage configurations.
 
+## Complete .env
+
+Here is the full configuration file that you can use to configure Papra. The variables values are the default values.
+
+<Code code={fullDotEnv} language="env" title=".env" />
+
+## Configuration variables
+
+Here is the complete list of configuration variables that you can use to configure Papra. You can set these variables in the `.env` file or pass them as environment variables when running the Docker container.
+
+<Fragment set:html={sectionsHtml} />
+
+
 ## Configuration files
 
 You can configure Papra using standard environment variables or use some configuration files.
@@ -42,7 +54,7 @@ Example of configuration files:
   <TabItem label="papra.config.json">
     ```json
     {
-      "$schema": "https://docs.papra.com/papra-config-schema.json",
+      "$schema": "https://docs.papra.app/papra-config-schema.json",
       "server": {
         "baseUrl": "https://papra.example.com"
       },
@@ -61,7 +73,7 @@ Example of configuration files:
 
       ```json
       {
-        "$schema": "https://docs.papra.com/papra-config-schema.json",
+        "$schema": "https://docs.papra.app/papra-config-schema.json",
         // ...
       }
       ```
@@ -72,17 +84,4 @@ Example of configuration files:
 </Tabs>
 
 
-You'll find the complete list of configuration variables with their environment variables equivalents and path for files in the next section.
-
-## Complete .env
-
-Here is the full configuration file that you can use to configure Papra. The variables values are the default values.
-
-<Code code={fullDotEnv} language="env" title=".env" />
-
-## Configuration variables
-
-Here is the complete list of configuration variables that you can use to configure Papra. You can set these variables in the `.env` file or pass them as environment variables when running the Docker container.
-
-<Fragment set:html={marked.parse(mdSections)} />
-
+You'll find the complete list of configuration variables with their environment variables equivalents and path for files in the previous section.

apps/docs/src/content/docs/03-guides/01-intake-emails-with-owlrelay.mdx

@@ -39,7 +39,7 @@ By integrating Papra with OwlRelay, your instance will generate email addresses
 
 3. **Configure your Papra instance**
 
-   Once you have created your API key, you can configure your Papra instance to receive emails by setting the `OWLRELAY_API_KEY` and `OWLRELAY_WEBHOOK_SECRET` environment variables.
+   Once you have created your API key, you can configure your Papra instance to receive emails by setting the `OWLRELAY_API_KEY` and `INTAKE_EMAILS_WEBHOOK_SECRET` environment variables.
 
    ```bash
    # Enable intake emails

apps/docs/src/content/docs/03-guides/02-intake-emails-with-cf-email-worker.mdx

@@ -52,7 +52,7 @@ The code for the Email Worker proxy is available in the [papra-hq/email-proxy](h
 
     - **Option 2**: Build and deploy the Email Worker
 
-      Clone the [papra-hq/email-proxy](https://github.com/papra-hq/email-proxy) repository and deploy the worker using Wrangler cli. You will need to have Node.js v22 and pnpm installed.
+      Clone the [papra-hq/email-proxy](https://github.com/papra-hq/email-proxy) repository and deploy the worker using Wrangler cli. You will need to have Node.js v24 and pnpm installed.
 
         ```bash
         # Clone the repository

apps/docs/src/content/docs/03-guides/04-setup-custom-oauth2.mdx

@@ -0,0 +1,181 @@
+---
+title: Setup Custom OAuth2 Providers
+description: Step-by-step guide to setup custom OAuth2 providers for authentication in your Papra instance.
+slug: guides/setup-custom-oauth2-providers
+---
+
+import { Aside } from '@astrojs/starlight/components';
+import { Steps } from '@astrojs/starlight/components';
+
+This guide will show you how to configure custom OAuth2 providers for authentication in your Papra instance.
+
+<Aside type="note">
+  Papra's OAuth2 implementation is based on the [Better Auth Generic OAuth plugin](https://www.better-auth.com/docs/plugins/generic-oauth). For more detailed information about the configuration options and advanced usage, please refer to their documentation.
+</Aside>
+
+## Prerequisites
+
+In order to follow this guide, you need:
+- A custom OAuth2 provider
+- An accessible Papra instance
+- Basic understanding of OAuth2 flows
+
+## Configuration
+
+To set up custom OAuth2 providers, you'll need to configure the `AUTH_PROVIDERS_CUSTOMS` environment variable with an array of provider configurations. Here's an example:
+
+```bash
+AUTH_PROVIDERS_CUSTOMS='[
+  {
+    "providerId": "custom-oauth2",
+    "providerName": "Custom OAuth2",
+    "providerIconUrl": "https://api.iconify.design/tabler:login-2.svg",
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "type": "oidc",
+    "discoveryUrl": "https://your-provider.tld/.well-known/openid-configuration",
+    "scopes": ["openid", "profile", "email"]
+  }
+]'
+```
+
+Each provider configuration supports the following fields:
+
+- `providerId`: A unique identifier for the OAuth provider
+- `providerName`: The display name of the provider
+- `providerIconUrl`: URL of the icon to display (optional) you can use a base64 encoded image or an url to a remote image.
+- `clientId`: OAuth client ID
+- `clientSecret`: OAuth client secret
+- `type`: Type of OAuth flow ("oauth2" or "oidc")
+- `discoveryUrl`: URL to fetch OAuth 2.0 configuration (recommended for OIDC providers)
+- `authorizationUrl`: URL for the authorization endpoint (required for OAuth2 if not using discoveryUrl)
+- `tokenUrl`: URL for the token endpoint (required for OAuth2 if not using discoveryUrl)
+- `userInfoUrl`: URL for the user info endpoint (required for OAuth2 if not using discoveryUrl)
+- `scopes`: Array of OAuth scopes to request
+- `redirectURI`: Custom redirect URI (optional)
+- `responseType`: OAuth response type (defaults to "code")
+- `prompt`: Controls the authentication experience ("select_account", "consent", "login", "none")
+- `pkce`: Whether to use PKCE (Proof Key for Code Exchange)
+- `accessType`: Access type for the authorization request
+
+## Setup
+
+<Steps>
+
+1. **Configure your OAuth2 Provider**
+
+   First, you'll need to register your application with your OAuth2 provider. This typically involves:
+   - Creating a new application in your provider's dashboard
+   - Setting up the redirect URI (usually `https://<your-papra-instance>/api/auth/oauth2/callback/:providerId`)
+   - Obtaining the client ID and client secret
+   - Configuring the required scopes
+
+2. **Configure Papra**
+
+   Add the `AUTH_PROVIDERS_CUSTOMS` environment variable to your Papra instance. Here are some examples:
+
+   For OIDC providers:
+   ```json
+   [
+     {
+       "providerId": "custom-oauth2",
+       "providerName": "Custom OAuth2",
+       "providerIconUrl": "https://api.iconify.design/tabler:login-2.svg",
+       "clientId": "your-client-id",
+       "clientSecret": "your-client-secret",
+       "type": "oidc",
+       "discoveryUrl": "https://your-provider.tld/.well-known/openid-configuration",
+       "scopes": ["openid", "profile", "email"]
+     }
+   ]
+   ```
+
+   For standard OAuth2 providers:
+   ```json
+   [
+     {
+       "providerId": "custom-oauth2",
+       "providerName": "Custom OAuth2",
+       "providerIconUrl": "https://api.iconify.design/tabler:login-2.svg",
+       "clientId": "your-client-id",
+       "clientSecret": "your-client-secret",
+       "type": "oauth2",
+       "authorizationUrl": "https://your-provider.tld/oauth2/authorize",
+       "tokenUrl": "https://your-provider.tld/oauth2/token",
+       "userInfoUrl": "https://your-provider.tld/oauth2/userinfo",
+       "scopes": ["profile", "email"]
+     }
+   ]
+   ```
+
+   <Aside type="note">
+     The `discoveryUrl` is recommended for OIDC providers as it automatically configures all the necessary endpoints.
+     For standard OAuth2 providers, you'll need to specify the endpoints manually.
+   </Aside>
+
+3. **Test the Configuration**
+
+   - Restart your Papra instance to apply the changes
+   - Go to the login page
+   - You should see your custom OAuth2 providers as login options
+   - Try logging in with a test account
+
+</Steps>
+
+## Troubleshooting
+
+### Providers Not Showing Up
+
+If your OAuth2 providers are not showing up on the login page:
+- Check that the JSON configuration in `AUTH_PROVIDERS_CUSTOMS` is valid
+- Ensure all required fields are provided
+- Verify that the provider IDs are unique
+
+### Authentication Fails
+
+If authentication fails:
+- Verify that the redirect URI is correctly configured in your OAuth2 provider
+- Check that the client ID and client secret are correct
+- Ensure the required scopes are properly configured
+- Check the Papra logs for any error messages
+
+### OIDC Discovery Issues
+
+If you're using OIDC and experiencing issues:
+- Verify that the `discoveryUrl` is accessible
+- Check that the provider supports OIDC discovery
+- Ensure the provider's configuration is properly exposed through the discovery endpoint
+
+## Security Considerations
+
+<Aside type="caution">
+  Always use HTTPS for your OAuth2 endpoints and ensure your client secret is kept secure.
+  Consider using PKCE (Proof Key for Code Exchange) for additional security by setting `pkce: true` in your configuration.
+</Aside>
+
+## Multiple Providers
+
+You can configure multiple custom OAuth2 providers by adding them to the array:
+
+```json
+[
+  {
+    "providerId": "custom-oauth2-1",
+    "providerName": "Custom OAuth2 Provider 1",
+    "type": "oidc",
+    "discoveryUrl": "https://provider1.tld/.well-known/openid-configuration",
+    "clientId": "client-id-1",
+    "clientSecret": "client-secret-1",
+    "scopes": ["openid", "profile", "email"]
+  },
+  {
+    "providerId": "custom-oauth2-2",
+    "providerName": "Custom OAuth2 Provider 2",
+    "type": "oidc",
+    "discoveryUrl": "https://provider2.tld/.well-known/openid-configuration",
+    "clientId": "client-id-2",
+    "clientSecret": "client-secret-2",
+    "scopes": ["openid", "profile", "email"]
+  }
+]
+```

apps/docs/src/content/docs/03-guides/05-setup-document-encryption.mdx

@@ -0,0 +1,448 @@
+---
+title: Setup Document Encryption
+description: Step-by-step guide to enable and configure document encryption in Papra for enhanced data security.
+slug: guides/document-encryption
+---
+import { Steps } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
+import { Code } from '@astrojs/starlight/components';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import EncryptionKeyGenerator from '../../../components/encryption-key-generator.astro';
+
+<Aside type="note">
+Document encryption is available in Papra v0.9.0 and above.
+</Aside>
+
+Document encryption in Papra provides end-to-end protection for your stored documents using industry-standard AES-256-GCM encryption. This guide will walk you through enabling encryption, understanding how it works, and managing encryption keys.
+
+## How Encryption Works
+
+Papra uses a two-layer encryption approach that provides both security and flexibility:
+
+### Key Encryption Architecture
+
+1. **Key Encryption Key (KEK)**: A master key that you provide, used to encrypt document-specific keys
+2. **Document Encryption Key (DEK)**: Unique per-document keys that actually encrypt your files
+3. **File Encryption**: Each document gets its own random 256-bit encryption key for maximum security
+
+<div class="dark:block hidden">
+![Key Encryption Architecture](../../../assets/docs/encryption-schema-light.png)
+</div>
+<div class="dark:hidden block">
+![Key Encryption Architecture](../../../assets/docs/encryption-schema-dark.png)
+</div>
+
+### Encryption Flow
+
+<Steps>
+
+1. **Document Upload**: When you upload a document, Papra generates a unique 256-bit encryption key (DEK)
+
+2. **File Encryption**: The document is encrypted using AES-256-GCM with the DEK
+
+3. **Key Wrapping**: The DEK is encrypted (wrapped) using your Key Encryption Key (KEK)
+
+4. **Storage**: The encrypted document and wrapped DEK are stored separately - the file in your storage backend, the wrapped key in the database along with the document metadata
+
+5. **Retrieval**: When accessing a document, Papra unwraps the DEK using your KEK, then decrypts the file stream
+
+</Steps>
+
+<Aside type="note">
+This architecture means that even if someone gains access to your file storage, they cannot decrypt documents without access to both your document records and your KEK, in other words, without your database and your environment variables.
+</Aside>
+
+## Quick Setup
+
+<Steps>
+
+1. **Generate an encryption key**
+
+   Generate a secure random 256-bit key in hex format, using this generator or OpenSSL command.
+
+   <Tabs>
+    <TabItem label="Key generator">
+    <EncryptionKeyGenerator />
+    </TabItem>
+
+   <TabItem label="OpenSSL command">
+   ```bash
+   openssl rand -hex 32
+   ```
+
+   This will output something like: `0deba5534bd70548de92d1fd4ae37cf901cca3dc20589b7e022ddb680c98e50c`
+   </TabItem>
+
+   </Tabs>
+
+
+
+2. **Enable encryption in your configuration**
+
+   Add the following environment variables to your `.env` file or Docker configuration:
+
+   ```bash
+   DOCUMENT_STORAGE_ENCRYPTION_IS_ENABLED=true
+   DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS=<your-encryption-key>
+   ```
+
+3. **Restart Papra**
+
+   Restart your Papra instance to apply the encryption settings.
+
+</Steps>
+
+## Configuration Options
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `DOCUMENT_STORAGE_ENCRYPTION_IS_ENABLED` | Enable/disable document encryption | No |
+| `DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS` | Key encryption keys for document encryption | Yes (if encryption enabled) |
+
+### Key Formats
+
+<Tabs>
+  <TabItem label="Single Key">
+    For simple setups, provide a single 32-byte hex string:
+
+    ```bash
+    DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS=<your-encryption-key>
+    ```
+
+    This key will automatically be assigned version `1`.
+  </TabItem>
+
+  <TabItem label="Multiple Keys">
+    For key rotation and advanced setups, provide versioned keys:
+
+    ```bash
+    DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS=1:<your-encryption-key-1>,2:<your-encryption-key-2>
+    ```
+
+    - The highest version key encrypts new documents
+    - All keys can decrypt existing documents
+    - Versions can be any alphabetically sortable string
+    - Order in the list doesn't matter
+  </TabItem>
+</Tabs>
+
+## Docker Compose Setup
+
+Add encryption configuration to your Docker Compose file:
+
+<Tabs>
+  <TabItem label="Environment Variables">
+    ```yaml title="docker-compose.yml" ins={8-9}
+    services:
+      papra:
+        container_name: papra
+        image: ghcr.io/papra-hq/papra:latest
+        restart: unless-stopped
+        environment:
+          # ... other environment variables ...
+          - DOCUMENT_STORAGE_ENCRYPTION_IS_ENABLED=true
+          - DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS=<your-encryption-key>
+        volumes:
+          - ./app-data:/app/app-data
+        ports:
+          - "1221:1221"
+    ```
+  </TabItem>
+
+  <TabItem label="Config File">
+    ```yaml title="docker-compose.yml"
+    services:
+      papra:
+        container_name: papra
+        image: ghcr.io/papra-hq/papra:latest
+        restart: unless-stopped
+        volumes:
+          - ./app-data:/app/app-data
+          - ./papra.config.yaml:/app/app-data/papra.config.yaml
+        ports:
+          - "1221:1221"
+    ```
+
+    ```yaml title="./papra.config.yaml"
+    documentsStorage:
+      encryption:
+        isEncryptionEnabled: true
+        documentKeyEncryptionKeys: "<your-encryption-key>"
+    ```
+  </TabItem>
+</Tabs>
+
+## Key Management
+
+### Key Rotation
+
+Key rotation allows you to replace encryption keys without losing access to existing documents:
+
+<Steps>
+
+1. **Generate a new key**
+
+   ```bash
+   openssl rand -hex 32
+   ```
+
+2. **Add the new key with a higher version**
+
+   ```bash
+   DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS=1:old_key_here,2:new_key_here
+   ```
+
+3. **Restart Papra**
+
+   New documents will use the highest version key (version 2), while existing documents remain accessible with the old key.
+
+4. **Optional: Remove old keys**
+
+   Once you're confident all documents are using the new key, you can remove old keys. However, this will make any documents encrypted with old keys inaccessible.
+
+</Steps>
+
+<Aside type="caution">
+Never remove a key version if there are still documents encrypted with that key, unless you're certain you no longer need access to those documents.
+</Aside>
+
+### Key Security Best Practices
+
+1. **Store keys securely**: Use a secrets management system in production
+2. **Use different keys per environment**: Development, staging, and production should have separate keys
+3. **Backup your keys**: Loss of encryption keys means permanent loss of document access
+4. **Rotate keys periodically**: Consider rotating keys annually or after security incidents
+5. **Limit key access**: Only authorized personnel should have access to encryption keys
+
+### Docker Secrets Example
+
+For production environments, store your encryption keys securely using external secret management systems or secure file systems, and reference them via environment variables.
+
+## Compatibility and Migration
+
+### Enabling Encryption on Existing Instances
+
+When you enable encryption on a Papra instance that already has documents:
+
+- **Existing documents**: Remain unencrypted but accessible
+- **New documents**: Are encrypted using the current KEK
+- **Mixed storage**: Papra automatically handles both encrypted and unencrypted documents
+
+### Migrating Existing Documents to Encrypted Format
+
+If you want to encrypt all existing unencrypted documents after enabling encryption, Papra provides a maintenance command to handle this migration automatically.
+
+<Aside type="caution">
+It's advised to make a backup of your documents and database before running the migration. 
+</Aside>
+
+<Steps>
+
+1. **Verify encryption is properly configured**
+
+   Ensure encryption is enabled and working for new documents before migrating existing ones:
+
+   ```bash
+   # Check that your configuration includes:
+   DOCUMENT_STORAGE_ENCRYPTION_IS_ENABLED=true
+   DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS=<your-key>
+   ```
+
+2. **Run dry-run to preview changes**
+
+   <Tabs>
+     <TabItem label="Docker Compose">
+       ```bash
+       # Run dry-run inside the Docker container
+       docker compose exec papra pnpm maintenance:encrypt-all-documents --dry-run
+       ```
+     </TabItem>
+
+     <TabItem label="Docker">
+       ```bash
+       # Run dry-run inside the Docker container
+       docker exec -it papra pnpm maintenance:encrypt-all-documents --dry-run
+       ```
+     </TabItem>
+
+     <TabItem label="Source Installation">
+       ```bash
+       # From your Papra server directory
+       pnpm maintenance:encrypt-all-documents --dry-run
+       ```
+     </TabItem>
+
+
+   </Tabs>
+
+   This will show you:
+   - How many documents will be encrypted
+   - Which documents will be affected
+   - No actual encryption will be performed
+
+4. **Run the migration**
+
+   <Tabs>
+     <TabItem label="Docker Compose">
+       ```bash
+       # Run migration inside the Docker container
+       docker compose exec papra pnpm maintenance:encrypt-all-documents
+       ```
+     </TabItem>
+
+     <TabItem label="Docker">
+       ```bash
+       # Run migration inside the Docker container
+       docker exec -it papra pnpm maintenance:encrypt-all-documents
+       ```
+     </TabItem>
+
+     <TabItem label="Source Installation">
+       ```bash
+       # From your Papra server directory
+       pnpm maintenance:encrypt-all-documents
+       ```
+     </TabItem>
+   </Tabs>
+
+   The command will:
+   - Find all unencrypted documents
+   - Encrypt each document using your configured KEK
+   - Update database records with encryption metadata
+   - Remove original unencrypted files from storage
+   - Provide progress logging throughout the process
+
+5. **Verify migration success**
+
+   After migration:
+   - Test document access through the Papra interface
+   - Check that storage files are now encrypted (should start with `PP01`)
+   - Verify all documents are accessible and downloadable
+
+</Steps>
+
+<Aside type="tip">
+**Migration Performance**
+
+- The migration processes documents sequentially to ensure reliability
+- Large document collections may take considerable time
+- Monitor disk space during migration (temporary storage overhead)
+- Consider running during maintenance windows for production systems
+</Aside>
+
+#### Troubleshooting Migration Issues
+
+**Migration fails with "Document encryption is not enabled"**
+- Verify `DOCUMENT_STORAGE_ENCRYPTION_IS_ENABLED=true` is set
+- Restart Papra after configuration changes
+
+**Migration fails with "Document encryption keys are not set"**
+- Ensure `DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS` contains valid keys
+- Verify key format is correct (64-character hex string)
+
+**Migration stops or fails partway**
+- Check available disk space
+- Review Papra logs for specific error messages
+- Restore from backup and retry after fixing the issue
+
+**Documents inaccessible after migration**
+- Verify encryption keys are still properly configured
+- Check that Papra can access your storage backend
+- Restore from backup if necessary
+
+### Disabling Encryption
+
+If you disable encryption:
+
+- **Encrypted documents**: Remain encrypted but are automatically decrypted when accessed (if KEK is still available)
+- **New documents**: Are stored unencrypted
+- **Data loss risk**: If you remove the KEK while encrypted documents exist, those documents become inaccessible
+
+<Aside type="caution">
+Disabling encryption doesn't automatically decrypt existing documents in storage. They remain encrypted and require the KEK for access.
+</Aside>
+
+### Storage Driver Compatibility
+
+The encryption layer sits between Papra and your chosen storage driver, providing consistent encryption regardless of where files are stored (S3, Azure Blob Storage, File System, etc.).
+
+## Technical Details
+
+### Encryption Algorithm
+
+- **Algorithm**: AES-256-GCM (Authenticated Encryption)
+- **Key size**: 256 bits (32 bytes)
+- **IV size**: 96 bits (12 bytes)
+- **Authentication tag**: 128 bits (16 bytes)
+
+### File Format
+
+Encrypted files use a custom format with a magic number for identification:
+
+```
+| Magic (4 bytes) | IV (12 bytes) | Encrypted Data | Auth Tag (16 bytes) |
+```
+
+- **Magic number**: `PP01` - identifies Papra encrypted files
+- **IV**: Initialization vector for GCM mode
+- **Encrypted Data**: The actual encrypted document content
+- **Auth Tag**: Authentication tag for integrity verification
+
+### Performance Considerations
+
+- **Streaming encryption**: Files are encrypted/decrypted in streams, minimizing memory usage
+- **No size overhead**: Minimal storage overhead (32 bytes per file for headers)
+- **CPU impact**: Modern processors handle AES encryption efficiently
+
+## Troubleshooting
+
+### Common Issues
+
+**"Document KEK required" error**
+- Ensure `DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS` is set
+- Verify the key format is correct (64 character hex string)
+
+**"Document KEK not found" error**
+- The document was encrypted with a key version that's no longer available
+- Add the missing key version back to your configuration
+
+**"Unsupported encryption algorithm" error**
+- The document uses an encryption algorithm not supported by this Papra version
+- This shouldn't occur in normal operation
+
+**Performance issues**
+- Consider your storage driver's performance characteristics
+- Encryption adds minimal overhead, but network/disk I/O remains the bottleneck
+
+### Verification
+
+To verify encryption is working:
+
+1. Upload a document after enabling encryption
+2. Check your storage backend - the file should not be readable as plain text
+3. The file should start with the magic number `PP01` if you examine it directly
+
+<Aside>
+You can find complete configuration options in the [configuration reference](/self-hosting/configuration). Look for variables prefixed with `DOCUMENT_STORAGE_ENCRYPTION_`.
+</Aside>
+
+## Security Considerations
+
+### Threat Model
+
+Document encryption in Papra protects against:
+
+- **Storage compromise**: If your file storage is breached, documents remain encrypted
+- **Database-only breach**: Without the KEK, wrapped DEKs cannot be unwrapped
+- **Configuration exposure**: If the KEK is exposed, the files remain encrypted as long as the DEK are not exposed
+
+### Limitations
+
+Encryption does not protect against:
+
+- **Application-level access**: Users with document access can view decrypted content
+- **Memory dumps**: Decrypted content exists temporarily in application memory
+- **Key and database compromise**: If KEKs are stolen, all DEKs can be decrypted if the database is compromised
+- **Full system compromise**: If the entire Papra instance is compromised, documents can be accessed

apps/docs/src/content/docs/03-guides/06-tagging-rules.mdx

@@ -0,0 +1,102 @@
+---
+title: Using Tagging Rules
+description: Learn how to automate document organization with tagging rules.
+slug: guides/tagging-rules
+---
+
+## What are Tagging Rules?
+
+Tagging rules allow you to automatically apply tags to documents based on specific conditions. This helps maintain consistent organization without manual effort, especially when dealing with large numbers of documents.
+
+## How Tagging Rules Work
+
+When a tagging rule is enabled, it automatically checks new documents as they're uploaded. If a document matches the rule's conditions, the specified tags are automatically applied.
+
+### Rule Components
+
+Each tagging rule consists of:
+
+1. **Conditions**: Rules that determine which documents should be tagged
+   - Field: The document property to check (e.g., name, content)
+   - Operator: How to compare the field (e.g., contains, equals)
+   - Value: The text to match against
+
+2. **Actions**: The tags to apply when conditions are met
+
+## Applying Rules to Existing Documents
+
+### The "Run Now" Feature
+
+When you create a new tagging rule, it only applies to documents uploaded *after* the rule is created. To apply the rule to documents that already exist in your organization, use the **"Apply to existing documents"** button.
+
+This feature is particularly useful when:
+- You create a new rule and want to organize your existing documents
+- You modify a rule and want to reprocess documents
+- You're setting up your organization and want to retroactively organize imported documents
+
+### How to Apply a Rule to Existing Documents
+
+1. Navigate to your organization's Tagging Rules page
+2. Find the rule you want to apply
+3. Click the **"Apply to existing documents"** button
+4. Confirm the action in the dialog
+5. The task is queued and will be processed in the background
+
+The system will:
+- Queue a background task to process all documents
+- Process documents in batches to avoid overloading the system
+- Check all existing documents in your organization
+- Apply tags where the rule's conditions match
+- Show you a success message once the task is queued
+
+:::tip
+Applying a rule to existing documents runs as a background task, so you don't need to wait for it to complete. The processing happens asynchronously and efficiently handles large document collections by processing them in batches.
+:::
+
+## Best Practices
+
+### Creating Effective Rules
+
+1. **Be specific**: Use precise conditions to avoid over-tagging
+2. **Test first**: Create a rule and test it on a few documents before applying to all existing documents
+3. **Use multiple conditions**: Combine conditions for more accurate matching
+4. **Review regularly**: Periodically review your rules to ensure they're still relevant
+
+### Example Rules
+
+**Invoice Classification**
+- Condition: Document name contains "invoice"
+- Action: Apply "Invoice" tag
+
+**Quarterly Reports**
+- Condition: Document name contains "Q1" or "Q2" or "Q3" or "Q4"
+- Action: Apply "Report" tag
+
+## Using the API
+
+You can also apply tagging rules programmatically using the API. The endpoint enqueues a background task and returns immediately:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  https://api.papra.app/api/organizations/YOUR_ORG_ID/tagging-rules/RULE_ID/apply
+```
+
+Response (HTTP 202 Accepted):
+```json
+{
+  "taskId": "task_abc123"
+}
+```
+
+Where:
+- `taskId`: The ID of the background task processing your request
+
+:::note
+The API returns a task ID immediately. The actual processing happens in the background and may take some time depending on the number of documents. Task status retrieval will be available in a future release.
+:::
+
+## Related Resources
+
+- [API Endpoints Documentation](/resources/api-endpoints)
+- [CLI Documentation](/resources/cli)

apps/docs/src/content/docs/04-resources/01-troubleshooting.mdx

@@ -0,0 +1,40 @@
+---
+title: Troubleshooting
+description: Troubleshooting guide for Papra
+slug: resources/troubleshooting
+---
+
+You can find here some common issues and how to fix them. If you encounter an issue that is not listed here, please [open an issue](https://github.com/papra-hq/papra/issues/new/choose) or [join our Discord](https://papra.app/discord).
+
+## Failed to ensure that the database directory exists
+
+Upon starting the server or a script, you may encounter this error
+
+```
+Failed to ensure that the database directory exists, error while creating the directory
+Error: EACCES: permission denied, mkdir './app-data/db'
+
+```
+
+Before accessing the DB sqlite file, the server will try to ensure that the database directory exists, and if it doesn't, it try will create it. But in case of insufficient permissions, it will fail.
+
+To fix this, you can either:
+
+- Create the directory manually `mkdir -p <your-app-data-dir>/db`
+- Ensure that the directory is owned by the user running the container
+- Run the server as root (not recommended)
+
+## Invalid application origin
+
+Papra ensures [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection by validating the Origin header in requests. This check ensures that requests originate from the application or a trusted source. Any request that does not originate from a trusted origin will be rejected.
+
+If you are self-hosting Papra, you may encounter an error stating that the application origin is invalid while trying to login or register.
+
+To fix this, you can either:
+
+- Update the `APP_BASE_URL` environment variable to match the url of your application (e.g. `https://papra.my-homelab.tld`)
+- Add the current url to the `TRUSTED_ORIGINS` environment variable if you need to allow multiple origins, comma separated. By default the `TRUSTED_ORIGINS` is set to the `APP_BASE_URL`
+- If you are using a reverse proxy, you may need to add the url to the `TRUSTED_ORIGINS` environment variable
+
+
+

apps/docs/src/content/docs/04-resources/03-api-endpoints.mdx

@@ -0,0 +1,322 @@
+---
+title: API Endpoints
+description: The list and details of all the API endpoints available in Papra.
+slug: resources/api-endpoints
+---
+
+## Authentication
+
+The public API uses a bearer token for authentication. You can get a token by logging to your Papra account and creating an API token.
+
+<details>
+
+<summary>How to create an API token</summary>
+
+![API Token](../../../assets/api-key-creation-1.png)
+![API Token](../../../assets/api-key-creation-2.png)
+
+</details>
+
+
+To authenticate your requests, include the token in the `Authorization` header with the `Bearer` prefix:
+
+```
+Authorization: Bearer YOUR_API_TOKEN
+```
+
+### Examples
+
+**Using cURL:**
+```bash
+curl -H "Authorization: Bearer YOUR_API_TOKEN" \
+  https://api.papra.app/api/organizations
+```
+
+**Using JavaScript (fetch):**
+```javascript
+const response = await fetch('https://api.papra.app/api/organizations', {
+  headers: {
+    'Authorization': 'Bearer YOUR_API_TOKEN',
+    'Content-Type': 'application/json'
+  }
+})
+```
+
+### API Key Permissions
+
+When creating an API key, you can select from the following permissions:
+
+**Organizations:**
+- `organizations:create` - Create new organizations
+- `organizations:read` - Read organization information and list organizations of the user
+- `organizations:update` - Update organization details
+- `organizations:delete` - Delete organizations
+
+**Documents:**
+- `documents:create` - Upload and create new documents
+- `documents:read` - Read and download documents
+- `documents:update` - Update document metadata and content
+- `documents:delete` - Delete documents
+
+**Tags:**
+- `tags:create` - Create new tags
+- `tags:read` - Read tag information and list tags
+- `tags:update` - Update tag details
+- `tags:delete` - Delete tags
+
+## Endpoints
+
+### List organizations
+
+**GET** `/api/organizations`
+
+List all organizations accessible to the authenticated user.
+
+- Required API key permissions: `organizations:read`
+- Response (JSON)
+  - `organizations`: The list of organizations.
+
+### Create an organization
+
+**POST** `/api/organizations`
+
+Create a new organization.
+
+- Required API key permissions: `organizations:create`
+- Body (JSON)
+  - `name`: The organization name (3-50 characters).
+- Response (JSON)
+  - `organization`: The created organization.
+
+### Get an organization
+
+**GET** `/api/organizations/:organizationId`
+
+Get an organization by its ID.
+
+- Required API key permissions: `organizations:read`
+- Response (JSON)
+  - `organization`: The organization.
+
+### Update an organization
+
+**PUT** `/api/organizations/:organizationId`
+
+Update an organization's name.
+
+- Required API key permissions: `organizations:update`
+- Body (JSON)
+  - `name`: The new organization name (3-50 characters).
+- Response (JSON)
+  - `organization`: The updated organization.
+
+### Delete an organization
+
+**DELETE** `/api/organizations/:organizationId`
+
+Delete an organization by its ID.
+
+- Required API key permissions: `organizations:delete`
+- Response: empty (204 status code)
+
+### Create a document
+
+**POST** `/api/organizations/:organizationId/documents`
+
+Create a new document in the organization.
+
+- Required API key permissions: `documents:create`
+- Body (form-data)
+  - `file`: The file to upload.
+  - `ocrLanguages`: (optional) The languages to use for OCR.
+- Response (JSON)
+  - `document`: The created document.
+
+### List documents
+
+**GET** `/api/organizations/:organizationId/documents`
+
+List all documents in the organization.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+  - `pageIndex`: (optional, default: 0) The page index to start from.
+  - `pageSize`: (optional, default: 100) The number of documents to return.
+  - `tags`: (optional) The tags IDs to filter by.
+- Response (JSON)
+  - `documents`: The list of documents.
+  - `documentsCount`: The total number of documents.
+
+### List deleted documents (trash)
+
+**GET** `/api/organizations/:organizationId/documents/deleted`
+
+List all deleted documents (in trash) in the organization.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+  - `pageIndex`: (optional, default: 0) The page index to start from.
+  - `pageSize`: (optional, default: 100) The number of documents to return.
+- Response (JSON)
+  - `documents`: The list of deleted documents.
+  - `documentsCount`: The total number of deleted documents.
+
+### Get a document
+
+**GET** `/api/organizations/:organizationId/documents/:documentId`
+
+Get a document by its ID.
+
+- Required API key permissions: `documents:read`
+- Response (JSON)
+  - `document`: The document.
+
+### Delete a document
+
+**DELETE** `/api/organizations/:organizationId/documents/:documentId`
+
+Delete a document by its ID.
+
+- Required API key permissions: `documents:delete`
+- Response: empty (204 status code)
+
+### Get a document file
+
+**GET** `/api/organizations/:organizationId/documents/:documentId/file`
+
+Get a document file content by its ID.
+
+- Required API key permissions: `documents:read`
+- Response: The document file stream.
+
+### Search documents
+
+**GET** `/api/organizations/:organizationId/documents/search`
+
+Search documents in the organization by name or content.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+  - `searchQuery`: The search query.
+  - `pageIndex`: (optional, default: 0) The page index to start from.
+  - `pageSize`: (optional, default: 100) The number of documents to return.
+- Response (JSON)
+  - `searchResults`: The search results.
+    - `documents`: The list of matching documents.
+      - `id`: The document ID.
+      - `name`: The document name.
+
+### Get organization documents statistics
+
+**GET** `/api/organizations/:organizationId/documents/statistics`
+
+Get the statistics (number of documents and total size) of the documents in the organization.
+
+- Required API key permissions: `documents:read`
+- Response (JSON)
+  - `organizationStats`: The organization documents statistics.
+    - `documentsCount`: The total number of documents.
+    - `documentsSize`: The total size of the documents.
+
+### Update a document
+
+**PATCH** `/api/organizations/:organizationId/documents/:documentId`
+
+Change the name or content (for search purposes) of a document.
+
+- Required API key permissions: `documents:update`
+- Body (form-data)
+  - `name`: (optional) The document name.
+  - `content`: (optional) The document content.
+- Response (JSON)
+  - `document`: The updated document.
+
+### Get document activity
+
+**GET** `/api/organizations/:organizationId/documents/:documentId/activity`
+
+Get the activity log of a document.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+  - `pageIndex`: (optional, default: 0) The page index to start from.
+  - `pageSize`: (optional, default: 100) The number of documents to return.
+- Response (JSON)
+  - `activities`: The list of activities.
+
+### Create a tag
+
+**POST** `/api/organizations/:organizationId/tags`
+
+Create a new tag in the organization.
+
+- Required API key permissions: `tags:create`
+- Body (form-data)
+  - `name`: The tag name.
+  - `color`: The tag color in hex format (e.g. `#000000`).
+  - `description`: (optional) The tag description.
+- Response (JSON)
+  - `tag`: The created tag.
+
+### List tags
+
+**GET** `/api/organizations/:organizationId/tags`
+
+List all tags in the organization.
+
+- Required API key permissions: `tags:read`
+- Response (JSON)
+  - `tags`: The list of tags.
+
+### Update a tag
+
+**PUT** `/api/organizations/:organizationId/tags/:tagId`
+
+Change the name, color or description of a tag.
+
+- Required API key permissions: `tags:update`
+- Body
+  - `name`: (optional) The tag name.
+  - `color`: (optional) The tag color in hex format (e.g. `#000000`).
+  - `description`: (optional) The tag description.
+- Response (JSON)
+  - `tag`: The updated tag.
+
+### Delete a tag
+
+**DELETE** `/api/organizations/:organizationId/tags/:tagId`
+
+Delete a tag by its ID.
+
+- Required API key permissions: `tags:delete`
+- Response: empty (204 status code)
+
+### Add a tag to a document
+
+**POST** `/api/organizations/:organizationId/documents/:documentId/tags`
+
+Associate a tag to a document.
+
+- Required API key permissions: `tags:read` and `documents:update`
+- Body
+  - `tagId`: The tag ID.
+- Response: empty (204 status code)
+
+### Remove a tag from a document
+
+**DELETE** `/api/organizations/:organizationId/documents/:documentId/tags/:tagId`
+
+Remove a tag from a document.
+
+- Required API key permissions: `tags:read` and `documents:update`
+- Response: empty (204 status code)
+
+### Apply tagging rule to existing documents
+
+**POST** `/api/organizations/:organizationId/tagging-rules/:taggingRuleId/apply`
+
+Enqueue a background task to apply a tagging rule to all existing documents in the organization. This endpoint returns immediately with a task ID, and the processing happens asynchronously in the background. The task will check all documents and apply tags where the rule's conditions match.
+
+- Required API key permissions: `tags:read` and `documents:update`
+- Response (JSON, HTTP 202)
+  - `taskId`: The ID of the background task. You can use this to track the task's progress (task status retrieval coming in a future release).

apps/docs/src/content/docs/05-architecture/document-deduplication.mdx

@@ -0,0 +1,40 @@
+---
+title: Document Deduplication
+description: How Papra prevents duplicate documents and saves storage space.
+slug: architecture/document-deduplication
+---
+
+## Overview
+
+Papra automatically detects and prevents duplicate documents per organization using content hashing. This ensures that if the same file is uploaded multiple times, only one copy is stored, saving storage space and reducing clutter.
+
+## How It Works
+
+When a document is added to an organization (upload, email ingestion, folder sync, ...), the server computes a **SHA-256 hash** of the file content and checks if a document with the same hash already exists in that organization.
+
+- If there is **no document with the same hash** in the organization, the new document is added as usual
+- If a document **with same content exists**, the upload is rejected
+- If a document **with same content was previously deleted** (in trash), it is restored instead of creating a new copy, the metadata is updated to match the newly added document
+
+
+## Technical Details
+
+### Hash Algorithm
+
+- Papra uses **SHA-256** for content hashing.
+- Computed during streaming upload (no extra I/O)
+- 64-character hexadecimal string stored in the database
+
+### Database Constraint
+
+The database enforces uniqueness with a composite index:
+
+```sql
+UNIQUE (organization_id, original_sha256_hash)
+```
+
+This guarantees no two active documents in the same organization can have identical content.
+
+### File Content Only
+
+Only the **file content** is hashed and used for deduplication, filenames, upload dates, and metadata don't affect deduplication. Two files are considered duplicates if and only if their content is strictly identical.

apps/docs/src/content/docs/05-architecture/no-mutation-principle.mdx

@@ -0,0 +1,38 @@
+---
+title: No-Mutation Principle
+description: Why Papra never modifies your original documents and the architectural decisions behind this choice.
+slug: architecture/no-mutation-principle
+---
+
+## Core Philosophy
+
+Papra follows a fundamental principle: **documents are never mutated after upload**. When you input a document, you can always retrieve it exactly as it was uploaded.
+
+## The Design Choice
+
+An archiving platform should guarantee users they can retrieve their documents in their original form. This means:
+
+- No conversion to different formats
+- No metadata injection into the file itself
+- No overlay of OCR-ed content on scanned PDFs
+- No processing that modifies the original file
+
+The simple mental model is: **"If I input X, I'll retrieve X"**
+
+## Why This Matters
+
+### Trust and Reliability
+
+When archiving important documents, users need absolute confidence that their files remain untouched. Whether it's a legal document, a medical record, or a personal photo, the original should be sacrosanct.
+
+### Simplicity
+
+This approach eliminates the mental overhead of wondering "what happened to my file?" Users don't need to understand concepts like:
+- Original vs. processed versions
+- Format conversions
+- OCR overlays
+- Metadata injection
+
+### Flexibility for the Future
+
+While Papra currently doesn't mutate documents, the architecture leaves room for future enhancements. If needed, a "processed" version concept could be added alongside originals, giving users the choice without forcing a particular model.

apps/docs/src/content/docs/05-architecture/organization-deletion-purge.mdx

@@ -0,0 +1,62 @@
+---
+title: Organization Deletion & Purge
+description: How Papra handles organization deletion with a grace period and eventual purge.
+slug: architecture/organization-deletion-purge
+---
+
+## Overview
+
+Papra implements a two-phase deletion process for organizations: soft deletion followed by hard deletion (purge). This provides a grace period for recovery while ensuring eventual cleanup of resources.
+
+## Deletion Process
+
+### Who Can Delete
+
+Only the **organization owner** can delete an organization. Admins and members do not have this permission.
+
+### What Happens During Deletion
+
+When an organization is deleted:
+
+1. **Members are removed** - All organization members are stripped from the organization, leaving them dangling
+2. **Invitations are removed** - All pending invitations are deleted
+3. **Metadata is recorded**:
+   - `deletedAt`: Timestamp when the deletion occurred
+   - `deletedBy`: ID of the user (owner) who deleted the organization
+   - `scheduledPurgeAt`: Future date when hard deletion will occur (default: 30 days)
+
+The organization itself remains in the database in a soft-deleted state, allowing for potential restoration.
+
+## Purge Process
+
+### When Purge Occurs
+
+Hard deletion (purge) happens when `scheduledPurgeAt` is reached. By default, this is **30 days** after the deletion date.
+
+### What Gets Purged
+
+When an organization is purged:
+
+- **All documents** are deleted from storage
+- **All database records** related to the organization are removed (cascade handles related records, like Tags, Intake Emails, etc.)
+- The organization itself is permanently deleted
+
+The process handles documents in batches using an iterator to avoid memory issues with large organizations.
+
+### Background Task
+
+Purging is handled by a periodic background task that:
+
+1. Queries for organizations with `scheduledPurgeAt` in the past
+2. For each expired organization:
+   - Deletes all document files from storage
+   - Hard deletes the organization (cascade handles related records)
+3. Logs the process for monitoring and debugging
+
+The task continues even if individual file deletions fail, logging errors without blocking the entire purge operation.
+
+## Recovery
+
+Organizations can be restored before the `scheduledPurgeAt` date is reached, but only by the user who deleted them (the previous owner). After this date, recovery is no longer possible, even if the purge has not yet occurred.
+
+> Note: After recovery, the organization owner must re-invite members as they were removed during deletion.

apps/docs/src/content/docs/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Papra documentation
-description: Papra documentation.
+description: Documentation for Papra, the minimalistic document archiving platform.
 hero:
   title: Papra Docs
   tagline: Documentation for Papra, the minimalistic document archiving platform.
@@ -53,9 +53,9 @@ In today's digital world, managing countless important documents efficiently and
 - **Content extraction**: Automatically extract text from images or scanned documents for search.
 - **Tagging Rules**: Automatically tag documents based on custom rules.
 - **Folder ingestion**: Automatically import documents from a folder.
-- *In progress:* **i18n**: Support for multiple languages.
-- *Coming soon:* **SDK and API**: Build your own applications on top of Papra.
-- *Coming soon:* **CLI**: Manage your documents from the command line.
+- **API, SDK and webhooks**: Build your own applications on top of Papra.
+- **CLI**: Manage your documents from the command line.
+- **i18n**: Support for multiple languages.
 - *Coming soon:* **Document sharing**: Share documents with others.
 - *Coming soon:* **Document requests**: Generate upload links for people to add documents.
 

apps/docs/src/content/navigation.ts

@@ -1,10 +1,11 @@
 import type { StarlightUserConfig } from '@astrojs/starlight/types';
 
-export const sidebar: StarlightUserConfig['sidebar'] = [
+export const sidebar = [
   {
     label: 'Getting Started',
     items: [
       { label: 'Introduction', slug: '' },
+      { label: 'Changelog', link: '/changelog' },
     ],
   },
   {
@@ -12,6 +13,7 @@ export const sidebar: StarlightUserConfig['sidebar'] = [
     items: [
       { label: 'Using Docker', slug: 'self-hosting/using-docker' },
       { label: 'Using Docker Compose', slug: 'self-hosting/using-docker-compose' },
+      { label: 'Docker Compose Generator', link: '/docker-compose-generator', badge: { text: 'new', variant: 'note' } },
       { label: 'Configuration', slug: 'self-hosting/configuration' },
     ],
   },
@@ -30,11 +32,44 @@ export const sidebar: StarlightUserConfig['sidebar'] = [
         label: 'Setup Ingestion Folder',
         slug: 'guides/setup-ingestion-folder',
       },
+      {
+        label: 'Setup Custom OAuth2 Providers',
+        slug: 'guides/setup-custom-oauth2-providers',
+      },
+      {
+        label: 'Document Encryption',
+        slug: 'guides/document-encryption',
+      },
+      {
+        label: 'Tagging Rules',
+        slug: 'guides/tagging-rules',
+      },
+    ],
+  },
+  {
+    label: 'Architecture',
+    items: [
+      {
+        label: 'No-Mutation Principle',
+        slug: 'architecture/no-mutation-principle',
+      },
+      {
+        label: 'Document Deduplication',
+        slug: 'architecture/document-deduplication',
+      },
+      {
+        label: 'Organization Deletion',
+        slug: 'architecture/organization-deletion-purge',
+      },
     ],
   },
   {
     label: 'Resources',
     items: [
+      {
+        label: 'Troubleshooting',
+        slug: 'resources/troubleshooting',
+      },
       {
         label: 'CLI Documentation',
         slug: 'resources/cli',
@@ -46,6 +81,10 @@ export const sidebar: StarlightUserConfig['sidebar'] = [
           target: '_blank',
         },
       },
+      {
+        label: 'API Endpoints',
+        slug: 'resources/api-endpoints',
+      },
     ],
   },
-];
+] satisfies StarlightUserConfig['sidebar'];

apps/docs/src/docker-compose-generator/dc-generator.astro

@@ -0,0 +1,487 @@
+---
+import { codeToHtml } from 'shiki';
+
+const images = {
+  GitHub: 'ghcr.io/papra-hq/papra',
+  DockerHub: 'corentinth/papra',
+};
+
+const defaultDockerCompose = `
+services:
+  papra:
+    image: ghcr.io/papra-hq/papra:latest
+    container_name: papra
+    restart: unless-stopped
+    ports:
+      - 1221:1221
+    environment:
+      - AUTH_SECRET=change-me
+      - APP_BASE_URL=http://localhost:1221
+    volumes:
+      - ./app-data:/app/app-data
+    user: 1000:1000
+`.trim();
+
+const dcHtml = await codeToHtml(defaultDockerCompose, { theme: 'vitesse-black', lang: 'yaml' });
+const defaultCommand = `mkdir -p ./app-data/{db,documents} && docker compose up -d`;
+---
+
+
+<h2 class="mt-8 mb-2">General settings</h2>
+
+<div class="flex items-center gap-2 mt-1">
+  <label for="port" class="min-w-32">External port</label>
+  <input id="port" class="input-field" value="1221" type="number" min="1024" max="65535" placeholder="eg: 1221" />
+</div>
+
+<div class="flex items-center gap-2 mt-1">
+  <label for="app-base-url" class="min-w-32">App base URL</label>
+  <input id="app-base-url" class="input-field" type="text" placeholder="eg: https://papra.example.com" value="http://localhost:1221" />
+</div>
+
+<div class="flex items-center gap-2 mt-1">
+  <label for="source" class="min-w-32">Image source</label>
+  <select class="input-field mt-0" id="source">
+    {Object.entries(images).map(([registry, imageName]) => <option class="bg-background" value={imageName}>{`${registry} - ${imageName}`}</option>)}
+  </select>
+</div>
+
+<div class="flex items-center gap-2 mt-1">
+  <label for="service-name" class="min-w-32">Service Name</label>
+  <input id="service-name" class="input-field" value="papra" type="text" placeholder="eg: papra" />
+</div>
+
+<div class="flex items-center gap-2 mt-1">
+  <label
+    for="auth-secret"
+    class="min-w-32"
+  >
+  Auth secret
+  </label>
+  <div class="flex items-center gap-2 mt-0 w-full">
+    <input class="input-field font-mono" id="auth-secret" type="text" placeholder="eg: 1234567890" />
+    <button class="btn bg-muted" id="refresh-secret"> Refresh </button>
+  </div>
+</div>
+
+<div class="flex items-center gap-2 mt-1">
+  <label for="volume-path" class="min-w-32">Volume path</label>
+  <input id="volume-path" class="input-field" value="./app-data" type="text" placeholder="eg: ./app-data" />
+</div>
+
+<div class="flex items-center gap-2 mt-1">
+  <label for="privileged-mode" class="min-w-32">Privileged mode</label>
+  <div class="flex items-center gap-2 mt-0 w-full">
+    <select class="input-field mt-0" id="privileged-mode">
+      <option value="false" class="bg-background">Rootless</option>
+      <option value="true" class="bg-background">Root</option>
+    </select>
+  </div>
+</div>
+
+<h2 class="mt-8 mb-2">Ingestion folder</h2>
+
+<div class="flex items-center gap-2 mt-1">
+  <label for="ingestion-enabled" class="min-w-32">Enable ingestion</label>
+  <div class="flex items-center gap-2 mt-0 w-full">
+    <select class="input-field mt-0" id="ingestion-enabled">
+      <option value="false" class="bg-background">Disabled</option>
+      <option value="true" class="bg-background">Enabled</option>
+    </select>
+  </div>
+</div>
+
+<div class="flex items-center gap-2 mt-1" id="ingestion-path-container" style="display: none;">
+  <label for="ingestion-path" class="min-w-32">Ingestion path</label>
+  <input id="ingestion-path" class="input-field" value="./ingestion" type="text" placeholder="eg: ./ingestion" />
+</div>
+
+<h2 class="mt-8 mb-2">Intake emails</h2>
+<div class="flex items-center gap-2 mt-1">
+  <label for="intake-email-enabled" class="min-w-32">Enabled</label>
+  <div class="flex items-center gap-2 mt-0 w-full">
+    <select class="input-field mt-0" id="intake-email-enabled">
+      <option value="false" class="bg-background">Disabled</option>
+      <option value="true" class="bg-background">Enabled</option>
+    </select>
+  </div>
+</div>
+
+<div class="flex items-center gap-2 mt-1" id="intake-email-driver-container" style="display: none;">
+  <label for="intake-email-driver" class="min-w-32">Driver</label>
+  <div class="flex items-center gap-2 mt-0 w-full">
+    <select class="input-field mt-0" id="intake-email-driver">
+      <option value="owlrelay" class="bg-background">OwlRelay</option>
+      <option value="random-username" class="bg-background">Cloudflare Email Worker</option>
+    </select>
+  </div>
+</div>
+
+<div id="intake-email-owlrelay-config" style="display: none;" class="mt-1">
+  <div class="flex items-center gap-2 mt-1">
+    <label for="intake-email-owlrelay-api-key" class="min-w-32">API Key</label>
+    <input id="intake-email-owlrelay-api-key" class="input-field" type="text" placeholder="owrl_*****" />
+  </div>
+  <div class="flex items-center gap-2 mt-1">
+    <label for="intake-email-owlrelay-webhook-url" class="min-w-32">Webhook URL</label>
+    <input id="intake-email-owlrelay-webhook-url" class="input-field" type="text" placeholder="https://your-instance.com/api/intake-emails/ingest" value="https://localhost:1221/api/intake-emails/ingest" />
+  </div>
+</div>
+
+<div id="intake-email-cf-worker-config" style="display: none;" class="mt-1">
+  <div class="flex items-center gap-2 mt-1">
+    <label for="intake-email-cf-email-domain" class="min-w-32">Email domain</label>
+    <input id="intake-email-cf-email-domain" class="input-field" type="text" placeholder="papra.email" />
+  </div>
+</div>
+
+<div class="flex items-center gap-2 mt-1" id="intake-email-webhook-secret-container" style="display: none;">
+  <label for="intake-email-webhook-secret" class="min-w-32">Webhook secret</label>
+  <div class="flex items-center gap-2 mt-0 w-full">
+    <input class="input-field font-mono" id="intake-email-webhook-secret" type="text" placeholder="a-random-key" />
+    <button class="btn bg-muted" id="refresh-webhook-secret">Refresh</button>
+  </div>
+</div>
+
+<div id="docker-compose-output" class="mt-12" set:html={dcHtml} />
+
+<pre id="command-output" class="bg-card p-4 rounded-md text-muted-foreground text-sm font-mono overflow-x-auto">{defaultCommand}</pre>
+
+<div class="flex items-center gap-2 mt-4">
+  <button class="btn bg-muted mt-0" id="download-button">Download docker-compose.yml</button>
+  <button class="btn bg-muted mt-0" id="copy-button">Copy docker compose to clipboard</button>
+  <button class="btn bg-muted mt-0" id="copy-command-button">Copy command</button>
+</div>
+
+
+<script>
+import { codeToHtml } from 'shiki';
+import { stringify } from 'yaml';
+
+const portInput = document.getElementById('port') as HTMLInputElement;
+const sourceSelect = document.getElementById('source') as HTMLSelectElement;
+const serviceNameInput = document.getElementById('service-name') as HTMLInputElement;
+const authSecretInput = document.getElementById('auth-secret') as HTMLInputElement;
+const appBaseUrlInput = document.getElementById('app-base-url') as HTMLInputElement;
+const refreshSecretButton = document.getElementById('refresh-secret');
+const copyButton = document.getElementById('copy-button');
+const dockerComposeOutput = document.getElementById('docker-compose-output');
+const downloadButton = document.getElementById('download-button');
+const volumePathInput = document.getElementById('volume-path') as HTMLInputElement;
+const privilegedModeSelect = document.getElementById('privileged-mode') as HTMLSelectElement;
+const ingestionEnabledSelect = document.getElementById('ingestion-enabled') as HTMLSelectElement;
+const ingestionPathInput = document.getElementById('ingestion-path') as HTMLInputElement;
+const ingestionPathContainer = document.getElementById('ingestion-path-container') as HTMLDivElement;
+const intakeEmailEnabledSelect = document.getElementById('intake-email-enabled') as HTMLSelectElement;
+const intakeDriverSelect = document.getElementById('intake-email-driver') as HTMLSelectElement;
+const owlrelayConfig = document.getElementById('intake-email-owlrelay-config') as HTMLDivElement;
+const cfWorkerConfig = document.getElementById('intake-email-cf-worker-config') as HTMLDivElement;
+const owlrelayApiKeyInput = document.getElementById('intake-email-owlrelay-api-key') as HTMLInputElement;
+const owlrelayWebhookUrlInput = document.getElementById('intake-email-owlrelay-webhook-url') as HTMLInputElement;
+const cfEmailDomainInput = document.getElementById('intake-email-cf-email-domain') as HTMLInputElement;
+const webhookSecretInput = document.getElementById('intake-email-webhook-secret') as HTMLInputElement;
+const refreshWebhookSecretButton = document.getElementById('refresh-webhook-secret');
+const commandOutput = document.getElementById('command-output');
+const copyCommandButton = document.getElementById('copy-command-button');
+
+// Track whether the app base URL has been customized by the user
+let isAppBaseUrlCustomized = false;
+// Track whether the webhook URL has been customized by the user
+let isWebhookUrlCustomized = false;
+
+function getRandomString() {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  return Array.from({ length: 48 }, () => alphabet[Math.floor(Math.random() * alphabet.length)]).join('');
+}
+
+function copyToClipboard(text: string) {
+  navigator.clipboard.writeText(text);
+}
+
+function isDefaultAppBaseUrl(url: string, port: string): boolean {
+  return url === `http://localhost:${port}`;
+}
+
+function generateDefaultWebhookUrl(baseUrl: string): string {
+  // Remove trailing slash if present
+  const cleanBaseUrl = baseUrl.replace(/\/$/, '');
+  return `${cleanBaseUrl}/api/intake-emails/ingest`;
+}
+
+function isDefaultWebhookUrl(webhookUrl: string, baseUrl: string): boolean {
+  return webhookUrl === generateDefaultWebhookUrl(baseUrl);
+}
+
+function refreshIsWebhookUrlCustomized() {
+  const currentBaseUrl = appBaseUrlInput.value.trim();
+  const currentWebhookUrl = owlrelayWebhookUrlInput.value.trim();
+
+  if (isDefaultWebhookUrl(currentWebhookUrl, currentBaseUrl)) {
+    isWebhookUrlCustomized = false;
+  } else {
+    isWebhookUrlCustomized = true;
+  }
+}
+
+function refreshIsAppBaseUrlCustomized() {
+  const currentPort = portInput.value;
+  const currentUrl = appBaseUrlInput.value.trim();
+
+  if (isDefaultAppBaseUrl(currentUrl, currentPort)) {
+    isAppBaseUrlCustomized = false;
+  } else {
+    isAppBaseUrlCustomized = true;
+  }
+}
+
+function updateWebhookUrlFromBaseUrl() {
+  if (!isWebhookUrlCustomized) {
+    const baseUrl = appBaseUrlInput.value.trim();
+    if (baseUrl) {
+      owlrelayWebhookUrlInput.value = generateDefaultWebhookUrl(baseUrl);
+    }
+  }
+}
+
+function updateAppBaseUrlFromPort() {
+  if (!isAppBaseUrlCustomized) {
+    const port = portInput.value;
+    appBaseUrlInput.value = `http://localhost:${port}`;
+    // Also update webhook URL when app base URL changes
+    updateWebhookUrlFromBaseUrl();
+  }
+}
+
+function handlePortChange() {
+  updateAppBaseUrlFromPort();
+  updateDockerCompose();
+}
+
+function handleAppBaseUrlChange() {
+  refreshIsAppBaseUrlCustomized();
+  updateWebhookUrlFromBaseUrl();
+  updateDockerCompose();
+}
+
+function handleWebhookUrlChange() {
+  refreshIsWebhookUrlCustomized();
+  updateDockerCompose();
+}
+
+function getDockerComposeYml() {
+  const serviceName = serviceNameInput.value;
+  const isRootless = privilegedModeSelect.value === 'false';
+  const image = sourceSelect.value;
+  const port = portInput.value;
+  const authSecret = authSecretInput.value;
+  const volumePath = volumePathInput.value;
+  const isIngestionEnabled = ingestionEnabledSelect.value === 'true';
+  const ingestionPath = ingestionPathInput.value;
+  const intakeEmailEnabled = intakeEmailEnabledSelect.value === 'true';
+  const intakeDriver = intakeDriverSelect.value;
+  const webhookSecret = webhookSecretInput.value;
+  const appBaseUrl = appBaseUrlInput.value.trim() || `http://localhost:${port}`;
+
+  const version = isRootless ? 'latest' : 'latest-root';
+  const fullImage = `${image}:${version}`;
+
+  const environment = [
+    `AUTH_SECRET=${authSecret}`,
+    `APP_BASE_URL=${appBaseUrl}`,
+    isIngestionEnabled && 'INGESTION_FOLDER_IS_ENABLED=true',
+    intakeEmailEnabled && 'INTAKE_EMAILS_IS_ENABLED=true',
+    intakeEmailEnabled && `INTAKE_EMAILS_DRIVER=${intakeDriver}`,
+    intakeEmailEnabled && `INTAKE_EMAILS_WEBHOOK_SECRET=${webhookSecret}`,
+    intakeEmailEnabled && intakeDriver === 'owlrelay' && owlrelayApiKeyInput.value && `OWLRELAY_API_KEY=${owlrelayApiKeyInput.value}`,
+    intakeEmailEnabled && intakeDriver === 'owlrelay' && owlrelayWebhookUrlInput.value && `OWLRELAY_WEBHOOK_URL=${owlrelayWebhookUrlInput.value}`,
+    intakeEmailEnabled && intakeDriver === 'random-username' && cfEmailDomainInput.value && `INTAKE_EMAILS_EMAIL_GENERATION_DOMAIN=${cfEmailDomainInput.value}`,
+  ].flat().filter(Boolean);
+
+  const volumes = [
+    `${volumePath}:/app/app-data`,
+    isIngestionEnabled && `${ingestionPath}:/app/ingestion`,
+  ].filter(Boolean);
+
+  const dc = {
+    services: {
+      [serviceName]: {
+        image: fullImage,
+        container_name: serviceName,
+        restart: 'unless-stopped',
+        ports: [`${port}:1221`],
+        environment,
+        volumes,
+        ...(isRootless && {
+          user: '1000:1000',
+        }),
+      },
+    },
+  };
+
+  return stringify(dc);
+}
+
+function getStartCommand() {
+  const volumePath = volumePathInput.value;
+  const volumePathNormalized = volumePath.replace(/\/$/, '');
+  const volumeWithSubdirs = `${volumePathNormalized}/{db,documents}`;
+
+  const mkdirCommand = `mkdir -p ${volumeWithSubdirs}`;
+
+  const dockerCommand = 'docker compose up -d';
+
+  return `${mkdirCommand} && ${dockerCommand}`;
+}
+
+async function updateDockerCompose() {
+  const dockerCompose = getDockerComposeYml();
+  const command = getStartCommand();
+
+  const html = await codeToHtml(dockerCompose, { theme: 'vitesse-black', lang: 'yaml' });
+
+  if (dockerComposeOutput) {
+    dockerComposeOutput.innerHTML = html;
+  }
+
+  if (commandOutput) {
+    commandOutput.textContent = command;
+  }
+}
+
+function handleCopy() {
+  const dockerCompose = getDockerComposeYml();
+
+  copyToClipboard(dockerCompose);
+
+  if (copyButton) {
+    copyButton.textContent = 'Copied!';
+  }
+
+  setTimeout(() => {
+    if (copyButton) {
+      copyButton.textContent = 'Copy to clipboard';
+    }
+  }, 1000);
+}
+
+function handleRefreshSecret() {
+  authSecretInput.value = getRandomString();
+  updateDockerCompose();
+}
+
+function handleDownload() {
+  const dockerCompose = getDockerComposeYml();
+
+  const blob = new Blob([dockerCompose], { type: 'text/yaml' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'docker-compose.yml';
+  a.click();
+}
+
+function handleIngestionEnabledChange() {
+  const isEnabled = ingestionEnabledSelect.value === 'true';
+  ingestionPathContainer.style.display = isEnabled ? 'flex' : 'none';
+  updateDockerCompose();
+}
+
+function handleIntakeEmailEnabledChange() {
+  const isEnabled = intakeEmailEnabledSelect.value === 'true';
+  const driverContainer = document.getElementById('intake-email-driver-container');
+  const webhookSecretContainer = document.getElementById('intake-email-webhook-secret-container');
+
+  if (driverContainer) {
+    driverContainer.style.display = isEnabled ? 'flex' : 'none';
+  }
+  if (webhookSecretContainer) {
+    webhookSecretContainer.style.display = isEnabled ? 'flex' : 'none';
+  }
+
+  if (!isEnabled) {
+    // Reset driver-specific configs when disabled
+    if (owlrelayConfig) {
+      owlrelayConfig.style.display = 'none';
+    }
+    if (cfWorkerConfig) {
+      cfWorkerConfig.style.display = 'none';
+    }
+  } else {
+    // Show the appropriate driver config
+    handleIntakeDriverChange();
+  }
+
+  updateDockerCompose();
+}
+
+function handleIntakeDriverChange() {
+  const driver = intakeDriverSelect.value;
+  const isEnabled = intakeEmailEnabledSelect.value === 'true';
+
+  if (!isEnabled) {
+    return;
+  }
+
+  if (owlrelayConfig) {
+    owlrelayConfig.style.display = driver === 'owlrelay' ? 'block' : 'none';
+  }
+  if (cfWorkerConfig) {
+    cfWorkerConfig.style.display = driver === 'random-username' ? 'block' : 'none';
+  }
+
+  updateDockerCompose();
+}
+
+function handleRefreshWebhookSecret() {
+  webhookSecretInput.value = getRandomString();
+  updateDockerCompose();
+}
+
+function handleCopyCommand() {
+  const command = getStartCommand();
+
+  copyToClipboard(command);
+
+  if (copyCommandButton) {
+    copyCommandButton.textContent = 'Copied!';
+  }
+
+  setTimeout(() => {
+    if (copyCommandButton) {
+      copyCommandButton.textContent = 'Copy command';
+    }
+  }, 1000);
+}
+
+// Add event listeners
+portInput.addEventListener('input', handlePortChange);
+sourceSelect.addEventListener('change', updateDockerCompose);
+serviceNameInput.addEventListener('input', updateDockerCompose);
+authSecretInput.addEventListener('input', updateDockerCompose);
+appBaseUrlInput.addEventListener('input', handleAppBaseUrlChange);
+refreshSecretButton?.addEventListener('click', handleRefreshSecret);
+copyButton?.addEventListener('click', handleCopy);
+downloadButton?.addEventListener('click', handleDownload);
+volumePathInput.addEventListener('input', updateDockerCompose);
+privilegedModeSelect.addEventListener('change', updateDockerCompose);
+ingestionEnabledSelect.addEventListener('change', handleIngestionEnabledChange);
+ingestionPathInput.addEventListener('input', updateDockerCompose);
+intakeEmailEnabledSelect.addEventListener('change', handleIntakeEmailEnabledChange);
+intakeDriverSelect.addEventListener('change', handleIntakeDriverChange);
+owlrelayApiKeyInput.addEventListener('input', updateDockerCompose);
+owlrelayWebhookUrlInput.addEventListener('input', handleWebhookUrlChange);
+cfEmailDomainInput.addEventListener('input', updateDockerCompose);
+webhookSecretInput.addEventListener('input', updateDockerCompose);
+refreshWebhookSecretButton?.addEventListener('click', handleRefreshWebhookSecret);
+copyCommandButton?.addEventListener('click', handleCopyCommand);
+
+authSecretInput.value = getRandomString();
+
+// Initial render
+updateDockerCompose();
+
+// Initial setup
+handleIngestionEnabledChange();
+handleIntakeEmailEnabledChange();
+webhookSecretInput.value = getRandomString();
+</script>

apps/docs/src/markdown.ts

@@ -0,0 +1,16 @@
+import { marked } from 'marked';
+
+const renderer = new marked.Renderer();
+renderer.heading = function ({ text, depth }) {
+  const slug = text.toLowerCase().replace(/\W+/g, '-');
+  return `
+<div class="sl-heading-wrapper level-h${depth}">
+<h${depth} id="${slug}">${text}</h${depth}>
+<a class="sl-anchor-link" href="#${slug}"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Configuration files”</span></a>
+</div>
+`.trim().replace(/\n/g, '');
+};
+
+export function renderMarkdown(markdown: string) {
+  return marked.parse(markdown, { renderer });
+}

apps/docs/src/pages/changelog.astro

@@ -0,0 +1,55 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import rawChangelog from '../../../../packages/docker/CHANGELOG.md?raw';
+import { parseChangelog } from '../changelog-parser';
+import { renderMarkdown } from '../markdown';
+
+const changelog = parseChangelog(rawChangelog);
+
+---
+
+<StarlightPage
+  frontmatter={{
+    title: 'Papra changelog',
+    description: 'View the changelogs of the docker images released by Papra.',
+    tableOfContents: false,
+  }}
+>
+  <p>
+    Here are the changelogs of the docker images released by Papra.<br />
+    For version after v0.9.6, Papra uses Calver as a versioning system with the format YY.MM.N where N is the number of releases in the month starting at 0 (e.g. 25.06.0 is the first release of June 2025).
+  </p>
+
+
+  {
+    changelog.map(({ entries, version }) => (
+      <section>
+
+        <h2 id={version} class="pb-1 mt-14">v{version}</h2>
+        <ul>
+          {entries.map(entry => (
+            <li>
+              <div class="flex flex-col">
+                <div class="text-foreground lh-normal changelog-entry" set:html={renderMarkdown(entry.content)} />
+                <div class="text-xs mt-1 flex gap-1 flex-wrap">
+                  <a href={entry.pr.url} class="text-muted-foreground hover:bg-muted transition border border-muted border-solid rounded-md no-underline px-1 py-0.5">PR #{entry.pr.number}</a>
+                  <a href={entry.commit.url} class="text-muted-foreground hover:bg-muted transition border border-muted border-solid rounded-md no-underline px-1 py-0.5">{entry.commit.hash.slice(0, 7)}</a>
+                  <a href={entry.contributor.url} class="text-muted-foreground hover:bg-muted transition border border-muted border-solid rounded-md no-underline px-1 py-0.5">
+                    By @{entry.contributor.username}
+                  </a>
+                </div>
+              </div>
+            </li>
+          ))}
+        </ul>
+      </section>
+    ))
+  }
+</StarlightPage>
+
+<style is:global>
+.changelog-entry pre {
+  border-radius: 6px;
+  color: hsl(var(--muted-foreground) / var(--un-text-opacity));
+}
+</style>

apps/docs/src/pages/docker-compose-generator.astro

@@ -0,0 +1,16 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import DockerComposeGeneratorComp from '../docker-compose-generator/dc-generator.astro';
+---
+
+<StarlightPage
+  frontmatter={{
+        title: 'Papra docker-compose.yml generator',
+        description: 'Generate a custom docker-compose.yml file for Papra, tailored to your needs.',
+        tableOfContents: false,
+    }}
+>
+    <p>This tool will help you generate a custom docker-compose.yml file for Papra, tailored to your needs. You can personalize the service name, the port, the auth secret, and the source image.</p>
+    <p>For more configuration options, you can use the <a href="/self-hosting/configuration">configuration reference</a>.</p>
+    <DockerComposeGeneratorComp />
+</StarlightPage>

apps/docs/src/pages/docs-navigation.json.ts

@@ -0,0 +1,28 @@
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { sidebar } from '../content/navigation';
+
+export const GET: APIRoute = async ({ site }) => {
+  const docs = await getCollection('docs');
+
+  const sections = sidebar.map((section) => {
+    return {
+      label: section.label,
+      items: section
+        .items
+        .filter(item => item.slug !== undefined || (item.link && !item.link.startsWith('http')))
+        .map((item) => {
+          const slug = item.slug ?? item.link?.replace(/^\//, '');
+
+          return {
+            label: item.label,
+            slug,
+            url: new URL(slug, site).toString(),
+            description: docs.find(doc => (doc.id === slug || (slug === '' && doc.id === 'index')))?.data.description,
+          };
+        }),
+    };
+  });
+
+  return new Response(JSON.stringify(sections));
+};

apps/docs/src/pages/papra-config-schema.json.ts

@@ -1,7 +1,7 @@
 import type { APIRoute } from 'astro';
 import type { ConfigDefinition } from 'figue';
-import { z } from 'astro:content';
 import { mapValues } from 'lodash-es';
+import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { configDefinition } from '../../../papra-server/src/modules/config/config';
 

apps/docs/tsconfig.json

@@ -1,5 +1,10 @@
 {
   "extends": "astro/tsconfigs/strict",
-  "include": [".astro/types.d.ts", "**/*"],
-  "exclude": ["dist"]
+  "include": [
+    ".astro/types.d.ts",
+    "**/*"
+  ],
+  "exclude": [
+    "dist"
+  ]
 }

apps/docs/uno.config.ts

@@ -0,0 +1,99 @@
+import {
+  defineConfig,
+  presetTypography,
+  presetUno,
+  transformerDirectives,
+  transformerVariantGroup,
+} from 'unocss';
+import presetAnimations from 'unocss-preset-animations';
+
+export default defineConfig({
+  presets: [
+    presetUno({
+      dark: {
+        dark: '[data-theme="dark"]',
+        light: '[data-theme="light"]',
+      },
+      prefix: '',
+    }),
+    presetAnimations(),
+    presetTypography(),
+  ],
+  transformers: [transformerVariantGroup(), transformerDirectives()],
+  theme: {
+    colors: {
+      border: 'hsl(var(--border))',
+      input: 'hsl(var(--input))',
+      ring: 'hsl(var(--ring))',
+      background: 'hsl(var(--background))',
+      foreground: 'hsl(var(--foreground))',
+      primary: {
+        DEFAULT: 'hsl(var(--primary))',
+        foreground: 'hsl(var(--primary-foreground))',
+      },
+      secondary: {
+        DEFAULT: 'hsl(var(--secondary))',
+        foreground: 'hsl(var(--secondary-foreground))',
+      },
+      destructive: {
+        DEFAULT: 'hsl(var(--destructive))',
+        foreground: 'hsl(var(--destructive-foreground))',
+      },
+      muted: {
+        DEFAULT: 'hsl(var(--muted))',
+        foreground: 'hsl(var(--muted-foreground))',
+      },
+      accent: {
+        DEFAULT: 'hsl(var(--accent))',
+        foreground: 'hsl(var(--accent-foreground))',
+      },
+      popover: {
+        DEFAULT: 'hsl(var(--popover))',
+        foreground: 'hsl(var(--popover-foreground))',
+      },
+      card: {
+        DEFAULT: 'hsl(var(--card))',
+        foreground: 'hsl(var(--card-foreground))',
+      },
+    },
+    borderRadius: {
+      lg: 'var(--radius)',
+      md: 'calc(var(--radius) - 2px)',
+      sm: 'calc(var(--radius) - 4px)',
+    },
+    animation: {
+      keyframes: {
+        'accordion-down':
+          '{ from { height: 0 } to { height: var(--kb-accordion-content-height) } }',
+        'accordion-up':
+          '{ from { height: var(--kb-accordion-content-height) } to { height: 0 } }',
+        'collapsible-down':
+          '{ from { height: 0 } to { height: var(--kb-collapsible-content-height) } }',
+        'collapsible-up':
+          '{ from { height: var(--kb-collapsible-content-height) } to { height: 0 } }',
+        'caret-blink': '{ 0%,70%,100% { opacity: 1 } 20%,50% { opacity: 0 } }',
+      },
+      timingFns: {
+        'accordion-down': 'ease-out',
+        'accordion-up': 'ease-out',
+        'collapsible-down': 'ease-out',
+        'collapsible-up': 'ease-out',
+        'caret-blink': 'ease-out',
+      },
+      durations: {
+        'accordion-down': '0.2s',
+        'accordion-up': '0.2s',
+        'collapsible-down': '0.2s',
+        'collapsible-up': '0.2s',
+        'caret-blink': '1.25s',
+      },
+      counts: {
+        'caret-blink': 'infinite',
+      },
+    },
+  },
+  shortcuts: {
+    'input-field': 'flex h-9 w-full bg-none outline-none rounded-lg border border-border border-solid bg-inherit px-3 py-1 text-sm shadow-none placeholder:text-muted-foreground focus-visible:(outline-none ring-1.5 ring-ring) disabled:(cursor-not-allowed opacity-50) transition-shadow',
+    'btn': 'text-sm font-medium hover:opacity-80 rounded-lg transition-all px-4 py-2 bg-none outline-none border-none cursor-pointer',
+  },
+});

apps/mobile/.gitignore

@@ -0,0 +1,43 @@
+# Learn more https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files
+
+# dependencies
+node_modules/
+
+# Expo
+.expo/
+dist/
+web-build/
+expo-env.d.ts
+
+# Native
+.kotlin/
+*.orig.*
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+
+# Metro
+.metro-health-check*
+
+# debug
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+
+# macOS
+.DS_Store
+*.pem
+
+# local env files
+.env*.local
+
+# typescript
+*.tsbuildinfo
+
+app-example
+
+# generated native folders
+/ios
+/android

apps/mobile/README.md

@@ -0,0 +1,5 @@
+# Papra Mobile App
+
+React Native mobile application for Papra document management platform, built with Expo.
+
+// Todo: Add more details about setup, development, and usage instructions.

apps/mobile/app.json

@@ -0,0 +1,55 @@
+{
+  "expo": {
+    "name": "mobile",
+    "slug": "mobile",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./src/assets/images/icon.png",
+    "scheme": "papra",
+    "userInterfaceStyle": "automatic",
+    "newArchEnabled": true,
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#E6F4FE",
+        "foregroundImage": "./src/assets/images/android-icon-foreground.png",
+        "backgroundImage": "./src/assets/images/android-icon-background.png",
+        "monochromeImage": "./src/assets/images/android-icon-monochrome.png"
+      },
+      "edgeToEdgeEnabled": true,
+      "predictiveBackGestureEnabled": false
+    },
+    "web": {
+      "output": "static",
+      "favicon": "./src/assets/images/favicon.png"
+    },
+    "plugins": [
+      "expo-router",
+      [
+        "expo-splash-screen",
+        {
+          "image": "./src/assets/images/splash-icon.png",
+          "imageWidth": 200,
+          "resizeMode": "contain",
+          "backgroundColor": "#ffffff",
+          "dark": {
+            "backgroundColor": "#000000"
+          }
+        }
+      ],
+      "expo-secure-store"
+    ],
+    "experiments": {
+      "typedRoutes": true,
+      "reactCompiler": true
+    },
+    "extra": {
+      "router": {},
+      "eas": {
+        "projectId": "f40c21f5-38e6-40d8-8627-528c1d3a533a"
+      }
+    }
+  }
+}

apps/mobile/app/(app)/(with-organizations)/(tabs)/_layout.tsx

@@ -0,0 +1,58 @@
+import { Tabs } from 'expo-router';
+import React from 'react';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+import { HapticTab } from '@/modules/ui/components/haptic-tab';
+import { Icon } from '@/modules/ui/components/icon';
+import { ImportTabButton } from '@/modules/ui/components/import-tab-button';
+import { useThemeColor } from '@/modules/ui/providers/use-theme-color';
+
+export default function TabLayout() {
+  const colors = useThemeColor();
+  const insets = useSafeAreaInsets();
+
+  return (
+    <Tabs
+      screenOptions={{
+        tabBarActiveTintColor: colors.primary,
+        headerShown: false,
+        tabBarButton: HapticTab,
+        tabBarStyle: {
+          backgroundColor: colors.secondaryBackground,
+          borderTopColor: colors.border,
+          paddingTop: 15,
+          paddingBottom: insets.bottom,
+          height: 65 + insets.bottom,
+        },
+      }}
+    >
+      <Tabs.Screen
+        name="list"
+        options={{
+          title: 'Documents',
+          tabBarIcon: ({ color }) => <Icon name="home" size={30} color={color} style={{ height: 30 }} />,
+          tabBarLabel: () => null,
+
+        }}
+      />
+      <Tabs.Screen
+        name="import"
+        options={{
+          title: 'Import',
+          tabBarButton: () => <ImportTabButton />,
+          tabBarLabel: () => null,
+
+        }}
+      />
+      <Tabs.Screen
+        name="settings"
+        options={{
+          title: 'Settings',
+          tabBarIcon: ({ color }) => <Icon name="settings" size={30} color={color} style={{ height: 30 }} />,
+          tabBarLabel: () => null,
+
+        }}
+      />
+    </Tabs>
+  );
+}

apps/mobile/app/(app)/(with-organizations)/(tabs)/import.tsx

@@ -0,0 +1,5 @@
+// This is a dummy screen that will never be rendered
+// The import tab button intercepts the press and opens a drawer instead
+export default function ImportScreen() {
+  return null;
+}

apps/mobile/app/(app)/(with-organizations)/(tabs)/list.tsx

@@ -0,0 +1,3 @@
+import { DocumentsListScreen } from '@/modules/documents/screens/documents-list.screen';
+
+export default DocumentsListScreen;

apps/mobile/app/(app)/(with-organizations)/(tabs)/settings.tsx

@@ -0,0 +1,3 @@
+import SettingsScreen from '@/modules/users/screens/settings.screen';
+
+export default SettingsScreen;

apps/mobile/app/(app)/(with-organizations)/_layout.tsx

@@ -0,0 +1,13 @@
+import { Stack } from 'expo-router';
+import { OrganizationsProvider } from '@/modules/organizations/organizations.provider';
+
+export default function WithOrganizationsLayout() {
+  return (
+    <OrganizationsProvider>
+      <Stack>
+        <Stack.Screen name="organizations/create" options={{ headerShown: false }} />
+        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+      </Stack>
+    </OrganizationsProvider>
+  );
+}

apps/mobile/app/(app)/(with-organizations)/organizations/create.tsx

@@ -0,0 +1,3 @@
+import { OrganizationCreateScreen } from '@/modules/organizations/screens/organization-create.screen';
+
+export default OrganizationCreateScreen;

apps/mobile/app/(app)/_layout.tsx

@@ -0,0 +1,18 @@
+import { Stack } from 'expo-router';
+import { StatusBar } from 'expo-status-bar';
+
+import { ApiProvider } from '@/modules/api/providers/api.provider';
+import 'react-native-reanimated';
+
+export default function RootLayout() {
+  return (
+    <ApiProvider>
+      <Stack>
+        <Stack.Screen name="auth/login" options={{ headerShown: false }} />
+        <Stack.Screen name="auth/signup" options={{ headerShown: false }} />
+        <Stack.Screen name="(with-organizations)" options={{ headerShown: false }} />
+      </Stack>
+      <StatusBar style="auto" />
+    </ApiProvider>
+  );
+}

apps/mobile/app/(app)/auth/login.tsx

@@ -0,0 +1,3 @@
+import { LoginScreen } from '@/modules/auth/screens/login.screen';
+
+export default LoginScreen;

apps/mobile/app/(app)/auth/signup.tsx

@@ -0,0 +1,3 @@
+import { SignupScreen } from '@/modules/auth/screens/signup.screen';
+
+export default SignupScreen;

apps/mobile/app/+not-found.tsx

@@ -0,0 +1,45 @@
+import { Link, Stack } from 'expo-router';
+import { StyleSheet, Text, useColorScheme, View } from 'react-native';
+
+export default function NotFoundScreen() {
+  const colorScheme = useColorScheme();
+  const isDark = colorScheme === 'dark';
+
+  const styles = createStylesNotFound(isDark);
+  return (
+    <>
+      <Stack.Screen options={{ title: 'Oops!' }} />
+      <View style={styles.container}>
+        <Text style={styles.title}>This screen doesn&apos;t exist.</Text>
+        <Link href="/" style={styles.link}>
+          <Text style={styles.linkText}>Go to home screen</Text>
+        </Link>
+      </View>
+    </>
+  );
+}
+
+export function createStylesNotFound(isDark: boolean) {
+  return StyleSheet.create({
+    container: {
+      flex: 1,
+      alignItems: 'center',
+      justifyContent: 'center',
+      padding: 20,
+    },
+    title: {
+      fontSize: 20,
+      fontWeight: 'bold',
+      marginBottom: 20,
+      color: isDark ? '#fff' : '#000',
+    },
+    link: {
+      marginTop: 15,
+      paddingVertical: 15,
+    },
+    linkText: {
+      fontSize: 14,
+      color: '#007AFF',
+    },
+  });
+}

apps/mobile/app/_layout.tsx

@@ -0,0 +1,25 @@
+import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native';
+import { Stack } from 'expo-router';
+import { StatusBar } from 'expo-status-bar';
+import { AppProviders } from '@/modules/app/providers/app-providers';
+
+import { useColorScheme } from '@/modules/ui/providers/use-color-scheme';
+import 'react-native-reanimated';
+
+export default function RootLayout() {
+  const colorScheme = useColorScheme();
+
+  return (
+    <AppProviders>
+      <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
+        <Stack>
+          <Stack.Screen name="index" options={{ headerShown: false }} />
+          <Stack.Screen name="config/server-selection" options={{ headerShown: false }} />
+          <Stack.Screen name="(app)" options={{ headerShown: false }} />
+          <Stack.Screen name="modal" options={{ presentation: 'modal', title: 'Modal' }} />
+        </Stack>
+        <StatusBar style="auto" />
+      </ThemeProvider>
+    </AppProviders>
+  );
+}

apps/mobile/app/config/server-selection.tsx

@@ -0,0 +1,3 @@
+import { ServerSelectionScreen } from '@/modules/config/screens/server-selection.screen';
+
+export default ServerSelectionScreen;

apps/mobile/app/index.tsx

@@ -0,0 +1,28 @@
+import { useQuery } from '@tanstack/react-query';
+import { Redirect } from 'expo-router';
+import { configLocalStorage } from '@/modules/config/config.local-storage';
+
+export default function Index() {
+  const query = useQuery({
+    queryKey: ['api-server-url'],
+    queryFn: configLocalStorage.getApiServerBaseUrl,
+  });
+
+  const getRedirection = () => {
+    if (query.isLoading) {
+      return null;
+    }
+
+    if (query.isError || query.data == null) {
+      return <Redirect href="/config/server-selection" />;
+    }
+
+    return <Redirect href="/auth/login" />;
+  };
+
+  return (
+    <>
+      {getRedirection()}
+    </>
+  );
+}

apps/mobile/app/modal.tsx

@@ -0,0 +1,29 @@
+import { Link } from 'expo-router';
+import { StyleSheet } from 'react-native';
+
+import { ThemedText } from '@/modules/ui/components/themed-text';
+import { ThemedView } from '@/modules/ui/components/themed-view';
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 20,
+  },
+  link: {
+    marginTop: 15,
+    paddingVertical: 15,
+  },
+});
+
+export default function ModalScreen() {
+  return (
+    <ThemedView style={styles.container}>
+      <ThemedText type="title">This is a modal</ThemedText>
+      <Link href="/" dismissTo style={styles.link}>
+        <ThemedText type="link">Go to home screen</ThemedText>
+      </Link>
+    </ThemedView>
+  );
+}

apps/mobile/eas.json

@@ -0,0 +1,21 @@
+{
+  "cli": {
+    "version": ">= 16.27.0",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal"
+    },
+    "production": {
+      "autoIncrement": true
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

apps/mobile/eslint.config.js

@@ -0,0 +1,29 @@
+import antfu from '@antfu/eslint-config';
+
+export default antfu({
+  typescript: {
+    tsconfigPath: './tsconfig.json',
+    overridesTypeAware: {
+      'ts/no-misused-promises': ['error', { checksVoidReturn: false }],
+      'ts/strict-boolean-expressions': ['error', { allowNullableObject: true }],
+    },
+
+  },
+  stylistic: {
+    semi: true,
+  },
+
+  rules: {
+    // To allow export on top of files
+    'ts/no-use-before-define': ['error', { allowNamedExports: true, functions: false }],
+    'curly': ['error', 'all'],
+    'vitest/consistent-test-it': ['error', { fn: 'test' }],
+    'ts/consistent-type-definitions': ['error', 'type'],
+    'style/brace-style': ['error', '1tbs', { allowSingleLine: false }],
+    'unused-imports/no-unused-vars': ['error', {
+      argsIgnorePattern: '^_',
+      varsIgnorePattern: '^_',
+      caughtErrorsIgnorePattern: '^_',
+    }],
+  },
+});

apps/mobile/metro.config.js

@@ -0,0 +1,8 @@
+const { getDefaultConfig } = require('expo/metro-config');
+
+const config = getDefaultConfig(__dirname);
+
+// Enable package exports for Better Auth
+config.resolver.unstable_enablePackageExports = true;
+
+module.exports = config;

apps/mobile/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "mobile",
+  "version": "1.0.0",
+  "private": true,
+  "main": "expo-router/entry",
+  "scripts": {
+    "dev": "pnpm start",
+    "start": "expo start",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  },
+  "dependencies": {
+    "@better-auth/expo": "catalog:",
+    "@corentinth/chisels": "catalog:",
+    "@expo/vector-icons": "^15.0.3",
+    "@react-native-async-storage/async-storage": "^2.2.0",
+    "@react-navigation/bottom-tabs": "^7.4.0",
+    "@react-navigation/elements": "^2.6.3",
+    "@react-navigation/native": "^7.1.8",
+    "@tanstack/react-form": "^1.23.8",
+    "@tanstack/react-query": "^5.90.7",
+    "better-auth": "catalog:",
+    "expo": "~54.0.22",
+    "expo-constants": "~18.0.10",
+    "expo-document-picker": "^14.0.7",
+    "expo-file-system": "^19.0.19",
+    "expo-font": "~14.0.9",
+    "expo-haptics": "~15.0.7",
+    "expo-image": "~3.0.10",
+    "expo-linking": "~8.0.8",
+    "expo-router": "~6.0.14",
+    "expo-secure-store": "^15.0.7",
+    "expo-splash-screen": "~31.0.10",
+    "expo-status-bar": "~3.0.8",
+    "expo-symbols": "~1.0.7",
+    "expo-system-ui": "~6.0.8",
+    "expo-web-browser": "~15.0.9",
+    "ofetch": "^1.4.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-reanimated": "~4.1.1",
+    "react-native-safe-area-context": "~5.6.0",
+    "react-native-screens": "~4.16.0",
+    "react-native-web": "~0.21.0",
+    "react-native-worklets": "0.5.1",
+    "valibot": "1.0.0-beta.10"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "catalog:",
+    "@types/react": "~19.1.0",
+    "eas-cli": "^16.27.0",
+    "eslint": "catalog:",
+    "eslint-config-expo": "~10.0.0",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}

apps/mobile/src/modules/api/api.client.ts

@@ -0,0 +1,30 @@
+import type { HttpClientOptions, ResponseType } from './http.client';
+import { Platform } from 'react-native';
+import { httpClient } from './http.client';
+
+export type ApiClient = ReturnType<typeof createApiClient>;
+
+export function createApiClient({
+  baseUrl,
+  getAuthCookie,
+}: {
+  baseUrl: string;
+  getAuthCookie: () => string;
+}) {
+  return async <T, R extends ResponseType = 'json'>({ path, ...rest}: { path: string } & Omit<HttpClientOptions<R>, 'url'>) => {
+    return httpClient<T, R>({
+      baseUrl,
+      url: path,
+      credentials: Platform.OS === 'web' ? 'include' : 'omit',
+      headers: {
+        ...(Platform.OS === 'web'
+          ? {}
+          : {
+              Cookie: getAuthCookie(),
+            }),
+        ...rest.headers,
+      },
+      ...rest,
+    });
+  };
+}

apps/mobile/src/modules/api/api.models.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'vitest';
+import { coerceDate } from './api.models';
+
+describe('api models', () => {
+  describe('coerceDate', () => {
+    test('transforms date-ish values into Date instances', () => {
+      expect(coerceDate(new Date('2024-01-01T00:00:00Z'))).toEqual(new Date('2024-01-01T00:00:00Z'));
+      expect(coerceDate('2024-01-01T00:00:00Z')).toEqual(new Date('2024-01-01T00:00:00Z'));
+      expect(coerceDate('2024-01-01')).toEqual(new Date('2024-01-01T00:00:00Z'));
+      expect(coerceDate(1704067200000)).toEqual(new Date('2024-01-01T00:00:00Z'));
+
+      expect(() => coerceDate(null)).toThrow('Invalid date: expected Date, string, or number, but received value "null" of type "object"');
+      expect(() => coerceDate(undefined)).toThrow('Invalid date: expected Date, string, or number, but received value "undefined" of type "undefined"');
+      expect(() => coerceDate({})).toThrow('Invalid date: expected Date, string, or number, but received value "[object Object]" of type "object"');
+      expect(() => coerceDate(['foo'])).toThrow('Invalid date: expected Date, string, or number, but received value "foo" of type "object"');
+      expect(() => coerceDate(true)).toThrow('Invalid date: expected Date, string, or number, but received value "true" of type "boolean"');
+    });
+  });
+});

apps/mobile/src/modules/api/api.models.ts

@@ -0,0 +1,43 @@
+type DateKeys = 'createdAt' | 'updatedAt' | 'deletedAt' | 'expiresAt' | 'lastTriggeredAt' | 'lastUsedAt' | 'scheduledPurgeAt';
+
+type CoerceDate<T> = T extends string | Date
+  ? Date
+  : T extends string | Date | null | undefined
+    ? Date | undefined
+    : T;
+
+type CoerceDates<T> = {
+  [K in keyof T]: K extends DateKeys ? CoerceDate<T[K]> : T[K];
+};
+
+export function coerceDate(date: unknown): Date {
+  if (date instanceof Date) {
+    return date;
+  }
+
+  if (typeof date === 'string' || typeof date === 'number') {
+    return new Date(date);
+  }
+
+  throw new Error(`Invalid date: expected Date, string, or number, but received value "${String(date)}" of type "${typeof date}"`);
+}
+
+export function coerceDateOrUndefined(date: unknown): Date | undefined {
+  if (date == null) {
+    return undefined;
+  }
+  return coerceDate(date);
+}
+
+export function coerceDates<T extends Record<string, unknown>>(obj: T): CoerceDates<T> {
+  return {
+    ...obj,
+    ...('createdAt' in obj ? { createdAt: coerceDateOrUndefined(obj.createdAt) } : {}),
+    ...('updatedAt' in obj ? { updatedAt: coerceDateOrUndefined(obj.updatedAt) } : {}),
+    ...('deletedAt' in obj ? { deletedAt: coerceDateOrUndefined(obj.deletedAt) } : {}),
+    ...('expiresAt' in obj ? { expiresAt: coerceDateOrUndefined(obj.expiresAt) } : {}),
+    ...('lastTriggeredAt' in obj ? { lastTriggeredAt: coerceDateOrUndefined(obj.lastTriggeredAt) } : {}),
+    ...('lastUsedAt' in obj ? { lastUsedAt: coerceDateOrUndefined(obj.lastUsedAt) } : {}),
+    ...('scheduledPurgeAt' in obj ? { scheduledPurgeAt: coerceDateOrUndefined(obj.scheduledPurgeAt) } : {}),
+  } as CoerceDates<T>;
+}

apps/mobile/src/modules/api/http.client.ts

@@ -0,0 +1,12 @@
+import type { FetchOptions, ResponseType } from 'ofetch';
+import { ofetch } from 'ofetch';
+
+export { ResponseType };
+export type HttpClientOptions<R extends ResponseType = 'json'> = Omit<FetchOptions<R>, 'baseURL'> & { url: string; baseUrl?: string };
+
+export async function httpClient<A, R extends ResponseType = 'json'>({ url, baseUrl, ...rest }: HttpClientOptions<R>) {
+  return ofetch<A, R>(url, {
+    baseURL: baseUrl,
+    ...rest,
+  });
+}

apps/mobile/src/modules/api/providers/api.provider.tsx

@@ -0,0 +1,69 @@
+import type { ReactNode } from 'react';
+import type { ApiClient } from '@/modules/api/api.client';
+import type { AuthClient } from '@/modules/auth/auth.client';
+import { useQuery } from '@tanstack/react-query';
+import { createContext, useContext, useEffect, useState } from 'react';
+import { createApiClient } from '@/modules/api/api.client';
+import { createAuthClient } from '@/modules/auth/auth.client';
+import { configLocalStorage } from '@/modules/config/config.local-storage';
+
+type ApiProviderProps = {
+  children: ReactNode;
+};
+
+const AuthClientContext = createContext<AuthClient | undefined>(undefined);
+const ApiClientContext = createContext<ApiClient | undefined>(undefined);
+
+export function ApiProvider({ children }: ApiProviderProps) {
+  const [authClient, setAuthClient] = useState<AuthClient | undefined>(undefined);
+  const [apiClient, setApiClient] = useState<ApiClient | undefined>(undefined);
+
+  const { data: baseUrl } = useQuery({
+    queryKey: ['api-server-url'],
+    queryFn: configLocalStorage.getApiServerBaseUrl,
+  });
+
+  useEffect(() => {
+    if (baseUrl == null) {
+      return;
+    }
+
+    const authClient = createAuthClient({ baseUrl });
+    setAuthClient(() => authClient);
+
+    const apiClient = createApiClient({ baseUrl, getAuthCookie: () => authClient.getCookie() });
+    setApiClient(() => apiClient);
+  }, [baseUrl]);
+
+  return (
+    <>
+      { authClient && apiClient && (
+        <AuthClientContext.Provider value={authClient}>
+          <ApiClientContext.Provider value={apiClient}>
+            {children}
+          </ApiClientContext.Provider>
+        </AuthClientContext.Provider>
+      )}
+    </>
+  );
+}
+
+export function useAuthClient(): AuthClient {
+  const context = useContext(AuthClientContext);
+
+  if (!context) {
+    throw new Error('useAuthClient must be used within ApiProvider');
+  }
+
+  return context;
+}
+
+export function useApiClient(): ApiClient {
+  const context = useContext(ApiClientContext);
+
+  if (!context) {
+    throw new Error('useApiClient must be used within ApiProvider');
+  }
+
+  return context;
+}

apps/mobile/src/modules/api/providers/query.provider.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 2,
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 10, // 10 minutes
+    },
+  },
+});
+
+type QueryProviderProps = {
+  children: ReactNode;
+};
+
+export function QueryProvider({ children }: QueryProviderProps) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}

apps/mobile/src/modules/app/providers/app-providers.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import { QueryProvider } from '../../api/providers/query.provider';
+import { AlertProvider } from '../../ui/providers/alert-provider';
+
+type AppProvidersProps = {
+  children: ReactNode;
+};
+
+export function AppProviders({ children }: AppProvidersProps) {
+  return (
+    <QueryProvider>
+      <AlertProvider>
+        {children}
+      </AlertProvider>
+    </QueryProvider>
+  );
+}

apps/mobile/src/modules/auth/auth.client.ts

@@ -0,0 +1,22 @@
+import { expoClient } from '@better-auth/expo/client';
+import { createAuthClient as createBetterAuthClient } from 'better-auth/react';
+import Constants from 'expo-constants';
+import * as SecureStore from 'expo-secure-store';
+import { Platform } from 'react-native';
+
+export type AuthClient = ReturnType<typeof createAuthClient>;
+
+export function createAuthClient({ baseUrl}: { baseUrl: string }) {
+  return createBetterAuthClient({
+    baseURL: baseUrl,
+    plugins: [
+      expoClient({
+        scheme: String(Constants.expoConfig?.scheme ?? 'papra'),
+        storagePrefix: String(Constants.expoConfig?.scheme ?? 'papra'),
+        storage: Platform.OS === 'web'
+          ? localStorage
+          : SecureStore,
+      }),
+    ],
+  });
+}

apps/mobile/src/modules/auth/components/back-to-server-selection.tsx

@@ -0,0 +1,44 @@
+import type { ThemeColors } from '@/modules/ui/theme.constants';
+import { router } from 'expo-router';
+import { StyleSheet, Text, TouchableOpacity } from 'react-native';
+import { Icon } from '@/modules/ui/components/icon';
+import { useThemeColor } from '@/modules/ui/providers/use-theme-color';
+
+export function BackToServerSelectionButton() {
+  const themeColors = useThemeColor();
+  const styles = createStyles({ themeColors });
+
+  return (
+    <TouchableOpacity
+      style={styles.backToServerButton}
+      onPress={() => router.push('/config/server-selection')}
+    >
+      <Icon name="arrow-left" size={20} color={themeColors.mutedForeground} />
+      <Text style={styles.backToServerText}>
+        Select server
+      </Text>
+    </TouchableOpacity>
+  );
+}
+
+function createStyles({ themeColors }: { themeColors: ThemeColors }) {
+  return StyleSheet.create({
+    backToServerButton: {
+      marginBottom: 16,
+      alignSelf: 'flex-start',
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: 6,
+      backgroundColor: themeColors.secondaryBackground,
+      borderRadius: 8,
+      paddingVertical: 10,
+      paddingHorizontal: 14,
+      borderWidth: 1,
+      borderColor: themeColors.border,
+    },
+    backToServerText: {
+      color: themeColors.mutedForeground,
+      fontSize: 16,
+    },
+  });
+}

apps/mobile/src/modules/auth/screens/login.screen.tsx

@@ -0,0 +1,346 @@
+import type { ThemeColors } from '@/modules/ui/theme.constants';
+import { useForm } from '@tanstack/react-form';
+import { useRouter } from 'expo-router';
+import { useState } from 'react';
+import {
+  ActivityIndicator,
+  KeyboardAvoidingView,
+  Platform,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import * as v from 'valibot';
+import { useAuthClient } from '@/modules/api/providers/api.provider';
+import { useAlert } from '@/modules/ui/providers/alert-provider';
+import { useThemeColor } from '@/modules/ui/providers/use-theme-color';
+import { useServerConfig } from '../../config/hooks/use-server-config';
+import { BackToServerSelectionButton } from '../components/back-to-server-selection';
+
+const loginSchema = v.object({
+  email: v.pipe(v.string(), v.email('Please enter a valid email')),
+  password: v.pipe(v.string(), v.minLength(8, 'Password must be at least 8 characters')),
+});
+
+export function LoginScreen() {
+  const router = useRouter();
+  const themeColors = useThemeColor();
+  const authClient = useAuthClient();
+  const { showAlert } = useAlert();
+  const insets = useSafeAreaInsets();
+
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const { data: serverConfig, isLoading: isLoadingConfig } = useServerConfig();
+
+  const form = useForm({
+    defaultValues: {
+      email: '',
+      password: '',
+    },
+    validators: {
+      onChange: loginSchema,
+    },
+
+    onSubmit: async ({ value }) => {
+      setIsSubmitting(true);
+      try {
+        const response = await authClient.signIn.email({ email: value.email, password: value.password, rememberMe: true });
+
+        if (response.error) {
+          throw new Error(response.error.message);
+        }
+
+        router.replace('/(app)/(with-organizations)/(tabs)/list');
+      } catch (error) {
+        showAlert({
+          title: 'Login Failed',
+          message: error instanceof Error ? error.message : 'An error occurred',
+        });
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+  });
+
+  const handleSocialSignIn = async (provider: string) => {
+    try {
+      const response = await authClient.signIn.social({ provider, callbackURL: '/' });
+      if (response.error) {
+        throw Object.assign(new Error(response.error.message), response.error);
+      }
+    } catch (error) {
+      showAlert({
+        title: 'Sign In Failed',
+        message: error instanceof Error ? error.message : 'An error occurred',
+      });
+    }
+  };
+
+  const authConfig = serverConfig?.config?.auth;
+  const isEmailEnabled = authConfig?.providers?.email?.isEnabled ?? false;
+  const isGoogleEnabled = authConfig?.providers?.google?.isEnabled ?? false;
+  const isGithubEnabled = authConfig?.providers?.github?.isEnabled ?? false;
+  const customProviders = authConfig?.providers?.customs ?? [];
+
+  const styles = createStyles({ themeColors });
+
+  if (isLoadingConfig) {
+    return (
+      <View style={[styles.container, styles.centerContent]}>
+        <ActivityIndicator size="large" color={themeColors.primary} />
+      </View>
+    );
+  }
+
+  return (
+    <KeyboardAvoidingView
+      style={{ ...styles.container, paddingTop: insets.top }}
+      behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+    >
+      <ScrollView
+        contentContainerStyle={styles.scrollContent}
+        keyboardShouldPersistTaps="handled"
+      >
+        <BackToServerSelectionButton />
+
+        <View style={styles.header}>
+          <Text style={styles.title}>Welcome Back</Text>
+          <Text style={styles.subtitle}>Sign in to your account</Text>
+        </View>
+
+        {isEmailEnabled && (
+          <View style={styles.formContainer}>
+            <form.Field name="email">
+              {field => (
+                <View style={styles.fieldContainer}>
+                  <Text style={styles.label}>Email</Text>
+                  <TextInput
+                    style={styles.input}
+                    placeholder="you@example.com"
+                    placeholderTextColor={themeColors.mutedForeground}
+                    value={field.state.value}
+                    onChangeText={field.handleChange}
+                    onBlur={field.handleBlur}
+                    autoCapitalize="none"
+                    autoCorrect={false}
+                    keyboardType="email-address"
+                    editable={!isSubmitting}
+                  />
+                </View>
+              )}
+            </form.Field>
+
+            <form.Field name="password">
+              {field => (
+                <View style={styles.fieldContainer}>
+                  <Text style={styles.label}>Password</Text>
+                  <TextInput
+                    style={styles.input}
+                    placeholder="Enter your password"
+                    placeholderTextColor={themeColors.mutedForeground}
+                    value={field.state.value}
+                    onChangeText={field.handleChange}
+                    onBlur={field.handleBlur}
+                    secureTextEntry
+                    editable={!isSubmitting}
+                  />
+                </View>
+              )}
+            </form.Field>
+
+            <TouchableOpacity
+              style={[styles.button, isSubmitting && styles.buttonDisabled]}
+              onPress={async () => form.handleSubmit()}
+              disabled={isSubmitting}
+            >
+              {isSubmitting
+                ? (
+                    <ActivityIndicator color="#fff" />
+                  )
+                : (
+                    <Text style={styles.buttonText}>Sign In</Text>
+                  )}
+            </TouchableOpacity>
+          </View>
+        )}
+
+        {(isGoogleEnabled || isGithubEnabled || customProviders.length > 0) && (
+          <>
+            {isEmailEnabled && (
+              <View style={styles.divider}>
+                <View style={styles.dividerLine} />
+                <Text style={styles.dividerText}>OR</Text>
+                <View style={styles.dividerLine} />
+              </View>
+            )}
+
+            <View style={styles.socialButtons}>
+              {isGoogleEnabled && (
+                <TouchableOpacity
+                  style={styles.socialButton}
+                  onPress={async () => handleSocialSignIn('google')}
+                >
+                  <Text style={styles.socialButtonText}>Continue with Google</Text>
+                </TouchableOpacity>
+              )}
+
+              {isGithubEnabled && (
+                <TouchableOpacity
+                  style={styles.socialButton}
+                  onPress={async () => handleSocialSignIn('github')}
+                >
+                  <Text style={styles.socialButtonText}>Continue with GitHub</Text>
+                </TouchableOpacity>
+              )}
+
+              {customProviders.map(provider => (
+                <TouchableOpacity
+                  key={provider.providerId}
+                  style={styles.socialButton}
+                  onPress={async () => handleSocialSignIn(provider.providerId)}
+                >
+                  <Text style={styles.socialButtonText}>
+                    Continue with
+                    {' '}
+                    {provider.providerName}
+                  </Text>
+                </TouchableOpacity>
+              ))}
+            </View>
+          </>
+        )}
+
+        {authConfig?.isRegistrationEnabled === true && (
+          <TouchableOpacity
+            style={styles.linkButton}
+            onPress={() => router.push('/auth/signup')}
+          >
+            <Text style={styles.linkText}>
+              Don&apos;t have an account? Sign up
+            </Text>
+          </TouchableOpacity>
+        )}
+      </ScrollView>
+    </KeyboardAvoidingView>
+  );
+}
+
+function createStyles({ themeColors }: { themeColors: ThemeColors }) {
+  return StyleSheet.create({
+    container: {
+      flex: 1,
+      backgroundColor: themeColors.background,
+    },
+    centerContent: {
+      justifyContent: 'center',
+      alignItems: 'center',
+    },
+    scrollContent: {
+      flexGrow: 1,
+      padding: 24,
+    },
+    header: {
+      marginBottom: 48,
+      marginTop: 16,
+    },
+    title: {
+      fontSize: 32,
+      fontWeight: 'bold',
+      color: themeColors.foreground,
+      marginBottom: 8,
+    },
+    subtitle: {
+      fontSize: 16,
+      color: themeColors.mutedForeground,
+    },
+    formContainer: {
+      gap: 16,
+    },
+    fieldContainer: {
+      gap: 8,
+    },
+    label: {
+      fontSize: 14,
+      fontWeight: '600',
+      color: themeColors.foreground,
+    },
+    input: {
+      height: 50,
+      borderWidth: 1,
+      borderColor: themeColors.border,
+      borderRadius: 8,
+      paddingHorizontal: 16,
+      fontSize: 16,
+      color: themeColors.foreground,
+      backgroundColor: themeColors.secondaryBackground,
+    },
+    button: {
+      height: 50,
+      backgroundColor: themeColors.primary,
+      borderRadius: 8,
+      justifyContent: 'center',
+      alignItems: 'center',
+      marginTop: 8,
+    },
+    buttonDisabled: {
+      opacity: 0.5,
+    },
+    buttonText: {
+      color: themeColors.primaryForeground,
+      fontSize: 16,
+      fontWeight: '600',
+    },
+    divider: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      marginVertical: 24,
+    },
+    dividerLine: {
+      flex: 1,
+      height: 1,
+      backgroundColor: themeColors.border,
+    },
+    dividerText: {
+      marginHorizontal: 16,
+      color: themeColors.mutedForeground,
+      fontSize: 14,
+    },
+    socialButtons: {
+      gap: 12,
+    },
+    socialButton: {
+      height: 50,
+      borderWidth: 1,
+      borderColor: themeColors.border,
+      borderRadius: 8,
+      justifyContent: 'center',
+      alignItems: 'center',
+      backgroundColor: themeColors.secondaryBackground,
+    },
+    socialButtonText: {
+      color: themeColors.foreground,
+      fontSize: 16,
+      fontWeight: '500',
+    },
+    linkButton: {
+      marginTop: 24,
+      alignItems: 'center',
+    },
+    linkText: {
+      color: themeColors.primary,
+      fontSize: 14,
+    },
+    backToServerButton: {
+      marginBottom: 16,
+      alignSelf: 'flex-start',
+    },
+    backToServerText: {
+      color: themeColors.primary,
+      fontSize: 14,
+    },
+  });
+}

apps/mobile/src/modules/auth/screens/signup.screen.tsx

@@ -0,0 +1,293 @@
+import type { ThemeColors } from '@/modules/ui/theme.constants';
+import { useForm } from '@tanstack/react-form';
+import { useRouter } from 'expo-router';
+import { useState } from 'react';
+import {
+  ActivityIndicator,
+  KeyboardAvoidingView,
+  Platform,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import * as v from 'valibot';
+import { useAuthClient } from '@/modules/api/providers/api.provider';
+import { useAlert } from '@/modules/ui/providers/alert-provider';
+import { useThemeColor } from '@/modules/ui/providers/use-theme-color';
+import { useServerConfig } from '../../config/hooks/use-server-config';
+import { BackToServerSelectionButton } from '../components/back-to-server-selection';
+
+const signupSchema = v.object({
+  name: v.pipe(v.string(), v.minLength(1, 'Name is required')),
+  email: v.pipe(v.string(), v.email('Please enter a valid email')),
+  password: v.pipe(v.string(), v.minLength(8, 'Password must be at least 8 characters')),
+});
+
+export function SignupScreen() {
+  const router = useRouter();
+  const themeColors = useThemeColor();
+  const authClient = useAuthClient();
+  const { showAlert } = useAlert();
+  const insets = useSafeAreaInsets();
+
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const { data: serverConfig, isLoading: isLoadingConfig } = useServerConfig();
+
+  const form = useForm({
+    defaultValues: {
+      name: '',
+      email: '',
+      password: '',
+    },
+    validators: {
+      onChange: signupSchema,
+    },
+    onSubmit: async ({ value }) => {
+      setIsSubmitting(true);
+      try {
+        const { name, email, password } = value;
+
+        await authClient.signUp.email({ name, email, password });
+
+        const isEmailVerificationRequired = serverConfig?.config?.auth?.isEmailVerificationRequired ?? false;
+
+        if (isEmailVerificationRequired) {
+          showAlert({
+            title: 'Check your email',
+            message: 'We sent you a verification link. Please check your email to verify your account.',
+            buttons: [{ text: 'OK', onPress: () => router.replace('/auth/login') }],
+          });
+        } else {
+          router.replace('/(app)/(with-organizations)/(tabs)/list');
+        }
+      } catch (error) {
+        showAlert({
+          title: 'Signup Failed',
+          message: error instanceof Error ? error.message : 'An error occurred',
+        });
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+  });
+
+  const authConfig = serverConfig?.config?.auth;
+  const isRegistrationEnabled = authConfig?.isRegistrationEnabled ?? false;
+
+  const styles = createStyles({ themeColors });
+
+  if (isLoadingConfig) {
+    return (
+      <View style={[styles.container, styles.centerContent]}>
+        <ActivityIndicator size="large" color={themeColors.primary} />
+      </View>
+    );
+  }
+
+  if (!isRegistrationEnabled) {
+    return (
+      <View style={[styles.container, styles.centerContent]}>
+        <Text style={styles.errorText}>Registration is currently disabled</Text>
+        <TouchableOpacity
+          style={styles.linkButton}
+          onPress={() => router.back()}
+        >
+          <Text style={styles.linkText}>Go back to login</Text>
+        </TouchableOpacity>
+      </View>
+    );
+  }
+
+  return (
+    <KeyboardAvoidingView
+      style={{ ...styles.container, paddingTop: insets.top }}
+      behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+    >
+      <ScrollView
+        contentContainerStyle={styles.scrollContent}
+        keyboardShouldPersistTaps="handled"
+      >
+        <BackToServerSelectionButton />
+
+        <View style={styles.header}>
+          <Text style={styles.title}>Create Account</Text>
+          <Text style={styles.subtitle}>Sign up to get started</Text>
+        </View>
+
+        <View style={styles.formContainer}>
+          <form.Field name="name">
+            {field => (
+              <View style={styles.fieldContainer}>
+                <Text style={styles.label}>Name</Text>
+                <TextInput
+                  style={styles.input}
+                  placeholder="Your name"
+                  placeholderTextColor={themeColors.mutedForeground}
+                  value={field.state.value}
+                  onChangeText={field.handleChange}
+                  onBlur={field.handleBlur}
+                  autoCapitalize="words"
+                  editable={!isSubmitting}
+                />
+              </View>
+            )}
+          </form.Field>
+
+          <form.Field name="email">
+            {field => (
+              <View style={styles.fieldContainer}>
+                <Text style={styles.label}>Email</Text>
+                <TextInput
+                  style={styles.input}
+                  placeholder="you@example.com"
+                  placeholderTextColor={themeColors.mutedForeground}
+                  value={field.state.value}
+                  onChangeText={field.handleChange}
+                  onBlur={field.handleBlur}
+                  autoCapitalize="none"
+                  autoCorrect={false}
+                  keyboardType="email-address"
+                  editable={!isSubmitting}
+                />
+              </View>
+            )}
+          </form.Field>
+
+          <form.Field name="password">
+            {field => (
+              <View style={styles.fieldContainer}>
+                <Text style={styles.label}>Password</Text>
+                <TextInput
+                  style={styles.input}
+                  placeholder="At least 8 characters"
+                  placeholderTextColor={themeColors.mutedForeground}
+                  value={field.state.value}
+                  onChangeText={field.handleChange}
+                  onBlur={field.handleBlur}
+                  secureTextEntry
+                  editable={!isSubmitting}
+                />
+              </View>
+            )}
+          </form.Field>
+
+          <TouchableOpacity
+            style={[styles.button, isSubmitting && styles.buttonDisabled]}
+            onPress={async () => form.handleSubmit()}
+            disabled={isSubmitting}
+          >
+            {isSubmitting
+              ? (
+                  <ActivityIndicator color="#fff" />
+                )
+              : (
+                  <Text style={styles.buttonText}>Sign Up</Text>
+                )}
+          </TouchableOpacity>
+        </View>
+
+        <TouchableOpacity
+          style={styles.linkButton}
+          onPress={() => router.back()}
+        >
+          <Text style={styles.linkText}>Already have an account? Sign in</Text>
+        </TouchableOpacity>
+      </ScrollView>
+    </KeyboardAvoidingView>
+  );
+}
+
+function createStyles({ themeColors }: { themeColors: ThemeColors }) {
+  return StyleSheet.create({
+    container: {
+      flex: 1,
+      backgroundColor: themeColors.background,
+    },
+    centerContent: {
+      justifyContent: 'center',
+      alignItems: 'center',
+      padding: 24,
+    },
+    scrollContent: {
+      flexGrow: 1,
+      padding: 24,
+    },
+    header: {
+      marginBottom: 48,
+      marginTop: 16,
+    },
+    title: {
+      fontSize: 32,
+      fontWeight: 'bold',
+      color: themeColors.foreground,
+      marginBottom: 8,
+    },
+    subtitle: {
+      fontSize: 16,
+      color: themeColors.mutedForeground,
+    },
+    formContainer: {
+      gap: 16,
+    },
+    fieldContainer: {
+      gap: 8,
+    },
+    label: {
+      fontSize: 14,
+      fontWeight: '600',
+      color: themeColors.foreground,
+    },
+    input: {
+      height: 50,
+      borderWidth: 1,
+      borderColor: themeColors.border,
+      borderRadius: 8,
+      paddingHorizontal: 16,
+      fontSize: 16,
+      color: themeColors.foreground,
+      backgroundColor: themeColors.secondaryBackground,
+    },
+    button: {
+      height: 50,
+      backgroundColor: themeColors.primary,
+      borderRadius: 8,
+      justifyContent: 'center',
+      alignItems: 'center',
+      marginTop: 8,
+    },
+    buttonDisabled: {
+      opacity: 0.5,
+    },
+    buttonText: {
+      color: themeColors.primaryForeground,
+      fontSize: 16,
+      fontWeight: '600',
+    },
+    linkButton: {
+      marginTop: 24,
+      alignItems: 'center',
+    },
+    linkText: {
+      color: themeColors.primary,
+      fontSize: 14,
+    },
+    errorText: {
+      fontSize: 16,
+      color: themeColors.primary,
+      marginBottom: 16,
+      textAlign: 'center',
+    },
+    backToServerButton: {
+      marginBottom: 16,
+      alignSelf: 'flex-start',
+    },
+    backToServerText: {
+      color: themeColors.primary,
+      fontSize: 14,
+    },
+  });
+}

apps/mobile/src/modules/config/config.constants.ts

@@ -0,0 +1 @@
+export const MANAGED_SERVER_URL = 'https://api.papra.app';

apps/mobile/src/modules/config/config.local-storage.ts

@@ -0,0 +1,9 @@
+import { buildStorageKey } from '../lib/local-storage/local-storage.models';
+import { storage } from '../lib/local-storage/local-storage.services';
+
+const CONFIG_API_SERVER_URL_KEY = buildStorageKey(['config', 'api-server-url']);
+
+export const configLocalStorage = {
+  getApiServerBaseUrl: async () => storage.getItem(CONFIG_API_SERVER_URL_KEY),
+  setApiServerBaseUrl: async ({ apiServerBaseUrl}: { apiServerBaseUrl: string }) => storage.setItem(CONFIG_API_SERVER_URL_KEY, apiServerBaseUrl),
+};

apps/mobile/src/modules/config/config.services.ts

@@ -0,0 +1,44 @@
+import type { ApiClient } from '../api/api.client';
+import { httpClient } from '../api/http.client';
+
+export async function fetchServerConfig({ apiClient}: { apiClient: ApiClient }) {
+  return apiClient<{
+    config: {
+      auth: {
+        isEmailVerificationRequired: boolean;
+        isPasswordResetEnabled: boolean;
+        isRegistrationEnabled: boolean;
+        showLegalLinksOnAuthPage: boolean;
+        providers: {
+          email: {
+            isEnabled: boolean;
+          };
+          github: {
+            isEnabled: boolean;
+          };
+          google: {
+            isEnabled: boolean;
+          };
+          customs: {
+            providerId: string;
+            providerName: string;
+          }[];
+        };
+      };
+    };
+  }>({
+    path: '/api/config',
+  });
+}
+
+export async function pingServer({ url}: { url: string }): Promise<true | never> {
+  const response = await httpClient<{ status: 'ok' | 'error' }>({ url: `/api/ping`, baseUrl: url })
+    .then(() => true)
+    .catch(() => false);
+
+  if (!response) {
+    throw new Error('Could not reach the server');
+  }
+
+  return true;
+}

apps/mobile/src/modules/config/hooks/use-server-config.ts

@@ -0,0 +1,12 @@
+import { useQuery } from '@tanstack/react-query';
+import { useApiClient } from '@/modules/api/providers/api.provider';
+import { fetchServerConfig } from '../config.services';
+
+export function useServerConfig() {
+  const apiClient = useApiClient();
+
+  return useQuery({
+    queryKey: ['server', 'config'],
+    queryFn: async () => fetchServerConfig({ apiClient }),
+  });
+}

apps/mobile/src/modules/config/screens/server-selection.screen.tsx

@@ -0,0 +1,238 @@
+import type { ThemeColors } from '@/modules/ui/theme.constants';
+import { useRouter } from 'expo-router';
+import { useState } from 'react';
+import {
+  ActivityIndicator,
+  KeyboardAvoidingView,
+  Platform,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { queryClient } from '@/modules/api/providers/query.provider';
+import { useAlert } from '@/modules/ui/providers/alert-provider';
+import { useThemeColor } from '@/modules/ui/providers/use-theme-color';
+import { MANAGED_SERVER_URL } from '../config.constants';
+import { configLocalStorage } from '../config.local-storage';
+import { pingServer } from '../config.services';
+
+function getDefaultCustomServerUrl() {
+  if (!__DEV__) {
+    return '';
+  }
+
+  // eslint-disable-next-line node/prefer-global/process
+  return process.env.EXPO_PUBLIC_API_URL ?? '';
+}
+
+export function ServerSelectionScreen() {
+  const router = useRouter();
+  const themeColors = useThemeColor();
+  const { showAlert } = useAlert();
+  const styles = createStyles({ themeColors });
+
+  const [selectedOption, setSelectedOption] = useState<'managed' | 'self-hosted'>('managed');
+  const [customUrl, setCustomUrl] = useState(getDefaultCustomServerUrl());
+  const [isValidating, setIsValidating] = useState(false);
+
+  const handleValidateCustomUrl = async ({ url}: { url: string }) => {
+    setIsValidating(true);
+    try {
+      await pingServer({ url });
+      await configLocalStorage.setApiServerBaseUrl({ apiServerBaseUrl: url });
+      await queryClient.invalidateQueries({ queryKey: ['api-server-url'] });
+
+      router.replace('/auth/login');
+    } catch {
+      showAlert({
+        title: 'Connection Failed',
+        message: 'Could not reach the server.',
+      });
+    } finally {
+      setIsValidating(false);
+    }
+  };
+
+  return (
+    <KeyboardAvoidingView
+      style={styles.container}
+      behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+    >
+      <ScrollView
+        contentContainerStyle={styles.scrollContent}
+        keyboardShouldPersistTaps="handled"
+      >
+        <View style={styles.header}>
+          <Text style={styles.title}>Welcome to Papra</Text>
+          <Text style={styles.subtitle}>Choose your server</Text>
+        </View>
+
+        <View style={styles.options}>
+          <TouchableOpacity
+            style={[
+              styles.optionCard,
+              selectedOption === 'managed' && styles.optionCardSelected,
+            ]}
+            onPress={() => setSelectedOption('managed')}
+            disabled={isValidating}
+          >
+            <Text style={styles.optionTitle}>Managed Cloud</Text>
+            <Text style={styles.optionDescription}>
+              Use the official Papra cloud service
+            </Text>
+          </TouchableOpacity>
+
+          <TouchableOpacity
+            style={[
+              styles.optionCard,
+              selectedOption === 'self-hosted' && styles.optionCardSelected,
+            ]}
+            onPress={() => setSelectedOption('self-hosted')}
+            disabled={isValidating}
+          >
+            <Text style={styles.optionTitle}>Self-Hosted</Text>
+            <Text style={styles.optionDescription}>
+              Connect to your own Papra server
+            </Text>
+          </TouchableOpacity>
+        </View>
+
+        {selectedOption === 'managed' && (
+          <TouchableOpacity
+            style={[styles.button, isValidating && styles.buttonDisabled]}
+            onPress={async () => handleValidateCustomUrl({ url: MANAGED_SERVER_URL })}
+            disabled={isValidating}
+          >
+            {isValidating
+              ? (
+                  <ActivityIndicator color="#fff" />
+                )
+              : (
+                  <Text style={styles.buttonText}>Continue with Managed</Text>
+                )}
+          </TouchableOpacity>
+        )}
+
+        {selectedOption === 'self-hosted' && (
+          <View style={styles.customUrlContainer}>
+            <Text style={styles.inputLabel}>Server URL</Text>
+            <TextInput
+              style={styles.input}
+              placeholder="https://your-server.com"
+              placeholderTextColor={themeColors.mutedForeground}
+              value={customUrl}
+              onChangeText={setCustomUrl}
+              autoCapitalize="none"
+              autoCorrect={false}
+              keyboardType="url"
+              editable={!isValidating}
+            />
+            <TouchableOpacity
+              style={[styles.button, isValidating && styles.buttonDisabled]}
+              onPress={async () => handleValidateCustomUrl({ url: customUrl })}
+              disabled={isValidating}
+            >
+              {isValidating
+                ? (
+                    <ActivityIndicator color="#fff" />
+                  )
+                : (
+                    <Text style={styles.buttonText}>Connect</Text>
+                  )}
+            </TouchableOpacity>
+          </View>
+        )}
+      </ScrollView>
+    </KeyboardAvoidingView>
+  );
+}
+
+function createStyles({ themeColors }: { themeColors: ThemeColors }) {
+  return StyleSheet.create({
+    container: {
+      flex: 1,
+      backgroundColor: themeColors.background,
+    },
+    scrollContent: {
+      flexGrow: 1,
+      padding: 24,
+      justifyContent: 'center',
+    },
+    header: {
+      marginBottom: 40,
+      alignItems: 'center',
+    },
+    title: {
+      fontSize: 32,
+      fontWeight: 'bold',
+      color: themeColors.foreground,
+      marginBottom: 8,
+    },
+    subtitle: {
+      fontSize: 16,
+      color: themeColors.mutedForeground,
+    },
+    options: {
+      gap: 16,
+      marginBottom: 24,
+    },
+    optionCard: {
+      paddingHorizontal: 20,
+      paddingVertical: 14,
+      borderRadius: 12,
+      borderWidth: 2,
+      borderColor: themeColors.border,
+      backgroundColor: themeColors.secondaryBackground,
+    },
+    optionCardSelected: {
+      borderColor: themeColors.primary,
+    },
+    optionTitle: {
+      fontSize: 18,
+      fontWeight: '600',
+      color: themeColors.foreground,
+      margin: 0,
+    },
+    optionDescription: {
+      fontSize: 14,
+      color: themeColors.mutedForeground,
+    },
+    customUrlContainer: {
+      gap: 12,
+    },
+    inputLabel: {
+      fontSize: 14,
+      fontWeight: '600',
+      color: themeColors.foreground,
+      marginBottom: 4,
+    },
+    input: {
+      height: 50,
+      borderWidth: 1,
+      borderColor: themeColors.border,
+      borderRadius: 8,
+      paddingHorizontal: 16,
+      fontSize: 16,
+      color: themeColors.foreground,
+      backgroundColor: themeColors.secondaryBackground,
+    },
+    button: {
+      height: 50,
+      backgroundColor: themeColors.primary,
+      borderRadius: 8,
+      justifyContent: 'center',
+      alignItems: 'center',
+    },
+    buttonDisabled: {
+      opacity: 0.5,
+    },
+    buttonText: {
+      color: themeColors.primaryForeground,
+      fontSize: 16,
+      fontWeight: '600',
+    },
+  });
+}