# Introduction

Sovrium is a source-available, self-hosted platform that turns a single configuration file into a complete web application.

:::callout
**Sovrium v0.10.0 — Active Development.** This project is under active development. APIs, configuration format, and features may change between versions.
:::

## What is Sovrium?

Sovrium is a configuration-driven application platform. You describe your application in a YAML or JSON file (data models, authentication, pages, themes, analytics) and Sovrium turns it into a running, full-stack web application.

No boilerplate code, no framework setup, no build pipeline. Just one file that declares what your app should be.

```yaml
name: my-app

tables:
  - id: 1
    name: tasks
    fields:
      - id: 1
        name: title
        type: single-line-text
        required: true

auth:
  strategies:
    - type: emailAndPassword

theme:
  colors:
    primary: '#3b82f6'
```

## Why Sovrium?

Most business applications share the same building blocks: data tables, user authentication, server-rendered pages, and a design system. Sovrium provides all of these out of the box, configured through a single schema.

### No vendor lock-in

Self-hosted on your infrastructure. Your data stays yours.

### Configuration over code

Declare what you need instead of writing boilerplate. 49 field types, ~80 component types, built-in auth.

### Progressive complexity

Start with just a name. Add tables, theme, pages, auth, and analytics as your needs grow.

### Source-available

Business Source License 1.1. Free for internal use. Becomes Apache 2.0 in 2030.

## How it works

Write a configuration file, run one command, and get a working application:

1. Define your schema in YAML or JSON
2. Run `sovrium start app.yaml`
3. Get a full-stack app with data tables, auth, pages, and more

## Next steps

Ready to try it? Install Sovrium and build your first app in under 5 minutes.

:::callout
**Installation** — Install Sovrium globally or as a project dependency using Bun.
:::

## Getting help

Found a bug, have a question, or want to request a feature?

Sovrium is open source. If you run into any issues or have ideas for improvement, the best way to reach us is through GitHub Issues.

[Open an issue on GitHub →](https://github.com/sovrium/sovrium/issues)

# Installation

Install Sovrium globally or as a project dependency using Bun.

## Prerequisites

Tables and auth work out of the box on an embedded SQLite database — no setup required. PostgreSQL 15+ is optional and unlocks advanced features (raw SQL, vector search). Running from source or as a library requires [Bun 1.3+](https://bun.sh).

## Standalone binary (recommended)

Sovrium ships as a self-contained binary — the recommended way to install. No runtime to install separately.

```bash
# Install script
curl -fsSL https://sovrium.com/install | sh

# Homebrew
brew install sovrium/tap/sovrium

# Docker
docker pull ghcr.io/sovrium/sovrium:latest
```

After installing, the `sovrium` command is available from anywhere.

## As a library

To use Sovrium programmatically from a Bun project, add it as a dependency:

```bash
bun add sovrium
```

:::callout
**Authoring config in TypeScript?** Install the zero-dependency `@sovrium/types` package for IDE autocompletion (`bun add -d @sovrium/types`) and author with `defineConfig`. See [Configuration Files](/en/configuration-files).
:::

## Verify installation

Run the help command to check that Sovrium is installed correctly:

```bash
sovrium --help
```

## Create a config file

Sovrium reads a YAML or JSON configuration file. Create an `app.yaml` with the simplest valid config:

```yaml
name: my-app
```

:::callout
**YAML or JSON.** Sovrium supports both `.yaml`/`.yml` and `.json` files. YAML is recommended for readability.
:::

## Database setup

Sovrium uses an embedded SQLite database by default — tables and auth work with zero configuration. Set `DATABASE_URL` only to choose the SQLite file location or to switch to PostgreSQL:

```bash
# Default: embedded SQLite — no DATABASE_URL needed

# Optional — choose where the SQLite file lives:
export DATABASE_URL="file:./data/app.db"

# Optional — use PostgreSQL for advanced features:
export DATABASE_URL="postgresql://user:password@localhost:5432/myapp"
```

:::callout
**SQLite by default.** Leave `DATABASE_URL` unset and Sovrium stores data in a local SQLite file. Use a `file:` URL to pick its location, or a `postgresql://` URL to switch engines. Pure static sites (pages and theme only) need no database at all.
:::

## Next steps

- [Quick Start](/en/quick-start) — build and run your first app.
- [Core Concepts](/en/concepts) — the anatomy of a Sovrium app.
- [Configuration Files](/en/configuration-files) — YAML, JSON, TypeScript, and `$ref`.

# Quick Start

Build your first Sovrium app in minutes. From zero to a running application. Choose the approach that fits your workflow.

## Choose your approach

Sovrium supports two configuration formats. YAML is great for simplicity; TypeScript gives you full type safety and autocompletion.

### Option A: YAML + CLI

The simplest path. Install the Sovrium CLI, write a YAML config, and start the server:

1. **Install the CLI** — Install Sovrium globally with Bun to get the `sovrium` command.

   ```bash
   bun add -g sovrium
   ```

2. **Create a config file** — Create an `app.yaml` with the simplest valid configuration: just a name.

   ```yaml
   name: my-app
   ```

3. **Add data tables** — Define your data models with typed fields, options, and validation.

   ```yaml
   name: my-app

   tables:
     - id: 1
       name: tasks
       fields:
         - id: 1
           name: title
           type: single-line-text
           required: true
         - id: 2
           name: status
           type: single-select
           options: [To Do, In Progress, Done]
   ```

4. **Start the server** — Run the dev server and visit `http://localhost:3000` to see your app.

   ```bash
   sovrium start app.yaml
   ```

:::callout
**Add more as you go.** Start small with just tables. Then progressively add theme, auth, pages, and analytics as your needs grow.
:::

### Option B: TypeScript + Bun

The power-user path. Create a Bun project, add Sovrium as a dependency, and write type-safe code:

1. **Initialize a project** — Scaffold a new Bun project with `bun init` and move into the directory.

   ```bash
   bun init my-app && cd my-app
   ```

2. **Add Sovrium** — Install Sovrium as a project dependency.

   ```bash
   bun add sovrium
   ```

3. **Write your app** — Open `index.ts` and import the `start` function with a minimal configuration.

   ```typescript
   import { start } from 'sovrium'

   await start({
     name: 'my-app',
   })
   ```

4. **Add data tables** — Extend the configuration with typed fields, options, and validation, with full autocompletion.

   ```typescript
   import { start } from 'sovrium'

   await start({
     name: 'my-app',
     tables: [
       {
         id: 1,
         name: 'tasks',
         fields: [
           {
             id: 1,
             name: 'title',
             type: 'single-line-text',
             required: true,
           },
           {
             id: 2,
             name: 'status',
             type: 'single-select',
             options: ['To Do', 'In Progress', 'Done'],
           },
         ],
       },
     ],
   })
   ```

5. **Run your app** — Execute `index.ts` with Bun. Visit `http://localhost:3000` to see your app.

   ```bash
   bun run index.ts
   ```

:::callout
**Why TypeScript?** TypeScript gives you autocompletion for every property, compile-time validation of field types, and the full power of Bun as your runtime. Ideal for developers who prefer code over config files.
:::

## What's next?

Now that your app is running, explore the schema reference to add more capabilities:

- [Core Concepts](/en/concepts): The anatomy of a Sovrium app
- [Schema Overview](/en/overview): All 18 root properties explained
- [Tables Overview](/en/tables-overview): 49 field types, permissions, indexes
- [Theme](/en/theme): Colors, fonts, spacing, and design tokens
- [Pages Overview](/en/pages-overview): ~80 component types for server-rendered pages

# Core Concepts

A Sovrium app is a single declarative **configuration object**. You describe _what_ your application is — its data, pages, forms, authentication, automations — and Sovrium turns that description into a running, full-stack web application. There is no boilerplate, no framework scaffolding, and no build pipeline to wire up.

This page explains the anatomy of that configuration object so the rest of the [App Schema](/en/overview) reference makes sense.

## The configuration object

Everything starts from one root object. Only `name` is required; every other section is optional and layered on as your app grows.

```yaml
name: my-app # App identifier (required)
version: 1.0.0 # SemVer version
description: My application # One-line description

tables: [...] # Data models (49 field types)
pages: [...] # Server-rendered pages (~80 component types)
forms: [...] # Standalone forms that capture submissions
auth: { ... } # Authentication, roles, RBAC
theme: { ... } # Design tokens (colors, fonts, spacing, …)
languages: { ... } # Multi-language support ($t: syntax)

automations: [...] # Event-driven workflows (triggers + actions)
actions: [...] # Reusable action templates ($ref)
connections: [...] # External-service credentials
agents: [...] # AI agents acting under an auth role
buckets: [...] # Named file-storage containers

components: [...] # Reusable UI templates ($ref, $variable)
analytics: { ... } # Cookie-free, first-party analytics
env: { ... } # Declared automation env vars ($env.NAME)
scripts: { ... } # Global page scripts
```

:::callout
**Progressive complexity.** A valid app can be as small as `name: my-app`. Add sections only when you need them — there is no "minimum viable scaffold" to fight through first.
:::

## The root sections

The configuration object groups its capabilities into the sections below. Each links to its dedicated reference.

| Section       | Purpose                                                                             | Reference                                        |
| ------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------ |
| `name`        | App identifier (npm naming rules). The only required property.                      | [App Metadata](/en/app-metadata)                 |
| `version`     | Semantic Versioning string. Feeds the immutable version ledger.                     | [App Metadata](/en/app-metadata)                 |
| `description` | Single-line app description (max 2000 chars).                                       | [App Metadata](/en/app-metadata)                 |
| `tables`      | Data models — the columns records can store across 49 field types.                  | [Tables Overview](/en/tables-overview)           |
| `pages`       | Server-rendered pages built from a tree of component types, with SEO and i18n.      | [Pages Overview](/en/pages-overview)             |
| `forms`       | Standalone forms that capture submissions into a table or trigger an automation.    | [Forms Overview](/en/forms-overview)             |
| `auth`        | Authentication strategies, roles, RBAC, sessions, and two-factor.                   | [Auth Overview](/en/auth-overview)               |
| `theme`       | Design tokens: colors, fonts, spacing, shadows, animations, breakpoints, radii.     | [Theme](/en/theme)                               |
| `languages`   | Multi-language support with `$t:` translation syntax and URL routing.               | [Languages](/en/languages)                       |
| `automations` | Event-driven workflows: a trigger fires, a sequence of actions runs.                | [Automations Overview](/en/automations-overview) |
| `actions`     | Reusable action templates referenced from automations via `$ref`.                   | [Automations Overview](/en/automations-overview) |
| `connections` | Reusable credentials for external services (OAuth2, API key, basic, bearer).        | [Automations Overview](/en/automations-overview) |
| `agents`      | AI agents that act on behalf of an auth role within a constrained tool set.         | [AI Overview](/en/ai-overview)                   |
| `buckets`     | Named storage containers with per-bucket file limits and permissions.               | [Buckets Overview](/en/buckets-overview)         |
| `components`  | Reusable UI templates inserted into pages via `$ref` with `$variable` substitution. | [Pages Overview](/en/pages-overview)             |
| `analytics`   | First-party, cookie-free analytics. `true` for defaults or an object for options.   | [Schema Overview](/en/overview)                  |
| `env`         | Declared environment variables resolved at runtime, referenced as `$env.NAME`.      | [Environment Variables](/en/env-vars)            |
| `scripts`     | Global scripts loaded on every page before page-level scripts.                      | [Pages Overview](/en/pages-overview)             |

:::callout
**Records are not a root section.** Records are the rows _inside_ your tables. They are created and queried at runtime through the REST/MCP API rather than declared in the config — see [Records Overview](/en/records-overview).
:::

## Configuration-driven philosophy

Sovrium inverts the usual relationship between code and configuration. Instead of writing application code that occasionally reads a config file, you write configuration that Sovrium executes directly.

- **Declare, don't implement.** You declare a `relationship` field; Sovrium creates the foreign key, the join queries, and the linked-record UI. You declare an `automation`; Sovrium wires the trigger, runs the actions, and records the run history.
- **One source of truth.** The same object drives the database schema, the REST API, the MCP server, the rendered pages, and the admin dashboard. There is no second place where the shape of your data is restated.
- **Cross-section validation.** Sections are validated together, not in isolation. A record automation that references a missing table, an attachment field pointing at an undeclared bucket, or a permission naming an unknown role are all rejected before the server starts — see [`sovrium validate`](/en/cli).
- **Self-hostable, no lock-in.** The config runs on your infrastructure against commodity storage (SQLite by default, PostgreSQL optional). Your data and your schema stay yours.

## The layer model (at a glance)

Internally, Sovrium follows a four-layer architecture. You never write code in these layers for a config-only app, but the model explains _why_ the schema is shaped the way it is.

| Layer              | Responsibility                                           | What your config touches                           |
| ------------------ | -------------------------------------------------------- | -------------------------------------------------- |
| **Presentation**   | Renders pages and serves the REST/MCP API.               | `pages`, `forms`, `components`, `theme`, `scripts` |
| **Application**    | Orchestrates workflows and use-cases.                    | `automations`, `actions`, `agents`                 |
| **Domain**         | Pure business rules and the validated app schema itself. | `tables`, `auth`, `languages`, validation          |
| **Infrastructure** | Talks to the database, file storage, and external APIs.  | `connections`, `buckets`, `env`                    |

The dependency direction always flows inward (Presentation → Application → Domain ← Infrastructure), which is why declaring data and rules (`tables`, `auth`) is independent of how they are rendered (`pages`) or persisted (`buckets`).

## Next steps

- [Configuration Files](/en/configuration-files) — YAML vs TypeScript, `defineConfig`, and multi-file configs with `$ref`.
- [Schema Overview](/en/overview) — the full root-property reference.
- [Quick Start](/en/quick-start) — build and run your first app.

# CLI Reference

The Sovrium CLI runs your application and manages its lifecycle: start and stop the server, hot-reload config without downtime, build a static site, scaffold a project, print the JSON Schema, and validate a config file. Configuration is loaded from a file or environment variable.

## Usage

The CLI accepts a command followed by an optional config file path and flags.

```bash
sovrium [command] [config] [flags]

sovrium start app.yaml          # Start the server (default command)
sovrium stop                    # Stop the running server
sovrium restart app.yaml        # Restart the running server
sovrium reload                  # Hot-reload config without downtime
sovrium build app.yaml          # Build static site
sovrium init ./my-app           # Scaffold a new project
sovrium schema                  # Print JSON Schema
sovrium validate app.yaml       # Validate config
sovrium --help                  # Show help
```

## Commands

The most common commands are below. If no command is specified, `start` is used by default. The CLI also exposes commands to extend a project (`agents`), operate it (`admin`, `secret`), and keep the binary current (`update`) — all documented below. Run `sovrium --help` for the full list.

### `sovrium start`

Start a development server that serves your application. This is the default command — running `sovrium app.yaml` is equivalent to `sovrium start app.yaml`.

```bash
sovrium start app.yaml
```

### `sovrium stop`

Stop the running Sovrium server.

```bash
sovrium stop
```

### `sovrium restart`

Restart the running server, optionally with a new config file.

```bash
sovrium restart app.yaml
```

### `sovrium reload`

Hot-reload the configuration of a running server without downtime. The reload first probes the live app's drift posture; if the live schema has drifted from the file (edited at runtime via the admin API or MCP), the reload is refused unless `--force` is passed. See [App Metadata](/en/app-metadata#schema-drift-detection).

```bash
sovrium reload
sovrium reload --force   # overwrite a drifted live schema with the file
```

### `sovrium init`

Scaffold a new project in the given directory (or the current directory). Use `--template <name>` to start from a template and `--name <name>` to set the app name.

```bash
sovrium init ./my-app --template blog
```

### `sovrium build`

Generate a static site from your configuration. Produces HTML, CSS, and assets ready for deployment to any static hosting provider.

```bash
sovrium build app.yaml
```

### `sovrium schema`

Print the JSON Schema (Draft-07) for the Sovrium app configuration to stdout. Use `--output <path>` to write to a file instead.

```bash
sovrium schema
sovrium schema --output app.schema.json
```

### `sovrium validate <config>`

Validate a configuration file against the Sovrium AppSchema. Returns exit code 0 if valid, 1 if invalid with error details.

```bash
sovrium validate app.yaml
```

### `sovrium agents list`

List the agent templates embedded in the binary. These are Claude Code subagent definitions you can install into a project's `.claude/agents/` directory.

```bash
sovrium agents list
```

### `sovrium agents install <name>`

Install an embedded agent template into `.claude/agents/<name>.md`. `add` is an alias of `install`. By default the agent is written under the current directory; pass `--target <dir>` to choose another project root. The command refuses to overwrite an existing agent file unless `--force` is supplied.

```bash
sovrium agents install crud-editor
sovrium agents add crud-editor --target ./my-project --force
```

### `sovrium admin create <email>`

Provision an admin user against the database without standing up a full schema. The password is taken from `--password <value>` when supplied (useful for CI/scripting); otherwise you are prompted interactively with echo disabled. Running without `--password` in a non-interactive shell (no TTY) is an error.

The database schema is resolved in this order: an explicit `--config <path>`, then `APP_SCHEMA`, then a minimal built-in default — so the bare `sovrium admin create <email>` flow works with no config file. If the admin already exists, no changes are made.

```bash
# Prompt for the password interactively
sovrium admin create me@example.com

# Supply the password (CI / scripting)
sovrium admin create me@example.com --password 's3cret-pass'

# Resolve the schema from a specific config
sovrium admin create me@example.com --config app.yaml
```

### `sovrium secret generate`

Print freshly-generated, cryptographically random secrets as `.env`-ready lines. Each secret is a 256-bit (64 hex character) value. With no scope, both `AUTH_SECRET` and `SOVRIUM_ENCRYPTION_KEY` are printed. Pass a scope to print a subset.

| Scope        | Output                                   |
| ------------ | ---------------------------------------- |
| _(none)_     | `AUTH_SECRET` + `SOVRIUM_ENCRYPTION_KEY` |
| `all`        | Both (explicit)                          |
| `auth`       | `AUTH_SECRET` only                       |
| `encryption` | `SOVRIUM_ENCRYPTION_KEY` only            |

The generated `.env` lines are written to stdout (so redirects work cleanly); informational notes go to stderr.

```bash
# Both secrets
sovrium secret generate

# Append a fresh AUTH_SECRET to your .env
sovrium secret generate auth >> .env

# Encryption key only
sovrium secret generate encryption
```

### `sovrium update`

Update Sovrium to the latest version. The behavior depends on how Sovrium was installed:

| Install method | Behavior                                                 |
| -------------- | -------------------------------------------------------- |
| `binary`       | Self-replaces from GitHub Releases (Unix)                |
| `homebrew`     | Delegates to `brew upgrade sovrium/tap/sovrium`          |
| `scoop`        | Delegates to `scoop update sovrium`                      |
| `docker`       | Prints the `docker pull` instruction                     |
| `npm`          | Prints a deprecation notice (the npm package is retired) |

```bash
sovrium update
sovrium update --help
```

### `sovrium --help`

Display the help message with a summary of commands, options, and examples.

```bash
sovrium --help
```

## Flags

Flags can be placed anywhere in the command.

| Flag                 | Description                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--watch, -w`        | Watch the config file for changes and hot-reload the server automatically. Only available with the `start` command. |
| `--version, -V`      | Show the Sovrium version number and exit.                                                                           |
| `--output <path>`    | Write output to a file instead of stdout (`schema` command only).                                                   |
| `--template <name>`  | Project template to scaffold from (`init` command).                                                                 |
| `--name <name>`      | App name to set when scaffolding (`init` command).                                                                  |
| `--target <dir>`     | Install destination, defaults to the current directory (`agents install` command).                                  |
| `--config <path>`    | Config file used to resolve the database schema (`admin create` command).                                           |
| `--password <value>` | Admin password; if omitted you are prompted interactively (`admin create` command).                                 |
| `--force`            | Overwrite existing files or a drifted live schema (`init`, `reload`, `agents install`).                             |
| `--help, -h`         | Show the help message and exit.                                                                                     |

## Configuration Sources

Sovrium can load configuration from a file path or from the `APP_SCHEMA` environment variable. A file path takes precedence when both are provided.

### File path

Pass a path to a JSON or YAML configuration file as the second argument.

```bash
sovrium start app.yaml
sovrium build config.json
```

### Environment variable

Set the `APP_SCHEMA` variable to provide configuration without a file. Supports inline JSON, inline YAML, or a remote URL.

```bash
# Inline JSON
APP_SCHEMA='{"name":"my-app"}' sovrium start

# Inline YAML
APP_SCHEMA='name: my-app' sovrium start

# Remote URL
APP_SCHEMA='https://example.com/app.yaml' sovrium start
```

:::callout
**YAML or JSON.** Sovrium supports both `.yaml`/`.yml` and `.json` files. YAML is recommended for readability.
:::

## Watch Mode

Watch mode monitors your config file and automatically reloads the server when changes are detected.

```bash
# Start with file watching
sovrium start app.yaml --watch

# Edit app.yaml in another terminal...
# Server reloads automatically
```

:::callout
**Error recovery.** If the updated config file is invalid, the reload fails gracefully and the previous server continues running. Fix the config and save to retry.
:::

## Examples

Common CLI usage patterns.

### `sovrium start`

```bash
# Start from a JSON file
sovrium start app.json

# Start from a YAML file
sovrium start app.yaml

# Implicit start (default command)
sovrium app.yaml

# Start with watch mode (hot reload)
sovrium start app.yaml --watch
sovrium start app.yaml -w

# Start on a custom port
PORT=8080 sovrium start app.yaml
```

### `sovrium build`

```bash
# Basic static build
sovrium build app.yaml

# Build for GitHub Pages
SOVRIUM_DEPLOYMENT=github-pages sovrium build app.yaml

# Build with sitemap and custom output
SOVRIUM_OUTPUT_DIR=./public \
  SOVRIUM_BASE_URL=https://example.com \
  SOVRIUM_GENERATE_SITEMAP=true \
  SOVRIUM_GENERATE_ROBOTS=true \
  sovrium build app.yaml
```

### `sovrium schema`

```bash
# Print JSON Schema to stdout
sovrium schema

# Write JSON Schema to a file
sovrium schema --output app.schema.json
```

### `sovrium validate <config>`

```bash
# Validate a YAML config
sovrium validate app.yaml

# Validate a JSON config
sovrium validate config.json
```

## Exit Codes

The CLI uses standard exit codes.

| Code | Meaning                                               |
| ---- | ----------------------------------------------------- |
| `0`  | Success                                               |
| `1`  | Error (invalid config, missing file, unknown command) |

## Related Pages

- [Configuration Files](/en/configuration-files) — YAML, JSON, TypeScript, and `$ref` multi-file configs.
- [Environment Variables](/en/env-vars) — `APP_SCHEMA`, `PORT`, `DATABASE_URL`, and build vars.
- [App Metadata](/en/app-metadata) — the version ledger and drift detection that `reload` respects.

# TypeScript API

Use Sovrium as a library in your TypeScript project. Import `start`, `build`, and the `AppConfig` type for full programmatic control with typed configuration.

```typescript
import { start, build, generateAppJsonSchema, validateConfig } from 'sovrium'
import type { AppConfig, SimpleServer, ValidateConfigResult } from 'sovrium'

// All config types are available:
// PageConfig, TableConfig, ThemeConfig, AuthConfig,
// ComponentConfig, LanguageConfig, AnalyticsConfig, ...
```

## Why TypeScript?

Using Sovrium programmatically gives you advantages beyond the CLI.

### Type safety

The `AppConfig` type provides autocomplete for every property and field type. Catch errors at compile time, not runtime.

### Programmatic control

Generate configuration dynamically, compose schemas, and integrate Sovrium into existing applications.

### IDE integration

Full IntelliSense in VS Code and JetBrains — hover docs, go-to-definition, and type errors.

## `start(app, options?)`

Start a development server from a typed configuration object. Returns a server instance with a `stop()` method.

```typescript
import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)
```

### `StartOptions`

Optional second argument to configure the server.

| Property    | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `port`      | Port number (0–65535). 0 selects an available port. Default: 3000. |
| `hostname`  | Server hostname. Default: `localhost`.                             |
| `publicDir` | Static file directory. Files are served at their relative path.    |

```typescript
import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)
```

## `build(app, options?)`

Generate a static site from a typed configuration object.

### `GenerateStaticOptions`

Optional second argument to control static output.

| Property             | Description                                         |
| -------------------- | --------------------------------------------------- |
| `outputDir`          | Output directory. Default: `./static`.              |
| `baseUrl`            | Base URL for sitemap and canonical links.           |
| `basePath`           | Path prefix for subdirectory deployments.           |
| `deployment`         | Target platform: `github-pages` or `generic`.       |
| `languages`          | Array of language codes for generation.             |
| `defaultLanguage`    | Default language code.                              |
| `generateSitemap`    | Generate `sitemap.xml`. Default: `false`.           |
| `generateRobotsTxt`  | Generate `robots.txt`. Default: `false`.            |
| `hydration`          | Enable client-side hydration. Default: `false`.     |
| `generateManifest`   | Generate `manifest.json` for PWA. Default: `false`. |
| `bundleOptimization` | Splitting strategy: `split` or `none`.              |
| `publicDir`          | Static asset directory to copy into output.         |

```typescript
import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)
```

## `generateAppJsonSchema()`

Generate the JSON Schema (Draft-07) for the Sovrium app configuration. Returns a plain object suitable for serialization or programmatic use.

```typescript
import { generateAppJsonSchema } from 'sovrium'

const schema = generateAppJsonSchema()
Bun.write('app.schema.json', JSON.stringify(schema, null, 2))
```

## `validateConfig(config)`

Validate an unknown value against the Sovrium AppSchema. Returns a result object indicating whether the config is valid, with parsed config or error details.

```typescript
import { validateConfig } from 'sovrium'

const result = validateConfig({ name: 'My App' })
if (result.valid) {
  console.log(result.config.name)
} else {
  console.error(result.errors)
}
```

## `AppConfig`

The primary type for typing your JSON or YAML configuration objects. Import it from `sovrium` to get full autocomplete and type checking.

| Property       | Description                                                                            |
| -------------- | -------------------------------------------------------------------------------------- |
| `name`         | Application name. Lowercase, npm-compatible (e.g. `my-app`, `@org/app`).               |
| `version?`     | SemVer version string (e.g. `1.0.0`).                                                  |
| `description?` | Single-line application description.                                                   |
| `tables?`      | Array of data table definitions with fields, indexes, and constraints.                 |
| `theme?`       | Design tokens: colors, fonts, spacing, animations, breakpoints, shadows, borderRadius. |
| `pages?`       | Array of page configurations with metadata, sections, and scripts.                     |
| `forms?`       | Standalone form definitions that capture submissions or trigger automations.           |
| `auth?`        | Authentication config: strategies, roles, plugins (admin, organization).               |
| `languages?`   | Multi-language config: supported languages, default language, translations.            |
| `components?`  | Array of reusable component templates with variable substitution.                      |
| `automations?` | Event-driven workflows: triggers plus sequential actions.                              |
| `actions?`     | Reusable action templates referenced from automations via `$ref`.                      |
| `connections?` | External-service credentials (OAuth2, API key, basic, bearer).                         |
| `agents?`      | AI agents acting under an auth role with constrained tools.                            |
| `buckets?`     | Named file-storage containers with per-bucket limits and permissions.                  |
| `env?`         | Declared automation environment variables, referenced as `$env.NAME`.                  |
| `analytics?`   | Built-in privacy-friendly analytics. Set to `true` for defaults or pass an object.     |

```typescript
import type { AppConfig } from 'sovrium'

const config: AppConfig = {
  name: 'my-app',
  version: '1.0.0',
  description: 'My application',
  tables: [
    /* ... */
  ],
  theme: {
    /* ... */
  },
  pages: [
    /* ... */
  ],
  auth: {
    /* ... */
  },
  languages: {
    /* ... */
  },
  components: [
    /* ... */
  ],
  analytics: true,
}
```

:::callout
**Incremental complexity.** Only `name` is required. Add `tables`, `theme`, `pages`, `auth`, `languages`, `components`, and `analytics` as you need them.
:::

## Type Reference

Additional TypeScript types exported from the `sovrium` package. Import them with `import type { ... } from "sovrium"`.

### `SimpleServer`

Returned by `start()`. A lightweight interface to the running server.

| Property | Description                                                                            |
| -------- | -------------------------------------------------------------------------------------- |
| `url`    | Server URL including protocol and port (e.g. `"http://localhost:3000"`).               |
| `stop()` | Gracefully stop the server. Returns a Promise that resolves when shutdown is complete. |

```typescript
import { start } from 'sovrium'
import type { SimpleServer } from 'sovrium'

const server: SimpleServer = await start({ name: 'my-app' })
console.log(server.url) // "http://localhost:3000"
await server.stop() // graceful shutdown
```

### `PageConfig`

Configuration for a single page. Element of `AppConfig['pages']`.

```typescript
const page: PageConfig = {
  name: 'home',
  path: '/',
  sections: [{ type: 'heading', content: 'Welcome' }],
}
```

### `TableConfig`

Configuration for a single data table. Element of `AppConfig['tables']`.

```typescript
const table: TableConfig = {
  id: 1,
  name: 'tasks',
  fields: [{ id: 1, name: 'title', type: 'single-line-text' }],
}
```

### `ComponentConfig`

Reusable component template with variable placeholders. Element of `AppConfig['components']`.

```typescript
const hero: ComponentConfig = {
  name: 'hero',
  type: 'section',
  children: [{ type: 'heading', content: '$title' }],
}
```

### `ThemeConfig`

Design tokens for colors, typography, spacing, shadows, and more.

```typescript
const theme: ThemeConfig = {
  colors: { primary: '#3b82f6' },
  fonts: { sans: 'Inter, sans-serif' },
}
```

### `AuthConfig`

Authentication strategies, roles, and plugin configuration.

```typescript
const auth: AuthConfig = {
  strategies: [{ type: 'emailAndPassword' }],
  roles: [{ name: 'admin' }, { name: 'member' }],
}
```

### `LanguageConfig`

Multi-language support with translations and language detection.

```typescript
const languages: LanguageConfig = {
  supported: ['en', 'fr'],
  default: 'en',
}
```

### `AnalyticsConfig`

Built-in privacy-friendly analytics. Use `true` for defaults or an object for custom settings.

```typescript
// Simple: just enable defaults
const analytics: AnalyticsConfig = true

// Custom settings
const custom: AnalyticsConfig = { retentionDays: 90, excludedPaths: ['/admin'] }
```

### `GenerateStaticResult`

Returned by `build()`. Contains the output directory path and the list of generated files.

| Property    | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `outputDir` | Absolute path to the output directory (e.g. `"./static"`).          |
| `files`     | Array of file paths generated during the build (HTML, CSS, assets). |

```typescript
import { build } from 'sovrium'
import type { GenerateStaticResult } from 'sovrium'

const result: GenerateStaticResult = await build({
  name: 'my-site',
  pages: [
    /* ... */
  ],
})
console.log(result.outputDir) // "./static"
console.log(result.files.length) // number of generated files
```

### `ValidateConfigResult`

Returned by `validateConfig()`. Indicates whether the config is valid and provides parsed config or error details.

| Property | Description                                                          |
| -------- | -------------------------------------------------------------------- |
| `valid`  | Boolean. `true` if the configuration is valid against the AppSchema. |
| `errors` | Array of validation error objects. Empty when `valid` is `true`.     |
| `config` | The parsed `AppConfig` object. Only present when `valid` is `true`.  |

```typescript
import { validateConfig } from 'sovrium'
import type { ValidateConfigResult } from 'sovrium'

const result: ValidateConfigResult = validateConfig({ name: 'my-app' })
console.log(result.valid) // true or false
console.log(result.errors) // validation error array (empty if valid)
console.log(result.config) // parsed AppConfig (if valid)
```

## Watch Mode

In development, use Bun's built-in watch mode to automatically restart your script when files change.

```bash
bun --watch index.ts
```

:::callout
**Reload vs watch.** `bun --watch` restarts the entire process when any imported file changes. For config-only changes, the CLI's `--watch` flag is more efficient.
:::

## Examples

Common usage patterns with Sovrium in TypeScript.

### Minimal server

```typescript
import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)
```

### With data tables

```typescript
import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)
```

### Static site generation

```typescript
import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)
```

### Dynamic configuration

```typescript
import { start } from 'sovrium'
import type { AppConfig, PageConfig, TableConfig, ThemeConfig } from 'sovrium'

// Compose config from typed sub-configs
const theme: ThemeConfig = {
  colors: { primary: process.env.BRAND_COLOR ?? '#3b82f6' },
}

const tables: TableConfig[] = ['users', 'posts'].map((name, i) => ({
  id: i + 1,
  name,
  fields: [
    { id: 1, name: 'title', type: 'single-line-text' as const, required: true },
    { id: 2, name: 'created_at', type: 'date' as const, includeTime: true },
  ],
}))

const pages: PageConfig[] = [{ name: 'home', path: '/', sections: [] }]

const app: AppConfig = {
  name: 'dynamic-app',
  tables,
  pages,
  theme,
}

await start(app)
```

# Environment Variables

Sovrium reads configuration from environment variables at startup. Set them in a `.env` file or your server environment. All variables are optional unless noted otherwise.

```bash
# .env

# Application
APP_SCHEMA='app.yaml'

# Server
PORT=3000
BASE_URL=http://localhost:3000

# Database (optional — defaults to embedded SQLite)
DATABASE_URL=file:./data/app.db

# Authentication
AUTH_SECRET=your-secret-key-here

# Default Admin
AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=secure-admin-password

# OAuth (Google example)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
```

## Application

Core application configuration. `APP_SCHEMA` is the primary way to provide a schema without a file argument.

| Variable     | Description                                                                                                      |
| ------------ | ---------------------------------------------------------------------------------------------------------------- |
| `APP_SCHEMA` | App schema as inline JSON, inline YAML, or a remote URL. Alternative to passing a file path on the command line. |

## Server

Server networking options for the `start` command.

| Variable   | Description                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `PORT`     | Server port number (0–65535). 0 selects an available port. Default: 3000.                                                       |
| `HOSTNAME` | Server hostname. Default: `localhost`.                                                                                          |
| `BASE_URL` | Base URL of the application (e.g., `https://myapp.com`). Used for authentication callback URLs and email links.                 |
| `NODE_ENV` | Runtime environment. Set to `"production"` for secure cookies, CSRF checks, and strict SMTP validation. Default: `development`. |

## Database

Database connection settings. Optional — Sovrium defaults to embedded SQLite when unset.

| Variable       | Description                                                                                                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | Database connection string. Optional: unset uses embedded SQLite; a `file:` URL (e.g., `file:./data/app.db`) picks the SQLite file; a `postgresql://` URL (e.g., `postgresql://user:password@localhost:5432/dbname`) switches to PostgreSQL. |

## Authentication

Variables for Better Auth integration. Required when the schema defines an `auth` section.

| Variable      | Description                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `AUTH_SECRET` | Secret key for signing tokens and encrypting sessions. Must be a strong random string (32+ characters recommended). |

### Default Admin User

Optional variables to create a default admin user on first startup. All three must be set for the admin user to be created.

| Variable              | Description                                                               |
| --------------------- | ------------------------------------------------------------------------- |
| `AUTH_ADMIN_EMAIL`    | Email address for the default admin user.                                 |
| `AUTH_ADMIN_PASSWORD` | Password for the default admin user. Must be at least 8 characters.       |
| `AUTH_ADMIN_NAME`     | Display name for the default admin user. Optional, defaults to `"Admin"`. |

### OAuth Providers

Credentials for each OAuth provider configured in the auth schema. Replace `{PROVIDER}` with the uppercase provider name.

| Variable                   | Description                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `{PROVIDER}_CLIENT_ID`     | OAuth client ID from the provider's developer console.                             |
| `{PROVIDER}_CLIENT_SECRET` | OAuth client secret from the provider's developer console. Keep this confidential. |

:::callout
**Supported providers.** Sovrium supports Google, GitHub, Microsoft, Slack, GitLab, and Facebook. For example, set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` for Google OAuth.
:::

## Email (SMTP)

SMTP configuration for sending authentication emails (verification, password reset, magic link). In development, falls back to Mailpit on `localhost:1025` if `SMTP_HOST` is not set.

| Variable         | Description                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| `SMTP_HOST`      | SMTP server hostname (e.g., `smtp.gmail.com`). Required in production.                         |
| `SMTP_PORT`      | SMTP server port. Default: 587.                                                                |
| `SMTP_SECURE`    | Use SSL/TLS connection. Default: `false` for port 587, `true` for port 465.                    |
| `SMTP_USER`      | SMTP authentication username.                                                                  |
| `SMTP_PASS`      | SMTP authentication password or app-specific password.                                         |
| `SMTP_FROM`      | Default sender email address (e.g., `noreply@yourdomain.com`). Default: `noreply@sovrium.com`. |
| `SMTP_FROM_NAME` | Default sender display name. Default: `Sovrium`.                                               |

:::callout
**Local development.** When `SMTP_HOST` is not configured in development mode, Sovrium automatically falls back to Mailpit (`localhost:1025`). Install Mailpit to view sent emails in a local web UI.
:::

## Build

Options for the `build` command that generates a static site.

| Variable                      | Description                                                                        |
| ----------------------------- | ---------------------------------------------------------------------------------- |
| `SOVRIUM_OUTPUT_DIR`          | Output directory. Default: `./dist`.                                               |
| `SOVRIUM_BASE_URL`            | Base URL for sitemap generation and canonical links (e.g., `https://example.com`). |
| `SOVRIUM_BASE_PATH`           | Path prefix for subdirectory deployments (e.g., `/my-app`).                        |
| `SOVRIUM_DEPLOYMENT`          | Deployment target: `github-pages` or `generic`.                                    |
| `SOVRIUM_LANGUAGES`           | Comma-separated language codes to build (e.g., `en,fr,de`).                        |
| `SOVRIUM_DEFAULT_LANGUAGE`    | Default language code (e.g., `en`).                                                |
| `SOVRIUM_GENERATE_SITEMAP`    | Generate `sitemap.xml`. Default: `false`.                                          |
| `SOVRIUM_GENERATE_ROBOTS`     | Generate `robots.txt`. Default: `false`.                                           |
| `SOVRIUM_HYDRATION`           | Enable client-side hydration. Default: `false`.                                    |
| `SOVRIUM_GENERATE_MANIFEST`   | Generate `manifest.json` for PWA. Default: `false`.                                |
| `SOVRIUM_BUNDLE_OPTIMIZATION` | Optimization strategy: `split` (code splitting) or `none`.                         |
| `SOVRIUM_PUBLIC_DIR`          | Directory containing static assets to copy into the output.                        |

## Debug

Diagnostic and testing variables. Not needed in normal operation.

| Variable                    | Description                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `LOG_LEVEL`                 | Set to `"debug"` for verbose logging (request logs, CSS compilation diagnostics). Default: follows `NODE_ENV`. |
| `EFFECT_DEVTOOLS`           | Set to `"1"` to enable Effect DevTools integration for runtime inspection.                                     |
| `RATE_LIMIT_WINDOW_SECONDS` | Rate limit window in seconds. Used in tests for faster execution. Default: 60.                                 |

# Configuration Files

Sovrium loads your application from a configuration file. The same configuration object can be written as YAML, JSON, or TypeScript, split across many files with `$ref`, and checked ahead of time with `sovrium validate`.

## YAML and JSON

The simplest configuration is a YAML or JSON file. YAML is recommended for hand-authoring — it supports comments, requires less punctuation, and is easier to read. JSON is convenient when generating configs programmatically.

```yaml
# app.yaml
name: my-app
version: 1.0.0
description: A simple todo list

tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text, required: true }
      - { id: 2, name: done, type: checkbox, default: false }
```

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A simple todo list",
  "tables": [
    {
      "id": 1,
      "name": "tasks",
      "fields": [
        { "id": 1, "name": "title", "type": "single-line-text", "required": true },
        { "id": 2, "name": "done", "type": "checkbox", "default": false }
      ]
    }
  ]
}
```

Run either with the CLI:

```bash
sovrium start app.yaml
sovrium start app.json
```

:::callout
**Format detection is by extension.** Sovrium routes `.yaml`/`.yml` files through its YAML parser and `.json` files through its JSON parser. The shape of the resulting object is identical — every example in this documentation can be transcribed between the two formats.
:::

## TypeScript with `defineConfig`

For full type safety and IDE autocompletion, author your config in TypeScript and validate it against the `@sovrium/types` package. `@sovrium/types` is a **zero-dependency** package of TypeScript types extracted directly from the Sovrium schema.

```bash
bun add -d @sovrium/types
```

```typescript
// app.ts
import { defineConfig } from '@sovrium/types'

export default defineConfig({
  name: 'my-app',
  version: '1.0.0',
  description: 'A simple todo list',
  tables: [
    {
      id: 1,
      name: 'tasks',
      fields: [
        { id: 1, name: 'title', type: 'single-line-text', required: true },
        { id: 2, name: 'done', type: 'checkbox', default: false },
      ],
    },
  ],
})
```

```bash
sovrium start app.ts
sovrium validate app.ts
```

`defineConfig` is an identity helper: it returns its argument unchanged but annotates it with the `AppConfig` type, so your editor reports invalid field types, unknown component types, and missing required properties as you type — no separate type import or `satisfies` needed.

:::callout
**`@sovrium/types` vs the `sovrium` package.** `@sovrium/types` ships only types (MIT-licensed, zero runtime). Use it to author config files. To run Sovrium programmatically (`import { start } from 'sovrium'`), see the [TypeScript API](/en/typescript).
:::

## Multi-file configs with `$ref`

As an app grows, a single file becomes unwieldy. Sovrium supports `$ref` to split configuration across multiple files. Any object containing exactly one key, `$ref`, whose value is a relative path, is replaced with the parsed contents of that file before validation.

```yaml
# app.yaml
name: crm-workspace
version: 2.0.0

auth:
  $ref: ./config/auth.yaml

theme:
  $ref: ./config/theme.yaml

tables:
  - $ref: ./config/tables/companies.yaml
  - $ref: ./config/tables/contacts.yaml
  - $ref: ./config/tables/deals.yaml

pages:
  - $ref: ./config/pages/sign-in.yaml
  - $ref: ./config/pages/companies.yaml

agents:
  - $ref: ./config/agents/records-assistant.yaml
```

```yaml
# config/tables/companies.yaml
id: 1
name: Companies
fields:
  - { id: 1, name: name, type: single-line-text, required: true }
  - { id: 2, name: website, type: url }
```

| Rule              | Behavior                                                                                                       |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| Path resolution   | `$ref` paths resolve relative to the file that contains them, not the working directory.                       |
| Mixed formats     | A YAML root file may `$ref` a JSON partial and vice versa — each file is parsed by its extension.              |
| Array elements    | A `$ref` can stand in for a whole array element (`- $ref: ...`) or a whole object value.                       |
| Resolution timing | All `$ref`s are resolved into one object _before_ schema validation, so cross-section checks see the full app. |

:::callout
**TypeScript configs compose differently.** `$ref` is a YAML/JSON mechanism. In TypeScript you compose with ordinary `import`s — define sub-configs in separate modules and assemble them inside `defineConfig({ ... })`.
:::

## Loading without a file

Configuration can also come from the `APP_SCHEMA` environment variable instead of a file path — inline JSON, inline YAML, or a remote URL. See the [CLI Reference](/en/cli#configuration-sources) for details.

## Validating a config

`sovrium validate` checks a config file against the full app schema — including cross-section rules such as "a record automation must reference an existing table" — and returns a non-zero exit code with error details when something is wrong.

```bash
sovrium validate app.yaml
sovrium validate app.ts
sovrium validate config.json
```

Run it in CI to catch configuration errors before deployment. Because validation runs the same schema the server uses at boot, a config that passes `validate` is guaranteed to start.

## Next steps

- [Core Concepts](/en/concepts) — the anatomy of the configuration object.
- [CLI Reference](/en/cli) — every command, flag, and configuration source.
- [TypeScript API](/en/typescript) — running Sovrium as a library.
- [Schema Overview](/en/overview) — the full root-property reference.

# Templates & Examples

The fastest way to learn Sovrium is to start from a working app. Sovrium ships a set of example configurations — each a complete, runnable project that composes real features (tables, auth, pages, theme, i18n, automations) into a single config tree. The same examples double as `sovrium init` templates, so you can scaffold any of them into a new directory and start iterating immediately.

Every example is a **directory** with an `app.yaml` entry point. Anything beyond the smallest starter splits its configuration across a `config/` subtree using [`$ref`](/en/configuration-files#multi-file-configs-with-ref) — one file per collection entity, one file per singleton, scalars stay inline. This mirrors the structure `sovrium init` scaffolds for you.

## Available templates

| Template          | Description                                                                                                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **hello-world**   | Minimal starter — one page, no collections. The default for `sovrium init`. Stays a single `app.yaml` to demonstrate when _not_ to pre-split.                                                                                   |
| **landing-page**  | Bilingual marketing site with i18n, a theme, reusable components, and the home page split out for size.                                                                                                                         |
| **crud-app**      | CRUD app with tables (contacts, companies), email/password auth, a theme, and dashboard + sign-in pages.                                                                                                                        |
| **api-only**      | Headless API mode with tables (projects, tasks) and auth — no pages. Demonstrates Sovrium as a backend.                                                                                                                         |
| **member-portal** | Public marketing pages plus an auth-gated portal area with role-gated sections. Magic-link + password auth.                                                                                                                     |
| **mcp-server**    | Headless MCP server exposing tables to an LLM client via per-entity `aiAccess` — no pages. See [MCP Integration](/en/mcp-integration).                                                                                          |
| **blog**          | Blog with posts (rich-text), tags, authors, and an index plus a dynamic `/blog/:slug` detail route.                                                                                                                             |
| **docs-site**     | Documentation website showcasing the markdown-pages feature: real `.md` files under `content/docs/`, a `contentDir` collection, a frontmatter sidebar, prev/next chrome, a TOC, and Shiki-highlighted code. No tables, no auth. |

Several templates ship with a paired editor agent (a Claude Code subagent definition) that `sovrium init` installs into `.claude/agents/`. See [`sovrium agents`](/en/cli#sovrium-agents-list) for managing agent templates directly.

## Scaffolding a project

`sovrium init` copies a template into a new (or current) directory. With no `--template`, the minimal `hello-world` starter is used.

```bash
# Default (hello-world, no paired agent)
sovrium init my-app

# Choose a template — also installs the paired editor agent
sovrium init my-app --template crud-app
sovrium init my-app --template landing-page
sovrium init my-app --template blog
sovrium init my-app --template member-portal

# Skip the paired agent install
sovrium init my-app --template crud-app --no-agent
```

Then run the scaffolded app:

```bash
sovrium start app.yaml          # Start the dev server
sovrium validate app.yaml       # Validate without starting
```

See the [CLI Reference](/en/cli#sovrium-init) for all `init` flags.

## Anatomy of an example

A non-trivial example looks like this (abbreviated `crud-app` layout):

```
crud-app/
├── app.yaml                 # Entry point — references everything via $ref
├── config/
│   ├── auth.yaml            # Singleton: auth strategies, roles
│   ├── theme.yaml           # Singleton: design tokens
│   └── tables/
│       ├── companies.yaml   # One file per table
│       └── contacts.yaml
└── public/                  # Static assets (favicon, images)
```

The `app.yaml` entry point pulls each part together with `$ref`, keeping the top-level file small and each entity in its own file:

```yaml
name: crud-app

auth:
  $ref: ./config/auth.yaml

theme:
  $ref: ./config/theme.yaml

tables:
  - $ref: ./config/tables/companies.yaml
  - $ref: ./config/tables/contacts.yaml

pages:
  - $ref: ./config/pages/dashboard.yaml
  - $ref: ./config/pages/sign-in.yaml
```

`$ref` resolution happens **before** validation: any object containing exactly one key — `$ref` whose value is a relative path — is replaced with the parsed contents of that file. A `$ref` may itself contain further `$ref`s, so configs nest to any depth. The single-file and multi-file forms are interchangeable; pick whichever keeps the project readable.

:::callout
**When to split.** Keep a config in one file while it is small (like `hello-world`). Split with `$ref` once a section grows large enough to deserve its own file — typically once you have more than one table, page, or a substantial theme. The full mechanics live in [Configuration Files → Multi-file configs](/en/configuration-files#multi-file-configs-with-ref).
:::

## Learning path

A practical order for working through the examples:

1. **hello-world** — understand the minimal shape of a config and the `pages` array.
2. **landing-page** — add a theme, reusable components, and i18n with `$t:` translation keys.
3. **crud-app** — introduce tables, auth, and data-bound pages (forms + data tables).
4. **api-only** / **mcp-server** — run Sovrium headless: as a REST backend or an LLM-facing MCP server.
5. **blog** / **member-portal** / **docs-site** — combine dynamic routes, role-gated areas, and markdown content.

## Related Pages

- [Quick Start](/en/quick-start) — zero to running app via YAML + CLI or TypeScript + Bun.
- [Configuration Files](/en/configuration-files) — YAML, JSON, TypeScript, and `$ref` multi-file composition.
- [CLI Reference](/en/cli) — `sovrium init`, `sovrium agents`, and the full command surface.
- [MCP Integration](/en/mcp-integration) — the headless MCP-server template explained.

# Schema Overview

The complete reference for the Sovrium app schema. A declarative configuration object with 18 root properties — only `name` is required. Everything else is optional, enabling progressive complexity from a minimal app identifier to a full-stack application.

## Schema Structure

```yaml
name: my-app # App identifier (required)
version: 1.0.0 # SemVer version
description: My application # One-line description

tables: [...] # Data models with 49 field types
pages: [...] # Server-rendered pages (~80 component types)
forms: [...] # Standalone forms capturing submissions
auth: { ... } # Authentication, roles, RBAC, 2FA
theme: { ... } # Design tokens (colors, fonts, etc.)
languages: { ... } # Multi-language support ($t: syntax)

automations: [...] # Event-driven workflows (triggers + actions)
actions: [...] # Reusable action templates ($ref)
connections: [...] # External-service credentials
agents: [...] # AI agents acting under an auth role
buckets: [...] # Named file-storage containers

components: [...] # Reusable UI templates ($ref, $variable)
analytics: { ... } # Cookie-free, first-party analytics
env: { ... } # Declared automation env vars ($env.NAME)
scripts: { ... } # Global page scripts
```

:::callout
**Progressive complexity.** Only `name` is required. Add `tables`, `theme`, `pages`, `auth`, and other sections as your app grows.
:::

## Root Properties

The app schema has 18 root properties. Only `name` is required.

| Property      | Type              | Description                                                                                                        |
| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `name`        | string (required) | App identifier following npm naming conventions. Lowercase, max 214 chars, supports scoped format (`@scope/name`). |
| `version`     | string            | Semantic Versioning 2.0.0 string (e.g. `1.0.0`, `2.0.0-beta.1`). Feeds the immutable version ledger.               |
| `description` | string            | Single-line app description (max 2000 chars). No line breaks. Unicode and emojis supported.                        |
| `tables`      | array             | Data models with 49 field types, relationships, indexes, permissions, and views.                                   |
| `theme`       | object            | Design tokens: colors, fonts, spacing, shadows, animations, breakpoints, and border radius.                        |
| `languages`   | object            | Multi-language support with `$t:` translation syntax, browser detection, and URL routing.                          |
| `auth`        | object            | Authentication strategies (email/password, magic link, OAuth), roles, RBAC, sessions, and two-factor.              |
| `analytics`   | object \| boolean | Privacy-friendly, cookie-free, first-party analytics. Set to `true` for defaults or configure with options.        |
| `components`  | array             | Reusable UI templates with `$ref` referencing and `$variable` substitution.                                        |
| `pages`       | array             | Server-rendered pages with ~80 component types, SEO metadata, and i18n support.                                    |
| `forms`       | array             | Standalone forms that capture submissions into a table or trigger an automation.                                   |
| `connections` | array             | Reusable credentials for external services: OAuth2, API key, basic auth, and bearer token.                         |
| `env`         | object            | Declared environment variables resolved at runtime, referenced in actions as `$env.NAME` (never logged).           |
| `actions`     | array             | Reusable action templates referenced from automations via `$ref` with `$vars`.                                     |
| `automations` | array             | Event-driven workflows: a trigger fires, a sequence of actions runs.                                               |
| `agents`      | array             | AI agents acting on behalf of an auth role within a constrained tool set, with approval gates and rate limits.     |
| `buckets`     | array             | Named storage containers with per-bucket file limits and access permissions.                                       |
| `scripts`     | object            | Global scripts loaded on every page before page-level scripts.                                                     |

## Property Details

Detailed rules and constraints for the three scalar root properties — `name`, `version`, and `description` — are covered on the [App Metadata](/en/app-metadata) page, which also documents the version ledger, drift detection, and draft staleness.

### `name`

The app name follows npm naming conventions. Lowercase, URL-safe, and unique within your deployment.

| Constraint | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| Pattern    | `^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$`. Lowercase letters, digits, hyphens, dots, tildes. |
| Max length | 214 characters maximum (including `@scope/` prefix if scoped).                                               |
| Scoped     | Supports npm-style scoped packages: `@scope/name` (e.g. `@acme/dashboard`).                                  |

```yaml
# Valid names
name: my-app
name: task-tracker-v2
name: '@acme/dashboard'
```

### `version`

Follows Semantic Versioning 2.0.0 ([semver.org](https://semver.org)). Format: `MAJOR.MINOR.PATCH` with optional pre-release and build metadata.

```yaml
version: 1.0.0 # Stable release
version: 2.0.0-beta.1 # Pre-release
version: 1.0.0+build.42 # Build metadata
```

### `description`

A single-line text describing the application. Displayed in the admin UI and metadata.

| Constraint | Description                                                   |
| ---------- | ------------------------------------------------------------- |
| Format     | Single line only. No line breaks (`\n`) allowed.              |
| Max length | 2000 characters maximum.                                      |
| Unicode    | Full Unicode support including emojis and special characters. |

## Configuration Formats

Sovrium accepts YAML, JSON, and TypeScript configuration. YAML is recommended for readability; JSON suits programmatic generation; TypeScript adds type safety via `@sovrium/types`. Large configs can be split across files with `$ref`. See [Configuration Files](/en/configuration-files) for the full guide.

```yaml
# YAML format (recommended)
name: my-app
version: 1.0.0
tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text }
```

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "tables": [
    {
      "id": 1,
      "name": "tasks",
      "fields": [{ "id": 1, "name": "title", "type": "single-line-text" }]
    }
  ]
}
```

## Cross-section validation

Root sections are validated _together_, not in isolation. Sovrium rejects a config before the server starts when, for example:

- a `user`/`created-by`/`updated-by` field exists but `auth` is not configured;
- a table or bucket permission names a role that is not declared;
- an attachment field references a `bucket` not present in `buckets`;
- a record automation trigger or action references a table that does not exist;
- an automation `$ref` action, AI agent reference, or form trigger names something undeclared.

Run [`sovrium validate`](/en/cli) to check these rules ahead of deployment.

## Related Pages

- [App Metadata](/en/app-metadata) — `name`, `version`, `description`, version ledger, drift detection.
- [Tables Overview](/en/tables-overview) — data models and 49 field types.
- [Pages Overview](/en/pages-overview) — ~80 component types for server-rendered pages.
- [Forms Overview](/en/forms-overview) — standalone forms and submissions.
- [Auth Overview](/en/auth-overview) — strategies, roles, and RBAC.
- [Automations Overview](/en/automations-overview) — triggers, actions, and connections.
- [AI Overview](/en/ai-overview) — agents and AI-native fields.
- [Buckets Overview](/en/buckets-overview) — file-storage containers.
- [Records Overview](/en/records-overview) — querying and mutating rows at runtime.
- [Theme](/en/theme) · [Responsive Design](/en/responsive-design) · [Animations](/en/animations) · [Languages](/en/languages).

# App Metadata

Three scalar root properties identify your application: `name`, `version`, and `description`. Only `name` is required. Together they anchor Sovrium's immutable version ledger and its schema-drift detection.

```yaml
name: '@acme/crm'
version: 2.1.0
description: 'A CRM workspace for managing contacts, deals, and tasks.'
```

## `name`

The app name follows npm package naming conventions. It is lowercase, URL-safe, and the only required property in the entire schema.

| Constraint | Description                                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| Pattern    | `^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$` — lowercase letters, digits, hyphens, dots, tildes. |
| Length     | 1–214 characters (including the `@scope/` prefix if scoped).                                                  |
| Leading    | Cannot start with a dot or underscore; no leading/trailing spaces.                                            |
| Scoped     | npm-style scoped names are allowed: `@scope/name` (e.g. `@acme/dashboard`).                                   |

```yaml
# Valid names
name: my-app
name: task-tracker-v2
name: '@acme/dashboard'
```

## `version`

A Semantic Versioning 2.0.0 string ([semver.org](https://semver.org)). Optional, but recommended — when present it feeds the version ledger described below.

| Rule           | Description                                                                   |
| -------------- | ----------------------------------------------------------------------------- |
| Format         | `MAJOR.MINOR.PATCH` (e.g. `1.0.0`). Each component is a non-negative integer. |
| No leading 0   | `01.0.0` is rejected — version components must not have leading zeros.        |
| Pre-release    | Optional hyphen suffix: `1.0.0-alpha`, `1.0.0-beta.1`, `2.0.0-rc.1`.          |
| Build metadata | Optional plus suffix: `1.0.0+build.123`, `1.0.0-alpha+001`.                   |

```yaml
version: 1.0.0 # Stable release
version: 2.0.0-beta.1 # Pre-release
version: 1.0.0+build.42 # Build metadata
```

## `description`

A single-line description shown in the admin UI and metadata.

| Constraint | Description                                               |
| ---------- | --------------------------------------------------------- |
| Format     | Single line only — line breaks (`\n`, `\r`) are rejected. |
| Max length | 2000 characters.                                          |
| Unicode    | Full Unicode support including emojis.                    |

```yaml
description: 'Full-featured e-commerce platform with cart, checkout & payment processing'
```

## Version history

Every Sovrium app keeps an **immutable version ledger** — an append-only audit log of schema snapshots. Each successful publish appends one row containing the encoded schema snapshot, a SHA-256 checksum of that snapshot, and the `source` that produced it. Restoring an older version copies its snapshot into a _new_ row; history is never mutated.

### The four transports

A schema change can arrive through one of four transports. Each transition appends exactly one ledger row, and the `source` column records which transport produced it.

| Transport       | `source` value | How a change arrives                                                               |
| --------------- | -------------- | ---------------------------------------------------------------------------------- |
| **Config file** | `config-file`  | `sovrium start app.yaml` at boot, or `sovrium reload` for a running server.        |
| **Env var**     | `env`          | The `APP_SCHEMA` environment variable (inline JSON/YAML or a remote URL snapshot). |
| **Admin API**   | `api`          | The admin HTTP API (`POST /api/admin/schema/draft/publish`).                       |
| **MCP**         | `mcp`          | An MCP schema-edit tool (`{app}_schema_draft_publish`).                            |

A fifth `source`, `restore`, marks rows created by restoring an earlier version. Checksums are self-contained (each row hashes its own snapshot, not a parent), which is what makes pruning interior rows safe.

## Schema drift detection

Because the live schema can be edited at runtime (via the admin API or MCP) while a `config-file` still sits on disk, the live app can **drift** away from its source file. Sovrium computes a drift posture from the ledger and exposes it so tooling can warn before overwriting work.

| Drift status        | Meaning                                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `in-sync`           | The active version came from a `config-file`/`env` transport — the running app matches its source.                      |
| `drifted-from-file` | The active version came from `api`/`mcp`/`restore` — the live app was edited at runtime and no longer matches the file. |
| `file-ahead`        | The on-disk file's normalized checksum changed — the source file is now ahead of the live app.                          |

:::callout
**`sovrium reload` respects drift.** Reloading a `config-file`-launched server first probes the live drift status. If the live app has `drifted-from-file`, the reload is refused unless you pass `--force` — preventing an accidental overwrite of runtime edits with stale file contents.
:::

## Draft staleness

Runtime editing happens against a **mutable draft** — a single working copy branched from the active version. The draft records the `baseVersion` it branched from, which doubles as both an optimistic-concurrency token on publish and a **staleness anchor**.

A draft becomes **stale** whenever `draft.baseVersion` no longer equals the active version number. This occurs when another admin publishes, or when a `config-file`/`env` reload moves the base underneath an open draft.

| Operation on a stale draft | Allowed?                                |
| -------------------------- | --------------------------------------- |
| Preview / validate / edit  | Yes                                     |
| Publish                    | No — blocked until the draft is rebased |

To clear staleness, **rebase** the draft: re-point its `baseVersion` to the active version, leaving the draft contents untouched. There is no field-level merge — the next publish is a whole-snapshot, last-writer-wins operation, consistent with Sovrium's snapshot-atomic schema system.

## Next steps

- [Schema Overview](/en/overview) — all root properties at a glance.
- [Configuration Files](/en/configuration-files) — how `config-file` and `env` transports load your app.
- [CLI Reference](/en/cli) — `sovrium reload` and drift handling.

# Theme

The `theme` property defines your design system through optional token categories. All tokens generate CSS custom properties and Tailwind CSS utility classes. Every category is optional — a minimal theme can be colors-only.

## Theme Properties

| Property       | Description                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `baseline`     | `'extend'` (default) keeps Sovrium's default design-system look; `'replace'` swaps it for a neutral floor.   |
| `colors`       | Named color tokens. Each generates `--color-{name}` and `bg-{name}`/`text-{name}`/`border-{name}` utilities. |
| `darkColors`   | Dark-mode color overrides, mirroring the `colors` structure.                                                 |
| `fonts`        | Typography for heading, body, and mono fonts.                                                                |
| `spacing`      | Named spacing tokens as Tailwind class strings.                                                              |
| `animations`   | Keyframe and motion design tokens. See [Animations](/en/animations).                                         |
| `breakpoints`  | Responsive breakpoints as pixel values. See [Responsive Design](/en/responsive-design).                      |
| `shadows`      | Named box-shadow tokens, each becoming a `shadow-{name}` utility.                                            |
| `borderRadius` | Named radius tokens, each becoming a `rounded-{name}` utility.                                               |
| `codeBlock`    | Syntax-highlighting theme for markdown fenced code blocks.                                                   |

## `colors`

Named color tokens as key-value pairs. Each becomes a CSS variable (`--color-{name}`) and Tailwind class (`bg-{name}`, `text-{name}`).

| Property   | Description                                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| `{name}`   | Token name (e.g., `primary`, `accent`). Used to generate CSS variable `--color-{name}` and Tailwind utilities. |
| CSS output | Generates `--color-{name}` CSS variable plus `bg-{name}`, `text-{name}`, `border-{name}` utility classes.      |

```yaml
theme:
  colors:
    primary: '#3b82f6'
    secondary: '#8b5cf6'
    accent: '#f59e0b'
    background: '#0a0e1a'
    text: '#e8ecf4'
    muted: '#64748b'
```

## `fonts`

Typography configuration for heading, body, and mono fonts. Supports family, fallback, weights, style, size, line height, letter spacing, transform, and url.

| Property        | Description                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `family`        | Font family name (e.g., `"Inter"`, `"Roboto"`). Maps to CSS `font-family`.                             |
| `fallback`      | Fallback font stack used when primary font is unavailable (e.g., `"system-ui, sans-serif"`).           |
| `weights`       | Array of numeric font weights to load (e.g., `[400, 600, 700]`). Optimizes download size.              |
| `style`         | Font style: `normal`, `italic`, or `oblique` (default: `normal`).                                      |
| `size`          | Base font size as CSS value (e.g., `"16px"`, `"1rem"`). Applied to body text.                          |
| `lineHeight`    | Line height multiplier or CSS value (e.g., `"1.5"`, `"1.2"`). Controls vertical spacing between lines. |
| `letterSpacing` | Letter spacing as CSS value (e.g., `"0.05em"`, `"-0.01em"`).                                           |
| `transform`     | Text transformation: `none`, `uppercase`, `lowercase`, or `capitalize`.                                |
| `url`           | Font file URL or Google Fonts URL. Injected as `<link>` in `<head>`.                                   |

```yaml
theme:
  fonts:
    heading:
      family: Inter
      weights: [600, 700]
      lineHeight: '1.2'
    body:
      family: Inter
      size: '16px'
      url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700'
```

:::callout
**Google Fonts.** Add a `url` to automatically load custom fonts. The URL is injected as a `<link>` tag in the page head.
:::

## `spacing`

Named spacing tokens as Tailwind class strings. Define container widths, section padding, gaps, and component spacing.

```yaml
theme:
  spacing:
    container: 'max-w-7xl mx-auto px-4'
    section: 'py-16 sm:py-20'
    card: 'p-6'
    gap: 'gap-8'
```

## `baseline` & dark mode

`baseline` controls whether Sovrium's prebuilt components extend the default look or start from a neutral floor.

| Value       | Behavior                                                                   |
| ----------- | -------------------------------------------------------------------------- |
| `'extend'`  | _(default)_ Components inherit Sovrium's v1 default design-system tokens.  |
| `'replace'` | Components drop the default look and start from a neutral, unstyled floor. |

`darkColors` mirrors the `colors` structure and supplies overrides applied in dark mode, so a single theme can ship both palettes.

```yaml
theme:
  baseline: extend
  colors:
    background: '#ffffff'
    text: '#0f172a'
  darkColors:
    background: '#0f172a'
    text: '#f8fafc'
```

## Shadows, Border Radius & Code Blocks

Additional design tokens for elevation, corner styling, and syntax highlighting.

### `shadows`

Named shadow tokens as CSS box-shadow values. Each becomes a `shadow-{name}` utility.

### `borderRadius`

Named border radius tokens as CSS values. Each becomes a `rounded-{name}` utility class.

### `codeBlock`

Selects the syntax-highlighting theme used for markdown fenced code blocks.

```yaml
theme:
  shadows:
    card: '0 4px 6px rgba(0, 0, 0, 0.1)'
    elevated: '0 10px 30px rgba(0, 0, 0, 0.2)'
  borderRadius:
    card: '0.75rem'
    button: '0.5rem'
```

## Responsive Breakpoints & Animations

`breakpoints` and `animations` each have a dedicated reference page:

- [Responsive Design](/en/responsive-design) — breakpoint pixel values and per-breakpoint overrides.
- [Animations](/en/animations) — keyframe and motion tokens.

```yaml
theme:
  breakpoints:
    sm: '640px'
    md: '768px'
    lg: '1024px'
```

:::callout
**Breakpoint values are pixel strings.** Each `breakpoints` value must match the `<number>px` format (e.g. `'768px'`) — bare numbers and non-pixel units are rejected by the schema.
:::

## Full Example

A complete theme configuration combining colors, fonts, spacing, and shadows.

```yaml
theme:
  colors:
    primary: '#6366f1'
    secondary: '#8b5cf6'
    accent: '#f59e0b'
    background: '#0f172a'
    surface: '#1e293b'
    text: '#f8fafc'
    muted: '#94a3b8'
  fonts:
    heading:
      family: Inter
      weights: [600, 700]
      url: 'https://fonts.googleapis.com/css2?family=Inter:wght@600;700&display=swap'
    body:
      family: Inter
      weights: [400, 500]
  spacing:
    container: 'max-w-6xl mx-auto px-4'
    section: 'py-16 sm:py-20'
```

![A CRM application rendered with custom theme colors, fonts, and spacing.](/docs/screenshots/app-page-en.png)

# Responsive Design

Sovrium's responsive system is built on **breakpoints** defined in `theme.breakpoints`. Each breakpoint becomes a min-width media query, and component props can be overridden per breakpoint for mobile-first layouts.

## `theme.breakpoints`

A map of breakpoint names to pixel values. Names are lowercase alphanumeric; values are pixel strings.

| Property | Description                                                                   |
| -------- | ----------------------------------------------------------------------------- |
| key      | Breakpoint name (lowercase alphanumeric, e.g. `sm`, `md`, `lg`, `xl`, `2xl`). |
| value    | Min-width threshold as a pixel string (e.g. `'640px'`, `'768px'`).            |

```yaml
theme:
  breakpoints:
    sm: '640px'
    md: '768px'
    lg: '1024px'
    xl: '1280px'
    '2xl': '1536px'
```

These map to the standard responsive tiers:

| Breakpoint | Min width | Typical target |
| ---------- | --------- | -------------- |
| `sm`       | `640px`   | Large mobile   |
| `md`       | `768px`   | Tablet         |
| `lg`       | `1024px`  | Laptop         |
| `xl`       | `1280px`  | Desktop        |
| `2xl`      | `1536px`  | Large desktop  |

:::callout
**Values must be pixel strings.** Each breakpoint value must match the `<number>px` format (e.g. `'768px'`). Non-pixel units (`rem`, `em`, `%`) are rejected by the schema.
:::

## Per-breakpoint overrides

Breakpoints power Tailwind's mobile-first utility variants. A base utility applies at all sizes; a prefixed variant (`md:`, `lg:`, …) applies from that breakpoint up. This is how a single component adapts across screen sizes.

```yaml
pages:
  - name: home
    path: /
    components:
      - type: container
        element: section
        props:
          # 1 column on mobile, 2 from md, 3 from lg
          className: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4'
        children:
          - { type: card, props: { className: 'p-4 md:p-6' } }
          - { type: card, props: { className: 'p-4 md:p-6' } }
          - { type: card, props: { className: 'p-4 md:p-6' } }
```

In the example above:

- `grid-cols-1` applies on all screens.
- `md:grid-cols-2` overrides it from `768px` up.
- `lg:grid-cols-3` overrides it again from `1024px` up.
- `p-4` is the base padding; `md:p-6` increases it from the `md` breakpoint.

:::callout
**Mobile-first.** Always declare the smallest layout as the base (unprefixed) utility, then layer larger-screen overrides with breakpoint prefixes. This guarantees a sensible default on the smallest viewport before any media query matches.
:::

## Custom breakpoints

Define your own names alongside or instead of the standard tiers. A custom breakpoint generates a matching utility prefix.

```yaml
theme:
  breakpoints:
    phone: '480px'
    tablet: '834px'
    wide: '1440px'
```

```yaml
props:
  className: 'flex-col tablet:flex-row wide:gap-12'
```

## Next steps

- [Theme](/en/theme) — the full theme token reference.
- [Animations](/en/animations) — keyframe and motion tokens.
- [Pages Overview](/en/pages-overview) — component props and the `className` prop.

# Animations

The `theme.animations` block defines motion design tokens — named animations, reusable durations and easing curves, and `@keyframes` definitions. Tokens generate CSS that any component can reference through its `className`.

## `theme.animations`

`animations` is a map keyed by token name (alphanumeric, must start with a letter). Each value is one of four shapes, giving you a spectrum from a one-line toggle to a full keyframe definition.

| Value shape   | Use it for                                                                        |
| ------------- | --------------------------------------------------------------------------------- |
| Boolean       | Enable or disable a named animation: `fadeIn: true`.                              |
| String        | A raw CSS animation value or a utility class name: `slideUp: 'animate-slide-up'`. |
| Config object | Detailed control: `enabled`, `duration`, `easing`, `delay`, `keyframes`.          |
| Token map     | A nested map of named `duration`, `easing`, or `keyframes` design tokens.         |

### Boolean and string forms

The quickest way to switch a built-in animation on, or to alias a class name.

```yaml
theme:
  animations:
    fadeIn: true
    slideUp: 'animate-slide-up'
```

### Config-object form

A detailed animation with timing control.

| Property    | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `enabled`   | Boolean. Whether the animation is active.                               |
| `duration`  | CSS duration (e.g. `'300ms'`, `'0.5s'`).                                |
| `easing`    | CSS easing/timing function (e.g. `'ease-in-out'`, `cubic-bezier(...)`). |
| `delay`     | CSS duration to wait before starting (e.g. `'0ms'`).                    |
| `keyframes` | Inline keyframe definition map.                                         |

```yaml
theme:
  animations:
    modalOpen:
      enabled: true
      duration: '300ms'
      easing: 'ease-in-out'
      delay: '0ms'
```

### Nested token maps

For a reusable motion system, declare `duration`, `easing`, and `keyframes` as named token maps. Other animations and component classes can then reference these tokens instead of repeating raw values.

```yaml
theme:
  animations:
    duration:
      fast: '200ms'
      normal: '300ms'
      slow: '500ms'
    easing:
      smooth: 'cubic-bezier(0.4, 0, 0.2, 1)'
      bounce: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)'
    keyframes:
      fadeIn:
        from: { opacity: '0' }
        to: { opacity: '1' }
      colorPulse:
        '0%': { backgroundColor: '$colors.primary' }
        '50%': { backgroundColor: '$colors.accent' }
        '100%': { backgroundColor: '$colors.primary' }
```

| Token map   | Key rule                            | Value                                             |
| ----------- | ----------------------------------- | ------------------------------------------------- |
| `duration`  | Alphanumeric, starts with a letter. | CSS duration string.                              |
| `easing`    | Alphanumeric, starts with a letter. | CSS easing/timing function.                       |
| `keyframes` | Alphanumeric, starts with a letter. | A keyframe map (`from`/`to` or percentage stops). |

:::callout
**Reference theme colors in keyframes.** Keyframe values may reference other theme tokens with the `$colors.<name>` syntax (e.g. `backgroundColor: '$colors.primary'`), keeping motion in sync with your palette.
:::

## Ecoconception note

Motion is a footprint concern. Prefer short durations and avoid long-running infinite animations on first paint. Sovrium's eco posture is operator-controlled via environment variables, not theme schema — see the [Environment Variables](/en/env-vars) reference for the `ECO_*` controls that govern client behavior.

## Next steps

- [Theme](/en/theme) — the full theme token reference.
- [Responsive Design](/en/responsive-design) — breakpoints and per-breakpoint overrides.
- [Pages Overview](/en/pages-overview) — applying animation classes to components.

# Languages

Multi-language support with translation keys, browser language detection, and automatic URL-based language routing (`/en/...`, `/fr/...`). Reference translations in pages using the `$t:` prefix.

## Defining Languages

Set a default language and list supported languages with code, locale, label, and text direction.

| Property           | Description                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `default`          | ISO 639-1 code for the default language (e.g., `"en"`). Used when no language is detected.         |
| `supported`        | Array of language entry objects. Each defines a supported language.                                |
| `fallback`         | Fallback language code (2 letters). Used when a translation key is missing in the active language. |
| `detectBrowser`    | Boolean. When `true`, auto-detects the user's browser language on first visit.                     |
| `persistSelection` | Boolean. When `true`, remembers the user's language choice across sessions.                        |

```yaml
languages:
  default: en
  supported:
    - code: en
      locale: en-US
      label: English
      direction: ltr
    - code: fr
      locale: fr-FR
      label: 'Français'
      direction: ltr
    - code: ar
      locale: ar-SA
      label: 'العربية'
      direction: rtl
```

## Language Entry Properties

Each entry in the `supported` array describes a language with these properties.

| Property    | Description                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `code`      | ISO 639-1 language code (e.g., `"en"`, `"fr"`, `"ar"`). Used in URL routing (`/en/`, `/fr/`).                |
| `locale`    | Full locale identifier (e.g., `"en-US"`, `"fr-FR"`, `"ar-SA"`). Used for number/date formatting.             |
| `label`     | Human-readable language name shown in language switchers (e.g., `"English"`, `"Français"`).                  |
| `direction` | Text direction: `"ltr"` (left-to-right) for most languages, `"rtl"` (right-to-left) for Arabic, Hebrew, etc. |
| `flag`      | Flag emoji or icon path displayed in language switchers.                                                     |

:::callout
**RTL Support.** Set `direction: rtl` for right-to-left languages like Arabic or Hebrew. Sovrium automatically mirrors the page layout, aligns text to the right, and applies the `dir="rtl"` attribute to the HTML root.
:::

## Translation Keys

Define key-value pairs for each language. Keys use dot notation for organization.

```yaml
languages:
  translations:
    en:
      hero.title: 'Welcome to My App'
      hero.description: 'Build faster with Sovrium'
      nav.home: 'Home'
      nav.about: 'About'
    fr:
      hero.title: 'Bienvenue sur Mon App'
      hero.description: 'Construisez plus vite avec Sovrium'
      nav.home: 'Accueil'
      nav.about: 'À propos'
```

## Using Translations

Reference translations in any content or prop value with the `$t:` prefix.

```yaml
# Reference translations with $t: prefix
pages:
  - name: home
    path: /
    sections:
      - type: section
        children:
          - type: h1
            content: '$t:hero.title'
          - type: paragraph
            content: '$t:hero.description'
```

:::callout
**`$t:` Translation Syntax.** Use `$t:key.path` in any page content or prop value to reference a translation. Example: `$t:hero.title` resolves to `"Welcome"` in English and `"Bienvenue"` in French.
:::

![English version of the app](/docs/screenshots/app-translation-en.png)

![French version of the app](/docs/screenshots/app-translation-fr.png)

## Adding a New Language

Follow these steps to add a new language to your application.

1. **Add language entry** — Add a new item to the `supported` array with `code`, `locale`, `label`, and `direction`.
2. **Add translations** — Create a new `translations` section for the language code with all required keys.
3. **Test the language** — Visit `/[lang-code]/` in your browser to verify the new language renders correctly.

# Tables Overview

Tables define your data models. Each table is a distinct entity (users, products, orders) whose `fields` declare the columns that records can store. Tables are the foundation of a Sovrium app: pages render their records, forms write to them, automations react to their changes, and the REST/MCP APIs expose them.

A table has at minimum an `id`, a `name`, and a `fields` array. Everything else — primary keys, indexes, constraints, views, permissions, webhooks, and AI exposure — is optional and layered on top.

```yaml
tables:
  - id: 1
    name: Contacts
    fields:
      - { id: 1, name: email, type: email, required: true, unique: true }
      - { id: 2, name: full_name, type: single-line-text, required: true }
      - { id: 3, name: created_at, type: created-at, indexed: true }
```

## Table Properties

Each entry in the `tables` array accepts the following properties.

| Property              | Description                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | Unique integer identifier for the table. Auto-generated when omitted.                                                                        |
| `name`                | User-friendly table name. Can contain spaces and mixed case; sanitized for database use (lowercase with underscores). Maximum 63 characters. |
| `fields`              | Array of field definitions. At least one field is required. Field names and IDs must be unique within the table.                             |
| `primaryKey`          | Primary key configuration. Defaults to an auto-generated `id` column. See [Indexes & Constraints](/en/table-indexes-constraints).            |
| `unique`              | Array of top-level unique-constraint declarations. Each entry covers one or more fields (e.g. `[{ fields: [slug] }]`).                       |
| `indexes`             | Array of index definitions for query performance and uniqueness enforcement.                                                                 |
| `uniqueConstraints`   | _(via `unique`)_ Multi-field uniqueness. Single-field entries fold into `field.unique`; composite entries become unique btree indexes.       |
| `foreignKeys`         | Composite (multi-column) foreign key definitions. Single-column foreign keys are created automatically from `relationship` fields.           |
| `constraints`         | Array of CHECK constraints with SQL expressions for cross-field data validation.                                                             |
| `views`               | Saved views with pre-configured filters, sorting, grouping, and visible fields. See [Views](/en/table-views).                                |
| `permissions`         | RBAC permissions controlling create, read, update, delete, restore, comment, and per-field access. See [Permissions](/en/table-permissions). |
| `rowLevelPermissions` | Server-side `when` predicates per CRUD operation for defense-in-depth row scoping.                                                           |
| `webhooks`            | Outgoing webhooks fired on record create/update/delete events. See [Webhooks](/en/table-webhooks).                                           |
| `comments`            | Comment-system configuration (guest commenting, moderation, threading).                                                                      |
| `aiAccess`            | Declares the table eligible for exposure via Sovrium's MCP server so AI assistants can list/read/write records (subject to RBAC).            |
| `allowDestructive`    | Boolean. When `true`, allows destructive schema migrations (column drops, type changes). Defaults to `false`.                                |
| `allowForceDelete`    | Boolean. Per-table opt-in permitting hard-delete via the admin dashboard (GDPR erasure). Defaults to `false`. See note below.                |

:::callout
**Soft-delete by default.** Deleting a record sets `deleted_at`/`deleted_by` and leaves the row recoverable via `/restore`. Set `allowForceDelete: true` only when a table needs irreversible hard-delete (e.g. GDPR right-to-erasure on an HR table). Financial ledgers and audit-adjacent tables should leave it at the `false` default — the admin force-delete endpoint returns `404` when force-delete is not allowed.
:::

## Base Field Properties

Every field — regardless of type — extends a common base. These properties are available on all 49 field types.

| Property       | Description                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Unique integer identifier for the field within the table. Auto-generated sequentially when omitted.                                             |
| `name`         | Column identifier. Must start with a letter and contain only lowercase letters, digits, and underscores (`^[a-z][a-z0-9_]*`). Maximum 63 chars. |
| `type`         | One of the 49 available field types (e.g. `single-line-text`, `integer`, `relationship`). See [Field Types](/en/field-types-overview).          |
| `required`     | Boolean. When `true`, the field must have a value for every record.                                                                             |
| `unique`       | Boolean. When `true`, no two records can share the same value.                                                                                  |
| `indexed`      | Boolean. When `true`, creates a database index on this field for faster queries.                                                                |
| `searchWeight` | PostgreSQL full-text-search relevance weight: `A` (highest) to `D` (lowest). Only effective when `indexed: true` and the data source uses FTS.  |
| `storage`      | Storage configuration object. `storage.compression` (boolean) enables compression for large text or attachment values.                          |

:::callout
**`default` is type-specific, not a base property.** Most value-carrying fields (text, numeric, selection, date, color, …) expose a `default` whose value type matches the field. System fields (`created-at`, relational, computed, AI) do not. Each field-type page lists whether `default` is available.
:::

### Example: a richer table

```yaml
tables:
  - id: 2
    name: Products
    fields:
      - { id: 1, name: sku, type: single-line-text, required: true, unique: true }
      - {
          id: 2,
          name: title,
          type: single-line-text,
          required: true,
          searchWeight: A,
          indexed: true,
        }
      - { id: 3, name: description, type: long-text, searchWeight: B }
      - { id: 4, name: price, type: currency, required: true, currency: USD }
      - { id: 5, name: in_stock, type: checkbox, default: true }
    primaryKey: { type: auto-increment, field: id }
    indexes:
      - { name: idx_products_sku, fields: [sku], unique: true }
    permissions:
      read: all
      create: [admin, editor]
      update: [admin, editor]
      delete: [admin]
```

## Related Pages

- [Field Types Overview](/en/field-types-overview) — all 49 field types by category.
- [Permissions](/en/table-permissions) — RBAC and per-field access control.
- [Indexes & Constraints](/en/table-indexes-constraints) — primary keys, indexes, CHECK constraints.
- [Relationships](/en/table-relationships) — linking tables together.
- [Views](/en/table-views) — saved filters, sorts, and grouping.
- [Validation](/en/table-validation) — field- and table-level validation rules.
- [Webhooks](/en/table-webhooks) — outgoing HTTP on record events.

# Field Types

Sovrium provides **49 field types**, organized into 9 categories. Every field shares the [base field properties](/en/tables-overview#base-field-properties) (`id`, `name`, `type`, `required`, `unique`, `indexed`, `searchWeight`, `storage`) and adds type-specific properties on top.

:::callout
**Counting note.** This documentation describes **49** field types, derived directly from the schema's field union (`FieldUnionSchema`, excluding the internal `unknown` catch-all). The product feature overview (`FEATURES.md`) currently states **52** — that figure is drift and should not be propagated. The authoritative breakdown is the per-category table below, which sums to exactly 49.
:::

## The 9 Categories

| Category                                    | Count  | Field types                                                                                          |
| ------------------------------------------- | :----: | ---------------------------------------------------------------------------------------------------- |
| [Text](/en/text-fields)                     |   6    | `single-line-text`, `long-text`, `rich-text`, `email`, `url`, `phone-number`                         |
| [Numeric](/en/number-fields)                |   6    | `integer`, `decimal`, `currency`, `percentage`, `rating`, `progress`                                 |
| [Date & Time](/en/datetime-fields)          |   7    | `date`, `datetime`, `time`, `duration`, `created-at`, `updated-at`, `deleted-at`                     |
| [Selection](/en/selection-fields)           |   4    | `checkbox`, `single-select`, `multi-select`, `status`                                                |
| [Relational](/en/relational-fields)         |   3    | `relationship`, `lookup`, `rollup`                                                                   |
| [User & Audit](/en/user-audit-fields)       |   4    | `user`, `created-by`, `updated-by`, `deleted-by`                                                     |
| [Attachment / Media](/en/attachment-fields) |   3    | `single-attachment`, `multiple-attachments`, `barcode`                                               |
| [Advanced](/en/advanced-fields)             |   9    | `formula`, `count`, `autonumber`, `button`, `json`, `array`, `color`, `code`, `geolocation`          |
| [AI](/en/ai-fields)                         |   7    | `ai-generate`, `ai-summary`, `ai-categorize`, `ai-extract`, `ai-sentiment`, `ai-tag`, `ai-translate` |
| **Total**                                   | **49** |                                                                                                      |

## Quick Summary

| Type                   | Category    | What it stores                                       |
| ---------------------- | ----------- | ---------------------------------------------------- |
| `single-line-text`     | Text        | Short single-line text (names, titles, labels).      |
| `long-text`            | Text        | Multi-line plain text (notes, descriptions).         |
| `rich-text`            | Text        | Formatted HTML via a WYSIWYG editor.                 |
| `email`                | Text        | Email address with RFC 5322 validation.              |
| `url`                  | Text        | Web address with URL validation.                     |
| `phone-number`         | Text        | Phone number stored as text (international formats). |
| `integer`              | Numeric     | Whole numbers with optional min/max.                 |
| `decimal`              | Numeric     | Fixed-precision decimals (1–10 places).              |
| `currency`             | Numeric     | Monetary values with ISO 4217 code and formatting.   |
| `percentage`           | Numeric     | Percentage values, displayed with `%`.               |
| `rating`               | Numeric     | Star/icon rating (`max` 1–10).                       |
| `progress`             | Numeric     | Progress bar 0–100 with optional color.              |
| `date`                 | Date & Time | Calendar date, optional time.                        |
| `datetime`             | Date & Time | Date plus time, timezone-aware.                      |
| `time`                 | Date & Time | Time-of-day without a date.                          |
| `duration`             | Date & Time | Elapsed time / work hours.                           |
| `created-at`           | Date & Time | System-set creation timestamp.                       |
| `updated-at`           | Date & Time | System-updated modification timestamp.               |
| `deleted-at`           | Date & Time | Soft-delete timestamp (NULL = active).               |
| `checkbox`             | Selection   | Boolean true/false.                                  |
| `single-select`        | Selection   | One option from a list.                              |
| `multi-select`         | Selection   | Multiple options from a list.                        |
| `status`               | Selection   | Colored workflow states.                             |
| `relationship`         | Relational  | Foreign-key link to another table.                   |
| `lookup`               | Relational  | A field read from a related record.                  |
| `rollup`               | Relational  | Aggregation over related records.                    |
| `user`                 | User/Audit  | Reference to a user (single or multiple).            |
| `created-by`           | User/Audit  | System-set creating user.                            |
| `updated-by`           | User/Audit  | System-set last-modifying user.                      |
| `deleted-by`           | User/Audit  | System-set deleting user.                            |
| `single-attachment`    | Attachment  | One uploaded file.                                   |
| `multiple-attachments` | Attachment  | Many uploaded files.                                 |
| `barcode`              | Attachment  | Barcode value (product identification).              |
| `formula`              | Advanced    | Computed value from a formula expression.            |
| `count`                | Advanced    | Count of related records.                            |
| `autonumber`           | Advanced    | Auto-incrementing number with prefix/padding.        |
| `button`               | Advanced    | Interactive button triggering a URL or automation.   |
| `json`                 | Advanced    | Structured JSON data.                                |
| `array`                | Advanced    | Array of typed values.                               |
| `color`                | Advanced    | Hex color value.                                     |
| `code`                 | Advanced    | Source code with syntax highlighting.                |
| `geolocation`          | Advanced    | Latitude/longitude coordinates.                      |
| `ai-generate`          | AI          | AI-generated text from a prompt.                     |
| `ai-summary`           | AI          | AI summary of source fields.                         |
| `ai-categorize`        | AI          | AI single-category classification.                   |
| `ai-extract`           | AI          | AI structured extraction (JSON Schema).              |
| `ai-sentiment`         | AI          | AI sentiment analysis.                               |
| `ai-tag`               | AI          | AI multi-tag assignment from an allow-list.          |
| `ai-translate`         | AI          | AI translation to a target language.                 |

## Category Pages

- [Text Fields](/en/text-fields)
- [Number Fields](/en/number-fields)
- [Date & Time Fields](/en/datetime-fields)
- [Selection Fields](/en/selection-fields)
- [Relational Fields](/en/relational-fields)
- [User & Audit Fields](/en/user-audit-fields)
- [Attachment Fields](/en/attachment-fields)
- [Advanced Fields](/en/advanced-fields)
- [AI Fields](/en/ai-fields)

# Text Fields

Six field types store textual content, from short labels to formatted rich text and validated strings. All share the [base field properties](/en/tables-overview#base-field-properties).

| Type               | Stores                                                           |
| ------------------ | ---------------------------------------------------------------- |
| `single-line-text` | Short, single-line text (names, titles, labels).                 |
| `long-text`        | Multi-line plain text (descriptions, notes, comments).           |
| `rich-text`        | Formatted HTML rendered with a WYSIWYG editor.                   |
| `email`            | Email address validated against RFC 5322.                        |
| `url`              | Web address validated as an absolute URL.                        |
| `phone-number`     | Phone number stored as text; preserves international formatting. |

## `single-line-text`

Short text limited to a single line. Stored as-is without formatting.

| Property  | Description                             |
| --------- | --------------------------------------- |
| `default` | Default string assigned to new records. |

```yaml
- { id: 1, name: title, type: single-line-text, required: true, indexed: true, default: Untitled }
```

## `long-text`

Multi-line plain text. Supports line breaks; no rich formatting (no bold/italics).

| Property  | Description                             |
| --------- | --------------------------------------- |
| `default` | Default string assigned to new records. |

```yaml
- { id: 2, name: description, type: long-text, default: 'Enter description here...' }
```

## `rich-text`

Formatted text with bold, italic, links, lists, headings, and more. Rendered with a Tiptap WYSIWYG editor and stored as HTML.

| Property         | Description                                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxLength`      | Maximum length in characters (integer ≥ 1). Validates on input.                                                                                               |
| `fullTextSearch` | Boolean. Enables full-text-search indexing for this field.                                                                                                    |
| `toolbar`        | Array of allowed toolbar actions (e.g. `bold`, `italic`, `link`, `heading`, `list`, `image`, `code-block`, `table`). When omitted, all actions are available. |
| `placeholder`    | Placeholder text shown when the editor is empty.                                                                                                              |
| `collaborative`  | Boolean. Enables real-time collaborative editing (Yjs).                                                                                                       |

```yaml
- id: 3
  name: article_content
  type: rich-text
  required: true
  maxLength: 10000
  toolbar: [bold, italic, link, heading, list]
  placeholder: 'Write your article...'
```

## `email`

Text field that validates email addresses (RFC 5322). Commonly `unique: true` and `indexed: true` for authentication and lookups.

| Property  | Description                                    |
| --------- | ---------------------------------------------- |
| `default` | Default email address assigned to new records. |

```yaml
- { id: 4, name: email, type: email, required: true, unique: true, indexed: true }
```

## `url`

Text field that validates web addresses. Supports multiple protocols (`http://`, `https://`, `ftp://`, …).

| Property  | Description                          |
| --------- | ------------------------------------ |
| `default` | Default URL assigned to new records. |

```yaml
- { id: 5, name: website, type: url, indexed: true, default: 'https://example.com' }
```

## `phone-number`

Text field for phone numbers. Numbers are stored exactly as entered (spaces, dashes, parentheses preserved); no automatic formatting is applied, allowing any international format.

| Property  | Description                                   |
| --------- | --------------------------------------------- |
| `default` | Default phone number assigned to new records. |

```yaml
- { id: 6, name: mobile_phone, type: phone-number, unique: true, default: '+1 (555) 000-0000' }
```

:::callout
**Full-text search & relevance.** Set `indexed: true` plus `searchWeight` (`A`–`D`) on text fields whose data source uses full-text search, to control relevance ranking. `rich-text` also exposes `fullTextSearch` to opt that column into the search index.
:::

# Number Fields

Six field types store numbers, currencies, percentages, ratings, and progress indicators. All share the [base field properties](/en/tables-overview#base-field-properties).

| Type         | Stores                                             |
| ------------ | -------------------------------------------------- |
| `integer`    | Whole numbers with optional min/max range.         |
| `decimal`    | Fixed-precision decimals (1–10 decimal places).    |
| `currency`   | Monetary values with ISO 4217 code and formatting. |
| `percentage` | Percentage values, displayed with `%`.             |
| `rating`     | Star/icon rating with a configurable maximum.      |
| `progress`   | A 0–100 progress bar with an optional color.       |

## `integer`

Whole numbers without decimal places. Optimized for performance.

| Property  | Description                        |
| --------- | ---------------------------------- |
| `min`     | Minimum allowed value (inclusive). |
| `max`     | Maximum allowed value (inclusive). |
| `default` | Default integer for new records.   |

```yaml
- { id: 1, name: quantity, type: integer, required: true, min: 0, max: 1000, default: 1 }
```

## `decimal`

Numbers with decimal places, stored with exact `DECIMAL` precision.

| Property    | Description                                         |
| ----------- | --------------------------------------------------- |
| `precision` | Number of decimal places. Integer from **1 to 10**. |
| `min`       | Minimum allowed value (inclusive).                  |
| `max`       | Maximum allowed value (inclusive).                  |
| `default`   | Default decimal for new records.                    |

```yaml
- { id: 2, name: weight, type: decimal, precision: 2, min: 0.01, max: 999.99, default: 1.0 }
```

## `currency`

Monetary values with locale-aware display formatting.

| Property             | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `currency`           | **Required.** ISO 4217 three-letter code (e.g. `USD`, `EUR`, `GBP`, `JPY`).         |
| `precision`          | Number of decimal places. Integer from **0 to 10** (default 2 for most currencies). |
| `min`                | Minimum allowed value (inclusive).                                                  |
| `max`                | Maximum allowed value (inclusive).                                                  |
| `symbolPosition`     | Currency-symbol placement: `before` ($100) or `after` (100€).                       |
| `negativeFormat`     | Negative-value display: `minus` (-100) or `parentheses` ((100)).                    |
| `thousandsSeparator` | Thousands grouping character: `comma`, `period`, `space`, or `none`.                |

```yaml
- id: 3
  name: price
  type: currency
  required: true
  currency: USD
  precision: 2
  symbolPosition: before
  negativeFormat: parentheses
  thousandsSeparator: comma
```

:::callout
**Corrected from earlier docs.** `currency` uses `thousandsSeparator` — an enum (`comma | period | space | none`), **not** a boolean. `negativeFormat` accepts `minus` or `parentheses` (there is no `red` option), and `precision` ranges **0–10**.
:::

## `percentage`

Percentage values (typically 0–100), displayed with a `%` symbol.

| Property    | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `precision` | Number of decimal places. Integer from **0 to 10** (default 0). |
| `min`       | Minimum allowed value (inclusive, typically 0).                 |
| `max`       | Maximum allowed value (inclusive, typically 100).               |
| `default`   | Default percentage for new records.                             |

```yaml
- { id: 4, name: discount_rate, type: percentage, precision: 1, min: 0, max: 100, default: 10.0 }
```

## `rating`

A rating value rendered as stars or other indicators.

| Property  | Description                                                 |
| --------- | ----------------------------------------------------------- |
| `max`     | Maximum rating value. Integer from **1 to 10** (default 5). |
| `style`   | Visual style for the rating (e.g. `stars`).                 |
| `default` | Default rating value for new records.                       |

```yaml
- { id: 5, name: product_rating, type: rating, max: 5, style: stars }
```

:::callout
**Corrected from earlier docs.** The rating field uses `max` and `style` — **not** `ratingMax` / `ratingStyle`.
:::

## `progress`

Displays a 0–100 value as a progress bar. Used to track completion toward a goal.

| Property  | Description                                                 |
| --------- | ----------------------------------------------------------- |
| `color`   | Progress-bar color as a 6-digit hex value (e.g. `#10B981`). |
| `default` | Default progress value (0–100) for new records.             |

```yaml
- { id: 6, name: task_completion, type: progress, color: '#10B981', default: 0 }
```

:::callout
**Corrected from earlier docs.** The progress field uses `color` (a hex string) — **not** `progressColor`.
:::

# Date & Time Fields

Seven field types store dates, times, durations, and system-managed audit timestamps. All share the [base field properties](/en/tables-overview#base-field-properties).

| Type         | Stores                                                    |
| ------------ | --------------------------------------------------------- |
| `date`       | A calendar date, with optional time component.            |
| `datetime`   | A date plus time, timezone-aware.                         |
| `time`       | A time of day without a date.                             |
| `duration`   | An elapsed-time / work-hours value (stored in seconds).   |
| `created-at` | System-set timestamp captured when a record is created.   |
| `updated-at` | System-updated timestamp refreshed on every modification. |
| `deleted-at` | Soft-delete timestamp; NULL means the record is active.   |

## `date`

Calendar dates, optionally including a time component.

| Property      | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| `format`      | Free-form display format string (e.g. `YYYY-MM-DD`, `MM/DD/YYYY`, `DD-MM-YYYY`). |
| `dateFormat`  | Display preset: `US`, `European`, or `ISO`.                                      |
| `timeFormat`  | Time display: `12-hour` or `24-hour`.                                            |
| `includeTime` | Boolean. When `true`, the date field also captures a time.                       |
| `timezone`    | IANA timezone identifier (e.g. `UTC`, `America/New_York`, `Europe/London`).      |
| `timeZone`    | Timezone setting accepting a specific zone or `local` (browser timezone).        |
| `default`     | Default date value for new records.                                              |

```yaml
- { id: 1, name: due_date, type: date, dateFormat: ISO, includeTime: false }
```

## `datetime`

Date plus time. Timezone-aware for accurate cross-region scheduling.

| Property     | Description                                                                      |
| ------------ | -------------------------------------------------------------------------------- |
| `format`     | Free-form display format string (e.g. `YYYY-MM-DD HH:mm`, `MM/DD/YYYY hh:mm A`). |
| `dateFormat` | Display preset: `US`, `European`, or `ISO`.                                      |
| `timeFormat` | Time display: `12-hour` or `24-hour`.                                            |
| `timezone`   | IANA timezone identifier.                                                        |
| `timeZone`   | Timezone setting accepting a specific zone or `local`.                           |
| `default`    | Default datetime value for new records.                                          |

```yaml
- { id: 2, name: published_at, type: datetime, timeFormat: 24-hour, timezone: UTC }
```

## `time`

Time-only values without a date. Used for schedules, opening hours, and time slots.

| Property     | Description                                          |
| ------------ | ---------------------------------------------------- |
| `timeFormat` | Time display: `12-hour` or `24-hour`.                |
| `default`    | Default time in `HH:MM:SS` format (e.g. `09:00:00`). |

```yaml
- { id: 3, name: start_time, type: time, required: true, timeFormat: 24-hour }
```

## `duration`

Elapsed time or work hours, stored as a number of seconds.

| Property        | Description                                              |
| --------------- | -------------------------------------------------------- |
| `format`        | Free-form display format string for the duration.        |
| `displayFormat` | Display preset: `h:mm`, `h:mm:ss`, or `decimal`.         |
| `default`       | Default duration value, in **seconds**, for new records. |

```yaml
- { id: 4, name: work_hours, type: duration, displayFormat: 'h:mm' }
```

## System Audit Timestamps

`created-at`, `updated-at`, and `deleted-at` are **system-managed** — their values are set automatically and cannot be edited manually. They take no type-specific properties beyond the base field properties (commonly `indexed: true`).

| Type         | Behavior                                                                                       |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `created-at` | Captured once when the record is created. Read-only.                                           |
| `updated-at` | Refreshed automatically whenever the record is modified. Read-only.                            |
| `deleted-at` | Set when the record is soft-deleted. `NULL` indicates an active record; a timestamp = deleted. |

```yaml
fields:
  - { id: 5, name: created_at, type: created-at, indexed: true }
  - { id: 6, name: updated_at, type: updated-at, indexed: true }
  - { id: 7, name: deleted_at, type: deleted-at, indexed: true }
```

:::callout
**Soft-delete lifecycle.** Adding a `deleted-at` field enables Sovrium's soft-delete-by-default behavior: deleting a record sets the timestamp instead of removing the row, and `/restore` clears it. Pair with [`deleted-by`](/en/user-audit-fields) to record who performed the deletion.
:::

# Selection Fields

Four field types let records choose from predefined options. All share the [base field properties](/en/tables-overview#base-field-properties).

| Type            | Stores                                                              |
| --------------- | ------------------------------------------------------------------- |
| `checkbox`      | A boolean true/false value.                                         |
| `single-select` | One option chosen from a predefined list.                           |
| `multi-select`  | Multiple options chosen from a predefined list.                     |
| `status`        | A colored workflow state from a list of `{ value, color }` options. |

## `checkbox`

Boolean field, typically rendered as a checkbox.

| Property  | Description                               |
| --------- | ----------------------------------------- |
| `default` | Default boolean value (`true` / `false`). |

```yaml
- { id: 1, name: is_active, type: checkbox, required: true, default: false }
```

## `single-select`

A single choice from a list of string options.

| Property     | Description                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `options`    | Array of strings defining the available choices.                                                                                                                   |
| `default`    | Default selected option (a string).                                                                                                                                |
| `conditions` | Optional behavioral conditions: `[{ when: <option>, then: { …property changes } }]` — apply property changes (e.g. `readOnly`) when a specific option is selected. |

```yaml
- id: 2
  name: category
  type: single-select
  options: [Electronics, Clothing, Food]
  default: Electronics
```

## `multi-select`

Multiple choices from a list of string options.

| Property        | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `options`       | Array of strings defining the available choices.                         |
| `maxSelections` | Maximum number of choices (integer ≥ 1; cannot exceed `options.length`). |
| `default`       | Default selections (an array of strings).                                |

```yaml
- id: 3
  name: tags
  type: multi-select
  options: [Urgent, Important, Review]
  maxSelections: 3
```

## `status`

A colored workflow state. Each option is an object with a `value` and a `color`, ideal for Kanban columns and pipeline stages.

| Property  | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `options` | Array of `{ value, color }` objects defining the colored states.   |
| `default` | Default status value (a string matching one of the option values). |

```yaml
- id: 4
  name: status
  type: status
  options:
    - { value: todo, color: '#94A3B8' }
    - { value: in_progress, color: '#3B82F6' }
    - { value: done, color: '#10B981' }
  default: todo
```

:::callout
**Single-select vs status.** Use `single-select` for plain enumerated values (string `options`). Use `status` when each state needs a color for visual workflow displays such as Kanban boards.
:::

# Relational Fields

Three field types connect tables and derive data from those connections. They form a chain: a `relationship` defines the link, then `lookup` and `rollup` read or aggregate data through it. (The related [`count`](/en/advanced-fields#count) field — categorized as Advanced — also traverses a relationship.)

| Type           | Purpose                                                               |
| -------------- | --------------------------------------------------------------------- |
| `relationship` | Creates a foreign-key link to another table. Foundation for the rest. |
| `lookup`       | Reads a single field value from a related record. Read-only.          |
| `rollup`       | Aggregates a field across many related records (sum, avg, …).         |

## `relationship`

Creates a foreign-key link to another table.

| Property          | Description                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `relatedTable`    | **Required.** Name of the target table to link to. Must match an existing table.                                   |
| `relationType`    | Cardinality. Defaults to `many-to-one`. Common values: `one-to-one`, `many-to-one`, `one-to-many`, `many-to-many`. |
| `foreignKey`      | Custom foreign-key column name (used for `one-to-many`). Auto-generated when omitted.                              |
| `displayField`    | Field from the related table shown in the UI (e.g. `name` instead of the raw id).                                  |
| `onDelete`        | Referential action when the related row is deleted (e.g. `cascade`, `set-null`, `restrict`, `no-action`).          |
| `onUpdate`        | Referential action when the related primary key is updated.                                                        |
| `reciprocalField` | Field name for the inverse (bidirectional) link on the related table.                                              |
| `allowMultiple`   | Boolean. Allows linking to multiple records (defaults to `true` for `many-to-many`).                               |
| `limitToView`     | Restricts selectable related records to those visible in a named view of the related table.                        |

```yaml
- id: 1
  name: customer
  type: relationship
  relatedTable: Customers
  relationType: many-to-one
  displayField: full_name
  onDelete: set-null
  reciprocalField: orders
```

## `lookup`

Displays a field value pulled from a related record via an existing relationship. Read-only and auto-updated.

| Property            | Description                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `relationshipField` | **Required.** Name of the relationship field to traverse (must exist in the same table). |
| `relatedField`      | **Required.** Field on the related table whose value to display.                         |
| `filters`           | Optional filter expression narrowing which related records are considered.               |

```yaml
- id: 2
  name: customer_email
  type: lookup
  relationshipField: customer
  relatedField: email
```

## `rollup`

Aggregates values from many related records.

| Property            | Description                                                                         |
| ------------------- | ----------------------------------------------------------------------------------- |
| `relationshipField` | **Required.** Name of the relationship field connecting to the related table.       |
| `relatedField`      | **Required.** Field on the related table to aggregate.                              |
| `aggregation`       | **Required.** Aggregation function (e.g. `SUM`, `AVG`, `MIN`, `MAX`, `COUNT`).      |
| `format`            | Display format for the aggregated result (e.g. `currency`, `number`, `percentage`). |
| `filters`           | Optional filter applied before aggregation.                                         |

```yaml
- id: 3
  name: total_sales
  type: rollup
  relationshipField: orders
  relatedField: amount
  aggregation: SUM
  format: currency
```

:::callout
**The relational chain.** Start with a `relationship` to create the link, then derive data without duplication: `orders → customer (relationship) → customer_email (lookup)`, or aggregate with `rollup`/`count`. `count`, `lookup`, and `rollup` are validated at config time to ensure their `relationshipField` references an actual `relationship` field in the same table.
:::

See [Relationships](/en/table-relationships) for a deeper look at cardinalities, referential actions, reciprocal links, and `displayField`.

# User & Audit Fields

Four field types reference users from the authentication system. Three are auto-populated audit fields tracking who created, updated, or deleted a record; one is an editable user reference. All require `auth` to be configured and share the [base field properties](/en/tables-overview#base-field-properties).

| Type         | Behavior                                                            |
| ------------ | ------------------------------------------------------------------- |
| `user`       | Editable reference to a user. Single or multiple selection.         |
| `created-by` | Auto-set to the user who created the record. Read-only.             |
| `updated-by` | Auto-set to the user who last modified the record. Read-only.       |
| `deleted-by` | Auto-set to the user who soft-deleted the record. NULL when active. |

## `user`

An editable reference to one or more users (e.g. an assignee).

| Property        | Description                                            |
| --------------- | ------------------------------------------------------ |
| `allowMultiple` | Boolean. When `true`, allows selecting multiple users. |

```yaml
- { id: 1, name: assigned_to, type: user, required: true, allowMultiple: false }
```

## System Audit Fields

`created-by`, `updated-by`, and `deleted-by` are **system-managed** — their values are set automatically and cannot be edited manually. They store a user-id reference and take no type-specific properties beyond the base field properties (commonly `indexed: true`).

| Type         | Behavior                                                                                                        |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `created-by` | Captures the user who created the record. Read-only.                                                            |
| `updated-by` | Captures the user who last modified the record. Read-only.                                                      |
| `deleted-by` | Captures the user who soft-deleted the record. `NULL` when the record is active or deleted by a system process. |

```yaml
fields:
  - { id: 2, name: created_by, type: created-by, indexed: true }
  - { id: 3, name: updated_by, type: updated-by, indexed: true }
  - { id: 4, name: deleted_by, type: deleted-by, indexed: true }
```

:::callout
**Auth required.** All user & audit fields resolve user-id references against the authentication system, so `auth` must be configured. Pair `deleted-by` with the [`deleted-at`](/en/datetime-fields) timestamp for a complete soft-delete audit trail (who deleted, and when).
:::

# Attachment Fields

The media category covers file uploads and the barcode field. `single-attachment` and `multiple-attachments` upload files into a storage bucket; `barcode` stores a scannable value (documented in detail on the [Advanced Fields](/en/advanced-fields#barcode) page). All share the [base field properties](/en/tables-overview#base-field-properties).

| Type                   | Stores                                                                |
| ---------------------- | --------------------------------------------------------------------- |
| `single-attachment`    | A single uploaded file.                                               |
| `multiple-attachments` | Multiple uploaded files.                                              |
| `barcode`              | A barcode value — see [Advanced Fields](/en/advanced-fields#barcode). |

## `single-attachment`

One uploaded file (avatar, document, image).

| Property            | Description                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `bucket`            | Storage bucket name. References a bucket in `app.buckets`. Uses the implicit `default` bucket when omitted. |
| `allowedFileTypes`  | Array of allowed MIME types (e.g. `["image/png", "image/jpeg"]`). All types allowed when empty.             |
| `maxFileSize`       | Maximum file size in **bytes** (integer ≥ 1). Example: `5242880` for 5 MB.                                  |
| `generateThumbnail` | Boolean. Generate image thumbnails on upload.                                                               |
| `storeMetadata`     | Boolean. Store metadata (image dimensions, video duration).                                                 |

```yaml
- id: 1
  name: avatar
  type: single-attachment
  bucket: avatars
  allowedFileTypes: [image/png, image/jpeg, image/gif]
  maxFileSize: 5242880
  generateThumbnail: true
  storeMetadata: true
```

## `multiple-attachments`

Many uploaded files (a gallery, a document set).

| Property             | Description                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `bucket`             | Storage bucket name. References a bucket in `app.buckets`. Uses `default` when omitted.                                      |
| `maxFiles`           | Maximum number of files allowed (integer ≥ 1).                                                                               |
| `allowedFileTypes`   | Array of allowed MIME types (e.g. `["application/pdf", "application/msword"]`).                                              |
| `maxFileSize`        | Maximum size in **bytes** per attachment (integer ≥ 1). Example: `10485760` for 10 MB.                                       |
| `generateThumbnails` | Boolean. Generate image thumbnails on upload. _(Note the plural — singular `generateThumbnail` is for `single-attachment`.)_ |
| `storeMetadata`      | Boolean. Store metadata for each attachment.                                                                                 |

```yaml
- id: 2
  name: documents
  type: multiple-attachments
  bucket: documents
  maxFiles: 10
  allowedFileTypes: [application/pdf, application/msword]
  maxFileSize: 10485760
  generateThumbnails: true
```

:::callout
**Buckets, not inline storage.** Attachment fields write to named buckets defined in `app.buckets` (local or S3). The `bucket` property selects which one; omitting it uses the implicit `default` bucket. `maxFileSize` is always specified in **bytes**. See the Buckets documentation for bucket configuration.
:::

The `barcode` field is the third member of the media category but is documented alongside the other specialized value fields — see [Advanced Fields → barcode](/en/advanced-fields#barcode).

# Advanced Fields

Nine specialized field types cover computed values, generated identifiers, interactive controls, and structured data. This page also documents `barcode` (a media-category field). All share the [base field properties](/en/tables-overview#base-field-properties).

| Type          | Stores / does                                             |
| ------------- | --------------------------------------------------------- |
| `formula`     | A value computed from a formula expression.               |
| `count`       | A count of related records.                               |
| `autonumber`  | An auto-incrementing number with prefix and zero-padding. |
| `button`      | An interactive button triggering a URL or automation.     |
| `json`        | Structured JSON data.                                     |
| `array`       | An array of typed values.                                 |
| `color`       | A hex color value.                                        |
| `code`        | Source code with syntax highlighting.                     |
| `geolocation` | Latitude/longitude coordinates.                           |
| `barcode`     | A barcode value (media category — see below).             |

## `formula`

Computes a value from a formula expression referencing other fields.

| Property     | Description                                                                               |
| ------------ | ----------------------------------------------------------------------------------------- |
| `formula`    | **Required.** Expression to compute. Supports field references, operators, and functions. |
| `resultType` | Expected data type of the result (e.g. `string`, `number`, `boolean`, `date`).            |
| `format`     | Display format for the result (e.g. `currency`, `percentage`, `decimal`, `date`).         |

```yaml
- { id: 1, name: total_price, type: formula, formula: 'price * quantity', resultType: number }
```

## `count`

Counts the number of records linked through a relationship field in the same table. A simplified `rollup`.

| Property            | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `relationshipField` | **Required.** Name of the relationship field whose linked records to count. |
| `filters`           | Optional filter expression — count only matching linked records.            |

```yaml
- {
    id: 2,
    name: completed_task_count,
    type: count,
    relationshipField: tasks,
    filters: { field: status, operator: equals, value: completed },
  }
```

## `autonumber`

An auto-incrementing number with an optional prefix and zero-padding.

| Property    | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `prefix`    | Optional text prepended to the number (e.g. `INV-`, `ORD-`).     |
| `startFrom` | Starting number (integer ≥ 1).                                   |
| `digits`    | Minimum digit count with zero-padding. Integer from **1 to 10**. |

```yaml
- { id: 3, name: invoice_number, type: autonumber, prefix: 'INV-', startFrom: 1000, digits: 5 }
```

## `button`

An interactive button rendered on records that triggers an action.

| Property     | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `label`      | **Required.** Button text.                                          |
| `action`     | **Required.** Type of action to trigger (e.g. `url`, `automation`). |
| `url`        | URL to open (when `action` is `url`).                               |
| `automation` | Automation name to run (when `action` is `automation`).             |

```yaml
- {
    id: 4,
    name: approve,
    type: button,
    label: Approve,
    action: automation,
    automation: approve_request,
  }
```

:::callout
**Corrected from earlier docs.** The button field uses `label`, `action`, `url`, and `automation` — **not** `buttonLabel` / `buttonAction` / `buttonUrl`.
:::

## `json`

Stores structured JSON data with optional schema validation.

| Property | Description                                          |
| -------- | ---------------------------------------------------- |
| `schema` | Optional JSON Schema object for validating contents. |

```yaml
- { id: 5, name: metadata, type: json, required: false }
```

## `array`

Stores an array of values with optional type and length constraints.

| Property   | Description                                  |
| ---------- | -------------------------------------------- |
| `itemType` | Data type of array elements (e.g. `string`). |
| `maxItems` | Maximum number of elements (integer ≥ 1).    |

```yaml
- { id: 6, name: tags, type: array, itemType: string, maxItems: 10 }
```

## `color`

Stores a color value in hexadecimal format. Rendered with a color picker.

| Property  | Description                                            |
| --------- | ------------------------------------------------------ |
| `default` | Default color as a 6-digit hex value (e.g. `#3B82F6`). |

```yaml
- { id: 7, name: brand_color, type: color, required: true, default: '#3B82F6' }
```

## `code`

Stores source code as plain text with syntax highlighting (CodeMirror 6).

| Property      | Description                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `language`    | **Required.** Language for highlighting (e.g. `javascript`, `typescript`, `yaml`, `json`, `python`, `sql`, `html`, `css`, `markdown`). |
| `lineNumbers` | Boolean. Show line numbers.                                                                                                            |
| `readOnly`    | Boolean. Make the editor read-only.                                                                                                    |
| `minLines`    | Minimum visible lines (integer ≥ 1).                                                                                                   |
| `maxLines`    | Maximum visible lines before scrolling (integer ≥ 1).                                                                                  |
| `tabSize`     | Tab size in spaces. Integer from **1 to 8** (default 2).                                                                               |

```yaml
- { id: 8, name: snippet, type: code, language: typescript, lineNumbers: true, tabSize: 2 }
```

## `geolocation`

Stores geographic coordinates (latitude and longitude) for location-based features. Takes no type-specific properties beyond the base field properties.

```yaml
- { id: 9, name: office_location, type: geolocation, required: true }
```

## `barcode`

Stores a barcode value for product identification and inventory. (Categorized under media, documented here with the other specialized value fields.)

| Property | Description                                |
| -------- | ------------------------------------------ |
| `format` | Barcode format (e.g. `EAN-13`, `CODE128`). |

```yaml
- { id: 10, name: product_barcode, type: barcode, required: true, format: EAN-13 }
```

:::callout
**Computed fields update automatically.** `formula`, `count`, and `rollup` (see [Relational Fields](/en/relational-fields)) are derived — they recompute when their inputs change and are not directly editable.
:::

# AI Fields

Seven field types compute their value with an LLM from one or more `sourceFields`. All share the [base field properties](/en/tables-overview#base-field-properties) and a common set of AI controls.

| Type            | Produces                                                  |
| --------------- | --------------------------------------------------------- |
| `ai-generate`   | Free-form generated text from a prompt template.          |
| `ai-summary`    | A summary of the source fields.                           |
| `ai-categorize` | A single category chosen from a predefined list.          |
| `ai-extract`    | Structured data matching a JSON Schema.                   |
| `ai-sentiment`  | Sentiment analysis of the source text.                    |
| `ai-tag`        | Multiple tags chosen from an allow-list.                  |
| `ai-translate`  | A translation of one source field into a target language. |

## Common AI Properties

Most AI fields accept these shared properties (in addition to their type-specific ones):

| Property       | Description                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `sourceFields` | **Required.** Field names used as input context. At least one (exactly one for `ai-translate`).                                    |
| `prompt`       | Custom prompt to guide the AI. `ai-generate` uses a `{{fieldName}}` template; others fall back to a sensible default when omitted. |
| `systemPrompt` | System prompt setting the AI persona and context.                                                                                  |
| `model`        | AI model override (e.g. `gpt-4o`, `claude-sonnet`). Non-empty string.                                                              |
| `temperature`  | Output creativity, `0` to `1`.                                                                                                     |

## `ai-generate`

Generates free-form text from a prompt template.

| Property | Description                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------ |
| `prompt` | Prompt template with `{{fieldName}}` variable substitution. _(Recommended for generate fields.)_ |

```yaml
- id: 1
  name: marketing_copy
  type: ai-generate
  sourceFields: [product_name, features]
  prompt: 'Write a compelling 2-paragraph marketing description for {{product_name}}. Key features: {{features}}.'
```

## `ai-summary`

Summarizes the source fields. Uses a default "Summarize the following" prompt when `prompt` is omitted.

```yaml
- { id: 2, name: ticket_summary, type: ai-summary, sourceFields: [body, thread] }
```

## `ai-categorize`

Classifies the source into exactly one of a fixed category list.

| Property     | Description                                                                            |
| ------------ | -------------------------------------------------------------------------------------- |
| `categories` | **Required.** Predefined categories the AI must choose from. Minimum 2, no duplicates. |

```yaml
- {
    id: 3,
    name: ticket_category,
    type: ai-categorize,
    sourceFields: [subject, body],
    categories: [billing, technical, account, general],
  }
```

## `ai-extract`

Extracts structured data described by a JSON Schema. Supports nested objects and arrays.

| Property | Description                                                                      |
| -------- | -------------------------------------------------------------------------------- |
| `schema` | **Required.** JSON Schema object describing the structure of the extracted data. |

```yaml
- id: 4
  name: invoice_data
  type: ai-extract
  sourceFields: [raw_text]
  schema:
    type: object
    properties:
      vendor_name: { type: string, description: Name of the vendor }
      total_amount: { type: number, description: Total amount due }
```

## `ai-sentiment`

Analyzes sentiment of the source text. `prompt` can adjust the focus (e.g. urgency, satisfaction).

```yaml
- { id: 5, name: review_sentiment, type: ai-sentiment, sourceFields: [review_text] }
```

## `ai-tag`

Assigns multiple tags from a predefined allow-list.

| Property  | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `tags`    | **Required.** Allowed tags the AI may assign. Minimum 2, no duplicates.     |
| `maxTags` | Maximum number of tags to assign (positive integer). No limit when omitted. |

```yaml
- {
    id: 6,
    name: article_tags,
    type: ai-tag,
    sourceFields: [title, body],
    tags: [technology, business, science, health, politics],
    maxTags: 3,
  }
```

## `ai-translate`

Translates one source field into a target language.

| Property         | Description                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `sourceFields`   | **Required.** Exactly **one** field name.                                                           |
| `targetLanguage` | **Required.** ISO 639-1 language code, optionally region-suffixed (e.g. `fr`, `es`, `ja`, `zh-CN`). |
| `prompt`         | Custom prompt to control translation tone, formality, and style.                                    |

```yaml
- {
    id: 7,
    name: description_fr,
    type: ai-translate,
    sourceFields: [description],
    targetLanguage: fr,
  }
```

:::callout
**AI provider routing.** AI fields route through Sovrium's provider-precedence resolver (env-controlled, local-first by default). The optional `model` property overrides the default model for that field. The connecting role still gates execution wherever the table is exposed via the MCP server.
:::

# Table Permissions

Sovrium controls record access with **role-based access control (RBAC)** at the table level, **field-level permissions** for granular column control, and optional **row-level predicates** for per-row scoping. Unauthorized access returns **404** (never 403) to prevent record enumeration.

## Permission Values

Every operation accepts one of three formats:

| Value                 | Meaning                                       |
| --------------------- | --------------------------------------------- |
| `all`                 | Everyone, including unauthenticated visitors. |
| `authenticated`       | Any logged-in user.                           |
| `['admin', 'editor']` | Only the listed role names (an array).        |

The three built-in roles are `admin`, `member`, and `viewer` (highest to lowest). Custom role names are also accepted in the array form.

## Table-Level Permissions

Set `permissions` on a table to gate each operation.

| Operation         | Controls who can…                                  |
| ----------------- | -------------------------------------------------- |
| `read`            | View records.                                      |
| `comment`         | Add comments to records.                           |
| `create`          | Create new records.                                |
| `update`          | Modify existing records.                           |
| `delete`          | Soft-delete records.                               |
| `restore`         | Restore soft-deleted records.                      |
| `permanentDelete` | Permanently remove soft-deleted records.           |
| `fields`          | Per-field read/write permissions (see below).      |
| `inherit`         | Inherit all permissions from a named parent table. |

```yaml
permissions:
  read: all
  comment: authenticated
  create: [admin, editor]
  update: [admin, editor]
  delete: [admin]
  restore: [admin]
  permanentDelete: [admin]
```

## Field-Level Permissions

Restrict read/write access to specific columns under `permissions.fields`. Each entry names a `field` and optionally its `read` and `write` audiences (same three formats). When a field permission is omitted, it inherits from the table-level `read` (for read) or `create`/`update` (for write).

| Property | Description                                                       |
| -------- | ----------------------------------------------------------------- |
| `field`  | Name of the field this permission applies to.                     |
| `read`   | Who can read (SELECT) this field. Inherits table `read` if unset. |
| `write`  | Who can write (INSERT/UPDATE) this field. Inherits if unset.      |

```yaml
permissions:
  read: authenticated
  fields:
    - { field: salary, read: [admin, hr], write: [admin] }
    - { field: department, read: all, write: [admin] }
```

## Row-Level Permissions

Set `rowLevelPermissions` for defense-in-depth scoping. Each CRUD operation can carry a server-side `when` predicate that is appended as a filter to every record-returning request. The role gate runs first; the row-level predicate then filters within the permitted role's scope.

A predicate is `{ field, operator, value }`:

| Field      | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `field`    | The table field, or a relation chain like `project.client_id`, to filter on.                                 |
| `operator` | `eq`, `neq`, or `in` (array membership).                                                                     |
| `value`    | A literal (string/number/boolean/array) **or** a `$currentUser` reference resolved per-request from session. |

```yaml
rowLevelPermissions:
  read:
    when:
      field: client_id
      operator: in
      value: { kind: currentUser, path: { kind: assignment, tableSlug: clients } }
  write:
    when:
      field: client_id
      operator: in
      value: { kind: currentUser, path: { kind: assignment, tableSlug: clients } }
```

:::callout
**404, not 403 — anti-enumeration.** When a request fails authorization (table-level, field-level, or row-level), Sovrium returns **404 Not Found** rather than 403 Forbidden. This prevents attackers from discovering which records or tables exist by probing for status codes.
:::

## Resource:Action Permissions

For broader permission contexts (admin plugin, API keys), Sovrium also supports a `resource: [actions]` map where each resource lists allowed actions and `*` means all actions:

```yaml
users: [read, list]
posts: [create, read, update, delete]
analytics: ['*']
```

# Indexes & Constraints

Beyond fields, a table can declare a primary key, indexes for query performance and uniqueness, unique-constraint sugar, CHECK constraints for cross-field rules, and composite foreign keys.

## Primary Key

Set `primaryKey` to control how each row is uniquely identified. When omitted, an auto-generated `id` column is the primary key.

| Property | Description                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `type`   | Generation strategy: `auto-increment` (sequential integers), `uuid` (random unique ids), or `composite` (multi-field). |
| `field`  | Field name for a single-column key. Only used with `auto-increment` or `uuid`. Must match `^[a-z][a-z0-9_]*`.          |
| `fields` | Array of field names for a composite primary key.                                                                      |

```yaml
primaryKey: { type: auto-increment, field: id }
```

```yaml
# Composite primary key
primaryKey: { type: composite, fields: [tenant_id, slug] }
```

## Indexes

`indexes` is an array of index definitions. Index names must be unique within the table.

| Property | Description                                                                                                          |
| -------- | -------------------------------------------------------------------------------------------------------------------- |
| `name`   | Index name. Must match `^[a-z][a-z0-9_]*`. Use descriptive names like `idx_users_email`.                             |
| `fields` | Array of field names covered by the index. At least one required.                                                    |
| `unique` | Boolean. When `true`, enforces uniqueness across the indexed fields.                                                 |
| `where`  | SQL `WHERE` clause for a **partial index** — indexes only rows satisfying the condition (e.g. `deleted_at IS NULL`). |

```yaml
indexes:
  - { name: idx_users_email, fields: [email], unique: true }
  - { name: idx_orders_status, fields: [status] }
  # Partial unique index — uniqueness only on non-deleted rows
  - { name: idx_active_slug, fields: [slug], unique: true, where: 'deleted_at IS NULL' }
```

## Unique Constraints (top-level `unique`)

The table-level `unique` array is sugar for declaring uniqueness over one or more fields. Single-field entries fold into the equivalent of `field.unique = true`; multi-field entries become a unique btree index.

```yaml
unique:
  - { fields: [slug] } # single-field uniqueness
  - { fields: [tenant_id, slug] } # composite uniqueness
```

## CHECK Constraints

`constraints` enforces complex business rules at the database level with SQL boolean expressions. Constraint names must be unique within the table and match `^[a-z][a-z0-9_]*`.

| Property | Description                                                              |
| -------- | ------------------------------------------------------------------------ |
| `name`   | Unique constraint name (lowercase, alphanumeric, underscores).           |
| `check`  | PostgreSQL boolean expression that must evaluate to TRUE for valid data. |

```yaml
constraints:
  - { name: chk_price_positive, check: 'price > 0' }
  - { name: chk_end_after_start, check: 'end_date > start_date' }
  - { name: chk_active_members_have_email, check: '(is_active = false) OR (email IS NOT NULL)' }
```

## Composite Foreign Keys

Single-column foreign keys are created automatically from [`relationship`](/en/relational-fields) fields. Use `foreignKeys` for **multi-column** references to a composite primary key in another table.

| Property           | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `name`             | Constraint name (lowercase, underscores, max 63 chars).                          |
| `fields`           | Local columns forming the foreign key.                                           |
| `referencedTable`  | Parent table containing the referenced columns.                                  |
| `referencedFields` | Columns in the parent table that are referenced.                                 |
| `onDelete`         | Referential action on delete: `cascade`, `set-null`, `restrict`, or `no-action`. |
| `onUpdate`         | Referential action on update: `cascade`, `set-null`, `restrict`, or `no-action`. |

```yaml
foreignKeys:
  - name: fk_permissions_tenant_user
    fields: [tenant_id, user_id]
    referencedTable: tenant_users
    referencedFields: [tenant_id, user_id]
    onDelete: cascade
    onUpdate: cascade
```

:::callout
**Indexes vs constraints.** Use `indexes` for query performance and single/multi-field uniqueness; use `constraints` (CHECK) for conditional and cross-field validation that uniqueness cannot express. Both are validated against the table's field names at config time.
:::

# Relationships

Tables connect through the [`relationship`](/en/relational-fields#relationship) field, which creates a foreign-key link to another table. Once a relationship exists, [`lookup`](/en/relational-fields#lookup), [`rollup`](/en/relational-fields#rollup), and [`count`](/en/advanced-fields#count) derive data through it without duplicating values.

## Defining a Relationship

```yaml
- id: 1
  name: customer
  type: relationship
  relatedTable: Customers
  relationType: many-to-one
  displayField: full_name
  onDelete: set-null
  onUpdate: cascade
  reciprocalField: orders
```

## Cardinalities

`relationType` sets the shape of the link. It defaults to `many-to-one`.

| Cardinality    | Meaning                                                                               |
| -------------- | ------------------------------------------------------------------------------------- |
| `one-to-one`   | Each record links to exactly one record, and vice versa.                              |
| `many-to-one`  | Many records here link to one record in the related table (default).                  |
| `one-to-many`  | One record here links to many in the related table (uses `foreignKey`).               |
| `many-to-many` | Records on both sides link to many on the other (`allowMultiple` defaults to `true`). |

## Referential Actions

`onDelete` and `onUpdate` define what happens to dependent rows when the related row is deleted or its key is updated.

| Action      | Effect                                         |
| ----------- | ---------------------------------------------- |
| `cascade`   | Propagate the delete/update to dependent rows. |
| `set-null`  | Set the foreign key to NULL on dependent rows. |
| `restrict`  | Prevent the operation while dependents exist.  |
| `no-action` | Defer the check; take no automatic action.     |

## Reciprocal Links & Display Field

| Property          | Description                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `reciprocalField` | Field name created on the related table for the inverse (bidirectional) link.               |
| `displayField`    | Field from the related table shown in the UI in place of the raw id (e.g. `full_name`).     |
| `foreignKey`      | Custom foreign-key column name (used for `one-to-many`). Auto-generated when omitted.       |
| `allowMultiple`   | Allows linking to multiple related records (defaults to `true` for `many-to-many`).         |
| `limitToView`     | Restricts selectable related records to those visible in a named view of the related table. |

## Worked Example

An `Orders` table linked to `Customers`, exposing the customer's email via lookup and a per-customer order total via rollup:

```yaml
tables:
  - id: 1
    name: Customers
    fields:
      - { id: 1, name: full_name, type: single-line-text, required: true }
      - { id: 2, name: email, type: email, unique: true }
  - id: 2
    name: Orders
    fields:
      - { id: 1, name: amount, type: currency, currency: USD, required: true }
      - id: 2
        name: customer
        type: relationship
        relatedTable: Customers
        relationType: many-to-one
        displayField: full_name
        onDelete: restrict
        reciprocalField: orders
      - {
          id: 3,
          name: customer_email,
          type: lookup,
          relationshipField: customer,
          relatedField: email,
        }
```

And on the `Customers` side, a rollup of order amounts through the reciprocal `orders` link:

```yaml
- {
    id: 3,
    name: lifetime_value,
    type: rollup,
    relationshipField: orders,
    relatedField: amount,
    aggregation: SUM,
    format: currency,
  }
```

:::callout
**Validation.** `lookup`, `rollup`, and `count` are validated at config time: their `relationshipField` must name an actual `relationship` field in the same table. A typo or a reference to a non-relationship field fails decoding with a clear error.
:::

# Views

Views are saved, named configurations of how a table's records are filtered, sorted, grouped, and projected. Add them under a table's `views` array. A view operates in one of two modes: **JSON config mode** (declarative filters/sorts/fields/group-by) or **SQL mode** (a raw PostgreSQL `query`).

## View Properties

| Property             | Description                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `id`                 | Unique view identifier.                                                                        |
| `name`               | Human-readable view name.                                                                      |
| `isDefault`          | Boolean. When `true`, this view's configuration applies when no specific view is requested.    |
| `filters`            | Filter conditions (JSON config mode). See below.                                               |
| `sorts`              | Array of `{ field, direction }` sort rules (JSON config mode). `direction` is `asc` or `desc`. |
| `fields`             | Array of field names to include, in display order (JSON config mode).                          |
| `groupBy`            | `{ field, direction? }` grouping configuration (JSON config mode).                             |
| `query`              | Raw SQL for a PostgreSQL `VIEW` (SQL mode). When set, JSON config properties are not used.     |
| `materialized`       | Boolean. With `query`, create a `MATERIALIZED VIEW` that caches results. SQL mode only.        |
| `refreshOnMigration` | Boolean. With `materialized`, refresh the materialized view during migrations.                 |

## JSON Config Mode

Declarative — filter, sort, group, and choose columns without writing SQL.

```yaml
views:
  - id: active_high_priority
    name: Active — High Priority
    isDefault: true
    filters:
      and:
        - { field: status, operator: equals, value: active }
        - { field: priority, operator: equals, value: high }
    sorts:
      - { field: created_at, direction: desc }
    fields: [title, status, priority, assigned_to]
    groupBy: { field: status, direction: asc }
```

### Filters

A filter is either a single condition `{ field, operator, value }` or a boolean group combining conditions with `and` / `or` (which may nest):

```yaml
filters:
  or:
    - { field: priority, operator: equals, value: high }
    - { field: priority, operator: equals, value: urgent }
```

Common operators include `equals`, `greaterThan`, `lessThan`, and similar comparison operators. See [Validation](/en/table-validation) for how filter fields are checked against the table.

## SQL Mode

For advanced reporting, provide a raw `query`. Set `materialized: true` to cache the results, and `refreshOnMigration: true` to keep the cache fresh across schema migrations.

```yaml
views:
  - id: monthly_revenue
    name: Monthly Revenue
    query: >
      SELECT date_trunc('month', created_at) AS month, SUM(amount) AS revenue
      FROM orders GROUP BY 1 ORDER BY 1
    materialized: true
    refreshOnMigration: true
```

:::callout
**Default view.** Mark exactly one view per table with `isDefault: true` to control what records appear when a consumer requests the table without naming a view. View ids and the single-default rule are validated at config time.
:::

# Validation

Sovrium validates data at two layers: **config-time** (the schema is decoded with Effect Schema when the app boots, catching invalid definitions) and **runtime** (records are checked against field rules, constraints, and permissions on every write). This page summarizes the validation surface for tables.

## Field-Level Validation

Many field types carry built-in validation derived from their properties:

| Rule                  | Applies to                                       | Effect                                                  |
| --------------------- | ------------------------------------------------ | ------------------------------------------------------- |
| `required`            | All fields                                       | Value must be present on every record.                  |
| `unique`              | All fields                                       | No two records may share the value.                     |
| `min` / `max`         | `integer`, `decimal`, `currency`, `percentage`   | Value must fall within the inclusive range.             |
| `precision`           | `decimal` (1–10), `currency`/`percentage` (0–10) | Restricts decimal places.                               |
| `currency` (ISO 4217) | `currency`                                       | Must be a valid three-letter code.                      |
| `maxLength`           | `rich-text`                                      | Caps character length.                                  |
| `maxSelections`       | `multi-select`                                   | Caps choices; cannot exceed the number of `options`.    |
| `options`             | `single-select`, `multi-select`, `status`        | Values must come from the declared option list.         |
| format validation     | `email`, `url`                                   | Must match RFC 5322 / a valid absolute URL.             |
| `targetLanguage`      | `ai-translate`                                   | Must be an ISO 639-1 code (optionally region-suffixed). |
| `categories` / `tags` | `ai-categorize` / `ai-tag`                       | Minimum 2 entries, no duplicates.                       |

## Table-Level Validation (Config Time)

When the schema is decoded, Sovrium enforces structural rules and rejects invalid configurations with descriptive errors:

- **Field names and IDs** must be unique within a table.
- **Field & table names** must match `^[a-z][a-z0-9_]*` (after sanitization) and stay within 63 characters.
- **Index names** and **constraint names** must be unique within the table and match the identifier pattern.
- **Primary key** fields must reference real fields.
- **Indexes, permissions, views, webhooks** are checked so their field references name actual table fields.
- **`count` / `rollup` / `lookup`** fields must reference an existing `relationship` field in the same table.
- **Formula fields** are validated for correct field references.
- **Webhook names** must be unique, and `payload` field selectors must name real fields (the implicit `id` is always valid).

## CHECK Constraints

Use [CHECK constraints](/en/table-indexes-constraints#check-constraints) for cross-field and conditional rules that field-level validation cannot express:

```yaml
constraints:
  - { name: chk_end_after_start, check: 'end_date > start_date' }
  - { name: chk_active_members_have_email, check: '(is_active = false) OR (email IS NOT NULL)' }
```

## Uniqueness & Integrity

- Single-field uniqueness: `field.unique: true` or a top-level `unique: [{ fields: [x] }]`.
- Composite uniqueness: top-level `unique: [{ fields: [a, b] }]` (becomes a unique index) or a unique [index](/en/table-indexes-constraints#indexes).
- Partial uniqueness: a unique index with a `where` clause (e.g. unique slug only among non-deleted rows).
- Relational integrity: [`relationship`](/en/relational-fields) fields create foreign keys with `onDelete`/`onUpdate` actions; composite references use `foreignKeys`.

:::callout
**Fail fast at boot.** Because configuration is decoded with Effect Schema, a malformed table definition (duplicate field name, dangling relationship reference, invalid currency code, out-of-range precision) fails when the app starts — not silently at runtime. Run `sovrium validate app.yaml` to check a config before deploying.
:::

# Webhooks

Add `webhooks` to a table to fire outgoing HTTP `POST` requests when records are created, updated, or deleted. Each webhook is syntactic sugar over automations — internally it expands to a record trigger plus a `webhook.send` action. Webhook names must be unique within the table.

## Webhook Properties

| Property  | Description                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `name`    | **Required.** Unique webhook identifier within the table.                                              |
| `url`     | **Required.** Destination URL. Must be a valid absolute `http(s)` URL.                                 |
| `events`  | **Required.** Record events that trigger delivery: any of `create`, `update`, `delete` (at least one). |
| `enabled` | Boolean. Whether the webhook is active (default `true`).                                               |
| `auth`    | Authentication for the outgoing request (HMAC, API key, or bearer). See below.                         |
| `retry`   | Retry policy for failed deliveries. See below.                                                         |
| `payload` | Payload field selection and metadata options. See below.                                               |

```yaml
webhooks:
  - name: order_created
    url: https://hooks.example.com/orders
    events: [create]
    enabled: true
```

## Authentication

`auth` secures the request. Three types are supported; secrets/keys/tokens support `$env.` references.

| Type     | Properties                                                                                        |
| -------- | ------------------------------------------------------------------------------------------------- |
| `hmac`   | `secret` (required), `algorithm` (`sha256` default, or `sha1`), `header` (signature header name). |
| `apiKey` | `key` (required), `header` (header name to carry the key).                                        |
| `bearer` | `token` (required) sent as a bearer token.                                                        |

```yaml
auth: { type: hmac, secret: '$env.PARTNER_WEBHOOK_SECRET', algorithm: sha256 }
```

```yaml
auth: { type: apiKey, key: '$env.SERVICE_API_KEY', header: X-API-Key }
```

```yaml
auth: { type: bearer, token: '$env.API_BEARER_TOKEN' }
```

## Retry Policy

`retry` controls how failed deliveries are retried.

| Property       | Description                                                                            |
| -------------- | -------------------------------------------------------------------------------------- |
| `maxAttempts`  | Number of retry attempts after the initial failure. `0` disables retries. Default `3`. |
| `backoff`      | Backoff strategy: `exponential` or `fixed`.                                            |
| `initialDelay` | Milliseconds before the first retry (default `1000`).                                  |
| `maxDelay`     | Maximum delay in milliseconds between retries.                                         |

```yaml
retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
```

## Payload Selection

`payload` shapes what data is sent. `includeFields` (whitelist) and `excludeFields` (blacklist) are mutually exclusive, and every named field must exist on the table (the implicit `id` is always valid).

| Property                | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `includeFields`         | Only include these fields (whitelist).                   |
| `excludeFields`         | Exclude these fields (blacklist).                        |
| `includePreviousValues` | Include the record's previous values on `update` events. |
| `includeMetadata`       | Include event metadata in the payload.                   |

```yaml
payload: { includeFields: [customer, status, total], includePreviousValues: true }
```

## Full Example

```yaml
webhooks:
  - name: order_lifecycle
    url: https://hooks.example.com/orders
    events: [create, update, delete]
    enabled: true
    auth: { type: hmac, secret: '$env.ORDER_WEBHOOK_SECRET', algorithm: sha256 }
    retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
    payload: { excludeFields: [internal_notes], includePreviousValues: true }
```

:::callout
**Validation.** Webhook `name`s must be unique within a table, and any field referenced by `payload.includeFields` / `excludeFields` must name a real field (or the implicit `id`). Invalid URLs and non-`http(s)` schemes are rejected at config-decode time.
:::

# Records Overview

Every table you declare automatically exposes a complete REST API for its records. There is no resolver to write and no endpoint to register — the moment a table exists in your config, its `records` collection is reachable under `/api/tables/:tableId/records`. This page documents the shared API surface: the URL layout, the response envelope, authorship metadata, and the cross-cutting rules (authentication, permissions, formatting) that every records endpoint obeys.

Records are the rows of a [table](tables-overview). Tables define the columns (fields); records hold the values. The Records API is the canonical read/write path for that data — pages render it, forms write to it, automations react to it, and external integrations consume it.

## Endpoint surface

`:tableId` accepts either the numeric table `id` or the table `name`/slug. All endpoints accept and return JSON.

| Method & Path                                                              | Description                                                             |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `POST /api/tables/:tableId/records`                                        | Create a single record                                                  |
| `GET /api/tables/:tableId/records`                                         | List records (pagination, sort, filter, field-select, group, aggregate) |
| `GET /api/tables/:tableId/records/:recordId`                               | Read a single record by ID                                              |
| `PATCH /api/tables/:tableId/records/:recordId`                             | Update a single record (partial)                                        |
| `DELETE /api/tables/:tableId/records/:recordId`                            | Soft delete a record (`?permanent=true` to hard delete)                 |
| `POST /api/tables/:tableId/records/upsert`                                 | Create-or-update by match fields                                        |
| `POST /api/tables/:tableId/records/batch`                                  | Batch create                                                            |
| `PATCH /api/tables/:tableId/records/batch`                                 | Batch update                                                            |
| `DELETE /api/tables/:tableId/records/batch`                                | Batch (soft) delete                                                     |
| `POST /api/tables/:tableId/records/:recordId/restore`                      | Restore a soft-deleted record                                           |
| `POST /api/tables/:tableId/records/batch/restore`                          | Batch restore                                                           |
| `GET /api/tables/:tableId/records/:recordId/history`                       | Record change history                                                   |
| `GET\|POST\|PATCH\|DELETE /api/tables/:tableId/records/:recordId/comments` | Record comments                                                         |
| `GET /api/tables/:tableId/trash`                                           | Browse soft-deleted records (trash view)                                |
| `GET /api/tables/:tableSlug/subscribe`                                     | Real-time WebSocket subscription                                        |

Detailed behavior is split across focused pages: [CRUD & upsert](records-crud), [filtering, sorting & pagination](records-filtering-sorting), [batch operations](records-batch), [history & comments](record-history), [soft delete & trash](records-soft-delete), [real-time subscriptions](records-realtime), and [import/export](records-import-export).

## The `fields` envelope

Record write bodies use the canonical Airtable-style envelope: a `fields` object mapping field names to values.

```json
POST /api/tables/contacts/records
{
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

A successful create returns `201 Created` with the stored record, including its generated `id` and authorship metadata:

```json
{
  "id": "42",
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "createdBy": "user-uuid-123",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

:::callout
**Flat bodies are accepted too.** A body without a `fields` key (e.g. `{ "email": "john@example.com" }`) is automatically wrapped into the canonical `{ "fields": { ... } }` shape. The envelope form is preferred and is the only shape accepted by batch and upsert endpoints.
:::

## List response envelope

`GET .../records` returns a paginated envelope, never a bare array:

```json
{
  "records": [{ "id": "1", "fields": {} }],
  "pagination": { "total": 128, "limit": 20, "offset": 0 }
}
```

`records` is the page of results; `pagination` carries the `total` matching-row count plus the `limit`/`offset` that produced this page. See [Filtering, Sorting & Pagination](records-filtering-sorting) for the full query-parameter grammar.

## Authorship metadata

The API automatically stamps and exposes authorship on every write. These fields are server-controlled and **read-only** — values supplied in a request body are ignored, so the audit trail cannot be forged.

| Field                     | Set when                     | Cleared/updated          |
| ------------------------- | ---------------------------- | ------------------------ |
| `createdBy` / `createdAt` | Record is created            | Never changes            |
| `updatedBy` / `updatedAt` | Record is created or updated | Re-stamped on each write |
| `deletedBy` / `deletedAt` | Record is soft-deleted       | Cleared on restore       |

`createdBy`, `updatedBy`, and `deletedBy` resolve to the authenticated user's ID. They are surfaced through dedicated [user-audit field types](user-audit-fields) (`created-by`, `updated-by`, `deleted-by`) and the `updated-at` system field auto-bumps the timestamp on every write — enabling the [optimistic-locking](records-crud) contract.

## Cross-cutting rules

Every records endpoint enforces the same guarantees:

| Concern                     | Behavior                                                                                                                         |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**          | Endpoints require a session. Unauthenticated requests return `401`.                                                              |
| **Table existence**         | An unknown `:tableId` returns `404` — never a 403, to avoid enumeration.                                                         |
| **RBAC**                    | Create/read/update/delete are gated per [table permission](table-permissions) and the role's [RBAC](auth-roles-rbac) grants.     |
| **Field-level permissions** | Responses omit fields the caller cannot read; writes to fields the caller cannot write are rejected.                             |
| **Validation**              | Field values are validated against the field type; missing required fields and constraint violations return `400`.               |
| **Anti-enumeration**        | Unauthorized access to an existing record returns `404`, not `403`, so an attacker cannot distinguish "forbidden" from "absent". |

:::callout
**404 over 403 is intentional.** To prevent record enumeration, the API returns `404 Not Found` for records the caller may not access — identical to the response for records that do not exist. See the [authentication overview](auth-overview).
:::

## Display vs raw formatting

By default, field values are returned raw (the stored value). Pass `?format=display` to receive human-readable, locale- and timezone-aware values (formatted currency, dates, durations, attachment display names). The raw form is preferred for programmatic clients; the display form is preferred for direct rendering. See [Record formatting](records-crud) for the controls.

## Related pages

- [CRUD & Upsert](records-crud) — create, read, update, delete, upsert, formatting
- [Filtering, Sorting & Pagination](records-filtering-sorting) — query parameters
- [Batch Operations](records-batch) — bulk create/update/delete
- [Record History & Comments](record-history) — change log and collaboration
- [Soft Delete & Restore](records-soft-delete) — trash and recovery
- [Real-Time Subscriptions](records-realtime) — WebSocket/SSE/poll
- [Import & Export](records-import-export) — CSV/JSON and clipboard
- [API Reference](api-reference) — the generated endpoint catalog

# Records CRUD & Upsert

This page covers single-record lifecycle operations: create, read, update, delete, and upsert. For listing many records see [Filtering, Sorting & Pagination](records-filtering-sorting); for bulk writes see [Batch Operations](records-batch). All write bodies use the canonical `{ "fields": { ... } }` envelope described in the [Records Overview](records-overview).

## Create a record

```json
POST /api/tables/contacts/records
{
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

| Status             | Meaning                                                                          |
| ------------------ | -------------------------------------------------------------------------------- |
| `201 Created`      | Record created; body is the stored record with `id` and authorship               |
| `400 Bad Request`  | Missing required field, invalid field-type value, or unique-constraint violation |
| `401 Unauthorized` | No active session                                                                |
| `404 Not Found`    | Table does not exist (or caller may not access it)                               |

The response carries the generated `id`, the `fields` echo, and the [authorship metadata](records-overview) (`createdBy`, `createdAt`, `updatedAt`).

## Read a record

```
GET /api/tables/contacts/records/42
```

| Status             | Meaning                                                           |
| ------------------ | ----------------------------------------------------------------- |
| `200 OK`           | Record returned                                                   |
| `401 Unauthorized` | No active session                                                 |
| `404 Not Found`    | Record absent **or** not visible to the caller (anti-enumeration) |

Fields the caller lacks read permission for are omitted from the response — the same record can return a different field set depending on the caller's role and [field-level permissions](table-permissions).

## Update a record

`PATCH` performs a partial update: only the fields present in the body are written; omitted fields are left untouched.

```json
PATCH /api/tables/contacts/records/42
{
  "fields": {
    "status": "active"
  }
}
```

| Status             | Meaning                                            |
| ------------------ | -------------------------------------------------- |
| `200 OK`           | Record updated; `updatedBy`/`updatedAt` re-stamped |
| `400 Bad Request`  | Invalid field-type value or constraint violation   |
| `401 Unauthorized` | No active session                                  |
| `404 Not Found`    | Record absent or not visible                       |
| `409 Conflict`     | Optimistic-lock failure (stale write)              |

### Optimistic locking

Include a top-level `updatedAt` token alongside `fields` to guard against lost updates. The server compares it to the stored `updated_at` column and rejects a divergent write with `409 Conflict`.

```json
PATCH /api/tables/contacts/records/42
{
  "fields": { "status": "active" },
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

:::callout
**Tables opt in via the `updated-at` system field.** Add a field of `type: 'updated-at'` so the column auto-bumps on every write. A plain `datetime` field is user-editable and is **not** auto-managed, so it cannot back the optimistic-lock contract.
:::

## Delete a record

By default `DELETE` is a **soft delete**: it sets `deletedAt`/`deletedBy` and leaves the row recoverable.

```
DELETE /api/tables/contacts/records/42
DELETE /api/tables/contacts/records/42?permanent=true
```

| Status                      | Meaning                                                      |
| --------------------------- | ------------------------------------------------------------ |
| `200 OK` / `204 No Content` | Record soft-deleted (or hard-deleted with `?permanent=true`) |
| `401 Unauthorized`          | No active session                                            |
| `403`/`404`                 | Caller lacks delete permission, or record not visible        |

Hard delete (`?permanent=true`) requires the `permanentDelete` permission and is irreversible. See [Soft Delete & Restore](records-soft-delete) for trash, restore, and cascade behavior on related records.

## Upsert a record

Upsert creates a record or updates an existing one matched on one or more unique fields, in a single call. Use `matchFields` (alias: `fieldsToMergeOn`) to name the merge key(s).

```json
POST /api/tables/contacts/records/upsert
{
  "fields": {
    "email": "john@example.com",
    "name": "John Doe",
    "status": "active"
  },
  "matchFields": ["email"]
}
```

The response reports whether the row was `created` or `updated`:

```json
{
  "id": 123,
  "operation": "created",
  "record": {
    "id": 123,
    "email": "john@example.com",
    "name": "John Doe",
    "status": "active"
  }
}
```

When an existing row matches the `matchFields`, `operation` is `"updated"` instead and the matched row is patched. Upsert is ideal for idempotent synchronization from external systems — see [Batch Operations](records-batch) for the multi-record `upsert` variant.

## Display vs raw formatting

The `format` query parameter controls how field values are serialized on read endpoints.

| `format`        | Behavior                                                                              |
| --------------- | ------------------------------------------------------------------------------------- |
| `raw` (default) | Stored values, unchanged — preferred for programmatic clients                         |
| `display`       | Human-readable values: formatted currency, dates, durations, attachment display names |

```
GET /api/tables/orders/records?format=display&timezone=Europe/Paris
```

Formatting is driven per field type:

| Field type                            | Display formatting                                                                |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| `currency`                            | Symbol, decimal places, and locale grouping                                       |
| `datetime`                            | Configured date/time format; `?timezone=` (IANA) overrides the rendering timezone |
| `duration`                            | `h:mm`, `h:mm:ss`, or decimal hours per the field config                          |
| `attachment` / `multiple-attachments` | URL plus metadata and display names                                               |
| `json`                                | Serialized per the field config and the `format` parameter                        |

:::callout
**Raw is the source of truth.** `format=display` is a presentation convenience layered on top of the stored value. Round-tripping (read with `display`, write back) is not guaranteed — always write the raw value. Numeric and date fields keep their raw form available for calculations.
:::

## Related pages

- [Records Overview](records-overview) — envelope, authorship, cross-cutting rules
- [Filtering, Sorting & Pagination](records-filtering-sorting) — list query grammar
- [Batch Operations](records-batch) — bulk create/update/delete/upsert
- [Soft Delete & Restore](records-soft-delete) — trash and recovery
- [Table Permissions](table-permissions) — RBAC and field-level access

# Filtering, Sorting & Pagination

`GET /api/tables/:tableId/records` returns a paginated envelope and accepts a rich set of query parameters to paginate, sort, filter, select fields, group, and aggregate records — so you can shape large datasets without writing custom endpoints. Every parameter is optional; combine them freely.

```
GET /api/tables/tasks/records?limit=10&offset=0&sort=priority:desc,name:asc&fields=id,name,status
```

The response is always the list envelope (never a bare array):

```json
{
  "records": [{ "id": "1", "fields": {} }],
  "pagination": { "total": 128, "limit": 10, "offset": 0 }
}
```

## Query parameter reference

| Parameter        | Description                                                | Example                          |
| ---------------- | ---------------------------------------------------------- | -------------------------------- |
| `limit`          | Maximum records to return                                  | `?limit=20`                      |
| `offset`         | Number of records to skip                                  | `?offset=40`                     |
| `page`           | Page number (1-indexed) — alternative to `offset`          | `?page=3`                        |
| `sort`           | Sort field(s) and direction                                | `?sort=name:asc,created_at:desc` |
| `order`          | Sort order (`asc`/`desc`) for a single-field sort          | `?sort=name&order=desc`          |
| `fields`         | Comma-separated field names to include                     | `?fields=id,name,status`         |
| `filter`         | Filter expression (JSON)                                   | `?filter={"status":"active"}`    |
| `view`           | Apply a saved [view](table-views) configuration            | `?view=2`                        |
| `groupBy`        | Group records by a field                                   | `?groupBy=status`                |
| `aggregate`      | Aggregation functions                                      | `?aggregate=sum:amount,count:id` |
| `q`              | Free-text search query                                     | `?q=invoice`                     |
| `format`         | `raw` (default) or `display` field values                  | `?format=display`                |
| `timezone`       | IANA timezone for date display formatting                  | `?timezone=Europe/Paris`         |
| `includeDeleted` | `true` to include soft-deleted rows; `only` for trash-only | `?includeDeleted=true`           |

## Pagination

Two equivalent paging styles are supported. Use `limit` + `offset` for cursor-style scanning, or `limit` + `page` for page-numbered UIs. `pagination.total` is the count of all matching rows (independent of the page), so a client can compute the page count as `ceil(total / limit)`.

```
GET /api/tables/tasks/records?limit=20&offset=40   # rows 41–60
GET /api/tables/tasks/records?limit=20&page=3       # rows 41–60 (1-indexed)
```

## Sorting

Sort by one or more fields, each with a direction, using `field:direction` segments separated by commas. The leftmost field is the primary sort key.

```
GET /api/tables/tasks/records?sort=priority:desc,name:asc
```

For a single sort field you may instead split the field and direction across `sort` and `order` (`?sort=name&order=desc`). The `field:direction` form is preferred because it composes cleanly for multi-key sorts.

## Field selection

Request a subset of columns with `fields`. This trims the response payload — useful for list views that only render a few columns. Fields the caller cannot read are omitted regardless of whether they appear in the `fields` list.

```
GET /api/tables/contacts/records?fields=id,name,status
```

## Filtering

Pass a JSON filter expression in the `filter` parameter. A flat object filters by equality on each key:

```
GET /api/tables/tasks/records?filter={"status":"active"}
```

For richer conditions, filters use the same structured form as saved [views](table-views) — a tree of `and`/`or` groups whose leaves are `{ field, operator, value }` conditions:

```yaml
filters:
  and:
    - field: status
      operator: in
      value: [todo, in_progress]
    - field: priority
      operator: equals
      value: high
```

Conditions name a `field`, an `operator` (e.g. `equals`, `in`, `greaterThan`), and a `value`. Operators are resolved per field type.

:::callout
**Prefer saved views for recurring queries.** A view bundles a filter tree, sort order, and field selection under a stable `id`. Reference it with `?view=2` rather than re-encoding the same filter on every request. See [Table Views](table-views).
:::

## Grouping & aggregation

`groupBy` partitions records by a field's value; `aggregate` computes summary functions. Combine them to produce grouped roll-ups (e.g. total amount per status).

```
GET /api/tables/orders/records?groupBy=status
GET /api/tables/orders/records?aggregate=sum:amount,count:id,avg:quantity
```

Each `aggregate` entry is `function:field` — supported functions include `sum`, `count`, `avg`, `min`, and `max`. When paired with `groupBy`, aggregates are computed per group.

## Saved views

A view (`?view=2`) applies its stored filter, sort, and field configuration server-side. Explicit query parameters layer on top of the view, letting a client further narrow a base view without redefining it.

```yaml
tables:
  - id: 1
    name: tasks
    views:
      - id: 2
        name: Active Tasks
        filters:
          and:
            - field: status
              operator: in
              value: [todo, in_progress]
        sorts:
          - field: priority
            direction: desc
```

## Including deleted records

By default, soft-deleted rows are excluded. Use `includeDeleted=true` to merge active and deleted rows, or `includeDeleted=only` for a trash-only view. See [Soft Delete & Restore](records-soft-delete) for the full recovery workflow.

## Related pages

- [Records Overview](records-overview) — list envelope and cross-cutting rules
- [CRUD & Upsert](records-crud) — single-record operations and formatting
- [Table Views](table-views) — saved filter/sort/field configurations
- [Soft Delete & Restore](records-soft-delete) — trash queries

# Batch Operations

Batch endpoints write many records in a single request, so you can import, synchronize, or modify bulk data efficiently — and atomically. Each batch runs in a single transaction: if any record fails validation, the whole batch rolls back and no rows are written. Pass `returnRecords: true` to receive the affected records in the response (otherwise only a summary is returned).

| Method & Path                                     | Operation   | Max per batch |
| ------------------------------------------------- | ----------- | ------------- |
| `POST /api/tables/:tableId/records/batch`         | Create      | 1000          |
| `PATCH /api/tables/:tableId/records/batch`        | Update      | 100           |
| `DELETE /api/tables/:tableId/records/batch`       | Soft delete | 100           |
| `POST /api/tables/:tableId/records/batch/restore` | Restore     | 100           |
| `POST /api/tables/:tableId/records/upsert`        | Upsert      | 100           |

All batch bodies require the canonical envelope form (`{ "fields": { ... } }`) — the flat-body shorthand accepted by single-record create is **not** available in batch requests. Every batch must contain at least one record.

## Batch create

Send a `records` array, each item an envelope. Up to 1000 records per call.

```json
POST /api/tables/contacts/records/batch
{
  "records": [
    { "fields": { "email": "alice@example.com", "name": "Alice" } },
    { "fields": { "email": "bob@example.com", "name": "Bob" } }
  ],
  "returnRecords": true
}
```

| Status             | Meaning                                                                                   |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `201 Created`      | All records created                                                                       |
| `400 Bad Request`  | Empty array, over the 1000 limit, or any record fails validation (whole batch rolls back) |
| `401 Unauthorized` | No active session                                                                         |
| `404 Not Found`    | Table not found or not visible                                                            |

## Batch update

Each item names the record `id` (string or number) plus the `fields` to patch. Up to 100 records per call.

```json
PATCH /api/tables/contacts/records/batch
{
  "records": [
    { "id": "1", "fields": { "status": "active" } },
    { "id": 2, "fields": { "status": "archived" } }
  ],
  "returnRecords": true
}
```

Updates are partial per record — only the named fields are written. If any `id` is missing or any value is invalid, the transaction rolls back.

## Batch delete

Send an `ids` array. Soft delete by default; set `permanent: true` to hard-delete already soft-deleted records (admin-only, enforced in the application layer). Up to 100 IDs per call.

```json
DELETE /api/tables/contacts/records/batch
{
  "ids": ["1", "2", 3],
  "permanent": false
}
```

:::callout
**`permanent` can also be a query string.** Route variants that keep the legacy contract accept `?permanent=true`. The JSON-body form is preferred. Permanent batch delete is irreversible and requires the `permanentDelete` permission — see [Soft Delete & Restore](records-soft-delete).
:::

## Batch restore

Recover many soft-deleted records at once. Records that are not currently deleted are skipped; a missing `id` rolls the whole batch back.

```json
POST /api/tables/contacts/records/batch/restore
{
  "ids": ["1", "2", "3"]
}
```

The restore clears each record's `deletedAt`/`deletedBy` and is logged to the record's [change history](record-history).

## Batch upsert

Create-or-update many records matched on one or more unique fields, in a single transaction. Name the merge key(s) with `fieldsToMergeOn` (alias: `matchFields`). Up to 100 records per call.

```json
POST /api/tables/contacts/records/upsert
{
  "records": [
    { "fields": { "email": "alice@example.com", "name": "Alice" } },
    { "fields": { "email": "carol@example.com", "name": "Carol" } }
  ],
  "fieldsToMergeOn": ["email"],
  "returnRecords": true
}
```

Each record is matched on the merge fields: an existing match is patched, otherwise a new row is created. Batch upsert is the canonical path for idempotent synchronization from an external source of truth.

## Limits & semantics summary

| Property        | Behavior                                                                      |
| --------------- | ----------------------------------------------------------------------------- |
| Atomicity       | Each batch is a single transaction — all-or-nothing                           |
| `returnRecords` | `false` by default; `true` returns the affected records                       |
| Minimum size    | At least one record/ID required (`400` otherwise)                             |
| Authorship      | `createdBy`/`updatedBy`/`deletedBy` stamped per record, same as single writes |
| Permissions     | RBAC and field-level permissions enforced per record                          |

## Related pages

- [CRUD & Upsert](records-crud) — single-record operations and the upsert contract
- [Soft Delete & Restore](records-soft-delete) — permanent delete and restore
- [Record History & Comments](record-history) — batch operations are logged
- [Records Overview](records-overview) — envelope and authorship rules

# Record History & Comments

Every record carries two activity surfaces: an automatic **change history** (a system-maintained audit trail of who changed what and when) and a **comment thread** (user-authored discussion attached to the record). Both are reachable under the record's URL.

| Method & Path                                                       | Description                              |
| ------------------------------------------------------------------- | ---------------------------------------- |
| `GET /api/tables/:tableId/records/:recordId/history`                | Retrieve the change history for a record |
| `GET /api/tables/:tableId/records/:recordId/comments`               | List comments on a record                |
| `GET /api/tables/:tableId/records/:recordId/comments/:commentId`    | Read a single comment                    |
| `POST /api/tables/:tableId/records/:recordId/comments`              | Create a comment                         |
| `PATCH /api/tables/:tableId/records/:recordId/comments/:commentId`  | Edit a comment                           |
| `DELETE /api/tables/:tableId/records/:recordId/comments/:commentId` | Delete a comment                         |

## Change history

History is tracked automatically for all tables — there is nothing to enable. Every create, update, delete, and restore is recorded with the acting user and a structured field-level diff. Read it with:

```
GET /api/tables/orders/records/123/history
```

```json
{
  "history": [
    {
      "id": 1,
      "action": "update",
      "changes": {
        "status": { "from": "pending", "to": "approved" }
      },
      "user": { "id": 1, "name": "Alice" },
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}
```

| Field       | Description                                  |
| ----------- | -------------------------------------------- |
| `action`    | `create`, `update`, `delete`, or `restore`   |
| `changes`   | Per-field `{ from, to }` diff for the change |
| `user`      | The acting user (`id`, `name`)               |
| `timestamp` | ISO 8601 time the change occurred            |

The history records changes from **all** sources — REST API writes, admin edits, automations, and batch operations — so the trail is complete. It complements the per-record [authorship fields](records-overview) (`createdBy`/`updatedBy`/`deletedBy`), which capture the latest actor on the record itself.

:::callout
**Retention and field-tracking config is not yet available.** History is currently tracked automatically for every table with no per-table options. Configurable retention policies and selective field tracking will arrive in a future schema version.
:::

## Comments

Comments are user-authored notes attached to a record, supporting `@mentions`. The current user is injected as the author automatically — you only supply the `content`.

```json
POST /api/tables/orders/records/123/comments
{
  "content": "This looks good! @alice can you confirm the numbers?"
}
```

A successful create returns `201 Created` with the stored comment, including parsed mentions and the resolved author:

```json
{
  "id": 2,
  "content": "This looks good! @alice can you confirm the numbers?",
  "mentions": [{ "userId": 1, "username": "alice", "position": 21 }],
  "author": { "id": 2, "name": "Bob" },
  "created_at": "2025-01-15T11:00:00Z"
}
```

`content` is required and limited to 10,000 characters. `@username` tokens are parsed into a `mentions` array (each with the resolved `userId`, `username`, and character `position`), which downstream features (e.g. [notifications](notifications)) consume.

### Reading comments

```
GET /api/tables/orders/records/123/comments       # list all
GET /api/tables/orders/records/123/comments/2      # single comment
```

The list endpoint returns the comment thread for the record. The author object is projected to a safe display shape (`id`, `name`) — email and other PII are never exposed in comment responses.

### Editing and deleting

```
PATCH  /api/tables/orders/records/123/comments/2
DELETE /api/tables/orders/records/123/comments/2
```

Editing replaces `content` (re-parsing mentions); deleting removes the comment. Both honor RBAC and the table's [permissions](table-permissions) — typically a user may edit/delete their own comments, with broader rights granted to elevated roles.

## Cross-cutting rules

| Concern        | Behavior                                                               |
| -------------- | ---------------------------------------------------------------------- |
| Authentication | All endpoints require a session (`401` otherwise)                      |
| Existence      | Unknown table/record/comment returns `404` (anti-enumeration)          |
| Author safety  | Comment author is server-injected; client-supplied authors are ignored |
| PII            | Author projection exposes only `id` and `name`                         |

## Related pages

- [Records Overview](records-overview) — authorship metadata vs change history
- [CRUD & Upsert](records-crud) — the writes that history records
- [Soft Delete & Restore](records-soft-delete) — delete/restore are logged to history
- [Table Permissions](table-permissions) — who may comment, edit, and delete

# Soft Delete & Restore

Deleting a record is **non-destructive by default**: the row is marked deleted (`deletedAt`/`deletedBy` stamped) and disappears from normal queries, but remains recoverable. This protects against accidental deletion, supports a trash/undo workflow, and keeps an audit trail. Permanent (hard) delete is a separate, permission-gated operation for cases that demand irreversible erasure.

| Method & Path                                                  | Description                   |
| -------------------------------------------------------------- | ----------------------------- |
| `DELETE /api/tables/:tableId/records/:recordId`                | Soft delete a record          |
| `DELETE /api/tables/:tableId/records/:recordId?permanent=true` | Permanently delete a record   |
| `GET /api/tables/:tableId/trash`                               | Browse soft-deleted records   |
| `POST /api/tables/:tableId/records/:recordId/restore`          | Restore a soft-deleted record |
| `POST /api/tables/:tableId/records/batch/restore`              | Restore many records          |

## Soft delete

```
DELETE /api/tables/orders/records/123
```

This sets `deletedAt` to the current time and `deletedBy` to the acting user, then excludes the row from default list and read responses. The operation is logged to the record's [change history](record-history).

## Permanent (hard) delete

```
DELETE /api/tables/orders/records/123?permanent=true
```

Hard delete removes the row irreversibly and requires the `permanentDelete` permission. When force-delete is not allowed for a table, the endpoint returns `404` (anti-enumeration) rather than `403`.

:::callout
**Hard-delete is opt-in and admin-gated.** Reserve `?permanent=true` for genuine erasure needs — e.g. GDPR right-to-erasure on personal data. Financial ledgers and audit-adjacent tables should rely on soft delete only. Permanent delete is an irreversible operation: there is no restore.
:::

## Cascade behavior on related records

When a record is deleted, related records are handled per the relationship field's `onDelete` policy. Configure it on the [relational field](relational-fields).

```yaml
tables:
  - id: 1
    name: orders
    permissions:
      delete: ['admin', 'member']
      permanentDelete: ['admin'] # Permanent delete requires admin role
    fields:
      - id: 1
        name: customer_id
        type: relationship
        relatedTable: customers
        onDelete: cascade # cascade | set-null | restrict
```

| `onDelete` | Effect when the parent is deleted             |
| ---------- | --------------------------------------------- |
| `cascade`  | Delete the dependent (child) records too      |
| `set-null` | Clear the foreign-key reference on dependents |
| `restrict` | Block the delete while dependents exist       |

## Trash view

`GET /api/tables/:tableId/trash` lists soft-deleted records so a UI can present a recoverable bin. The same result is available on the list endpoint via `includeDeleted=only`.

## Restore

```
POST /api/tables/orders/records/123/restore
```

Restore clears `deletedAt` (returning the row to normal queries), stamps a `restored_at`, captures the restoring user, and logs the operation to history.

```json
{
  "id": 123,
  "deleted_at": null,
  "restored_at": "2025-01-15T11:00:00Z"
}
```

| Status             | Meaning                         |
| ------------------ | ------------------------------- |
| `200 OK`           | Record restored                 |
| `400 Bad Request`  | Record is not currently deleted |
| `401 Unauthorized` | No active session               |
| `404 Not Found`    | Record absent or not visible    |

### Batch restore

Recover many records in one transaction. Records that are not currently deleted are skipped; a missing `id` rolls the whole batch back (`404`). See [Batch Operations](records-batch).

```json
POST /api/tables/orders/records/batch/restore
{
  "ids": ["123", "124", "125"]
}
```

## Querying deleted records

By default, soft-deleted rows are excluded from list and read responses. Override with the `includeDeleted` query parameter:

| Value       | Behavior                                                 |
| ----------- | -------------------------------------------------------- |
| _(omitted)_ | Active records only (default)                            |
| `true`      | Active **and** deleted records                           |
| `only`      | Soft-deleted records only (equivalent to the trash view) |

```
GET /api/tables/orders/records?includeDeleted=true
GET /api/tables/orders/records?includeDeleted=only
```

## Permissions summary

| Operation        | Permission                                                                      |
| ---------------- | ------------------------------------------------------------------------------- |
| Soft delete      | `delete` (per [table permissions](table-permissions) + [RBAC](auth-roles-rbac)) |
| Permanent delete | `permanentDelete` (typically admin only)                                        |
| Restore          | `delete` / restore grant for the role                                           |

## Related pages

- [Records Overview](records-overview) — `deletedBy`/`deletedAt` authorship
- [CRUD & Upsert](records-crud) — the single-record delete endpoint
- [Batch Operations](records-batch) — batch delete and restore
- [Relational Fields](relational-fields) — `onDelete` cascade configuration
- [Record History & Comments](record-history) — deletes and restores are logged

# Real-Time Subscriptions

Data-bound page components can stay current without a full reload by subscribing to record changes. A data source declares a `refreshMode` — `static` (the default), `poll`, or `realtime` — and Sovrium does the rest: poll mode re-fetches on an interval, realtime mode opens a WebSocket (with an SSE fallback) and applies `insert`/`update`/`delete` events as they arrive. External integrations can subscribe programmatically through the same endpoints.

| Endpoint                                   | Transport                               |
| ------------------------------------------ | --------------------------------------- |
| `GET /api/tables/:tableSlug/subscribe`     | WebSocket upgrade (per-table)           |
| `GET /api/tables/:tableSlug/subscribe/sse` | Server-Sent Events fallback (per-table) |
| `GET /api/realtime/subscribe`              | Global WebSocket                        |

## refreshMode on a data source

Set `refreshMode` on any component's `dataSource`. The component's existing `filter` and `sort` scope the live stream too — clients only receive changes that still match the data source's criteria.

```yaml
pages:
  - name: Live Dashboard
    path: /dashboard
    components:
      - type: dataTable
        dataSource:
          table: orders
          filter:
            - field: status
              operator: eq
              value: processing
          sort:
            - field: createdAt
              direction: desc
          refreshMode: realtime
```

## Poll mode

Poll mode periodically re-fetches the data source — no WebSocket needed. Use it when near-real-time is sufficient and connection management overhead is undesirable.

```yaml
dataSource:
  table: inventory
  refreshMode: poll
  pollIntervalMs: 10000 # Re-fetch every 10 seconds
```

| Property         | Default        | Constraint                                      |
| ---------------- | -------------- | ----------------------------------------------- |
| `pollIntervalMs` | `30000` (30 s) | Minimum `1000` (1 s) to prevent server flooding |

## Real-time mode (WebSocket)

`refreshMode: realtime` opens a WebSocket to `/api/tables/:tableSlug/subscribe`. The server pushes change events as records are created, updated, or deleted — from **any** source (REST API, admin UI, direct DB writes, automations).

```
GET /api/tables/orders/subscribe
Upgrade: websocket
```

The server then streams messages such as:

```json
{ "type": "change", "event": "insert", "record": { "id": "42", "fields": {  } } }
{ "type": "change", "event": "update", "record": {  }, "oldRecord": {  } }
{ "type": "change", "event": "delete", "recordId": 42 }
{ "type": "heartbeat", "timestamp": "2026-04-05T12:00:00Z" }
```

Insert/update events carry the full `record` (field-permission filtered server-side); delete events carry only `recordId`. The connection requires authentication (`401` on unauthenticated upgrade) and a valid table slug (`404` otherwise).

## Subscription filtering

Subscriptions respect the data source's current `filter` and `sort`, so clients are not flooded with irrelevant events. A change that no longer matches the filter is delivered as the appropriate transition (e.g. an update that moves a row out of the filtered set is surfaced so the client can drop it).

## Message contract

All realtime messages — WebSocket frames and SSE `data:` events use the **identical** format — are a discriminated union keyed on `type`.

| `type`              | Purpose                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `change`            | `insert`/`update`/`delete` mutation; `record`/`oldRecord` use the `{ id, fields }` payload |
| `conflict`          | A concurrent edit overwrote a pending optimistic change (drives the conflict toast)        |
| `heartbeat`         | Keep-alive emitted every `heartbeatIntervalMs`                                             |
| `subscribed`        | Handshake confirmation; echoes the resolved `filter`/`fields`/`subscriptionId`             |
| `unsubscribed`      | Unsubscription confirmation                                                                |
| `join` / `leave`    | A user opened/left a `presence: true` page (scoped by `pagePath`)                          |
| `presence-sync`     | Full presence snapshot sent once on join                                                   |
| `connection-status` | Transport connectivity (`connected` / `reconnecting`)                                      |

The `change` `record` payload mirrors the Records API `{ id, fields }` envelope, so a client can apply an event to a data-bound cache with no shape translation. The `fields` are already field-permission filtered.

:::callout
**Frozen transport constants.** Client and server share `REALTIME_TRANSPORT_CONFIG`: reconnect backoff `[1000, 2000, 4000, 8000]` ms, max reconnect delay `30000` ms, heartbeat `30000` ms, max `10` connections per user, idle timeout `300000` ms, presence-stale timeout `60000` ms, max `50` presence entries per page.
:::

## Presence awareness

When a page sets `presence: true`, the server broadcasts `join`/`leave`/`presence-sync` messages so teams can see who else is viewing the same page or table — reducing accidental conflicts. Presence is scoped by `pagePath`.

## Conflict resolution & optimistic locking

Realtime drives an optimistic-UI flow: the client applies its edit immediately, then reconciles with the server. If a concurrent edit overwrote a pending optimistic change, the server emits a `conflict` message and the canonical (server-wins) value prevails.

A record `PATCH` may carry a top-level `updatedAt` token. When present, the server rejects a stale write with `409 Conflict`. Tables that participate declare an `updated-at` system field so the column auto-bumps on every write — see [CRUD & Upsert](records-crud).

## Connection management

The client auto-reconnects with the configured backoff, sends/expects heartbeats, and falls back to SSE where WebSocket is unavailable — so realtime features work reliably across network conditions.

## Programmatic subscription

External clients open `/api/tables/:tableSlug/subscribe` (or the global `/api/realtime/subscribe`) and send a handshake naming the `table` (and optional `subscriptionId`, `filter`, `fields`). The server replies with a `subscribed` confirmation, then streams `change` events; an unsubscribe yields an `unsubscribed` confirmation.

## Related pages

- [CRUD & Upsert](records-crud) — the optimistic-locking `updatedAt` contract
- [Filtering, Sorting & Pagination](records-filtering-sorting) — the filter/sort that scope a subscription
- [Records Overview](records-overview) — the `{ id, fields }` envelope the stream mirrors
- [Pages Overview](pages-overview) — data-bound components and `dataSource` configuration

# Records Import & Export

Sovrium moves bulk data in and out of tables three ways: **CSV import** (upload a file to bulk-create records), **export** (download the current view as CSV or JSON), and **clipboard** (copy/paste rows between a data-table and a spreadsheet). Import and export are built-in native behavior on every table — no configuration required.

:::callout
**Status: planned.** The CSV import/export endpoints below are a designed, not-yet-shipped surface (the import/export user stories are `Not Started`). Clipboard paste/copy is built on the existing [batch](records-batch) and [list](records-filtering-sorting) endpoints. This page documents the intended API; the concrete request/response shapes are finalized during implementation.
:::

## CSV import

Upload a CSV file to bulk-load records, with column-to-field mapping, configurable duplicate handling, and per-row error reporting on partial failures.

```
POST /api/tables/:tableId/import
Content-Type: multipart/form-data

Body:
  file              (CSV file)
  mapping           (JSON: { "csvColumn": "tableField" })
  duplicateStrategy ("skip" | "overwrite" | "create")
  uniqueField       (field used to detect duplicates)
```

The response summarizes the outcome and reports per-row errors without failing the whole import:

```json
{
  "imported": 120,
  "skipped": 4,
  "updated": 11,
  "failed": 2,
  "errors": [
    { "row": 17, "field": "email", "error": "Invalid email format" },
    { "row": 92, "field": "amount", "error": "Expected a number" }
  ]
}
```

| Concept                        | Behavior                                                                      |
| ------------------------------ | ----------------------------------------------------------------------------- |
| Column mapping                 | `mapping` maps each CSV column to a table field; unmapped columns are ignored |
| `duplicateStrategy: skip`      | Skip rows whose `uniqueField` already exists                                  |
| `duplicateStrategy: overwrite` | Update the existing matching record                                           |
| `duplicateStrategy: create`    | Always insert a new record                                                    |
| Partial failure                | Valid rows are imported; invalid rows are reported in `errors`                |

Imported records pass the same field-type [validation](table-validation) and field-level [permissions](table-permissions) as a normal create.

## Export

Export the current view of a table — all visible rows, a hand-picked selection, or the same data as JSON for developer tooling.

```
GET /api/tables/:tableId/export?format=csv&viewId=2&filters=JSON&fields=id,name,status
GET /api/tables/:tableId/export?format=json&fields=id,name,status
GET /api/tables/:tableId/export?format=csv&recordIds=1,2,3&fields=id,name,status
```

The response streams the file with an attachment disposition:

```
Content-Type: text/csv            (or application/json)
Content-Disposition: attachment; filename="orders.csv"
```

| Parameter   | Description                                                                          |
| ----------- | ------------------------------------------------------------------------------------ |
| `format`    | `csv` (default) or `json`                                                            |
| `viewId`    | Export the rows of a saved [view](table-views)                                       |
| `filters`   | JSON filter expression (same grammar as [list filtering](records-filtering-sorting)) |
| `fields`    | Comma-separated columns to include                                                   |
| `recordIds` | Export only the named record IDs (a hand-picked selection)                           |

Export honors field-level read permissions — columns the caller cannot read are omitted from the file.

## Clipboard

The data-table component supports spreadsheet-style copy and paste, built on the standard Records endpoints.

| Action        | Behavior                                                            | Underlying endpoint                       |
| ------------- | ------------------------------------------------------------------- | ----------------------------------------- |
| Paste rows    | Paste tab-separated data from Excel/Google Sheets into a data-table | `POST /api/tables/:tableId/records/batch` |
| Paste preview | Preview pasted data with column mapping before committing           | (client-side, then batch create)          |
| Copy rows     | Select rows and copy as tab-separated values to the clipboard       | `GET /api/tables/:tableId/records`        |

Paste maps tab-separated columns onto table fields (with a preview/mapping step so the user can confirm before write), then commits via a single [batch create](records-batch) — keeping the operation atomic. Copy serializes the selected rows' visible columns to TSV.

## Related pages

- [Batch Operations](records-batch) — the atomic bulk-write path clipboard paste uses
- [Filtering, Sorting & Pagination](records-filtering-sorting) — the filter/field grammar export reuses
- [Table Views](table-views) — export a saved view by `viewId`
- [Table Validation](table-validation) — import rows pass field-type validation
- [Table Permissions](table-permissions) — field-level read/write gates import and export

# Runtime Data Customization

Developers declare the data model and the pages; **end users** shape how they see the data. Sovrium gives every data-bound view a set of built-in, runtime customization behaviors — filtering, sorting, grouping, column visibility, saved views, and CSV import/export — so users can tailor their workspace without a developer changing the config.

These behaviors are **native platform features**, not schema properties. The moment you render a [`data-table`](/en/data-components) over a table, the runtime customization surface comes with it. There is nothing to enable in `app.yaml` beyond the component itself; toolbar affordances control which controls are surfaced.

:::callout
**Two layers of views.** Developers define _config views_ on a table's `views` array ([Views](/en/table-views)) — the curated, named starting points. End users layer their own _runtime views_ on top, saved per-user. The two coexist: a user can start from a developer view and refine it without touching the config.
:::

## Runtime views

When a data-table is rendered, users can adjust the result set live:

| Capability        | What the user can do                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------ |
| Filter            | Build filter conditions in the toolbar; conditions stack with the developer's base filter. |
| Sort              | Reorder by one or more columns ascending/descending.                                       |
| Group             | Group rows by a field value into collapsible sections.                                     |
| Column visibility | Show/hide columns via a toggle (surfaced with `toolbar: { columnVisibility: true }`).      |
| Saved views       | Save the current filter + sort + field selection as a named, reusable view.                |
| Share             | Share a saved view with other users.                                                       |

Runtime filters and sorts are applied through the same Records API query layer documented in [Filtering & Sorting](/en/records-filtering-sorting) — the UI composes the `filter`, `sort`, `fields`, and `groupBy` parameters that the server already understands. A saved view persists that composition under a stable identifier so it can be re-applied with a single click.

The developer-facing entry point is the `data-table` component and its `view`, `filter`, `sort`, `toolbar`, and `groupBy` properties:

```yaml
components:
  - type: data-table
    dataSource:
      table: contacts
    view: active-customers # optional developer-defined starting view
    toolbar:
      columnVisibility: true # surface the column-visibility toggle
```

See [Data Components → data-table](/en/data-components) for the full property reference and [Views](/en/table-views) for developer-defined config views.

## CSV import & export

Users can move tabular data in and out of a table without leaving the page:

- **Export** the full table or just the selected rows to a CSV file.
- **Import** a CSV through a mapping wizard that pairs spreadsheet columns to table fields.

Import and export honor the same field-level permissions as the rest of the Records API — a user only exports fields they may read, and only imports into fields they may write. The underlying API paths are documented in [Import & Export](/en/records-import-export).

## Clipboard operations

Data tables support spreadsheet-style clipboard interactions: copy one or more rows and paste them — including pasting rows copied from an external spreadsheet — with a paste preview before the change is committed. This makes bulk edits feel like working in a spreadsheet while still running every write through the permission-checked Records API.

## Permissions still apply

Runtime customization never widens access. Every runtime view, export, import, and clipboard paste runs through the table's RBAC and field-level permissions. A user personalizing their workspace can only filter, read, write, and share data they are already authorized to access — and unauthorized record access returns `404` (anti-enumeration), exactly as documented in [Records Overview](/en/records-overview).

## Related Pages

- [Data Components](/en/data-components) — the `data-table` and other components that expose runtime customization.
- [Views](/en/table-views) — developer-defined config views that runtime views build on.
- [Filtering & Sorting](/en/records-filtering-sorting) — the Records API query layer behind runtime filters and sorts.
- [Import & Export](/en/records-import-export) — the CSV import/export API.
- [Records Overview](/en/records-overview) — permissions and the `404` anti-enumeration rule that runtime customization respects.

# Pages Overview

Pages are server-rendered (SSR) using a declarative component tree. Each page declares a `name`, a `path`, optional SEO `meta`, and a `components` array of nested components. Pages render your tables' records, host forms that write to them, embed interactive islands, and expose public-facing content — all from configuration, no custom React required.

A page needs at minimum a `name` and a `path`. Everything else — metadata, access control, scripts, dynamic collection routes, markdown content, view transitions, and per-page toasts — is optional and layered on top.

```yaml
pages:
  - name: Home
    path: /
    meta:
      title: Welcome
      description: The fastest way to ship internal tools.
    components:
      - type: hero
        content: Build apps from config
      - type: container
        children:
          - { type: text, content: 'Get started in minutes.' }
```

## Page Properties

Each entry in the `pages` array accepts the following properties.

| Property         | Description                                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | Optional unique identifier for the page. Auto-generated when omitted.                                                                                        |
| `name`           | Human-readable page name (used in navigation and admin listings).                                                                                            |
| `path`           | URL route. Static (`/about`), root (`/`), or dynamic with a `:param` segment (`/blog/:slug`). See [Routing](#routing).                                       |
| `meta`           | SEO and document-head metadata: title, description, Open Graph, Twitter cards, favicons, structured data. See [SEO & Metadata](/en/seo-meta).                |
| `components`     | Array of component definitions forming the page's render tree. See [the component model](#the-component-model).                                              |
| `access`         | Access control: `'all'` (public), `'authenticated'`, a role array `['admin']`, or `{ require, redirectTo }`. Defaults to `'all'`.                            |
| `collection`     | Template configuration that generates one route per table record (dynamic pages). See [Collection Pages](#collection-pages).                                 |
| `markdown`       | Render the entire page body from a markdown file or inline string, with layout and table-of-contents options. See [Markdown Pages](#markdown-pages).         |
| `source`         | File-based content source (`source.file`) for a `content` component — loads markdown from disk with frontmatter. Mutually exclusive with `content`.          |
| `layout`         | Named layout sections (e.g. a data-bound `sidebar`) wrapping the page body. See [Layouts & Sidebars](#layouts--sidebars).                                    |
| `scripts`        | Client-side scripts, feature flags, external dependencies, and config data injected into the page. See [Interactivity & Scripts](/en/interactivity-scripts). |
| `vars`           | Page-scoped variables (`key`/`value` pairs) referenceable via `$vars.*` in component templates.                                                              |
| `toasts`         | Page-level toast notification config (position, default duration).                                                                                           |
| `viewTransition` | Page navigation animation: `fade`, `slide` (with `direction`), or `none`, plus `duration`.                                                                   |
| `sitemap`        | Per-page sitemap entry (priority, change frequency) or `false` to exclude the page from the sitemap.                                                         |
| `rss`            | Enable an RSS feed for a collection page — `true` for defaults, or `{ limit }` to cap item count.                                                            |

```yaml
pages:
  - name: About
    path: /about
    access: all
    meta: { title: 'About Us' }
    viewTransition: { type: fade, duration: 200 }
    components:
      - { type: text, tag: h1, content: 'About' }
```

## Routing

The `path` property declares the URL where a page is served.

| Path form     | Example       | Description                                                                 |
| ------------- | ------------- | --------------------------------------------------------------------------- |
| Root          | `/`           | The home page.                                                              |
| Static        | `/about`      | A fixed route.                                                              |
| Nested static | `/checkout`   | Any number of static segments.                                              |
| Dynamic       | `/blog/:slug` | A `:param` segment captures a value available to the page as a route param. |
| Record id     | `/tasks/$id`  | Dynamic detail routes resolve the matching record into `$record.*`.         |

Dynamic routes are most often paired with a `collection` block so one page definition generates a route per record. See [Collection Pages](#collection-pages).

## The Component Model

A page's `components` array is a tree. Every component has a `type` (one of ~80 built-in component types) and a set of properties. Components compose through a shared module system, so the same cross-cutting properties are available almost everywhere:

| Shared property | Available on              | Description                                                                                                       |
| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `props`         | Almost all components     | Key-value bag of styling/config attributes rendered as HTML attributes (e.g. `className`, `variant`).             |
| `content`       | Content/layout components | Inline text or markdown; supports `$record.*`, `$vars.*`, and `$t:key` (translation) substitution.                |
| `children`      | Container-like components | Nested child component definitions.                                                                               |
| `dataSource`    | Data-bound components     | Binds the component to a table (filter, sort, pagination, single/search mode). See [Data Binding](#data-binding). |
| `visibility`    | Most components           | Conditional display based on auth state — server-rendered, hidden client-side when conditions are unmet.          |
| `responsive`    | Most components           | Per-breakpoint overrides for responsive behavior.                                                                 |
| `interactions`  | Interactive components    | Click actions, hover effects, and entrance animations. See [Interactivity & Scripts](/en/interactivity-scripts).  |
| `action`        | Form/button components    | Behavior to run on interaction — `crud`, `auth`, `navigate`, `automation`, with `onSuccess`/`onError` handlers.   |
| `i18n`          | Content components        | Localized content variants per language.                                                                          |

:::callout
**Variable substitution.** Component `content` and `props` values resolve three reference families at render time: `$record.<field>` (current data-source record), `$vars.<key>` / `$currentUser.<path>` (page and session context), and `$t:key` (translation keys, with fallback). The page-level `markdown` source additionally exposes `$frontmatter.*`.
:::

Components are grouped into categories, each documented on its own page:

| Category                                             | Examples                                                                                         |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [Layout](/en/layout-components)                      | hero, container, flex, grid, responsiveGrid, card, sidebar, modal, tab-panel                     |
| [Content](/en/content-components)                    | text, code, toc, accordion, blockquote, alert, custom-html                                       |
| [Data](/en/data-components)                          | data-table, list, gallery, kanban, calendar, chart, kpi, timeline                                |
| [Form Controls](/en/form-controls)                   | input, textarea, select, checkbox, radio, switch, slider, date-picker, file-upload, number-input |
| [Overlays](/en/overlay-components)                   | dialog, drawer, popover, tooltip, hover-card, alert-dialog, toast, progress, skeleton            |
| [Navigation](/en/navigation-components)              | navigation-menu, dropdown-menu, breadcrumb, tabs, pagination, toggle, button-group, menubar      |
| [Media](/en/media-components)                        | image, icon, video, audio, iframe, carousel, aspect-ratio                                        |
| [Display](/en/display-components)                    | static-table, command, empty-state, resizable, scroll-area, speech-bubble, status-indicator      |
| [Feedback](/en/feedback-components)                  | progress, spinner, skeleton                                                                      |
| [Interactive](/en/interactive-components)            | button, link, alert, badge, button-group                                                         |
| [Specialty](/en/specialty-components)                | wizard, reorderable-list, language-switcher, comments, ai-chat                                   |
| [Social](/en/social-components)                      | comments, commentCount, ai-chat, sharing                                                         |
| [SEO & Metadata](/en/seo-meta)                       | title, description, Open Graph, Twitter cards, JSON-LD, favicons                                 |
| [Interactivity & Scripts](/en/interactivity-scripts) | scripts, interactions, auto-save, custom-html                                                    |

## Data Binding

Bind any data component (or container) to a table with `dataSource`. The bound records expose their fields to descendants through `$record.<field>` references.

| `dataSource` property | Description                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `table`               | Table name to bind to (validated against `app.tables`).                                                                           |
| `fields`              | Specific fields to fetch (omit to fetch all).                                                                                     |
| `filter`              | Array of `{ field, operator, value }` conditions combined with AND. Operators: `eq`, `neq`, `contains`, `gt`, `lt`, `gte`, `lte`. |
| `sort`                | Array of `{ field, direction }` rules applied in order (primary, secondary).                                                      |
| `pagination`          | `{ pageSize, style }` — `style: numbered` renders page navigation; `style: loadMore` renders a Load More button.                  |
| `mode`                | `single` resolves one record by a route `param`; `search` filters across `searchFields` with `debounce` and `maxResults`.         |
| `id`                  | Identifier for cross-component data-source references.                                                                            |

```yaml
- type: data-table
  dataSource:
    table: tasks
    filter:
      - { field: status, operator: neq, value: archived }
    sort:
      - { field: created_at, direction: desc }
    pagination: { pageSize: 25, style: numbered }
```

:::callout
**Current-user scoping.** `$currentUser.*` resolves per-request during SSR (never cached across users): `$currentUser.id`, `$currentUser.role`, `$currentUser.email`, `$currentUser.isUnrestricted` (global-admin bypass), and `$currentUser.assignments.<table>` (flattened record ids the user is assigned to). Pages using `$currentUser` return `401` when accessed unauthenticated.
:::

## Collection Pages

A `collection` block turns one page definition into a route per table record. The page's `path` must include a dynamic `:param` segment matching `slugField`.

| `collection` property | Description                                                                             |
| --------------------- | --------------------------------------------------------------------------------------- |
| `table`               | Table name to generate collection pages from (must exist in `app.tables`).              |
| `slugField`           | Field whose value becomes the URL parameter (e.g. `slug`, `id`).                        |
| `filter`              | Optional `{ field, operator, value }` conditions limiting which records generate pages. |

```yaml
pages:
  - name: Blog Post
    path: /blog/:slug
    collection:
      table: posts
      slugField: slug
      filter:
        - { field: published, operator: eq, value: true }
    rss: { limit: 20 }
    components:
      - { type: text, tag: h1, content: '$record.title' }
      - { type: text, content: '$record.body', props: { format: markdown } }
```

A request to `/blog/123` that does not match any record returns a `404`.

## Markdown Pages

Render a whole page from markdown — either inline or from a file — with frontmatter, layout, and an auto-generated table of contents.

| `markdown` property | Description                                                                                                      |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `content`           | Inline markdown string.                                                                                          |
| `file`              | Path to a markdown file (e.g. `content/docs.md`), resolved from project root. Mutually exclusive with `content`. |
| `layout`            | Wrapper style: `prose` (default), `docs`, `full`, or `none`.                                                     |
| `toc`               | Table-of-contents config — `true` for defaults, or `{ maxDepth, position }` (`inline` or `sidebar`).             |

YAML frontmatter (between `---` delimiters) is parsed and exposed as `$frontmatter.*` in `meta` and sibling properties. Markdown HTML is sanitized to prevent XSS (consistent with the `text`/`alert` content components).

```yaml
pages:
  - name: Docs Home
    path: /docs
    markdown:
      file: content/docs/home.md
      layout: docs
      toc: { maxDepth: 3, position: sidebar }
```

For the `contentDir` collection (one page per markdown file in a directory, with a derived sidebar), use a `content` component with a `contentDir` source:

| `contentDir` property | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `directory`           | Directory containing markdown content files.                                   |
| `slugFrom`            | Derive URL slug from `filename` or `filepath`.                                 |
| `include`             | Glob pattern to filter files (e.g. `*.md`).                                    |
| `sort`                | `{ field, order }` — sort by a frontmatter field (e.g. `date`, `desc`).        |
| `filter`              | Filter conditions on frontmatter fields.                                       |
| `nav`                 | Sidebar config derived from the collection: `{ enabled, groupBy, labelFrom }`. |

## Layouts & Sidebars

The `layout` property wraps the page body in named sections. The most common is a data-bound `sidebar` rendered inside the page `<aside>`.

| Sidebar section property | Description                                                                   |
| ------------------------ | ----------------------------------------------------------------------------- |
| `dataSource`             | Binds entries to a table with `{ table, filter, sort }`.                      |
| `label`                  | Per-record label expression (supports `$record.<field>`).                     |
| `href`                   | Per-record anchor href (supports `$record.<field>`).                          |
| `archivedField`          | Field whose truthy value hides an entry from the sidebar.                     |
| `activeIndicator`        | Highlights the entry matching the active scope (e.g. tenant-switcher cookie). |

A scoped sidebar bound to `$currentUser.assignments.<table>` renders one entry per assigned record; a global admin (`isUnrestricted=true`) sees all records.

## Access Control

The `access` property gates a page:

| Form                                                 | Meaning                                                    |
| ---------------------------------------------------- | ---------------------------------------------------------- |
| `'all'`                                              | Everyone, including unauthenticated visitors (default).    |
| `'authenticated'`                                    | Any logged-in user.                                        |
| `['admin', 'editor']`                                | Specific role names.                                       |
| `{ require: 'authenticated', redirectTo: '/login' }` | Redirect unauthorized users instead of returning an error. |

## Related Pages

- [Layout Components](/en/layout-components) — structural building blocks.
- [Content Components](/en/content-components) — text, code, callouts, accordions.
- [Data Components](/en/data-components) — tables, lists, charts, KPIs bound to your data.
- [Form Controls](/en/form-controls) — inputs, selects, pickers, toggles.
- [SEO & Metadata](/en/seo-meta) — document head, social cards, structured data.
- [Interactivity & Scripts](/en/interactivity-scripts) — actions, animations, auto-save.
- [Tables Overview](/en/tables-overview) — the data models pages render.
- [Forms](/en/forms-overview) — standalone form definitions.
- [Search](/en/search-overview) — full-text and public search configuration.
- [Theme](/en/theme) — design tokens consumed by component styling.

# Layout Components

Layout components arrange the page. They define the visual skeleton — full-width heroes, centered containers, flex and grid tracks, cards, sidebars, and modals — and host other components as `children`. Every layout component accepts the shared `props` bag (rendered as HTML attributes such as `className`), plus `responsive`, `visibility`, and `i18n` modules. Container-like components additionally accept `children`.

```yaml
components:
  - type: hero
    content: Ship internal tools from config
    props: { className: 'bg-primary text-white py-24' }
  - type: container
    props: { className: 'max-w-4xl mx-auto px-6' }
    children:
      - type: grid
        props: { className: 'grid-cols-3 gap-6' }
        children:
          - { type: card, children: [{ type: text, content: 'Fast' }] }
```

## `hero`

A full-width banner section, typically the first block on a landing page. Renders `content` as its headline and accepts `children` for CTAs and supporting content.

| Property       | Description                                                                     |
| -------------- | ------------------------------------------------------------------------------- |
| `content`      | Headline text (supports `$record.*`, `$vars.*`, `$t:key` substitution).         |
| `children`     | Nested components rendered inside the hero (subtitles, buttons, media).         |
| `props`        | HTML attributes — typically `className` for background, padding, and alignment. |
| `interactions` | Click/hover/entrance behaviors (e.g. an entrance animation on load).            |
| `responsive`   | Per-breakpoint overrides.                                                       |
| `visibility`   | Conditional display based on auth state.                                        |

## `container`

A generic block-level wrapper. Use it to constrain width, apply padding, and group children.

| Property   | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `element`  | HTML element to render. Defaults to `div` (e.g. `section`, `main`, `article`). |
| `children` | Nested component definitions.                                                  |
| `content`  | Optional inline content rendered when no `children` are present.               |
| `props`    | HTML attributes (e.g. `className`).                                            |

## `flex`

A flexbox container. Lay out children in a row or column with gap, alignment, and wrapping controlled via Tailwind classes in `props.className`.

| Property     | Description                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `children`   | Nested components arranged along the flex axis.                                                   |
| `props`      | HTML attributes — set `className` to `flex flex-row`/`flex-col`, `gap-*`, `items-*`, `justify-*`. |
| `responsive` | Per-breakpoint direction/alignment overrides.                                                     |

## `grid`

A CSS grid container with fixed column tracks. Children flow into the grid cells.

| Property   | Description                                                                      |
| ---------- | -------------------------------------------------------------------------------- |
| `children` | Nested components placed into grid cells.                                        |
| `props`    | HTML attributes — set `className` to `grid grid-cols-*`, `gap-*`, `auto-rows-*`. |

## `responsiveGrid`

A grid whose column count adapts per breakpoint. Prefer this over `grid` when you want declarative responsive columns without hand-writing breakpoint classes.

| Property     | Description                                            |
| ------------ | ------------------------------------------------------ |
| `children`   | Nested components placed into the responsive grid.     |
| `responsive` | Per-breakpoint column counts (mobile, sm, md, lg, xl). |
| `props`      | HTML attributes (e.g. `gap-*`).                        |

## `card`

A bordered, padded surface for grouping related content. Commonly used in grids and galleries.

| Property       | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `children`     | Nested components rendered inside the card body.                  |
| `content`      | Optional inline content when no `children` are provided.          |
| `props`        | HTML attributes — `className` for elevation, radius, and padding. |
| `interactions` | Click/hover effects (e.g. hover elevation, navigate on click).    |

## `sidebar`

A vertical navigation panel, typically paired with a `container` main region to form an app-shell layout. Can be statically composed from `children` or data-bound through the page `layout.sidebar` config (see [Pages Overview → Layouts & Sidebars](/en/pages-overview#layouts--sidebars)).

| Property     | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `children`   | Navigation items and sections rendered as a vertical menu.                   |
| `props`      | HTML attributes — `className` for width and positioning (fixed-width panel). |
| `visibility` | Conditional display (e.g. hide for unauthenticated users).                   |

## `modal`

A dialog overlay opened by an interaction trigger. The `modal` layout component holds the dialog body; open it via a button's `interactions.onClick` with `modalId`. (For confirmation-style overlays, see [`dialog`/`alert-dialog`](/en/overlay-components).)

| Property   | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `id`       | Identifier targeted by an opening trigger (`onClick.modalId`). |
| `children` | Nested components rendered inside the modal panel.             |
| `props`    | HTML attributes (e.g. `className` for panel sizing).           |

Clicking the backdrop or pressing Escape closes the modal; focus is trapped within the modal while open.

## `tab-panel`

A single panel within a `tabs` container. Each panel has a trigger label and its own content/children. See [`tabs`](/en/navigation-components#tabs) for the container.

| Property   | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `label`    | Text shown on the tab trigger button.                                      |
| `content`  | Inline text content of the panel (omit when the panel renders `children`). |
| `children` | Nested components rendered inside the panel.                               |

## `divider`

A horizontal rule separating sections of content.

| Property      | Description                                     |
| ------------- | ----------------------------------------------- |
| `props.style` | Line style: `solid`, `dashed`, or `dotted`.     |
| `props.label` | Centered text rendered within the divider line. |
| `props`       | Additional HTML attributes (e.g. `className`).  |

## `spacer`

Vertical whitespace between blocks.

| Property     | Description                                    |
| ------------ | ---------------------------------------------- |
| `props.size` | Spacing preset: `sm`, `md`, `lg`, or `xl`.     |
| `props`      | Additional HTML attributes (e.g. `className`). |

```yaml
components:
  - { type: text, tag: h2, content: 'Section A' }
  - { type: spacer, props: { size: lg } }
  - { type: divider, props: { style: dashed, label: 'or' } }
  - { type: text, tag: h2, content: 'Section B' }
```

## Related Pages

- [Pages Overview](/en/pages-overview) — page structure, routing, and the component model.
- [Content Components](/en/content-components) — text, code, callouts, accordions.
- [Navigation Components](/en/navigation-components) — tabs, breadcrumbs, menus.
- [Overlay Components](/en/overlay-components) — dialogs, drawers, popovers.
- [Theme](/en/theme) — design tokens consumed by `className` styling.

# Content Components

Content components render text and prose. They cover rich text and markdown, code blocks with syntax highlighting, collapsible accordions, styled callouts, blockquotes, an auto-generated table of contents, and the page-level search-input UI. All content components support variable substitution in their `content` (`$record.*`, `$vars.*`, `$t:key`) and accept the shared `props` bag, plus `visibility`, `responsive`, and `i18n` modules.

```yaml
components:
  - type: text
    tag: h1
    content: Getting Started
  - type: text
    content: '$record.body'
    props: { format: markdown }
  - type: alert
    props: { variant: info, dismissible: true }
    content: 'Heads up — this is a callout.'
```

## `text`

The primary content component. Renders inline text, a semantic element (heading, paragraph, blockquote), or full markdown. The same `text` type covers headings, paragraphs, code blocks, and blockquotes via its `tag`/`props`.

| Property            | Description                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `content`           | Text or markdown source (supports `$record.*`, `$vars.*`, `$t:key`).                                           |
| `tag`               | Semantic element: `h1`–`h6`, `p`, `span`, `blockquote`, `code`, etc.                                           |
| `props.format`      | Set to `markdown` to render `content` as sanitized HTML (headings, bold, italic, links, images, nested lists). |
| `props.language`    | When `tag: code`, the language for syntax highlighting.                                                        |
| `props.lineNumbers` | When `tag: code`, set `true` to display line numbers.                                                          |
| `props.cite`        | When `tag: blockquote`, the citation source URL.                                                               |
| `props`             | Additional HTML attributes (e.g. `className`).                                                                 |

Markdown output is sanitized to prevent XSS (no `<script>` tags or event-handler attributes). Code blocks include a copy-to-clipboard button.

## `code`

A standalone code block (equivalent to `text` with `tag: code`, exposed as its own type for clarity).

| Property            | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `content`           | The code source.                                              |
| `props.language`    | Language for syntax highlighting (e.g. `ts`, `yaml`, `bash`). |
| `props.lineNumbers` | Display line numbers alongside the code.                      |
| `props`             | Additional HTML attributes.                                   |

## `toc`

Auto-generates a table of contents from the page's heading hierarchy. Clicking a link smooth-scrolls to the heading anchor; the active section is highlighted based on scroll position.

| Property       | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `props.sticky` | Set `true` to keep the TOC fixed to the viewport on scroll. |
| `props`        | Additional HTML attributes (e.g. `className`).              |

## `accordion`

Collapsible content sections, each with a summary trigger and a detail panel.

| Property            | Description                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `children`          | Accordion items (each with a summary label and detail content).                           |
| `props.mode`        | `single` collapses other sections when one opens; `multiple` allows several open at once. |
| `props.defaultOpen` | Set `true` to render a section expanded on page load.                                     |
| `props`             | Additional HTML attributes.                                                               |

## `blockquote`

A styled quotation block (equivalent to `text` with `tag: blockquote`). Nested blockquotes render with increasing indentation.

| Property     | Description                 |
| ------------ | --------------------------- |
| `content`    | The quoted text.            |
| `props.cite` | Citation source URL.        |
| `props`      | Additional HTML attributes. |

## `alert`

A styled callout block for highlighting information.

| Property            | Description                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `content`           | The alert message (supports substitution).                                                                |
| `props.variant`     | Visual style: `info`, `warning`, `error`, or `success` — each auto-selects an appropriate icon and color. |
| `props.dismissible` | Set `true` to render a close button that hides the alert.                                                 |
| `props`             | Additional HTML attributes.                                                                               |

## `searchInput`

A page-level search-input control that drives client-side filtering of a bound list or table. (The full-text _engine_ configuration — indexing, weights, public search — lives in the [Search](/en/search-overview) section; this is the UI building block.)

| Property            | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `props.placeholder` | Placeholder text shown in the search field.                                   |
| `props.debounceMs`  | Debounce delay before the search fires (results update live after the delay). |
| `props.minLength`   | Minimum query length before searching (prevents empty/short searches).        |
| `dataSource`        | Optional binding when the input filters a `search`-mode data source.          |

## `pageSearch`

A page-scoped search experience composed of an input plus a results region, bound to a searchable table. Use for in-page filtering of records.

| Property            | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `dataSource`        | Table binding in `search` mode (`searchFields`, `debounce`, `maxResults`). |
| `props.placeholder` | Placeholder for the search field.                                          |
| `children`          | Optional result-template components.                                       |

:::callout
**Markdown content vs. markdown pages.** A `text` component with `props.format: markdown` renders a _fragment_ of markdown inline. To render an _entire page_ from a markdown file (with frontmatter, layout, and TOC), use the page-level `markdown` property — see [Pages Overview → Markdown Pages](/en/pages-overview#markdown-pages).
:::

## Related Pages

- [Pages Overview](/en/pages-overview) — page structure and variable substitution.
- [Layout Components](/en/layout-components) — containers, grids, cards.
- [Media Components](/en/media-components) — images, video, icons, embeds.
- [Search](/en/search-overview) — full-text search engine and public search.
- [Search Components](/en/search-components) — search UI building blocks (in the Search section).
- [SEO & Metadata](/en/seo-meta) — document head and structured data.

# Data Components

Data components render records from your tables. Each binds to a table through the shared `dataSource` module (`table`, `filter`, `sort`, `pagination`, `mode`) and renders the matching records as a table, list, gallery, kanban board, calendar, chart, KPI, or timeline. Record fields are referenced with `$record.<field>` in templates. See [Pages Overview → Data Binding](/en/pages-overview#data-binding) for the full `dataSource` contract.

```yaml
components:
  - type: data-table
    dataSource: { table: tasks, sort: [{ field: due_date, direction: asc }] }
    columns:
      - { field: title, sortable: true }
      - { field: status, format: badge }
      - { field: due_date, format: relative-date }
```

## `data-table`

A feature-rich table with sorting, filtering, grouping, selection, bulk actions, summaries, and inline editing.

| Property       | Description                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `dataSource`   | Table binding (filter/sort applied server-side with AND logic).                                             |
| `view`         | Name of a saved [table view](/en/table-views) to inherit filters, sorts, and visible fields.                |
| `columns`      | Column definitions (see below). Auto-generated from table fields when omitted.                              |
| `filter`       | Additional filter conditions stacked on top of view filters.                                                |
| `sort`         | Default sort rules (initial state, or applied when no view sorts exist).                                    |
| `rowHeight`    | Row height preset (default: `medium`).                                                                      |
| `striped`      | Alternating row colors (default: `false`).                                                                  |
| `bordered`     | Show cell borders (default: `false`).                                                                       |
| `rowNumbers`   | Show a row-number column (default: `false`).                                                                |
| `emptyMessage` | Message displayed when no records match.                                                                    |
| `toolbar`      | Toolbar controls — e.g. `{ columnVisibility: true }` to show a column-visibility toggle.                    |
| `selection`    | Row selection config (see below).                                                                           |
| `bulkActions`  | Actions available when rows are selected (see below).                                                       |
| `groupBy`      | Row grouping config (see below).                                                                            |
| `summary`      | Summary row with aggregate computations (see below).                                                        |
| `autoSave`     | Inline-edit save behavior — see [Interactivity & Scripts → Auto-Save](/en/interactivity-scripts#auto-save). |

### `columns`

Each entry defines one column.

| Property            | Description                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `field`             | Field name from the data-source table.                                                                   |
| `label`             | Header label override (defaults to the field's display name).                                            |
| `width`             | Column width in pixels.                                                                                  |
| `minWidth`          | Minimum column width in pixels.                                                                          |
| `align`             | Text alignment: `left` (default), `center`, `right`.                                                     |
| `format`            | Display format override for cell rendering (e.g. `badge`, `currency`, `relative-date`).                  |
| `pinned`            | Pin the column to the left side of the table.                                                            |
| `sortable`          | Allow sorting on this column (default: `true`).                                                          |
| `filterable`        | Allow filtering on this column (default: `true`).                                                        |
| `editable`          | Allow inline editing (defaults to the table's permissions).                                              |
| `hidden`            | Column visibility (default: `true` = visible).                                                           |
| `conditionalStyles` | Rules `{ when: { operator: value }, className }` applying Tailwind classes when a cell condition is met. |
| `actions`           | Action buttons (e.g. edit/delete) with `label`, `icon`, and a confirm message (supports `{count}`).      |

### `selection`

| Property       | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `mode`         | `none` (default), `single`, or `multiple`.                        |
| `showCheckbox` | Show a checkbox column (default: `true` when mode is `multiple`). |

### `bulkActions`

| Property  | Description                                                                      |
| --------- | -------------------------------------------------------------------------------- |
| `label`   | Bulk-action button label.                                                        |
| `icon`    | Lucide icon name (e.g. `truck`, `trash`).                                        |
| `confirm` | Confirmation dialog message; supports `{count}` for the number of selected rows. |
| `action`  | The action invoked on the selected rows.                                         |

### `groupBy`

| Property    | Description                                |
| ----------- | ------------------------------------------ |
| `field`     | Field to group rows by.                    |
| `direction` | Group sort direction (default: `asc`).     |
| `collapsed` | Start groups collapsed (default: `false`). |
| `hideEmpty` | Hide empty groups (default: `false`).      |

### `summary`

| Property    | Description                                               |
| ----------- | --------------------------------------------------------- |
| `field`     | Field to compute the summary on.                          |
| `aggregate` | Aggregate function (`sum`, `avg`, `count`, `min`, `max`). |

## `list`

A vertical list of records, each rendered from a template using `$record.*` references.

| Property            | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `dataSource`        | Table binding.                                                 |
| `template.title`    | Primary text (`$record.*` reference).                          |
| `template.subtitle` | Secondary text.                                                |
| `template.image`    | Image URL (`$record.*` reference).                             |
| `template.badge`    | Badge text.                                                    |
| `template.meta`     | Metadata fields shown in the item footer (`field` + `format`). |
| `pagination`        | `button` (Load More) or `infinite` (load on scroll).           |
| `highlightSearch`   | Highlight matched search terms (default: `false`).             |
| `divided`           | Show dividers between items (default: `false`).                |
| `maxItems`          | Maximum number of items to display.                            |
| `emptyMessage`      | Message when no search results match.                          |

## `gallery`

A responsive card grid of records.

| Property           | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `dataSource`       | Table binding.                                                    |
| `gridColumns`      | Responsive column counts per breakpoint (mobile, sm, md, lg, xl). |
| `card.image`       | Cover image URL or `$record.*` reference.                         |
| `card.aspectRatio` | Cover aspect ratio (e.g. `4:3`, `16:9`, `1:1`).                   |
| `card.children`    | Child components for the card body.                               |
| `card.overlay`     | Components rendered in a hover overlay on the card.               |

## `kanban`

A drag-and-drop board grouping records into columns by a field value.

| Property           | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `dataSource`       | Table binding.                                                     |
| `groupBy`          | Field whose values become the kanban columns.                      |
| `card.children`    | Child components for the card body.                                |
| `card.image`       | Image URL or `$record.*` reference for the card cover.             |
| `card.colorField`  | Field whose values set the card background color.                  |
| `card.footer`      | Metadata fields displayed in the card footer (`field` + `format`). |
| `dragDrop.enabled` | Enable drag-and-drop between columns (default: `true`).            |

## `calendar`

A month/week/day calendar of date-bearing records.

| Property                   | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `dataSource`               | Table binding.                                                       |
| `mode`                     | Display mode: `month`, `week`, or `day`.                             |
| `event`                    | How records map to calendar events (start/end fields, title, color). |
| `interaction.slotMinutes`  | Time-slot interval in minutes for week/day views (default: 60).      |
| `interaction.nowIndicator` | Show a line at the current time in week/day views.                   |

## `chart`

A data visualization (bar, line, area) computed from aggregated records.

| Property          | Description                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| `dataSource`      | Table binding.                                                                                 |
| `series`          | One or more `{ field, color, stackGroup, fillOpacity }` series. Color is a theme token or hex. |
| `xAxis` / `yAxis` | Axis config — `{ field, scale, format, gridLines }`.                                           |
| `aggregate`       | `{ function, field, groupBy, interval }` for summarized data (omit `field` for count).         |
| `legend`          | `{ position, show }` legend display.                                                           |
| `tooltip`         | Tooltip text template (supports `{label}` and `{value}`).                                      |

## `kpi`

A single summary metric (a "stat card") with optional trend and sparkline.

| Property     | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| `dataSource` | Table binding.                                                                                |
| `aggregate`  | `{ function, field }` aggregate (omit `field` for count).                                     |
| `format`     | `{ type, options }` value formatting (e.g. `{ type: currency, options: { currency: USD } }`). |
| `trend`      | `{ period, direction, color, change }` comparison vs. a previous period.                      |
| `sparkline`  | `{ field, groupBy, interval, days }` mini trend line.                                         |

## `data-timeline`

A chronological feed of records ordered by a date/time field. Renders each record as a timeline entry.

| Property     | Description                                                                    |
| ------------ | ------------------------------------------------------------------------------ |
| `dataSource` | Table binding.                                                                 |
| `template`   | Per-record entry template (`$record.*` references for title, body, timestamp). |
| `props`      | Additional HTML attributes (e.g. `className`).                                 |

## `data-form` / `form`

A record-backed form for create/update operations against a table. The `action` (`crud`) determines whether it creates or edits, and form fields are generated from the table schema (overridable per field). For the full field reference and submission handling, see [Forms](/en/forms-overview) and [Form Controls](/en/form-controls).

| Property     | Description                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------- |
| `dataSource` | Table binding (single mode for edit, supplying current values).                                                      |
| `fields`     | Per-field config — `{ field, label, placeholder, readonly, disabled, default, hidden, accept, dropZone, maxFiles }`. |
| `layout`     | Field layout mode (default: `single-column`).                                                                        |
| `groups`     | Group fields under a labeled section divider (`{ label, fields }`).                                                  |
| `action`     | `crud` action with `operation: create                                                                                | update | delete`, `confirm`, and `onSuccess`/`onError` handlers. |

```yaml
- type: data-form
  dataSource: { table: contacts, mode: single, param: id }
  action:
    type: crud
    operation: update
    onSuccess: { type: navigate, url: /contacts }
  fields:
    - { field: email, label: 'Email Address' }
    - { field: notes, placeholder: 'Internal notes…' }
```

## Related Pages

- [Pages Overview](/en/pages-overview) — `dataSource` binding, filters, pagination, `$currentUser` scoping.
- [Tables Overview](/en/tables-overview) — the data models these components render.
- [Views](/en/table-views) — saved filters/sorts reused via `data-table.view`.
- [Form Controls](/en/form-controls) — individual input components.
- [Forms](/en/forms-overview) — standalone form definitions.
- [Interactivity & Scripts](/en/interactivity-scripts) — auto-save for inline editing.

# Form Controls

Form controls are the individual input components that compose a form. They render the standard interactive inputs — text, selection, toggles, sliders, pickers, file uploads — and integrate with a parent `form`/`data-form` for submission. Each control accepts the shared `props` bag plus `visibility`, `responsive`, and `i18n` modules. Most controls share a common set of attributes (`name`, `label`, `placeholder`, `disabled`, `required`, `defaultValue`).

```yaml
components:
  - type: form
    action: { type: crud, operation: create }
    children:
      - { type: input, name: email, props: { type: email, placeholder: 'you@example.com' } }
      - {
          type: select,
          name: plan,
          options: [{ label: Free, value: free }, { label: Pro, value: pro }],
        }
      - { type: switch, name: subscribe, props: { checked: true } }
```

## `input`

A single-line text input.

| Property             | Description                                                                     |
| -------------------- | ------------------------------------------------------------------------------- |
| `name`               | Field name (key in the submitted payload).                                      |
| `props.type`         | HTML input type: `text`, `email`, `password`, `number`, `tel`, `url`, `search`. |
| `props.placeholder`  | Placeholder text.                                                               |
| `props.defaultValue` | Initial value.                                                                  |
| `props.disabled`     | Disable the input.                                                              |
| `props.required`     | Mark the field required.                                                        |

## `textarea`

A multi-line text input.

| Property            | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `name`              | Field name.                                                |
| `props.rows`        | Visible number of text lines.                              |
| `props.maxLength`   | Maximum character count (prevents input beyond the limit). |
| `props.autoResize`  | Set `true` to expand the height as content grows.          |
| `props.placeholder` | Placeholder text.                                          |

## `select`

A dropdown that shows the selected value and opens an options list on click.

| Property             | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| `name`               | Field name.                                                            |
| `options`            | Array of `{ label, value, disabled?, icon? }` (at least one required). |
| `props.placeholder`  | Text shown when no value is selected.                                  |
| `props.searchable`   | Set `true` to enable type-ahead filtering of options.                  |
| `props.defaultValue` | Pre-selected value.                                                    |

## `combobox`

A searchable, autocompleting select for large option sets.

| Property             | Description                                                        |
| -------------------- | ------------------------------------------------------------------ |
| `name`               | Field name.                                                        |
| `options`            | Array of `{ label, value }` options (filtered by the typed query). |
| `props.placeholder`  | Placeholder for the search field.                                  |
| `props.defaultValue` | Pre-selected value.                                                |

## `checkbox`

A single checkbox input.

| Property              | Description                                 |
| --------------------- | ------------------------------------------- |
| `name`                | Field name.                                 |
| `props.checked`       | Render in the checked state.                |
| `props.indeterminate` | Render with a dash indicator (mixed state). |
| `props.disabled`      | Disable toggling.                           |

## `radio-group`

A group of mutually exclusive radio options.

| Property             | Description                                     |
| -------------------- | ----------------------------------------------- |
| `name`               | Field name.                                     |
| `options`            | Array of `{ label, value, disabled? }` options. |
| `props.defaultValue` | Pre-selected option.                            |
| `props.orientation`  | `horizontal` or `vertical` layout.              |

## `switch`

An on/off toggle switch with an accessible role.

| Property         | Description                |
| ---------------- | -------------------------- |
| `name`           | Field name.                |
| `props.checked`  | Render in the on position. |
| `props.disabled` | Disable toggling.          |

## `toggle` / `toggle-group`

`toggle` is a single pressable toggle button. `toggle-group` groups several toggles with single- or multiple-selection behavior.

| Property            | Description                                                            |
| ------------------- | ---------------------------------------------------------------------- |
| `name`              | Field name (toggle-group).                                             |
| `props.type`        | `single` or `multiple` (whether one or several toggles can be active). |
| `props.orientation` | `horizontal` or `vertical` (toggle-group).                             |
| `options`           | Toggle options (toggle-group).                                         |

## `slider`

A range input for selecting a numeric value or range.

| Property             | Description             |
| -------------------- | ----------------------- |
| `name`               | Field name.             |
| `props.min`          | Minimum value.          |
| `props.max`          | Maximum value.          |
| `props.step`         | Step increment.         |
| `props.defaultValue` | Initial value or range. |

## `date-picker`

A calendar-based date input.

| Property     | Description                                    |
| ------------ | ---------------------------------------------- |
| `name`       | Field name.                                    |
| `props.mode` | `single` (one date) or `range` (a date range). |
| `props.min`  | Earliest selectable date.                      |
| `props.max`  | Latest selectable date.                        |

## `time-picker`

A time input accepting user-entered time values.

| Property           | Description                               |
| ------------------ | ----------------------------------------- |
| `name`             | Field name.                               |
| `props.timeFormat` | `12h` (shows an AM/PM selector) or `24h`. |
| `props.minTime`    | Earliest selectable time.                 |
| `props.maxTime`    | Latest selectable time.                   |

## `number-input`

A numeric input with stepper buttons.

| Property     | Description                                               |
| ------------ | --------------------------------------------------------- |
| `name`       | Field name.                                               |
| `props.min`  | Minimum value (constrains typed and stepped values).      |
| `props.max`  | Maximum value.                                            |
| `props.step` | Increment amount for stepper buttons and keyboard arrows. |

## `file-upload`

A file selector with optional drag-and-drop.

| Property            | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `name`              | Field name.                                                             |
| `props.accept`      | Allowed MIME types/extensions (e.g. `image/*,.pdf`).                    |
| `props.maxFiles`    | Maximum number of files that can be selected.                           |
| `props.maxFileSize` | Maximum size in bytes (oversized files are rejected with an error).     |
| `props.dropZone`    | Set `true` to render a drag-and-drop area with a visual drop indicator. |

## `input-otp`

A segmented one-time-password / verification-code input.

| Property       | Description                        |
| -------------- | ---------------------------------- |
| `name`         | Field name.                        |
| `props.length` | Number of code digits/segments.    |
| `props.type`   | Allowed characters (e.g. numeric). |

## `field`

A composed form-field wrapper that renders a label, a control, a description, and an error message as one accessible unit.

| Property           | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `fieldLabel`       | Label element associated with the child control.                          |
| `fieldDescription` | Help text rendered below the control.                                     |
| `fieldError`       | Error message rendered in the destructive color below the control.        |
| `props.required`   | Show a required indicator (asterisk) on the label.                        |
| `children`         | The wrapped control component, which receives the composed field context. |

```yaml
- type: field
  fieldLabel: 'Email'
  fieldDescription: "We'll never share it."
  props: { required: true }
  children:
    - { type: input, name: email, props: { type: email } }
```

## Related Pages

- [Pages Overview](/en/pages-overview) — the component model and actions.
- [Forms](/en/forms-overview) — standalone form definitions and submission targets.
- [Data Components](/en/data-components) — `data-form` for record-backed forms.
- [Overlay Components](/en/overlay-components) — dialogs and drawers hosting forms.
- [Field Types Overview](/en/field-types-overview) — the table field types forms write to.

# Overlay Components

Overlay components float above the page: confirmation dialogs, side drawers, popovers, tooltips, toasts, and loading-state placeholders. Floating components (popover, tooltip, hover-card) share `floatingSide`/`floatingAlign` positioning, and dialog-family components open from a `trigger` and trap focus while open. All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: dialog
    title: Confirm
    trigger: { type: button, content: 'Open' }
    children:
      - { type: text, content: 'Are you sure?' }
```

## `dialog`

A modal dialog opened from a trigger. Clicking the backdrop or pressing Escape closes it; focus is trapped within the dialog while open.

| Property      | Description                                          |
| ------------- | ---------------------------------------------------- |
| `title`       | Dialog heading.                                      |
| `description` | Supporting text below the title.                     |
| `trigger`     | The element that opens the dialog when clicked.      |
| `children`    | Components rendered inside the dialog panel.         |
| `props`       | HTML attributes (e.g. `className` for panel sizing). |

## `alert-dialog`

A confirmation dialog for destructive actions, with explicit confirm/cancel buttons.

| Property       | Description                                           |
| -------------- | ----------------------------------------------------- |
| `content`      | The confirmation message.                             |
| `confirmLabel` | Label for the confirm button.                         |
| `cancelLabel`  | Label for the cancel button.                          |
| `trigger`      | The element that opens the alert dialog.              |
| `action`       | The action invoked on confirm (e.g. a `crud` delete). |

## `drawer`

A panel that slides in from a screen edge.

| Property     | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| `drawerSide` | Edge the drawer slides in from: `left`, `right`, `top`, `bottom`. |
| `drawerSize` | Size preset: `sm`, `md`, `lg`, `full`.                            |
| `trigger`    | The element that opens the drawer.                                |
| `children`   | Components rendered inside the drawer panel.                      |

## `popover`

A floating panel anchored to a trigger, opened on click.

| Property        | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `trigger`       | The element that opens the popover.                                        |
| `floatingSide`  | Preferred side relative to the trigger (`top`, `right`, `bottom`, `left`). |
| `floatingAlign` | Alignment along that side (`start`, `center`, `end`).                      |
| `children`      | Components rendered inside the popover.                                    |

## `tooltip`

A small hover hint anchored to a trigger.

| Property         | Description                             |
| ---------------- | --------------------------------------- |
| `tooltipContent` | The hint text.                          |
| `tooltipDelay`   | Delay before the tooltip appears (ms).  |
| `floatingSide`   | Preferred side relative to the trigger. |
| `floatingAlign`  | Alignment along that side.              |

## `hover-card`

A richer popover that opens on hover (e.g. a profile preview).

| Property        | Description                                         |
| --------------- | --------------------------------------------------- |
| `trigger`       | The element that reveals the card on hover.         |
| `floatingSide`  | Preferred side relative to the trigger.             |
| `floatingAlign` | Alignment along that side.                          |
| `openDelay`     | Delay before opening on hover (ms).                 |
| `closeDelay`    | Delay before closing after the pointer leaves (ms). |
| `children`      | Components rendered inside the card.                |

## `toast`

A transient notification. Toasts are usually emitted from an action's `onSuccess`/`onError` handler rather than placed in the tree directly; page-level placement is configured via [`page.toasts`](/en/pages-overview#page-properties).

| Property      | Description                                                                  |
| ------------- | ---------------------------------------------------------------------------- |
| `variant`     | Style: `success`, `error`, `warning`, `info` (also `default`/`destructive`). |
| `message`     | Toast text (supports `$variable` references).                                |
| `duration`    | Auto-dismiss duration in milliseconds (default: 5000).                       |
| `actionLabel` | Optional action-button label.                                                |
| `actionUrl`   | Optional URL the action button navigates to.                                 |

Multiple toasts stack without overlapping; position is configured per page (e.g. `top-right`, `bottom-center`).

## `progress`

A progress bar or circular indicator showing completion.

| Property                | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `progressValue`         | Current value.                                                                             |
| `progressMax`           | Maximum value.                                                                             |
| `props.showLabel`       | Display the percentage text alongside the bar.                                             |
| `props.size`            | Size preset (e.g. `sm` for a thinner bar).                                                 |
| `props.progressVariant` | Set to `circle` for a circular progress indicator with the percentage shown in the center. |

## `skeleton`

A loading placeholder shown while content is fetching.

| Property          | Description                                  |
| ----------------- | -------------------------------------------- |
| `skeletonVariant` | Shape: `text`, `circular`, or `rectangular`. |
| `skeletonWidth`   | Placeholder width.                           |
| `skeletonHeight`  | Placeholder height.                          |
| `props.animate`   | Set `true` for a pulsing animation.          |

## Related Pages

- [Pages Overview](/en/pages-overview) — actions, `onSuccess`/`onError` handlers, page toasts.
- [Layout Components](/en/layout-components) — the `modal` layout component.
- [Form Controls](/en/form-controls) — inputs commonly hosted in dialogs and drawers.
- [Feedback Components](/en/feedback-components) — progress, spinner, skeleton.
- [Data Components](/en/data-components) — record-detail drawers triggered from a data-table.

# Navigation Components

Navigation components move users around: top-level menus, dropdown and context menus, breadcrumb trails, tab panels, pagination controls, and grouped toggle/button controls. Menu and breadcrumb items follow shared schemas (`MenuItemSchema`, `NavItemSchema`, `BreadcrumbItemSchema`). All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: navigation-menu
    items:
      - { label: Home, href: / }
      - label: Products
        children:
          - { label: Catalog, href: /catalog, description: 'Browse everything' }
  - type: breadcrumb
    items:
      - { label: Home, href: / }
      - { label: Contacts }
```

## `navigation-menu`

A top-level navigation bar supporting nested items and mega-menu layouts.

| Property | Description                         |
| -------- | ----------------------------------- |
| `items`  | Array of nav items (see below).     |
| `props`  | HTML attributes (e.g. `className`). |

Each nav item (`NavItemSchema`):

| Item property | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `label`       | Display text for the item.                                             |
| `href`        | URL or route path (omit for parent items with `children`).             |
| `description` | Text shown below the label in mega-menu style.                         |
| `icon`        | Lucide icon name displayed next to the label.                          |
| `target`      | Anchor target (typically `_blank` for external links).                 |
| `rel`         | Anchor `rel` attribute (commonly `noopener noreferrer` with `_blank`). |
| `children`    | Child nav items forming a sub-menu or mega-menu.                       |

## `dropdown-menu`

A menu that opens from a trigger button, with optional nested sub-menus.

| Property    | Description                      |
| ----------- | -------------------------------- |
| `trigger`   | The element that opens the menu. |
| `menuItems` | Array of menu items (see below). |

Each menu item (`MenuItemSchema`):

| Item property | Description                                          |
| ------------- | ---------------------------------------------------- |
| `label`       | Display text (omit for a separator).                 |
| `icon`        | Lucide icon name next to the label.                  |
| `shortcut`    | Keyboard-shortcut hint on the right (e.g. `Ctrl+C`). |
| `disabled`    | Visible but not clickable.                           |
| `separator`   | Render a divider line instead of a clickable item.   |
| `variant`     | Visual style (e.g. `destructive` for red text).      |
| `children`    | Nested sub-menu items.                               |
| `action`      | The action invoked when the item is clicked.         |

## `context-menu`

A right-click menu using the same `MenuItemSchema` items as `dropdown-menu`, anchored to the pointer position rather than a trigger button.

| Property    | Description                                  |
| ----------- | -------------------------------------------- |
| `menuItems` | Menu items (same shape as `dropdown-menu`).  |
| `children`  | The element the context menu is attached to. |

## `menubar`

A horizontal application menu bar (File / Edit / View style), each top-level item opening a `MenuItemSchema` menu.

| Property | Description                                            |
| -------- | ------------------------------------------------------ |
| `menus`  | Array of top-level menus, each with a label and items. |

## `breadcrumb`

A breadcrumb trail of navigation segments.

| Property | Description                            |
| -------- | -------------------------------------- |
| `items`  | Array of breadcrumb items (see below). |

Each breadcrumb item (`BreadcrumbItemSchema`):

| Item property | Description                                         |
| ------------- | --------------------------------------------------- |
| `label`       | Display text for the segment.                       |
| `href`        | URL or route path (omit for the current-page item). |
| `icon`        | Lucide icon name displayed before the label.        |

## `tabs`

A tabbed container. Each tab's content is a [`tab-panel`](/en/layout-components#tab-panel) child.

| Property             | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `children`           | `tab-panel` components, one per tab.                              |
| `props.orientation`  | Layout direction of the tab triggers: `horizontal` or `vertical`. |
| `props.defaultValue` | The tab open on initial render.                                   |

## `pagination`

Page-navigation controls for paginated lists/tables.

| Property       | Description                                                     |
| -------------- | --------------------------------------------------------------- |
| `totalPages`   | Total number of pages.                                          |
| `currentPage`  | The currently active page.                                      |
| `siblingCount` | How many page numbers to show on each side of the current page. |

## `toggle` / `toggle-group`

Toggle buttons for navigation/filtering. `toggle` is a single toggle; `toggle-group` groups several. (Also documented as form controls — see [Form Controls](/en/form-controls#toggle--toggle-group).)

| Property            | Description                            |
| ------------------- | -------------------------------------- |
| `props.type`        | `single` or `multiple` active toggles. |
| `props.orientation` | `horizontal` or `vertical`.            |
| `options`           | Toggle options (toggle-group).         |

## `button-group`

A row of related buttons. Combine with a `dropdown-menu` to build a split-button pattern (a primary button plus a dropdown of secondary actions); keyboard navigation works across both.

| Property   | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| `children` | The grouped `button` (and optional `dropdown-menu`) components. |
| `props`    | HTML attributes (e.g. `className`).                             |

## Related Pages

- [Pages Overview](/en/pages-overview) — the component model and actions.
- [Layout Components](/en/layout-components) — `tab-panel`, `sidebar`, app-shell layout.
- [Interactive Components](/en/interactive-components) — buttons and links used in menus.
- [Overlay Components](/en/overlay-components) — popovers and dialogs opened from menus.

# Media Components

Media components render images, icons, video, audio, and embedded frames. They handle responsive sizing, lazy loading, accessibility attributes, and security sandboxing. All accept the shared `props` bag (where most media attributes live) plus `visibility` and `responsive` modules; `$record.*` references resolve in `props.src`, `props.alt`, etc.

```yaml
components:
  - type: image
    props: { src: '$record.cover', alt: '$record.title', loading: lazy, objectFit: cover }
  - type: icon
    props: { name: check-circle, size: 20, color: 'var(--color-primary)' }
```

## `image`

A responsive image.

| Property          | Description                                    |
| ----------------- | ---------------------------------------------- |
| `props.src`       | Image URL (required; supports `$record.*`).    |
| `props.alt`       | Alternative text (required for accessibility). |
| `props.loading`   | `lazy` defers loading until near the viewport. |
| `props.srcset`    | Candidate sources for responsive selection.    |
| `props.sizes`     | Source-size hints paired with `srcset`.        |
| `props.width`     | Intrinsic width (prevents layout shift).       |
| `props.height`    | Intrinsic height.                              |
| `props.objectFit` | Scaling: `cover`, `contain`, `fill`, `none`.   |

A failed load shows a placeholder. Wrap an `image` in a [`link`](/en/interactive-components#link) to make it clickable.

## `icon`

An inline SVG icon from the Lucide icon set.

| Property            | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `props.name`        | Lucide icon name (maps to the matching SVG; supports `$variable`).                           |
| `props.size`        | Width/height in pixels (default: 24).                                                        |
| `props.color`       | SVG stroke color (defaults to `currentColor`; supports `$variable`).                         |
| `props.strokeWidth` | SVG stroke width (default: 2).                                                               |
| `props.className`   | Tailwind classes (e.g. color utilities).                                                     |
| `props.ariaLabel`   | Accessible label — sets `role="img"` and `aria-label`; without it the icon is `aria-hidden`. |

Icons render correctly as children of `button` and `link`, and emit `data-testid="icon-{name}"`.

## `video`

A video player supporting direct files and YouTube/Vimeo embeds.

| Property            | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `props.src`         | Direct video URL or embed URL (YouTube/Vimeo auto-convert to an iframe). |
| `props.poster`      | Preview image shown before playback.                                     |
| `props.controls`    | Show playback controls.                                                  |
| `props.autoplay`    | Autoplay on load.                                                        |
| `props.muted`       | Start muted.                                                             |
| `props.loop`        | Loop playback.                                                           |
| `props.aspectRatio` | Responsive sizing (`16:9`, `4:3`, or custom).                            |
| `props.tracks`      | Subtitle/caption tracks (VTT format).                                    |

## `audio`

An audio player.

| Property         | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `props.src`      | Audio URL (required for single-source audio).                  |
| `props.controls` | Show playback controls.                                        |
| `props.autoplay` | Autoplay on load.                                              |
| `props.loop`     | Loop playback.                                                 |
| `props.sources`  | Multiple formats with MIME types (for cross-browser fallback). |

## `iframe`

An embedded external frame.

| Property                                             | Description                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------ |
| `props.src`                                          | Frame URL (required).                                              |
| `props.title`                                        | Accessible title (required for accessibility).                     |
| `props.sandbox`                                      | Sandbox attribute restricting the frame's capabilities (security). |
| `props.allow`                                        | Permissions granted (e.g. camera, microphone).                     |
| `props.width` / `props.height` / `props.aspectRatio` | Responsive sizing.                                                 |

## `carousel`

A horizontally or vertically scrolling slideshow of child slides.

| Property            | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `children`          | Slide components.                                        |
| `props.orientation` | Scroll direction: `horizontal` or `vertical`.            |
| `props`             | Additional HTML attributes (e.g. autoplay/loop options). |

## `aspect-ratio`

A wrapper that maintains a fixed aspect ratio for its child (commonly a media element).

| Property      | Description                                  |
| ------------- | -------------------------------------------- |
| `props.ratio` | The aspect ratio to enforce (e.g. `16:9`).   |
| `children`    | The media (or other) component to constrain. |

## Related Pages

- [Pages Overview](/en/pages-overview) — the component model and variable substitution.
- [Content Components](/en/content-components) — text and prose blocks.
- [Layout Components](/en/layout-components) — containers and grids for media layout.
- [SEO & Metadata](/en/seo-meta) — Open Graph images and preload hints.
- [Buckets](/en/buckets-overview) — storage for uploaded media referenced by `src`.

# Social Components

Social components add engagement to pages: threaded comments (authenticated and public/guest), comment counts, an AI-agent chat panel, and sharing controls. The comments components integrate with the table comment system and respect the table's `comment` permission. All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: comments
    props: { placeholder: 'Add a comment…', limit: 20, sort: newest, paginationStyle: loadMore }
  - type: commentCount
    props: { format: '{count} comments', emptyText: 'No comments yet' }
```

## `comments`

A full comment thread for a record. On a collection page it auto-resolves `$record.id` and `collection.table` for API calls. Displays author name, avatar, content, and relative timestamp; respects the table's `comment` permission (hidden when the user lacks it).

| Property                | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `props.placeholder`     | Placeholder text for the comment-form textarea.                        |
| `props.limit`           | Comments loaded per page (default: 20).                                |
| `props.sort`            | Order: `newest` (desc, default) or `oldest` (asc).                     |
| `props.paginationStyle` | `loadMore` (default, a Load More button) or `numbered` (page numbers). |
| `props.showCount`       | Show a comment-count badge (default: `true`).                          |
| `props.emptyText`       | Custom message when no comments exist (default: "No comments yet").    |

The comment form is shown to authenticated users with `comment` permission and hidden from unauthenticated visitors (who instead see a "Sign in to comment" prompt when `comment: authenticated`). Authors can edit/delete their own comments; admins can delete any. Content is limited to 10,000 characters (matching the API).

### Public / guest comments

When the table's comment config enables `guestComments`, the form also accepts guest name and email, and supports moderation, threading, and spam protection:

| Concern         | Behavior                                                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Guest fields    | Name required (1–100 chars); email required when `guestEmailRequired` (default), validated as an email. Stored with `userId: null`.                                             |
| Threading       | `threading: true` shows a single-level Reply on top-level comments; replies store a `parentId`. `threading: false` (default) is flat.                                           |
| Moderation      | `moderation: true` creates new comments as `pending`; admins approve/reject. `autoApprove.authenticated` / `autoApprove.previouslyApproved` bypass moderation.                  |
| Spam protection | Honeypot field, IP rate limiting (`rateLimitPerIp`, default 5/min → 429), link threshold (`maxLinksBeforeModeration`), and blocked-word auto-reject — all enforced server-side. |

## `commentCount`

A compact comment-count display. On collection pages it auto-resolves `$record.id` and `collection.table`; on dataSource-bound parents it resolves per `$record.id` for each record in a list.

| Property          | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `props.format`    | Count template with a `{count}` placeholder (default: `'{count} comments'`). |
| `props.emptyText` | Display when the count is 0 (default: `'0 comments'`).                       |

The count is read from the comments API pagination metadata and includes only `approved` comments when moderation is on.

## `ai-chat`

An embedded chat panel backed by a configured AI agent. See [Agents](/en/ai-agents) for agent configuration.

| Property           | Description                                 |
| ------------------ | ------------------------------------------- |
| `agent`            | Agent name from `app.agents[]`.             |
| `placeholder`      | Placeholder text for the chat input.        |
| `height`           | Chat container height in pixels.            |
| `showHistory`      | Show previous conversation history on load. |
| `allowAttachments` | Allow file attachments in chat.             |

```yaml
- type: ai-chat
  agent: support-assistant
  height: 480
  placeholder: 'Ask a question…'
  allowAttachments: true
```

## `sharing`

Share controls for the current page or record (social links, copy-link). Sharing surfaces are composed from `link`/`button` components with `navigate` interactions; for copy-to-clipboard behavior see [Interactivity & Scripts](/en/interactivity-scripts).

| Property   | Description                                                                  |
| ---------- | ---------------------------------------------------------------------------- |
| `props`    | HTML attributes and share-target options (e.g. `className`, share URL/text). |
| `children` | Custom share buttons/links.                                                  |

## Related Pages

- [Pages Overview](/en/pages-overview) — collection pages and `$record.*` resolution.
- [Agents](/en/ai-agents) — configure the AI agents that power `ai-chat`.
- [Table Permissions](/en/table-permissions) — the `comment` permission gating comments.
- [Interactivity & Scripts](/en/interactivity-scripts) — clipboard and navigate actions for sharing.
- [Notifications](/en/automation-email-actions) — comment automation triggers.

# SEO & Metadata

The page-level `meta` property controls everything rendered into the document `<head>`: the title and description, social-sharing cards, structured data, favicons, and performance hints. Metadata supports `$record.*` and `$frontmatter.*` substitution, so collection and markdown pages produce per-record SEO automatically.

```yaml
pages:
  - name: Blog Post
    path: /blog/:slug
    collection: { table: posts, slugField: slug }
    meta:
      title: '$record.title'
      description: '$record.excerpt'
      openGraph: { type: article, image: '$record.cover' }
      twitter: { card: summary_large_image }
```

## Core Metadata

| Property       | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| `title`        | Page title for the browser tab and SEO (max ~60 chars for optimal display).       |
| `description`  | Page description for SEO and social sharing (max ~160 chars).                     |
| `keywords`     | Comma-separated SEO keywords.                                                     |
| `author`       | Page author or organization name.                                                 |
| `canonical`    | Canonical URL to prevent duplicate-content issues.                                |
| `robots`       | Robot directives (e.g. `noindex, nofollow`).                                      |
| `noindex`      | Shorthand for `robots: noindex` — prevents indexing by search engines.            |
| `lang`         | Page language code (ISO 639-1 with optional country; auto-detected when omitted). |
| `image`        | Default social-sharing image (shorthand also feeding Open Graph/Twitter).         |
| `siteName`     | Site name (shorthand for `openGraph.siteName`).                                   |
| `stylesheet`   | Path to the main stylesheet.                                                      |
| `googleFonts`  | Google Fonts URL.                                                                 |
| `translations` | Localized metadata (translated `title`/`description`) per language.               |

## `openGraph`

Open Graph protocol metadata for rich social-media sharing.

| Property      | Description                                            |
| ------------- | ------------------------------------------------------ |
| `type`        | Open Graph object type (e.g. `website`, `article`).    |
| `title`       | OG title (may differ from the page title).             |
| `description` | OG description.                                        |
| `url`         | Canonical URL for this page.                           |
| `image`       | Image URL for social sharing (recommended 1200×630px). |
| `imageAlt`    | Alternative text for the OG image.                     |
| `siteName`    | Name of the overall website.                           |
| `locale`      | Locale in `language_TERRITORY` form.                   |
| `video`       | Video URL when sharing video content.                  |
| `audio`       | Audio URL when sharing audio content.                  |

## `twitter`

Twitter/X Card metadata.

| Property      | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `card`        | Card type (`summary`, `summary_large_image`, `app`, `player`).    |
| `title`       | Twitter Card title.                                               |
| `description` | Twitter Card description.                                         |
| `image`       | Image URL (min 144×144 for `summary`, 300×157 for large).         |
| `imageAlt`    | Alternative text for the image.                                   |
| `site`        | Twitter `@username` of the website.                               |
| `creator`     | Twitter `@username` of the content creator.                       |
| `player`      | HTTPS URL to a video player plus `width`/`height` (player cards). |
| `app`         | App name, store IDs, and deep-link URLs for app cards.            |

## `structuredData`

Schema.org JSON-LD structured data emitted as a `<script type="application/ld+json">` block. Supported helpers include `Article`, `Organization`, and `PostalAddress`.

| Property   | Description                                                                                                                        |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `@context` | Schema.org context (`https://schema.org`).                                                                                         |
| `@type`    | Schema.org type (e.g. `Article`, `Organization`, `Product`).                                                                       |
| `...`      | Type-specific fields — e.g. for `Article`: `headline`, `author` (`{ name, url }`), `publisher` (`{ name, logo }`), `image`, dates. |

```yaml
meta:
  structuredData:
    '@context': https://schema.org
    '@type': Article
    headline: '$record.title'
    author: { name: '$record.author', url: '$record.author_url' }
    image: '$record.cover'
```

## `favicons`

Favicon configuration for browsers and devices.

| Property   | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| `default`  | Default icon path (SVG or ICO).                                     |
| `apple`    | iOS home-screen icon.                                               |
| `sizes`    | Size-specific favicons (`{ src, sizes, type }`, e.g. 32×32, 16×16). |
| `maskIcon` | Safari pinned-tab mask icon path and color.                         |

## Performance Hints

Resource hints injected into the head to speed up loading.

| Property      | Description                                                                       |
| ------------- | --------------------------------------------------------------------------------- |
| `preload`     | Critical resources to preload — each `{ href, as, type?, media?, crossorigin? }`. |
| `dnsPrefetch` | Domains to DNS-prefetch (array of domains).                                       |
| `customHead`  | Additional custom `<head>` elements (`{ tag, attributes, content }`).             |

```yaml
meta:
  preload:
    - { href: /fonts/inter.woff2, as: font, type: font/woff2, crossorigin: anonymous }
  dnsPrefetch: ['https://cdn.example.com']
  favicons:
    default: /favicon.svg
    apple: /apple-touch-icon.png
```

:::callout
**Per-page sitemap & RSS.** SEO crawlability is complemented by the page-level `sitemap` property (`{ priority, changefreq }`, or `false` to exclude) and `rss` (for collection pages). See [Pages Overview → Page Properties](/en/pages-overview#page-properties).
:::

## Related Pages

- [Pages Overview](/en/pages-overview) — page structure, collection pages, sitemap, RSS.
- [Content Components](/en/content-components) — page body content.
- [Media Components](/en/media-components) — images referenced by Open Graph and preload.
- [Languages](/en/languages) — localized metadata translations.

# Interactivity & Scripts

Sovrium pages are server-rendered, then progressively enhanced with declarative interactivity. This page covers the `scripts` block (external/inline scripts, feature flags, config data), the `interactions` module (click actions, hover effects, entrance animations), auto-save for inline editing, reorderable lists, and custom HTML. No hand-written event wiring is required for the built-in patterns.

```yaml
pages:
  - name: Dashboard
    path: /dashboard
    scripts:
      external:
        - { src: 'https://cdn.example.com/widget.js', async: true, position: body-end }
      features: { betaPanel: true }
    components:
      - type: button
        content: Save
        interactions:
          onClick: { animation: pulse, submitForm: settings-form }
```

## `scripts`

Page-level client-side script management.

| Property   | Description                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `external` | External JavaScript dependencies — each `{ src, async, defer, module, integrity, crossorigin, position }`. |
| `inline`   | Inline JavaScript snippets — each `{ code, async? }`. `async: true` wraps the code in an async IIFE.       |
| `features` | Client-side feature toggles — a boolean flag or `{ enabled, config }` per feature.                         |
| `config`   | Arbitrary client-side configuration data exposed to scripts.                                               |

### External script attributes

| Attribute     | Description                                           |
| ------------- | ----------------------------------------------------- |
| `src`         | Script source URL.                                    |
| `async`       | Load asynchronously (non-blocking).                   |
| `defer`       | Defer execution until the DOM is parsed.              |
| `module`      | Load as an ES module (`type="module"`).               |
| `integrity`   | Subresource-integrity hash for security.              |
| `crossorigin` | CORS setting: `anonymous` or `use-credentials`.       |
| `position`    | Insert location: `head`, `body-start`, or `body-end`. |

## `interactions`

The shared `interactions` module attaches client-side behavior to a component: click actions, hover effects, and entrance animations.

### `onClick`

| Property     | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `animation`  | Animation to play on click (`pulse`, `ripple`, `bounce`, or `none`). |
| `navigate`   | Path to navigate to (internal route or same-page anchor).            |
| `url`        | External URL to open (in same tab, or new tab with a target).        |
| `scrollTo`   | Anchor section to smooth-scroll to.                                  |
| `toggle`     | Element id to show/hide.                                             |
| `submitForm` | Form id to submit.                                                   |
| `modalId`    | Modal section id to open.                                            |

Click behaviors can combine — e.g. play an animation, then navigate.

### `onHover`

| Property          | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| `transform`       | CSS transform on hover (scale/rotate/translate; e.g. `scale: 1.05`).     |
| `opacity`         | Opacity value on hover (0–1).                                            |
| `backgroundColor` | Background color on hover.                                               |
| `textColor`       | Text color on hover.                                                     |
| `borderColor`     | Border color on hover.                                                   |
| `boxShadow`       | Box shadow on hover.                                                     |
| `duration`        | Transition duration (ms; `0` applies effects instantly).                 |
| `easing`          | Timing function: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`. |

All hover effects apply simultaneously with coordinated timing.

### `onEntrance`

| Property    | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `animation` | Animation type triggered when the element enters the viewport. |
| `threshold` | Fraction of the element visible before triggering (0–1).       |
| `delay`     | Delay before the animation starts.                             |
| `once`      | Trigger only once.                                             |

## Actions & response handlers

Interactive components carry an `action` (e.g. `crud`, `auth`, `navigate`, `automation`) with `onSuccess`/`onError` response handlers. A handler may show a `toast`, `navigate`, `reset` the form, show a `message`, or render a `successPage` with follow-up `actions`. `action.type: automation` invokes a named [automation](/en/automations-overview).

```yaml
- type: button
  content: Submit
  action:
    type: crud
    operation: create
    onSuccess: { type: navigate, url: /thanks }
    onError: { type: message, toast: { variant: error, message: 'Save failed' } }
```

## Auto-Save

Data components support inline-edit auto-save via the `autoSave` module (most commonly on `data-table`).

| Property                | Description                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `saveMode`              | `auto` (debounced), `onBlur` (save when the edited field loses focus), or `manual` (default).         |
| `autoSaveDebounceMs`    | Debounce delay after the last keystroke (default: 500; min: 100). Rapid edits batch into one request. |
| `showSaveIndicator`     | Display status: Idle / Saving… / Saved / Error (with retry on failure).                               |
| `saveIndicatorPosition` | `inline` (near the edited cell), `toast`, or `toolbar`.                                               |

Only the changed cell value is sent in the PATCH payload; navigating away flushes pending saves immediately.

## `reorderable-list`

A list whose items can be reordered by drag-and-drop or keyboard, firing an `onReorder` action.

| Property     | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `dataSource` | Optional table binding for list items.                      |
| `children`   | The list items (each rendered with a drag handle).          |
| `onReorder`  | Action invoked when items are reordered (drag or keyboard). |

## `custom-html` (`customHTML`)

Embed raw HTML — inline or from a file — in a sandboxed context with access to theme CSS variables.

| Property  | Description                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| `content` | Inline HTML string.                                                                           |
| `htmlSrc` | Path to an external HTML file, relative to the project root. Takes precedence over `content`. |

The HTML renders in a sandboxed context (no access to parent-page JS) and can reference theme variables (e.g. `var(--color-primary)`). An invalid `htmlSrc` renders a clear error instead of crashing.

```yaml
- type: customHTML
  content: '<div style="color: var(--color-primary)">Custom block</div>'
```

## Clipboard & patterns

Common interactive patterns are built from the primitives above: copy-to-clipboard buttons (a `button` with an action), debounced search inputs (`searchInput` with `debounceMs`), modals opened via `onClick.modalId`, and visibility gating via the `visibility` module (server-rendered but hidden client-side when auth conditions are unmet — hidden components never leak sensitive data into the HTML).

## Related Pages

- [Pages Overview](/en/pages-overview) — the component model, actions, and `scripts`/`vars`.
- [Form Controls](/en/form-controls) — inputs that auto-save or submit via actions.
- [Data Components](/en/data-components) — `data-table` inline-edit auto-save.
- [Overlay Components](/en/overlay-components) — toasts and dialogs triggered by interactions.
- [Automations](/en/automations-overview) — automations invoked by `action.type: automation`.

# Display Components

Display components present static or structural content that is not bound to a table data source: hard-coded tables, command palettes, empty states, resizable split panels, scroll areas, chat speech bubbles, carousels, accordions, and tab containers. All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: static-table
    headers: [Plan, Price, Seats]
    rows:
      - [Free, '$0', '1']
      - [Pro, '$29', '10']
    caption: 'Pricing tiers'
```

## `static-table`

A table populated from inline data (not a data source).

| Property  | Description                                      |
| --------- | ------------------------------------------------ |
| `headers` | Column header labels.                            |
| `rows`    | Row data as an array of string arrays.           |
| `caption` | Caption text displayed above or below the table. |

## `command`

A command palette (⌘K-style) of searchable command groups.

| Property | Description                                                                             |
| -------- | --------------------------------------------------------------------------------------- |
| `groups` | Groups of commands. Each group has a heading and `items` (`{ label, icon, shortcut }`). |

## `empty-state`

A placeholder shown when there is nothing to display.

| Property      | Description                            |
| ------------- | -------------------------------------- |
| `icon`        | Lucide icon name for the illustration. |
| `title`       | Title text.                            |
| `description` | Supporting text below the title.       |
| `children`    | Optional call-to-action components.    |

## `resizable`

Resizable split panels separated by a draggable handle.

| Property       | Description                                           |
| -------------- | ----------------------------------------------------- |
| `direction`    | Panel layout direction: `horizontal` or `vertical`.   |
| `defaultSizes` | Default panel sizes as percentages (must sum to 100). |
| `minSize`      | Minimum panel size as a percentage.                   |
| `children`     | The panel components.                                 |

## `scroll-area`

A scrollable region with custom scrollbars.

| Property      | Description                                       |
| ------------- | ------------------------------------------------- |
| `orientation` | Scroll axis: `vertical`, `horizontal`, or `both`. |
| `maxHeight`   | CSS max-height for the area (e.g. `400px`).       |
| `children`    | The scrollable content.                           |

## `speech-bubble`

A chat-style message bubble (used in conversation UIs).

| Property  | Description                                                         |
| --------- | ------------------------------------------------------------------- |
| `content` | The message text.                                                   |
| `props`   | HTML attributes — typically `className` for sender alignment/color. |

## `list-item`

A single list-item element, used as a building block inside lists and menus.

| Property   | Description        |
| ---------- | ------------------ |
| `content`  | Inline content.    |
| `children` | Nested components. |
| `props`    | HTML attributes.   |

## `aspect-ratio`

Constrains a child to a fixed width-to-height ratio.

| Property   | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `ratio`    | Width-to-height ratio (e.g. `16/9` = 1.778, `1` = square). |
| `children` | The constrained component.                                 |

## `carousel`

A slideshow of child slides with optional auto-play and navigation.

| Property           | Description                                   |
| ------------------ | --------------------------------------------- |
| `orientation`      | Scroll direction: `horizontal` or `vertical`. |
| `autoplay`         | Automatically advance slides.                 |
| `autoplayInterval` | Interval between auto-play transitions (ms).  |
| `showDots`         | Show dot indicators below the carousel.       |
| `showArrows`       | Show previous/next navigation arrows.         |
| `children`         | The slide components.                         |

## `accordion`

Collapsible content sections. (Also documented in [Content Components](/en/content-components#accordion).)

| Property      | Description                           |
| ------------- | ------------------------------------- |
| `type`        | `single` or `multiple` open sections. |
| `defaultOpen` | IDs of items open by default.         |
| `children`    | The accordion items.                  |

## `tabs`

A tabbed container holding [`tab-panel`](/en/layout-components#tab-panel) children. (Also documented in [Navigation Components](/en/navigation-components#tabs).)

| Property       | Description                                 |
| -------------- | ------------------------------------------- |
| `orientation`  | Trigger layout: `horizontal` or `vertical`. |
| `defaultValue` | ID of the tab active by default.            |
| `children`     | The `tab-panel` components.                 |

## Related Pages

- [Pages Overview](/en/pages-overview) — the component model.
- [Layout Components](/en/layout-components) — containers, cards, tab panels.
- [Data Components](/en/data-components) — data-bound tables vs. `static-table`.
- [Content Components](/en/content-components) — text, code, callouts.

# Feedback Components

Feedback components communicate progress and loading state: a progress bar/circle, a spinner, and skeleton placeholders. All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: progress
    progressValue: 60
    progressMax: 100
    props: { showLabel: true, size: sm }
  - type: skeleton
    skeletonVariant: rectangular
    props: { animate: true }
```

## `progress`

A determinate progress indicator, rendered as a bar or circle.

| Property                | Description                                                             |
| ----------------------- | ----------------------------------------------------------------------- |
| `progressValue`         | Current value (0 to `progressMax`).                                     |
| `progressMax`           | Maximum value (default: 100).                                           |
| `props.showLabel`       | Display the percentage label.                                           |
| `props.size`            | Size preset (e.g. `sm` for a thinner bar).                              |
| `props.progressVariant` | `circle` renders a circular progress with the percentage in the center. |

## `spinner`

An indeterminate loading spinner for short waits.

| Property     | Description                                              |
| ------------ | -------------------------------------------------------- |
| `props.size` | Spinner size preset.                                     |
| `props`      | Additional HTML attributes (e.g. `className` for color). |

## `skeleton`

A shaped loading placeholder shown while content is fetching.

| Property          | Description                                   |
| ----------------- | --------------------------------------------- |
| `skeletonVariant` | Shape: `text`, `circular`, or `rectangular`.  |
| `skeletonWidth`   | CSS width (e.g. `200px`, `100%`).             |
| `skeletonHeight`  | CSS height (e.g. `20px`, `3rem`).             |
| `props.animate`   | Enable the pulse animation (default: `true`). |

## Related Pages

- [Pages Overview](/en/pages-overview) — the component model.
- [Overlay Components](/en/overlay-components) — `progress` and `skeleton` are also overlay-adjacent.
- [Interactivity & Scripts](/en/interactivity-scripts) — auto-save status indicators.
- [Data Components](/en/data-components) — loading states for data-bound components.

# Interactive Components

Interactive components are the clickable, inline primitives: buttons that fire actions, links that navigate, alerts and badges that convey status. They carry the shared `action` and `interactions` modules (click/hover/entrance behavior) plus `props`, `visibility`, and `responsive`.

```yaml
components:
  - type: button
    label: Save
    action: { type: crud, operation: create, onSuccess: { type: navigate, url: /done } }
  - type: link
    content: Learn more
    props: { href: /docs, target: _blank }
```

## `button`

A clickable button that triggers an `action` and/or `interactions`.

| Property         | Description                                                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `label`          | Button text label.                                                                                                                 |
| `content`        | Inline content (alternative to `label`; can hold an `icon` child).                                                                 |
| `action`         | Action to run on click — `crud`, `auth`, `navigate`, `automation` — with `onSuccess`/`onError` handlers.                           |
| `interactions`   | Click animation, navigation, scroll, toggle, submit-form, or open-modal. See [Interactivity & Scripts](/en/interactivity-scripts). |
| `props.loading`  | Show a loading spinner inside the button.                                                                                          |
| `props.confirm`  | Click-time confirmation prompt before the action runs.                                                                             |
| `props.variant`  | Visual style variant (e.g. `primary`, `secondary`, `destructive`).                                                                 |
| `props.disabled` | Disable the button.                                                                                                                |

## `link`

An anchor element for navigation.

| Property       | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `content`      | Link text (supports substitution).                               |
| `props.href`   | URL or route path.                                               |
| `props.target` | Anchor target (e.g. `_blank` for a new tab).                     |
| `props.rel`    | Anchor `rel` attribute (e.g. `noopener noreferrer`).             |
| `children`     | Optional nested content (e.g. an `image` for a clickable image). |

## `alert`

An inline callout block. (Also documented in [Content Components](/en/content-components#alert).)

| Property            | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `content`           | The alert message.                                                 |
| `props.variant`     | `info`, `warning`, `error`, or `success` (each with an auto-icon). |
| `props.dismissible` | Render a close button that hides the alert.                        |

## `badge`

A small status/label chip.

| Property  | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `content` | Badge label text.                                                 |
| `variant` | Rendering mode (e.g. `status` for a status-indicator dot).        |
| `color`   | Color token for the status dot (`variant: status`).               |
| `label`   | Status label text next to the dot (`variant: status`).            |
| `pulse`   | Enable a pulsing animation on the status dot (`variant: status`). |

## `button-group`

A row of related buttons. (Also documented in [Navigation Components](/en/navigation-components#button-group); combine with `dropdown-menu` for a split-button.)

| Property   | Description                                              |
| ---------- | -------------------------------------------------------- |
| `children` | The grouped `button` components (and optional dropdown). |
| `props`    | HTML attributes (e.g. `className`).                      |

## Related Pages

- [Pages Overview](/en/pages-overview) — actions and response handlers.
- [Interactivity & Scripts](/en/interactivity-scripts) — click/hover/entrance behavior in depth.
- [Form Controls](/en/form-controls) — inputs that buttons submit.
- [Navigation Components](/en/navigation-components) — menus and split-button patterns.

# Specialty Components

Specialty components serve focused use cases: multi-step wizards, drag-to-reorder lists, language switching, status dots, and standalone advanced inputs. Several are cross-referenced from other category pages (form-controls, social) where they fit more than one role. All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: wizard
    steps:
      - { id: account, label: Account, description: 'Set up your account' }
      - { id: profile, label: Profile }
    children:
      - { type: input, name: email }
      - { type: input, name: name }
```

## `wizard`

A stepped, multi-page flow with a progress indicator.

| Property      | Description                       |
| ------------- | --------------------------------- |
| `steps`       | Step definitions (see below).     |
| `initialStep` | The step `id` shown first.        |
| `children`    | The components rendered per step. |

Each step:

| Step property | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| `id`          | Unique step identifier (used for navigation and `initialStep`). |
| `label`       | Display text in the progress indicator.                         |
| `icon`        | Lucide icon name in the step indicator.                         |
| `description` | Short description below the step label.                         |

## `reorderable-list`

A list whose items can be reordered by drag-and-drop or keyboard. (Also documented in [Interactivity & Scripts](/en/interactivity-scripts#reorderable-list).)

| Property     | Description                                    |
| ------------ | ---------------------------------------------- |
| `dragHandle` | Enable drag-and-drop reordering of list items. |
| `onReorder`  | Action fired when items are reordered.         |
| `children`   | The list items (each with a drag handle).      |

## `language-switcher`

A control that switches the active language for an internationalized app.

| Property | Description                                                          |
| -------- | -------------------------------------------------------------------- |
| `props`  | HTML attributes and display options (e.g. `className`, label style). |

See [Languages](/en/languages) for i18n configuration.

## `status-indicator`

A colored status dot with a label (also expressible as `badge` with `variant: status`).

| Property | Description                                      |
| -------- | ------------------------------------------------ |
| `label`  | Status label text next to the dot.               |
| `color`  | Dot color (CSS color value or theme token name). |
| `pulse`  | Enable a pulsing animation on the dot.           |

## `file-upload`

A file picker with optional drag-and-drop. (Also documented in [Form Controls](/en/form-controls#file-upload).)

| Property      | Description                                            |
| ------------- | ------------------------------------------------------ |
| `accept`      | Accepted MIME types/extensions (e.g. `image/*, .pdf`). |
| `dropZone`    | Enable a drag-and-drop dropzone area.                  |
| `maxFiles`    | Maximum number of files per upload.                    |
| `maxFileSize` | Maximum file size in bytes (e.g. `10485760` for 10MB). |

## `number-input`

A numeric input with stepper buttons. (Also documented in [Form Controls](/en/form-controls#number-input).)

| Property       | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `min`          | Minimum value.                                              |
| `max`          | Maximum value.                                              |
| `step`         | Step increment.                                             |
| `showStepper`  | Show increment/decrement stepper buttons (default: `true`). |
| `defaultValue` | Initial numeric value.                                      |

## `time-picker`

A time input. (Also documented in [Form Controls](/en/form-controls#time-picker).)

| Property      | Description                                   |
| ------------- | --------------------------------------------- |
| `minTime`     | Minimum selectable time (HH:mm).              |
| `maxTime`     | Maximum selectable time (HH:mm).              |
| `stepMinutes` | Minute increment for selection (default: 15). |

## `comments` / `ai-chat`

Engagement components documented in [Social Components](/en/social-components): `comments` (threaded comments, public/guest), `commentCount`, and `ai-chat` (an AI-agent chat panel).

## Related Pages

- [Pages Overview](/en/pages-overview) — the component model and actions.
- [Form Controls](/en/form-controls) — `file-upload`, `number-input`, `time-picker`.
- [Social Components](/en/social-components) — `comments`, `commentCount`, `ai-chat`.
- [Languages](/en/languages) — i18n for `language-switcher`.
- [Agents](/en/ai-agents) — agents powering `ai-chat`.

# Forms Overview

Forms capture input from submitters and route it somewhere useful — into a table, through an automation, into the built-in submission ledger, or any combination of the three. They are declared in the top-level `forms` array, each one reachable at its own URL, embeddable inside a page, and addressable from an automation trigger.

A form is the public-facing counterpart to a table: where a table defines _what_ data looks like, a form defines _how_ people contribute it. The same form can write directly to a `tables[]` entry, fire a `notify-sales` automation, or simply land in the platform's `form_submissions` ledger for later review.

```yaml
forms:
  - id: 1
    name: contact
    title: Contact Sales
    path: /contact
    submitTo:
      table: leads
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: table-field, column: message }
```

## Form Properties

Each entry in the `forms` array accepts the following properties.

| Property       | Description                                                                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Unique positive integer identifying the form. Must be unique across `forms[]`.                                                                                             |
| `name`         | Kebab-case unique identifier (`^[a-z][a-z0-9-]*`, 1–64 chars). Referenced by page components (`formRef`) and the form automation trigger. Must be unique across `forms[]`. |
| `title`        | Human-friendly title shown to submitters. Supports `$t:` i18n keys.                                                                                                        |
| `description`  | Optional intro paragraph rendered above the first field.                                                                                                                   |
| `path`         | Optional friendly public URL (e.g. `/contact`). When set, the form is served there _and_ at the canonical `/forms/{name}`. See [Public Routes](#public-routes).            |
| `submitTo`     | Where the submission is persisted and/or routed: a table, an automation, the ledger, or a combination. Required. See [Submit Targets](#submit-targets).                    |
| `fields`       | Ordered list of field definitions rendered in the form. At least one required. See [Form Fields](/en/form-fields).                                                         |
| `layout`       | Rendering mode: `single-page` (default), `multi-step`, or `one-question`. See [Multi-Step Forms](/en/form-multi-step).                                                     |
| `steps`        | Step definitions for `multi-step` / `one-question` layouts. See [Multi-Step Forms](/en/form-multi-step).                                                                   |
| `fieldGroups`  | Labeled section dividers grouping fields within a single-page layout.                                                                                                      |
| `display`      | Cosmetic options (columns, progress bar, submit label, per-form theme). See [Multi-Step Forms](/en/form-multi-step).                                                       |
| `access`       | Access control: `all`, `authenticated`, or a role list, with an optional `redirectTo`. See [Access Control](#access-control).                                              |
| `availability` | Submission window (`opensAt`, `closesAt`) and submission cap (`maxSubmissions`), with an optional custom closed-form page.                                                 |
| `antiSpam`     | Honeypot, sliding-window rate limits, and a CAPTCHA connection stub.                                                                                                       |
| `analytics`    | Per-form opt-out (`enabled: false`) excluding the form from aggregate analytics. Defaults to enabled.                                                                      |
| `prefill`      | Map of form field → `$query.{name}` / `$user.{prop}` / `$parent.{path}` reference or literal default. See [Form Fields](/en/form-fields).                                  |
| `submitter`    | Save-and-resume, edit-after-submit, and unique-submission rules.                                                                                                           |
| `onSuccess`    | Post-submit behavior (success page, redirect, reset, toast, inline message). See [Submissions](/en/form-submissions).                                                      |
| `onError`      | What to show when a submission fails server-side (toast, inline message, error page). See [Submissions](/en/form-submissions).                                             |

## Submit Targets

The `submitTo` object decouples a form from any single persistence model. At least one of `table`, `automation`, or `storeSubmission: true` (the default) must be set — otherwise the submission would be discarded silently and the schema rejects the config.

| Property          | Description                                                                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table`           | Persist the submission as a record in this table. References a `tables[].name`; validated against the app's `tables[]` array.                                                     |
| `automation`      | Invoke this automation _after_ the writes commit. References an `automations[].name`; validated against the app's `automations[]` array.                                          |
| `mapping`         | Map form field names to destination column names. Defaults to identity (form field name = table column name). A mapping target that does not exist on the table fails validation. |
| `storeSubmission` | Persist the submission in the built-in `form_submissions` ledger. Defaults to `true` — set `false` to opt out (and then `table` or `automation` is mandatory).                    |

```yaml
submitTo:
  table: support_tickets
  automation: page-on-call
  mapping:
    userEmail: email # form field 'userEmail' -> table column 'email'
```

:::callout
**Tables, automations, the ledger — or all three.** A form can dual-write to a `table` and the ledger, fire an automation, or do everything at once. The table write and the ledger write happen inside a single transaction; the automation runs only after both commit. See [Submissions](/en/form-submissions) for the full dual-write contract.
:::

## Public Routes

Every form is reachable at the canonical route `/forms/{name}` regardless of configuration — a form without a `path` is not private, it is simply only reachable there. When `path` is set, the form is served at that custom path **and** at `/forms/{name}` simultaneously (no redirect; both URLs render the same form).

| Rule              | Description                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| Canonical route   | `/forms/{name}` always serves the form (HTTP 200). An unknown name returns 404.                                  |
| Custom path       | Optional. Must start with `/`, 2–256 URL-safe characters; static (no `:id` dynamic segments).                    |
| Reserved prefixes | `/api/`, `/admin/`, `/forms/`, and `/auth/` are rejected so a form cannot shadow a built-in route.               |
| Collision rule    | A `forms[].path` MUST NOT collide with any `pages[].path`. Collisions fail validation with an error naming both. |
| Embed route       | `/forms/{name}/embed` serves a minimal HTML shell for iframe embedding on third-party sites.                     |

## Access Control

The `access` object reuses the shared permission model used by tables, pages, buckets, automations, and agents.

| Property     | Description                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `require`    | `'all'` (everyone, including anonymous), `'authenticated'` (any logged-in user), or a role list (`['admin', 'editor']`). |
| `redirectTo` | Optional path (e.g. `/login`) to redirect denied submitters to, instead of returning a 401/403. Must start with `/`.     |

```yaml
forms:
  - id: 2
    name: member-survey
    title: Member Survey
    access:
      require: authenticated
      redirectTo: /login
    submitTo: { table: survey_responses }
    fields:
      - { kind: standalone, name: rating, inputType: rating, required: true }
```

:::callout
**`$user.*` references require authentication.** A form whose `access.require` is `'all'` (the default) may not carry a per-field `defaultValue` referencing `$user.*` — the value would always resolve empty for anonymous visitors and could leak session state. Set `access.require` to `authenticated` or a role list, or use top-level `prefill` (which silently drops unresolvable `$user` references on public forms). See [Form Fields](/en/form-fields).
:::

## Embedding a Form in a Page

A top-level form can be rendered inline inside a page via the form control's `formRef`. The form is defined once and reused anywhere — fields, validation, conditional logic, multi-step layout, file uploads, and `onSuccess`/`onError` all flow from `app.forms[]`. The host page's access control is intersected with the form's own rules at render time.

```yaml
pages:
  - id: 1
    name: landing
    path: /
    components:
      - type: form
        formRef: contact # renders the top-level "contact" form inline
        props:
          label: Get in touch # display-only override of the submit label
```

See [Form Controls](/en/form-controls) for the page-component side of `formRef`.

## Related Pages

- [Form Fields](/en/form-fields) — standalone vs table-bound fields, prefill, inline relationship create.
- [Conditional Logic](/en/form-conditional-logic) — visible / required / disabled rules.
- [Multi-Step Forms](/en/form-multi-step) — steps, branching, one-question layouts, display overrides.
- [Submissions](/en/form-submissions) — the dual-write ledger, success and error handling.
- [File Uploads](/en/form-file-uploads) — attachment fields backed by buckets.
- [Tables Overview](/en/tables-overview) — the data models forms write to.
- [Form Controls](/en/form-controls) — embedding a form inside a page.
- [Auth](/en/auth-overview) — roles and authentication behind `access`.

# Form Fields

A form's `fields` array is an ordered list of field definitions rendered top to bottom. Each field is one of five **kinds**, discriminated by a `kind` property. Table-bound fields inherit their type and validation from a table column; standalone fields are typed inline; calculation, section, and signature fields cover computed values, dividers, and signatures.

```yaml
forms:
  - id: 1
    name: signup
    title: Create your account
    submitTo: { table: users }
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: newsletter, inputType: checkbox, label: Subscribe to updates }
```

## Field Kinds

| Kind          | Description                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `table-field` | Bound to a column on `submitTo.table`. Type, validation, and persistence flow from the table schema; the form overrides only display. |
| `standalone`  | Typed inline via `inputType`; not persisted to a column directly. Use for forms that route only to automations or the ledger.         |
| `calculation` | Read-only computed value derived from other fields via a `{{fieldName}}` formula. Renders no input.                                   |
| `section`     | Visual divider with an optional heading and description. Renders no input.                                                            |
| `signature`   | Captures a hand-drawn or typed signature.                                                                                             |

## Common Field Properties

Every input-bearing field kind (`table-field`, `standalone`, `calculation`, `signature`) shares a common base.

| Property       | Description                                                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `label`        | Label shown to the submitter. Supports `$t:` i18n keys.                                                                                |
| `placeholder`  | Placeholder text shown when the field is empty.                                                                                        |
| `helpText`     | Help text rendered below the field.                                                                                                    |
| `required`     | Boolean. When `true`, the field must have a value. For conditional requiredness use `requiredWhen`.                                    |
| `readOnly`     | Boolean. Renders the field display-only.                                                                                               |
| `hidden`       | Boolean. Hides the field from the UI but still submits it (server-only value).                                                         |
| `defaultValue` | Literal value, or a `$query.{name}` / `$user.{prop}` reference resolved at render time.                                                |
| `visibleWhen`  | Conditional visibility rule. See [Conditional Logic](/en/form-conditional-logic).                                                      |
| `requiredWhen` | Conditional required rule (same shape as `visibleWhen`).                                                                               |
| `disabledWhen` | Conditional disabled rule (same shape as `visibleWhen`).                                                                               |
| `permissions`  | Per-field `read` permission. When the requesting role is excluded, the value is redacted from admin exports and per-submission detail. |

## Table-Bound Fields

A `kind: table-field` references a `column` on the form's `submitTo.table`. The field type, validation, and persistence all come from the table schema — the form supplies only display concerns plus, for attachment columns, upload options.

| Property      | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `column`      | Column name on `submitTo.table`. Required.                       |
| `accept`      | Comma-separated MIME types or extensions for attachment columns. |
| `maxFileSize` | Maximum size (bytes) per uploaded file (attachment columns).     |
| `maxFiles`    | Maximum number of files for `multiple-attachments` columns.      |
| `dropZone`    | Render a drag-and-drop zone alongside the file picker.           |

```yaml
fields:
  - kind: table-field
    column: subject
    label: What can we help with?
    placeholder: Briefly describe the issue
  - kind: table-field
    column: priority
    helpText: Urgent issues are triaged first
```

Attachment columns (`single-attachment`, `multiple-attachments`) automatically render a file input. See [File Uploads](/en/form-file-uploads) for the upload pipeline and bucket binding.

## Standalone Fields

A `kind: standalone` field is typed inline via `inputType` and is not written to a table column directly. It is ideal for forms that route to an automation or live only in the submission ledger.

| Property      | Description                                                                         |
| ------------- | ----------------------------------------------------------------------------------- |
| `name`        | Field name unique within the form (`^[a-zA-Z][a-zA-Z0-9_-]*`, ≤64 chars). Required. |
| `inputType`   | Control type (see below). Required.                                                 |
| `options`     | `{ value, label }` choices for `select` / `multi-select` / `radio`.                 |
| `accept`      | Accepted MIME types for `attachment` input.                                         |
| `maxFiles`    | Max files for `attachment` input.                                                   |
| `maxFileSize` | Maximum size (bytes) per uploaded file.                                             |
| `dropZone`    | Render a drag-and-drop zone alongside the file picker.                              |

**Available `inputType` values:** `short-text`, `long-text`, `email`, `url`, `phone`, `number`, `date`, `datetime`, `select`, `multi-select`, `checkbox`, `radio`, `rating`, `attachment`.

```yaml
fields:
  - kind: standalone
    name: rating
    inputType: rating
    label: How was your experience?
    required: true
  - kind: standalone
    name: source
    inputType: select
    label: How did you hear about us?
    options:
      - { value: search, label: Search engine }
      - { value: referral, label: Referral }
      - { value: social, label: Social media }
```

## Calculation, Section & Signature Fields

| Kind          | Key properties                                                                                                                         |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `calculation` | `name`, `formula` (references other fields via `{{name}}`), optional `format` (`number` / `currency` / `percent` / `text`). Read-only. |
| `section`     | Optional `heading`, `description`, and a whole-section `visibleWhen` rule. Renders no input.                                           |
| `signature`   | `name`. Captures a hand-drawn or typed signature.                                                                                      |

```yaml
fields:
  - { kind: standalone, name: quantity, inputType: number, label: Quantity }
  - { kind: standalone, name: unit_price, inputType: number, label: Unit price }
  - kind: calculation
    name: total
    label: Total
    formula: '{{quantity}} * {{unit_price}}'
    format: currency
```

## Prefill

The top-level `prefill` map seeds field values at render time. Keys are form field names; values are either a literal default or a reference:

| Reference        | Resolves to                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `$query.{name}`  | A URL query-string parameter (e.g. `$query.utm_source`).                                                     |
| `$user.{prop}`   | A property of the authenticated user (e.g. `$user.email`). Silently dropped on public forms with no session. |
| `$parent.{path}` | A field of the parent record — only valid for inline-relationship forms (see below).                         |

```yaml
forms:
  - id: 1
    name: lead-capture
    title: Request a demo
    submitTo: { table: leads }
    prefill:
      utm_source: $query.utm_source
      utm_campaign: $query.utm_campaign
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: utm_source, inputType: short-text, hidden: true }
      - { kind: standalone, name: utm_campaign, inputType: short-text, hidden: true }
```

:::callout
**Two ways to default a value.** Per-field `defaultValue` accepts `$query` / `$user` references inline, while the top-level `prefill` map keeps prefill wiring in one place. On a public form (`access.require: all`), per-field `defaultValue: $user.*` is rejected at validation time — use top-level `prefill` (which tolerates an empty `$user` resolution) or require authentication.
:::

## Inline Relationship Create

When a form is embedded inside a parent record's detail page (e.g. a "+ New ticket" button on a Project page), the `$parent.{path}` prefill source ties the new child back to its parent automatically. This is configured on the page form control via `inlinePrefill`.

| Property      | Description                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `prefill`     | Field-name → prefill-source map (same `$query` / `$user` / `$parent` union).                                              |
| `lockPrefill` | When `true`, the prefilled fields are hidden and cannot be overridden (still validated server-side). Defaults to `false`. |

```yaml
forms:
  - id: 1
    name: new-ticket
    submitTo: { table: tickets }
    fields:
      - { kind: table-field, column: title, required: true }
      - { kind: table-field, column: project_id }
      - { kind: table-field, column: reporter_id }

pages:
  - id: 1
    name: project-detail
    path: /portal/projects/:id
    components:
      - type: form
        formRef: new-ticket
        inlinePrefill:
          prefill:
            project_id: $parent.id # locked to the current project
            reporter_id: $user.id
          lockPrefill: true
```

On submit, the engine revalidates parent existence to defend against stale `$parent` references. Both single and multi-relationship columns are supported.

## Related Pages

- [Forms Overview](/en/forms-overview) — form metadata, submit targets, access control.
- [Conditional Logic](/en/form-conditional-logic) — `visibleWhen` / `requiredWhen` / `disabledWhen`.
- [Multi-Step Forms](/en/form-multi-step) — distributing fields across steps.
- [File Uploads](/en/form-file-uploads) — attachment input options and bucket binding.
- [Relational Fields](/en/relational-fields) — the relationship columns `$parent` targets.
- [Form Controls](/en/form-controls) — the page component that hosts `formRef` + `inlinePrefill`.

# Form Conditional Logic

Conditional logic makes a form respond to what the submitter enters: fields appear, become required, or grey out depending on the values of other fields. Three rule properties drive this — `visibleWhen`, `requiredWhen`, and `disabledWhen` — and all three share the same condition shape, so once you learn one you know all three.

```yaml
fields:
  - {
      kind: standalone,
      name: has_company,
      inputType: checkbox,
      label: I'm signing up on behalf of a company,
    }
  - kind: standalone
    name: company_name
    inputType: short-text
    label: Company name
    visibleWhen: { field: has_company, operator: eq, value: true }
    requiredWhen: { field: has_company, operator: eq, value: true }
```

## Rule Properties

| Property       | Effect when the condition is **true**                                         |
| -------------- | ----------------------------------------------------------------------------- |
| `visibleWhen`  | The field (or section) is shown. When false, it is hidden and not submitted.  |
| `requiredWhen` | The field becomes required. When false, it is optional.                       |
| `disabledWhen` | The field is disabled (greyed out, not editable). When false, it is editable. |

Each rule lives on a field's common base, so it can be applied to any input-bearing field kind. `section` fields support `visibleWhen` to show or hide an entire labeled group.

## Simple Conditions

A simple condition compares one field's current value against a target using an operator.

| Property   | Description                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `field`    | Name of the field whose value is evaluated.                                                                             |
| `operator` | Comparison operator (see table below).                                                                                  |
| `value`    | Value to compare against. A scalar for comparison operators; an array for membership; omitted for `empty` / `notEmpty`. |

### Condition Operators

| Operator   | Meaning                               |
| ---------- | ------------------------------------- |
| `eq`       | Equals the value.                     |
| `neq`      | Does not equal the value.             |
| `contains` | String/array contains the value.      |
| `empty`    | Field has no value (ignores `value`). |
| `notEmpty` | Field has a value (ignores `value`).  |
| `gt`       | Greater than the value.               |
| `gte`      | Greater than or equal to the value.   |
| `lt`       | Less than the value.                  |
| `lte`      | Less than or equal to the value.      |
| `in`       | Value is one of the array members.    |
| `notIn`    | Value is none of the array members.   |

```yaml
fields:
  - kind: standalone
    name: contact_method
    inputType: select
    label: Preferred contact method
    options:
      - { value: email, label: Email }
      - { value: phone, label: Phone }
  - kind: standalone
    name: phone
    inputType: phone
    label: Phone number
    visibleWhen: { field: contact_method, operator: eq, value: phone }
    requiredWhen: { field: contact_method, operator: eq, value: phone }
```

## Compound Conditions (AND / OR)

Conditions compose with `and` / `or` and may nest arbitrarily. An `and` block is true when **every** child is true; an `or` block is true when **any** child is true.

```yaml
fields:
  - kind: standalone
    name: expedite_reason
    inputType: long-text
    label: Why does this need to be expedited?
    visibleWhen:
      and:
        - { field: priority, operator: in, value: [high, urgent] }
        - or:
            - { field: budget, operator: gte, value: 10000 }
            - { field: vip_customer, operator: eq, value: true }
```

:::callout
**`disabledWhen` keeps a field present.** A disabled field still renders and still submits its current value — it just cannot be edited. Use `visibleWhen` when a field should disappear and stop submitting entirely; use `disabledWhen` when the value should remain but be locked.
:::

## Step Branching

In multi-step layouts, conditions also drive flow control. A step's `goToWhen` rules let a true condition jump to a different step instead of the linear next one, and a step-level `visibleWhen` skips the entire step. See [Multi-Step Forms](/en/form-multi-step) for the full branching model.

```yaml
steps:
  - id: account-type
    title: Account type
    fields: [plan]
    goToWhen:
      - when: { field: plan, operator: eq, value: enterprise }
        goTo: sales-contact
  - id: billing
    title: Billing
    fields: [card_number, billing_email]
  - id: sales-contact
    title: Talk to sales
    fields: [company, seats]
```

## Conditions Through `formRef`

When a top-level form is embedded in a page via the form control's `formRef`, all of its conditional logic comes along — `visibleWhen`, `requiredWhen`, `disabledWhen`, and step branching behave identically whether the form is rendered at `/forms/{name}` or inline on a host page. Define the conditions once on the form; every embed inherits them. See [Form Controls](/en/form-controls).

## Related Pages

- [Form Fields](/en/form-fields) — where `visibleWhen` / `requiredWhen` / `disabledWhen` live.
- [Multi-Step Forms](/en/form-multi-step) — step-level visibility and `goToWhen` branching.
- [Forms Overview](/en/forms-overview) — form metadata and submit targets.
- [Form Controls](/en/form-controls) — embedding a conditional form in a page.

# Multi-Step Forms

Long forms are easier to complete when they are broken into manageable pieces. The `layout` property chooses how a form's fields are presented: all at once, split into steps with previous/next navigation, or one field per screen Typeform-style. Steps support conditional skipping and branching so the path through the form can adapt to the submitter's answers.

```yaml
forms:
  - id: 1
    name: onboarding
    title: Set up your workspace
    layout: multi-step
    submitTo: { table: workspaces }
    fields:
      - { kind: standalone, name: workspace_name, inputType: short-text, required: true }
      - { kind: standalone, name: team_size, inputType: number }
      - { kind: standalone, name: use_case, inputType: long-text }
    steps:
      - { id: basics, title: The basics, fields: [workspace_name] }
      - { id: team, title: Your team, fields: [team_size] }
      - { id: goals, title: Your goals, fields: [use_case] }
```

## Layout Modes

| Mode           | Description                                                                        |
| -------------- | ---------------------------------------------------------------------------------- |
| `single-page`  | All fields on one page (default). Steps are ignored.                               |
| `multi-step`   | Fields grouped into `steps[]` with previous/next navigation.                       |
| `one-question` | One field per screen, advancing automatically. Driven by the same `steps[]` model. |

## Step Definitions

When `layout` is `multi-step` or `one-question`, the `steps` array partitions the form's fields into ordered screens. Each step references field names defined in the parent `fields` array.

| Property      | Description                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`          | Unique step id within the form (kebab-case recommended, ≤64 chars). Required.                                                                    |
| `title`       | Step title shown above the fields.                                                                                                               |
| `description` | Step intro paragraph.                                                                                                                            |
| `fields`      | Field names belonging to this step. Each must match a field's `name` (standalone/calculation/signature) or `column` (table-field). At least one. |
| `visibleWhen` | Whole-step visibility rule. When false, the entire step is skipped. Uses the [conditional](/en/form-conditional-logic) shape.                    |
| `goToWhen`    | Branching rules. The first matching rule jumps to its `goTo` step instead of the linear next step.                                               |

## Navigation & Branching

By default a multi-step form advances linearly: step 1 → step 2 → step 3. Two mechanisms override that flow.

**Skip a step** with a step-level `visibleWhen` — when the condition is false the step is removed from the sequence entirely.

**Branch to a different step** with `goToWhen`. Each rule has a `when` condition and a `goTo` target step id; the first matching rule wins, otherwise linear flow continues.

```yaml
steps:
  - id: plan
    title: Choose a plan
    fields: [plan]
    goToWhen:
      # Enterprise plans skip self-serve billing and route to a sales step
      - when: { field: plan, operator: eq, value: enterprise }
        goTo: sales
  - id: billing
    title: Payment
    fields: [card_number]
  - id: sales
    title: Talk to sales
    fields: [company, seats]
    # only relevant for enterprise; hidden otherwise
    visibleWhen: { field: plan, operator: eq, value: enterprise }
```

:::callout
**`goTo` targets must exist.** Each `goToWhen[].goTo` must match a `steps[].id` in the same form. A linear next step is taken whenever no `goToWhen` rule matches.
:::

## One-Question-at-a-Time

The `one-question` layout presents a single field per screen for a focused, conversational experience. It reuses the same `steps[]` model — typically one field per step — and the same `visibleWhen` / `goToWhen` branching applies.

```yaml
forms:
  - id: 2
    name: survey
    title: Quick survey
    layout: one-question
    submitTo: { storeSubmission: true }
    display:
      progressBar: true
    fields:
      - {
          kind: standalone,
          name: nps,
          inputType: rating,
          label: How likely are you to recommend us?,
        }
      - {
          kind: standalone,
          name: reason,
          inputType: long-text,
          label: What's the main reason for your score?,
        }
    steps:
      - { id: q1, fields: [nps] }
      - { id: q2, fields: [reason] }
```

## Display Overrides

The `display` object adjusts how the form looks without affecting submission semantics.

| Property      | Description                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------ |
| `columns`     | Number of columns the fields are arranged in (1–4). Applies to single-page and per-step layouts. |
| `progressBar` | Show a progress bar in `multi-step` / `one-question` layouts. No effect on `single-page`.        |
| `submitLabel` | Submit button label (`Submit` by default). Supports `$t:` keys.                                  |
| `theme`       | Per-form overrides: `primaryColor`, `backgroundColor`, `borderRadius`.                           |

```yaml
forms:
  - id: 3
    name: registration
    title: Event registration
    layout: multi-step
    display:
      columns: 2
      progressBar: true
      submitLabel: Complete registration
      theme:
        primaryColor: '#4f46e5'
        borderRadius: 0.5rem
    submitTo: { table: registrations }
    fields:
      - { kind: table-field, column: first_name, required: true }
      - { kind: table-field, column: last_name, required: true }
      - { kind: table-field, column: email, required: true }
      - { kind: table-field, column: dietary_notes }
    steps:
      - { id: name, title: Your name, fields: [first_name, last_name] }
      - { id: contact, title: Contact & preferences, fields: [email, dietary_notes] }
```

## Related Pages

- [Form Fields](/en/form-fields) — the fields distributed across steps.
- [Conditional Logic](/en/form-conditional-logic) — the condition shape used by `visibleWhen` and `goToWhen`.
- [Forms Overview](/en/forms-overview) — `layout`, `steps`, and `display` in the full form schema.
- [Submissions](/en/form-submissions) — what happens after the final step.

# Form Submissions

Every form submission produces a durable record. By default it lands in the built-in `form_submissions` ledger — the platform's canonical "this form received an answer" log — and, when `submitTo.table` is set, in your own table too. The two writes are transactional, so you never end up with a ledger entry promising a record that was never written. After the writes commit, `onSuccess` decides what the submitter sees and `onError` covers failures.

```yaml
forms:
  - id: 1
    name: contact
    submitTo:
      table: leads
      # storeSubmission defaults to true — table AND ledger
    fields:
      - { kind: table-field, column: email, required: true }
    onSuccess:
      type: toast
      variant: success
      message: Thanks! We'll be in touch.
```

## The Submission Ledger

The `form_submissions` ledger lives in an internal Sovrium-managed schema (mirroring the isolation of `auth.*`) — you never create or manage it yourself. Every submission writes one ledger row by default; set `submitTo.storeSubmission: false` to opt out (in which case `table` or `automation` becomes mandatory).

| Column                 | Type           | Description                                                                       |
| ---------------------- | -------------- | --------------------------------------------------------------------------------- |
| `id`                   | UUID           | Stable submission id; surfaced to `onSuccess` templates via `$submission.id`.     |
| `form_name`            | text           | The `forms[].name` at submission time.                                            |
| `form_id`              | integer        | The `forms[].id` at submission time (denormalized for joins).                     |
| `submitted_at`         | timestamptz    | Server timestamp when the row was created.                                        |
| `submitter_user_id`    | UUID, nullable | The authenticated user, when the form requires authentication.                    |
| `submitter_ip`         | inet, nullable | Submitter IP (stored hashed by default) — used by anti-spam and audit.            |
| `submitter_user_agent` | text, nullable | Submitter user-agent string.                                                      |
| `data`                 | jsonb          | The full validated answer payload (mirrors what was written to `submitTo.table`). |
| `linked_record_table`  | text, nullable | The bound table name, when `submitTo.table` is set.                               |
| `linked_record_id`     | text, nullable | The inserted record's id (text-typed to handle integer / UUID / string ids).      |
| `status`               | enum           | Lifecycle state (see below).                                                      |
| `status_reason`        | text, nullable | Short reason when `status` is `failed` or `spam`.                                 |

## Lifecycle Status

| State        | Meaning                                                                            | Transitions to                                    |
| ------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------- |
| `received`   | Accepted; written to the ledger and bound table (if any).                          | `processing` (if automation), `done` (otherwise). |
| `processing` | The bound automation is running.                                                   | `done` on success, `failed` on terminal failure.  |
| `done`       | Terminal — all writes and the bound automation completed.                          | —                                                 |
| `spam`       | Terminal — the anti-spam pipeline classified it as spam; preserved for moderation. | —                                                 |
| `failed`     | Terminal — a downstream step failed and was not retried; `status_reason` is set.   | —                                                 |

## The Dual-Write Contract

When `submitTo.table` is set, the submission writes one row to that table **and** one ledger row inside a single transaction. If the table write fails — a constraint violation, type error, or foreign-key miss — the ledger row rolls back too, and the submitter receives an HTTP 4xx/5xx error with `fieldErrors:[{ name, message }]` naming the offending column. No "ghost" ledger entry is ever left behind.

When `submitTo.automation` is set, the automation is invoked **after** both writes commit. An automation failure does **not** roll back the writes — the submission is recorded, `status` moves to `failed`, and the automation's own retry/failure machinery applies.

```yaml
forms:
  - id: 2
    name: stream-event
    submitTo:
      automation: post-event-to-stream
      storeSubmission: false # opt out — ledger is skipped; automation handles persistence
    fields:
      - { kind: standalone, name: event_payload, inputType: long-text }
```

:::callout
**Bypass the ledger only when you mean it.** `storeSubmission: false` is the only way to skip the ledger and is intended for very high-volume forms that route to a stream or queue. Whenever it is set, `submitTo` must still specify a `table` or an `automation`, or validation fails — a form that persists nowhere is a configuration bug.
:::

## On Success

The `onSuccess` object decides what the submitter sees after a successful submission. It is a discriminated union on `type`.

| `type`        | Behavior                                                                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `successPage` | Render a custom success page (`title`, `message`, optional `buttonLabel` + `buttonHref`, optional `actions[]`, `showSummary`).                 |
| `redirect`    | Navigate to `url` after an optional `delaySeconds` (default 2; `0` is immediate). Supports `$submission.id` / `$record.id` template variables. |
| `reset`       | Clear the form for another submission, with an optional `message` and `preserveFields[]` to retain.                                            |
| `toast`       | Show a transient toast (`message`, optional `variant`: `success` / `info`).                                                                    |
| `message`     | Replace the form with an inline `message` in place.                                                                                            |

```yaml
onSuccess:
  type: redirect
  url: /thank-you?ref=$submission.id
  delaySeconds: 0
```

A `successPage` may render `actions[]` buttons — each is either `action: reset` (submit another) or `action: navigate` (link to `url`) — and `showSummary: true` lists the submitted values, honoring hidden fields and per-field read permissions.

## On Error

The `onError` object controls the message shown when a submission fails server-side.

| Property  | Description                                                               |
| --------- | ------------------------------------------------------------------------- |
| `type`    | `toast`, `message` (inline), or `errorPage` (full page).                  |
| `message` | Body message. Supports `$t:` keys.                                        |
| `title`   | Optional title (used by `errorPage`).                                     |
| `variant` | Toast variant (`error` / `warning`) — only meaningful when `type: toast`. |

```yaml
onError:
  type: message
  message: Something went wrong saving your request. Please try again.
```

:::callout
**Field-level validation errors are separate.** Server-side validation failures (e.g. an invalid email or a foreign-key violation) return HTTP 400 with a `fieldErrors:[{ name, message }]` envelope and are surfaced inline on the offending field — independently of `onError`, which covers whole-submission failures.
:::

## Related Pages

- [Forms Overview](/en/forms-overview) — `submitTo`, `storeSubmission`, and the `onSuccess` / `onError` schema.
- [Form Fields](/en/form-fields) — per-field `permissions` that redact ledger exports.
- [File Uploads](/en/form-file-uploads) — file metadata stored in the ledger `data` payload.
- [Tables Overview](/en/tables-overview) — the bound table the dual-write targets.

# Form File Uploads

Forms can collect files — resumes, invoices, photos, documents — and persist them to your own storage instead of a third-party CDN. Attachment fields render a file picker (and optional drag-and-drop zone), validate type and size before upload, show progress and previews, and submit a canonical `{ url, name, size, mimeType }` metadata object. Files land in a configured `app.buckets[]` destination on your S3, local disk, or database storage.

```yaml
buckets:
  - name: applications
    default: true
    backend: s3
    config: { bucket: $env.S3_BUCKET, region: us-east-1 }

forms:
  - id: 1
    name: apply
    title: Job Application
    path: /apply
    submitTo: { table: applications }
    fields:
      - { kind: standalone, name: full_name, inputType: single-line-text, required: true }
      - kind: standalone
        name: resume
        inputType: attachment
        label: Resume
        required: true
        accept: 'application/pdf,.doc,.docx'
        maxFileSize: 10485760 # 10 MB
        dropZone: true
```

## Attachment Field Configuration

Attachment behavior is configured the same way on both field kinds: a `kind: standalone` field with `inputType: attachment`, or a `kind: table-field` whose underlying column is `single-attachment` / `multiple-attachments`. The upload props are shared.

| Property      | Description                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `accept`      | Comma-separated MIME types or extensions restricting the file dialog (e.g. `image/*`, `application/pdf`, `.doc,.docx`). |
| `maxFileSize` | Maximum size in bytes per file. Larger files are rejected with an inline error before upload starts.                    |
| `maxFiles`    | Maximum number of files (multiple-file fields only). Selecting more surfaces an inline error.                           |
| `dropZone`    | Render a drag-and-drop area alongside the picker, accepting the same files.                                             |

:::callout
**Single vs multiple.** A single-file attachment submits one `FileMetadata` object (or `null` when empty); a multiple-file attachment submits a `FileMetadata[]` array (or `[]`). For table-bound fields the multiplicity is inferred from the column type (`single-attachment` vs `multiple-attachments`); for standalone fields it follows the upload UI presented by `inputType: attachment` and `maxFiles`.
:::

## Bucket Binding

The storage destination comes from `app.buckets[]`. A form inherits a **default bucket**: the bucket whose `default: true` flag is set, or the only bucket when exactly one is defined. Files are uploaded there on submit, and the form payload carries canonical metadata for each file. Per-field bucket overrides are reserved for a follow-up release.

```yaml
buckets:
  - name: documents
    default: true
    backend: local
    config: { path: ./storage/documents }

forms:
  - id: 2
    name: invoice-upload
    title: Upload Invoice
    submitTo: { automation: process-invoice }
    fields:
      - { kind: standalone, name: vendor, inputType: single-line-text, required: true }
      - kind: standalone
        name: document
        inputType: attachment
        accept: 'application/pdf,image/*'
        maxFileSize: 20971520 # 20 MB
        dropZone: true
```

## Upload UX

The attachment field renders a complete upload experience:

| Behavior             | Description                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Type filter          | `accept` restricts both the browser dialog and drag-and-drop; mismatched files surface an inline error.             |
| Size validation      | `maxFileSize` rejects oversized files before upload begins.                                                         |
| Progress indicator   | A progress bar or spinner is shown while each file uploads.                                                         |
| Preview              | Image files render a thumbnail after upload; non-image files render filename + size.                                |
| Remove               | Selected files can be removed before submit (keyboard-accessible); removing one of many does not affect the others. |
| Required enforcement | A `required` attachment field with no file blocks submission with an inline error.                                  |

## File Metadata Shape

When the form submits, each attachment value is normalized to a canonical metadata object — the same shape consumed by `submitTo.table`, `submitTo.automation` triggers, and the `form_submissions` ledger `data` payload.

```typescript
type FileMetadata = {
  url: string // canonical URL into the bucket (signed when the bucket is private)
  name: string // original filename
  size: number // bytes
  mimeType: string // detected MIME type
}
```

A single-file field submits `FileMetadata | null`; a multiple-file field submits `FileMetadata[]`. Routing the upload to an automation makes the same metadata available in the trigger payload — for example to run an AI extraction over `{{trigger.data.document.url}}`.

## Related Pages

- [Form Fields](/en/form-fields) — the field kinds attachment uploads extend.
- [Forms Overview](/en/forms-overview) — `submitTo` targets that receive file metadata.
- [Submissions](/en/form-submissions) — file metadata stored in the ledger `data` payload.
- [Buckets](/en/buckets-overview) — configuring S3, local, and database storage backends.

# Authentication Overview

Sovrium ships authentication as a first-class platform capability powered by [Better Auth](https://better-auth.com). A single `auth` block in your app config enables sign-up, sign-in, sessions, role-based access control, and admin user management — no auth code to write.

The `auth` block answers one question: **does this app have users?** When it is present, authentication is on; when it is omitted, every `/api/auth/*` route returns `404` and the app is fully public.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
```

That four-line config gives you working email/password sign-up and sign-in, server-managed sessions, the three built-in roles, and the admin user-management endpoints.

## Enabling Authentication

Authentication is enabled by the **presence** of the `auth` object. There is no `auth.enabled: true` flag.

| State          | Result                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------- |
| `auth` omitted | App is public. All `/api/auth/*` routes return `404`. No identity, no sessions.               |
| `auth` present | Auth is on. Sign-up/sign-in routes mount, sessions are issued, RBAC and admin features apply. |

At minimum the `auth` block requires a non-empty `strategies` array (at least one strategy, no duplicate types). Everything else is optional and layered on top.

:::callout
**Admin features are always on.** When `auth` is configured, user management, role assignment, and impersonation endpoints are mounted automatically — there is no separate toggle. The first user to register becomes an admin (`firstUserAdmin`).
:::

## The `auth` Config Block

The `auth` object accepts the following top-level properties. Each links to its dedicated page.

| Property                | Description                                                                                                                                                    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `strategies`            | **Required.** Array of authentication strategies (email/password, magic link, OAuth). At least one; no duplicate types. See [Strategies](/en/auth-strategies). |
| `allowSignUp`           | Boolean. Controls self-registration. `true` (default) lets anyone sign up; `false` restricts user creation to admins. See [Strategies](/en/auth-strategies).   |
| `roles`                 | Array of custom role definitions layered on top of the built-in roles. See [Roles & RBAC](/en/auth-roles-rbac).                                                |
| `defaultRole`           | Role assigned to new users on registration. Defaults to `member`. See [Roles & RBAC](/en/auth-roles-rbac).                                                     |
| `groups`                | User groups for many-to-many membership and group-scoped permissions. See [Groups](/en/auth-groups).                                                           |
| `twoFactor`             | TOTP-based two-factor authentication. Requires the `emailAndPassword` strategy. See [Two-Factor](/en/auth-two-factor).                                         |
| `emailTemplates`        | Custom subject/body for authentication emails (verification, reset, magic link, OTP, invitation, …). See [Strategies](/en/auth-strategies).                    |
| `invitationTokenExpiry` | Lifetime of single-use admin invitation tokens. Duration string (`72h`, `7d`) or milliseconds. Defaults to `72h`.                                              |
| `scopeTables`           | Tables referenced by the multi-tenant `user_access` junction. Drives `$currentUser.assignments` scoping. See [Sessions](/en/auth-sessions).                    |
| `landingPath`           | Engine-resolver mount path for per-role post-login landing. See [Post-Login Landing](/en/auth-post-login).                                                     |
| `noAccessPath`          | Fallback path when no role's `defaultLanding` matches the session. Defaults to `/403`. See [Post-Login Landing](/en/auth-post-login).                          |

Infrastructure secrets (signing keys, callback URLs, OAuth credentials) live in environment variables — **not** in this schema. See [Environment Variables](/en/env-vars).

## Default Roles

Every Sovrium app with auth configured has three built-in roles available without any configuration. They cannot be redefined.

| Role     | Level | Access                                                                |
| -------- | ----- | --------------------------------------------------------------------- |
| `admin`  | 80    | Full access — manage users, roles, settings; all table permissions.   |
| `member` | 40    | Standard access to application resources (the default new-user role). |
| `viewer` | 10    | Read-only access.                                                     |

The numeric **level** establishes a hierarchy (higher = more privileged) used by permission resolution. Custom roles slot into this hierarchy with their own `level`. See [Roles & RBAC](/en/auth-roles-rbac) for definitions, hierarchy, and admin roles.

## Required Environment Variables

Two environment variables are required for production auth:

| Variable      | Purpose                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `AUTH_SECRET` | Secret key for signing tokens and encrypting sessions. Use a strong random string (32+ chars). |
| `BASE_URL`    | Base URL of the app (e.g. `https://myapp.com`). Used for auth callback URLs and email links.   |

```bash
AUTH_SECRET=your-strong-random-secret-32-chars-min
BASE_URL=https://myapp.com
```

:::callout
**Never commit `AUTH_SECRET`.** Treat it like a database password. Rotating it invalidates all active sessions. See [Environment Variables](/en/env-vars) for the full list, including OAuth `{PROVIDER}_CLIENT_ID` / `{PROVIDER}_CLIENT_SECRET` pairs.
:::

## Complete Example

```yaml
auth:
  # Two ways in: credentials + Google social login
  strategies:
    - type: emailAndPassword
      minPasswordLength: 12
      requireEmailVerification: true
    - type: oauth
      providers: [google, github]

  # Self-registration on, new users start as viewers
  allowSignUp: true
  defaultRole: viewer

  # One extra role beyond the built-ins
  roles:
    - name: editor
      description: Can edit content
      level: 30

  # Group membership for field-level permissions
  groups:
    - name: marketing
    - name: finance

  # TOTP 2FA (requires emailAndPassword above)
  twoFactor:
    issuer: MyApp
    backupCodes: true
```

## Where to Go Next

- [Strategies](/en/auth-strategies) — email/password, magic link, email-OTP, social/OAuth, registration control, and email templates.
- [Roles & RBAC](/en/auth-roles-rbac) — role definitions, hierarchy, and admin roles.
- [Groups](/en/auth-groups) — many-to-many membership and group-based permissions.
- [Sessions](/en/auth-sessions) — session config, revocation, and active-scope sessions.
- [Two-Factor](/en/auth-two-factor) — TOTP setup and recovery codes.
- [OAuth Server](/en/auth-oauth-server) — Sovrium as an OAuth/OIDC authorization server.
- [Post-Login Landing](/en/auth-post-login) — per-role landing and `$currentUser.assignments` interpolation.
- [Table Permissions](/en/table-permissions) — how roles and groups gate per-table and per-field access.

# Authentication Strategies

`auth.strategies` is a **required, non-empty array** declaring how users authenticate. Each entry is a discriminated union keyed by `type`. At least one strategy is required, and **no two entries may share the same `type`**.

```yaml
auth:
  strategies:
    - type: emailAndPassword
    - type: oauth
      providers: [google, github]
```

| `type`             | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `emailAndPassword` | Traditional credential-based sign-up and sign-in.                  |
| `magicLink`        | Passwordless sign-in via a one-time email link.                    |
| `oauth`            | Social login with external identity providers (Google, GitHub, …). |

:::callout
**Email-OTP is enabled differently.** There is no `type: emailOtp` strategy. Email-OTP turns on automatically when you supply an `auth.emailTemplates.emailOtp` template (see [Email-OTP](#email-otp) below).
:::

## Email & Password

The most common strategy. Credentials are validated server-side and a session is issued on success.

```yaml
auth:
  strategies:
    - type: emailAndPassword
      minPasswordLength: 12
      maxPasswordLength: 128
      requireEmailVerification: true
      autoSignIn: true
```

| Property                   | Description                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| `minPasswordLength`        | Minimum password length, 6–128. Defaults to `8`.                                           |
| `maxPasswordLength`        | Maximum password length, 8–256. Defaults to `128`.                                         |
| `requireEmailVerification` | Boolean. When `true`, users must verify their email before sign-in. Defaults to `false`.   |
| `autoSignIn`               | Boolean. When `true`, users are signed in automatically after sign-up. Defaults to `true`. |

When `requireEmailVerification: true`, a verification email is sent on sign-up using the `verification` template (see [Email Templates](#email-templates)).

## Magic Link

Passwordless authentication. The user enters their email, receives a one-time link, and is signed in by clicking it. Requires SMTP to be configured (see [Environment Variables](/en/env-vars)).

```yaml
auth:
  strategies:
    - type: magicLink
      expirationMinutes: 30
```

| Property            | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `expirationMinutes` | Link lifetime in minutes (positive integer). Defaults to `15`. |

The link body is rendered from the `magicLink` email template when provided.

## Email-OTP

Email-OTP delivers a numeric one-time code by email instead of a link. **It is not a strategy entry** — it activates when you define the `emailOtp` email template:

```yaml
auth:
  strategies:
    - type: emailAndPassword
  emailTemplates:
    emailOtp:
      subject: Your sign-in code
      text: 'Your verification code is $code. It expires shortly.'
```

The presence of `emailTemplates.emailOtp` mounts the email-OTP plugin. The `$code` variable is substituted with the generated one-time code.

## Social / OAuth Providers

Federated login through external identity providers. Credentials are **never** in the schema — they load from environment variables.

```yaml
auth:
  strategies:
    - type: oauth
      providers: [google, github, microsoft, slack, gitlab]
```

| Property    | Description                                                                |
| ----------- | -------------------------------------------------------------------------- |
| `providers` | Non-empty array of provider identifiers. Credentials loaded from env vars. |

Supported providers:

| Provider    | Use case                       |
| ----------- | ------------------------------ |
| `google`    | Google Workspace integration.  |
| `github`    | Developer authentication.      |
| `microsoft` | Enterprise / Azure AD.         |
| `slack`     | Workspace communication.       |
| `gitlab`    | Developer / CI-CD integration. |

Each enabled provider needs a credential pair in the environment:

```bash
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
```

The general form is `{PROVIDER}_CLIENT_ID` and `{PROVIDER}_CLIENT_SECRET`. Callback URLs are derived from `BASE_URL`. See [Environment Variables](/en/env-vars).

## Registration Control

`auth.allowSignUp` decides whether the public can create their own accounts.

```yaml
auth:
  allowSignUp: false
  strategies:
    - type: emailAndPassword
```

| Value            | Behavior                                                                                                       |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `true` (default) | Anyone can self-register via the enabled strategies.                                                           |
| `false`          | Self-registration is disabled. Only admins create users via `POST /api/auth/admin/create-user` or invitations. |

When self-registration is off, admins onboard users with single-use invitation tokens:

```yaml
auth:
  allowSignUp: false
  strategies:
    - type: emailAndPassword
  invitationTokenExpiry: 7d
```

| Property                | Description                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `invitationTokenExpiry` | Lifetime of tokens from `POST /api/auth/admin/invite-user`. Duration string (`72h`, `7d`) or milliseconds. Defaults to `72h`. |

:::callout
Shorter expiries suit high-security customer portals; the `72h` default suits B2B onboarding where invitees may not check email immediately. Invitation tokens are single-use and consumed on first successful accept.
:::

## Email Templates

`auth.emailTemplates` customizes the subject and body of authentication emails. Every template is optional — Better Auth supplies sensible defaults. Defining the `emailOtp` template additionally **enables** the email-OTP flow.

```yaml
auth:
  strategies:
    - type: emailAndPassword
    - type: magicLink
  emailTemplates:
    verification:
      subject: Verify your email for MyApp
      text: 'Hi $name, confirm your email: $url'
    resetPassword:
      subject: Reset your password
      text: 'Reset your password: $url'
      html: '<p>Click <a href="$url">here</a> to reset your password.</p>'
    magicLink:
      subject: Your sign-in link
      text: 'Sign in to MyApp: $url'
```

| Template               | When it is sent                                       |
| ---------------------- | ----------------------------------------------------- |
| `verification`         | Email verification after sign-up.                     |
| `resetPassword`        | Password-reset request.                               |
| `magicLink`            | Magic-link sign-in.                                   |
| `emailOtp`             | Email one-time code (its presence enables email-OTP). |
| `twoFactorBackupCodes` | Two-factor backup codes delivery.                     |
| `welcome`              | Welcome email after verification.                     |
| `accountDeletion`      | Account-deletion confirmation.                        |
| `invitation`           | Admin-issued invitation (passwordless onboarding).    |

Each template accepts a required `subject` and optional `text` and/or `html` bodies. Bodies support `$variable` substitution:

| Variable            | Meaning                                                             |
| ------------------- | ------------------------------------------------------------------- |
| `$url`              | Action link (verify, reset, magic link, invitation accept).         |
| `$name`             | Recipient's name.                                                   |
| `$email`            | Recipient's email address.                                          |
| `$code`             | One-time code (email-OTP).                                          |
| `$organizationName` | Organization name (invitations).                                    |
| `$inviterName`      | Name of the admin who sent the invitation (admin invitations only). |

:::callout
Magic link, email-OTP, password reset, and verification emails all require SMTP. When SMTP is unset the app boots with email disabled and logs a warning — those strategies will not deliver. See [Environment Variables](/en/env-vars).
:::

## Related Pages

- [Authentication Overview](/en/auth-overview) — the `auth` block and how strategies fit in.
- [Sessions](/en/auth-sessions) — what happens after a successful sign-in.
- [Two-Factor](/en/auth-two-factor) — adding TOTP on top of email/password.
- [Environment Variables](/en/env-vars) — `AUTH_SECRET`, `BASE_URL`, and OAuth credentials.

# Roles & RBAC

Sovrium uses **role-based access control (RBAC)** with an optional layer of [groups](/en/auth-groups). Every authenticated user has exactly one role; roles are arranged in a numeric **hierarchy**; and [table permissions](/en/table-permissions) reference roles to gate create/read/update/delete and per-field access.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
  roles:
    - name: editor
      description: Can edit content
      level: 30
```

## Built-in Roles

Three roles ship with every auth-enabled app. They are always available and **cannot be redefined** by custom roles.

| Role     | Level | Access                                                            |
| -------- | ----- | ----------------------------------------------------------------- |
| `admin`  | 80    | Full access — manage users, roles, and settings; all permissions. |
| `member` | 40    | Standard access to application resources.                         |
| `viewer` | 10    | Read-only access.                                                 |

## Role Hierarchy & Levels

Each role has a numeric `level`. Higher levels are more privileged. The level establishes an ordering used by permission resolution and by features that compare role seniority (for example, an admin-equivalent role is one at the highest configured level).

Built-in levels are fixed at `admin=80`, `member=40`, `viewer=10`. Custom roles slot anywhere along this scale via their own `level`:

```yaml
auth:
  roles:
    - name: editor
      level: 30 # between viewer (10) and member (40)
    - name: moderator
      level: 50 # between member (40) and admin (80)
```

:::callout
**Most-permissive-wins.** When a user's permissions come from multiple sources (their role and their groups), the union of granted operations applies. If the role grants `read` and a group grants `update`, the user gets both. See [Groups](/en/auth-groups).
:::

## Custom Role Definitions

`auth.roles` is an array of custom role definitions layered on top of the built-ins. An empty array (or omitting the field) means only the built-in roles exist.

```yaml
auth:
  roles:
    - name: editor
      description: Can edit content
      level: 30
    - name: moderator
      level: 20
    - name: contributor
```

| Property         | Description                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | **Required.** Role identifier. Lowercase, alphanumeric, hyphens; must start with a letter. Must be unique and must not collide with a built-in role name or a group name. |
| `description`    | Human-readable description of the role's purpose.                                                                                                                         |
| `level`          | Hierarchy level (higher = more privileged). Built-in references: `admin=80`, `member=40`, `viewer=10`.                                                                    |
| `defaultLanding` | Per-role post-login landing URL. See [Post-Login Landing](/en/auth-post-login).                                                                                           |
| `pickerLanding`  | Multi-record fallback for a templated `defaultLanding`. See [Post-Login Landing](/en/auth-post-login).                                                                    |

**Naming rules** — role names match `^[a-z][a-z0-9-]*$`:

| Name              | Valid? | Reason                   |
| ----------------- | ------ | ------------------------ |
| `editor`          | ✅     | lowercase letters        |
| `content-manager` | ✅     | hyphen allowed           |
| `Editor`          | ❌     | uppercase not allowed    |
| `123role`         | ❌     | must start with a letter |

Validation rejects:

- Duplicate custom role names.
- Custom names that collide with built-in roles (`admin`, `member`, `viewer`).
- Custom names that collide with a [group](/en/auth-groups) name (roles and groups share a namespace).

## Default Role

`auth.defaultRole` is the role assigned to new users on registration. It defaults to `member` when omitted, and must reference a built-in role **or** a custom role defined in `auth.roles`.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: viewer # new users start read-only
  roles:
    - name: editor
      level: 30
```

| Property      | Description                                                                            |
| ------------- | -------------------------------------------------------------------------------------- |
| `defaultRole` | Role granted to newly registered users. Built-in or custom name. Defaults to `member`. |

:::callout
A `defaultRole` referencing an undefined custom role fails validation at startup. Define the role in `auth.roles` before naming it as the default. Setting `defaultRole: viewer` is a common pattern for apps where new users should be read-only until an admin promotes them.
:::

## Admin Roles

When `auth` is configured, the admin user-management surface is always mounted (there is no separate toggle). The **first user to register becomes an admin** (`firstUserAdmin`). Admins can:

- Create users (`POST /api/auth/admin/create-user`) — including when `allowSignUp: false`.
- Invite users with single-use tokens (`POST /api/auth/admin/invite-user`).
- Assign and change roles.
- Impersonate users for support workflows.
- Ban / unban users.

The highest-level role is treated as admin-equivalent for these checks, so a custom role at `level: 80` (or higher) participates in admin gating alongside the built-in `admin` role.

## How Roles Gate Data

Roles do not grant data access on their own — they are referenced by each table's `permissions` block. A role with no matching permission entry has no access to that table. See [Table Permissions](/en/table-permissions) for the full create/read/update/delete/restore/comment and per-field model, including how `group:`-prefixed entries combine with roles.

## Related Pages

- [Authentication Overview](/en/auth-overview) — default roles in context.
- [Groups](/en/auth-groups) — many-to-many membership layered on roles.
- [Post-Login Landing](/en/auth-post-login) — per-role landing rules.
- [Table Permissions](/en/table-permissions) — where roles actually gate data.

# Groups

**Groups** complement [roles](/en/auth-roles-rbac) by adding a many-to-many layer: a user has exactly one role, but can belong to **any number of groups**. Permissions can reference groups with the `group:` prefix, making them ideal for team-scoped and field-level access.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  groups:
    - name: marketing
    - name: finance
      description: Finance team with access to financial data
    - name: project-alpha
      description: Cross-functional team
      maxMembers: 50
```

Teams are configured through groups — define a group per team (engineering, marketing, …) and reference it in permissions.

## Defining Groups

`auth.groups` is an array of group definitions.

| Property      | Description                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | **Required.** Group identifier. Lowercase, alphanumeric, hyphens; must start with a letter. Must be unique and must not collide with a role name. |
| `description` | Human-readable description of the group's purpose.                                                                                                |
| `maxMembers`  | Maximum number of members (integer ≥ 1). Unlimited when omitted.                                                                                  |

**Naming rules** — group names match `^[a-z][a-z0-9-]*$` (the same convention as role names):

| Name            | Valid? | Reason                   |
| --------------- | ------ | ------------------------ |
| `marketing`     | ✅     | lowercase letters        |
| `dev-team`      | ✅     | hyphen allowed           |
| `project-alpha` | ✅     | hyphen allowed           |
| `Marketing`     | ❌     | uppercase not allowed    |
| `123team`       | ❌     | must start with a letter |

:::callout
**Roles and groups share one namespace.** A group named `admin` is rejected because it collides with the built-in role. Keep group names distinct from every built-in and custom role name. Validation also rejects duplicate group names.
:::

## Membership

A user can be a member of multiple groups simultaneously. Membership is managed at runtime (assigned by admins or by [automations](/en/automations-overview)) — the schema declares which groups _exist_, not who belongs to them. When `maxMembers` is set, attempts to add a member beyond the cap are rejected.

## Group-Based Permissions

Reference a group in a table's `permissions` block by prefixing its name with `group:`. Group entries sit alongside role names in the same permission arrays:

```yaml
tables:
  - id: 1
    name: Campaigns
    fields:
      - { id: 1, name: title, type: single-line-text, required: true }
      - { id: 2, name: budget, type: number }
    permissions:
      read: [member, 'group:marketing']
      update: ['group:marketing']
      # field-level: only finance can read the budget column
      fields:
        budget:
          read: ['group:finance']
```

| Entry form        | Meaning                                         |
| ----------------- | ----------------------------------------------- |
| `member`          | Grant to everyone with the `member` role.       |
| `group:marketing` | Grant to every member of the `marketing` group. |
| `admin`           | Grant to the `admin` role.                      |

Permission resolution is **most-permissive-wins**: a user's effective permissions are the union of those granted by their role and by every group they belong to. If a user's role grants `read` and their `marketing` group grants `update`, they get both.

:::callout
Groups shine for **field-level permissions** — e.g. exposing a `salary` or `budget` column only to a `group:finance` while the rest of the table is broadly readable. See [Table Permissions](/en/table-permissions) for the complete field-level model.
:::

## Related Pages

- [Roles & RBAC](/en/auth-roles-rbac) — the single-role layer groups build on.
- [Table Permissions](/en/table-permissions) — full `group:` permission and field-level model.
- [Automations](/en/automations-overview) — assign users to groups in response to events.

# Sessions

When a user authenticates, Sovrium issues a **server-managed session** (an `httpOnly` cookie backed by a row in the `auth.session` table). Sessions are inspectable, listable, and revocable through the auth API, and — for multi-tenant apps — augmented by an **active-scope session API** that lets a user choose which assignment is currently in context.

## Session Configuration

Core session behavior (lifetime, refresh window) is managed at the **Better Auth server level**, not in the app schema. There is no `auth.session` config block.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  # Session lifetime/refresh are Better Auth server defaults — not schema fields.
```

| Concern                    | Where it lives                                                                 |
| -------------------------- | ------------------------------------------------------------------------------ |
| Session lifetime / refresh | Better Auth server defaults (not exposed in `app.auth`).                       |
| Signing & encryption       | `AUTH_SECRET` environment variable. See [Environment Variables](/en/env-vars). |
| Cookie security            | `secure` cookies in production; derived from `BASE_URL` / `NODE_ENV`.          |

:::callout
Rotating `AUTH_SECRET` invalidates every active session — all users are signed out. Treat it as a credential and rotate deliberately. See [Security Hardening](/en/security-hardening).
:::

## Inspecting & Ending Sessions

The following endpoints are mounted automatically when `auth` is configured.

| Method | Endpoint                          | Purpose                                                       |
| ------ | --------------------------------- | ------------------------------------------------------------- |
| `GET`  | `/api/auth/get-session`           | Returns the current session and user, or a null body if none. |
| `GET`  | `/api/auth/list-sessions`         | Lists all active sessions for the authenticated user.         |
| `POST` | `/api/auth/sign-out`              | Invalidates the current session (idempotent — always `200`).  |
| `POST` | `/api/auth/revoke-session`        | Revokes a specific session by id.                             |
| `POST` | `/api/auth/revoke-other-sessions` | Revokes every session except the current one.                 |

Behavior worth noting:

- `get-session` returns a **null body** (not an error) when unauthenticated or after sign-out, so a client can safely poll it to render auth state.
- `list-sessions` is **session-isolated** — a user only ever sees their own sessions, each with `id`, `userId`, creation, and expiration timestamps.
- `sign-out` is **idempotent**: calling it without a session, or repeatedly, still returns `200`.

## Active-Scope Sessions (Multi-Tenant)

Apps that scope data per tenant use the `user_access` junction: a user can have multiple access rows for the same table (e.g. a fractional CFO assigned to three client companies). The **active-scope session API** lets that user pick which assignment is currently active, persisted in a per-table cookie and resolved by `$currentUser.activeAssignment`.

First, declare the scope tables:

```yaml
auth:
  strategies:
    - type: emailAndPassword
  roles:
    - name: customer-admin
  scopeTables: [clients]
  landingPath: /portal
  # No extra config — active-scope endpoints auto-mount for every scopeTables entry.
```

| Property      | Description                                                                                                                                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scopeTables` | Array of table slugs (from `app.tables[].name`) that `user_access` rows may reference. Non-empty; entries must be valid slug identifiers; no duplicates. Validated against `app.tables[].name` at startup. |

Then the engine auto-mounts these endpoints for each entry in `scopeTables`:

| Method   | Path                                   | Behavior                                                                                                                                   |
| -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST`   | `/api/session/active-scope/:tableSlug` | Body `{ recordId }`. Sets the active-scope cookie when `recordId` is in the user's `user_access`; returns `403` otherwise (no cookie set). |
| `GET`    | `/api/session/active-scope/:tableSlug` | Returns `{ tableSlug, recordId }` from the cookie, or `null` when unset.                                                                   |
| `DELETE` | `/api/session/active-scope/:tableSlug` | Clears the cookie (returns `204`).                                                                                                         |

A `:tableSlug` that is not in `scopeTables` returns `404`.

### Security Model

The active-scope cookie is named `sovrium_active_assignment_<tableSlug>` (one per scope table).

1. **Cookie attributes** — `httpOnly`, `sameSite=lax`, and `secure` in production. Not readable by client JavaScript.
2. **Every write is server-validated** — `POST` verifies the `recordId` is in the user's `user_access` rows for that slug. Out-of-scope writes return `403` with no state change.
3. **Every read is server-validated** — when resolving `$currentUser.activeAssignment`, the engine re-checks the cookie against `user_access`. Tampered, stale, or now-revoked values are discarded and the resolver falls back to the user's first accessible record.

:::callout
**Tamper-proof by construction.** A user cannot edit the cookie to reach a record outside their assignments — the value is re-validated against `user_access` on every request, both when set and when read. This makes context-switching safe without re-authenticating.
:::

`$currentUser.activeAssignment` is consumable in `dataSource.filter` predicates and row-level permission `when` clauses, so every assignment-bound view refreshes automatically when the active scope changes. The related `$currentUser.assignments.<table>` token (the full set of a user's assignments) is covered in [Post-Login Landing](/en/auth-post-login).

## Related Pages

- [Authentication Overview](/en/auth-overview) — enabling auth and the `auth` block.
- [Post-Login Landing](/en/auth-post-login) — `$currentUser.assignments` interpolation and per-role landing.
- [Table Permissions](/en/table-permissions) — row-level `when` predicates that consume `$currentUser`.
- [Security Hardening](/en/security-hardening) — `AUTH_SECRET` rotation and cookie hardening.

# Two-Factor Authentication

`auth.twoFactor` enables **TOTP-based two-factor authentication** (time-based one-time passwords). Users add a second factor with an authenticator app (Google Authenticator, 1Password, Authy, …) and enter a rotating code at sign-in.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
```

:::callout
**2FA requires the `emailAndPassword` strategy.** TOTP layers a second factor on top of password sign-in. Configuring `twoFactor` without an `emailAndPassword` strategy in `auth.strategies` fails validation at startup.
:::

## Enabling 2FA

The simplest form is a boolean — enable with defaults:

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor: true
```

For control over the issuer name, backup codes, and code format, use the object form:

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
    digits: 6
    period: 30
```

## Configuration

`auth.twoFactor` accepts either a boolean or a configuration object.

| Property      | Description                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| _(boolean)_   | `true` enables 2FA with defaults; `false` (or omitting the field) disables it.           |
| `issuer`      | Name shown in the user's authenticator app (e.g. `MyApp`). Identifies the account entry. |
| `backupCodes` | Boolean. When `true`, generate single-use backup codes for account recovery.             |
| `digits`      | Number of digits in the TOTP code, 4–8. Defaults to `6`.                                 |
| `period`      | Code rotation interval in seconds (positive). Defaults to `30`.                          |

:::callout
Keep `digits: 6` and `period: 30` unless you have a specific compatibility need — they match the defaults nearly every authenticator app expects. Non-standard values can confuse some apps.
:::

## Backup Codes

When `backupCodes: true`, users receive a set of single-use recovery codes during 2FA enrollment — essential when they lose access to their authenticator device. Delivery is customizable via the `twoFactorBackupCodes` [email template](/en/auth-strategies#email-templates):

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
  emailTemplates:
    twoFactorBackupCodes:
      subject: Your MyApp recovery codes
      text: 'Keep these recovery codes safe: $code'
```

## Enrollment Flow

1. The user signs in with email and password as usual.
2. They enroll in 2FA — the app shows a TOTP secret (typically as a QR code) labeled with `issuer`.
3. They scan it into an authenticator app, which begins generating codes every `period` seconds.
4. On subsequent sign-ins, after the password step they enter the current `digits`-length code.
5. If enabled, backup codes provide a recovery path when the device is unavailable.

## Related Pages

- [Strategies](/en/auth-strategies) — the `emailAndPassword` strategy 2FA depends on, plus the `twoFactorBackupCodes` email template.
- [Sessions](/en/auth-sessions) — sessions issued after the second factor succeeds.
- [Authentication Overview](/en/auth-overview) — the `auth` block in context.

# OAuth Server

Beyond consuming social logins (see [Strategies](/en/auth-strategies)), Sovrium can act **as an OAuth 2.1 / OpenID Connect 1.0 authorization server** — issuing access and refresh tokens for downstream apps and AI/MCP clients that authenticate against your Sovrium identity store.

This is how Sovrium becomes the identity provider for a fleet of apps: one Sovrium instance holds the users, and other services delegate sign-in to it.

## Enabling

The OAuth-server endpoints are **auto-mounted whenever `auth` is configured** — there is nothing to turn on in the schema.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  # OAuth-server endpoints mount automatically under /api/auth/oauth2/* once auth is configured.
```

:::callout
**No schema knobs (yet).** Token lifetimes and other tunables are operator concerns governed by defaults and environment variables, not `app.auth` fields. A future `app.auth.oauthServer.{...}` block may expose select knobs once route wiring stabilizes and we know which settings schema authors actually need. Without `auth` configured, all `/api/auth/*` routes return `404` — there is no identity to authorize.
:::

## Endpoints

The authorization server exposes the standard OAuth 2.1 / OIDC surface under `/api/auth/oauth2/*`, plus discovery documents at well-known paths.

| Method | Path                                      | Purpose                                                  |
| ------ | ----------------------------------------- | -------------------------------------------------------- |
| `GET`  | `/.well-known/oauth-authorization-server` | RFC 8414 authorization-server metadata.                  |
| `GET`  | `/.well-known/openid-configuration`       | OIDC Discovery 1.0 metadata.                             |
| `GET`  | `/.well-known/jwks.json`                  | JSON Web Key Set — public keys for token verification.   |
| `POST` | `/api/auth/oauth2/register`               | RFC 7591 Dynamic Client Registration.                    |
| `GET`  | `/api/auth/oauth2/authorize`              | Authorization endpoint (PKCE-S256 required).             |
| `POST` | `/api/auth/oauth2/consent`                | User-consent acknowledgement.                            |
| `POST` | `/api/auth/oauth2/continue`               | Resume after account-select / post-login.                |
| `POST` | `/api/auth/oauth2/token`                  | Token endpoint (`authorization_code` + `refresh_token`). |
| `GET`  | `/api/auth/oauth2/userinfo`               | OIDC UserInfo claims for the access token.               |
| `POST` | `/api/auth/oauth2/introspect`             | RFC 7662 token introspection.                            |
| `POST` | `/api/auth/oauth2/revoke`                 | RFC 7009 token revocation.                               |

## Defaults

Sovrium tunes the authorization server for self-hosted and AI-client use out of the box:

| Setting                     | Default             | Why                                                                                   |
| --------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
| Dynamic client registration | Enabled             | MCP clients (Claude Desktop, ChatGPT Dev Mode) self-register without operator action. |
| Access token lifetime       | 1 hour              | Industry standard.                                                                    |
| Refresh token lifetime      | 30 days             | Industry standard.                                                                    |
| Login page                  | `/login`            | Sovrium engine page.                                                                  |
| Consent page                | `/oauth/consent`    | Sovrium engine page.                                                                  |
| PKCE                        | Required (S256)     | OAuth 2.1 mandates PKCE for the authorization code flow.                              |
| Token signing               | Rotating EdDSA keys | Signed `id_token`s and access tokens published via the JWKS endpoint.                 |

## MCP & AI Clients

Dynamic client registration is enabled specifically so AI assistants and MCP clients can self-register and obtain tokens, then call your app's MCP-exposed tables (subject to the same [RBAC](/en/auth-roles-rbac) and [table permissions](/en/table-permissions) as any other caller). This lets an AI client act on behalf of a real user, with the same access that user would have in the UI.

## Related Pages

- [Strategies](/en/auth-strategies) — Sovrium as an OAuth _client_ (social login), the inverse direction.
- [Roles & RBAC](/en/auth-roles-rbac) — the access model tokens are bound to.
- [Table Permissions](/en/table-permissions) — what an authorized token can reach.
- [Environment Variables](/en/env-vars) — `AUTH_SECRET` (token signing) and `BASE_URL` (issuer / discovery URLs).

# Post-Login Landing

After sign-in, different users should land on different pages — an admin on the admin home, a customer on their record (or a picker when they have several). Sovrium expresses this as **auth configuration**, not per-page redirect logic: each role declares a `defaultLanding`, the `auth` block declares a `landingPath` mount point, and `noAccessPath` handles the unmatched case.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  scopeTables: [clients]
  defaultRole: customer-admin
  landingPath: /portal
  noAccessPath: /403
  roles:
    - name: engineer
      defaultLanding: /admin
    - name: customer-admin
      defaultLanding: /portal/clients/$currentUser.assignments.clients[0]
      pickerLanding: /portal/select/clients
```

## Configuration Fields

Two fields on `auth`, two on each role:

| Field            | Level     | Description                                                                                                                                                                                            |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `landingPath`    | `auth`    | Engine-resolver mount path. Sessions navigating here are redirected to the matching role's `defaultLanding`. Must start with `/`. Required whenever any role sets `defaultLanding` or `pickerLanding`. |
| `noAccessPath`   | `auth`    | Fallback path when no role's `defaultLanding` matches the session. Must start with `/`. Defaults to `/403`.                                                                                            |
| `defaultLanding` | `roles[]` | Per-role landing URL. Must start with `/`. May contain at most one `$currentUser.assignments.<table>[0]` token.                                                                                        |
| `pickerLanding`  | `roles[]` | Multi-record fallback for a _templated_ `defaultLanding`. Must start with `/`. Must **not** contain any assignment token.                                                                              |

:::callout
`landingPath` is **user-controlled** — pick `/portal`, `/dashboard`, `/home`, or anything else. There is no engine convention. The same is true of `pickerLanding`: `/portal/select/clients`, `/companies-picker`, whatever you like.
:::

## Resolution Logic

When an authenticated session navigates to `auth.landingPath`, the engine walks `auth.roles[]` in **declaration order** and applies the first role the user holds. For that role's `defaultLanding`:

| `defaultLanding` shape           | Assignment count for the templated `<table>` | Engine action                                    |
| -------------------------------- | -------------------------------------------- | ------------------------------------------------ |
| Bare URL (no token)              | n/a                                          | Redirect to `defaultLanding` unconditionally.    |
| Templated (one token)            | Exactly one assignment                       | Substitute the assignment ID, redirect there.    |
| Templated (one token)            | More than one assignment                     | Redirect to the role's `pickerLanding`.          |
| No role matched / no assignments | n/a                                          | Redirect to `noAccessPath` (defaults to `/403`). |

## `$currentUser.assignments` Interpolation

The `$currentUser.assignments.<table>` token resolves to the set of record IDs from the user's `user_access` rows for `<table>` (a [scope table](/en/auth-sessions)). It appears in two distinct ways:

**In a `defaultLanding` URL** — the single-record form `$currentUser.assignments.<table>[0]` substitutes the _first_ assignment ID, producing a deep link straight to that record:

```yaml
roles:
  - name: customer-admin
    defaultLanding: /portal/clients/$currentUser.assignments.clients[0]
    pickerLanding: /portal/select/clients
```

A role may contain **at most one** such token (the resolver cannot infer which scope to count with two). A `pickerLanding` must contain **none** — by definition the multi-record case has no single ID to substitute.

**In a `dataSource.filter`** — the un-indexed form `$currentUser.assignments.<table>` resolves to the full ID list, so the picker page lists exactly the records the user can reach:

```yaml
pages:
  - name: client-picker
    path: /portal/select/clients
    access: authenticated
    components:
      - type: list
        props: { id: clients }
        dataSource:
          table: clients
          filter:
            - field: id
              operator: in
              value: $currentUser.assignments.clients
        children:
          - type: text
            content: $record.name
```

## The `landingPath` Page Is the Access Guard

`landingPath` must be backed by a **co-located page** declared at the same `path`. That page is the unauthenticated-access guard: its `access` block bounces anonymous visitors to `/login` before the landing resolver runs. For authenticated visitors the resolver redirects away before this (typically empty) page renders.

```yaml
auth:
  landingPath: /portal
  # ...

pages:
  - name: portal-landing
    path: /portal
    access:
      require: authenticated
      redirectTo: /login
    components: [] # never rendered for authed users — resolver redirects first
```

:::callout
Forgetting the co-located guard page is the most common mistake: `landingPath: /portal` with no `/portal` page leaves anonymous visitors unguarded. Always pair the mount path with a page that requires authentication.
:::

## Full Example

```yaml
auth:
  strategies:
    - type: emailAndPassword
  scopeTables: [clients]
  defaultRole: customer-admin
  landingPath: /portal
  noAccessPath: /403
  roles:
    - name: engineer
      defaultLanding: /admin
    - name: customer-admin
      defaultLanding: /portal/clients/$currentUser.assignments.clients[0]
      pickerLanding: /portal/select/clients

pages:
  - name: portal-landing
    path: /portal
    access: { require: authenticated, redirectTo: /login }
    components: []
  - name: client-detail
    path: /portal/clients/:id
    access: authenticated
    components: []
  - name: client-picker
    path: /portal/select/clients
    access: authenticated
    components: []
  - name: admin-home
    path: /admin
    access: [engineer]
    components: []
  - name: forbidden
    path: /403
    access: authenticated
    components: []
```

In this app: an `engineer` lands on `/admin`; a `customer-admin` with one client lands on that client's detail page; with several, on the picker; and anyone the resolver cannot place hits `/403`.

## Related Pages

- [Roles & RBAC](/en/auth-roles-rbac) — where `defaultLanding` / `pickerLanding` are defined on roles.
- [Sessions](/en/auth-sessions) — `scopeTables`, `user_access`, and `$currentUser.activeAssignment`.
- [Pages](/en/pages-overview) — page `path`, `access`, and `dataSource.filter`.

# Automations Overview

Automations are Sovrium's workflow engine. Each automation pairs **one trigger** (the event that starts it) with an **ordered list of actions** (the steps it runs). When the trigger fires, the actions execute sequentially — passing data forward through template variables — until the workflow completes, stops, or fails.

Automations are declared under the top-level `app.automations[]` array. Triggers react to record changes, schedules, inbound webhooks, auth events, form submissions, manual buttons, sub-workflow calls, other automations' failures, and comments. Actions span more than 20 families: HTTP, record CRUD, email, AI, file operations, flow control, approvals, and more.

```yaml
automations:
  - name: new-order-alert
    label: Notify the team about new orders
    trigger:
      type: record
      table: orders
      events: [create]
    actions:
      - name: notifyTeam
        type: email
        operator: send
        props:
          to: '{{trigger.data.owner_email}}'
          subject: 'New order {{trigger.data.id}}'
          body: 'Amount: ${{trigger.data.amount}}'
    timeout: 60000
```

## Anatomy

An automation has exactly one `trigger` and at least one entry in `actions`. Everything else — timeout, retry, concurrency, tags, permissions, AI exposure — is optional.

| Property      | Description                                                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`        | Unique kebab-case identifier (`^[a-z][a-z0-9-]*$`, max 100 chars). Used in webhook URLs and as the `automation/call` target.                                       |
| `label`       | Human-readable label shown in the admin interface.                                                                                                                 |
| `description` | Free-text description of what the automation does.                                                                                                                 |
| `enabled`     | Boolean. When `false`, the automation is registered but never fires. Defaults to `true`.                                                                           |
| `trigger`     | The single event that starts this workflow. See [Triggers](/en/automation-triggers).                                                                               |
| `actions`     | Ordered array of action steps (minimum 1). Steps run sequentially unless a `path`/`loop` action branches. See [Actions Overview](/en/automation-actions-overview). |
| `retry`       | Automation-level retry policy applied to the whole run. See [Retry & Failure](/en/automation-retry-failure).                                                       |
| `timeout`     | Total run timeout in milliseconds (1000–900000, default 300000).                                                                                                   |
| `concurrency` | `{ limit }` — max simultaneous runs of this automation (1–50). See concurrency note below.                                                                         |
| `tags`        | Array of strings for organizing and filtering automations.                                                                                                         |
| `permissions` | `{ trigger }` — who can manually invoke this automation (`all`, `authenticated`, or a role array).                                                                 |
| `aiAccess`    | Declares a **manual-trigger** automation as invokable via Sovrium's MCP server. Setting it on a non-manual trigger is a decode error.                              |

:::callout
**Data flows between steps via template variables.** Reference the trigger payload with `{{trigger.data.fieldName}}`, a prior step's output with `{{stepName.result}}`, an environment secret with `$env.VAR_NAME` (never logged), and a stored credential with `$connection.NAME`. See [Template Helpers](#template-variables) below.
:::

## Template Variables

Every string prop in an action can interpolate runtime values. The resolution sources are:

| Source           | Syntax                     | Notes                                                                                                                               |
| ---------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Trigger payload  | `{{trigger.data.field}}`   | The data the trigger carried (record row, webhook body, form values, …).                                                            |
| Previous step    | `{{stepName.result}}`      | The output of any earlier action, referenced by its `name`.                                                                         |
| Environment var  | `$env.VAR_NAME`            | Resolved from `app.env`. Redacted in logs. See [Env Vars](/en/automation-env-vars).                                                 |
| Connection       | `$connection.NAME`         | Resolved credentials for an external service. See [Connections](/en/automation-connections).                                        |
| Helper functions | `{{helperName arg "lit"}}` | 100+ formatting helpers (text, number, date, logic, collection, encoding). Nest with parentheses: `{{uppercase (trim step.text)}}`. |

## Concurrency

Each automation has an independent FIFO semaphore. When `concurrency.limit` is set, incoming triggers beyond the limit are persisted as `queued` and promoted to `running` as in-flight slots free. Without the block, the global `AUTOMATION_CONCURRENCY_DEFAULT` env (default 5) applies. Queueing is in-memory and single-process — designed for Sovrium's single-tenant deployment model.

## Configuration Surface

Automations sit alongside three sibling top-level blocks that they routinely reference:

| Block             | Purpose                                                    | Page                                                |
| ----------------- | ---------------------------------------------------------- | --------------------------------------------------- |
| `app.automations` | The workflows themselves.                                  | this page                                           |
| `app.actions`     | Reusable action templates referenced via the `ref` action. | [Actions Overview](/en/automation-actions-overview) |
| `app.connections` | Stored credentials for authenticated HTTP/AI calls.        | [Connections](/en/automation-connections)           |
| `app.env`         | Declared environment variables / secrets.                  | [Env Vars](/en/automation-env-vars)                 |

## Related Pages

- [Triggers](/en/automation-triggers) — all 9 trigger types.
- [Actions Overview](/en/automation-actions-overview) — the action model and the ~22 families.
- [Runs](/en/automation-runs) — monitoring execution history and statuses.
- [Retry & Failure](/en/automation-retry-failure) — retry policies, timeouts, idempotency.
- [Connections](/en/automation-connections) — OAuth2, API key, basic, bearer credentials.
- [Environment Variables](/en/automation-env-vars) — secrets for automations.

# Automation Triggers

A trigger is the single event that starts an automation. Sovrium ships **9 trigger types**. Every automation declares exactly one `trigger` object whose `type` selects the variant; the remaining properties configure it.

```yaml
automations:
  - name: order-webhook
    trigger:
      type: webhook
      method: POST
    actions:
      - { name: ack, type: webhook, operator: response, props: { status: 202 } }
```

## Trigger Catalog

| `type`               | Fires when…                                                           | Key context exposed                       |
| -------------------- | --------------------------------------------------------------------- | ----------------------------------------- |
| `webhook`            | An inbound HTTP request hits the automation's endpoint.               | `{{trigger.body}}`, headers, query        |
| `cron`               | A cron schedule elapses.                                              | scheduled time                            |
| `record`             | A record is created, updated, or deleted in a watched table.          | `{{trigger.data.*}}` (the row)            |
| `auth`               | An authentication event occurs (sign-up, sign-in, …).                 | the auth event + user                     |
| `form`               | A top-level form is submitted.                                        | `{{trigger.data.*}}` (form values)        |
| `manual`             | An admin clicks a button or calls the trigger API.                    | `{{trigger.inputData.*}}`                 |
| `automation-call`    | Another automation invokes this one via the `automation/call` action. | `{{trigger.inputData.*}}`                 |
| `automation-failure` | A watched automation fails.                                           | the failed run + error                    |
| `comment`            | A comment is created on a record.                                     | `$trigger.comment.*`, `$trigger.record.*` |

## Webhook Trigger

Exposes an HTTP endpoint that, when hit, starts the automation. Accepts one or more methods and supports inbound authentication, custom responses, request/query validation, rate limiting, and deduplication.

| Property              | Description                                                                                               |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| `method`              | HTTP method(s) to accept — `GET`/`POST`/`PUT`/`PATCH`/`DELETE`, or an array of them. **Required.**        |
| `secret`              | Secret for HMAC signature verification (e.g. `$env.WEBHOOK_SECRET`).                                      |
| `respondImmediately`  | When `true` (default), respond `202` immediately; when `false`, wait for the run to complete.             |
| `auth`                | Inbound auth config — `type` is `bearer`, `apiKey`, `hmac`, or `basic` (see table below).                 |
| `response`            | Custom response: `statusCode`/`status`, `body` (string template or JSON), `headers`.                      |
| `requestSchema`       | JSON Schema validating the request body.                                                                  |
| `querySchema`         | JSON Schema validating query parameters.                                                                  |
| `rateLimit`           | `{ maxRequests, windowSeconds }` rate-limit config for the endpoint.                                      |
| `deduplicationKey`    | Template computing a dedup key (e.g. `"{{body.orderId}}"`) — repeated keys within the window are dropped. |
| `deduplicationWindow` | Dedup window in seconds (default 300).                                                                    |

**Inbound `auth.type` options:** `bearer` (with `token`, `prefix`), `apiKey` (with `key`, `header`), `hmac` (with `secret`, `algorithm`), `basic` (with `username`, `password`). All credential values support `$env.VAR`.

```yaml
trigger:
  type: webhook
  method: [POST]
  auth: { type: hmac, secret: $env.STRIPE_SIGNING_SECRET, algorithm: sha256 }
  deduplicationKey: '{{body.id}}'
  deduplicationWindow: 600
```

## Cron Trigger

Runs the automation on a schedule.

| Property     | Description                                                                                                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expression` | Cron expression — standard 5-field or 6-field with seconds (e.g. `0 9 * * 1-5`). No `@daily`/`@hourly` aliases — use the numeric equivalent. **Validated at config decode.** |
| `timezone`   | IANA timezone (e.g. `America/New_York`). Defaults to `UTC`. Validated against the IANA database.                                                                             |

```yaml
trigger:
  type: cron
  expression: '0 9 * * 1-5'
  timezone: Europe/Paris
```

## Record Trigger

Fires when records change in a table.

| Property      | Description                                                               |
| ------------- | ------------------------------------------------------------------------- |
| `table`       | Name of the table to watch. **Required.**                                 |
| `events`      | Array of `create` / `update` / `delete` (minimum 1). **Required.**        |
| `watchFields` | On `update`, only fire when one of these fields changes.                  |
| `condition`   | A condition group — only fire when the changed row matches the predicate. |

```yaml
trigger:
  type: record
  table: orders
  events: [create, update]
  watchFields: [status]
  condition:
    conditions: [{ field: '{{trigger.data.status}}', operator: equals, value: paid }]
```

## Auth Trigger

Fires on authentication lifecycle events.

| Property | Description                                                                                         |
| -------- | --------------------------------------------------------------------------------------------------- |
| `events` | Array of `signUp`, `signIn`, `signOut`, `passwordReset`, `emailVerified` (minimum 1). **Required.** |

```yaml
trigger:
  type: auth
  events: [signUp]
```

## Form Trigger

Fires when a top-level form (`forms[].name`) is submitted.

| Property | Description                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `form`   | References `forms[].name`. **Required.** _(Hard break: this used to be a page path.)_ See [Forms](/en/forms-overview). |

```yaml
trigger:
  type: form
  form: contact-request
```

## Manual Trigger

Admin-initiated execution via a button or API call.

| Property       | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `label`        | Button label in the admin interface (e.g. `Export Report`).            |
| `inputSchema`  | JSON Schema describing required input fields supplied at trigger time. |
| `requiredRole` | Auth role required to trigger (default `admin`).                       |

Manual triggers are the **only** triggers eligible for `aiAccess` (MCP invocation), since they don't fire on their own.

```yaml
trigger:
  type: manual
  label: Sync inventory
  requiredRole: admin
  inputSchema: { warehouse: { type: string } }
```

## Automation-Call Trigger

Fires when another automation invokes this one via the `automation/call` action — enabling sub-workflow composition.

| Property      | Description                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------ |
| `inputSchema` | Expected input contract (JSON Schema-like). If omitted, accepts any `inputData` from the caller. |

```yaml
trigger:
  type: automation-call
  inputSchema: { customerId: { type: string } }
```

See [Flow Control](/en/automation-flow-control) for the `automation/call` and `automation/return` actions.

## Automation-Failure Trigger

Fires when a watched automation fails — composable failure handling without per-automation notification config.

| Property      | Description                                                                            |
| ------------- | -------------------------------------------------------------------------------------- |
| `automations` | Array of automation names (kebab-case) to watch. If omitted, fires on **any** failure. |

```yaml
trigger:
  type: automation-failure
  automations: [nightly-sync, billing-run]
```

## Comment Trigger

Fires when a comment is created on a record in a comments-enabled table.

| Property                 | Description                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `table`                  | Name of the table with comments enabled. **Required.**                                             |
| `when`                   | `approved` (moderated-approved only), `created` (any new comment), or `any`. Default `created`.    |
| `filter`                 | `{ topLevelOnly, repliesOnly, mentionsOnly }` (top-level and replies-only are mutually exclusive). |
| `respectReadPermissions` | When true, only fire if the triggering context can read the record.                                |

Comment triggers expose `$trigger.comment.*`, `$trigger.record.*`, `$trigger.threadParticipants`, and `$trigger.mentions`.

```yaml
trigger:
  type: comment
  table: tickets
  when: created
  filter: { mentionsOnly: true }
```

## Related Pages

- [Automations Overview](/en/automations-overview) — anatomy and template variables.
- [Actions Overview](/en/automation-actions-overview) — what runs after a trigger fires.
- [Webhooks (tables)](/en/table-webhooks) — _outgoing_ table webhooks (distinct from inbound webhook triggers).
- [Flow Control](/en/automation-flow-control) — `automation/call` and `automation/return`.

# Automation Actions Overview

Actions are the individual steps an automation runs. Every action shares the same shape: a **`type`** and an **`operator`** that together select the operation, plus a **`props`** object carrying its inputs. Steps run sequentially (top to bottom) unless a `path` or `loop` action branches execution.

```yaml
actions:
  - name: fetchUser # step name — referenced as {{fetchUser.result}}
    type: http # action family
    operator: get # operation within the family
    props: # operation-specific inputs
      url: 'https://api.example.com/users/{{trigger.data.userId}}'
      connection: example-api
```

## The Action Model

| Element    | Description                                                                                          |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| `type`     | The action **family** (e.g. `http`, `record`, `email`). Selects the broad capability.                |
| `operator` | The **operation** within the family (e.g. `get`, `create`, `send`). Determines the shape of `props`. |
| `props`    | Operation-specific inputs. String values support [template variables](/en/automations-overview).     |

## Common Base Properties

Every action — regardless of `type`/`operator` — accepts these base fields:

| Property          | Description                                                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | Step name for referencing outputs (e.g. `fetchUser`). Must match `^[a-zA-Z][a-zA-Z0-9_]*$`. **Required.**                                 |
| `label`           | Human-readable label for the step.                                                                                                        |
| `retry`           | Per-action retry policy — `{ maxAttempts, delayMs?, strategy? }`. See [Retry & Failure](/en/automation-retry-failure).                    |
| `continueOnError` | Boolean. When `true`, the workflow continues even if this action fails. Defaults to `false`.                                              |
| `timeout`         | Per-action timeout in milliseconds (1000–900000). Terminates the action uniformly when exceeded — distinct from per-type `props.timeout`. |

:::callout
**Two timeouts, two scopes.** The top-level `timeout` field fences the whole action and is enforced for **every** action type. A `props.timeout` (e.g. on `http`, `code`, `automation/call`) fences the handler's internal operation. The smaller of the two wins.
:::

## Conditional Execution

Branching and conditional skipping are handled by dedicated control-flow actions rather than a per-action `condition` field:

- **`filter/continue`** — evaluate a condition group; on false, `stop` the run or `skip` to the next action.
- **`path/branch`** — route into named branches based on per-branch conditions.

See [Flow Control](/en/automation-flow-control) and [Data & State Actions](/en/automation-data-actions).

## The ~22 Action Families

Each family groups one or more operators. The pages below document every operator.

| Family       | Operators                                                                                                                                   | Page                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `data`       | set, aggregate, sort, limit, deduplicate, merge, split, compare, lookup                                                                     | [Data & State](/en/automation-data-actions)           |
| `state`      | get, set, increment, delete, list                                                                                                           | [Data & State](/en/automation-data-actions)           |
| `filter`     | continue                                                                                                                                    | [Data & State](/en/automation-data-actions)           |
| `crypto`     | hash, hmac                                                                                                                                  | [Data & State](/en/automation-data-actions)           |
| `digest`     | collect, release                                                                                                                            | [Data & State](/en/automation-data-actions)           |
| `http`       | request, get, post, put, patch, delete                                                                                                      | [HTTP & Webhooks](/en/automation-http-actions)        |
| `webhook`    | send, response                                                                                                                              | [HTTP & Webhooks](/en/automation-http-actions)        |
| `record`     | create, read, update, delete, upsert, batchCreate, batchUpdate, batchDelete, batchUpsert                                                    | [Record & File](/en/automation-record-actions)        |
| `file`       | upload, download, delete, copy, move, list, getMetadata, signUrl, generatePdf, generateCsv, parseCsv, extractText, transformImage, compress | [Record & File](/en/automation-record-actions)        |
| `path`       | branch                                                                                                                                      | [Flow Control](/en/automation-flow-control)           |
| `loop`       | each                                                                                                                                        | [Flow Control](/en/automation-flow-control)           |
| `automation` | call, return                                                                                                                                | [Flow Control](/en/automation-flow-control)           |
| `flow`       | stop                                                                                                                                        | [Flow Control](/en/automation-flow-control)           |
| `email`      | send                                                                                                                                        | [Email & Notifications](/en/automation-email-actions) |
| `analytics`  | track                                                                                                                                       | [Email & Notifications](/en/automation-email-actions) |
| `ai`         | generate, classify, extract, agent                                                                                                          | [AI Actions](/en/automation-ai-actions)               |
| `approval`   | request                                                                                                                                     | [Approval & Delay](/en/automation-approval-delay)     |
| `delay`      | wait, queue, webhook                                                                                                                        | [Approval & Delay](/en/automation-approval-delay)     |
| `auth`       | createUser, assignRole, banUser, unbanUser                                                                                                  | [Auth Actions](/en/automation-auth-actions)           |
| `code`       | runTypescript                                                                                                                               | [Code Actions](/en/automation-code-actions)           |
| `cloud`      | provision-db, spawn-app, route-add, disable-app, destroy-app                                                                                | [Cloud Actions](/en/automation-cloud-actions)         |
| `ref`        | _(no operator)_                                                                                                                             | this page                                             |

## Reusable Action Templates (`ref`)

Define a reusable action under the top-level `app.actions[]` array, then invoke it from any automation with a `ref` action. The `ref` action has no `operator` — it carries a `$ref` (template name) and optional `$vars` (substitution overrides).

| Property | Description                                                                           |
| -------- | ------------------------------------------------------------------------------------- |
| `$ref`   | Name of the action template to invoke (must match a template in `app.actions[]`).     |
| `$vars`  | Variables to substitute in the referenced template (overrides the template defaults). |

```yaml
# Top-level reusable template
actions:
  - name: notify-slack
    type: http
    operator: post
    props:
      url: $env.SLACK_WEBHOOK_URL
      body: { text: '{{message}}' }

# Invoking it inside an automation
automations:
  - name: order-alert
    trigger: { type: record, table: orders, events: [create] }
    actions:
      - name: alert
        type: ref
        $ref: notify-slack
        $vars: { message: 'New order {{trigger.data.id}}' }
```

## Related Pages

- [Automations Overview](/en/automations-overview) — the trigger + actions anatomy.
- [Triggers](/en/automation-triggers) — events that start a workflow.
- [Retry & Failure](/en/automation-retry-failure) — retry, timeout, idempotency.
- [Connections](/en/automation-connections) — credentials for authenticated actions.

# Data & State Actions

These five families manipulate data **in flight** between steps and persist values **across runs**: `data` (transforms), `state` (key-value store), `filter` (conditional gating), `crypto` (hashing), and `digest` (batching events for later release).

## Data — In-Memory Transforms

The `data` family transforms arrays and values that have already flowed through the workflow. Nine operators.

| Operator      | Props                                     | Description                                                            |
| ------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
| `set`         | `value`                                   | Set a value (or compute one from templates) for later steps.           |
| `aggregate`   | `input`, `function`, `field?`, `groupBy?` | Reduce an array — `sum`/`avg`/`min`/`max`/`count`, optionally grouped. |
| `sort`        | `input`, `field`, `direction?`            | Sort an array by `field` (`asc` default / `desc`).                     |
| `limit`       | `input`, `count`                          | Take the first `count` items.                                          |
| `deduplicate` | `input`, `key`                            | Remove duplicate items by `key`.                                       |
| `merge`       | `left`, `right`, `joinKey?`               | Merge two arrays, optionally joining on `joinKey`.                     |
| `split`       | `input`, `size`                           | Chunk an array into sub-arrays of `size`.                              |
| `compare`     | `left`, `right`, `key`                    | Diff two arrays by `key` (added / removed / changed).                  |
| `lookup`      | `input`, `key`, `value`                   | Build a key→value lookup map from an array.                            |

```yaml
- name: revenueByRegion
  type: data
  operator: aggregate
  props:
    input: '{{fetchOrders.result}}'
    function: sum
    field: amount
    groupBy: region
```

## State — Cross-Run Key-Value Store

The `state` family persists values across automation runs (counters, cursors, dedup markers). Optional `namespace` scopes keys; `ttl` expires them. Five operators.

| Operator    | Props                                | Description                                        |
| ----------- | ------------------------------------ | -------------------------------------------------- |
| `get`       | `key`, `namespace?`                  | Read a stored value.                               |
| `set`       | `key`, `value`, `namespace?`, `ttl?` | Store a value, optionally with a time-to-live.     |
| `increment` | `key`, `amount?`, `namespace?`       | Atomically increment a numeric value (default +1). |
| `delete`    | `key`, `namespace?`                  | Remove a stored value.                             |
| `list`      | `prefix?`, `namespace?`, `limit?`    | List keys (optionally filtered by prefix).         |

```yaml
- name: bumpCounter
  type: state
  operator: increment
  props: { key: 'orders:{{trigger.data.region}}', namespace: metrics }
```

## Filter — Conditional Gating

The `filter` family decides whether the workflow proceeds. One operator.

| Operator   | Props                   | Description                                                                                                                         |
| ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `continue` | `condition`, `onFalse?` | Evaluate a [condition group](/en/automation-flow-control); on false, `stop` (halt) or `skip` (skip to next action). Default `stop`. |

```yaml
- name: onlyPaid
  type: filter
  operator: continue
  props:
    condition:
      conditions: [{ field: '{{trigger.data.status}}', operator: equals, value: paid }]
    onFalse: stop
```

## Crypto — Hashing & HMAC

The `crypto` family computes digests and signatures (e.g. webhook signature verification). Two operators.

| Operator | Props                                       | Description                                                         |
| -------- | ------------------------------------------- | ------------------------------------------------------------------- |
| `hash`   | `input`, `algorithm`, `encoding?`           | Hash with `md5` / `sha256` / `sha512`; `hex` (default) or `base64`. |
| `hmac`   | `input`, `secret`, `algorithm`, `encoding?` | HMAC with `sha256` / `sha512`; keyed by `secret`.                   |

```yaml
- name: signPayload
  type: crypto
  operator: hmac
  props:
    input: '{{trigger.body}}'
    secret: $env.SIGNING_SECRET
    algorithm: sha256
    encoding: hex
```

## Digest — Batch & Release

The `digest` family collects items across multiple runs into a named bucket, then releases them as a batch (e.g. roll up notifications into a daily summary). Two operators.

| Operator  | Props                              | Description                                                              |
| --------- | ---------------------------------- | ------------------------------------------------------------------------ |
| `collect` | `bucket`, `item`, `deduplicateBy?` | Add an item to a named bucket, optionally deduplicating.                 |
| `release` | `bucket`, `sort?`, `limit?`        | Drain a bucket — optionally sorted (`{ field, direction? }`) and capped. |

```yaml
# Producer automation (record trigger) collects
- name: queueDigest
  type: digest
  operator: collect
  props: { bucket: daily-summary, item: '{{trigger.data}}', deduplicateBy: id }

# Consumer automation (cron trigger) releases
- name: drain
  type: digest
  operator: release
  props: { bucket: daily-summary, sort: { field: created_at, direction: desc }, limit: 50 }
```

## Related Pages

- [Actions Overview](/en/automation-actions-overview) — the type + operator + props model.
- [Flow Control](/en/automation-flow-control) — condition groups, `path`, `loop`.
- [HTTP & Webhooks](/en/automation-http-actions) — sourcing data from external APIs.
- [Records CRUD](/en/records-crud) — the data API behind record reads.

# HTTP & Webhook Actions

The `http` family makes outbound HTTP calls to external APIs (optionally authenticated via a stored connection). The `webhook` family sends signed outgoing webhooks and writes a custom response back to an inbound webhook trigger.

## HTTP — Outbound Requests

Six operators. The generic `request` operator takes an explicit `method`; the verb operators (`get`/`post`/`put`/`patch`/`delete`) are shorthands and accept a `connection` reference for authenticated calls.

| Operator  | Key props                                                                                | Description                                            |
| --------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `request` | `url`, `method`, `headers?`, `body?`, `contentType?`, `timeout?`, `expectedStatus?`      | Generic request with an explicit method (templatable). |
| `get`     | `url`, `headers?`, `timeout?`, `expectedStatus?`, `connection?`                          | HTTP GET.                                              |
| `post`    | `url`, `headers?`, `body?`, `contentType?`, `timeout?`, `expectedStatus?`, `connection?` | HTTP POST.                                             |
| `put`     | _(same as post)_                                                                         | HTTP PUT.                                              |
| `patch`   | _(same as post)_                                                                         | HTTP PATCH.                                            |
| `delete`  | `url`, `headers?`, `body?`, `timeout?`, `expectedStatus?`, `connection?`                 | HTTP DELETE.                                           |

| Shared prop      | Description                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `url`            | Request URL (templatable).                                                                                   |
| `headers`        | Map of request headers (values templatable, e.g. `Authorization: 'Bearer $env.API_KEY'`).                    |
| `body`           | String or JSON object body.                                                                                  |
| `contentType`    | `json` (default) / `form` / `text` / `xml`.                                                                  |
| `timeout`        | Per-request timeout in ms.                                                                                   |
| `expectedStatus` | Array of acceptable HTTP status codes; anything else fails the step.                                         |
| `connection`     | Name of a stored [connection](/en/automation-connections) — injects OAuth2/API-key/basic/bearer credentials. |

```yaml
- name: createContact
  type: http
  operator: post
  props:
    url: 'https://api.crm.example/contacts'
    connection: crm-oauth
    contentType: json
    body: { email: '{{trigger.data.email}}', name: '{{trigger.data.name}}' }
    expectedStatus: [200, 201]
```

:::callout
**Use `connection` instead of inlining secrets.** When a `connection` is referenced, Sovrium attaches the right `Authorization` header and (for OAuth2) refreshes tokens automatically. Define connections under `app.connections`. See [Connections](/en/automation-connections).
:::

## Webhook — Outgoing & Response

Two operators. `send` fires a signed outgoing webhook; `response` writes the HTTP response for an automation started by a **webhook trigger**.

| Operator   | Props                              | Description                                                                  |
| ---------- | ---------------------------------- | ---------------------------------------------------------------------------- |
| `send`     | `url`, `event`, `data?`, `secret?` | Send an outgoing webhook with an `event` name and optional HMAC `secret`.    |
| `response` | `status?`, `body?`, `headers?`     | Set the HTTP response returned to the inbound caller (webhook-trigger only). |

```yaml
# Notify a downstream service
- name: notifyDownstream
  type: webhook
  operator: send
  props:
    url: 'https://hooks.example.com/orders'
    event: order.created
    data: { id: '{{trigger.data.id}}' }
    secret: $env.OUTGOING_WEBHOOK_SECRET

# Reply to the inbound caller
- name: ack
  type: webhook
  operator: response
  props: { status: 200, body: { ok: true } }
```

:::callout
**Inbound vs outgoing vs table webhooks.** The `webhook` **trigger** receives inbound HTTP (see [Triggers](/en/automation-triggers)). The `webhook/send` **action** posts outgoing HTTP from a running automation. Separately, [table webhooks](/en/table-webhooks) fire automatically on record create/update/delete without an automation. The `webhook/response` action only applies to automations started by a webhook trigger.
:::

## Related Pages

- [Connections](/en/automation-connections) — OAuth2, API key, basic, bearer credentials.
- [Environment Variables](/en/automation-env-vars) — `$env` secrets used in headers.
- [Triggers](/en/automation-triggers) — the inbound webhook trigger.
- [Table Webhooks](/en/table-webhooks) — automatic outgoing webhooks on record events.
- [Data & State Actions](/en/automation-data-actions) — transforming HTTP responses.

# Record & File Actions

The `record` family reads and writes table records (single and batch). The `file` family performs storage operations — upload, download, generation, and transformation.

## Record — Table CRUD

Operators cover single-row CRUD plus batch operations. Reads/updates/deletes use a [condition group](/en/automation-flow-control) `filter`; creates/updates carry a `data` map. Batch operators iterate over an `items` array (a template resolving to a list).

| Operator      | Props                                                  | Description                                             |
| ------------- | ------------------------------------------------------ | ------------------------------------------------------- |
| `create`      | `table`, `data`                                        | Insert one record.                                      |
| `read`        | `table`, `filter`                                      | Read records matching the filter.                       |
| `update`      | `table`, `data`, `filter`                              | Update records matching the filter.                     |
| `delete`      | `table`, `filter`                                      | Soft-delete records matching the filter.                |
| `upsert`      | `table`, `data`, `filter`                              | Update if a match exists, otherwise create.             |
| `batchCreate` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Insert many records from an array.                      |
| `batchUpdate` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Update many records from an array.                      |
| `batchUpsert` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Upsert many records from an array.                      |
| `batchDelete` | `table`, `filter`, `limit?`                            | Delete records matching the filter (capped by `limit`). |

```yaml
- name: logActivity
  type: record
  operator: create
  props:
    table: activity_log
    data:
      action: 'order.created'
      order_id: '{{trigger.data.id}}'
      occurred_at: '{{now}}'
```

```yaml
- name: importRows
  type: record
  operator: batchCreate
  props:
    table: contacts
    items: '{{parseLeads.result}}'
    batchSize: 100
    continueOnItemError: true
```

:::callout
**Record actions respect table permissions and soft-delete.** Writes go through the same RBAC and validation as the [records API](/en/records-overview); `delete` is soft by default (sets `deleted_at`). See [Table Permissions](/en/table-permissions) and [Records CRUD](/en/records-crud).
:::

## File — Storage Operations

Fourteen operators spanning storage, metadata/access, generation, and advanced transforms. They operate against Sovrium's configured storage (local or S3) — see [File Operations](/en/file-operations).

### Storage

| Operator   | Props                             | Description                    |
| ---------- | --------------------------------- | ------------------------------ |
| `upload`   | `source`, `path?`, `contentType?` | Upload a file to storage.      |
| `download` | `key`                             | Download a stored file by key. |
| `delete`   | `key`                             | Delete a stored file.          |
| `copy`     | `source`, `destination`           | Copy a stored file.            |
| `move`     | `source`, `destination`           | Move/rename a stored file.     |
| `list`     | `prefix`, `limit?`                | List files under a prefix.     |

### Metadata & Access

| Operator      | Props                             | Description                                                                                     |
| ------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- |
| `getMetadata` | `key`                             | Read a file's metadata (size, content type, …).                                                 |
| `signUrl`     | `key`, `expiresIn?`, `operation?` | Generate a time-limited signed URL (`download` / `upload`). See [Signed URLs](/en/signed-urls). |

### Generation

| Operator      | Props                                                                                    | Description                                                    |
| ------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `generatePdf` | `template`, `filename`, `data?`, `pageSize?`, `orientation?`, `margins?`, `destination?` | Render an HTML template to a PDF (`A4`/`A3`/`Letter`/`Legal`). |
| `generateCsv` | `data`, `filename`, `columns?`, `delimiter?`, `includeHeaders?`, `destination?`          | Generate a CSV from an array.                                  |

### Advanced

| Operator         | Props                                                                                 | Description                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `parseCsv`       | `source`, `columns?`, `skipRows?`, `delimiter?`                                       | Parse a CSV file into an array of rows.                                                             |
| `extractText`    | `source`, `format?`                                                                   | Extract text from a document (`plain` / `markdown`).                                                |
| `transformImage` | `source`, `width?`, `height?`, `fit?`, `format?`, `quality?`, `crop?`, `destination?` | Resize/convert an image (`jpeg`/`png`/`webp`/`avif`). See [Image Transforms](/en/image-transforms). |
| `compress`       | `files`, `filename`, `destination?`                                                   | Zip multiple files into one archive.                                                                |

```yaml
- name: invoice
  type: file
  operator: generatePdf
  props:
    template: invoice-template
    filename: 'invoice-{{trigger.data.id}}.pdf'
    data: '{{trigger.data}}'
    pageSize: A4
    orientation: portrait
    destination: invoices/
```

```yaml
- name: thumbnail
  type: file
  operator: transformImage
  props:
    source: '{{upload.result.key}}'
    width: 320
    fit: cover
    format: avif
    quality: 70
```

:::callout
**Eco-aware image transforms.** Default to `avif` and lazy delivery for generated images; image transcoding is governed by the operator-controlled `ECO_IMAGE_FORMAT` env. See [Image Transforms](/en/image-transforms).
:::

## Related Pages

- [Records Overview](/en/records-overview) — the records data model and API.
- [Records CRUD](/en/records-crud) — the create/read/update/delete contract.
- [File Operations](/en/file-operations) — the storage layer behind file actions.
- [Signed URLs](/en/signed-urls) — time-limited access links.
- [Image Transforms](/en/image-transforms) — on-the-fly image processing.

# Flow Control Actions

Flow-control actions change the **shape** of a workflow rather than its data: they branch, iterate, halt, and compose other automations as sub-workflows.

## Condition Groups

`path` branches and the `filter/continue` gate evaluate **condition groups** — one or more comparisons combined with `and`/`or`.

| Element      | Description                                               |
| ------------ | --------------------------------------------------------- |
| `logic`      | `and` (all must match, default) or `or` (any must match). |
| `conditions` | Array of `{ field, operator, value? }` (minimum 1).       |

**Comparison operators:** `equals`, `notEquals`, `contains`, `notContains`, `startsWith`, `endsWith`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`, `isEmpty`, `isNotEmpty`, `isNull`, `isNotNull`, `matches`.

```yaml
condition:
  logic: and
  conditions:
    - { field: '{{trigger.data.status}}', operator: equals, value: paid }
    - { field: '{{trigger.data.amount}}', operator: greaterThan, value: 100 }
```

## Path — Branching

The `path/branch` operator routes execution into named branches. Each branch has its own `condition` and nested `actions`.

| Prop    | Description                                                                           |
| ------- | ------------------------------------------------------------------------------------- |
| `paths` | Array of branches: `{ name, condition?, actions[] }`.                                 |
| `mode`  | `first-match` (run the first matching branch) or `all-matching` (run all that match). |

```yaml
- name: route
  type: path
  operator: branch
  props:
    mode: first-match
    paths:
      - name: vip
        condition:
          conditions: [{ field: '{{trigger.data.tier}}', operator: equals, value: vip }]
        actions:
          - {
              name: vipEmail,
              type: email,
              operator: send,
              props: { to: '{{trigger.data.email}}', subject: 'VIP welcome', body: 'Thanks!' },
            }
      - name: standard
        actions:
          - {
              name: stdEmail,
              type: email,
              operator: send,
              props: { to: '{{trigger.data.email}}', subject: 'Welcome', body: 'Hi!' },
            }
```

## Loop — Iteration

The `loop/each` operator iterates over an array, running its nested `actions` per item.

| Prop                  | Description                                         |
| --------------------- | --------------------------------------------------- |
| `items`               | Template resolving to the array to iterate.         |
| `actions`             | Nested actions executed for each item.              |
| `maxIterations`       | Cap on the number of iterations.                    |
| `continueOnItemError` | When `true`, a failing item doesn't abort the loop. |

```yaml
- name: notifyEach
  type: loop
  operator: each
  props:
    items: '{{fetchSubscribers.result}}'
    maxIterations: 500
    continueOnItemError: true
    actions:
      - name: send
        type: email
        operator: send
        props: { to: '{{item.email}}', subject: 'Update', body: 'Hi {{item.name}}' }
```

## Flow — Stop

The `flow/stop` operator immediately halts the run with an optional status and output.

| Prop      | Description                              |
| --------- | ---------------------------------------- |
| `message` | Reason the run stopped (templatable).    |
| `status`  | `success` or `error` (default `error`).  |
| `output`  | Key-value output returned to the caller. |

```yaml
- name: bail
  type: flow
  operator: stop
  props: { status: success, message: 'Nothing to do', output: { processed: 0 } }
```

## Automation — Call & Return (Sub-Workflows)

The `automation` family composes workflows. `call` invokes another automation (one with an `automation-call` trigger); `return` sends output back to the caller.

| Operator | Props                                                  | Description                                                                                                                                   |
| -------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `call`   | `name`, `inputData?`, `waitForCompletion?`, `timeout?` | Invoke a sub-automation by `name`; optionally wait for it and time out.                                                                       |
| `return` | `output`                                               | Return key-value output to the calling automation (only with `automation-call` trigger). Accessible as `steps.{name}.result.*` in the parent. |

```yaml
# Parent: invoke a reusable sub-workflow and wait
- name: enrich
  type: automation
  operator: call
  props:
    name: enrich-lead
    inputData: { email: '{{trigger.data.email}}' }
    waitForCompletion: true
    timeout: 30000

# Sub-workflow (trigger: { type: automation-call }): return result
- name: done
  type: automation
  operator: return
  props: { output: { score: '{{computeScore.result}}' } }
```

:::callout
**Sub-workflow vs failure handling.** `automation/call` invokes a target that declares an `automation-call` trigger. To react to a workflow that _fails_, use the [`automation-failure` trigger](/en/automation-triggers) instead.
:::

## Related Pages

- [Actions Overview](/en/automation-actions-overview) — base props and the family map.
- [Triggers](/en/automation-triggers) — `automation-call` and `automation-failure` triggers.
- [Data & State Actions](/en/automation-data-actions) — `filter/continue` conditional gating.
- [Approval & Delay](/en/automation-approval-delay) — pausing a run for humans or time.

# Email & Notification Actions

The `email` family sends transactional email from a running automation. The `analytics` family emits named events used for notifications, metrics, and downstream tracking.

## Email — Send

One operator. Recipients support templates; `cc`/`bcc`/`replyTo` accept a single address or an array.

| Prop      | Description                                              |
| --------- | -------------------------------------------------------- |
| `to`      | Recipient address (templatable). **Required.**           |
| `subject` | Email subject (templatable). **Required.**               |
| `body`    | Email body (templatable). **Required.**                  |
| `from`    | Sender address (defaults to the configured SMTP sender). |
| `cc`      | Carbon-copy address(es) — string or array.               |
| `bcc`     | Blind-copy address(es) — string or array.                |
| `replyTo` | Reply-to address(es) — string or array.                  |

```yaml
- name: orderConfirmation
  type: email
  operator: send
  props:
    to: '{{trigger.data.customer_email}}'
    subject: 'Order {{trigger.data.id}} confirmed'
    body: 'Thanks for your order! Total: ${{trigger.data.amount}}'
    cc: [sales@example.com]
    replyTo: support@example.com
```

:::callout
**Email requires SMTP to be configured.** When `SMTP_HOST` is unset, email is disabled and the send is logged rather than delivered — Sovrium does not silently fall back to a local mail catcher in production. Configure SMTP via env vars (see [Environment Variables](/en/automation-env-vars) and the app's auth/email settings).
:::

## Analytics — Track (Notifications & Metrics)

One operator. Emits a named event with arbitrary properties — the foundation for in-app notifications, usage metrics, and downstream sinks.

| Prop         | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| `event`      | Event name (e.g. `order.created`, `user.invited`). **Required.** |
| `properties` | Key-value event properties (templatable).                        |

```yaml
- name: trackSignup
  type: analytics
  operator: track
  props:
    event: user.signed_up
    properties:
      userId: '{{trigger.data.id}}'
      plan: '{{trigger.data.plan}}'
```

:::callout
**Notifications are event-driven.** Rather than a standalone notifications config block, Sovrium drives in-app and email notifications from automation events: an `analytics/track` event (or a record/auth trigger) fans out to channels, and an `email/send` action delivers the message. Compose these with [flow control](/en/automation-flow-control) and [digest batching](/en/automation-data-actions) for daily summaries.
:::

## Related Pages

- [Actions Overview](/en/automation-actions-overview) — base props and the family map.
- [Environment Variables](/en/automation-env-vars) — SMTP and provider secrets.
- [Data & State Actions](/en/automation-data-actions) — `digest` for batching notifications.
- [Analytics](/en/analytics) — the analytics surface that consumes tracked events.

# AI Actions

The `ai` family runs language-model operations as automation steps. Four operators cover free-form generation, classification, structured extraction, and autonomous agent execution. Provider and model are explicit per action; credentials come from a stored [connection](/en/automation-connections). For self-hosted or custom endpoints (e.g. Ollama), the base URL is configured once via the `AI_BASE_URL` environment variable, not per action.

| Operator   | Purpose                                                            |
| ---------- | ------------------------------------------------------------------ |
| `generate` | Produce free-form text (or JSON) from a prompt.                    |
| `classify` | Assign an input to one of a fixed set of categories.               |
| `extract`  | Pull structured data matching a schema out of unstructured text.   |
| `agent`    | Invoke a configured autonomous agent to perform a multi-step task. |

**Shared provider props:** `provider` is `openai` / `anthropic` / `ollama` / `custom`; `model` is the model id; `connection` references stored credentials. Self-hosted endpoints (e.g. Ollama) are pointed at via the `AI_BASE_URL` environment variable.

## generate

| Prop             | Description                                                 |
| ---------------- | ----------------------------------------------------------- |
| `provider`       | `openai` / `anthropic` / `ollama` / `custom`. **Required.** |
| `model`          | Model id. **Required.**                                     |
| `prompt`         | The user prompt (templatable). **Required.**                |
| `systemPrompt`   | Optional system prompt.                                     |
| `temperature`    | Sampling temperature.                                       |
| `maxTokens`      | Max tokens to generate.                                     |
| `responseFormat` | `text` (default) or `json`.                                 |
| `connection`     | Stored connection providing credentials.                    |

```yaml
- name: draftReply
  type: ai
  operator: generate
  props:
    provider: anthropic
    model: claude-sonnet
    systemPrompt: 'You are a concise support agent.'
    prompt: 'Draft a reply to: {{trigger.comment.body}}'
    responseFormat: text
    connection: anthropic-key
```

## classify

| Prop         | Description                                       |
| ------------ | ------------------------------------------------- |
| `input`      | Text to classify (templatable). **Required.**     |
| `categories` | Array of candidate category labels. **Required.** |
| _(provider)_ | `provider`, `model`, `connection?`                |

```yaml
- name: triage
  type: ai
  operator: classify
  props:
    provider: openai
    model: gpt-4o-mini
    input: '{{trigger.data.message}}'
    categories: [bug, billing, feature-request, spam]
    connection: openai-key
```

## extract

| Prop         | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `input`      | Unstructured text to extract from (templatable). **Required.** |
| `schema`     | JSON Schema describing the desired output shape. **Required.** |
| _(provider)_ | `provider`, `model`, `connection?`                             |

```yaml
- name: parseInvoice
  type: ai
  operator: extract
  props:
    provider: openai
    model: gpt-4o
    input: '{{extractText.result}}'
    schema:
      total: { type: number }
      due_date: { type: string }
      vendor: { type: string }
    connection: openai-key
```

## agent

Invokes an autonomous agent configured under the app's AI agents. The agent plans and executes multiple steps against its scoped tools.

| Prop             | Description                                       |
| ---------------- | ------------------------------------------------- |
| `agent`          | Name of a configured agent. **Required.**         |
| `task`           | The task instruction (templatable). **Required.** |
| `context`        | Key-value context passed to the agent.            |
| `maxSteps`       | Cap on the agent's reasoning/tool steps.          |
| `responseFormat` | `text` (default) or `json`.                       |
| `timeout`        | Per-invocation timeout in ms.                     |
| `connection`     | Stored connection providing credentials.          |

```yaml
- name: resolve
  type: ai
  operator: agent
  props:
    agent: support-resolver
    task: 'Resolve ticket {{trigger.data.id}} using the knowledge base.'
    context: { customerTier: '{{trigger.data.tier}}' }
    maxSteps: 8
    responseFormat: json
```

:::callout
**Eco-aware provider routing.** AI calls route through the provider-precedence resolver governed by `ECO_AI_PROVIDER_PRECEDENCE` (default `local-first`) — never hard-code a single cloud provider when a local model can serve the request. See [AI Overview](/en/ai-overview).
:::

## Related Pages

- [AI Overview](/en/ai-overview) — providers, models, and eco routing.
- [AI Agents](/en/ai-agents) — configuring the autonomous agents invoked by `ai/agent`.
- [Connections](/en/automation-connections) — credentials for AI providers.
- [Approval & Delay](/en/automation-approval-delay) — human-in-the-loop gates around AI output.

# Approval & Delay Actions

These two families **pause** a running workflow. The `approval` family waits for a human decision (human-in-the-loop). The `delay` family waits for a duration, a datetime, an external webhook callback, or paces a queue of items.

## Approval — Human-in-the-Loop

One operator, `request`. It suspends the run, notifies approvers, and resumes once a decision is recorded (or the timeout fires). Requires `app.auth` to be configured.

| Prop        | Description                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approvers` | `all-admins`, or an array of email addresses / role names. **Required.**                                                                          |
| `message`   | Message shown to approvers (templatable). **Required.**                                                                                           |
| `options`   | Approval choices, minimum 2 (`{ value, label? }`). Default `[{ value: approve }, { value: reject }]`. The chosen `value` becomes the step output. |
| `timeout`   | How long to wait (e.g. `24h`, `7d`). No timeout by default.                                                                                       |
| `onTimeout` | On timeout: `approve` (auto-approve), `reject` (auto-reject), or `escalate` (notify escalation).                                                  |
| `notifyVia` | Notification channel: `email` (default), `webhook`, or `both`.                                                                                    |

```yaml
- name: approveRefund
  type: approval
  operator: request
  props:
    approvers: all-admins
    message: 'Approve refund of ${{trigger.data.amount}} for order {{trigger.data.id}}?'
    options:
      - { value: approve, label: 'Approve refund' }
      - { value: reject, label: 'Deny' }
    timeout: 48h
    onTimeout: reject
    notifyVia: email
```

:::callout
**Branch on the decision.** The approval step's output (the chosen option `value`) feeds naturally into a [`path/branch`](/en/automation-flow-control) so the workflow can take different paths for approve vs reject.
:::

## Delay — Wait, Queue, Webhook

Three operators that pause execution differently.

### wait

Pause for a fixed duration or until a specific datetime.

| Prop       | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| `duration` | Delay as number + unit (`ms`/`s`/`m`/`h`/`d`), e.g. `30s`, `24h`, `7d`.     |
| `until`    | ISO 8601 datetime (or template) to wait until, e.g. `2025-12-01T09:00:00Z`. |

```yaml
- name: cooldown
  type: delay
  operator: wait
  props: { duration: 15m }
```

### queue

Process queued items one at a time with configurable spacing — ideal for rate-limited downstream APIs.

| Prop           | Description                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `interval`     | Minimum delay between processing each item — number + unit (`ms`/`s`/`m`/`h`), e.g. `500ms`, `2s`. **Required.** |
| `maxQueueSize` | Max items in the queue before new entries are rejected (default unlimited).                                      |

```yaml
- name: paceApiCalls
  type: delay
  operator: queue
  props: { interval: 1s, maxQueueSize: 1000 }
```

### webhook

Pause until an external webhook callback is received (e.g. an async third-party job completes).

| Prop           | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `callbackId`   | Custom callback identifier (templatable). Auto-generated when omitted. |
| `timeout`      | Max time to wait for the callback — number + unit, e.g. `1h`, `7d`.    |
| `onTimeout`    | On timeout: `continue`, `stop`, or `error` (default `error`).          |
| `expectedData` | Expected shape used to validate the inbound callback payload.          |

```yaml
- name: awaitProcessing
  type: delay
  operator: webhook
  props:
    callbackId: 'job-{{trigger.data.id}}'
    timeout: 2h
    onTimeout: error
```

## Related Pages

- [Actions Overview](/en/automation-actions-overview) — base props and the family map.
- [Flow Control](/en/automation-flow-control) — branch on an approval decision.
- [HTTP & Webhooks](/en/automation-http-actions) — inbound webhook responses and outgoing sends.
- [Auth Overview](/en/auth-overview) — `app.auth` (required for approvals).

# Connections

Connections store credentials for external services **once** under the top-level `app.connections[]` array, then reference them from HTTP and AI actions via `$connection.NAME`. Sovrium attaches the right authentication on each request and — for OAuth2 — refreshes tokens automatically.

```yaml
connections:
  - name: crm-oauth
    label: Acme CRM
    type: oauth2
    props:
      provider: google
      clientId: $env.GOOGLE_CLIENT_ID
      clientSecret: $env.GOOGLE_CLIENT_SECRET
      scopes: [openid, email, profile]
```

Every connection shares three base fields and a typed `props` object:

| Property      | Description                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| `name`        | Kebab-case identifier (`^[a-z][a-z0-9-]*$`, max 100). Referenced as `$connection.NAME`. **Required.** |
| `label`       | Human-readable label.                                                                                 |
| `description` | What the connection is for.                                                                           |
| `type`        | `oauth2` / `apiKey` / `basic` / `bearer`. **Required.** Determines the `props` shape.                 |
| `props`       | Type-specific credential config (below). Secret values should use `$env.VAR`.                         |

Connection names must be unique across the app.

## OAuth2

Full OAuth2 with authorization-code or client-credentials grants, PKCE, token refresh, and per-user vs shared (app) tokens.

| `props` field          | Description                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`             | Known provider shorthand (e.g. `google`, `github`, `slack`). May infer auth/token URLs.                                                     |
| `clientId`             | OAuth2 client ID (supports `$env.VAR`). **Required.**                                                                                       |
| `clientSecret`         | OAuth2 client secret (supports `$env.VAR`). **Required.**                                                                                   |
| `authorizationUrl`     | Authorization endpoint (required for custom providers).                                                                                     |
| `tokenUrl`             | Token endpoint (required for custom providers).                                                                                             |
| `scopes`               | Array of scopes to request.                                                                                                                 |
| `redirectUri`          | Redirect URI registered with the provider. Required at runtime — auto-generation is not implemented.                                        |
| `grantType`            | `authorizationCode` (default) or `clientCredentials`.                                                                                       |
| `pkce`                 | PKCE method: `S256` (recommended), `plain`, or `none` (default).                                                                            |
| `audience`             | API audience / resource identifier (e.g. an Auth0 audience URL).                                                                            |
| `authenticationMethod` | How client creds are sent on token requests: `header` (HTTP Basic, RFC 6749 default) or `body` (form params). Honored by the refresh grant. |
| `extraAuthParams`      | Extra params appended to the authorization URL (e.g. `access_type: offline`, `prompt: consent`).                                            |
| `extraTokenParams`     | Extra params appended to token-exchange requests.                                                                                           |
| `scope`                | Connection scope: `app` (admin-only shared token, default) or `user` (per-user tokens).                                                     |

```yaml
- name: hubspot
  type: oauth2
  props:
    clientId: $env.HUBSPOT_CLIENT_ID
    clientSecret: $env.HUBSPOT_CLIENT_SECRET
    authorizationUrl: 'https://app.hubspot.com/oauth/authorize'
    tokenUrl: 'https://api.hubapi.com/oauth/v1/token'
    scopes: [crm.objects.contacts.read]
    redirectUri: 'https://myapp.example.com/oauth/callback'
    pkce: S256
    scope: user
    extraAuthParams: { access_type: offline, prompt: consent }
```

:::callout
**App vs per-user tokens.** `scope: app` stores one shared token usable by admins. `scope: user` issues and stores tokens per end-user, so each user's HTTP/AI actions act as themselves. **Client-credentials** flows (machine-to-machine, no user) set `grantType: clientCredentials`. Token refresh happens automatically; the refresh request honors `authenticationMethod`.
:::

## API Key

API key sent in a configurable header, with an optional prefix.

| `props` field | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| `key`         | API key value (typically `$env.VAR`). **Required.**             |
| `header`      | Header name for the key (default `X-API-Key`).                  |
| `prefix`      | Prefix before the value in the header (e.g. `Bearer`, `Token`). |

```yaml
- name: github-api
  type: apiKey
  props: { key: $env.GITHUB_TOKEN, header: Authorization, prefix: Bearer }
```

## Basic Auth

HTTP Basic authentication.

| `props` field | Description                                   |
| ------------- | --------------------------------------------- |
| `username`    | Username (supports `$env.VAR`). **Required.** |
| `password`    | Password (supports `$env.VAR`). **Required.** |

```yaml
- name: legacy-api
  type: basic
  props: { username: $env.LEGACY_USER, password: $env.LEGACY_PASS }
```

## Bearer Token

A static bearer token sent in the `Authorization` header.

| `props` field | Description                                              |
| ------------- | -------------------------------------------------------- |
| `token`       | Bearer token value (typically `$env.VAR`). **Required.** |

```yaml
- name: internal-svc
  type: bearer
  props: { token: $env.INTERNAL_SERVICE_TOKEN }
```

## Referencing a Connection

Attach a connection to an HTTP or AI action via the `connection` prop:

```yaml
- name: fetch
  type: http
  operator: get
  props: { url: 'https://api.example.com/me', connection: github-api }
```

## Related Pages

- [HTTP & Webhooks](/en/automation-http-actions) — actions that consume connections.
- [AI Actions](/en/automation-ai-actions) — AI providers authenticated via connections.
- [Environment Variables](/en/automation-env-vars) — `$env` secrets referenced by connection props.
- [Auth Overview](/en/auth-overview) — end-user authentication (distinct from outbound connections).

# Environment Variables

Declare the environment variables your automations need under the top-level `app.env[]` array. Each entry documents a variable, whether it's required, and an optional default. At runtime, reference a value anywhere a template or connection prop is accepted with `$env.VAR_NAME`.

```yaml
env:
  - { key: SLACK_WEBHOOK_URL, description: Slack incoming webhook URL }
  - { key: STRIPE_SECRET, description: Stripe API secret, required: true }
  - { key: REGION, description: Default region, required: false, default: eu-west }
```

## Env Var Properties

| Property      | Description                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | Variable name in uppercase snake*case (`^[A-Z]A-Z0-9*]\*$`, e.g. `API_KEY`). **Required.**                                        |
| `description` | What the variable is used for.                                                                                                    |
| `required`    | Whether the variable must be set (default `true`). When required and unset, validation fails at boot.                             |
| `default`     | Fallback value used when the variable is not set. When both `required` and `default` are present, `default` acts as the fallback. |

Keys must be unique across the app.

## Referencing Secrets

Use `$env.VAR_NAME` in action props, connection props, and webhook auth:

```yaml
connections:
  - name: openai-key
    type: bearer
    props: { token: $env.OPENAI_API_KEY }

automations:
  - name: notify
    trigger: { type: record, table: orders, events: [create] }
    actions:
      - name: ping
        type: http
        operator: post
        props:
          url: $env.SLACK_WEBHOOK_URL
          body: { text: 'New order {{trigger.data.id}}' }
```

:::callout
**Secrets are never logged.** Values resolved from `$env` are redacted from run logs, step outputs shown in the admin UI, and the runs API. Store credentials in `$env` (or a connection) rather than inlining them in action props.
:::

## Frugal-by-Default Operator Env

Beyond `app.env` (which the schema author declares), Sovrium's runtime footprint is governed by operator-controlled `ECO_*` environment variables (e.g. `ECO_IMAGE_FORMAT`, `ECO_AI_PROVIDER_PRECEDENCE`). These are **not** part of the app schema — operators opt out, never in. AI actions and image transforms invoked from automations honor these defaults automatically. See [AI Overview](/en/ai-overview) and [Image Transforms](/en/image-transforms).

## Related Pages

- [Connections](/en/automation-connections) — credential blocks that consume `$env`.
- [Actions Overview](/en/automation-actions-overview) — where `$env` is interpolated.
- [HTTP & Webhooks](/en/automation-http-actions) — secrets in request headers.

# Automation Runs

Every time a trigger fires, Sovrium records a **run** — a row capturing the trigger payload, each step's status and output, and the final outcome. The runs API lets you list, inspect, replay, and cancel runs for monitoring and debugging.

## Runs API

| Method & Path                           | Purpose                                                   |
| --------------------------------------- | --------------------------------------------------------- |
| `GET /api/automations/runs`             | List runs (paginated, filterable by status / automation). |
| `GET /api/automations/runs/:id`         | Run detail including per-step results.                    |
| `POST /api/automations/runs/:id/replay` | Replay a run, resuming from the first failed step.        |
| `POST /api/automations/runs/:id/cancel` | Cancel a pending or running run.                          |

```bash
# List failed runs of a specific automation
GET /api/automations/runs?status=failed&automationName=welcome-email

# Replay a failed run
POST /api/automations/runs/550e8400-.../replay
```

## Run Statuses

| Status                  | Meaning                                                                     |
| ----------------------- | --------------------------------------------------------------------------- |
| `pending`               | Queued, waiting to execute (or waiting on a concurrency slot).              |
| `running`               | Currently executing.                                                        |
| `completed`             | All actions succeeded.                                                      |
| `completed-with-errors` | Finished, but one or more steps failed under `continueOnError`.             |
| `failed`                | An action errored (triggers the `automation-failure` trigger + retries).    |
| `timed-out`             | Exceeded the automation- or action-level `timeout`. Distinct from `failed`. |
| `exhausted`             | Failed after exhausting all configured retry attempts (dead-letter).        |
| `cancelled`             | Manually cancelled via the API.                                             |

## Step Statuses

| Status      | Meaning                                                                       |
| ----------- | ----------------------------------------------------------------------------- |
| `running`   | Currently executing.                                                          |
| `completed` | Succeeded.                                                                    |
| `failed`    | Errored.                                                                      |
| `skipped`   | Not run — e.g. after a `filter/continue` halt or in partial-failure recovery. |

## Replay & Idempotent Resume

Replaying a partially failed run **skips already-completed steps** and resumes from the first failed step (idempotent resume) — completed steps are never re-executed. Replay always creates a **new** run rather than mutating the original, preserving audit history.

:::callout
**Distinguish duration from error.** A run that exceeds its `timeout` is recorded as `timed-out`, not `failed`, so operators can tell runaway workflows apart from genuine errors. After retries are exhausted, the status becomes `exhausted` and the [`automation-failure` trigger](/en/automation-triggers) fires with the full attempt history.
:::

## Related Pages

- [Retry & Failure](/en/automation-retry-failure) — retry policies, timeouts, dead-letter, idempotency.
- [Triggers](/en/automation-triggers) — the `automation-failure` trigger that reacts to `failed`/`exhausted` runs.
- [Automations Overview](/en/automations-overview) — concurrency and the run lifecycle.

# Retry & Failure Handling

Automations are resilient by configuration: retry transient failures with backoff, fence runaway steps with timeouts, recover partially-failed runs idempotently, and route exhausted runs to a failure handler.

## Retry Policy

A `retry` block can be set at the **automation** level (whole run) or the **action** level (single step).

| Property      | Description                                                           |
| ------------- | --------------------------------------------------------------------- |
| `maxAttempts` | Maximum retry attempts (1–10). **Required.**                          |
| `delayMs`     | Base delay between retries in ms (100–60000, default 1000).           |
| `strategy`    | `fixed` (constant delay, default) or `exponential` (growing backoff). |

```yaml
automations:
  - name: sync-inventory
    trigger: { type: cron, expression: '0 * * * *' }
    retry: { maxAttempts: 5, delayMs: 2000, strategy: exponential }
    actions:
      - name: pull
        type: http
        operator: get
        props: { url: $env.INVENTORY_API, expectedStatus: [200] }
        retry: { maxAttempts: 3, strategy: fixed } # per-action override
```

## Timeouts

Two independent timeout scopes:

| Scope            | Where                              | Effect                                                            |
| ---------------- | ---------------------------------- | ----------------------------------------------------------------- |
| Automation       | `automation.timeout` (1000–900000) | Caps total run time. On expiry the run is marked `timed-out`.     |
| Action (uniform) | `action.timeout` (1000–900000)     | Caps one step; `retry`/`continueOnError` still apply.             |
| Action (handler) | `action.props.timeout`             | Per-type internal fence (e.g. `http`, `code`, `automation/call`). |

A `timed-out` run is **distinct from `failed`** so operators can tell runaway duration apart from errors.

## Continue on Error

Set `continueOnError: true` on an action so its failure doesn't abort the run. Subsequent actions still execute and the run finishes as `completed-with-errors`.

```yaml
- name: bestEffortLog
  type: analytics
  operator: track
  continueOnError: true
  props: { event: order.created, properties: { id: '{{trigger.data.id}}' } }
```

## Dead Letter & Exhaustion

When a run fails after exhausting all configured `maxAttempts`, it transitions to the `exhausted` status (dead-letter). Each attempt is recorded with timestamp, error message, and stack trace. The [`automation-failure` trigger](/en/automation-triggers) fires after exhaustion, handing the failure handler the full attempt history — enabling centralized failure handling without per-automation notification config.

## Partial-Failure Recovery & Idempotency

When a run fails mid-pipeline, completed steps show `completed`, the failing step shows `failed`, and downstream steps show `skipped`. Replaying the run **resumes from the failed step**, skipping already-completed steps (idempotent resume). Replay always creates a new run, never mutating the original.

:::callout
**Webhook deduplication.** Webhook triggers accept a `deduplicationKey` (a template over the payload) and `deduplicationWindow` (seconds) to drop duplicate runs from identical payloads. Combined with idempotent resume, this makes at-least-once delivery safe. See [Triggers](/en/automation-triggers).
:::

## Related Pages

- [Runs](/en/automation-runs) — run/step statuses, replay, and cancel.
- [Triggers](/en/automation-triggers) — `automation-failure` trigger and webhook dedup.
- [Actions Overview](/en/automation-actions-overview) — `retry`, `timeout`, `continueOnError` base props.

# Auth Actions

The `auth` family manages user accounts as part of a workflow — provisioning users, changing roles, and moderating accounts. These actions require `app.auth` to be configured and go through the same RBAC as the rest of the platform. Four operators.

| Operator     | Props                                 | Description                                                                                                    |
| ------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `createUser` | `email`, `name`, `password?`, `role?` | Create a new user account (password auto-generated if omitted; role defaults to the configured `defaultRole`). |
| `assignRole` | `userId`, `role`                      | Assign a role (`admin`, `member`, `viewer`, or custom) to an existing user.                                    |
| `banUser`    | `userId`, `reason?`                   | Ban a user account; `reason` is stored for the audit trail.                                                    |
| `unbanUser`  | `userId`                              | Lift a ban on a user account.                                                                                  |

```yaml
# Provision a teammate when an invite record is created
- name: provision
  type: auth
  operator: createUser
  props:
    email: '{{trigger.data.email}}'
    name: '{{trigger.data.name}}'
    role: member

# Promote on approval
- name: promote
  type: auth
  operator: assignRole
  props: { userId: '{{trigger.data.user_id}}', role: admin }
```

:::callout
**Auth actions need `app.auth`.** They operate on the same user store and roles as end-user authentication. See [Auth Overview](/en/auth-overview) and [Roles & RBAC](/en/auth-roles-rbac).
:::

## Related Pages

- [Auth Overview](/en/auth-overview) — authentication configuration.
- [Roles & RBAC](/en/auth-roles-rbac) — the roles assigned by `assignRole`.
- [Actions Overview](/en/automation-actions-overview) — base props and the family map.

# Code Actions

The `code` family runs custom TypeScript as an automation step for logic that the declarative actions don't cover. One operator, `runTypescript`. The source is a named `execute(context)` function whose body is **type-checked at server startup**.

| Prop        | Description                                                                                                                                                                      |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | TypeScript source for a named `execute(context)` function. In TS configs, wrap with `String(function execute(context: CodeContext) { … })` for IDE autocompletion. **Required.** |
| `inputData` | Template-resolved key-value pairs passed as `context.inputData`.                                                                                                                 |
| `input`     | Template-resolved key-value pairs passed as `context.input` (same resolution rules as `inputData`).                                                                              |
| `packages`  | npm package specifiers with optional version pins (e.g. `lodash`, `date-fns@3.6.0`, `@scope/pkg@1.2.3`). Resolved/installed at app start or via `sovrium install`.               |
| `timeout`   | Execution timeout in ms (1000–300000, default 30000).                                                                                                                            |

## Code Context

The `execute` function receives a `context` object:

| Member              | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `context.trigger`   | The trigger payload.                                              |
| `context.steps`     | Outputs of prior steps, keyed by step name.                       |
| `context.inputData` | Template-resolved inputs from the `inputData` prop.               |
| `context.input`     | Template-resolved inputs from the `input` prop.                   |
| `context.env`       | Environment variables (sensitive values redacted in logs).        |
| `context.actions`   | Invoke native actions or reusable templates from within the code. |
| `context.packages`  | The declared npm packages, accessed by name.                      |
| `context.log`       | Structured logging: `info`, `warn`, `error`.                      |

```yaml
- name: enrich-lead
  type: code
  operator: runTypescript
  props:
    packages: [date-fns]
    inputData: { url: '{{trigger.data.profile_url}}' }
    code: |
      async function execute(context) {
        const res = await context.actions.http.get({ url: context.inputData.url })
        context.log.info('fetched', res.status)
        return { score: res.body.score, fetchedAt: new Date().toISOString() }
      }
```

:::callout
**Type-checked at startup, sandboxed at runtime.** The `execute` body is validated when the app boots, so a malformed function fails fast rather than mid-run. Declared `packages` are resolved ahead of time and exposed via `context.packages` — they are not fetched on demand inside the sandbox.
:::

## Related Pages

- [Actions Overview](/en/automation-actions-overview) — invoking native actions (also available as `context.actions`) and reusable `ref` templates.
- [Environment Variables](/en/automation-env-vars) — `context.env` and secret redaction.
- [HTTP & Webhooks](/en/automation-http-actions) — the HTTP actions reachable from code.

# Cloud Actions

The `cloud` family orchestrates **Sovrium Cloud** tenant apps — provisioning their databases, booting their processes, attaching ingress routes, and tearing them down. Five operators. These actions are **gated**: they only run when the host process is started with the `SOVRIUM_CLOUD_MODE` env flag.

| Operator       | Props                  | Description                                                     |
| -------------- | ---------------------- | --------------------------------------------------------------- |
| `provision-db` | `dbName`               | Provision a logical database for a tenant (e.g. `tenant_acme`). |
| `spawn-app`    | `appSlug`, `configRef` | Boot a tenant app process from a validated config reference.    |
| `route-add`    | `domain`, `port`       | Attach an ingress route (domain → port) to a tenant app.        |
| `disable-app`  | `appSlug`              | Stop a tenant app while preserving its data.                    |
| `destroy-app`  | `appSlug`              | Tear down a tenant app and drop its data.                       |

| Prop        | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| `appSlug`   | Tenant app slug — stable lowercase-kebab identifier (e.g. `acme-crm`). Templatable. |
| `dbName`    | Logical tenant database name (e.g. `tenant_acme`). Templatable.                     |
| `configRef` | Reference to the validated tenant config to boot (id / row ref / URL). Templatable. |
| `domain`    | Route domain to attach — a bare host (e.g. `acme.sovrium.app`). Templatable.        |
| `port`      | Tenant app listening port the route targets (1–65535).                              |

```yaml
# Onboard a new tenant when a signup record is approved
automations:
  - name: onboard-tenant
    trigger: { type: record, table: tenant_signups, events: [update] }
    actions:
      - name: db
        type: cloud
        operator: provision-db
        props: { dbName: 'tenant_{{trigger.data.slug}}' }
      - name: boot
        type: cloud
        operator: spawn-app
        props: { appSlug: '{{trigger.data.slug}}', configRef: '{{trigger.data.config_ref}}' }
      - name: route
        type: cloud
        operator: route-add
        props: { domain: '{{trigger.data.slug}}.sovrium.app', port: 3000 }
```

:::callout
**Gated, never schema-controlled.** Cloud actions are accepted by the schema everywhere, but a config that uses them is **rejected at validate time** unless the host runs with the `SOVRIUM_CLOUD_MODE` process-env gate. The gate is a host concern — never a schema field. Use these actions only in a Sovrium Cloud control-plane app.
:::

## Related Pages

- [Actions Overview](/en/automation-actions-overview) — base props and the family map.
- [Triggers](/en/automation-triggers) — record/manual triggers that drive tenant onboarding.
- [Environment Variables](/en/automation-env-vars) — operator-controlled host env (distinct from `app.env`).

# Buckets Overview

Buckets are named containers for uploaded files. Each bucket carries its own size limit, allowed MIME types, public/private visibility, and access permissions. Tables reference buckets through [attachment fields](/en/attachment-fields), [forms](/en/form-file-uploads) write files into them, and the REST API exposes upload, download, signed-URL, and image-transform endpoints.

Two concerns are deliberately separated:

- **Where files are stored** — the storage _backend_ — is operator-controlled via environment variables (`STORAGE_PROVIDER` and friends). It never appears in the app schema.
- **How files are organized** — the _buckets_ — is application configuration declared in the top-level `buckets[]` array of your config.

```yaml
buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/jpeg, image/png, image/webp]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]
```

When `buckets` is omitted entirely, Sovrium provisions an implicit `default` bucket (`public: false`, standard permission defaults).

## Storage Backends

The backend is chosen at deploy time with `STORAGE_PROVIDER`. All three backends support the full file-operations, signed-URL, and image-transform surface.

| Backend            | `STORAGE_PROVIDER`                     | Best for                                    | Scalability    | Native presigned URLs           |
| ------------------ | -------------------------------------- | ------------------------------------------- | -------------- | ------------------------------- |
| Local filesystem   | `local` (default)                      | Development, single-node, self-hosted       | Disk-bound     | No (Sovrium signs internally)   |
| S3 / S3-compatible | `s3`                                   | Production, scale-out                       | Unlimited      | Yes (delegated to the provider) |
| MinIO              | `s3` + `STORAGE_FORCE_PATH_STYLE=true` | Self-hosted S3-compatible object store      | Unlimited      | Yes                             |
| PostgreSQL `bytea` | `bytea`                                | Small files, simple single-database deploys | Database-bound | No (Sovrium signs internally)   |

:::callout
**Frugal by default.** The default backend is `local` — zero external dependencies, mirroring Sovrium's SQLite-default database posture. Opt _out_ to S3 only when you need scale-out or multi-node deployments. See [Ecoconception](/en/ecoconception).
:::

### Backend Environment Variables

| Variable                   | Required | Default     | Purpose                                                                  |
| -------------------------- | -------- | ----------- | ------------------------------------------------------------------------ |
| `STORAGE_PROVIDER`         | No       | `local`     | Storage backend: `s3`, `local`, or `bytea`.                              |
| `STORAGE_ENDPOINT`         | S3 only  | —           | S3-compatible endpoint URL.                                              |
| `STORAGE_BUCKET`           | S3 only  | —           | Underlying S3 bucket name (the host object store, not a Sovrium bucket). |
| `STORAGE_REGION`           | S3 only  | `us-east-1` | AWS region.                                                              |
| `STORAGE_ACCESS_KEY`       | S3 only  | —           | S3 access key ID.                                                        |
| `STORAGE_SECRET_KEY`       | S3 only  | —           | S3 secret access key.                                                    |
| `STORAGE_FORCE_PATH_STYLE` | No       | `false`     | Use path-style URLs (required for MinIO).                                |

:::callout
**Sovrium buckets are path prefixes, not S3 buckets.** Every bucket you declare in `buckets[]` maps to a path prefix inside the single host bucket configured by `STORAGE_BUCKET` (e.g. `avatars/`, `documents/`). One S3 bucket holds all your Sovrium buckets.
:::

See [Environment Variables](/en/env-vars) for the full operator-facing variable reference.

## Bucket Properties

Each entry in the `buckets[]` array accepts the following properties.

| Property           | Description                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | Unique bucket name. Lowercase, alphanumeric, hyphens; must start with a letter; max 63 characters (S3 prefix compatibility). Used as the storage path prefix. |
| `public`           | Boolean. When `true`, files are served without signed URLs. Defaults to `false` (private).                                                                    |
| `maxFileSize`      | Maximum file size in bytes for uploads to this bucket. Overrides the global `STORAGE_MAX_FILE_SIZE`. Must be ≥ 1.                                             |
| `allowedMimeTypes` | Array of allowed MIME types for uploads. Supports wildcards (e.g. `image/*`). When omitted, all types are accepted. Minimum one entry.                        |
| `permissions`      | Per-operation access control. See [Permissions](#permissions) below.                                                                                          |

:::callout
**Name validation is strict.** `Avatars` (uppercase) and `123-bucket` (leading digit) are rejected by `sovrium validate`. Valid examples: `avatars`, `documents`, `public-assets`, `user-uploads`. Duplicate names across the array are also rejected at validation time.
:::

## Permissions

Bucket permissions use the same shared `PermissionValueSchema` format as [table permissions](/en/table-permissions): each operation accepts `all`, `authenticated`, or a list of role names.

| Operation    | Description                              | Default                                     |
| ------------ | ---------------------------------------- | ------------------------------------------- |
| `upload`     | Who can upload files to this bucket.     | `authenticated`                             |
| `download`   | Who can download files from this bucket. | `all` if public, `authenticated` if private |
| `sign`       | Who can generate signed download URLs.   | `authenticated`                             |
| `signUpload` | Who can generate signed upload URLs.     | `[admin]`                                   |
| `delete`     | Who can delete files from this bucket.   | `[admin]`                                   |

Permission values:

- `all` — everyone, including unauthenticated requests.
- `authenticated` — any logged-in user.
- `['admin', 'editor']` — only the listed roles.

```yaml
buckets:
  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf, text/csv]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]
```

When a bucket omits `permissions` entirely, the per-operation defaults above apply — notably, only the `admin` role can generate signed URLs.

## Public vs Private

| Visibility                | Behavior                                                                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `public: true`            | Files served directly without authentication or signed URLs. Suitable for avatars, logos, marketing assets.    |
| `public: false` (default) | Files require either authentication (matching `download` permission) or a valid [signed URL](/en/signed-urls). |

Operators can additionally expose path prefixes globally via `STORAGE_PUBLIC_PATHS` (see [Signed URLs](/en/signed-urls)).

## Example: Multiple Buckets

A public images bucket alongside a private, role-gated documents bucket.

```yaml
buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/*]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]
```

## Related Pages

- [File Operations](/en/file-operations) — upload, download, list, and delete endpoints.
- [Signed URLs](/en/signed-urls) — time-limited access to private files.
- [Image Transforms](/en/image-transforms) — on-the-fly resize, crop, and format conversion.
- [Attachment Fields](/en/attachment-fields) — storing files against table records.
- [Form File Uploads](/en/form-file-uploads) — accepting files through forms.
- [Environment Variables](/en/env-vars) — operator-facing backend configuration.

# File Operations

Every bucket exposes a REST API for the core file lifecycle: upload, download, and delete. Operations are authenticated against the bucket's [permissions](/en/buckets-overview#permissions), hardened against path-traversal and XSS, and integrated with Sovrium's [soft-delete pattern](/en/tables-overview).

The `{bucket}` path parameter references a bucket name declared in your `buckets[]` array. See [Buckets Overview](/en/buckets-overview).

## Endpoints

| Method   | Endpoint                            | Description                                                                       |
| -------- | ----------------------------------- | --------------------------------------------------------------------------------- |
| `POST`   | `/api/buckets/{bucket}/files`       | Upload a file (multipart form data). Returns `201` with the generated file key.   |
| `GET`    | `/api/buckets/{bucket}/files/{key}` | Download a file by key. Returns the file content with the correct `Content-Type`. |
| `DELETE` | `/api/buckets/{bucket}/files/{key}` | Delete a file by key from storage.                                                |
| `GET`    | `/api/admin/buckets/quota`          | _(Admin)_ Return current storage usage in bytes.                                  |

## Upload

Send the file as multipart form data. The server validates it against the bucket's `maxFileSize` and `allowedMimeTypes`, generates an unpredictable key, and stores it in the configured backend.

```bash
curl -X POST https://app.example.com/api/buckets/documents/files \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@report.pdf"
```

```json
{
  "key": "documents/9f3c1e2a-7b44-4d10-9e21-8a6f0c1d2e3b.pdf",
  "filename": "report.pdf",
  "size": 245760,
  "mimeType": "application/pdf"
}
```

| Behavior                                           | Result                                                                  |
| -------------------------------------------------- | ----------------------------------------------------------------------- |
| Valid file within limits                           | `201` with the generated file key.                                      |
| Empty request body                                 | `400 Bad Request`.                                                      |
| Exceeds bucket or global max size                  | `413 Payload Too Large` (rejected early, before the full body is read). |
| Exceeds `STORAGE_MAX_TOTAL_SIZE` quota             | `507 Insufficient Storage`.                                             |
| Unauthenticated request to an authenticated bucket | `401 Unauthorized`.                                                     |

:::callout
**Keys are randomized.** Uploads always receive a UUID-based key, so files never overwrite one another and storage URLs are unguessable. Two uploads of the same filename produce two distinct keys.
:::

## Download

```bash
curl https://app.example.com/api/buckets/documents/files/{key} \
  -H "Authorization: Bearer $TOKEN" -O
```

| Behavior                                                   | Result                                              |
| ---------------------------------------------------------- | --------------------------------------------------- |
| File exists, caller has `download` permission              | `200` with file content and correct `Content-Type`. |
| Non-existent key                                           | `404 Not Found`.                                    |
| Private file, no auth and no [signed URL](/en/signed-urls) | `403 Forbidden`.                                    |

Responses include a `Content-Disposition` header — non-image files are served as `attachment` to prevent the browser from rendering them inline.

## Delete

```bash
curl -X DELETE https://app.example.com/api/buckets/documents/files/{key} \
  -H "Authorization: Bearer $TOKEN"
```

| Behavior                                    | Result                            |
| ------------------------------------------- | --------------------------------- |
| File exists, caller has `delete` permission | `200`, file removed from storage. |
| Non-existent key                            | `404 Not Found`.                  |

## Security Hardening

File operations apply the recurring [pre-launch security baseline](/en/buckets-overview) for uploads automatically:

| Measure                           | Behavior                                                                  |
| --------------------------------- | ------------------------------------------------------------------------- |
| Path traversal                    | `../` sequences in filenames are sanitized or rejected.                   |
| Null bytes                        | Filenames containing null bytes are rejected.                             |
| Special / unicode characters      | Encoded safely for storage.                                               |
| Randomized keys                   | UUID-based keys prevent guessable URLs.                                   |
| `X-Content-Type-Options: nosniff` | Sent on every served file.                                                |
| `Content-Security-Policy`         | Sent on every served file.                                                |
| XSS-prone types (HTML, SVG)       | Served with a safe `Content-Type` or forced to download as an attachment. |

## File Lifecycle

Attachments follow Sovrium's soft-delete-by-default lifecycle. File presence tracks the owning record:

| Action on the record          | File behavior                                        |
| ----------------------------- | ---------------------------------------------------- |
| Soft-delete record            | File preserved in storage.                           |
| Restore record                | File access restored.                                |
| Hard-delete (purge)           | File removed from storage.                           |
| Replace attachment            | Old file removed from storage.                       |
| Clear attachment (set `null`) | File removed from storage.                           |
| Shared reference              | File preserved while any other record references it. |

## Large Uploads & Quota

Uploads stream rather than buffering wholesale, so large files do not spike memory. Limits are operator-controlled via environment variables.

| Variable                 | Default              | Purpose                                                                                |
| ------------------------ | -------------------- | -------------------------------------------------------------------------------------- |
| `STORAGE_MAX_FILE_SIZE`  | `104857600` (100 MB) | Maximum single file size in bytes. A bucket's `maxFileSize` overrides this per-bucket. |
| `STORAGE_MAX_TOTAL_SIZE` | Unlimited            | Maximum total storage per application in bytes (multi-tenant safety).                  |

```bash
STORAGE_MAX_FILE_SIZE=52428800
STORAGE_MAX_TOTAL_SIZE=10737418240
```

The admin quota endpoint reports usage:

```bash
curl https://app.example.com/api/admin/buckets/quota \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

```json
{ "usedBytes": 524288000, "maxBytes": 10737418240 }
```

Deleting files reduces tracked usage. When no `STORAGE_MAX_TOTAL_SIZE` is configured, uploads are unrestricted.

## Related Pages

- [Buckets Overview](/en/buckets-overview) — declaring buckets, backends, and permissions.
- [Signed URLs](/en/signed-urls) — time-limited download and direct browser uploads.
- [Image Transforms](/en/image-transforms) — resizing and reformatting on download.
- [Attachment Fields](/en/attachment-fields) — files attached to table records.
- [Form File Uploads](/en/form-file-uploads) — accepting uploads through forms.
- [Environment Variables](/en/env-vars) — size and quota configuration.

# Signed URLs

Signed URLs grant temporary, scoped access to private files without exposing storage credentials or making the file permanently public. A signed URL embeds an HMAC-SHA256 token (signed with `AUTH_SECRET`) that encodes the path, operation, and expiry. Tampering with any part invalidates the token.

Signed URLs work across all three storage backends. For S3 backends, Sovrium delegates to native S3 presigning; for [local and bytea backends](/en/buckets-overview#storage-backends), it generates and validates signatures internally — no AWS SDK required at the application layer.

## Public vs Private Access

By default, files are private and require either authentication or a signed URL. Operators can carve out always-public path prefixes.

| Variable                 | Default   | Purpose                                                                     |
| ------------------------ | --------- | --------------------------------------------------------------------------- |
| `STORAGE_DEFAULT_ACCESS` | `private` | Default access level for new files (`private` or `public`).                 |
| `STORAGE_PUBLIC_PATHS`   | (none)    | Comma-separated path prefixes served without authentication or signed URLs. |

```bash
STORAGE_DEFAULT_ACCESS=private
STORAGE_PUBLIC_PATHS=assets/,avatars/,logos/
```

| Behavior                                       | Result                                         |
| ---------------------------------------------- | ---------------------------------------------- |
| File under a `STORAGE_PUBLIC_PATHS` prefix     | Served without authentication or a signed URL. |
| File outside public paths, no valid signed URL | `403 Forbidden`.                               |
| `STORAGE_DEFAULT_ACCESS=public`                | All files accessible without signed URLs.      |

Public-path configuration is validated on startup — no trailing wildcards, no overlapping prefixes. A bucket marked `public: true` in the schema is the per-bucket equivalent (see [Buckets Overview](/en/buckets-overview#public-vs-private)).

## Download Signed URLs

Request a time-limited download URL for a private file.

```http
POST /api/buckets/{bucket}/sign
Content-Type: application/json
Authorization: Bearer <token>

{
  "path": "documents/contract.pdf",
  "expiresIn": 3600,
  "operation": "download"
}
```

```json
{
  "signedUrl": "https://app.example.com/api/buckets/documents/files/documents/contract.pdf?token=eyJhbGciOiJIUzI1NiJ9...",
  "path": "documents/contract.pdf",
  "expiresAt": "2026-04-05T11:00:00Z"
}
```

| Parameter   | Type    | Required | Default    | Description                                      |
| ----------- | ------- | -------- | ---------- | ------------------------------------------------ |
| `path`      | string  | Yes      | —          | File path relative to the storage root.          |
| `expiresIn` | integer | No       | `3600`     | Expiry in seconds. Range: 60 to 604800 (7 days). |
| `operation` | string  | No       | `download` | `download` or `upload`.                          |

| Behavior                        | Result                                      |
| ------------------------------- | ------------------------------------------- |
| Valid path                      | Signed URL plus `expiresAt` timestamp.      |
| Accessing the URL before expiry | File served with no further authentication. |
| Accessing after expiry          | `403 Forbidden`.                            |
| `expiresIn` < 60 or > 604800    | `400 Bad Request`.                          |
| Non-existent path               | `404 Not Found`.                            |
| Tampered token                  | `403 Forbidden`.                            |

## Upload Signed URLs

Issue a write token so a browser can upload directly to storage without proxying bytes through the application server.

```http
POST /api/buckets/{bucket}/sign
Content-Type: application/json
Authorization: Bearer <token>

{
  "path": "uploads/user-123/profile-photo.jpg",
  "expiresIn": 600,
  "operation": "upload",
  "contentType": "image/jpeg",
  "maxSize": 5242880
}
```

```json
{
  "signedUrl": "https://app.example.com/api/buckets/uploads/files/uploads/user-123/profile-photo.jpg?token=eyJhbGciOiJIUzI1NiJ9...",
  "path": "uploads/user-123/profile-photo.jpg",
  "expiresAt": "2026-04-05T10:10:00Z",
  "method": "PUT",
  "headers": { "Content-Type": "image/jpeg" }
}
```

| Parameter     | Type    | Required | Default            | Description                                          |
| ------------- | ------- | -------- | ------------------ | ---------------------------------------------------- |
| `contentType` | string  | No       | —                  | Required MIME type, enforced server-side on the PUT. |
| `maxSize`     | integer | No       | `10485760` (10 MB) | Maximum upload size in bytes.                        |

| Behavior                                 | Result                                            |
| ---------------------------------------- | ------------------------------------------------- |
| Upload via the PUT URL                   | File stored at the specified path.                |
| Upload after expiry                      | `403 Forbidden`.                                  |
| Wrong MIME type (when `contentType` set) | `400 Bad Request`.                                |
| Exceeds `maxSize`                        | `413 Payload Too Large`.                          |
| Reusing an upload token to download      | Rejected — the operation is encoded in the token. |

## Batch Signing

Generate signed URLs for up to 100 files in one request — useful for rendering a page full of private images.

```http
POST /api/buckets/{bucket}/sign/batch
Content-Type: application/json
Authorization: Bearer <token>

{
  "files": [
    { "path": "photos/photo-1.jpg", "expiresIn": 3600 },
    { "path": "photos/photo-2.jpg", "expiresIn": 3600 },
    { "path": "documents/report.pdf", "expiresIn": 7200 }
  ]
}
```

Each file may carry its own `expiresIn`. Non-existent files are returned with an `error: "not_found"` entry (partial success rather than failing the whole batch). Requesting more than 100 files returns `400 Bad Request`.

## Endpoint Summary

| Method | Endpoint                                       | Auth                                    |
| ------ | ---------------------------------------------- | --------------------------------------- |
| `POST` | `/api/buckets/{bucket}/sign`                   | Required (session).                     |
| `POST` | `/api/buckets/{bucket}/sign/batch`             | Required (session).                     |
| `GET`  | `/api/buckets/{bucket}/files/{path}?token=...` | None — the token is the authentication. |
| `PUT`  | `/api/buckets/{bucket}/files/{path}?token=...` | None — the token is the authentication. |

Calling either `sign` endpoint without a valid session returns `401`.

## Access Control

Who may sign is governed by two independent layers, both using the shared `PermissionValueSchema` format (`all` | `authenticated` | role list).

### Per-Bucket Permissions

Set `sign` and `signUpload` on the bucket.

```yaml
buckets:
  - name: documents
    permissions:
      sign: authenticated
      signUpload: [admin, editor]
      download: authenticated
      delete: [admin]

  - name: public-assets
    public: true
    permissions:
      sign: all
      signUpload: [admin]
      download: all
```

| Behavior                                | Result                                    |
| --------------------------------------- | ----------------------------------------- |
| Caller matches `permissions.sign`       | Can generate download signed URLs.        |
| Caller matches `permissions.signUpload` | Can generate upload signed URLs.          |
| Caller does not match                   | `403 Forbidden`.                          |
| Bucket has no `permissions` block       | Only the `admin` role can sign (default). |

### Per-Role Storage Permissions

Roles can independently grant or revoke signing via `storage.sign` / `storage.signUpload`.

```yaml
auth:
  roles:
    - name: member
      permissions:
        storage:
          sign: true
          signUpload: false
    - name: viewer
      permissions:
        storage:
          sign: false
          signUpload: false
```

Admin has full signing rights by default. When no storage permissions are defined anywhere, signing defaults to admin-only.

## Attachment Field Integration

When a table [attachment field](/en/attachment-fields) points at a private file, the record API response automatically embeds a signed download URL (default 1-hour expiry):

```json
{
  "id": 1,
  "name": "Q1 Report",
  "attachment": {
    "path": "documents/q1-report.pdf",
    "filename": "q1-report.pdf",
    "size": 245760,
    "mimeType": "application/pdf",
    "signedUrl": "https://app.example.com/api/buckets/documents/files/documents/q1-report.pdf?token=...",
    "signedUrlExpiresAt": "2026-04-05T11:00:00Z"
  }
}
```

Public files include a direct URL with no token. Image attachments can carry [transform parameters](/en/image-transforms) inside the signed URL.

## Related Pages

- [Buckets Overview](/en/buckets-overview) — buckets, backends, and the `public` toggle.
- [File Operations](/en/file-operations) — direct upload, download, and delete.
- [Image Transforms](/en/image-transforms) — combine transforms with signed URLs.
- [Attachment Fields](/en/attachment-fields) — auto-signing in record responses.
- [Environment Variables](/en/env-vars) — public-path and access-level configuration.

# Image Transforms

Sovrium transforms stored images on the fly via URL query parameters. Width, height, format, quality, and crop are applied at request time using the [Sharp](https://sharp.pixelplumbing.com/) library — no external image service. Transformed outputs are cached, and the original file is never modified.

Transforms work on files from any [storage backend](/en/buckets-overview#storage-backends) (S3, local, bytea) and apply to the standard download endpoint:

```http
GET /api/buckets/{bucket}/files/photos/team-photo.jpg?width=400&height=300&fit=cover
```

## Resize

| Parameter | Type    | Range     | Default   | Description              |
| --------- | ------- | --------- | --------- | ------------------------ |
| `width`   | integer | 1–2500    | original  | Target width in pixels.  |
| `height`  | integer | 1–2500    | original  | Target height in pixels. |
| `fit`     | string  | see below | `contain` | Resize strategy.         |

Providing only one dimension auto-calculates the other, preserving aspect ratio. Values outside 1–2500 return `400 Bad Request`.

### Fit Modes

| Mode      | Behavior                                                        |
| --------- | --------------------------------------------------------------- |
| `contain` | Fit within the bounds, preserving aspect ratio (may letterbox). |
| `cover`   | Fill the bounds, preserving aspect ratio (may crop edges).      |
| `fill`    | Stretch to exact dimensions, ignoring aspect ratio.             |
| `inside`  | Like `contain`, but never upscales.                             |
| `outside` | Like `cover`, but never downscales.                             |

## Format Conversion

Convert to modern formats to cut file size and improve load times.

```http
# Explicit format
GET /api/buckets/{bucket}/files/photos/banner.png?format=webp

# Preserve source format, skip negotiation
GET /api/buckets/{bucket}/files/photos/banner.png?format=origin

# Automatic: negotiated from the Accept header
GET /api/buckets/{bucket}/files/photos/banner.png
Accept: image/avif,image/webp,image/*
```

| Format   | Extension | Use case                                        |
| -------- | --------- | ----------------------------------------------- |
| `avif`   | `.avif`   | Best compression, newest browsers.              |
| `webp`   | `.webp`   | Strong compression, broad modern support.       |
| `jpeg`   | `.jpg`    | Universal compatibility.                        |
| `png`    | `.png`    | Transparency, lossless.                         |
| `origin` | (source)  | Preserve source format, opt out of negotiation. |

Without a `format` parameter, the server negotiates the best supported format from the `Accept` header. The response `Content-Type` always reflects the actual output. An unsupported `format` value returns `400 Bad Request`.

:::callout
**AVIF is the eco default.** Sovrium's frugal-by-default posture sets `ECO_IMAGE_FORMAT=avif` so server-side transcoding favors the smallest payload. Operators opt out per [Ecoconception](/en/ecoconception); `format=origin` opts out per request.
:::

## Quality

```http
GET /api/buckets/{bucket}/files/photos/hero.jpg?quality=95
GET /api/buckets/{bucket}/files/photos/hero.jpg?width=100&quality=30
```

| Behavior                 | Result                              |
| ------------------------ | ----------------------------------- |
| `quality` accepts 1–100  | Higher values produce larger files. |
| Default                  | `80` when omitted.                  |
| Out of range             | `400 Bad Request`.                  |
| Applies to lossy formats | JPEG, WebP, AVIF.                   |
| Ignored for              | Lossless PNG output.                |

## Crop

Crop strategies only apply when `fit=cover`; otherwise the `crop` parameter is ignored.

```http
GET /api/buckets/{bucket}/files/photos/team.jpg?width=300&height=300&fit=cover&crop=entropy
GET /api/buckets/{bucket}/files/photos/team.jpg?width=300&height=300&fit=cover&crop=50,30
```

| Strategy  | Syntax                  | Description                                               |
| --------- | ----------------------- | --------------------------------------------------------- |
| center    | `crop=center` (default) | Crop from the center of the image.                        |
| entropy   | `crop=entropy`          | Smart crop using Shannon entropy.                         |
| attention | `crop=attention`        | Smart crop using Sharp's attention strategy.              |
| focal     | `crop=x,y`              | Crop around a focal point (`x`,`y` as 0–100 percentages). |

Focal-point values outside 0–100 return `400 Bad Request`.

## Presets

Define named transform presets once via an environment variable, then request them by name.

| Variable                    | Default | Purpose                       |
| --------------------------- | ------- | ----------------------------- |
| `STORAGE_TRANSFORM_PRESETS` | (none)  | JSON string of named presets. |

```bash
STORAGE_TRANSFORM_PRESETS='{"thumbnail":{"width":150,"height":150,"fit":"cover"},"preview":{"width":600,"quality":80},"avatar":{"width":64,"height":64,"fit":"cover","crop":"attention"}}'
```

```http
# Apply a preset
GET /api/buckets/{bucket}/files/photos/profile.jpg?preset=avatar

# Preset with overrides — explicit params win
GET /api/buckets/{bucket}/files/photos/profile.jpg?preset=thumbnail&quality=95
```

| Behavior                               | Result                                             |
| -------------------------------------- | -------------------------------------------------- |
| Known preset                           | Applies its width, height, fit, quality, and crop. |
| Explicit URL params alongside a preset | Override the preset values.                        |
| Unknown preset name                    | `400 Bad Request`.                                 |
| `preset` used when none configured     | `400 Bad Request`.                                 |

Preset names must be alphanumeric with hyphens (validated on startup).

## Caching

Transformed images are cached so repeated requests are served instantly.

| Mechanism       | Detail                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------- |
| Response header | `Cache-Control: public, max-age=31536000, immutable` (1 year, content-addressed).         |
| `ETag`          | Hash of the source file plus transform parameters.                                        |
| `If-None-Match` | A matching ETag returns `304 Not Modified`.                                               |
| Disk cache      | Stored in `STORAGE_TRANSFORM_CACHE_DIR`, keyed by `sha256(file_path + transform_params)`. |
| Eviction        | LRU, bounded by `STORAGE_TRANSFORM_CACHE_MAX_SIZE`.                                       |

| Variable                           | Default     | Purpose                          |
| ---------------------------------- | ----------- | -------------------------------- |
| `STORAGE_TRANSFORM_CACHE_DIR`      | OS temp dir | Directory for cached transforms. |
| `STORAGE_TRANSFORM_CACHE_MAX_SIZE` | `500`       | Maximum cache size in MB.        |

## Original Preservation

| Guarantee                  | Behavior                                                                |
| -------------------------- | ----------------------------------------------------------------------- |
| Source bytes are immutable | Original file is byte-identical after any number of transform requests. |
| No-param request           | Returns the unmodified original.                                        |
| Cache deletion             | Never affects original-file availability.                               |
| Non-image files (PDF, CSV) | Transform params return `400 Bad Request`.                              |
| Supported types            | JPEG, PNG, WebP, AVIF, GIF, TIFF, SVG (SVG is passed through).          |

## Related Pages

- [Buckets Overview](/en/buckets-overview) — backends and bucket configuration.
- [File Operations](/en/file-operations) — upload, download, delete.
- [Signed URLs](/en/signed-urls) — transforms can be embedded in signed URLs.
- [Attachment Fields](/en/attachment-fields) — thumbnail transforms on record attachments.
- [Ecoconception](/en/ecoconception) — `ECO_IMAGE_FORMAT` and frugal-by-default posture.
- [Environment Variables](/en/env-vars) — preset and cache configuration.

# Search Overview

Sovrium search is **not a standalone feature domain**. It extends the schemas you already use: tables declare _what_ is searchable (field weights, indexing), and page components declare _how_ search behaves (engine, debounce, highlighting, result display). There is no top-level `app.search` config — configuration lives where it is used.

The backend is built entirely on PostgreSQL: Full-Text Search (`tsvector`/`tsquery`) plus the `pg_trgm` extension for fuzzy, typo-tolerant matching. No Elasticsearch, no Algolia, no external service — search stays inside your own database, in keeping with Sovrium's digital-sovereignty principle.

:::callout
Two distinct search layers exist. **Record search** (this page) queries table data through the `search` data-source mode and the four engines below. **Public-pages search** indexes static page _content_ via the `pageSearch` component — see [search-components](/en/search-components#pagesearch). They are different features at different layers.
:::

## Search engines

A data source in `mode: 'search'` selects its backend with `searchEngine`. The same table can use different engines on different pages.

| Engine    | Where it runs            | Best for                                                                        |
| --------- | ------------------------ | ------------------------------------------------------------------------------- |
| `client`  | Browser JavaScript       | Small datasets already loaded in the page; instant, no round-trip. **Default.** |
| `fts`     | PostgreSQL FTS           | Server-side ranked relevance over indexed text; large datasets.                 |
| `trigram` | PostgreSQL `pg_trgm`     | Fuzzy matching and typo tolerance; partial/misspelled queries.                  |
| `hybrid`  | PostgreSQL FTS + trigram | FTS for relevance with a trigram fuzzy fallback; best of both.                  |

### `client` — browser filtering

JavaScript filtering in the browser. The records are already fetched, and the query narrows them in-memory. Zero server round-trip, but the whole result set must fit in the page. Use it for small reference lists and pickers.

```yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: client
    debounceMs: 300
```

### `fts` — PostgreSQL Full-Text Search

Server-side ranked search using `tsvector`/`tsquery`. Results come back ordered by relevance, weighted by each field's [`searchWeight`](/en/full-text-search#field-relevance-weights). Requires the searched fields to be `indexed: true`. Use it for large, text-heavy datasets where ranking matters.

```yaml
- type: data-table
  dataSource:
    table: articles
    mode: search
    searchFields: [title, body]
    searchEngine: fts
    debounceMs: 300
    limit: 20
```

### `trigram` — fuzzy matching

Uses the `pg_trgm` extension to match on character trigrams, tolerating typos and partial words. Ideal when users misspell or type fragments (e.g. `prodct` still matches `product`). See [full-text-search](/en/full-text-search#trigram-fuzzy-matching) for indexing details.

```yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name]
    searchEngine: trigram
```

### `hybrid` — relevance plus fuzziness

Combines FTS for relevance ranking with trigram as a fuzzy fallback, so exact and ranked matches surface first while misspelled queries still return results. The most forgiving engine for end-user-facing search.

```yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: hybrid
    debounceMs: 300
    limit: 50
```

:::callout
`searchEngine` defaults to `client`. The `fts`, `trigram`, and `hybrid` engines run in PostgreSQL only — they require an indexed corpus. On SQLite, server-side ranking falls back to a simpler match; design index-backed search against Postgres. See [full-text-search](/en/full-text-search#postgresql-vs-sqlite).
:::

## The `search` data-source mode

Search is one of three data-source modes (`list`, `single`, `search`). Setting `mode: 'search'` turns a data-bound component into an interactive, debounced search experience.

| Property       | Description                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------- |
| `table`        | Table to query (validated against `app.tables`).                                               |
| `searchFields` | Array (≥ 1) of field names to search across. Required for search mode.                         |
| `searchEngine` | Backend: `client` (default), `fts`, `trigram`, or `hybrid`.                                    |
| `debounceMs`   | Debounce delay for the search input in milliseconds (integer ≥ 0), e.g. `300`, `500`.          |
| `limit`        | Maximum number of results to return (integer ≥ 1), e.g. `10`, `20`, `50`.                      |
| `bindTo`       | ID of a `searchInput` component whose query drives this data source (cross-component binding). |
| `filter`       | Filter conditions (AND logic) applied alongside the search query.                              |
| `sort`         | Sort rules applied to results.                                                                 |
| `refreshMode`  | How results refresh after load: `none` (default), `poll`, or `realtime`.                       |

```yaml
# Interactive search with debounce and a result limit
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: hybrid
    debounceMs: 300
    limit: 20
```

For static filtering and ordering of non-search results, use the `list` mode with `filter`/`sort` instead — see [records-filtering-sorting](/en/records-filtering-sorting).

## Choosing an approach

| Need                                                | Use                                                                     |
| --------------------------------------------------- | ----------------------------------------------------------------------- |
| Narrow a small list already on the page             | `searchEngine: client`                                                  |
| Rank large text datasets by relevance               | `searchEngine: fts` + `indexed: true` + `searchWeight`                  |
| Tolerate typos and partial words                    | `searchEngine: trigram`                                                 |
| Both relevance ranking and typo tolerance           | `searchEngine: hybrid`                                                  |
| Search static page content site-wide                | `pageSearch` component — see [search-components](/en/search-components) |
| Define which fields are searchable and how weighted | Field-level config — see [full-text-search](/en/full-text-search)       |

## Related

- [Full-Text Search](/en/full-text-search) — field-level `fullTextSearch`, `indexed`, and `searchWeight`.
- [Search Components](/en/search-components) — `searchInput`, `pageSearch`, `list`, `command`, and toolbar search.
- [Text Fields](/en/text-fields) — the `rich-text` field's `fullTextSearch` flag.
- [Tables Overview](/en/tables-overview) — base field properties including `indexed` and `searchWeight`.

# Full-Text Search

Tables declare _what_ is searchable. Three field-level properties control how a field participates in search: `indexed` makes it queryable, `searchWeight` ranks its relevance, and `fullTextSearch` (on `rich-text`) enables FTS indexing for formatted content. Components then pick the engine that consumes these — see [search-overview](/en/search-overview#search-engines).

## Field properties

| Property         | Applies to      | Description                                                                                                        |
| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ |
| `indexed`        | All field types | Boolean. Creates a database index on the field. Required for `fts`, `trigram`, and `hybrid` engines.               |
| `searchWeight`   | All field types | `A`–`D`. PostgreSQL FTS relevance weight. Only effective when `indexed: true` and the engine is `fts` or `hybrid`. |
| `fullTextSearch` | `rich-text`     | Boolean. Enables full-text-search indexing for the field's formatted content.                                      |

These extend the [base field properties](/en/tables-overview#base-field-properties) shared by every field type.

## Field relevance weights

`searchWeight` maps directly to PostgreSQL FTS weights, ordering how strongly a match in each field influences the relevance rank. A title match outranks a body match.

| Weight | Relevance | Typical fields                       |
| ------ | --------- | ------------------------------------ |
| `A`    | Highest   | Title, name, headline.               |
| `B`    | High      | Description, summary, excerpt.       |
| `C`    | Medium    | Tags, categories, labels.            |
| `D`    | Lowest    | Internal notes, metadata, footnotes. |

```yaml
tables:
  - name: articles
    fields:
      - { id: 1, name: title, type: single-line-text, indexed: true, searchWeight: A }
      - { id: 2, name: summary, type: long-text, indexed: true, searchWeight: B }
      - { id: 3, name: tags, type: single-line-text, indexed: true, searchWeight: C }
      - { id: 4, name: body, type: rich-text, indexed: true, fullTextSearch: true, searchWeight: B }
```

:::callout
`searchWeight` is only meaningful when the field is `indexed: true` **and** a data source queries it with `searchEngine: 'fts'` or `'hybrid'`. With `client` or `trigram` engines the weight is ignored.
:::

## `fullTextSearch` on rich text

The `rich-text` field stores formatted HTML. Setting `fullTextSearch: true` enables full-text-search indexing of its text content so the field can participate in `fts`/`hybrid` queries alongside plain-text fields.

```yaml
- id: 5
  name: article_content
  type: rich-text
  required: true
  maxLength: 10000
  fullTextSearch: true
  searchWeight: B
  toolbar: [bold, italic, link, heading, list]
```

Plain `long-text` and `single-line-text` fields do not need `fullTextSearch` — set `indexed: true` and a `searchWeight`, and they are FTS-ready. The `fullTextSearch` flag exists specifically for `rich-text` because its stored value is HTML markup rather than plain text. See [text-fields](/en/text-fields#rich-text) for the full `rich-text` property set.

## PostgreSQL vs SQLite

| Aspect             | PostgreSQL                                            | SQLite                                                 |
| ------------------ | ----------------------------------------------------- | ------------------------------------------------------ |
| FTS engine         | Native `tsvector`/`tsquery` with weighted ranking.    | Simpler matching; weighted ranking is reduced.         |
| Fuzzy matching     | `pg_trgm` extension (trigram, typo-tolerant).         | Not available — trigram engine targets Postgres.       |
| `searchWeight` A–D | Fully honored in relevance ranking.                   | Best-effort; weight ordering may be approximate.       |
| Recommendation     | Use for index-backed `fts`/`trigram`/`hybrid` search. | Zero-config default; design ranked search on Postgres. |

:::callout
SQLite is Sovrium's zero-config default database. For production search that depends on ranked relevance (`searchWeight`) or fuzzy matching (`trigram`/`hybrid`), run against PostgreSQL where `tsvector` and `pg_trgm` are available.
:::

## Trigram fuzzy matching

The `pg_trgm` extension breaks text into three-character sequences (trigrams) and matches on overlap, tolerating typos and partial words. This powers the `trigram` and `hybrid` engines. A field used for fuzzy search should be `indexed: true` so PostgreSQL can build a trigram (GIN/GiST) index.

```yaml
tables:
  - name: products
    fields:
      - { id: 1, name: name, type: single-line-text, indexed: true, searchWeight: A }
```

```yaml
# Component side — fuzzy matching on the indexed field
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name]
    searchEngine: trigram
```

A query of `prodct` still matches `product`; `lapto` matches `laptop`. Pair trigram with FTS using `searchEngine: 'hybrid'` to keep relevance ranking for exact terms while retaining typo tolerance for the rest.

## Related

- [Search Overview](/en/search-overview) — the four search engines and the `search` data-source mode.
- [Search Components](/en/search-components) — `searchInput`, `list`, `pageSearch`, and toolbar search.
- [Text Fields](/en/text-fields) — `rich-text`, `long-text`, and the `fullTextSearch` flag.
- [Tables Overview](/en/tables-overview) — `indexed`, `searchWeight`, and other base field properties.

# Search Components

Where tables declare _what_ is searchable and engines declare _how_ a query runs (see [search-overview](/en/search-overview)), components are _where_ search appears on the page. Sovrium provides five complementary pieces: a `searchInput` that drives a query, a `list` that renders results, a `pageSearch` that indexes static page content, a `command` palette for keyboard-driven navigation, and toolbar search built into data components.

| Component        | Purpose                                                                        |
| ---------------- | ------------------------------------------------------------------------------ |
| `searchInput`    | Standalone search box that drives another component via `dataSource.bindTo`.   |
| `list`           | Search-first result display with item templates, highlighting, and pagination. |
| `pageSearch`     | Site-wide static search over public page content (build/start-time index).     |
| `command`        | Command palette (⌘K-style) for grouped, keyboard-driven actions.               |
| toolbar `search` | In-component search bar on `data-table`, kanban, calendar, etc.                |

## `searchInput`

A standalone search box. On its own it renders an accessible input; bound to a data source it becomes the query driver for a sibling component. Pair it with a `list` (or `data-table`) whose data source sets `bindTo` to the input's `id`.

| Property     | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| `id`         | Identifier other components reference via `dataSource.bindTo`.         |
| `visibility` | Standard visibility controls (shared across components).               |
| `i18n`       | Standard internationalization fields (translatable label/placeholder). |

```yaml
components:
  # 1. The input drives the query
  - type: searchInput
    id: product-query

  # 2. The list consumes it via bindTo
  - type: list
    dataSource:
      table: products
      mode: search
      searchFields: [name, description]
      searchEngine: hybrid
      debounceMs: 300
      bindTo: product-query
    listDisplay:
      itemTemplate:
        title: '$record.name'
        subtitle: '$record.description'
      highlight: true
```

:::callout
`debounceMs` lives on the **data source** of the consuming component, not on `searchInput` — the input emits keystrokes and the bound data source debounces them before querying. See [search-overview](/en/search-overview#the-search-data-source-mode).
:::

## `list` — result display

The `list` component is designed as a search-first display: the natural companion for `searchInput`. It renders each record through an item template with optional highlighting, dividers, and load-more pagination.

| Property                | Description                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `itemTemplate.title`    | Primary text via a `$record.*` reference (e.g. `$record.name`).                                                     |
| `itemTemplate.subtitle` | Secondary text (e.g. `$record.description`).                                                                        |
| `itemTemplate.image`    | Image URL (e.g. `$record.thumbnail`).                                                                               |
| `itemTemplate.badge`    | Badge text (e.g. `$record.category`).                                                                               |
| `itemTemplate.metadata` | Array of `{ field, format }` shown in the item footer (`currency`, `relative-date`, `badge`, `text`, `short-date`). |
| `emptyMessage`          | Message shown when no results match.                                                                                |
| `loadMore`              | `button` (Load More button) or `infinite` (load on scroll).                                                         |
| `highlight`             | Boolean. Highlight matched search terms in item text (default `false`).                                             |
| `divider`               | Boolean. Show visual dividers between items (default `false`).                                                      |
| `maxItems`              | Maximum number of items to display (integer ≥ 1).                                                                   |

```yaml
- type: list
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    bindTo: product-query
  listDisplay:
    itemTemplate:
      title: '$record.name'
      subtitle: '$record.description'
      image: '$record.thumbnail'
      badge: '$record.category'
      metadata:
        - field: price
          format: currency
    emptyMessage: No products found
    loadMore: infinite
    highlight: true
    divider: true
    maxItems: 50
```

## `pageSearch` — static page index

A site-wide search component that indexes **public pages** (`access` missing or `access: 'all'`) at `sovrium build` time and `sovrium start` boot. The index is a JSON file plus a tiny client runtime under `<outputDir>/sovrium-search/`, served by the public-dir route. This is a different layer from record search — it searches page _content_, not table rows.

| Property      | Description                                              |
| ------------- | -------------------------------------------------------- |
| `placeholder` | Placeholder text shown in the search input.              |
| `maxResults`  | Maximum number of results to display (positive integer). |
| `visibility`  | Standard visibility controls.                            |
| `i18n`        | Standard internationalization fields.                    |

```yaml
pages:
  - id: home
    name: home
    path: /
    components:
      - type: pageSearch
        placeholder: Search the site...
        maxResults: 10
```

:::callout
`pageSearch` is **self-activating**: the moment a `type: 'pageSearch'` component appears anywhere in `app.pages[].components[]`, `sovrium build` and `sovrium start` emit the static search index. No env var, no top-level `app.search` config. The indexer crawls public pages only — pages with `access: 'authenticated'`, role arrays, or `require`-based access are excluded from the index.
:::

## `command` — command palette

A ⌘K-style command palette for keyboard-driven navigation and actions. Commands are organized into groups, each surfacing searchable entries the user filters by typing.

| Property        | Description                                           |
| --------------- | ----------------------------------------------------- |
| `commandGroups` | Array (≥ 1) of grouped commands shown in the palette. |
| `visibility`    | Standard visibility controls.                         |
| `i18n`          | Standard internationalization fields.                 |

```yaml
- type: command
  commandGroups:
    - heading: Navigation
      commands:
        - label: Go to Dashboard
          href: /dashboard
        - label: Go to Settings
          href: /settings
    - heading: Actions
      commands:
        - label: New Product
          href: /products/new
```

## Toolbar search

Data components expose an in-component search bar through their toolbar. On a `data-table`, set `toolbar.search: true` to render a global search input over the bound rows — a quick filter without a separate `searchInput`.

| Toolbar flag | Description                   |
| ------------ | ----------------------------- |
| `search`     | Show the global search input. |
| `filters`    | Show the filter builder.      |
| `sort`       | Show the sort builder.        |

```yaml
- type: data-table
  dataSource:
    table: orders
    mode: search
    searchFields: [customer, reference]
  toolbar:
    search: true
    filters: true
    sort: true
```

Kanban and calendar components share a `search` configuration for their own in-component search bar via the same pattern.

## Highlighting and debounce

- **Highlighting** — set `highlight: true` on `list` (`listDisplay.highlight`) to wrap matched terms in result text. Off by default.
- **Debounce** — set `debounceMs` on the data source (e.g. `300`) so the query fires only after the user pauses typing, preventing a request per keystroke.

These work together: a `searchInput` emits keystrokes, the bound data source debounces and queries, and the `list` highlights matches in the rendered results.

## Related

- [Search Overview](/en/search-overview) — engines and the `search` data-source mode.
- [Full-Text Search](/en/full-text-search) — field `indexed`, `searchWeight`, and `fullTextSearch`.
- [Data Components](/en/data-components) — `data-table`, kanban, calendar, and their toolbars.
- [Content Components](/en/content-components) — text, media, and structural page content.
- [Records: Filtering & Sorting](/en/records-filtering-sorting) — non-search list filtering and ordering.

# AI Overview

Sovrium ships a complete, self-hostable AI layer. Every capability is opt-in and governed by the platform's existing RBAC and field-level permissions — AI never bypasses the security model. The AI layer is **disabled by default**: nothing AI-related runs until you set the `AI_PROVIDER` environment variable.

The design philosophy mirrors the rest of the platform: **operators control infrastructure via environment variables, schema authors declare intent in config.** Which provider answers a call, where embeddings live, and whether the MCP server mounts are operator concerns (`AI_PROVIDER`, `MCP_ENABLED`, …). Which tables an agent may touch and which entities are AI-eligible are schema-author concerns (`agents[]`, `aiAccess`).

## The AI Ecosystem

Eight building blocks compose into the full AI experience.

| Capability          | What it does                                                                                              | Docs                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **Providers**       | Pick the LLM and embedding backend (Anthropic, OpenAI, Mistral, Gemini, local Ollama, OpenAI-compatible). | [AI Providers](/en/ai-providers)       |
| **Eco routing**     | Frugal-by-default provider precedence — prefer a local model, fall back to cloud.                         | [AI Eco Routing](/en/ai-eco-routing)   |
| **AI fields**       | Computed table columns that summarize, categorize, extract, translate, etc. using an LLM.                 | [AI Fields](/en/ai-fields)             |
| **AI chat**         | A conversational interface over your data — query, mutate, and trigger automations in natural language.   | [AI Chat](/en/ai-chat)                 |
| **AI agents**       | Autonomous virtual users with scoped tools, approval gates, schedules, and operational limits.            | [AI Agents](/en/ai-agents)             |
| **RAG knowledge**   | Ground answers in your tables and documents via vector embeddings and semantic search.                    | [AI RAG](/en/ai-rag)                   |
| **Agent memory**    | Conversation history, RAG-backed knowledge, and persistent learned facts per agent.                       | [AI Memory](/en/ai-memory)             |
| **MCP integration** | Expose Sovrium as an MCP server, and let agents consume external MCP tools.                               | [MCP Integration](/en/mcp-integration) |

:::callout
**AI fields are documented under Tables.** The seven computed field types (`ai-summary`, `ai-categorize`, `ai-extract`, `ai-sentiment`, `ai-tag`, `ai-translate`, `ai-generate`) live on table records and are covered in [AI Fields](/en/ai-fields). This section covers the conversational, agentic, and interoperability layers.
:::

## Configuration Philosophy

AI behaves like the database (`DATABASE_URL`), storage (`STORAGE_PROVIDER`), and auth (`AUTH_SECRET`) layers: **infrastructure is env-var config, intent is schema.**

| Concern                                   | Controlled by | Where                                            |
| ----------------------------------------- | ------------- | ------------------------------------------------ |
| Which provider/model/key to use           | Operator      | `AI_PROVIDER`, `AI_MODEL`, `AI_API_KEY` env vars |
| Provider routing precedence (eco)         | Operator      | `ECO_AI_PROVIDER_PRECEDENCE` env var             |
| Whether the MCP server mounts             | Operator      | `MCP_ENABLED`, `MCP_TRANSPORT`, … env vars       |
| Which entities are AI-eligible            | Schema author | `aiAccess` on tables / automations / actions     |
| Agent identity, tools, approval, schedule | Schema author | `app.agents[]`                                   |
| AI computed columns                       | Schema author | `type: ai-*` fields on a table                   |

The single master switch is `AI_PROVIDER`. When unset (or blanked), the entire AI layer is silently disabled — AI fields skip computation, the chat endpoint returns a disabled response, agents do not run, and RAG/embedding infrastructure is not provisioned. No errors are thrown at boot; AI simply stays dormant until configured.

```bash
# Minimal enablement: a local Ollama model (no API key, no cloud).
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
```

```bash
# A cloud provider.
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
AI_MODEL=claude-sonnet-4-5
```

## How the Pieces Fit Together

```
                         AI_PROVIDER (master switch)
                                  │
        ┌─────────────────┬───────┴────────┬──────────────────┐
        ▼                 ▼                ▼                  ▼
   AI Fields          AI Chat          AI Agents          MCP Server
 (computed cols)   (conversation)   (virtual users)    (external clients)
        │                 │                │                  │
        │                 └──── tools ─────┤                  │
        │                                  │                  │
        ▼                                  ▼                  ▼
                          RBAC + field-level permissions (always enforced)
                                  │
                                  ▼
                    RAG knowledge + agent memory (pgvector / SQLite BLOB)
```

Every AI surface — fields, chat, agents, MCP — funnels through the same authorization layer. An agent inherits its role's permissions; a chat user can only see records their session permits; an MCP client is bounded by its token's role. There is no privileged AI bypass.

## Prerequisites

| Requirement       | Why                                                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `AI_PROVIDER` set | Master switch. Without it the whole AI layer is dormant.                                                         |
| `app.auth` (most) | Agents are stored as auth users; chat and MCP RBAC require roles. AI fields work without auth.                   |
| pgvector / SQLite | RAG embeddings need PostgreSQL + pgvector **or** SQLite (Float32 BLOB + app-side cosine). No external vector DB. |

## Related Pages

- [AI Providers](/en/ai-providers) — choose and configure the LLM backend.
- [AI Eco Routing](/en/ai-eco-routing) — local-first provider precedence.
- [AI Fields](/en/ai-fields) — computed columns powered by an LLM.
- [AI Chat](/en/ai-chat) — conversational data interaction.
- [AI Agents](/en/ai-agents) — autonomous virtual users.
- [AI RAG](/en/ai-rag) — retrieval-augmented knowledge.
- [AI Memory](/en/ai-memory) — agent conversation, knowledge, and facts.
- [MCP Integration](/en/mcp-integration) — Sovrium as MCP server and client.
- [Environment Variables](/en/env-vars) — full env-var reference.

# AI Providers

The AI provider is the LLM (and embedding) backend that powers every AI capability. You select it with environment variables — never in the app schema. Setting `AI_PROVIDER` is the master switch that activates the entire AI layer; leaving it unset keeps AI dormant.

```bash
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
AI_MODEL=claude-sonnet-4-5
```

## Supported Providers

| Provider              | `AI_PROVIDER` value       | API key required | Base URL required | Notes                                                               |
| --------------------- | ------------------------- | ---------------- | ----------------- | ------------------------------------------------------------------- |
| **Anthropic**         | `anthropic`               | Yes              | No                | Claude models. Default model: `claude-sonnet-4-5`.                  |
| **OpenAI**            | `openai`                  | Yes              | No                | GPT / o-series models. Default model: `gpt-4o`.                     |
| **Mistral**           | `mistral`                 | Yes              | No                | Mistral / Codestral. Default model: `mistral-large-latest`.         |
| **Google Gemini**     | `google` (alias `gemini`) | Yes              | No                | Gemini models. Default model: `gemini-2.0-flash`.                   |
| **Ollama**            | `ollama`                  | No               | Yes               | Local, self-hosted. No key needed. Default model: `llama3.1`.       |
| **OpenAI-compatible** | `openai-compatible`       | Yes              | Yes               | Any endpoint that speaks the OpenAI API. Set `AI_MODEL` explicitly. |

:::callout
**`gemini` is an accepted alias** for the canonical `google` value. Both resolve to Google Gemini; `google` is preferred in new configs.
:::

## Core Environment Variables

| Variable                  | Description                                                                                     | Example                  |
| ------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------ |
| `AI_PROVIDER`             | Provider identifier. Master switch — unset disables all AI.                                     | `anthropic`              |
| `AI_API_KEY`              | API key for cloud providers. Not used by Ollama.                                                | `sk-ant-...`             |
| `AI_BASE_URL`             | Endpoint URL. Required for Ollama and OpenAI-compatible; cloud providers use built-in defaults. | `http://localhost:11434` |
| `AI_MODEL`                | Default LLM model. Falls back to the provider's recommended default when unset.                 | `claude-sonnet-4-5`      |
| `AI_TEMPERATURE`          | Default sampling temperature, `0`–`1` inclusive.                                                | `0.7`                    |
| `AI_MAX_TOKENS`           | Default maximum output tokens (positive integer).                                               | `4096`                   |
| `AI_EMBEDDING_MODEL`      | Embedding model for RAG. Defaults to the provider's embedding model.                            | `text-embedding-3-small` |
| `AI_EMBEDDING_DIMENSIONS` | Vector dimensions (must match the embedding model's output).                                    | `1536`                   |

An empty or whitespace-only value is treated identically to unset — operators who blank out `AI_PROVIDER` intend to disable it, not supply an invalid value. The server boots cleanly with AI disabled rather than throwing a parse error.

## Provider-Specific Key & URL Aliases

In addition to the generic `AI_API_KEY` / `AI_BASE_URL`, each cloud provider accepts a conventional alias env var. The generic `AI_*` value always takes precedence; the alias is the fallback.

| Provider          | API-key alias       | Base-URL alias       |
| ----------------- | ------------------- | -------------------- |
| Anthropic         | `ANTHROPIC_API_KEY` | —                    |
| OpenAI            | `OPENAI_API_KEY`    | —                    |
| Mistral           | `MISTRAL_API_KEY`   | —                    |
| Google Gemini     | `GOOGLE_API_KEY`    | —                    |
| Ollama            | — (no key)          | `OLLAMA_BASE_URL`    |
| OpenAI-compatible | (uses `AI_API_KEY`) | (uses `AI_BASE_URL`) |

## Default Models

When `AI_MODEL` is unset, each provider resolves to a sensible default:

| Provider          | Default model           |
| ----------------- | ----------------------- |
| Anthropic         | `claude-sonnet-4-5`     |
| OpenAI            | `gpt-4o`                |
| Mistral           | `mistral-large-latest`  |
| Google Gemini     | `gemini-2.0-flash`      |
| Ollama            | `llama3.1`              |
| OpenAI-compatible | _none_ — set `AI_MODEL` |

OpenAI-compatible endpoints point at an arbitrary backend, so there is no universal default model — you must set `AI_MODEL` explicitly.

## Model Validation

For providers with a known catalogue (Anthropic, OpenAI, Mistral, Google), Sovrium emits a **non-fatal startup warning** when `AI_MODEL` (or an agent's `model` override) does not match a recognized model — typically a cross-provider mix-up (`gpt-4o` on `anthropic`) or a typo (`claud-sonet`). This is a warning, not an error; the server still starts.

Ollama and OpenAI-compatible providers have **open-ended catalogues** (locally installed models, arbitrary endpoints), so model-name validation is skipped entirely for them.

## Configuration Examples

```bash
# Self-hosted, zero-cost, frugal-by-default: local Ollama.
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434     # or OLLAMA_BASE_URL
AI_MODEL=llama3.1
AI_EMBEDDING_MODEL=nomic-embed-text
```

```bash
# Anthropic with a temperature override.
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...           # or AI_API_KEY
AI_MODEL=claude-sonnet-4-5
AI_TEMPERATURE=0.3
AI_MAX_TOKENS=4096
```

```bash
# An OpenAI-compatible gateway (vLLM, LiteLLM, Azure OpenAI, etc.).
AI_PROVIDER=openai-compatible
AI_BASE_URL=https://my-gateway.internal/v1
AI_API_KEY=...
AI_MODEL=my-deployed-model             # required — no default
```

:::callout
**Per-agent overrides.** Any agent in `app.agents[]` can override `model`, `temperature`, and `maxTokens` for itself, falling back to these env-var defaults when omitted. See [AI Agents](/en/ai-agents).
:::

## Related Pages

- [AI Overview](/en/ai-overview) — the full AI ecosystem map.
- [AI Eco Routing](/en/ai-eco-routing) — local-first provider precedence.
- [AI Agents](/en/ai-agents) — per-agent model overrides.
- [AI RAG](/en/ai-rag) — embedding model and vector storage.
- [Environment Variables](/en/env-vars) — complete env-var reference.

# AI Eco Routing

Sovrium treats environmental footprint as a first-class platform property. AI inference is one of the most resource-intensive operations a platform can perform, so Sovrium routes AI calls **local-first by default**: when a local model (Ollama) is reachable, it answers; only when it is not does the call fall back to a configured cloud provider.

This is controlled by a single operator env var — `ECO_AI_PROVIDER_PRECEDENCE` — never by the app schema. Like every `ECO_*` variable, its default is the eco-aligned setting; operators opt _out_, never in.

```bash
ECO_AI_PROVIDER_PRECEDENCE=local-first   # the default — usually omit it entirely
AI_PROVIDER=anthropic                    # cloud fallback target
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434   # local provider endpoint
```

## Precedence Modes

| Value         | Behavior                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `local-first` | **(default)** Prefer a reachable local Ollama; fall back to the configured cloud `AI_PROVIDER` when Ollama is unreachable.     |
| `cloud-first` | Use the configured cloud provider; use a reachable Ollama only when no cloud provider is configured.                           |
| `local-only`  | Use a local provider exclusively. AI calls have no cloud fallback — when no reachable Ollama is configured, AI is unavailable. |

An unset, empty, or unrecognized value resolves to the eco-aligned default, `local-first`.

## How Routing Resolves

The resolver combines three inputs: the active precedence, whether an Ollama endpoint is **configured** (via `OLLAMA_BASE_URL`, or `AI_BASE_URL` when `AI_PROVIDER=ollama`), and whether the runtime's reachability probe found Ollama **usable** (configured _and_ responding).

| Precedence    | Ollama usable | Cloud configured | Routes to     | Notes                                                                       |
| ------------- | ------------- | ---------------- | ------------- | --------------------------------------------------------------------------- |
| `local-first` | yes           | —                | Ollama        | Preferred local path.                                                       |
| `local-first` | no            | yes              | cloud         | Fallback. Flagged with a reason when Ollama was configured but unreachable. |
| `local-first` | no            | no               | Ollama / none | Disabled when no provider is configured at all.                             |
| `cloud-first` | —             | yes              | cloud         | Cloud always wins when configured.                                          |
| `cloud-first` | yes           | no               | Ollama        | Local used only because no cloud is configured.                             |
| `local-only`  | yes           | —                | Ollama        | Local exclusively.                                                          |
| `local-only`  | no            | —                | none          | No fallback — AI unavailable until a reachable Ollama exists.               |

:::callout
**Reachability is probed, not assumed.** The runtime checks whether the configured Ollama endpoint actually responds before routing to it. Under `local-first`, when Ollama is _configured but unreachable_, the fallback to cloud is recorded with an operator-facing reason; when Ollama was never configured, the fallback happens silently.
:::

## Observability

The active eco-routing decision is surfaced on the health endpoint (`GET /api/health`, under `body.ai`):

| Field              | Meaning                                                                            |
| ------------------ | ---------------------------------------------------------------------------------- |
| `precedence`       | The active `ECO_AI_PROVIDER_PRECEDENCE` value.                                     |
| `resolvedProvider` | The canonical provider AI calls are routed to (or absent when AI is disabled).     |
| `ollamaReachable`  | Whether the local Ollama probe succeeded.                                          |
| `configured`       | The raw `AI_PROVIDER` value.                                                       |
| `fallbackReason`   | Why the resolver fell back to a non-preferred provider (present only on fallback). |

This makes routing auditable: operators can confirm whether a deployment is actually running on its local model or quietly burning cloud tokens.

## Configuration Examples

```bash
# Frugal default: local Ollama with an Anthropic safety net.
# (ECO_AI_PROVIDER_PRECEDENCE=local-first is the default — shown for clarity.)
ECO_AI_PROVIDER_PRECEDENCE=local-first
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434
AI_MODEL=claude-sonnet-4-5
```

```bash
# Strict local-only deployment — no data ever leaves the host.
ECO_AI_PROVIDER_PRECEDENCE=local-only
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
```

```bash
# Quality-first: always use the cloud provider.
ECO_AI_PROVIDER_PRECEDENCE=cloud-first
AI_PROVIDER=openai
OPENAI_API_KEY=...
AI_MODEL=gpt-4o
```

## Related Pages

- [AI Providers](/en/ai-providers) — provider, key, and base-URL configuration.
- [AI Overview](/en/ai-overview) — the AI ecosystem and configuration philosophy.
- [Environment Variables](/en/env-vars) — complete `ECO_*` and `AI_*` reference.

# AI Chat

AI Chat is a conversational interface over your application data. Users ask questions and issue commands in natural language; the platform translates them into permitted queries, mutations, and automation triggers, then returns a structured reply. It is available both as a REST endpoint (`POST /api/ai/chat`) and as an embeddable page component (`type: ai-chat`).

Chat is **native** once `AI_PROVIDER` is configured — the platform auto-detects every table and field, so no per-table YAML is needed for query support. All actions taken through chat are governed by the requesting user's RBAC and field-level permissions and are written to the activity log for full auditability.

## What Chat Can and Cannot Do

| Chat **can**                                                   | Chat **cannot**                                        |
| -------------------------------------------------------------- | ------------------------------------------------------ |
| Query records across tables via natural language               | Modify table schemas (add/remove fields, change types) |
| Create, update, and delete records (destructive ops confirmed) | Create or modify automations                           |
| Trigger manual-trigger automations the user may run            | Access records outside the user's RBAC permissions     |
| Maintain conversation context within a session                 | Bypass field-level permissions                         |

## Architecture

```
User Message
    │
    ▼
POST /api/ai/chat ──▶ Resolve Agent (or default AI) ──▶ Inject Context
    │                                                        │
    │   ┌────────────────────────────────────────────────────┘
    ▼   ▼
AI Provider ──▶ Tool Calls (query, mutate, trigger) ──▶ RBAC check ──▶ Activity Log
    │
    ▼
Structured Response (reply text + actions taken)
```

Chat resolves an agent (when one is named) or falls back to the default AI provider. The model interacts with data exclusively through **tool calls** — structured operations Sovrium executes after an RBAC check — rather than fabricating data in free text.

## Using Chat as a Page Component

The `ai-chat` component embeds a chat panel into any page.

```yaml
pages:
  - name: dashboard
    path: /dashboard
    components:
      - type: ai-chat
        agent: support-agent # optional — falls back to default AI provider
        placeholder: Ask about your tickets...
        chatHeight: 600
        showHistory: true
        allowAttachments: false
```

| Property           | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `agent`            | Agent name from `app.agents[]`. Omit to use the default AI provider. |
| `placeholder`      | Placeholder text for the chat input field.                           |
| `chatHeight`       | Chat container height in pixels (must be > 0).                       |
| `showHistory`      | Whether to show previous conversation history on load.               |
| `allowAttachments` | Whether to allow file attachments in the chat.                       |

## Using the REST API

```http
POST /api/ai/chat
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "message": "How many open tickets are there?",
  "context": { "table": "tickets" },
  "sessionId": "sess_abc123"
}
```

```json
{
  "reply": "There are 42 open tickets — 5 critical, 12 high, 18 medium, 7 low.",
  "actions": [
    {
      "type": "query",
      "table": "tickets",
      "description": "Counted tickets where status = 'open', grouped by priority"
    }
  ],
  "sessionId": "sess_abc123"
}
```

## Record Queries

When `AI_PROVIDER` is set, the chat API natively translates natural-language questions into SQL/API queries against the user's **permitted** tables, executes them, and formats the result into the conversation. No configuration is required — the platform introspects the schema automatically. Queries never reach tables or fields the requesting role cannot read.

## Record Mutations

Chat can create, update, and delete records on the user's behalf. Mutations honor field-level permissions (a role that cannot write a field cannot set it through chat), and **destructive operations require confirmation** before they execute. Every mutation is recorded in the activity log alongside the user who initiated it.

## Triggering Automations

Chat can invoke **manual-trigger** automations the user is permitted to run, then report the result back in the conversation. Chat cannot run automations of other trigger types, nor create or edit automation definitions.

## Tool Calling

Chat is built on function/tool calling. Sovrium presents the model a set of tool definitions (query, mutate, trigger); the model returns a `tool_call`; Sovrium executes it **after an RBAC check** and feeds the result back to the model, which then composes the final reply. Structured tool calling — rather than free-text data generation — is what keeps chat grounded and auditable.

```
User Message → AI Provider (with tool definitions)
                    │
                    ▼
              AI returns tool_call
                    │
                    ▼
         Sovrium executes tool (RBAC checked)
                    │
                    ▼
         Tool result sent back to AI
                    │
                    ▼
              AI returns final text response
```

## Streaming Responses

Chat supports Server-Sent Events (SSE) streaming so users see progressive text generation instead of waiting for the full response.

| Behavior            | Detail                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| Chunk delivery      | Partial message content arrives as SSE chunks, forwarded in real time as the provider emits them. |
| Completion marker   | The final SSE event carries a `[DONE]` marker; the complete message is assembled from all chunks. |
| Persistence         | Streamed messages are persisted to conversation history once complete.                            |
| Permissions         | Streaming enforces the same RBAC as non-streaming chat.                                           |
| Time-to-first-chunk | A `504` is returned when the provider sends no first chunk before `AI_CHAT_STREAM_TIMEOUT`.       |
| Connection drop     | Handled gracefully — a partial response is discarded if the connection drops before completion.   |

## Rate Limiting

Per-user rate limits protect the AI provider from being overwhelmed and cap cost. Limits are configured via environment variables, not the app schema.

| Variable                 | Description                                             | Default  |
| ------------------------ | ------------------------------------------------------- | -------- |
| `AI_CHAT_RATE_LIMIT`     | Messages allowed per window, per user.                  | `60`     |
| `AI_CHAT_RATE_WINDOW`    | Rate-limit window length.                               | 1 minute |
| `AI_CHAT_STREAM_TIMEOUT` | Deadline for time-to-first-chunk on streaming requests. | —        |

A rate-limited request returns `429` with a `Retry-After` header and remaining-quota information. Each user has an independent counter, and the window resets after it expires. Agent API calls respect the same limits as user chat.

## Error Handling

When the AI provider fails, chat returns a user-friendly error rather than leaking raw provider internals. When `AI_PROVIDER` is unset, the chat endpoint responds with a disabled state instead of erroring — consistent with the platform's "AI dormant until configured" contract.

## Related Pages

- [AI Overview](/en/ai-overview) — the full AI ecosystem.
- [AI Providers](/en/ai-providers) — configure the LLM backend.
- [AI Agents](/en/ai-agents) — agents that power named chat panels.
- [AI Memory](/en/ai-memory) — conversation history and learned facts.
- [Records Overview](/en/records-overview) — the record CRUD model chat operates on.
- [Roles & RBAC](/en/auth-roles-rbac) — the permissions chat always enforces.

# AI Agents

An agent is an autonomous AI actor that operates **as a virtual user** inside your app. Each agent binds to an auth role, is restricted to an explicit allowlist of tables and actions, and can be gated by human approval, run on a schedule, and bounded by operational limits. Agents are declared under the top-level `app.agents[]` array.

Agents require `app.auth` to be configured (they are stored as auth users) and `AI_PROVIDER` to be set.

```yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: You are a courteous support assistant. Resolve tickets accurately.
    tools:
      tables: [tickets, customers]
      actions: [record.read, record.update, email.send]
    approval:
      mode: selective
      required: [email.send]
    limits:
      maxActionsPerMinute: 20
      maxTokensPerDay: 100000
```

## Agent-as-User Model

Each agent is materialized at runtime as an `auth.user` record with `type: 'agent'` and a synthetic email (`{name}@agents.sovrium.local`). This is the foundation of agent security:

- The agent **inherits every table and field permission of its assigned role**, exactly like a human user.
- Agents **cannot authenticate** via any login endpoint (email/password, magic link, OTP).
- Agent actions appear in the activity log with `actor.type = 'agent'`.
- Agent users are excluded from the user list by default, and included only when `?includeAgents=true` is passed.

Agent user records are managed automatically: created on first startup, updated when the role changes, and soft-deleted when the agent is removed from config.

## Definition Properties

The core identity fields are inlined at the top level of each agent entry.

| Property       | Description                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------- |
| `name`         | Unique kebab-case identifier (e.g. `support-agent`). Lowercase letters, digits, single hyphens. |
| `role`         | Auth role the agent operates as. Must reference a role in `auth.roles`.                         |
| `systemPrompt` | System prompt defining the agent's personality, role, and rules.                                |
| `instructions` | Optional array of behavioral instructions, appended as numbered rules to the system prompt.     |
| `model`        | LLM model override (defaults to `AI_MODEL`).                                                    |
| `temperature`  | Temperature override, `0`–`1` inclusive (defaults to `AI_TEMPERATURE`).                         |
| `maxTokens`    | Max output tokens override (defaults to `AI_MAX_TOKENS`).                                       |
| `enabled`      | Whether the agent can execute. Defaults to `true`. Disabled agents skip scheduled runs.         |

## Tools & Double-Gate Security

The `tools` block is the agent's capability allowlist. Sovrium enforces a **double-gate** security model — both gates must pass:

1. **RBAC gate** — does the agent's role have permission for this table/action?
2. **Allowlist gate** — is this table/action listed in the agent's `tools`?

An agent with no `tools` has **no access** (secure by default).

| Property        | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `tools.tables`  | Table names the agent can access (at least one; must exist in `tables`). |
| `tools.actions` | Action types the agent can perform (at least one; see below).            |

### Available Actions

Actions follow the `type.operator` pattern used by the automation engine.

| Category   | Actions                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------- |
| **Record** | `record.read`, `record.create`, `record.update`, `record.delete`                         |
| **State**  | `state.get`, `state.set`, `state.increment`, `state.delete`, `state.list` (cross-run KV) |
| **HTTP**   | `http.request`                                                                           |
| **AI**     | `ai.generate`, `ai.classify`, `ai.extract` (chain LLM sub-tasks)                         |
| **Code**   | `code.runTypescript` (sandboxed)                                                         |
| **Email**  | `email.send`                                                                             |
| **Auth**   | `auth.createUser`, `auth.assignRole`, `auth.banUser`, `auth.unbanUser`                   |
| **File**   | `file.upload`, `file.download`, `file.delete`, `file.list`, `file.getMetadata`           |

## Permissions: Who Can Invoke the Agent

The optional `permissions` block describes the agent's RBAC integration and who may trigger it.

| Property                  | Description                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `permissions.type`        | User-type discriminator — always `agent`.                                                  |
| `permissions.trigger`     | Who may invoke this agent: `all`, `authenticated`, or a role array like `[admin, member]`. |
| `permissions.emailDomain` | Domain for the synthetic agent email (defaults to `agents.sovrium.local`).                 |

## Human-in-the-Loop Approval

The `approval` block gates agent actions behind human review.

| Property              | Description                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `approval.mode`       | `none` (execute immediately), `all` (every action needs approval), or `selective`.         |
| `approval.required`   | Actions requiring approval (a subset of `tools.actions`). Required when `mode: selective`. |
| `approval.timeout`    | Seconds before a pending approval expires (default `3600`).                                |
| `approval.escalation` | Escalation when an approval stays pending — `{ after: <seconds>, to: <role> }`.            |

```yaml
approval:
  mode: selective
  required: [record.delete, email.send]
  timeout: 1800
  escalation:
    after: 600
    to: admin
```

:::callout
**Escalation `after` must be less than `timeout`.** An approval that is not actioned within `after` seconds escalates to the `to` role; if still unactioned by `timeout`, it expires.
:::

## Scheduled Execution

The `schedule` block makes an agent run automatically at a cron interval. The `taskPrompt` is sent to the LLM as the user message on each run.

| Property              | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| `schedule.cron`       | Standard 5-field cron expression (e.g. `*/15 * * * *`, `0 9 * * MON`). |
| `schedule.timezone`   | IANA timezone identifier (defaults to `UTC`).                          |
| `schedule.taskPrompt` | Prompt sent to the LLM on each scheduled execution.                    |

```yaml
schedule:
  cron: '0 9 * * MON'
  timezone: Europe/Paris
  taskPrompt: Summarize last week's new tickets and post the digest.
```

Scheduled runs respect `enabled` (disabled agents skip them) and `approval` (e.g. `mode: all` pauses the scheduled run for human sign-off).

## Operational Limits

The `limits` block caps resource consumption to prevent runaway agents. All fields are optional and fall back to system defaults.

| Property                     | Default  | Description                                         |
| ---------------------------- | -------- | --------------------------------------------------- |
| `limits.maxActionsPerMinute` | `30`     | Maximum DB/email actions per minute.                |
| `limits.maxTokensPerDay`     | `200000` | Maximum LLM tokens per 24h. Resets at midnight UTC. |
| `limits.maxConcurrentTasks`  | `5`      | Maximum simultaneous task executions.               |

## Memory, Knowledge, and MCP

Agents compose with three further capabilities, each documented in its own page:

| Block       | Purpose                                                                      | Docs                                   |
| ----------- | ---------------------------------------------------------------------------- | -------------------------------------- |
| `memory`    | Conversation history, RAG knowledge retrieval, and persistent learned facts. | [AI Memory](/en/ai-memory)             |
| `knowledge` | Tables and documents to embed as the agent's RAG knowledge base.             | [AI RAG](/en/ai-rag)                   |
| `mcp`       | Allowlist of external MCP tools the agent may invoke.                        | [MCP Integration](/en/mcp-integration) |

## Multi-Agent & Invocation

Agents can be invoked from the AI chat interface (a named `ai-chat` component), via API, on a schedule, and from automations through the [`ai:agent` action](/en/automation-ai-actions). Because each agent is a distinct virtual user with its own role and tool allowlist, multiple agents can coexist with different privilege boundaries — a read-only analyst agent and a write-capable triage agent, for example.

## Full Example

```yaml
agents:
  - name: data-analyst
    role: analyst
    systemPrompt: You are an expert data analyst. Be precise and cite the records you used.
    instructions:
      - Never expose customer PII in summaries.
      - Prefer aggregates over row-level dumps.
    tools:
      tables: [orders, customers]
      actions: [record.read]
    approval:
      mode: none
    limits:
      maxActionsPerMinute: 20
      maxTokensPerDay: 150000
    schedule:
      cron: '0 7 * * *'
      timezone: UTC
      taskPrompt: Produce the daily orders summary.
```

## Related Pages

- [AI Overview](/en/ai-overview) — the full AI ecosystem.
- [AI Providers](/en/ai-providers) — model, temperature, and token defaults agents inherit.
- [AI Chat](/en/ai-chat) — embed an agent as a conversational panel.
- [AI Memory](/en/ai-memory) — agent conversation, knowledge, and facts.
- [AI RAG](/en/ai-rag) — knowledge sources agents embed.
- [MCP Integration](/en/mcp-integration) — agents as MCP clients.
- [AI Actions](/en/automation-ai-actions) — the `ai:agent` automation action and AI action vocabulary.
- [Roles & RBAC](/en/auth-roles-rbac) — the role permissions agents inherit.

# AI RAG

Retrieval-Augmented Generation (RAG) lets agents and the chat interface answer questions grounded in **your application's actual data** — table records and uploaded documents — instead of relying solely on the model's training data. Before generating a response, the runtime retrieves the most relevant content from a vector-indexed knowledge base and injects it into context.

RAG is **native** once `AI_PROVIDER` is configured: the embedding infrastructure is provisioned automatically, with no YAML required to wire up storage. Schema authors declare _what_ to embed (in an agent's `knowledge` block); operators tune _how_ via env vars.

## Architecture

```
Knowledge Sources                         Vector Store
    │                                          │
    ├── Table Records ───▶ Chunk + Embed ───▶  │
    │   (specified fields)                     │
    │                                          │
    └── Documents ───────▶ Chunk + Embed ───▶  │
        (PDF, MD, TXT)                         ▼
                                       Similarity Search
                                              │
                                              ▼
                       AI Provider (generates a grounded response)
```

## Dialect-Aware Storage

RAG works on **both** database dialects via the `AiEmbeddingRepository` port — there is no external vector database on either.

| Dialect    | Storage                                                | Similarity                                      |
| ---------- | ------------------------------------------------------ | ----------------------------------------------- |
| PostgreSQL | pgvector extension; `vector` column in the `ai` schema | Cosine distance computed in SQL (HNSW-indexed). |
| SQLite     | `Float32` BLOB column (packed bytes)                   | Cosine similarity computed in application code. |

:::callout
**The frugal default — SQLite + Ollama — supports RAG.** SQLite stores vectors as packed `Float32` BLOBs and computes cosine similarity in application code, normalized to match the Postgres contract. The response envelope and each result's shape (`agentName`, `sourceRef`, `content`, `similarity`) are identical across dialects, so callers never branch on the storage engine.
:::

## Knowledge Sources

An agent's `knowledge` block defines the input data sources embedded into its knowledge base. Both source types are optional and can be combined.

### Table Knowledge

Embed specified fields from a table. Only text-like fields (single-line-text, long-text, rich-text, markdown) should be embedded. An optional `filter` limits which rows are included.

```yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: Answer using the FAQ and published docs.
    knowledge:
      tables:
        - { table: faq, fields: [question, answer] }
        - { table: docs, fields: [content], filter: { status: published } }
```

| Property | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `table`  | Table name to embed (must reference a table in `app.tables`).         |
| `fields` | Field names to include in embeddings (at least one).                  |
| `filter` | Optional key-value equality filter selecting which rows are embedded. |

When source records change, embeddings are updated automatically (auto-sync).

### Document Knowledge

Embed document files (PDF, Markdown, plain text) discovered in the knowledge directory.

```yaml
knowledge:
  documents:
    - { path: /knowledge/product-manual.pdf, label: Product Manual }
```

| Property | Description                                   |
| -------- | --------------------------------------------- |
| `path`   | File path to the document.                    |
| `label`  | Optional human-readable label for the source. |

Documents placed in `AI_KNOWLEDGE_DIR` are natively discovered, parsed, chunked, embedded, and stored.

| Format     | Extension | Notes                                  |
| ---------- | --------- | -------------------------------------- |
| PDF        | `.pdf`    | Text-only; scanned PDFs not supported. |
| Markdown   | `.md`     | Formatting stripped, structure kept.   |
| Plain text | `.txt`    | Ingested directly.                     |

## Per-Agent Knowledge Scoping

Each agent has its own **isolated** knowledge base, keyed by agent name. One agent never retrieves another agent's embeddings. Chat can additionally access knowledge scoped to the requesting user's permissions. This isolation lets a support agent and a sales agent embed entirely different corpora without cross-contamination.

## Embedding & Retrieval Configuration

Chunking, embedding, and retrieval are tuned via environment variables.

| Variable                  | Description                                         | Default                            |
| ------------------------- | --------------------------------------------------- | ---------------------------------- |
| `AI_EMBEDDING_MODEL`      | Embedding model to use.                             | Provider's default embedding model |
| `AI_EMBEDDING_DIMENSIONS` | Vector dimensions (must match the model output).    | Auto-detected from the model       |
| `AI_KNOWLEDGE_DIR`        | Path to the knowledge documents folder.             | `./knowledge`                      |
| `AI_RAG_CHUNK_SIZE`       | Characters per chunk.                               | `512`                              |
| `AI_RAG_CHUNK_OVERLAP`    | Overlap between adjacent chunks.                    | `50`                               |
| `AI_RAG_SIMILARITY`       | Minimum cosine similarity to retain a result (0–1). | `0.7`                              |
| `AI_RAG_MAX_RESULTS`      | Maximum chunks returned per query.                  | `5`                                |

## Rebuild & Search APIs

| Endpoint                   | Purpose                                                                                                                                 |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/ai/rag/rebuild` | Re-embeds the configured agent/document knowledge and persists vectors. Admin-only when `app.auth` is configured.                       |
| `POST /api/ai/rag/search`  | Embeds a query, runs similarity search (optionally scoped by `agent`), filters by the similarity threshold, and returns ranked results. |

Both endpoints behave identically across PostgreSQL and SQLite — same authorization, same response shape.

## Related Pages

- [AI Overview](/en/ai-overview) — the full AI ecosystem.
- [AI Agents](/en/ai-agents) — agents that own knowledge bases.
- [AI Memory](/en/ai-memory) — runtime knowledge retrieval vs. embedded sources.
- [AI Providers](/en/ai-providers) — embedding model configuration.
- [Environment Variables](/en/env-vars) — full `AI_RAG_*` reference.

# AI Memory

Agent memory gives an agent context that persists beyond a single message. It is configured under an agent's `memory` block and is composed of **three independent tiers**, each disabled by default and enabled individually. Before the runtime invokes the LLM (for example, when the `ai:agent` automation action dispatches a task), it assembles context from whichever tiers are enabled.

| Tier           | Persistence                         | Direction  | Purpose                                               |
| -------------- | ----------------------------------- | ---------- | ----------------------------------------------------- |
| `conversation` | Session-level (ephemeral, windowed) | Read       | Maintain dialogue context across recent messages.     |
| `knowledge`    | Read-only RAG sources               | Read       | Retrieve relevant documents via semantic search.      |
| `facts`        | Persistent across sessions          | Read/write | Remember AI-managed facts the agent learns over time. |

```yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: Be helpful and remember the customer's preferences.
    memory:
      conversation:
        enabled: true
        windowSize: 10
        summarize: true
      knowledge:
        enabled: true
        sources: [faq, docs]
        retrievalLimit: 5
        similarityThreshold: 0.7
      facts:
        enabled: true
        maxFacts: 100
        namespace: support
```

## Conversation Memory

Retains recent messages from the agent's session. When enabled, the runtime loads the last `windowSize` messages into context before each invocation.

| Property     | Default | Description                                                                   |
| ------------ | ------- | ----------------------------------------------------------------------------- |
| `enabled`    | `false` | Whether conversation memory is active.                                        |
| `windowSize` | `10`    | Number of recent messages kept in context.                                    |
| `summarize`  | `false` | When `true`, older messages are compressed into a summary instead of dropped. |

## Knowledge Memory

RAG-based semantic retrieval from configured knowledge sources. When enabled, the runtime runs a similarity search against the listed sources before each invocation and injects the most relevant documents into context. This is the _runtime retrieval_ side of RAG — distinct from the agent's `knowledge` block, which defines the _input sources_ that get embedded.

| Property              | Default | Description                                                                   |
| --------------------- | ------- | ----------------------------------------------------------------------------- |
| `enabled`             | `false` | Whether knowledge retrieval is active.                                        |
| `sources`             | —       | Knowledge source names to search (must reference configured knowledge bases). |
| `retrievalLimit`      | `5`     | Maximum documents retrieved per query.                                        |
| `similarityThreshold` | `0.7`   | Minimum similarity score (`0`–`1`) for a retrieved document to be included.   |

:::callout
**Knowledge memory reuses the RAG pipeline.** Retrieval runs against the same vector store described in [AI RAG](/en/ai-rag) — pgvector on PostgreSQL or `Float32` BLOB + app-side cosine on SQLite.
:::

## Facts Memory

Persistent key-value facts the agent learns across sessions. Unlike the `state` automation action (explicit developer-set KV), facts are **AI-managed**: the agent itself decides what is worth remembering. Facts are retrieved by semantic relevance to the current task, not by exact-key lookup.

| Property    | Default    | Description                                                                         |
| ----------- | ---------- | ----------------------------------------------------------------------------------- |
| `enabled`   | `false`    | Whether facts memory is active.                                                     |
| `maxFacts`  | `100`      | Maximum number of facts the agent can store.                                        |
| `namespace` | agent name | Namespace for fact isolation. Lowercase, starts with a letter (`^[a-z][a-z0-9-]*`). |

### Namespace Isolation & Per-User Scoping

Facts are partitioned by `namespace` (defaulting to the agent's name), so two agents never read each other's learned facts. Combined with the agent-as-user model — each agent is a distinct `auth.user` — this gives per-agent and, where chat scopes by session, per-user fact isolation. An agent cannot leak one customer's learned facts into another customer's conversation.

## Tier Composition

All three tiers are optional and combine freely. A read-only analyst agent might enable only `knowledge`; a long-running support agent might enable all three. When multiple tiers are enabled, the runtime assembles context from each before invoking the LLM:

```
conversation (recent dialogue)
        +
knowledge (semantically-retrieved docs)
        +
facts (relevant learned facts)
        ▼
   assembled context → LLM
```

## Related Pages

- [AI Agents](/en/ai-agents) — the agent the `memory` block belongs to.
- [AI RAG](/en/ai-rag) — the embedding/retrieval pipeline knowledge memory uses.
- [AI Chat](/en/ai-chat) — conversation history in the chat interface.
- [AI Overview](/en/ai-overview) — the full AI ecosystem.

# MCP Integration

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to tools and data. Sovrium speaks MCP in **both directions**:

- **Server mode** — external AI clients (Claude Desktop, Claude Code, ChatGPT Dev Mode, Cursor) connect to Sovrium and call generated tools: table CRUD, manual-automation invocation, and action-template execution.
- **Client mode** — Sovrium agents call tools hosted on _external_ MCP servers (web search, document fetch, code execution) as part of their workflows.

The two modes are configured independently and serve opposite roles.

| Mode   | Controlled by  | Where                               | LLM required on Sovrium?                    |
| ------ | -------------- | ----------------------------------- | ------------------------------------------- |
| Server | Operator (env) | `MCP_ENABLED`, `MCP_TRANSPORT`, …   | No — the LLM lives at the connecting client |
| Client | Schema author  | An agent's `mcp.allowedTools` block | Yes — `AI_PROVIDER` set                     |

:::callout
**Server mode needs no `AI_PROVIDER`.** When Sovrium is the MCP _server_, the LLM runs at the connecting client. The platform only exposes tools; it does not call a model. `AI_PROVIDER` is only required for client mode (and the rest of the AI layer).
:::

## Server Mode

### Enablement

The MCP server is **disabled by default**. The operator opts in via env vars; the server only mounts the `/mcp` route when `MCP_ENABLED=true`.

| Variable                    | Description                                                                      | Default                  |
| --------------------------- | -------------------------------------------------------------------------------- | ------------------------ |
| `MCP_ENABLED`               | Master switch — mounts the MCP route only when `true`.                           | `false`                  |
| `MCP_TRANSPORT`             | `streamable-http` for remote clients, `stdio` for local IDE integration.         | `streamable-http`        |
| `MCP_MOUNT_PATH`            | Route prefix when transport is `streamable-http`.                                | `/mcp`                   |
| `MCP_AUTH_STRATEGY`         | `oauth2` (when `app.auth` is configured) or `token`.                             | `oauth2` when auth wired |
| `MCP_TOKEN_ADMIN`           | Bearer token granting the admin role (≥32 chars; `openssl rand -hex 32`).        | —                        |
| `MCP_TOKEN_MEMBER`          | Bearer token granting the member role (≥32 chars).                               | —                        |
| `MCP_TOKEN_VIEWER`          | Bearer token granting the viewer role (≥32 chars).                               | —                        |
| `MCP_RATE_LIMIT_PER_MINUTE` | Per-token requests per minute.                                                   | `60`                     |
| `MCP_RATE_LIMIT_PER_DAY`    | Per-token requests per day.                                                      | `5000`                   |
| `MCP_AUDIT_ENABLED`         | Log every tool call to `system.ai_tool_calls` + the activity stream.             | `true`                   |
| `MCP_EXPOSE_INTERNALS`      | Expose read-only auth/system tables to the admin role.                           | `true`                   |
| `MCP_CONFIRM_DESTRUCTIVE`   | Compile `destructiveHint=true` onto delete tools and non-idempotent automations. | `true`                   |

```bash
MCP_ENABLED=true
MCP_TRANSPORT=streamable-http
MCP_AUTH_STRATEGY=token
MCP_TOKEN_ADMIN=$(openssl rand -hex 32)
MCP_TOKEN_VIEWER=$(openssl rand -hex 32)
```

### Exposed Surfaces

When mounted, the server generates tools from four surfaces — all gated by RBAC and `aiAccess`:

```
/mcp ─── tools/list ───▶ filtered by connecting role
            │
   ┌────────┴───────────────────────────────────┐
   │ 1. User tables       {app}_{table}_{op}     │  CRUD
   │ 2. Manual automations {app}_automation_{name}│  invocation
   │ 3. Action templates   {app}_action_{name}    │  execution
   │ 4. Admin internals    {app}_auth_*_read/_list │  read-only, denylisted secrets
   └─────────────────────────────────────────────┘
            │
   Audit → system.ai_tool_calls   Rate-limit → per token / OAuth client_id
```

### Declaring AI-Eligible Entities

A schema author marks an entity eligible for MCP exposure with `aiAccess`. This declares _intent_; the operator still has to enable the server with `MCP_ENABLED`. `aiAccess` applies identically to `app.tables[]`, manual-trigger `app.automations[]`, and `app.actions[]`.

It takes two forms — a boolean shorthand or a rich config object:

```yaml
# Boolean shorthand — enable with defaults.
tables:
  - name: contacts
    aiAccess: true
```

```yaml
# Rich config — supplying any object IS the enable signal (no `enabled` field).
tables:
  - name: contacts
    aiAccess:
      description: Customer contacts. Use this when the user asks about people.
      operations: [read, list, create, update]
      fieldExposure: permissioned
      annotations:
        readOnly: false
        destructive: false
```

| Property              | Description                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| `description`         | Hand-written tool description shown to the AI client — the biggest lever for steering AI behavior. |
| `operations`          | Subset of `read`, `list`, `create`, `update`, `delete` to expose (tables default to all five).     |
| `fieldExposure`       | `permissioned` (default — only fields the role can read/write), `all`, or `whitelist`.             |
| `whitelistFields`     | Fields to expose when `fieldExposure: whitelist` (required and non-empty in that mode).            |
| `annotations`         | MCP risk hints — see below.                                                                        |
| `requireConfirmation` | Force `destructiveHint=true` regardless of operation type (e.g. for email-sending automations).    |

### Tool Risk Annotations

Annotations compile into MCP tool definitions so clients can decide whether to auto-approve a call or require confirmation. They map directly to the MCP spec:

| Annotation    | MCP hint          | Meaning                                                               |
| ------------- | ----------------- | --------------------------------------------------------------------- |
| `readOnly`    | `readOnlyHint`    | Tool only reads data; safe to auto-approve.                           |
| `destructive` | `destructiveHint` | Performs destructive operations; clients should require confirmation. |
| `idempotent`  | `idempotentHint`  | Calling twice with the same args is safe (no duplicate side effects). |
| `openWorld`   | `openWorldHint`   | Reaches outside the local app (external API, network call).           |

Sensible defaults are derived from the operation type when annotations are unset.

### Authentication

| Strategy | When                              | How                                                                                        |
| -------- | --------------------------------- | ------------------------------------------------------------------------------------------ |
| `token`  | Default when `app.auth` is absent | Static per-role bearer tokens (`MCP_TOKEN_ADMIN/MEMBER/VIEWER`). At least one must be set. |
| `oauth2` | Default when `app.auth` is wired  | OAuth 2.1 against Better Auth's OAuth-server plugin.                                       |

The connecting credential's role drives RBAC: a `viewer` token can only read/list even when an entity's `aiAccess.operations` allows writes. Startup validation rejects `MCP_AUTH_STRATEGY=token` with no token set, and `oauth2` when `app.auth` is not configured.

### RBAC, Audit & Rate Limiting

- **RBAC** — MCP clients are governed by the same role permissions and row-level rules as human sessions. There is no AI bypass.
- **Audit** — every tool call is logged to `system.ai_tool_calls` and the activity stream when `MCP_AUDIT_ENABLED` is `true` (the default).
- **Rate limiting** — enforced per token (or OAuth `client_id`); over-limit requests return `429` with standard rate-limit headers.

### Admin Internals

When `MCP_EXPOSE_INTERNALS=true` (the default), the admin role gets read-only tools over the `auth` and `system` schema tables (`{app}_auth_*_read/_list`, `{app}_system_*_read/_list`), with secret columns denylisted. Set it to `false` to remove all internal tools from `tools/list`, even for admins.

## Client Mode

Sovrium agents can consume tools from external MCP servers. An agent's `mcp` block defines the allowlist of external tool names it may invoke.

```yaml
agents:
  - name: research-agent
    role: analyst
    systemPrompt: Research topics using approved external tools.
    mcp:
      allowedTools: [web_search, fetch_url]
```

| Property           | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `mcp.allowedTools` | External MCP tool names the agent is allowed to use. |

This complements the agent's internal `tools` allowlist: `tools` scopes what the agent can do _inside_ Sovrium, while `mcp.allowedTools` scopes which _external_ MCP tools it may call.

## Related Pages

- [AI Overview](/en/ai-overview) — the full AI ecosystem and config philosophy.
- [AI Agents](/en/ai-agents) — agents that act as MCP clients.
- [Tables Overview](/en/tables-overview) — the `aiAccess` table property.
- [Actions](/en/automation-actions-overview) — action templates exposed as MCP tools.
- [Roles & RBAC](/en/auth-roles-rbac) — the permissions MCP always enforces.
- [Environment Variables](/en/env-vars) — full `MCP_*` reference.

# User Management

Sovrium provisions and manages users without ever requiring you to touch the database directly. The first administrator is created at boot (from environment variables, a one-time token, or the CLI); subsequent users are created, listed, role-assigned, and invited through the authenticated admin API. Every operation is RBAC-gated and audit-logged.

User management is only available when [authentication](/en/auth-overview) is configured. The admin plugin is enabled automatically the moment an `auth` block exists — there is no separate flag to set.

## Admin Bootstrap

The very first admin cannot be created by another admin (there is none yet) or by self-registration (you do not want anyone claiming the admin seat). Sovrium offers **three complementary bootstrap paths** for provisioning that first account on a fresh database.

| Path                  | When to use                             | Mechanism                                                                                                                                             |
| --------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Env-var bootstrap** | Automated / IaC deploys                 | Set `AUTH_ADMIN_EMAIL` + `AUTH_ADMIN_PASSWORD` (+ optional `AUTH_ADMIN_NAME`); the admin is created on first boot.                                    |
| **One-time token**    | You do not want credentials in env vars | Boot with no `AUTH_ADMIN_EMAIL` and no users; a 64-hex token is printed in the startup banner and claimed once via `POST /api/admin/bootstrap/claim`. |
| **CLI**               | Interactive provisioning                | `sovrium admin create <email>` works against the configured database (or the default SQLite file) with no `app.yaml` required.                        |

### Env-var bootstrap (no-config)

```bash
AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=SecureP@ssw0rd!
AUTH_ADMIN_NAME=System Administrator   # optional, defaults to "Administrator"
```

On first boot against a fresh database the server provisions the admin with a verified email and grants it access to every admin-only endpoint. On subsequent startups the path no-ops — it never creates a duplicate and never modifies an existing user, even if the email already maps to a different role. The success is logged **without** exposing the password.

| Env var               | Description                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------- |
| `AUTH_ADMIN_EMAIL`    | Email for the bootstrap admin. Required for the env-var path. Must be a valid email format.   |
| `AUTH_ADMIN_PASSWORD` | Initial password. Required for the env-var path. Must meet the minimum length (8 characters). |
| `AUTH_ADMIN_NAME`     | Display name. Optional — defaults to `Administrator`.                                         |

:::callout
**Bootstrap is gated on a configured `auth` block.** If `auth` is absent, or `AUTH_ADMIN_EMAIL`/`AUTH_ADMIN_PASSWORD` is missing, no admin is created — the server boots without one. The env-var path is a no-op when any user already exists.
:::

### One-time token bootstrap

When the server boots with **no** `AUTH_ADMIN_EMAIL` set **and** no users in the database, it generates a 256-bit cryptographically random token, prints it once in the startup banner, and accepts a single claim:

```bash
# Token appears in the banner as:
#   → First-admin token (POST /api/admin/bootstrap/claim): <64-hex-token>

curl -X POST http://localhost:3000/api/admin/bootstrap/claim \
  -H 'Content-Type: application/json' \
  -d '{ "token": "<64-hex-token>", "email": "admin@example.com", "password": "SecureP@ssw0rd!", "name": "Admin" }'
```

Security properties:

- Only the SHA-256 hash of the token is persisted; the plaintext is printed to stdout exactly once and never logged.
- The token expires after **1 hour** and can be claimed **once** — replays return `401`.
- Once any admin exists the route returns **404**: the bootstrap window has closed, and even a leaked valid token cannot reopen it.

This is the path that makes "run the binary on a fresh server with only `DATABASE_URL` set, open the URL, build the app live" possible. See [Database Infrastructure](/en/database-infrastructure) for the zero-config database that pairs with it.

## Creating & Managing Users

Once an admin exists, all subsequent user lifecycle operations run through the admin API. Each endpoint requires an authenticated admin session — unauthenticated requests return `401`, non-admin sessions return `403`.

| Operation      | Endpoint                                   | Notes                                                                                   |
| -------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| Create user    | `POST /api/auth/admin/create-user`         | Engineer chooses the password; **no email** is sent. Returns `201`.                     |
| List users     | `GET /api/auth/admin/list-users`           | Paginated (`limit`/`offset`), returns count metadata, supports search by email or name. |
| Get user       | `GET /api/auth/admin/get-user/:id`         | Full detail incl. role, ban status, email-verified flag. `404` for unknown ids.         |
| Set role       | `POST /api/auth/admin/set-role`            | Assign `admin` / `member` / `viewer` (or any [custom role](/en/auth-roles-rbac)).       |
| Set password   | `POST /api/auth/admin/set-user-password`   | Reset a user's password administratively.                                               |
| List sessions  | `GET /api/auth/admin/list-user-sessions`   | Active [sessions](/en/auth-sessions) for a user.                                        |
| Revoke session | `POST /api/auth/admin/revoke-user-session` | Force-logout a specific session.                                                        |
| Impersonate    | `POST /api/auth/admin/impersonate-user`    | Start/stop impersonation for support workflows.                                         |

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
```

:::callout
**Validation is enforced server-side.** Create-user returns `400` for a missing/malformed email or missing password, and `422` when the email already exists. Roles assigned must be one of the app's declared roles — see [Roles & RBAC](/en/auth-roles-rbac).
:::

## Role Assignment

Sovrium ships three default roles — `admin`, `member`, `viewer` — and supports custom roles declared in the `auth` block. New users receive `auth.defaultRole` (falls back to `member`) unless an explicit role is supplied at creation. The first bootstrap admin is always created with the `admin` role and a verified email.

Roles drive every authorization decision in the platform: table [permissions](/en/table-permissions), per-field access, page access, and the admin API itself. See [Roles & RBAC](/en/auth-roles-rbac) for the full role model and field-level permission matrix.

## Invitation Flow

The `create-user` endpoint requires the admin to choose the customer's password and sends no email — unsuitable for real customer onboarding. The parallel **passwordless invitation flow** closes that gap: the admin issues an invitation with `{ email, name, role }` (no password), Sovrium emails a single-use link, and the customer sets their own password and lands authenticated.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  invitationTokenExpiry: '72h' # default lifetime; accepts '30s' / '15m' / '72h' / '7d' / ms
  emailTemplates:
    invitation:
      subject: 'You are invited to join, $name'
      text: |
        Hi $name,
        $inviterName invited you to join.
        Set your password: $url
        This invitation expires in 72 hours.
```

| Endpoint                                 | Behavior                                                                                                                                                                                           |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/auth/admin/invite-user`       | Accepts `{ email, name, role }` (no password). Returns `200` with `{ user, invitationSent: true }`. `401`/`403` for unauth/non-admin; `422` when the email already maps to a fully-onboarded user. |
| `POST /api/auth/admin/accept-invitation` | Backs the public `/accept-invitation?token=...` page. The customer sets a password and lands in an authenticated session.                                                                          |

Invitation tokens reuse the `auth.verification` table (the same shape Better Auth uses for password reset), expire after `invitationTokenExpiry` (default 72h), and are single-use — replays return `400`/`410`. Email substitution variables: `$name`, `$url`, `$email`, `$inviterName`. `auth.allowSignUp: false` does **not** block invitations — admin-driven user creation is always available when auth is configured.

:::callout
**Onboarding is decoupled from access assignment.** Inviting a user creates the account but does not grant them any tenant scope. Wiring a user to data access is a separate step via the standard records API — an admin can invite first and assign later, or vice versa.
:::

## Related Pages

- [Authentication Overview](/en/auth-overview) — strategies, configuration, the `auth` block.
- [Roles & RBAC](/en/auth-roles-rbac) — role model and field-level permissions.
- [Sessions](/en/auth-sessions) — session lifetime, revocation, multi-device.
- [Admin Dashboard](/en/admin-dashboard) — operator-grade read API over users, tables, automations.
- [Activity Monitoring](/en/activity-monitoring) — audit trail of user and admin actions.
- [Database Infrastructure](/en/database-infrastructure) — the zero-config database the no-config bootstrap pairs with.
- [Environment Variables](/en/env-vars) — full env-var reference incl. `AUTH_ADMIN_*`.

# Activity Monitoring

Sovrium records every meaningful action across the application — record create/update/delete, authentication events, and administrative operations — into a system-wide activity log. The log is queryable through an authenticated API with filtering and pagination, giving operators and auditors a single place to answer "who did what, when".

This is the operator-facing read surface over the platform's canonical audit-log event store. Each entry is immutable and outlives the rows it references where required for compliance (an `account.deletion.purged` event survives the erasure of the user who triggered it — see [GDPR & Privacy](/en/gdpr-privacy)).

## What Gets Tracked

| Category                   | Examples                                                            |
| -------------------------- | ------------------------------------------------------------------- |
| **Record CRUD**            | `create`, `update`, `delete`, `restore` on any table record.        |
| **Authentication events**  | Sign-in, sign-up, password reset, session revocation.               |
| **Administrative actions** | User creation, role changes, bans, schema publishes, force-deletes. |
| **System events**          | Migrations, account-deletion scheduling and purge.                  |

Each entry carries the action, the affected table and record id (when applicable), a timestamp, and the acting user (id, name, email). The actor reference is FK-linked with `ON DELETE SET NULL` so an audit entry remains a valid compliance record even after the actor's account is erased.

## Querying the Activity Log

The activity API is admin-gated. Unauthenticated requests return `401`; non-admin sessions return `403`.

```
GET /api/activity?page=1&pageSize=20&table=orders&action=update
```

```json
{
  "activities": [
    {
      "id": "act_123",
      "action": "update",
      "tableName": "orders",
      "recordId": 456,
      "createdAt": "2025-01-15T10:30:00Z",
      "user": { "id": "1", "name": "Alice", "email": "alice@example.com" }
    }
  ],
  "pagination": { "total": 150, "page": 1, "pageSize": 20, "totalPages": 8 }
}
```

| Endpoint                        | Description                                     |
| ------------------------------- | ----------------------------------------------- |
| `GET /api/activity`             | Paginated, filterable list of activity entries. |
| `GET /api/activity/:activityId` | Full detail for a single activity entry.        |

### Query Parameters

| Parameter  | Type   | Description                                                    |
| ---------- | ------ | -------------------------------------------------------------- |
| `page`     | number | Page number (default: `1`).                                    |
| `pageSize` | number | Entries per page.                                              |
| `table`    | string | Filter to a single table by name.                              |
| `action`   | string | Filter by action (`create`, `update`, `delete`, `restore`, …). |

:::callout
**Activity log vs record history.** The activity log is a cross-table, system-wide stream answering "what happened across the app". For the field-level before/after change set of a single record, use [Record History](/en/record-history) — it captures the diff of each individual edit. The two complement each other: activity for breadth, history for depth.
:::

## Retention

Activity entries are retained according to the platform retention policy. Soft-deleted source rows themselves age out per the `ECO_RETENTION_PURGE_DAYS` horizon (see [Ecoconception](/en/ecoconception)), but audit entries required for compliance — notably erasure records — are preserved independently of the rows they describe.

## Compliance Use

The same shape returned to admins is returned to auditors, so SOC2 / GDPR review documentation reflects exactly what operators see. Combined with the immutable canonical event store, the activity log provides the "audit trail of erasure" required when honoring a [right-to-be-forgotten](/en/gdpr-privacy) request: the deletion is itself logged, with the actor reference null-ified once the account is purged.

## Related Pages

- [Record History](/en/record-history) — field-level before/after diffs per record.
- [Soft Delete](/en/records-soft-delete) — recoverable deletes and the `deleted_at` tombstone.
- [Admin Dashboard](/en/admin-dashboard) — operator read API over the rest of the platform.
- [GDPR & Privacy](/en/gdpr-privacy) — erasure records and the audit trail of deletion.
- [User Management](/en/user-management) — the admin actions that produce activity entries.

# Analytics

Sovrium ships a built-in, first-party analytics engine. It tracks page views, sessions, referrers, UTM campaigns, and device breakdowns on a single unified event model — with no cookies, no fingerprinting, and no external services. All data stays on your server, which makes it GDPR-friendly by default.

Analytics is configured via the `analytics` property in the app schema. When enabled, Sovrium injects a lightweight (~1KB) tracking script that records page views via `navigator.sendBeacon()` to `POST /api/analytics/collect`.

## Configuration

`analytics` accepts a boolean shorthand or an object for fine-grained control.

```yaml
# Boolean shorthand — enable with all defaults
analytics: true

# Object form — override individual settings, keep defaults for the rest
analytics:
  enabled: true
  retentionDays: 365
  excludedPaths:
    - /admin/*
    - /api/*
  respectDoNotTrack: true
  sessionTimeout: 30
```

| Property            | Default | Range / Values      | Description                                                         |
| ------------------- | ------- | ------------------- | ------------------------------------------------------------------- |
| `enabled`           | `true`  | boolean             | Enable/disable analytics tracking.                                  |
| `retentionDays`     | `365`   | `1`–`730`           | Days to retain analytics data. Older rows are automatically purged. |
| `excludedPaths`     | `[]`    | string[] (glob)     | URL patterns excluded from tracking (e.g. `/admin/*`, `/api/*`).    |
| `respectDoNotTrack` | `true`  | boolean             | Honor the browser `DNT:1` header — those visitors are not tracked.  |
| `sessionTimeout`    | `30`    | `1`–`120` (minutes) | Idle period after which a new session begins.                       |

:::callout
**Boolean vs object.** `analytics: true` enables defaults (365-day retention, DNT respected, 30-minute sessions). Use the object form to override specific settings while keeping defaults for the rest. `analytics: false` (or omitting the property) disables analytics — no endpoints are mounted.
:::

## Unified Events Model

All analytics events — page views, custom track calls, and future sources — share a single `system.analytics_events` table with an `event_type` discriminator column. This follows the industry-standard pattern used by PostHog, Mixpanel, and Amplitude, but self-hosted with no external dependency (see DEC-019).

```
system.analytics_events
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid()
  app_name        TEXT NOT NULL
  event_type      TEXT NOT NULL          -- 'page_view' | 'track' | extensible
  event_name      TEXT NOT NULL          -- path for page_view, custom name for track
  org_id          TEXT                   -- organization scope (nullable pre-auth)
  timestamp       TIMESTAMPTZ NOT NULL DEFAULT now()
  visitor_hash    TEXT NOT NULL          -- privacy-preserving visitor identifier
  session_hash    TEXT NOT NULL          -- privacy-preserving session identifier
  properties      JSONB NOT NULL DEFAULT '{}'
```

| Event type  | `event_name`          | `properties` payload                                                                                |
| ----------- | --------------------- | --------------------------------------------------------------------------------------------------- |
| `page_view` | The page path         | `path`, `referrer`, `utm_*`, `device_type`, `browser_*`, `os_*`, `screen_*`, `language`, `country`. |
| `track`     | The custom event name | Arbitrary key-value metadata from an automation action or the tracking API.                         |

The promoted columns (`event_type`, `event_name`, `org_id`, `visitor_hash`, `session_hash`, `timestamp`) drive efficient `WHERE`/`GROUP BY` queries; everything else lives in JSONB. The same privacy primitives — server-side visitor/session hashing (SHA-256, no PII stored), DNT respect, and the retention horizon — apply uniformly to every event type, and every row is org-scoped for multi-tenant isolation.

:::callout
**Storage-engine parity.** The unified events table is exercised by both the PostgreSQL (`->>` over `system.analytics_events`) and [SQLite](/en/database-infrastructure) (`json_extract` over `system_analytics_events`) query paths. Both produce identical response shapes for collect, overview time-series, top-pages, referrer/UTM, and device breakdown.
:::

## Querying Analytics

Aggregated analytics are exposed through admin-gated read endpoints. Inspect raw events for debugging or custom dashboards.

| Endpoint                       | Returns                                                      |
| ------------------------------ | ------------------------------------------------------------ |
| `POST /api/analytics/collect`  | Public ingest endpoint hit by the tracking script.           |
| `GET /api/analytics/overview`  | Totals + bucketed daily time series.                         |
| `GET /api/analytics/pages`     | Top pages by view count.                                     |
| `GET /api/analytics/referrers` | Referrer and UTM-campaign breakdown.                         |
| `GET /api/analytics/devices`   | Device-type and browser breakdown.                           |
| `GET /api/analytics/campaigns` | UTM campaign analysis.                                       |
| `GET /api/analytics/events`    | **Admin-only** raw event inspection (paginated, filterable). |

### Inspecting raw events

`GET /api/analytics/events` provides row-level visibility into the unified stream — complementing the aggregated endpoints. It is admin-only and supports filtering by `event_type`, `event_name`, and date range.

```
GET /api/analytics/events?event_type=track&limit=50&offset=0&from=2026-01-01&to=2026-04-15
```

| Parameter     | Description                               |
| ------------- | ----------------------------------------- |
| `event_type`  | Filter by type (`page_view`, `track`, …). |
| `event_name`  | Exact-match event name.                   |
| `from` / `to` | ISO 8601 date range (inclusive).          |
| `limit`       | Max results (default `50`, max `1000`).   |
| `offset`      | Pagination offset (default `0`).          |

## Privacy & Compliance

- **No cookies, no fingerprinting.** Visitors are identified by a server-computed SHA-256 hash; no client-side identifier is stored.
- **DNT respected by default.** Visitors sending `DNT:1` are not tracked when `respectDoNotTrack` is on.
- **All data is local.** No third-party services and no external calls — analytics never leaves your server.
- **Bounded retention.** Data older than `retentionDays` is automatically purged, aligning with the platform's data-minimisation posture (see [Ecoconception](/en/ecoconception)).

## Related Pages

- [Admin Dashboard](/en/admin-dashboard) — operator read API across the platform.
- [Activity Monitoring](/en/activity-monitoring) — audit trail of user and admin actions.
- [Automations](/en/automations-overview) — emit custom `track` events from automation actions.
- [Ecoconception](/en/ecoconception) — data retention and environmental footprint.
- [Database Infrastructure](/en/database-infrastructure) — the SQLite/PostgreSQL parity behind the events table.

# Admin Dashboard

Sovrium ships a built-in App Admin Dashboard: a family of read-only API endpoints that give operators and auditors a single, consistent surface over the running app's health and inventory. Every endpoint is RBAC-gated, emits a canonical audit-log event, and returns `404` (never `403`) on unauthorized access to defeat enumeration.

The dashboard is a **read** surface. Mutating operations — creating users, changing roles, publishing schema — live in their own endpoints ([User Management](/en/user-management)); the dashboard reflects state, it does not change it. Three audiences share the exact same response shapes: **admins** (drill-down decisions), **operators** (incident reports, on-call handoffs), and **auditors** (SOC2 / GDPR review documentation).

## Two Response Shapes

Every dashboard endpoint is one of two shapes, so the contract generalizes cleanly across domains.

| Shape        | Endpoint pattern                   | Body                                                                                                                       |
| ------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Overview** | `GET /api/admin/{domain}/overview` | Period-aware aggregate counters (`totals`), a bucketed time series (`series`), and derived health metrics. Non-paginated.  |
| **List**     | `GET /api/admin/{domain}`          | Cursor-paginated items, each carrying an operator-grade `_admin` block with `metadata` (counts, last-activity timestamps). |

Overview endpoints accept a shared period preset (`24h` \| `7d` \| `30d`) via `resolvePeriodWindow()`; list endpoints accept cursor pagination, free-text search, and `?include_deleted=true`.

## Endpoint Surface

| Domain          | Endpoint(s)                                                              | Returns                                                                                             |
| --------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Config**      | `GET /api/admin/config/version`                                          | Running version, build commit, active database runtime, Bun version, process start time.            |
| **Automations** | `GET /api/admin/automations/overview`, `GET /api/admin/automations/runs` | Run totals, failure counts, `success_rate`, bucketed series; paginated run list.                    |
| **Users**       | `GET /api/admin/users/overview`                                          | Total users, recently active, new signups for the period, role distribution, signup/session series. |
| **Tables**      | `GET /api/admin/tables/overview`                                         | Per-table `rowCount`, `softDeletedCount`, `lastWriteAt`, `writesInPeriod`, totals, write series.    |
| **Buckets**     | `GET /api/admin/buckets`, `GET /api/admin/buckets/overview`              | Cursor-paginated bucket list with provider filter; quota/usage overview.                            |
| **Forms**       | `GET /api/admin/forms`, `GET /api/admin/forms/:formName`                 | Configured forms with submission counts and last-submission timestamps; per-form detail.            |

```bash
# Version reflection — the smallest read endpoint, the cross-cutting shake-down test
curl -H 'Cookie: <admin session>' http://localhost:3000/api/admin/config/version

# Period-scoped overview
curl -H 'Cookie: <admin session>' 'http://localhost:3000/api/admin/tables/overview?period=7d'

# Cursor-paginated list with search
curl -H 'Cookie: <admin session>' 'http://localhost:3000/api/admin/forms?search=contact&limit=20'
```

:::callout
**Period presets are shared, not per-endpoint.** Overview endpoints reuse one `periodPresetSchema` (`24h` \| `7d` \| `30d`) and one `resolvePeriodWindow()` helper rather than redeclaring the enum, so a window means the same thing everywhere. Sparse domains (user signups) and dense ones (automation runs) share the identical `totals + series` body.
:::

## Cross-Cutting Guarantees

Every dashboard endpoint inherits the same security and observability primitives:

| Guarantee            | Behavior                                                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **RBAC**             | Three-tier middleware gates each route on the caller's role.                                                                                                                |
| **Anti-enumeration** | Unauthorized access returns **404**, never `403` — the id space is unguessable and the route's existence is unobservable. See [Security Hardening](/en/security-hardening). |
| **Audit log**        | Each call emits a canonical event (e.g. `form.detail.queried`) exactly once. See [Activity Monitoring](/en/activity-monitoring).                                            |
| **OpenAPI**          | Routes are declared via the shared `adminRoute` helper, so the surface is documented and type-checked.                                                                      |
| **Forward contract** | `?include_deleted=true` parses without `400` so auditors get a stable interface as deleted-row visibility lands.                                                            |

## Sibling Endpoints (Not the Dashboard)

Some operator-relevant reads live outside the `/api/admin/{domain}` dashboard family because they predate it or belong to another subsystem:

- **Per-user records** (id, email, name) → `GET /api/auth/admin/list-users`. See [User Management](/en/user-management).
- **Aggregated traffic analytics** → `GET /api/analytics/overview` and siblings. See [Analytics](/en/analytics).
- **System-wide activity stream** → `GET /api/activity`. See [Activity Monitoring](/en/activity-monitoring).

## Related Pages

- [User Management](/en/user-management) — the mutating admin operations the dashboard reflects.
- [Activity Monitoring](/en/activity-monitoring) — the audit-log stream every dashboard call writes to.
- [Analytics](/en/analytics) — the traffic-analytics read surface.
- [Security Hardening](/en/security-hardening) — RBAC, 404-not-403, rate limiting.
- [Buckets Overview](/en/buckets-overview) — storage buckets surfaced by the buckets endpoints.
- [Forms Overview](/en/forms-overview) — the forms surfaced by the forms endpoints.

# Schema Migrations

Sovrium evolves your database schema automatically. It diffs the application configuration against the physical database, generates the appropriate SQL, and executes it inside a transaction — no hand-written migration files. The system validates checksums to detect drift, supports rollback to recover from failures, and records a complete audit trail of every change.

There are two trigger points: **boot-time evolution** (the config changed since last start) and **live-migration on publish** (a draft published over the API). Additive changes apply live without a restart; destructive changes are deferred to a restart for safety.

## Automatic Schema Evolution

When the configuration differs from the database, Sovrium detects the change and applies the migration automatically — all within a transaction so a partial failure rolls back cleanly.

Supported structural changes:

```yaml
# Before
tables:
  - id: 1
    name: users
    fields:
      - { id: 1, name: email, type: email }

# After — add a phone field; Sovrium generates ADD COLUMN
tables:
  - id: 1
    name: users
    fields:
      - { id: 1, name: email, type: email }
      - { id: 2, name: phone, type: single-line-text }
```

| Change class       | Examples                                                    |
| ------------------ | ----------------------------------------------------------- |
| **Structural**     | Add/remove/rename fields and tables.                        |
| **Field property** | Type change, constraint, default, options, required toggle. |
| **Index & view**   | Add/drop indexes; create/update saved views.                |

Field IDs are the rename anchor — keep the `id` stable and change the `name` to rename a column without losing data. See [Table Indexes & Constraints](/en/table-indexes-constraints) and [Validation](/en/table-validation) for the per-field properties migrations track.

## Checksum Validation

Sovrium fingerprints the schema to skip unnecessary migration work and detect drift.

1. On the first migration, Sovrium computes a **SHA-256 checksum** of the schema and stores it.
2. On each subsequent startup it compares the current schema's checksum against the stored one.
3. **Unchanged** → the server starts quickly, running no migrations.
4. **Changed** → Sovrium executes the necessary migrations and saves the new checksum.

This makes restarts cheap when nothing changed and guarantees the database matches the declared schema when something did.

## Live-Migration on Publish

Publishing a draft over the admin API makes it the live schema **without a restart** — and for additive data-structure changes, the physical table or column is created on the running server immediately.

| Change                                        | Applied                                                                            | Why                                                                                                                       |
| --------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Additive** (add table, add column)          | **Live** — table/column exists on the running server and is immediately queryable. | Adding structure cannot lose data; safe to apply against live traffic.                                                    |
| **Destructive** (drop/rename column or table) | **Deferred to restart**                                                            | A drop/rename against a running server with traffic risks irreversible data loss without an operator's deliberate action. |

The publish pipeline runs **migrate-before-swap**: `validate → optimistic-concurrency check → apply additive DDL → insert version row → swap live app → re-register routes`. Because the DDL runs before the route swap, the newly registered `/api/tables/:slug/records` routes never point at a table that does not yet exist.

:::callout
**Additive applies live, destructive waits for a restart** (DEC-024). This relaxes the older "edit config → restart → tables ready" rule only for the safe additive case. A failed live-migration **aborts the publish** — the version is not advanced and the live app is not swapped, so a broken migration never leaves routes pointing at a missing table.
:::

## Rollback

When a migration fails, the transaction rolls back and the schema is left in its prior consistent state. Rollback is currently available **programmatically**; dedicated CLI rollback commands (`migrate:rollback`, `--to <version>`, `--force`) are planned. The version ledger records every applied schema version, so a prior version snapshot can be re-applied.

## Audit Trail

The migration system records, for each migration:

- Migration timestamp
- Schema version number
- Schema checksum (SHA-256)
- Complete schema snapshot
- Rollback operations and reason

This audit trail is the source of truth for "which schema produced this database" — auditors cross-reference it against the [activity log](/en/activity-monitoring) to correlate data changes with the schema version in force at the time.

## Error Handling

Migrations fail loud and safe. Each of these scenarios aborts before or during execution and rolls back any partial work:

| Scenario                 | Behavior                                                    |
| ------------------------ | ----------------------------------------------------------- |
| **Invalid schema**       | Validation errors are surfaced before any migration starts. |
| **Migration failure**    | A SQL execution error rolls back the transaction.           |
| **Connection error**     | The database being unavailable aborts the run.              |
| **Constraint violation** | A foreign-key or unique-constraint failure rolls back.      |

## Related Pages

- [Database Infrastructure](/en/database-infrastructure) — the SQLite/PostgreSQL engines migrations target.
- [Table Indexes & Constraints](/en/table-indexes-constraints) — the index and constraint definitions migrations apply.
- [Validation](/en/table-validation) — field- and table-level rules tracked across evolution.
- [Activity Monitoring](/en/activity-monitoring) — the audit stream correlated against schema versions.
- [Admin Dashboard](/en/admin-dashboard) — `config/version` reports the active runtime and build.

# Database Infrastructure

Sovrium runs on an embedded SQLite database with **zero configuration** and scales up to PostgreSQL by setting a single environment variable. The entire runtime — migrations, client bundles, the CSS engine, example configs — is bundled into one standalone binary, and a static page-render cache keeps server CPU frugal. This page documents the persistence and distribution layer that makes "run the binary, open the URL" possible.

## Zero-Config SQLite Default

When no `DATABASE_URL` is set, Sovrium resolves the `sqlite` dialect, creates `./.sovrium/database.db`, auto-applies the SQLite migration set on first boot, and serves the full core surface — schema, auth, records CRUD, migrations, and forms. The startup banner prints `Database: SQLite (<absolute path>)`.

This mirrors the platform's frugal-by-default philosophy (twin of `STORAGE_PROVIDER` and the `ECO_*` family): the operator opts **into** PostgreSQL by setting `DATABASE_URL`, never the other way around.

## PostgreSQL When Configured

Set `DATABASE_URL` to a `postgresql://` URL and Sovrium resolves the `postgres` dialect, connects, applies the PostgreSQL migration set, and prints `Database: PostgreSQL`. No SQLite file is created. This path is byte-identical to pre-existing PostgreSQL deployments.

A single source of truth — `parseDatabaseDialectConfig()` — scheme-discriminates the one `DATABASE_URL` variable:

| `DATABASE_URL` value                     | Resolves to                                                           |
| ---------------------------------------- | --------------------------------------------------------------------- |
| `postgres://…` / `postgresql://…`        | PostgreSQL at that URL.                                               |
| _unset / empty_                          | SQLite at `./.sovrium/database.db` (the zero-config default).         |
| `file:./x.db` / `file:/abs.db`           | SQLite at the resolved path.                                          |
| `sqlite:./x.db` / `sqlite:///abs.db`     | SQLite alias for the same on-disk file.                               |
| `:memory:`                               | Ephemeral SQLite (dialect-level only — not a full deployment target). |
| anything else (bare path, `mysql://`, …) | Throws `Unsupported DATABASE_URL scheme: …` at boot (fail-loud).      |

:::callout
**`SQLITE_PATH` was removed** (pre-1.0 breaking change, no compatibility bridge). The SQLite file location is now chosen exclusively through `DATABASE_URL` via the `file:` / `sqlite:` schemes. A bare filesystem path with no scheme (`DATABASE_URL=./database.db`) is **rejected** at boot — prefix it with `file:`.
:::

The selected dialect drives the Drizzle client (`bun:sqlite` or `bun:sql`), the migration set, the Better Auth adapter provider, and the operator-facing `runtime` label from `GET /api/admin/config/version` (`sqlite-aio` on SQLite, `postgres` on PostgreSQL).

### Graceful degradation

SQLite mode supports the core subset. Advanced PostgreSQL-only features — notably pgvector RAG semantic search — return a typed `501 { error: 'requires-postgres' }` rather than crash. Scale up to PostgreSQL to unlock them; no code changes required.

## Embedded Data Directory

All local state lives under a single, relocatable data directory.

| Env var            | Default          | Description                                                                                                |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`     | _unset → SQLite_ | Database engine + location selector.                                                                       |
| `SOVRIUM_DATA_DIR` | `./.sovrium`     | Root for the SQLite DB file, lock files, and local storage. Relocate the whole data dir with one variable. |

The default `./.sovrium/database.db` sits under this data dir; the parent directory is created automatically on first boot.

## Static Page Render Cache

Sovrium renders pages server-side on every request. For a page whose HTML does not depend on per-request state (a marketing, about, or pricing page), that is wasted CPU. The in-memory render cache renders such a page once and serves it from memory on subsequent anonymous requests, skipping `renderToString` entirely — an ecoconception and latency win.

| Env var          | Default | Options       | Description                                                                           |
| ---------------- | ------- | ------------- | ------------------------------------------------------------------------------------- |
| `ECO_PAGE_CACHE` | `on`    | `on` \| `off` | In-memory cache of request-invariant page HTML. Operators opt out; they never opt in. |

How it works:

- **Cacheability is derived, never authored.** A page is cacheable only when its rendered HTML cannot vary by request — it is excluded if it has non-public `access`, a `collection`, a page/component `dataSource`, a `contentDir`, a file `source`, a `markdown` body, `presence`, a data-bound sidebar, or a dynamic `:param` route segment.
- **Safety model.** The cache is consulted only for **anonymous, non-preview** requests; session-dependent filtering is deterministic when no session exists, so one user's view can never leak to another.
- **Invalidation by checksum.** Each entry is keyed by `${appRenderChecksum}:${path}:${language}`. The checksum is a SHA-256 of the render-affecting schema slice (`pages`, `components`, `theme`, `languages`, `analytics`); any schema edit changes every key, so stale entries become unreachable. No TTL, no purge logic.
- **Observability.** Every page response carries `X-Render-Cache: hit | miss | bypass` and a `Cache-Control` header (`public, max-age=300` for cacheable, `private, no-cache` for bypassed). Language variants (`/` vs `/fr/`) are isolated by key.

See [Ecoconception](/en/ecoconception) for the full `ECO_*` env-var contract.

## Standalone Binary Distribution

Sovrium's primary distribution channel is a **standalone binary** (`bun build --compile`) that runs with no Bun or Node.js on the target host. The binary embeds the entire runtime into a single executable:

- CLI command surface (`--version`, `validate`, `build`, `schema`, `init`, `agents list`)
- Migration sets (both dialects)
- Client bundles and island chunks
- Agent templates and example configs
- The native-free themed CSS engine

In compiled mode the binary reads its **embedded** assets, never the repo's on-disk `dist/`/`src/`/`specs/` trees — so it behaves identically when launched from any working directory on a customer machine. Embedded client bundles, island chunks, and the language-switcher script are served over HTTP from a binary-launched server (`GET /assets/output.css`, `GET /assets/client.js`, `GET /assets/islands/*`).

## Related Pages

- [Installation](/en/installation) — getting the binary and running it.
- [Environment Variables](/en/env-vars) — full env-var reference incl. `DATABASE_URL`, `SOVRIUM_DATA_DIR`.
- [Schema Migrations](/en/migrations) — the migration sets each dialect applies.
- [Buckets Overview](/en/buckets-overview) — local vs S3 storage, the `STORAGE_PROVIDER` twin.
- [Ecoconception](/en/ecoconception) — the `ECO_PAGE_CACHE` and broader frugal-by-default contract.
- [Admin Dashboard](/en/admin-dashboard) — `config/version` reports the active runtime.

# Security Hardening

Sovrium designs out the recurring failure modes of insecure apps — exposed surfaces, missing auth, broken object-level authorization, enumerable endpoints — at the platform layer, so every app inherits the defenses with no per-app configuration. Every HTTP response carries a hardened header set, CSRF is enforced in production, sensitive endpoints are rate-limited, and unauthorized access returns `404` rather than `403`.

These guarantees are applied **in code** (not only at the reverse-proxy ingress), so they hold even for a self-hosted deploy with no proxy attached.

## HTTP Security Headers

Every response — page, API, static asset, or `404` — carries a hardened header set, applied via Hono's `secureHeaders` middleware registered as the **first** `*` middleware so it runs before route matching and covers error responses.

| Header                                | Value / behavior                                                                                                |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Strict-Transport-Security`           | `max-age=31536000; includeSubDomains` (1-year HSTS, covers subdomains).                                         |
| `X-Content-Type-Options`              | `nosniff` (disables MIME sniffing).                                                                             |
| `X-Frame-Options`                     | `SAMEORIGIN` / `DENY` (anti-clickjacking).                                                                      |
| `Referrer-Policy`                     | `strict-origin-when-cross-origin`.                                                                              |
| `Cross-Origin-Opener-Policy`          | `same-origin`.                                                                                                  |
| `Cross-Origin-Resource-Policy`        | `same-origin`.                                                                                                  |
| `Permissions-Policy`                  | Denies camera, microphone, geolocation, payment, usb, accelerometer, …                                          |
| `Content-Security-Policy-Report-Only` | `default-src 'self'`, `frame-ancestors 'none'`, `object-src 'none'`, `base-uri 'self'`, `form-action 'self'`, … |
| `Content-Security-Policy` (enforced)  | **Absent** — report-only first; the enforced, nonce-based CSP is a Phase 2 promotion.                           |

:::callout
**CSP ships report-only first.** It surfaces violations without blocking while the SSR layer still emits inline `<script>`/`<style>`. The enforced header is deliberately absent for now, and a spec locks that absence in so a premature flip fails CI. The in-code directives mirror the Caddy ingress backstop so both layers agree.
:::

HSTS is emitted unconditionally even over plain HTTP — browsers ignore it on an `http://` connection, and a TLS-terminating proxy forwards exactly the value the server produces.

## CSRF & Cross-Origin Enforcement

Sovrium relies on Better Auth's built-in origin-check middleware. A state-changing, cookie-bearing request whose `Origin` is forged or stripped is rejected — a cross-site forgery cannot ride a victim's session cookie.

| Environment            | `disableCSRFCheck` | Behavior                                                                |
| ---------------------- | ------------------ | ----------------------------------------------------------------------- |
| `NODE_ENV=development` | `true`             | Origin check bypassed — forged `Origin` accepted (local cross-port DX). |
| `NODE_ENV=production`  | `false`            | Origin check active — forged / missing `Origin` rejected `403`.         |

- `trustedOrigins` is scoped to the app's own `BASE_URL` origin — **never** `'*'`. A wildcard is an open-redirect / origin-validation bypass; scoping it also makes Better Auth reject an external-origin `redirectTo` on password reset.
- `useSecureCookies` is enabled in production. Both the CSRF gate and secure cookies silently degrade if `NODE_ENV` is unset, so a missing-`NODE_ENV` risk is surfaced **loud** in the production startup banner (and suppressed in dev to keep output clean).

:::callout
**Set `NODE_ENV=production` in production.** CSRF enforcement and secure cookies both key off it. When unset, the server warns loudly in the startup banner — heed it before going live.
:::

## Rate Limiting

Sovrium replaces Better Auth's native rate limiting (known upstream bugs) with custom Hono middleware on the sensitive endpoints.

| Endpoint                                | Limit                     | Window |
| --------------------------------------- | ------------------------- | ------ |
| `POST /api/auth/sign-in/email`          | 5 attempts                | 60 s   |
| `POST /api/auth/sign-up/email`          | 5 attempts                | 60 s   |
| `POST /api/auth/request-password-reset` | 3 attempts                | 60 s   |
| `POST /api/auth/admin/*`                | General per-IP rate limit | —      |

Exceeding a limit returns `429 Too Many Requests`. Admin routes additionally run an auth-check middleware that returns `401` **before** parameter validation, so an unauthenticated caller never learns the shape of a protected endpoint.

## Anti-Enumeration: 404, Not 403

Unauthorized access to a protected resource returns **`404 Not Found`**, never `403 Forbidden`. A `403` confirms the resource exists; a `404` makes the resource's existence — and the id space — unobservable. This applies uniformly across record reads, the [admin dashboard](/en/admin-dashboard), and the per-table force-delete endpoint (which returns `404` when force-delete is not allowed for that table).

Object-level authorization is enforced before any sensitive logic runs: a request is authenticated, then checked for access to the specific object, and on failure returns `404`. Combined with unguessable ids, this defeats enumeration even though the `404` itself is observable.

## Defense-in-Depth Summary

| Concern                | Mechanism                                                                     |
| ---------------------- | ----------------------------------------------------------------------------- |
| Transport security     | HSTS (`max-age=31536000; includeSubDomains`).                                 |
| MIME / clickjacking    | `nosniff`, `X-Frame-Options`.                                                 |
| Cross-origin isolation | COOP + CORP `same-origin`, report-only CSP.                                   |
| CSRF                   | Better Auth origin check (production), scoped `trustedOrigins`.               |
| Brute-force            | Per-endpoint rate limiting (`429`).                                           |
| Enumeration            | `404`-not-`403`, unguessable ids, auth-check before validation.               |
| Authorization          | RBAC + [field-level permissions](/en/table-permissions), object-level checks. |

## Related Pages

- [Authentication Overview](/en/auth-overview) — auth strategies and the `auth` block.
- [Sessions](/en/auth-sessions) — session lifetime, revocation, secure cookies.
- [Roles & RBAC](/en/auth-roles-rbac) — role model and field-level permissions.
- [Table Permissions](/en/table-permissions) — per-table and per-field access control.
- [Admin Dashboard](/en/admin-dashboard) — the 404-on-unauthorized read surface.
- [GDPR & Privacy](/en/gdpr-privacy) — data export and erasure guarantees.
- [Environment Variables](/en/env-vars) — `NODE_ENV`, `BASE_URL`, and related settings.

# GDPR & Privacy

Sovrium gives end users self-service control over their personal data, satisfying the core GDPR rights without operator intervention. An authenticated user can download a complete, machine-readable copy of everything Sovrium holds about them, and can schedule an irreversible erasure of their account on a safe, reversible-until-final timeline.

These are end-user endpoints — they act on the caller's own data, scoped exclusively by the authenticated session. No id is ever taken from the request body.

## Data Export (Articles 15 & 20)

`GET /api/account/export` returns the caller's complete personal-data footprint as structured JSON, satisfying the GDPR **right of access** (Art. 15) and **right to data portability** (Art. 20).

```
GET /api/account/export
Cookie: <session cookie>
```

No request body, query, or path parameters — the user id comes only from the session. The response aggregates four sources for the caller:

| Source               | Contents                                                                                                              |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Profile**          | The caller's `auth.user` row.                                                                                         |
| **Sessions**         | The caller's `auth.session` rows.                                                                                     |
| **Linked accounts**  | The caller's `auth.account` rows (OAuth providers + email/password credential), **with all secret material omitted**. |
| **Authored records** | Every table record across the app where `created_by = caller`.                                                        |

:::callout
**Secrets are never exported.** Password hashes, OAuth tokens, and other credential material are stripped from the linked-accounts section. The export is a portability artifact, not a credential dump.
:::

## Account Deletion & Erasure (Article 17)

`POST /api/account/delete` lets a user request irreversible erasure of their account, satisfying the GDPR **right to erasure** (Art. 17). Deletion follows a **scheduled-erasure model with a 7-day grace period** — never an immediate destroy.

```
POST /api/account/delete
Cookie: <session cookie>
Content-Type: application/json

{ "confirm": true }
```

| Step            | Request                     | Effect                                                                                                                                                                                                                    |
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Schedule** | `{ "confirm": true }`       | Marks `scheduledErasureAt = now + 7 days`, revokes all of the caller's sessions (logged out everywhere), writes an `account.deletion.scheduled` audit event, returns `202 Accepted`. **Does not delete yet.**             |
| **2. Cancel**   | `{ "cancel": true }`        | During the window, the user signs back in and cancels — clears `scheduledErasureAt`, returns `200 OK`.                                                                                                                    |
| **3. Purge**    | _(automatic, after window)_ | A purge job **hard-deletes** the caller's `auth.user`, `auth.session`, `auth.account`, `auth.verification` rows and every table record where `created_by = caller`, then writes an `account.deletion.purged` audit event. |

A bare `POST` with no `confirm`/`cancel` flag is rejected `400` (anti-fat-finger).

## Hard Delete, Not Soft Delete

Erasure performs **physical row removal** — not the soft-delete `deleted_at` tombstone used elsewhere in the platform. After the purge, no recoverable personal data remains, as Art. 17 requires.

This is the deliberate exception to Sovrium's [soft-delete-by-default](/en/records-soft-delete) posture: ordinary deletes are recoverable tombstones, but a GDPR erasure must leave nothing behind. Per-table irreversible deletes via the admin dashboard require the explicit `allowForceDelete: true` opt-in (see [Table Permissions](/en/table-permissions)); the force-delete endpoint returns `404` when force-delete is not allowed.

:::callout
**The audit trail of erasure outlives the user.** The `account.deletion.purged` event survives the deleted user row — the `audit_log.actor_id` foreign key is `ON DELETE SET NULL`, so the entry remains a valid compliance record with a null-ified actor. Deleting the data and proving the data was deleted are two separate obligations.
:::

## Privacy by Design

Beyond the self-service rights, privacy is built into the platform defaults:

- **Cookie-free analytics** — visitors are identified by server-side SHA-256 hashes; no PII or client identifier is stored, and Do Not Track is respected. See [Analytics](/en/analytics).
- **Bounded retention** — soft-deleted rows age out per `ECO_RETENTION_PURGE_DAYS` (see [Ecoconception](/en/ecoconception)); less stored data is both a privacy and a frugality win.
- **No external services** — all personal data stays on your server; nothing is shipped to a third party.

## Related Pages

- [Activity Monitoring](/en/activity-monitoring) — the audit trail of deletion and access events.
- [Soft Delete](/en/records-soft-delete) — the recoverable tombstone model erasure deliberately bypasses.
- [Table Permissions](/en/table-permissions) — `allowForceDelete` and field-level access.
- [Security Hardening](/en/security-hardening) — auth, CSRF, anti-enumeration.
- [Analytics](/en/analytics) — cookie-free, privacy-first tracking.
- [Ecoconception](/en/ecoconception) — data retention and minimisation.

# Ecoconception

Sovrium treats environmental footprint as a **first-class platform property** — not a feature, not a paid tier, not a checkbox. The platform is frugal by default, the posture is operator-controlled through environment variables, and the footprint is measurable rather than aspirational. Owning your data and minimising its environmental cost are the same fight against absentee infrastructure.

The eco posture lives in `ECO_*` environment variables — the twin of `DATABASE_URL`, `STORAGE_PROVIDER`, and `AI_PROVIDER`. It is **never** part of the app schema: a schema author must not be able to silently disable frugality for the end users of their app (ADR 013).

## Core Principles

| Principle                                      | Meaning                                                                                                                          |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Frugal by default**                          | Every operator-facing toggle defaults to the eco-aligned setting. Operators opt _out_, never in.                                 |
| **Operator-controlled, not schema-controlled** | Eco posture is in env vars, not `app.eco.*`. Schema fields for eco are explicitly rejected.                                      |
| **Measurable, not aspirational**               | The platform commits to an `X-Eco-Index` response header and a page-weight budget; eco badges without measurement are forbidden. |

## The `ECO_*` Env-Var Contract

Frugal by default — operators opt out by overriding. These are the operator knobs for the platform's environmental posture.

| Env var                      | Default          | Options                                                           | Purpose                                                                                    |
| ---------------------------- | ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `ECO_MODE`                   | `balanced`       | `balanced` \| `lenient` (legacy `on`→`balanced`, `off`→`lenient`) | Master eco-posture toggle; gates the downstream sub-knobs.                                 |
| `ECO_IMAGE_FORMAT`           | `avif`           | `avif` \| `webp` \| `jpeg` \| `png`                               | Server-side image transcoding default. AVIF is ~50% smaller than JPEG.                     |
| `ECO_PAGE_CACHE`             | `on`             | `on` \| `off`                                                     | In-memory cache of static, request-invariant page HTML — skips `renderToString` on hits.   |
| `ECO_INDEX_HEADER`           | `on`             | `on` \| `off`                                                     | Emit the `X-Eco-Index` response header graded from transfer size.                          |
| `ECO_LOW_DATA_DEFAULT`       | `off`            | `on` \| `off` \| `respect-client`                                 | End-user low-data-mode posture (down-shift assets when on / on client hint).               |
| `ECO_AI_PROVIDER_PRECEDENCE` | `local-first`    | `local-first` \| `cloud-first` \| `local-only`                    | Routing precedence for AI calls; pairs with `AI_PROVIDER`.                                 |
| `ECO_AI_MAX_CARBON_CLASS`    | `G` (permissive) | `A`–`G`                                                           | Upper bound on the carbon class of a selected AI provider/region.                          |
| `ECO_PAGE_WEIGHT_BUDGET_KB`  | `500`            | integer                                                           | Per-page transfer budget for the page-weight gate.                                         |
| `ECO_RETENTION_PURGE_DAYS`   | `365`            | integer (`0` disables)                                            | Default soft-deleted-row purge horizon for tables that opt in.                             |
| `ECO_DESIGN_LAYER`           | `on`             | `on` \| `off`                                                     | Emit the always-on default design layer (an override surface, not a load-bearing default). |

:::callout
**Operators opt out, never in.** Each `ECO_*` toggle defaults to the eco-aligned value. To relax frugality you must explicitly set the variable — mirroring how `DATABASE_URL` defaults to SQLite and `STORAGE_PROVIDER` auto-selects local storage. Eco posture is never declared in the app schema.
:::

## Already-Aligned Foundations

Several Sovrium decisions serve frugality before any `ECO_*` variable is touched:

| Decision                                    | Footprint benefit                                                                                                           |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Standalone binary distribution              | One static binary, no Node runtime, fewer dependencies at boot. See [Database Infrastructure](/en/database-infrastructure). |
| SQLite + local-storage zero-config defaults | Single process, no managed cloud DB required.                                                                               |
| SSR + islands architecture                  | Only the active island ships; heavy editors lazy-load.                                                                      |
| Programmatic CSS compiler                   | Compiled per-theme on demand, in-memory cache — no megabyte static stylesheet. See [Theme](/en/theme).                      |
| Soft-delete with retention horizon          | Explicit purge-or-keep posture instead of infinite accumulation. See [Soft Delete](/en/records-soft-delete).                |
| Local-first AI option                       | Local inference avoids cross-Atlantic round-trips.                                                                          |

## Low-Data Mode

`ECO_LOW_DATA_DEFAULT` controls how aggressively Sovrium down-shifts asset weight for end users. When `on`, low-data variants (lower-resolution images, simpler renders) are served by default; with `respect-client`, the posture follows the visitor's `Save-Data` / `prefers-reduced-data` client hints; `off` always serves the full variant.

Low-data mode **down-shifts gracefully** — it never refuses to render a chart or rich-text editor. Paternalistic feature-blocking is an explicit anti-pattern; eco posture lowers fidelity, it does not break a user's workflow.

## Measurement: `X-Eco-Index`

When `ECO_INDEX_HEADER=on`, page responses carry an `X-Eco-Index` header graded (A–G) from the response transfer size against tiered thresholds (the largest sitting at `ECO_PAGE_WEIGHT_BUDGET_KB`). This makes the footprint observable per response rather than a marketing claim — eco badges without a measured number are forbidden (ADR 013).

## Eco Dashboard

The admin eco dashboard surfaces the running posture: an RGESN self-evaluation tile, the AI provider mix by carbon class, the top storage consumers, and the current `ECO_*` settings in force. It reads the same measured signals (the `X-Eco-Index` grades, the page-weight budget) the platform emits — never a synthetic "Eco Mode On" badge.

## Anti-Patterns

- **Greenwashing badges** — rendering an "Eco Mode On" badge without a measured footprint number.
- **Paternalistic feature blocking** — refusing to render content because of an eco posture; always down-shift gracefully.
- **Paid eco tier** — gating eco features behind a license key. All eco posture is free in self-hosted mode.
- **Schema-level eco config** — adding `app.eco.lowDataMode = true`. Eco is operator-controlled; use env vars.
- **Hardcoded cloud AI calls** — bypassing `ECO_AI_PROVIDER_PRECEDENCE` and calling a cloud provider directly. Always route through the precedence resolver.

## Related Pages

- [Database Infrastructure](/en/database-infrastructure) — `ECO_PAGE_CACHE` and the static render cache.
- [Theme](/en/theme) — the programmatic CSS compiler and `ECO_DESIGN_LAYER`.
- [Soft Delete](/en/records-soft-delete) — the retention horizon `ECO_RETENTION_PURGE_DAYS` governs.
- [GDPR & Privacy](/en/gdpr-privacy) — data minimisation as a privacy-and-frugality twin.
- [Analytics](/en/analytics) — bounded retention and cookie-free tracking.
- [Environment Variables](/en/env-vars) — full env-var reference.

# JSON Schema

The Sovrium app schema defines the complete structure of your application configuration. It is published as a standard **JSON Schema (Draft-07)**, derived directly from the canonical Effect Schema (`AppSchema`). Use it for editor autocomplete, real-time validation, CI config checks, and programmatic verification.

Three artifacts share that single source of truth:

| Artifact            | Format             | Generated by       | Use it for                                  |
| ------------------- | ------------------ | ------------------ | ------------------------------------------- |
| JSON Schema         | JSON (Draft-07)    | `sovrium schema`   | Editor autocomplete, CI validation          |
| `@sovrium/types`    | TypeScript `.d.ts` | npm package        | `defineConfig()` autocompletion in `app.ts` |
| AppSchema validator | runtime decode     | `sovrium validate` | Verifying a config file before deploy       |

:::callout
**Interactive Schema Explorer.** Browse the full schema visually with the JSON Schema Viewer. Expand properties, view types, and explore nested structures.

[Open Schema Explorer ↗](https://json-schema.app/view/%23?url=https%3A%2F%2Fsovrium.com%2Fschema%2Fapp.json)
:::

## Generating the schema

The CLI prints the JSON Schema for the Sovrium app configuration. By default it writes to stdout; pass `--output <path>` to write a file instead.

```bash
# Print the JSON Schema to stdout
sovrium schema

# Write the JSON Schema to a file
sovrium schema --output app.schema.json
```

The generated document is a self-contained Draft-07 schema with a top-level `$schema` declaration, so any JSON-Schema-aware tool can consume it without further configuration. See the [CLI Reference](/en/cli) for the full command surface.

## Root properties at a glance

The schema's root object accepts the following top-level properties. Every property except `name` is optional and layered on top.

| Property      | Type       | Description                                              |
| ------------- | ---------- | -------------------------------------------------------- |
| `name`        | `string`   | Application name (required)                              |
| `version`     | `string`   | App config version string                                |
| `description` | `string`   | Human-readable description                               |
| `tables`      | `object[]` | Data tables (see [Tables Overview](/en/tables-overview)) |
| `pages`       | `object[]` | Pages and their sections                                 |
| `forms`       | `object[]` | Standalone forms                                         |
| `auth`        | `object`   | Authentication and RBAC configuration                    |
| `theme`       | `object`   | Design tokens (colors, fonts, spacing)                   |
| `components`  | `object[]` | Reusable components                                      |
| `automations` | `object[]` | Trigger/action workflows                                 |
| `connections` | `object[]` | External service connections                             |
| `languages`   | `object`   | Internationalization / i18n                              |
| `analytics`   | `object`   | Privacy-friendly analytics                               |
| `agents`      | `object[]` | AI agents                                                |

## Schema URLs

Reference the hosted Sovrium JSON Schema by URL in your editor, CI pipeline, or validation scripts.

### Versioned (recommended)

Pin to a specific version for production stability. The schema URL includes the exact package version.

```
https://sovrium.com/schema/app-0.10.0.json
```

### Latest

Always points to the most recent version. Convenient for development, but may introduce breaking changes.

```
https://sovrium.com/schema/app.json
```

## Editor integration

Add the JSON Schema to your editor for autocomplete, inline documentation, and real-time validation as you write your Sovrium config.

### VS Code

VS Code supports JSON Schema natively for both JSON and YAML files (the YAML extension is required for `.yaml`/`.yml`).

**Option 1: Add `$schema` directly to your config file**

```yaml
# yaml-language-server: $schema=https://sovrium.com/schema/app.json
name: my-app
```

You can also point the directive at a locally generated file:

```yaml
# yaml-language-server: $schema=./app.schema.json
name: my-app
```

**Option 2: Configure in VS Code `settings.json`**

```json
{
  "yaml.schemas": {
    "https://sovrium.com/schema/app.json": ["app.yaml", "*.sovrium.yaml"]
  },
  "json.schemas": [
    {
      "fileMatch": ["app.json", "*.sovrium.json"],
      "url": "https://sovrium.com/schema/app.json"
    }
  ]
}
```

### JetBrains

IntelliJ IDEA, WebStorm, and other JetBrains IDEs support JSON Schema mapping natively.

Go to **Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings**. Click **+** to add a new mapping, paste the schema URL (or the path to a generated `app.schema.json`), and set the file pattern to match your config file (e.g., `app.yaml` or `app.json`).

## TypeScript autocompletion with `@sovrium/types`

When you author your configuration as a TypeScript file (`app.ts`) instead of YAML/JSON, the zero-dependency `@sovrium/types` package gives you full IDE autocompletion, inline type errors, and jump-to-definition — backed by the same `AppSchema`.

```bash
bun add -d @sovrium/types
```

Wrap your config in `defineConfig()` to get type-checked autocompletion as you type:

```typescript
import { defineConfig } from '@sovrium/types'

export default defineConfig({
  name: 'my-app',
  description: 'My Sovrium application',
  tables: [
    {
      id: 1,
      name: 'contacts',
      fields: [{ id: 1, name: 'email', type: 'email', required: true }],
    },
  ],
})
```

:::callout
**Zero runtime dependencies.** `@sovrium/types` ships only TypeScript type definitions (generated from `AppSchema`), so it adds nothing to your bundle and stays MIT-licensed. The CLI accepts `app.ts` directly — `sovrium start app.ts`, `sovrium validate app.ts`.
:::

## Validating a config file

Use `sovrium validate` to check a configuration file against `AppSchema` before deploying. It accepts `.json`, `.yaml`, `.yml`, and `.ts` files, resolving any `$ref` includes first.

```bash
# Validate a YAML config
sovrium validate app.yaml

# Validate a JSON config
sovrium validate config.json

# Validate a TypeScript config
sovrium validate app.ts
```

On success it prints `Valid configuration: <name>` and exits `0`. On failure it prints the structural decode errors (formatted as a tree) plus any post-decode findings — unknown field types and gated `type: cloud` actions — then exits `1`.

| Exit code | Meaning                                                            |
| --------- | ------------------------------------------------------------------ |
| `0`       | Config is valid                                                    |
| `1`       | Config is invalid (decode error, unknown field type, missing file) |

:::callout
**Unknown field types are caught at validate time.** A field whose `type` is not one of the [49 known field types](/en/field-types-overview) passes the structural decode but is flagged by `sovrium validate` (and would otherwise fail during SQL generation). Validating early surfaces these before runtime.
:::

## Programmatic validation

For CI pipelines, run `sovrium validate` as a build step and gate on its exit code:

```bash
sovrium validate app.yaml || exit 1
```

For richer integrations, you can also serve the live schema over HTTP from a running instance (admin-only) and feed it to external tooling — see [OpenAPI](/en/openapi) for the full HTTP schema surface.

# API Reference

Sovrium exposes a complete REST API for managing tables, records, views, activity logs, analytics, authentication, and admin schema management. All endpoints accept and return JSON, enforce RBAC with field-level permissions, and emit a single canonical error envelope.

:::callout
**Early Preview.** The API surface is evolving. Endpoints may change before v1.0.
:::

## Base URL

All endpoints are relative to your Sovrium instance base URL.

```
http://localhost:3000/api
```

## Authentication & access control

The API uses session-based authentication (Better Auth). Requests that touch protected resources must carry a valid session cookie or `Authorization: Bearer <token>` header. Access is governed by **RBAC** (admin, member, viewer) with **field-level permissions** layered on top.

Per the anti-enumeration policy, an authenticated request that lacks read access to a resource returns **404** (not 403), so the caller cannot distinguish "not found" from "no access". A genuine **403** is reserved for surfaces where the resource is known to exist but the action is denied (e.g. a non-admin hitting `GET /api/admin/schema/versions`).

## Error response contract

All 4xx/5xx responses use a single canonical JSON envelope, so one decoder covers every error.

**Generic 4xx/5xx envelope:**

```json
{
  "success": false,
  "message": "Authentication required",
  "code": "UNAUTHORIZED"
}
```

The `code` is drawn from a stable enum: `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `VALIDATION_ERROR`, `CONFLICT`, `RATE_LIMITED`, `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE`. Optional `error` (legacy type identifier) and `details` may also be present.

**Validation 400 envelope** — when the failure is field-level, an `errors[]` array names each offending field:

```json
{
  "success": false,
  "message": "One or more fields failed validation",
  "code": "VALIDATION_ERROR",
  "errors": [{ "field": "id", "message": "Cannot write to readonly field 'id'" }]
}
```

| Status | `code`              | Meaning                                             |
| ------ | ------------------- | --------------------------------------------------- |
| `400`  | `VALIDATION_ERROR`  | Field-level validation failure (carries `errors[]`) |
| `401`  | `UNAUTHORIZED`      | No / expired session                                |
| `403`  | `FORBIDDEN`         | Authenticated, action denied (resource known)       |
| `404`  | `NOT_FOUND`         | Not found, or anti-enumeration access denial        |
| `413`  | `PAYLOAD_TOO_LARGE` | Batch payload exceeds the limit                     |
| `429`  | `RATE_LIMITED`      | Rate limit exceeded                                 |
| `500`  | `INTERNAL_ERROR`    | Unexpected server error (details redacted)          |

## Health

Server health check endpoint (unauthenticated).

| Method | Path          | Description         |
| ------ | ------------- | ------------------- |
| `GET`  | `/api/health` | Check server status |

## Tables

Read table definitions, including field schemas and permission rules.

| Method | Path                                | Description           |
| ------ | ----------------------------------- | --------------------- |
| `GET`  | `/api/tables`                       | List all tables       |
| `GET`  | `/api/tables/{tableId}`             | Get table by ID       |
| `GET`  | `/api/tables/{tableId}/permissions` | Get table permissions |

## Records

Full CRUD, batch operations, soft-delete lifecycle, revision history, and record comments. See [Records Overview](/en/records-overview) for the data model.

### CRUD

| Method   | Path                                       | Description          |
| -------- | ------------------------------------------ | -------------------- |
| `GET`    | `/api/tables/{tableId}/records`            | List records         |
| `POST`   | `/api/tables/{tableId}/records`            | Create a record      |
| `GET`    | `/api/tables/{tableId}/records/{recordId}` | Get record by ID     |
| `PATCH`  | `/api/tables/{tableId}/records/{recordId}` | Update a record      |
| `DELETE` | `/api/tables/{tableId}/records/{recordId}` | Soft-delete a record |

### Batch operations

| Method   | Path                                   | Description                  |
| -------- | -------------------------------------- | ---------------------------- |
| `POST`   | `/api/tables/{tableId}/records/batch`  | Create multiple records      |
| `PATCH`  | `/api/tables/{tableId}/records/batch`  | Update multiple records      |
| `DELETE` | `/api/tables/{tableId}/records/batch`  | Soft-delete multiple records |
| `POST`   | `/api/tables/{tableId}/records/upsert` | Create or update a record    |

### Trash & history

| Method | Path                                               | Description                 |
| ------ | -------------------------------------------------- | --------------------------- |
| `GET`  | `/api/tables/{tableId}/trash`                      | List trashed records        |
| `POST` | `/api/tables/{tableId}/records/{recordId}/restore` | Restore a deleted record    |
| `POST` | `/api/tables/{tableId}/records/batch/restore`      | Restore multiple records    |
| `GET`  | `/api/tables/{tableId}/records/{recordId}/history` | Get record revision history |

### Comments

| Method   | Path                                                | Description               |
| -------- | --------------------------------------------------- | ------------------------- |
| `GET`    | `/api/tables/{tableId}/records/{recordId}/comments` | List comments on a record |
| `POST`   | `/api/tables/{tableId}/records/{recordId}/comments` | Add a comment             |
| `GET`    | `.../{recordId}/comments/{commentId}`               | Get comment by ID         |
| `PATCH`  | `.../{recordId}/comments/{commentId}`               | Update a comment          |
| `DELETE` | `.../{recordId}/comments/{commentId}`               | Delete a comment          |

## Views

Pre-configured views that filter, sort, and group records from a table.

| Method | Path                                           | Description                |
| ------ | ---------------------------------------------- | -------------------------- |
| `GET`  | `/api/tables/{tableId}/views`                  | List views for a table     |
| `GET`  | `/api/tables/{tableId}/views/{viewId}`         | Get view by ID             |
| `GET`  | `/api/tables/{tableId}/views/{viewId}/records` | Get records through a view |

## Activity

Audit log of data changes across all tables.

| Method | Path                         | Description           |
| ------ | ---------------------------- | --------------------- |
| `GET`  | `/api/activity`              | List activity entries |
| `GET`  | `/api/activity/{activityId}` | Get activity detail   |

## Analytics

Privacy-friendly, cookie-free usage analytics.

| Method | Path                       | Description               |
| ------ | -------------------------- | ------------------------- |
| `POST` | `/api/analytics/collect`   | Collect a page view event |
| `GET`  | `/api/analytics/overview`  | Get analytics overview    |
| `GET`  | `/api/analytics/pages`     | Get top pages             |
| `GET`  | `/api/analytics/referrers` | Get top referrers         |
| `GET`  | `/api/analytics/devices`   | Get device breakdown      |
| `GET`  | `/api/analytics/campaigns` | Get campaign stats        |

## Admin: schema management

Live schema editing (draft → validate → publish) for admin users. Registered only when `app.auth` is configured and `SCHEMA_EDIT_API_ENABLED=true`; otherwise every `/api/admin/schema/*` path returns 404. All routes require the `admin` role.

| Method | Path                                   | Description                        |
| ------ | -------------------------------------- | ---------------------------------- |
| `GET`  | `/api/admin/schema/status`             | Drift / draft status               |
| `GET`  | `/api/admin/schema/diff`               | Preview live-vs-file drift         |
| `GET`  | `/api/admin/schema/export`             | Serialize the live version as YAML |
| `GET`  | `/api/admin/schema/draft`              | Get the working draft              |
| `PUT`  | `/api/admin/schema/draft`              | Replace the working draft          |
| `POST` | `/api/admin/schema/draft/discard`      | Discard the draft                  |
| `POST` | `/api/admin/schema/draft/validate`     | Validate the draft                 |
| `POST` | `/api/admin/schema/draft/publish`      | Publish the draft (new version)    |
| `POST` | `/api/admin/schema/draft/rebase`       | Rebase a stale draft on active     |
| `GET`  | `/api/admin/schema/versions`           | List published versions            |
| `GET`  | `/api/admin/schema/versions/{version}` | Get a version                      |
| `POST` | `.../versions/{version}/restore`       | Restore a version                  |

Per-resource draft mutations (`/api/admin/schema/draft/tables`, `/pages`, `/auth/strategies`, `/forms`, `/automations`, `/connections`, `/preview`) and the `/api/admin/schema/prune` operation round out the surface. Each REST endpoint is mirrored as an MCP tool (`{appName}_schema_*`) for AI agents.

## Authentication endpoints

Authentication is handled by Better Auth and mounted at `/api/auth/*`. It includes email/password sign-in and sign-up, social OAuth providers, session management, password reset, email verification, two-factor authentication, magic links, email OTP, organizations, and admin user management. See the [Auth configuration docs](/en/auth-overview) for setup, or explore every auth endpoint in the live API documentation.

Admins can browse the full machine-readable surface at `/api/scalar` and fetch the raw OpenAPI documents — see [OpenAPI](/en/openapi).

## Cross-cutting features

Capabilities that apply across all API endpoints.

- **Pagination** — list endpoints page their results
- **Soft deletes** — `DELETE` trashes (recoverable); a separate purge hard-deletes
- **RBAC** — admin / member / viewer roles gate every protected route
- **Field-level permissions** — granular read/write control per field per role
- **Rate limiting** — auth and admin endpoints are rate-limited
- **Canonical error envelope** — every 4xx/5xx shares one shape (see above)

# LLM Reference

Sovrium provides machine-readable documentation files designed for Large Language Models (LLMs) and AI coding assistants. Use these files to give AI tools full context about the Sovrium app schema, CLI, API, and configuration format.

:::callout
**Download LLM Documentation.** Plain-text files optimized for AI tools like Claude, ChatGPT, GitHub Copilot, and Cursor.

- [llms.txt ↗](/llms.txt) — compact quick reference
- [llms-full.txt ↗](/llms-full.txt) — comprehensive single-file reference
  :::

## What is llms.txt?

An emerging standard for providing documentation to AI assistants in a machine-friendly format.

The llms.txt convention is a growing standard where websites serve plain-text documentation files at well-known URLs (`/llms.txt` and `/llms-full.txt`). These files are specifically formatted for Large Language Models to consume, providing structured information about the project, its APIs, configuration format, and capabilities. Sovrium publishes two files: a compact quick reference for fast lookups, and a comprehensive full reference for generating configurations and answering detailed questions.

## The Files

Two documentation files optimized for different use cases.

### `llms.txt`

```
https://sovrium.com/llms.txt
```

Compact overview with links to all documentation sections. Best for quick context and navigation.

- **Size**: About 40 lines — fits easily in any LLM context window.
- **Use case**: Use when you need a quick summary or want to point an AI tool to specific documentation sections.

### `llms-full.txt`

```
https://sovrium.com/llms-full.txt
```

Complete documentation covering the entire Sovrium platform. Best for deep AI assistance.

- **Size**: About 3000 lines — comprehensive, single-file reference.
- **Use case**: Use when you want an AI assistant to have full context about Sovrium, generate configurations, or answer detailed questions.

The full reference covers:

- Getting Started guides
- Schema Overview & Root Properties
- All 49 Field Types
- All Component Types
- Authentication configuration
- Theme & design tokens
- Pages & interactions
- Languages & i18n
- Analytics configuration
- API Reference (records, auth, admin, health)
- Complete YAML examples
- JSON Schema reference

:::callout
**Auto-synced with releases.** Both files are automatically updated with every Sovrium release to reflect the latest schema version, field types, component types, and API endpoints. The current version is always accurate.
:::

## Usage with AI Tools

How to feed Sovrium documentation to your AI assistant of choice.

Fetch the documentation directly:

```bash
# Quick reference (~40 lines)
curl https://sovrium.com/llms.txt

# Complete documentation (~2700 lines)
curl https://sovrium.com/llms-full.txt
```

Paste the URL or content into your AI assistant with a prompt like:

```
Read the Sovrium documentation from https://sovrium.com/llms-full.txt
and help me create an app.yaml configuration for a blog with:
- A posts table with title, content, and published_at fields
- Email/password authentication
- A homepage with a list of recent posts
```

:::callout
**Which file to use?** Start with `llms.txt` for quick questions about what Sovrium can do. Use `llms-full.txt` when you need the AI to generate complete configurations, understand all field types, or work with the full API.
:::

## Building Sovrium apps with AI

Because a Sovrium app is a single declarative config file, it is an ideal target for AI-assisted authoring. A practical loop:

1. **Give the AI context.** Point it at `llms-full.txt` so it knows the full schema — all [49 field types](/en/field-types-overview), component types, auth options, and the [REST API surface](/en/api-reference).
2. **Author in TypeScript for type safety.** Have the AI generate an `app.ts` using `defineConfig()` from [`@sovrium/types`](/en/json-schema#typescript-autocompletion-with-sovriumtypes). Your editor then validates the AI's output as it writes, catching invalid field types and misshaped sections inline.
3. **Validate before running.** Run `sovrium validate app.ts` (see the [CLI Reference](/en/cli)) to confirm the config decodes against `AppSchema`, surfacing unknown field types and structural errors with exit code `1`.
4. **Iterate against the running app.** Start with `sovrium start app.ts --watch`; the AI can refine the config and the server hot-reloads on save.

:::callout
**Type-checked output beats free-text guesses.** Pairing `llms-full.txt` (context) with `@sovrium/types` (compile-time validation) and `sovrium validate` (runtime decode) gives the AI a tight feedback loop — generated configs are checked at author time and validate time, before they ever boot.
:::

# OpenAPI

Sovrium describes its HTTP API as standard **OpenAPI 3.1** documents, generated from the same Zod request/response schemas (`src/domain/models/api/`) that validate live traffic. Because the OpenAPI documents expose the full API shape, they are served **admin-only** at runtime — never to unauthenticated or non-admin callers.

:::callout
**Admin-only by design.** Exposing the API schema to the public would leak the internal surface. Sovrium gates all OpenAPI endpoints behind the `admin` role. When `app.auth` is not configured, the endpoints are not registered at all (every path returns 404).
:::

## What is generated

Two OpenAPI documents plus one interactive explorer, served by a running Sovrium instance.

| Endpoint                     | Returns          | Description                                 |
| ---------------------------- | ---------------- | ------------------------------------------- |
| `GET /api/openapi.json`      | OpenAPI 3.1 JSON | The application API (tables, records, etc.) |
| `GET /api/auth/openapi.json` | OpenAPI 3.1 JSON | The Better Auth API surface                 |
| `GET /api/scalar`            | HTML (Scalar UI) | Unified interactive explorer for both       |

The application document is produced by an internal `getOpenAPIDocument(app)` helper; the auth document is generated by Better Auth's `generateOpenAPISchema()`. The Scalar UI mounts both as switchable sources ("API" and "Auth").

## Access control

All three endpoints share one admin guard.

| Caller                       | `/api/openapi.json` | Reason                                                |
| ---------------------------- | ------------------- | ----------------------------------------------------- |
| Unauthenticated              | `401 UNAUTHORIZED`  | No session (standard HTTP authn semantics)            |
| Authenticated, non-admin     | `404 NOT_FOUND`     | Anti-enumeration: authz denial looks like "not found" |
| Authenticated admin          | `200` + document    | Full access                                           |
| Any caller, `app.auth` unset | `404 NOT_FOUND`     | Routes never registered                               |

The 401/404 envelopes follow the [canonical error contract](/en/api-reference#error-response-contract).

## Fetching the documents

From a running instance, an admin can fetch the raw documents (session cookie or `Authorization: Bearer <token>` required):

```bash
# Application API schema
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/openapi.json

# Better Auth API schema
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/auth/openapi.json
```

Save a document to disk to feed it to external tooling:

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/openapi.json -o app.openapi.json
```

:::callout
**No standalone `export` command yet.** Sovrium does not currently ship a user-facing `sovrium openapi` CLI subcommand — the OpenAPI documents are generated and served by the running server at the admin-only routes above. To produce a static file, fetch the route as an admin and redirect to a file (shown above). The JSON Schema, by contrast, _does_ have a dedicated command — see [`sovrium schema`](/en/json-schema#generating-the-schema).
:::

## Scalar API explorer

Visit `/api/scalar` in a browser while signed in as an admin to browse, search, and try out every endpoint. The explorer renders both the application and Better Auth documents from a single page.

```
http://localhost:3000/api/scalar
```

It surfaces request/response schemas, status codes, and the canonical error envelope, and lets you issue authenticated requests directly from the page.

## External tool integration

Because the documents are standard OpenAPI 3.1, any compatible tool can consume them once you have fetched the JSON as an admin.

| Tool               | How to use the document                                            |
| ------------------ | ------------------------------------------------------------------ |
| Postman            | Import → File → select `app.openapi.json` to generate a collection |
| Insomnia           | Import / Export → Import Data → From File                          |
| openapi-typescript | Generate typed clients from `app.openapi.json`                     |
| Redoc / Swagger UI | Point the viewer at the fetched JSON file                          |

For client-side TypeScript types of the _config_ (not the API), prefer [`@sovrium/types`](/en/json-schema#typescript-autocompletion-with-sovriumtypes); for API client generation, use the OpenAPI document above.

## How it stays in sync

The application OpenAPI document is derived from the same Zod schemas the routes use for validation, and the auth document is generated by Better Auth at request time. There is no separately maintained spec file to drift — adding or changing an endpoint's request/response schema updates the generated document automatically. See the [API Reference](/en/api-reference) for the human-readable endpoint map.

# License

Sovrium is released under the **Business Source License 1.1 (BSL 1.1)**. This page summarizes what that means in practice. The authoritative terms are in the [`LICENSE.md`](https://github.com/sovrium/sovrium/blob/main/LICENSE.md) file at the root of the repository.

:::callout
The Business Source License is **not** an open-source license today, but the Licensed Work automatically converts to a true open-source license on the Change Date. Until then, every feature is free to use in self-hosted mode — there is no paid edition, no license keys, and no feature gates.
:::

## What you can do

You may use Sovrium for **any purpose**, with a single restriction described below. Permitted uses explicitly include:

- Internal business applications for your organization
- Client deployments where the client self-hosts and controls the software
- Non-commercial personal projects
- Educational and research purposes
- Contributing improvements back to the project

## The one restriction

You may **not** use Sovrium to provide a hosted or managed service to third parties where Sovrium — or a substantial portion of its functionality — provides the primary value of that service.

"Third parties" means individuals or organizations other than you, your employees, your contractors working solely on your behalf, or your wholly-owned subsidiaries.

Restricted uses (which require a separate commercial license) include:

- Offering "Sovrium Cloud Hosting" as a service to customers
- Embedding Sovrium as the core feature of a SaaS platform offered to third parties
- Providing managed Sovrium instances to customers as a commercial offering
- White-labeling Sovrium and selling it as a hosted service

## Change Date

On **2030-06-02** — four years from this version's release — the license automatically converts to the **Apache License, Version 2.0**. From that date, the corresponding version of Sovrium is fully open source.

## Copyright

The Licensed Work is Copyright (c) 2025-2026 ESSENTIAL SERVICES. Every source file carries the BSL 1.1 header.

## Commercial licensing

If your use falls under the restriction above, a commercial license is available. Contact **license@sovrium.com**.

## See also

- [Trademark](/en/trademark) — how the "Sovrium" name and logo may be used
- [Contributing](/en/contributing) — how to propose changes

# Trademark

**Sovrium** is a registered trademark of **ESSENTIAL SERVICES** (registered in France, and potentially other jurisdictions). This page summarizes the trademark usage guidelines. The full notice lives in [`TRADEMARK.md`](https://github.com/sovrium/sovrium/blob/main/TRADEMARK.md) at the root of the repository.

## Copyright versus trademark

The project keeps copyright and trademark deliberately separate:

| Legal aspect | Owner              | What it protects                                                                  |
| ------------ | ------------------ | --------------------------------------------------------------------------------- |
| Copyright    | ESSENTIAL SERVICES | The source code, documentation, and creative works (under [BSL 1.1](/en/license)) |
| Trademark    | ESSENTIAL SERVICES | The "Sovrium" brand name and logo                                                 |
| Domain       | ESSENTIAL SERVICES | The sovrium.com web property                                                      |

This separation means the code can eventually become open source while the brand stays protected.

## Permitted use

You may use the name "Sovrium" when:

- Referring to this software factually ("built with Sovrium", "compatible with Sovrium")
- Describing your own project that uses Sovrium ("MyApp uses Sovrium for its backend")
- Contributing to the Sovrium project
- Writing tutorials or documentation about Sovrium

## Prohibited use

You may **not** use "Sovrium" to:

- Name your own product or service (e.g. "Sovrium Cloud", "Sovrium Plus")
- Imply official endorsement without permission
- Create confusion about the source or origin of a product
- Register similar trademarks or domain names

## Commercial and brand use

Commercial use of the Sovrium **software** requires a commercial license (see [License](/en/license)). Use of the Sovrium **trademark** in commercial contexts requires explicit permission from ESSENTIAL SERVICES.

For trademark licensing inquiries, contact **license@sovrium.com**.

## See also

- [License](/en/license) — the BSL 1.1 terms for the code
- [Contributing](/en/contributing) — how to propose changes

# Contributing

Sovrium is built in the open and welcomes contributions. Whether you are fixing a typo, improving the documentation, reporting a bug, or proposing a feature, this page explains how to get started.

## Ways to contribute

- **Report a bug or request a feature** — open an issue on [GitHub](https://github.com/sovrium/sovrium/issues) with a clear description and, where possible, a minimal reproduction.
- **Improve the documentation** — these docs are part of the repository; corrections and clarifications are always welcome.
- **Submit a pull request** — implement a fix or feature and open a PR for review (requires certification — see below).

## Becoming a certified contributor

Opening issues and reporting bugs is open to everyone. **Submitting code, however, requires becoming a certified contributor.** To get certified, contact us at **contribute@sovrium.com** and we will guide you through the process.

We introduced this step deliberately. The volume of unsolicited, AI-generated pull requests has made open contribution unsustainable for many projects — maintainers end up spending more time triaging low-effort, machine-written patches than building. Certification lets us:

- **Keep review capacity for real work** — we are not overwhelmed by a flood of automated, drive-by PRs.
- **Guarantee a high-quality contributor community** — certified contributors understand the codebase, the architecture, and the standards before they ship.

Certification is not a paywall and not a popularity contest — it is a short conversation to confirm you are a person who will contribute thoughtfully. Once certified, your pull requests are reviewed and merged like any other.

## Before you start

- Search existing [issues](https://github.com/sovrium/sovrium/issues) and pull requests to avoid duplicating work.
- For anything non-trivial, open an issue first to discuss the approach before writing code — it saves everyone time.
- By contributing, you agree that your contribution is licensed under the project's [Business Source License 1.1](/en/license).

## Development setup

Sovrium runs on [Bun](https://bun.sh) (1.3+). Clone the repository and install dependencies:

```bash
git clone https://github.com/sovrium/sovrium
cd sovrium
bun install
```

Run the app from source:

```bash
bun run start path/to/your/app.ts
```

Validate a configuration file against the schema:

```bash
bun run src/cli/index.ts validate path/to/your/app.ts
```

## Coding standards

- **TypeScript** throughout, written for the Bun runtime.
- **Conventional commits** — prefix messages with `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, etc.
- Keep changes focused — one logical change per pull request makes review faster.
- Match the surrounding code style; the repository's formatter and linter define the conventions.

## Submitting a pull request

1. Fork the repository and create a topic branch.
2. Make your change with a clear, conventional commit message.
3. Open a pull request describing **what** changed and **why**.
4. Respond to review feedback — maintainers will help shepherd the change to merge.

## Trademark note

Contributing code does not grant any right to the **Sovrium** name or logo. See the [Trademark](/en/trademark) page for how the brand may be used.

## See also

- [License](/en/license) — the BSL 1.1 terms
- [Trademark](/en/trademark) — brand usage guidelines

# Introduction

Sovrium est une plateforme source-available, auto-hébergée qui transforme un seul fichier de configuration en une application web complète.

:::callout
**Sovrium v0.10.0 — Développement actif.** Ce projet est en cours de développement actif. Les API, le format de configuration et les fonctionnalités peuvent évoluer d'une version à l'autre.
:::

## Qu'est-ce que Sovrium ?

Sovrium est une plateforme applicative pilotée par la configuration. Vous décrivez votre application dans un fichier YAML ou JSON (modèles de données, authentification, pages, thèmes, analytique) et Sovrium la transforme en une application web full-stack opérationnelle.

Aucun code générique, aucune configuration de framework, aucun pipeline de build. Juste un fichier qui déclare ce que votre application doit être.

```yaml
name: my-app

tables:
  - id: 1
    name: tasks
    fields:
      - id: 1
        name: title
        type: single-line-text
        required: true

auth:
  strategies:
    - type: emailAndPassword

theme:
  colors:
    primary: '#3b82f6'
```

## Pourquoi Sovrium ?

La plupart des applications métier partagent les mêmes briques de base : tables de données, authentification des utilisateurs, pages rendues côté serveur et système de design. Sovrium fournit tout cela d'emblée, configuré via un seul schéma.

### Aucune dépendance à un fournisseur

Auto-hébergé sur votre infrastructure. Vos données restent les vôtres.

### La configuration plutôt que le code

Déclarez ce dont vous avez besoin au lieu d'écrire du code générique. 49 types de champs, environ 80 types de composants, authentification intégrée.

### Complexité progressive

Commencez avec un simple nom. Ajoutez des tables, un thème, des pages, l'authentification et l'analytique à mesure que vos besoins grandissent.

### Code source disponible

Business Source License 1.1. Gratuit pour un usage interne. Devient Apache 2.0 en 2030.

## Comment ça fonctionne

Écrivez un fichier de configuration, exécutez une seule commande et obtenez une application opérationnelle :

1. Définissez votre schéma en YAML ou JSON
2. Exécutez `sovrium start app.yaml`
3. Obtenez une application full-stack avec tables de données, authentification, pages et bien plus encore

## Étapes suivantes

Prêt à l'essayer ? Installez Sovrium et créez votre première application en moins de 5 minutes.

:::callout
**Installation** — Installez Sovrium globalement ou comme dépendance de projet à l'aide de Bun.
:::

## Obtenir de l'aide

Vous avez trouvé un bug, vous avez une question ou vous souhaitez proposer une fonctionnalité ?

Sovrium est open source. Si vous rencontrez un problème ou si vous avez des idées d'amélioration, le meilleur moyen de nous joindre est via les Issues GitHub.

[Ouvrir une issue sur GitHub →](https://github.com/sovrium/sovrium/issues)

# Installation

Installez Sovrium globalement ou comme dépendance de projet à l'aide de Bun.

## Prérequis

Les tables et l'authentification fonctionnent d'emblée sur une base de données SQLite embarquée — aucune configuration requise. PostgreSQL 15+ est optionnel et débloque des fonctionnalités avancées (SQL brut, recherche vectorielle). L'exécution depuis les sources ou en tant que bibliothèque nécessite [Bun 1.3+](https://bun.sh).

## Binaire autonome (recommandé)

Sovrium est distribué sous forme de binaire autonome — c'est la méthode d'installation recommandée. Aucun environnement d'exécution à installer séparément.

```bash
# Script d'installation
curl -fsSL https://sovrium.com/install | sh

# Homebrew
brew install sovrium/tap/sovrium

# Docker
docker pull ghcr.io/sovrium/sovrium:latest
```

Après l'installation, la commande `sovrium` est disponible depuis n'importe où.

## En tant que bibliothèque

Pour utiliser Sovrium par programmation depuis un projet Bun, ajoutez-le comme dépendance :

```bash
bun add sovrium
```

:::callout
**Vous rédigez votre configuration en TypeScript ?** Installez le paquet sans dépendance `@sovrium/types` pour l'autocomplétion dans l'IDE (`bun add -d @sovrium/types`) et rédigez votre configuration avec `defineConfig`. Voir [Fichiers de configuration](/fr/configuration-files).
:::

## Vérifier l'installation

Exécutez la commande d'aide pour vérifier que Sovrium est correctement installé :

```bash
sovrium --help
```

## Créer un fichier de configuration

Sovrium lit un fichier de configuration YAML ou JSON. Créez un fichier `app.yaml` avec la configuration valide la plus simple :

```yaml
name: my-app
```

:::callout
**YAML ou JSON.** Sovrium prend en charge les fichiers `.yaml`/`.yml` et `.json`. Le YAML est recommandé pour sa lisibilité.
:::

## Configuration de la base de données

Sovrium utilise par défaut une base de données SQLite embarquée — les tables et l'authentification fonctionnent sans aucune configuration. Définissez `DATABASE_URL` uniquement pour choisir l'emplacement du fichier SQLite ou pour passer à PostgreSQL :

```bash
# Par défaut : SQLite embarqué — aucun DATABASE_URL nécessaire

# Optionnel — choisir l'emplacement du fichier SQLite :
export DATABASE_URL="file:./data/app.db"

# Optionnel — utiliser PostgreSQL pour les fonctionnalités avancées :
export DATABASE_URL="postgresql://user:password@localhost:5432/myapp"
```

:::callout
**SQLite par défaut.** Laissez `DATABASE_URL` non défini et Sovrium stocke les données dans un fichier SQLite local. Utilisez une URL `file:` pour choisir son emplacement, ou une URL `postgresql://` pour changer de moteur. Les sites purement statiques (pages et thème uniquement) n'ont besoin d'aucune base de données.
:::

## Étapes suivantes

- [Démarrage rapide](/fr/quick-start) — créez et exécutez votre première application.
- [Concepts fondamentaux](/fr/concepts) — l'anatomie d'une application Sovrium.
- [Fichiers de configuration](/fr/configuration-files) — YAML, JSON, TypeScript et `$ref`.

# Démarrage rapide

Créez votre première application Sovrium en quelques minutes. De zéro à une application opérationnelle. Choisissez l'approche qui correspond à votre flux de travail.

## Choisissez votre approche

Sovrium prend en charge deux formats de configuration. Le YAML est parfait pour la simplicité ; TypeScript offre un typage complet et l'autocomplétion.

### Option A : YAML + CLI

La voie la plus simple. Installez le CLI Sovrium, rédigez une configuration YAML et démarrez le serveur :

1. **Installer le CLI** — Installez Sovrium globalement avec Bun pour obtenir la commande `sovrium`.

   ```bash
   bun add -g sovrium
   ```

2. **Créer un fichier de configuration** — Créez un fichier `app.yaml` avec la configuration valide la plus simple : juste un nom.

   ```yaml
   name: my-app
   ```

3. **Ajouter des tables de données** — Définissez vos modèles de données avec des champs typés, des options et de la validation.

   ```yaml
   name: my-app

   tables:
     - id: 1
       name: tasks
       fields:
         - id: 1
           name: title
           type: single-line-text
           required: true
         - id: 2
           name: status
           type: single-select
           options: [To Do, In Progress, Done]
   ```

4. **Démarrer le serveur** — Lancez le serveur de développement et rendez-vous sur `http://localhost:3000` pour voir votre application.

   ```bash
   sovrium start app.yaml
   ```

:::callout
**Enrichissez au fur et à mesure.** Commencez petit avec uniquement des tables. Puis ajoutez progressivement le thème, l'authentification, les pages et l'analytique à mesure que vos besoins grandissent.
:::

### Option B : TypeScript + Bun

La voie pour les utilisateurs avancés. Créez un projet Bun, ajoutez Sovrium comme dépendance et rédigez du code fortement typé :

1. **Initialiser un projet** — Échafaudez un nouveau projet Bun avec `bun init` et entrez dans le répertoire.

   ```bash
   bun init my-app && cd my-app
   ```

2. **Ajouter Sovrium** — Installez Sovrium comme dépendance du projet.

   ```bash
   bun add sovrium
   ```

3. **Rédiger votre application** — Ouvrez `index.ts` et importez la fonction `start` avec une configuration minimale.

   ```typescript
   import { start } from 'sovrium'

   await start({
     name: 'my-app',
   })
   ```

4. **Ajouter des tables de données** — Enrichissez la configuration avec des champs typés, des options et de la validation, avec une autocomplétion complète.

   ```typescript
   import { start } from 'sovrium'

   await start({
     name: 'my-app',
     tables: [
       {
         id: 1,
         name: 'tasks',
         fields: [
           {
             id: 1,
             name: 'title',
             type: 'single-line-text',
             required: true,
           },
           {
             id: 2,
             name: 'status',
             type: 'single-select',
             options: ['To Do', 'In Progress', 'Done'],
           },
         ],
       },
     ],
   })
   ```

5. **Exécuter votre application** — Exécutez `index.ts` avec Bun. Rendez-vous sur `http://localhost:3000` pour voir votre application.

   ```bash
   bun run index.ts
   ```

:::callout
**Pourquoi TypeScript ?** TypeScript offre l'autocomplétion pour chaque propriété, la validation des types de champs à la compilation et toute la puissance de Bun comme environnement d'exécution. Idéal pour les développeurs qui préfèrent le code aux fichiers de configuration.
:::

## Et ensuite ?

Maintenant que votre application est opérationnelle, explorez la référence du schéma pour ajouter davantage de fonctionnalités :

- [Concepts fondamentaux](/fr/concepts) : l'anatomie d'une application Sovrium
- [Vue d'ensemble du schéma](/fr/overview) : les 18 propriétés racine expliquées
- [Vue d'ensemble des tables](/fr/tables-overview) : 49 types de champs, permissions, index
- [Thème](/fr/theme) : couleurs, polices, espacement et jetons de design
- [Vue d'ensemble des pages](/fr/pages-overview) : environ 80 types de composants pour des pages rendues côté serveur

# Concepts fondamentaux

Une application Sovrium est un unique **objet de configuration** déclaratif. Vous décrivez _ce qu'est_ votre application — ses données, ses pages, ses formulaires, son authentification, ses automatisations — et Sovrium transforme cette description en une application web full-stack opérationnelle. Il n'y a aucun code générique, aucun échafaudage de framework et aucun pipeline de build à câbler.

Cette page explique l'anatomie de cet objet de configuration afin que le reste de la référence du [Schéma d'application](/fr/overview) prenne tout son sens.

## L'objet de configuration

Tout part d'un seul objet racine. Seul `name` est obligatoire ; toutes les autres sections sont optionnelles et s'ajoutent en couches à mesure que votre application grandit.

```yaml
name: my-app # Identifiant de l'application (obligatoire)
version: 1.0.0 # Version SemVer
description: My application # Description en une ligne

tables: [...] # Modèles de données (49 types de champs)
pages: [...] # Pages rendues côté serveur (~80 types de composants)
forms: [...] # Formulaires autonomes qui capturent des soumissions
auth: { ... } # Authentification, rôles, RBAC
theme: { ... } # Jetons de design (couleurs, polices, espacement, …)
languages: { ... } # Prise en charge multilingue (syntaxe $t:)

automations: [...] # Workflows pilotés par événements (déclencheurs + actions)
actions: [...] # Modèles d'actions réutilisables ($ref)
connections: [...] # Identifiants de services externes
agents: [...] # Agents IA agissant sous un rôle d'authentification
buckets: [...] # Conteneurs de stockage de fichiers nommés

components: [...] # Modèles d'interface réutilisables ($ref, $variable)
analytics: { ... } # Analytique de première partie, sans cookie
env: { ... } # Variables d'environnement d'automatisation déclarées ($env.NAME)
scripts: { ... } # Scripts de page globaux
```

:::callout
**Complexité progressive.** Une application valide peut se résumer à `name: my-app`. Ajoutez des sections uniquement lorsque vous en avez besoin — il n'y a pas d'« échafaudage minimal viable » à surmonter au préalable.
:::

## Les sections racine

L'objet de configuration regroupe ses fonctionnalités dans les sections ci-dessous. Chacune renvoie à sa référence dédiée.

| Section       | Objet                                                                                                        | Référence                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `name`        | Identifiant de l'application (règles de nommage npm). La seule propriété obligatoire.                        | [Métadonnées de l'application](/fr/app-metadata)               |
| `version`     | Chaîne de versionnage sémantique. Alimente le registre de versions immuable.                                 | [Métadonnées de l'application](/fr/app-metadata)               |
| `description` | Description de l'application en une seule ligne (2000 caractères max).                                       | [Métadonnées de l'application](/fr/app-metadata)               |
| `tables`      | Modèles de données — les colonnes que les enregistrements peuvent stocker via 49 types de champs.            | [Vue d'ensemble des tables](/fr/tables-overview)               |
| `pages`       | Pages rendues côté serveur, construites à partir d'un arbre de types de composants, avec SEO et i18n.        | [Vue d'ensemble des pages](/fr/pages-overview)                 |
| `forms`       | Formulaires autonomes qui capturent des soumissions dans une table ou déclenchent une automatisation.        | [Vue d'ensemble des formulaires](/fr/forms-overview)           |
| `auth`        | Stratégies d'authentification, rôles, RBAC, sessions et double authentification.                             | [Vue d'ensemble de l'authentification](/fr/auth-overview)      |
| `theme`       | Jetons de design : couleurs, polices, espacement, ombres, animations, points de rupture, rayons.             | [Thème](/fr/theme)                                             |
| `languages`   | Prise en charge multilingue avec la syntaxe de traduction `$t:` et le routage d'URL.                         | [Langues](/fr/languages)                                       |
| `automations` | Workflows pilotés par événements : un déclencheur se déclenche, une séquence d'actions s'exécute.            | [Vue d'ensemble des automatisations](/fr/automations-overview) |
| `actions`     | Modèles d'actions réutilisables référencés depuis les automatisations via `$ref`.                            | [Vue d'ensemble des automatisations](/fr/automations-overview) |
| `connections` | Identifiants réutilisables pour les services externes (OAuth2, clé API, basic, bearer).                      | [Vue d'ensemble des automatisations](/fr/automations-overview) |
| `agents`      | Agents IA qui agissent au nom d'un rôle d'authentification dans un ensemble d'outils restreint.              | [Vue d'ensemble de l'IA](/fr/ai-overview)                      |
| `buckets`     | Conteneurs de stockage nommés avec des limites de fichiers et des permissions par bucket.                    | [Vue d'ensemble des buckets](/fr/buckets-overview)             |
| `components`  | Modèles d'interface réutilisables insérés dans les pages via `$ref` avec substitution de `$variable`.        | [Vue d'ensemble des pages](/fr/pages-overview)                 |
| `analytics`   | Analytique de première partie, sans cookie. `true` pour les valeurs par défaut ou un objet pour les options. | [Vue d'ensemble du schéma](/fr/overview)                       |
| `env`         | Variables d'environnement déclarées, résolues à l'exécution, référencées comme `$env.NAME`.                  | [Variables d'environnement](/fr/env-vars)                      |
| `scripts`     | Scripts globaux chargés sur chaque page avant les scripts au niveau de la page.                              | [Vue d'ensemble des pages](/fr/pages-overview)                 |

:::callout
**Les enregistrements ne sont pas une section racine.** Les enregistrements sont les lignes _à l'intérieur_ de vos tables. Ils sont créés et interrogés à l'exécution via l'API REST/MCP plutôt que déclarés dans la configuration — voir [Vue d'ensemble des enregistrements](/fr/records-overview).
:::

## La philosophie pilotée par la configuration

Sovrium inverse la relation habituelle entre code et configuration. Au lieu d'écrire du code applicatif qui lit occasionnellement un fichier de configuration, vous écrivez une configuration que Sovrium exécute directement.

- **Déclarer, ne pas implémenter.** Vous déclarez un champ `relationship` ; Sovrium crée la clé étrangère, les requêtes de jointure et l'interface des enregistrements liés. Vous déclarez une `automation` ; Sovrium câble le déclencheur, exécute les actions et enregistre l'historique des exécutions.
- **Une seule source de vérité.** Le même objet pilote le schéma de la base de données, l'API REST, le serveur MCP, les pages rendues et le tableau de bord d'administration. Il n'y a pas de second endroit où la forme de vos données serait redéfinie.
- **Validation inter-sections.** Les sections sont validées ensemble, et non isolément. Une automatisation d'enregistrement qui référence une table inexistante, un champ de pièce jointe pointant vers un bucket non déclaré ou une permission nommant un rôle inconnu sont tous rejetés avant le démarrage du serveur — voir [`sovrium validate`](/fr/cli).
- **Auto-hébergeable, sans dépendance.** La configuration s'exécute sur votre infrastructure avec un stockage standard (SQLite par défaut, PostgreSQL optionnel). Vos données et votre schéma restent les vôtres.

## Le modèle en couches (en un coup d'œil)

En interne, Sovrium suit une architecture à quatre couches. Vous n'écrivez jamais de code dans ces couches pour une application uniquement configurée, mais ce modèle explique _pourquoi_ le schéma est structuré ainsi.

| Couche             | Responsabilité                                                                   | Ce que votre configuration touche                  |
| ------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Présentation**   | Rend les pages et sert l'API REST/MCP.                                           | `pages`, `forms`, `components`, `theme`, `scripts` |
| **Application**    | Orchestre les workflows et les cas d'usage.                                      | `automations`, `actions`, `agents`                 |
| **Domaine**        | Règles métier pures et schéma d'application validé lui-même.                     | `tables`, `auth`, `languages`, validation          |
| **Infrastructure** | Communique avec la base de données, le stockage de fichiers et les API externes. | `connections`, `buckets`, `env`                    |

Le sens des dépendances va toujours vers l'intérieur (Présentation → Application → Domaine ← Infrastructure), c'est pourquoi déclarer les données et les règles (`tables`, `auth`) est indépendant de la manière dont elles sont rendues (`pages`) ou persistées (`buckets`).

## Étapes suivantes

- [Fichiers de configuration](/fr/configuration-files) — YAML vs TypeScript, `defineConfig` et configurations multi-fichiers avec `$ref`.
- [Vue d'ensemble du schéma](/fr/overview) — la référence complète des propriétés racine.
- [Démarrage rapide](/fr/quick-start) — créez et exécutez votre première application.

# Référence CLI

Le CLI Sovrium exécute votre application et gère son cycle de vie : démarrer et arrêter le serveur, recharger la configuration à chaud sans interruption, générer un site statique, échafauder un projet, afficher le JSON Schema et valider un fichier de configuration. La configuration est chargée depuis un fichier ou une variable d'environnement.

## Utilisation

Le CLI accepte une commande suivie d'un chemin de fichier de configuration optionnel et d'options.

```bash
sovrium [command] [config] [flags]

sovrium start app.yaml          # Démarrer le serveur (commande par défaut)
sovrium stop                    # Arrêter le serveur en cours d'exécution
sovrium restart app.yaml        # Redémarrer le serveur en cours d'exécution
sovrium reload                  # Recharger la configuration à chaud sans interruption
sovrium build app.yaml          # Générer un site statique
sovrium init ./my-app           # Échafauder un nouveau projet
sovrium schema                  # Afficher le JSON Schema
sovrium validate app.yaml       # Valider la configuration
sovrium --help                  # Afficher l'aide
```

## Commandes

Les commandes les plus courantes sont présentées ci-dessous. Si aucune commande n'est spécifiée, `start` est utilisée par défaut. Le CLI expose également des commandes pour étendre un projet (`agents`), l'exploiter (`admin`, `secret`) et maintenir le binaire à jour (`update`) — toutes documentées ci-dessous. Exécutez `sovrium --help` pour la liste complète.

### `sovrium start`

Démarre un serveur de développement qui sert votre application. C'est la commande par défaut — exécuter `sovrium app.yaml` équivaut à `sovrium start app.yaml`.

```bash
sovrium start app.yaml
```

### `sovrium stop`

Arrête le serveur Sovrium en cours d'exécution.

```bash
sovrium stop
```

### `sovrium restart`

Redémarre le serveur en cours d'exécution, éventuellement avec un nouveau fichier de configuration.

```bash
sovrium restart app.yaml
```

### `sovrium reload`

Recharge à chaud la configuration d'un serveur en cours d'exécution sans interruption. Le rechargement sonde d'abord l'état de dérive de l'application en direct ; si le schéma en direct a dérivé par rapport au fichier (modifié à l'exécution via l'API d'administration ou MCP), le rechargement est refusé sauf si `--force` est passé. Voir [Métadonnées de l'application](/fr/app-metadata#schema-drift-detection).

```bash
sovrium reload
sovrium reload --force   # écrase un schéma en direct dérivé avec le fichier
```

### `sovrium init`

Échafaude un nouveau projet dans le répertoire indiqué (ou le répertoire courant). Utilisez `--template <name>` pour partir d'un modèle et `--name <name>` pour définir le nom de l'application.

```bash
sovrium init ./my-app --template blog
```

### `sovrium build`

Génère un site statique à partir de votre configuration. Produit du HTML, du CSS et des ressources prêts à être déployés vers n'importe quel hébergeur de sites statiques.

```bash
sovrium build app.yaml
```

### `sovrium schema`

Affiche le JSON Schema (Draft-07) de la configuration d'application Sovrium sur la sortie standard. Utilisez `--output <path>` pour écrire dans un fichier à la place.

```bash
sovrium schema
sovrium schema --output app.schema.json
```

### `sovrium validate <config>`

Valide un fichier de configuration par rapport à l'AppSchema Sovrium. Retourne le code de sortie 0 si la configuration est valide, 1 si elle est invalide avec le détail des erreurs.

```bash
sovrium validate app.yaml
```

### `sovrium agents list`

Liste les modèles d'agents intégrés au binaire. Ce sont des définitions de sous-agents Claude Code que vous pouvez installer dans le répertoire `.claude/agents/` d'un projet.

```bash
sovrium agents list
```

### `sovrium agents install <name>`

Installe un modèle d'agent intégré dans `.claude/agents/<name>.md`. `add` est un alias d'`install`. Par défaut, l'agent est écrit sous le répertoire courant ; passez `--target <dir>` pour choisir une autre racine de projet. La commande refuse d'écraser un fichier d'agent existant sauf si `--force` est fourni.

```bash
sovrium agents install crud-editor
sovrium agents add crud-editor --target ./my-project --force
```

### `sovrium admin create <email>`

Provisionne un utilisateur administrateur dans la base de données sans avoir à fournir un schéma complet. Le mot de passe est lu depuis `--password <value>` lorsqu'il est fourni (utile en CI/scripts) ; sinon, il vous est demandé de manière interactive avec l'écho désactivé. Exécuter la commande sans `--password` dans un shell non interactif (sans TTY) est une erreur.

Le schéma de la base de données est résolu dans cet ordre : un `--config <path>` explicite, puis `APP_SCHEMA`, puis un schéma par défaut minimal intégré — afin que la commande `sovrium admin create <email>` fonctionne sans fichier de configuration. Si l'administrateur existe déjà, aucune modification n'est effectuée.

```bash
# Demander le mot de passe de manière interactive
sovrium admin create me@example.com

# Fournir le mot de passe (CI / scripts)
sovrium admin create me@example.com --password 's3cret-pass'

# Résoudre le schéma depuis une configuration spécifique
sovrium admin create me@example.com --config app.yaml
```

### `sovrium secret generate`

Affiche des secrets fraîchement générés, cryptographiquement aléatoires, sous forme de lignes prêtes pour `.env`. Chaque secret est une valeur de 256 bits (64 caractères hexadécimaux). Sans portée, `AUTH_SECRET` et `SOVRIUM_ENCRYPTION_KEY` sont tous deux affichés. Passez une portée pour n'afficher qu'un sous-ensemble.

| Portée       | Sortie                                   |
| ------------ | ---------------------------------------- |
| _(aucune)_   | `AUTH_SECRET` + `SOVRIUM_ENCRYPTION_KEY` |
| `all`        | Les deux (explicite)                     |
| `auth`       | `AUTH_SECRET` uniquement                 |
| `encryption` | `SOVRIUM_ENCRYPTION_KEY` uniquement      |

Les lignes `.env` générées sont écrites sur la sortie standard (pour que les redirections fonctionnent proprement) ; les messages d'information vont sur la sortie d'erreur.

```bash
# Les deux secrets
sovrium secret generate

# Ajouter un nouveau AUTH_SECRET à votre .env
sovrium secret generate auth >> .env

# Clé de chiffrement uniquement
sovrium secret generate encryption
```

### `sovrium update`

Met à jour Sovrium vers la dernière version. Le comportement dépend de la méthode d'installation :

| Méthode d'installation | Comportement                                              |
| ---------------------- | --------------------------------------------------------- |
| `binary`               | Auto-remplacement depuis GitHub Releases (Unix)           |
| `homebrew`             | Délègue à `brew upgrade sovrium/tap/sovrium`              |
| `scoop`                | Délègue à `scoop update sovrium`                          |
| `docker`               | Affiche l'instruction `docker pull`                       |
| `npm`                  | Affiche un avis d'obsolescence (le paquet npm est retiré) |

```bash
sovrium update
sovrium update --help
```

### `sovrium --help`

Affiche le message d'aide avec un résumé des commandes, des options et des exemples.

```bash
sovrium --help
```

## Options

Les options peuvent être placées n'importe où dans la commande.

| Option               | Description                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--watch, -w`        | Surveille le fichier de configuration et recharge automatiquement le serveur à chaud. Disponible uniquement avec la commande `start`. |
| `--version, -V`      | Affiche le numéro de version de Sovrium et quitte.                                                                                    |
| `--output <path>`    | Écrit la sortie dans un fichier au lieu de la sortie standard (commande `schema` uniquement).                                         |
| `--template <name>`  | Modèle de projet à partir duquel échafauder (commande `init`).                                                                        |
| `--name <name>`      | Nom de l'application à définir lors de l'échafaudage (commande `init`).                                                               |
| `--target <dir>`     | Répertoire de destination de l'installation, par défaut le répertoire courant (commande `agents install`).                            |
| `--config <path>`    | Fichier de configuration utilisé pour résoudre le schéma de la base de données (commande `admin create`).                             |
| `--password <value>` | Mot de passe administrateur ; s'il est omis, il vous est demandé de manière interactive (commande `admin create`).                    |
| `--force`            | Écrase les fichiers existants ou un schéma en direct dérivé (`init`, `reload`, `agents install`).                                     |
| `--help, -h`         | Affiche le message d'aide et quitte.                                                                                                  |

## Sources de configuration

Sovrium peut charger la configuration depuis un chemin de fichier ou depuis la variable d'environnement `APP_SCHEMA`. Un chemin de fichier a la priorité lorsque les deux sont fournis.

### Chemin de fichier

Passez un chemin vers un fichier de configuration JSON ou YAML comme deuxième argument.

```bash
sovrium start app.yaml
sovrium build config.json
```

### Variable d'environnement

Définissez la variable `APP_SCHEMA` pour fournir la configuration sans fichier. Prend en charge le JSON en ligne, le YAML en ligne ou une URL distante.

```bash
# JSON en ligne
APP_SCHEMA='{"name":"my-app"}' sovrium start

# YAML en ligne
APP_SCHEMA='name: my-app' sovrium start

# URL distante
APP_SCHEMA='https://example.com/app.yaml' sovrium start
```

:::callout
**YAML ou JSON.** Sovrium prend en charge les fichiers `.yaml`/`.yml` et `.json`. Le YAML est recommandé pour sa lisibilité.
:::

## Mode surveillance

Le mode surveillance surveille votre fichier de configuration et recharge automatiquement le serveur lorsque des modifications sont détectées.

```bash
# Démarrer avec la surveillance de fichier
sovrium start app.yaml --watch

# Modifiez app.yaml dans un autre terminal...
# Le serveur se recharge automatiquement
```

:::callout
**Récupération d'erreur.** Si le fichier de configuration mis à jour est invalide, le rechargement échoue proprement et le serveur précédent continue de fonctionner. Corrigez la configuration et enregistrez pour réessayer.
:::

## Exemples

Cas d'utilisation courants du CLI.

### `sovrium start`

```bash
# Démarrer depuis un fichier JSON
sovrium start app.json

# Démarrer depuis un fichier YAML
sovrium start app.yaml

# Démarrage implicite (commande par défaut)
sovrium app.yaml

# Démarrer avec le mode surveillance (rechargement à chaud)
sovrium start app.yaml --watch
sovrium start app.yaml -w

# Démarrer sur un port personnalisé
PORT=8080 sovrium start app.yaml
```

### `sovrium build`

```bash
# Build statique de base
sovrium build app.yaml

# Build pour GitHub Pages
SOVRIUM_DEPLOYMENT=github-pages sovrium build app.yaml

# Build avec sitemap et sortie personnalisée
SOVRIUM_OUTPUT_DIR=./public \
  SOVRIUM_BASE_URL=https://example.com \
  SOVRIUM_GENERATE_SITEMAP=true \
  SOVRIUM_GENERATE_ROBOTS=true \
  sovrium build app.yaml
```

### `sovrium schema`

```bash
# Afficher le JSON Schema sur la sortie standard
sovrium schema

# Écrire le JSON Schema dans un fichier
sovrium schema --output app.schema.json
```

### `sovrium validate <config>`

```bash
# Valider une configuration YAML
sovrium validate app.yaml

# Valider une configuration JSON
sovrium validate config.json
```

## Codes de sortie

Le CLI utilise des codes de sortie standard.

| Code | Signification                                                        |
| ---- | -------------------------------------------------------------------- |
| `0`  | Succès                                                               |
| `1`  | Erreur (configuration invalide, fichier manquant, commande inconnue) |

## Pages associées

- [Fichiers de configuration](/fr/configuration-files) — configurations multi-fichiers YAML, JSON, TypeScript et `$ref`.
- [Variables d'environnement](/fr/env-vars) — `APP_SCHEMA`, `PORT`, `DATABASE_URL` et variables de build.
- [Métadonnées de l'application](/fr/app-metadata) — le registre de versions et la détection de dérive que `reload` respecte.

# API TypeScript

Utilisez Sovrium comme bibliothèque dans votre projet TypeScript. Importez `start`, `build` et le type `AppConfig` pour un contrôle programmatique complet avec une configuration typée.

```typescript
import { start, build, generateAppJsonSchema, validateConfig } from 'sovrium'
import type { AppConfig, SimpleServer, ValidateConfigResult } from 'sovrium'

// All config types are available:
// PageConfig, TableConfig, ThemeConfig, AuthConfig,
// ComponentConfig, LanguageConfig, AnalyticsConfig, ...
```

## Pourquoi TypeScript ?

Utiliser Sovrium par programmation vous offre des avantages au-delà du CLI.

### Sécurité des types

Le type `AppConfig` fournit l'autocomplétion pour chaque propriété et type de champ. Détectez les erreurs à la compilation, pas à l'exécution.

### Contrôle programmatique

Générez la configuration dynamiquement, composez des schémas et intégrez Sovrium dans des applications existantes.

### Intégration à l'IDE

IntelliSense complet dans VS Code et JetBrains — documentation au survol, accès à la définition et erreurs de type.

## `start(app, options?)`

Démarre un serveur de développement à partir d'un objet de configuration typé. Retourne une instance de serveur dotée d'une méthode `stop()`.

```typescript
import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)
```

### `StartOptions`

Deuxième argument optionnel pour configurer le serveur.

| Propriété   | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `port`      | Numéro de port (0–65535). 0 sélectionne un port disponible. Par défaut : 3000.    |
| `hostname`  | Nom d'hôte du serveur. Par défaut : `localhost`.                                  |
| `publicDir` | Répertoire de fichiers statiques. Les fichiers sont servis à leur chemin relatif. |

```typescript
import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)
```

## `build(app, options?)`

Génère un site statique à partir d'un objet de configuration typé.

### `GenerateStaticOptions`

Deuxième argument optionnel pour contrôler la sortie statique.

| Propriété            | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `outputDir`          | Répertoire de sortie. Par défaut : `./static`.              |
| `baseUrl`            | URL de base pour le sitemap et les liens canoniques.        |
| `basePath`           | Préfixe de chemin pour les déploiements en sous-répertoire. |
| `deployment`         | Plateforme cible : `github-pages` ou `generic`.             |
| `languages`          | Tableau de codes de langue pour la génération.              |
| `defaultLanguage`    | Code de langue par défaut.                                  |
| `generateSitemap`    | Génère `sitemap.xml`. Par défaut : `false`.                 |
| `generateRobotsTxt`  | Génère `robots.txt`. Par défaut : `false`.                  |
| `hydration`          | Active l'hydratation côté client. Par défaut : `false`.     |
| `generateManifest`   | Génère `manifest.json` pour les PWA. Par défaut : `false`.  |
| `bundleOptimization` | Stratégie de découpage : `split` ou `none`.                 |
| `publicDir`          | Répertoire de ressources statiques à copier dans la sortie. |

```typescript
import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)
```

## `generateAppJsonSchema()`

Génère le JSON Schema (Draft-07) de la configuration d'application Sovrium. Retourne un objet simple, adapté à la sérialisation ou à un usage programmatique.

```typescript
import { generateAppJsonSchema } from 'sovrium'

const schema = generateAppJsonSchema()
Bun.write('app.schema.json', JSON.stringify(schema, null, 2))
```

## `validateConfig(config)`

Valide une valeur inconnue par rapport à l'AppSchema Sovrium. Retourne un objet résultat indiquant si la configuration est valide, avec la configuration analysée ou le détail des erreurs.

```typescript
import { validateConfig } from 'sovrium'

const result = validateConfig({ name: 'My App' })
if (result.valid) {
  console.log(result.config.name)
} else {
  console.error(result.errors)
}
```

## `AppConfig`

Le type principal pour typer vos objets de configuration JSON ou YAML. Importez-le depuis `sovrium` pour obtenir une autocomplétion et une vérification de type complètes.

| Propriété      | Description                                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `name`         | Nom de l'application. En minuscules, compatible npm (par ex. `my-app`, `@org/app`).                                  |
| `version?`     | Chaîne de version SemVer (par ex. `1.0.0`).                                                                          |
| `description?` | Description de l'application en une seule ligne.                                                                     |
| `tables?`      | Tableau de définitions de tables de données avec champs, index et contraintes.                                       |
| `theme?`       | Jetons de design : couleurs, polices, espacement, animations, points de rupture, ombres, borderRadius.               |
| `pages?`       | Tableau de configurations de pages avec métadonnées, sections et scripts.                                            |
| `forms?`       | Définitions de formulaires autonomes qui capturent des soumissions ou déclenchent des automatisations.               |
| `auth?`        | Configuration d'authentification : stratégies, rôles, plugins (admin, organization).                                 |
| `languages?`   | Configuration multilingue : langues prises en charge, langue par défaut, traductions.                                |
| `components?`  | Tableau de modèles de composants réutilisables avec substitution de variables.                                       |
| `automations?` | Workflows pilotés par événements : déclencheurs plus actions séquentielles.                                          |
| `actions?`     | Modèles d'actions réutilisables référencés depuis les automatisations via `$ref`.                                    |
| `connections?` | Identifiants de services externes (OAuth2, clé API, basic, bearer).                                                  |
| `agents?`      | Agents IA agissant sous un rôle d'authentification avec des outils restreints.                                       |
| `buckets?`     | Conteneurs de stockage de fichiers nommés avec des limites et des permissions par bucket.                            |
| `env?`         | Variables d'environnement d'automatisation déclarées, référencées comme `$env.NAME`.                                 |
| `analytics?`   | Analytique intégrée respectueuse de la vie privée. Définissez `true` pour les valeurs par défaut ou passez un objet. |

```typescript
import type { AppConfig } from 'sovrium'

const config: AppConfig = {
  name: 'my-app',
  version: '1.0.0',
  description: 'My application',
  tables: [
    /* ... */
  ],
  theme: {
    /* ... */
  },
  pages: [
    /* ... */
  ],
  auth: {
    /* ... */
  },
  languages: {
    /* ... */
  },
  components: [
    /* ... */
  ],
  analytics: true,
}
```

:::callout
**Complexité incrémentale.** Seul `name` est obligatoire. Ajoutez `tables`, `theme`, `pages`, `auth`, `languages`, `components` et `analytics` à mesure que vous en avez besoin.
:::

## Référence des types

Types TypeScript supplémentaires exportés depuis le paquet `sovrium`. Importez-les avec `import type { ... } from "sovrium"`.

### `SimpleServer`

Retourné par `start()`. Une interface légère vers le serveur en cours d'exécution.

| Propriété | Description                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| `url`     | URL du serveur incluant le protocole et le port (par ex. `"http://localhost:3000"`).          |
| `stop()`  | Arrête proprement le serveur. Retourne une Promise qui se résout lorsque l'arrêt est terminé. |

```typescript
import { start } from 'sovrium'
import type { SimpleServer } from 'sovrium'

const server: SimpleServer = await start({ name: 'my-app' })
console.log(server.url) // "http://localhost:3000"
await server.stop() // graceful shutdown
```

### `PageConfig`

Configuration d'une page unique. Élément de `AppConfig['pages']`.

```typescript
const page: PageConfig = {
  name: 'home',
  path: '/',
  sections: [{ type: 'heading', content: 'Welcome' }],
}
```

### `TableConfig`

Configuration d'une table de données unique. Élément de `AppConfig['tables']`.

```typescript
const table: TableConfig = {
  id: 1,
  name: 'tasks',
  fields: [{ id: 1, name: 'title', type: 'single-line-text' }],
}
```

### `ComponentConfig`

Modèle de composant réutilisable avec des espaces réservés de variables. Élément de `AppConfig['components']`.

```typescript
const hero: ComponentConfig = {
  name: 'hero',
  type: 'section',
  children: [{ type: 'heading', content: '$title' }],
}
```

### `ThemeConfig`

Jetons de design pour les couleurs, la typographie, l'espacement, les ombres et plus encore.

```typescript
const theme: ThemeConfig = {
  colors: { primary: '#3b82f6' },
  fonts: { sans: 'Inter, sans-serif' },
}
```

### `AuthConfig`

Stratégies d'authentification, rôles et configuration des plugins.

```typescript
const auth: AuthConfig = {
  strategies: [{ type: 'emailAndPassword' }],
  roles: [{ name: 'admin' }, { name: 'member' }],
}
```

### `LanguageConfig`

Prise en charge multilingue avec traductions et détection de langue.

```typescript
const languages: LanguageConfig = {
  supported: ['en', 'fr'],
  default: 'en',
}
```

### `AnalyticsConfig`

Analytique intégrée respectueuse de la vie privée. Utilisez `true` pour les valeurs par défaut ou un objet pour des réglages personnalisés.

```typescript
// Simple: just enable defaults
const analytics: AnalyticsConfig = true

// Custom settings
const custom: AnalyticsConfig = { retentionDays: 90, excludedPaths: ['/admin'] }
```

### `GenerateStaticResult`

Retourné par `build()`. Contient le chemin du répertoire de sortie et la liste des fichiers générés.

| Propriété   | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `outputDir` | Chemin absolu du répertoire de sortie (par ex. `"./static"`).                     |
| `files`     | Tableau des chemins de fichiers générés pendant le build (HTML, CSS, ressources). |

```typescript
import { build } from 'sovrium'
import type { GenerateStaticResult } from 'sovrium'

const result: GenerateStaticResult = await build({
  name: 'my-site',
  pages: [
    /* ... */
  ],
})
console.log(result.outputDir) // "./static"
console.log(result.files.length) // number of generated files
```

### `ValidateConfigResult`

Retourné par `validateConfig()`. Indique si la configuration est valide et fournit la configuration analysée ou le détail des erreurs.

| Propriété | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `valid`   | Booléen. `true` si la configuration est valide par rapport à l'AppSchema.   |
| `errors`  | Tableau d'objets d'erreurs de validation. Vide lorsque `valid` est `true`.  |
| `config`  | L'objet `AppConfig` analysé. Présent uniquement lorsque `valid` est `true`. |

```typescript
import { validateConfig } from 'sovrium'
import type { ValidateConfigResult } from 'sovrium'

const result: ValidateConfigResult = validateConfig({ name: 'my-app' })
console.log(result.valid) // true or false
console.log(result.errors) // validation error array (empty if valid)
console.log(result.config) // parsed AppConfig (if valid)
```

## Mode surveillance

En développement, utilisez le mode surveillance intégré de Bun pour redémarrer automatiquement votre script lorsque les fichiers changent.

```bash
bun --watch index.ts
```

:::callout
**Reload vs watch.** `bun --watch` redémarre l'ensemble du processus dès qu'un fichier importé change. Pour des changements de configuration uniquement, l'option `--watch` du CLI est plus efficace.
:::

## Exemples

Cas d'utilisation courants avec Sovrium en TypeScript.

### Serveur minimal

```typescript
import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)
```

### Avec des tables de données

```typescript
import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)
```

### Génération de site statique

```typescript
import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)
```

### Configuration dynamique

```typescript
import { start } from 'sovrium'
import type { AppConfig, PageConfig, TableConfig, ThemeConfig } from 'sovrium'

// Compose config from typed sub-configs
const theme: ThemeConfig = {
  colors: { primary: process.env.BRAND_COLOR ?? '#3b82f6' },
}

const tables: TableConfig[] = ['users', 'posts'].map((name, i) => ({
  id: i + 1,
  name,
  fields: [
    { id: 1, name: 'title', type: 'single-line-text' as const, required: true },
    { id: 2, name: 'created_at', type: 'date' as const, includeTime: true },
  ],
}))

const pages: PageConfig[] = [{ name: 'home', path: '/', sections: [] }]

const app: AppConfig = {
  name: 'dynamic-app',
  tables,
  pages,
  theme,
}

await start(app)
```

# Variables d'environnement

Sovrium lit la configuration à partir des variables d'environnement au démarrage. Définissez-les dans un fichier `.env` ou dans l'environnement de votre serveur. Toutes les variables sont optionnelles sauf indication contraire.

```bash
# .env

# Application
APP_SCHEMA='app.yaml'

# Server
PORT=3000
BASE_URL=http://localhost:3000

# Database (optional — defaults to embedded SQLite)
DATABASE_URL=file:./data/app.db

# Authentication
AUTH_SECRET=your-secret-key-here

# Default Admin
AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=secure-admin-password

# OAuth (Google example)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
```

## Application

Configuration principale de l'application. `APP_SCHEMA` est le moyen privilégié de fournir un schéma sans argument de fichier.

| Variable     | Description                                                                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `APP_SCHEMA` | Schéma de l'application sous forme de JSON en ligne, de YAML en ligne ou d'URL distante. Alternative au passage d'un chemin de fichier en ligne de commande. |

## Serveur

Options réseau du serveur pour la commande `start`.

| Variable   | Description                                                                                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PORT`     | Numéro de port du serveur (0–65535). 0 sélectionne un port disponible. Par défaut : 3000.                                                                             |
| `HOSTNAME` | Nom d'hôte du serveur. Par défaut : `localhost`.                                                                                                                      |
| `BASE_URL` | URL de base de l'application (par ex. `https://myapp.com`). Utilisée pour les URL de rappel d'authentification et les liens d'email.                                  |
| `NODE_ENV` | Environnement d'exécution. Définissez à `"production"` pour des cookies sécurisés, des vérifications CSRF et une validation SMTP stricte. Par défaut : `development`. |

## Base de données

Paramètres de connexion à la base de données. Optionnel — Sovrium utilise par défaut SQLite embarqué lorsqu'il n'est pas défini.

| Variable       | Description                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DATABASE_URL` | Chaîne de connexion à la base de données. Optionnel : non défini, utilise SQLite embarqué ; une URL `file:` (par ex. `file:./data/app.db`) choisit le fichier SQLite ; une URL `postgresql://` (par ex. `postgresql://user:password@localhost:5432/dbname`) bascule vers PostgreSQL. |

## Authentification

Variables pour l'intégration de Better Auth. Requises lorsque le schéma définit une section `auth`.

| Variable      | Description                                                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_SECRET` | Clé secrète pour signer les jetons et chiffrer les sessions. Doit être une chaîne aléatoire robuste (32 caractères ou plus recommandés). |

### Utilisateur administrateur par défaut

Variables optionnelles pour créer un utilisateur administrateur par défaut au premier démarrage. Les trois doivent être définies pour que l'utilisateur administrateur soit créé.

| Variable              | Description                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `AUTH_ADMIN_EMAIL`    | Adresse email de l'utilisateur administrateur par défaut.                                      |
| `AUTH_ADMIN_PASSWORD` | Mot de passe de l'utilisateur administrateur par défaut. Doit comporter au moins 8 caractères. |
| `AUTH_ADMIN_NAME`     | Nom d'affichage de l'utilisateur administrateur par défaut. Optionnel, par défaut `"Admin"`.   |

### Fournisseurs OAuth

Identifiants pour chaque fournisseur OAuth configuré dans le schéma d'authentification. Remplacez `{PROVIDER}` par le nom du fournisseur en majuscules.

| Variable                   | Description                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `{PROVIDER}_CLIENT_ID`     | Identifiant client OAuth issu de la console développeur du fournisseur.                   |
| `{PROVIDER}_CLIENT_SECRET` | Secret client OAuth issu de la console développeur du fournisseur. À garder confidentiel. |

:::callout
**Fournisseurs pris en charge.** Sovrium prend en charge Google, GitHub, Microsoft, Slack, GitLab et Facebook. Par exemple, définissez `GOOGLE_CLIENT_ID` et `GOOGLE_CLIENT_SECRET` pour Google OAuth.
:::

## Email (SMTP)

Configuration SMTP pour l'envoi d'emails d'authentification (vérification, réinitialisation de mot de passe, lien magique). En développement, bascule sur Mailpit à `localhost:1025` si `SMTP_HOST` n'est pas défini.

| Variable         | Description                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `SMTP_HOST`      | Nom d'hôte du serveur SMTP (par ex. `smtp.gmail.com`). Requis en production.                                  |
| `SMTP_PORT`      | Port du serveur SMTP. Par défaut : 587.                                                                       |
| `SMTP_SECURE`    | Utiliser une connexion SSL/TLS. Par défaut : `false` pour le port 587, `true` pour le port 465.               |
| `SMTP_USER`      | Nom d'utilisateur d'authentification SMTP.                                                                    |
| `SMTP_PASS`      | Mot de passe d'authentification SMTP ou mot de passe spécifique à l'application.                              |
| `SMTP_FROM`      | Adresse email d'expéditeur par défaut (par ex. `noreply@yourdomain.com`). Par défaut : `noreply@sovrium.com`. |
| `SMTP_FROM_NAME` | Nom d'affichage de l'expéditeur par défaut. Par défaut : `Sovrium`.                                           |

:::callout
**Développement local.** Lorsque `SMTP_HOST` n'est pas configuré en mode développement, Sovrium bascule automatiquement sur Mailpit (`localhost:1025`). Installez Mailpit pour visualiser les emails envoyés dans une interface web locale.
:::

## Build

Options pour la commande `build` qui génère un site statique.

| Variable                      | Description                                                                                        |
| ----------------------------- | -------------------------------------------------------------------------------------------------- |
| `SOVRIUM_OUTPUT_DIR`          | Répertoire de sortie. Par défaut : `./dist`.                                                       |
| `SOVRIUM_BASE_URL`            | URL de base pour la génération du sitemap et les liens canoniques (par ex. `https://example.com`). |
| `SOVRIUM_BASE_PATH`           | Préfixe de chemin pour les déploiements en sous-répertoire (par ex. `/my-app`).                    |
| `SOVRIUM_DEPLOYMENT`          | Cible de déploiement : `github-pages` ou `generic`.                                                |
| `SOVRIUM_LANGUAGES`           | Codes de langue séparés par des virgules à générer (par ex. `en,fr,de`).                           |
| `SOVRIUM_DEFAULT_LANGUAGE`    | Code de langue par défaut (par ex. `en`).                                                          |
| `SOVRIUM_GENERATE_SITEMAP`    | Génère `sitemap.xml`. Par défaut : `false`.                                                        |
| `SOVRIUM_GENERATE_ROBOTS`     | Génère `robots.txt`. Par défaut : `false`.                                                         |
| `SOVRIUM_HYDRATION`           | Active l'hydratation côté client. Par défaut : `false`.                                            |
| `SOVRIUM_GENERATE_MANIFEST`   | Génère `manifest.json` pour les PWA. Par défaut : `false`.                                         |
| `SOVRIUM_BUNDLE_OPTIMIZATION` | Stratégie d'optimisation : `split` (découpage du code) ou `none`.                                  |
| `SOVRIUM_PUBLIC_DIR`          | Répertoire contenant les ressources statiques à copier dans la sortie.                             |

## Débogage

Variables de diagnostic et de test. Non nécessaires en fonctionnement normal.

| Variable                    | Description                                                                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOG_LEVEL`                 | Définissez à `"debug"` pour une journalisation détaillée (journaux de requêtes, diagnostics de compilation CSS). Par défaut : suit `NODE_ENV`. |
| `EFFECT_DEVTOOLS`           | Définissez à `"1"` pour activer l'intégration des Effect DevTools pour l'inspection à l'exécution.                                             |
| `RATE_LIMIT_WINDOW_SECONDS` | Fenêtre de limitation de débit en secondes. Utilisée dans les tests pour une exécution plus rapide. Par défaut : 60.                           |

# Fichiers de configuration

Sovrium charge votre application à partir d'un fichier de configuration. Le même objet de configuration peut être écrit en YAML, JSON ou TypeScript, réparti sur plusieurs fichiers avec `$ref`, et vérifié à l'avance avec `sovrium validate`.

## YAML et JSON

La configuration la plus simple est un fichier YAML ou JSON. Le YAML est recommandé pour une rédaction manuelle — il prend en charge les commentaires, nécessite moins de ponctuation et est plus facile à lire. Le JSON est pratique lorsqu'on génère des configurations par programmation.

```yaml
# app.yaml
name: my-app
version: 1.0.0
description: A simple todo list

tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text, required: true }
      - { id: 2, name: done, type: checkbox, default: false }
```

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A simple todo list",
  "tables": [
    {
      "id": 1,
      "name": "tasks",
      "fields": [
        { "id": 1, "name": "title", "type": "single-line-text", "required": true },
        { "id": 2, "name": "done", "type": "checkbox", "default": false }
      ]
    }
  ]
}
```

Exécutez l'un ou l'autre avec le CLI :

```bash
sovrium start app.yaml
sovrium start app.json
```

:::callout
**La détection du format se fait par extension.** Sovrium achemine les fichiers `.yaml`/`.yml` vers son analyseur YAML et les fichiers `.json` vers son analyseur JSON. La forme de l'objet résultant est identique — chaque exemple de cette documentation peut être transcrit d'un format à l'autre.
:::

## TypeScript avec `defineConfig`

Pour un typage complet et l'autocomplétion dans l'IDE, rédigez votre configuration en TypeScript et validez-la par rapport au paquet `@sovrium/types`. `@sovrium/types` est un paquet **sans dépendance** de types TypeScript extraits directement du schéma Sovrium.

```bash
bun add -d @sovrium/types
```

```typescript
// app.ts
import { defineConfig } from '@sovrium/types'

export default defineConfig({
  name: 'my-app',
  version: '1.0.0',
  description: 'A simple todo list',
  tables: [
    {
      id: 1,
      name: 'tasks',
      fields: [
        { id: 1, name: 'title', type: 'single-line-text', required: true },
        { id: 2, name: 'done', type: 'checkbox', default: false },
      ],
    },
  ],
})
```

```bash
sovrium start app.ts
sovrium validate app.ts
```

`defineConfig` est un assistant d'identité : il retourne son argument inchangé mais l'annote avec le type `AppConfig`, de sorte que votre éditeur signale les types de champs invalides, les types de composants inconnus et les propriétés obligatoires manquantes au fur et à mesure que vous tapez — sans import de type séparé ni `satisfies`.

:::callout
**`@sovrium/types` vs le paquet `sovrium`.** `@sovrium/types` ne fournit que des types (sous licence MIT, sans aucun runtime). Utilisez-le pour rédiger des fichiers de configuration. Pour exécuter Sovrium par programmation (`import { start } from 'sovrium'`), voir l'[API TypeScript](/fr/typescript).
:::

## Configurations multi-fichiers avec `$ref`

À mesure qu'une application grandit, un fichier unique devient difficile à gérer. Sovrium prend en charge `$ref` pour répartir la configuration sur plusieurs fichiers. Tout objet contenant exactement une clé, `$ref`, dont la valeur est un chemin relatif, est remplacé par le contenu analysé de ce fichier avant la validation.

```yaml
# app.yaml
name: crm-workspace
version: 2.0.0

auth:
  $ref: ./config/auth.yaml

theme:
  $ref: ./config/theme.yaml

tables:
  - $ref: ./config/tables/companies.yaml
  - $ref: ./config/tables/contacts.yaml
  - $ref: ./config/tables/deals.yaml

pages:
  - $ref: ./config/pages/sign-in.yaml
  - $ref: ./config/pages/companies.yaml

agents:
  - $ref: ./config/agents/records-assistant.yaml
```

```yaml
# config/tables/companies.yaml
id: 1
name: Companies
fields:
  - { id: 1, name: name, type: single-line-text, required: true }
  - { id: 2, name: website, type: url }
```

| Règle                | Comportement                                                                                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Résolution de chemin | Les chemins `$ref` se résolvent relativement au fichier qui les contient, et non au répertoire de travail.                                                  |
| Formats mixtes       | Un fichier racine YAML peut faire `$ref` vers une partie JSON et vice versa — chaque fichier est analysé selon son extension.                               |
| Éléments de tableau  | Un `$ref` peut remplacer un élément entier de tableau (`- $ref: ...`) ou une valeur d'objet entière.                                                        |
| Moment de résolution | Tous les `$ref` sont résolus en un seul objet _avant_ la validation du schéma, de sorte que les vérifications inter-sections voient l'application complète. |

:::callout
**Les configurations TypeScript se composent différemment.** `$ref` est un mécanisme YAML/JSON. En TypeScript, vous composez avec des `import` ordinaires — définissez des sous-configurations dans des modules séparés et assemblez-les à l'intérieur de `defineConfig({ ... })`.
:::

## Chargement sans fichier

La configuration peut également provenir de la variable d'environnement `APP_SCHEMA` au lieu d'un chemin de fichier — JSON en ligne, YAML en ligne ou URL distante. Voir la [Référence CLI](/fr/cli#configuration-sources) pour plus de détails.

## Valider une configuration

`sovrium validate` vérifie un fichier de configuration par rapport au schéma d'application complet — y compris les règles inter-sections telles que « une automatisation d'enregistrement doit référencer une table existante » — et retourne un code de sortie non nul avec le détail des erreurs en cas de problème.

```bash
sovrium validate app.yaml
sovrium validate app.ts
sovrium validate config.json
```

Exécutez-la en CI pour détecter les erreurs de configuration avant le déploiement. Comme la validation exécute le même schéma que celui utilisé par le serveur au démarrage, une configuration qui passe `validate` est garantie de démarrer.

## Étapes suivantes

- [Concepts fondamentaux](/fr/concepts) — l'anatomie de l'objet de configuration.
- [Référence CLI](/fr/cli) — chaque commande, option et source de configuration.
- [API TypeScript](/fr/typescript) — exécuter Sovrium comme bibliothèque.
- [Vue d'ensemble du schéma](/fr/overview) — la référence complète des propriétés racine.

# Modèles et exemples

La façon la plus rapide d'apprendre Sovrium est de partir d'une application fonctionnelle. Sovrium fournit un ensemble de configurations d'exemple — chacune étant un projet complet et exécutable qui compose de vraies fonctionnalités (tables, authentification, pages, thème, i18n, automatisations) en une seule arborescence de configuration. Ces mêmes exemples servent aussi de modèles `sovrium init`, vous pouvez donc échafauder n'importe lequel dans un nouveau répertoire et commencer à itérer immédiatement.

Chaque exemple est un **répertoire** avec un point d'entrée `app.yaml`. Tout ce qui dépasse le plus petit démarrage scinde sa configuration sur une sous-arborescence `config/` à l'aide de [`$ref`](/fr/configuration-files#multi-file-configs-with-ref) — un fichier par entité de collection, un fichier par singleton, les scalaires restant en ligne. Cela reflète la structure que `sovrium init` échafaude pour vous.

## Modèles disponibles

| Modèle            | Description                                                                                                                                                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **hello-world**   | Démarrage minimal — une page, aucune collection. Le défaut de `sovrium init`. Reste un seul `app.yaml` pour montrer quand _ne pas_ pré-scinder.                                                                                                                                                                           |
| **landing-page**  | Site marketing bilingue avec i18n, un thème, des composants réutilisables et la page d'accueil scindée pour la taille.                                                                                                                                                                                                    |
| **crud-app**      | Application CRUD avec tables (contacts, sociétés), authentification e-mail/mot de passe, un thème et des pages tableau de bord + connexion.                                                                                                                                                                               |
| **api-only**      | Mode API sans interface, avec tables (projets, tâches) et authentification — aucune page. Démontre Sovrium en tant que backend.                                                                                                                                                                                           |
| **member-portal** | Pages marketing publiques plus une zone de portail protégée par authentification avec sections selon le rôle. Authentification lien magique + mot de passe.                                                                                                                                                               |
| **mcp-server**    | Serveur MCP sans interface exposant des tables à un client LLM via un `aiAccess` par entité — aucune page. Voir [Intégration MCP](/fr/mcp-integration).                                                                                                                                                                   |
| **blog**          | Blog avec articles (rich-text), étiquettes, auteurs, et un index plus une route de détail dynamique `/blog/:slug`.                                                                                                                                                                                                        |
| **docs-site**     | Site de documentation présentant la fonctionnalité de pages markdown : de vrais fichiers `.md` sous `content/docs/`, une collection `contentDir`, une barre latérale dérivée du frontmatter, une navigation précédent/suivant, une table des matières et du code coloré par Shiki. Aucune table, aucune authentification. |

Plusieurs modèles sont fournis avec un agent éditeur associé (une définition de sous-agent Claude Code) que `sovrium init` installe dans `.claude/agents/`. Voir [`sovrium agents`](/fr/cli#sovrium-agents-list) pour gérer directement les modèles d'agents.

## Échafauder un projet

`sovrium init` copie un modèle dans un nouveau répertoire (ou le répertoire courant). Sans `--template`, le démarrage minimal `hello-world` est utilisé.

```bash
# Défaut (hello-world, aucun agent associé)
sovrium init my-app

# Choisir un modèle — installe aussi l'agent éditeur associé
sovrium init my-app --template crud-app
sovrium init my-app --template landing-page
sovrium init my-app --template blog
sovrium init my-app --template member-portal

# Ignorer l'installation de l'agent associé
sovrium init my-app --template crud-app --no-agent
```

Exécutez ensuite l'application échafaudée :

```bash
sovrium start app.yaml          # Démarrer le serveur de développement
sovrium validate app.yaml       # Valider sans démarrer
```

Voir la [Référence CLI](/fr/cli#sovrium-init) pour toutes les options de `init`.

## Anatomie d'un exemple

Un exemple non trivial ressemble à ceci (disposition abrégée de `crud-app`) :

```
crud-app/
├── app.yaml                 # Point d'entrée — référence tout via $ref
├── config/
│   ├── auth.yaml            # Singleton : stratégies d'auth, rôles
│   ├── theme.yaml           # Singleton : jetons de design
│   └── tables/
│       ├── companies.yaml   # Un fichier par table
│       └── contacts.yaml
└── public/                  # Ressources statiques (favicon, images)
```

Le point d'entrée `app.yaml` rassemble chaque partie avec `$ref`, gardant le fichier de premier niveau petit et chaque entité dans son propre fichier :

```yaml
name: crud-app

auth:
  $ref: ./config/auth.yaml

theme:
  $ref: ./config/theme.yaml

tables:
  - $ref: ./config/tables/companies.yaml
  - $ref: ./config/tables/contacts.yaml

pages:
  - $ref: ./config/pages/dashboard.yaml
  - $ref: ./config/pages/sign-in.yaml
```

La résolution de `$ref` a lieu **avant** la validation : tout objet contenant exactement une clé — `$ref` dont la valeur est un chemin relatif — est remplacé par le contenu analysé de ce fichier. Un `$ref` peut lui-même contenir d'autres `$ref`, donc les configurations s'imbriquent à n'importe quelle profondeur. Les formes mono-fichier et multi-fichiers sont interchangeables ; choisissez celle qui garde le projet lisible.

:::callout
**Quand scinder.** Gardez une configuration dans un seul fichier tant qu'elle est petite (comme `hello-world`). Scindez avec `$ref` dès qu'une section devient assez grande pour mériter son propre fichier — généralement dès que vous avez plus d'une table, d'une page ou un thème conséquent. La mécanique complète se trouve dans [Fichiers de configuration → Configurations multi-fichiers](/fr/configuration-files#multi-file-configs-with-ref).
:::

## Parcours d'apprentissage

Un ordre pratique pour parcourir les exemples :

1. **hello-world** — comprendre la forme minimale d'une configuration et le tableau `pages`.
2. **landing-page** — ajouter un thème, des composants réutilisables et l'i18n avec les clés de traduction `$t:`.
3. **crud-app** — introduire les tables, l'authentification et les pages liées aux données (formulaires + tableaux de données).
4. **api-only** / **mcp-server** — exécuter Sovrium sans interface : comme backend REST ou serveur MCP face à un LLM.
5. **blog** / **member-portal** / **docs-site** — combiner routes dynamiques, zones selon le rôle et contenu markdown.

## Pages associées

- [Démarrage rapide](/fr/quick-start) — de zéro à une application en cours d'exécution via YAML + CLI ou TypeScript + Bun.
- [Fichiers de configuration](/fr/configuration-files) — composition multi-fichiers YAML, JSON, TypeScript et `$ref`.
- [Référence CLI](/fr/cli) — `sovrium init`, `sovrium agents` et l'ensemble des commandes.
- [Intégration MCP](/fr/mcp-integration) — le modèle de serveur MCP sans interface expliqué.

# Vue d'ensemble du schéma

La référence complète du schéma d'application Sovrium. Un objet de configuration déclaratif comportant 18 propriétés racines — seule `name` est obligatoire. Tout le reste est optionnel, ce qui permet une complexité progressive : d'un simple identifiant d'application minimal jusqu'à une application full-stack complète.

## Structure du schéma

```yaml
name: my-app # App identifier (required)
version: 1.0.0 # SemVer version
description: My application # One-line description

tables: [...] # Data models with 49 field types
pages: [...] # Server-rendered pages (~80 component types)
forms: [...] # Standalone forms capturing submissions
auth: { ... } # Authentication, roles, RBAC, 2FA
theme: { ... } # Design tokens (colors, fonts, etc.)
languages: { ... } # Multi-language support ($t: syntax)

automations: [...] # Event-driven workflows (triggers + actions)
actions: [...] # Reusable action templates ($ref)
connections: [...] # External-service credentials
agents: [...] # AI agents acting under an auth role
buckets: [...] # Named file-storage containers

components: [...] # Reusable UI templates ($ref, $variable)
analytics: { ... } # Cookie-free, first-party analytics
env: { ... } # Declared automation env vars ($env.NAME)
scripts: { ... } # Global page scripts
```

:::callout
**Complexité progressive.** Seule `name` est obligatoire. Ajoutez `tables`, `theme`, `pages`, `auth` et les autres sections à mesure que votre application évolue.
:::

## Propriétés racines

Le schéma d'application comporte 18 propriétés racines. Seule `name` est obligatoire.

| Propriété     | Type              | Description                                                                                                                                           |
| ------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string (requis)   | Identifiant d'application suivant les conventions de nommage npm. Minuscules, max 214 caractères, prend en charge le format à portée (`@scope/name`). |
| `version`     | string            | Chaîne Semantic Versioning 2.0.0 (par ex. `1.0.0`, `2.0.0-beta.1`). Alimente le registre de versions immuable.                                        |
| `description` | string            | Description de l'application sur une seule ligne (max 2000 caractères). Pas de sauts de ligne. Unicode et emojis pris en charge.                      |
| `tables`      | array             | Modèles de données avec 49 types de champ, relations, index, permissions et vues.                                                                     |
| `theme`       | object            | Jetons de design : couleurs, polices, espacements, ombres, animations, points de rupture et rayons de bordure.                                        |
| `languages`   | object            | Prise en charge multilingue avec la syntaxe de traduction `$t:`, détection du navigateur et routage par URL.                                          |
| `auth`        | object            | Stratégies d'authentification (email/mot de passe, lien magique, OAuth), rôles, RBAC, sessions et double authentification.                            |
| `analytics`   | object \| boolean | Analyses respectueuses de la vie privée, sans cookies, first-party. Définissez `true` pour les valeurs par défaut ou configurez avec des options.     |
| `components`  | array             | Modèles d'interface réutilisables avec référencement `$ref` et substitution `$variable`.                                                              |
| `pages`       | array             | Pages rendues côté serveur avec ~80 types de composants, métadonnées SEO et prise en charge i18n.                                                     |
| `forms`       | array             | Formulaires autonomes qui capturent des soumissions dans une table ou déclenchent une automatisation.                                                 |
| `connections` | array             | Identifiants réutilisables pour services externes : OAuth2, clé API, authentification basique et jeton bearer.                                        |
| `env`         | object            | Variables d'environnement déclarées résolues à l'exécution, référencées dans les actions comme `$env.NAME` (jamais journalisées).                     |
| `actions`     | array             | Modèles d'action réutilisables référencés depuis les automatisations via `$ref` avec `$vars`.                                                         |
| `automations` | array             | Workflows pilotés par événements : un déclencheur se déclenche, une séquence d'actions s'exécute.                                                     |
| `agents`      | array             | Agents IA agissant au nom d'un rôle d'authentification au sein d'un ensemble d'outils contraint, avec portes d'approbation et limites de débit.       |
| `buckets`     | array             | Conteneurs de stockage nommés avec des limites de fichiers et des permissions d'accès par bucket.                                                     |
| `scripts`     | object            | Scripts globaux chargés sur chaque page avant les scripts au niveau de la page.                                                                       |

## Détails des propriétés

Les règles et contraintes détaillées des trois propriétés racines scalaires — `name`, `version` et `description` — sont présentées sur la page [Métadonnées de l'application](/fr/app-metadata), qui documente également le registre de versions, la détection de dérive et l'obsolescence des brouillons.

### `name`

Le nom de l'application suit les conventions de nommage npm. En minuscules, compatible avec les URL et unique au sein de votre déploiement.

| Contrainte   | Description                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Motif        | `^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$`. Lettres minuscules, chiffres, traits d'union, points, tildes. |
| Longueur max | 214 caractères maximum (préfixe `@scope/` inclus s'il y a une portée).                                                   |
| Avec portée  | Prend en charge les paquets à portée de style npm : `@scope/name` (par ex. `@acme/dashboard`).                           |

```yaml
# Valid names
name: my-app
name: task-tracker-v2
name: '@acme/dashboard'
```

### `version`

Suit Semantic Versioning 2.0.0 ([semver.org](https://semver.org)). Format : `MAJOR.MINOR.PATCH` avec métadonnées de pré-version et de build optionnelles.

```yaml
version: 1.0.0 # Stable release
version: 2.0.0-beta.1 # Pre-release
version: 1.0.0+build.42 # Build metadata
```

### `description`

Un texte sur une seule ligne décrivant l'application. Affiché dans l'interface d'administration et les métadonnées.

| Contrainte   | Description                                                                      |
| ------------ | -------------------------------------------------------------------------------- |
| Format       | Une seule ligne. Aucun saut de ligne (`\n`) autorisé.                            |
| Longueur max | 2000 caractères maximum.                                                         |
| Unicode      | Prise en charge complète d'Unicode, y compris les emojis et caractères spéciaux. |

## Formats de configuration

Sovrium accepte la configuration en YAML, JSON et TypeScript. Le YAML est recommandé pour sa lisibilité ; le JSON convient à la génération programmatique ; le TypeScript ajoute la sécurité de typage via `@sovrium/types`. Les configurations volumineuses peuvent être réparties sur plusieurs fichiers avec `$ref`. Consultez [Fichiers de configuration](/fr/configuration-files) pour le guide complet.

```yaml
# YAML format (recommended)
name: my-app
version: 1.0.0
tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text }
```

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "tables": [
    {
      "id": 1,
      "name": "tasks",
      "fields": [{ "id": 1, "name": "title", "type": "single-line-text" }]
    }
  ]
}
```

## Validation inter-sections

Les sections racines sont validées _ensemble_, et non isolément. Sovrium rejette une configuration avant le démarrage du serveur lorsque, par exemple :

- un champ `user`/`created-by`/`updated-by` existe mais `auth` n'est pas configuré ;
- une permission de table ou de bucket nomme un rôle qui n'est pas déclaré ;
- un champ de pièce jointe référence un `bucket` absent de `buckets` ;
- un déclencheur ou une action d'automatisation d'enregistrement référence une table qui n'existe pas ;
- une action `$ref` d'automatisation, une référence d'agent IA ou un déclencheur de formulaire nomme quelque chose de non déclaré.

Exécutez [`sovrium validate`](/fr/cli) pour vérifier ces règles avant le déploiement.

## Pages associées

- [Métadonnées de l'application](/fr/app-metadata) — `name`, `version`, `description`, registre de versions, détection de dérive.
- [Vue d'ensemble des tables](/fr/tables-overview) — modèles de données et 49 types de champ.
- [Vue d'ensemble des pages](/fr/pages-overview) — ~80 types de composants pour les pages rendues côté serveur.
- [Vue d'ensemble des formulaires](/fr/forms-overview) — formulaires autonomes et soumissions.
- [Vue d'ensemble de l'authentification](/fr/auth-overview) — stratégies, rôles et RBAC.
- [Vue d'ensemble des automatisations](/fr/automations-overview) — déclencheurs, actions et connexions.
- [Vue d'ensemble de l'IA](/fr/ai-overview) — agents et champs IA-natifs.
- [Vue d'ensemble des buckets](/fr/buckets-overview) — conteneurs de stockage de fichiers.
- [Vue d'ensemble des enregistrements](/fr/records-overview) — interrogation et modification des lignes à l'exécution.
- [Thème](/fr/theme) · [Design responsive](/fr/responsive-design) · [Animations](/fr/animations) · [Langues](/fr/languages).

# Métadonnées de l'application

Trois propriétés racines scalaires identifient votre application : `name`, `version` et `description`. Seule `name` est obligatoire. Ensemble, elles ancrent le registre de versions immuable de Sovrium et sa détection de dérive du schéma.

```yaml
name: '@acme/crm'
version: 2.1.0
description: 'A CRM workspace for managing contacts, deals, and tasks.'
```

## `name`

Le nom de l'application suit les conventions de nommage des paquets npm. Il est en minuscules, compatible avec les URL et constitue la seule propriété obligatoire de tout le schéma.

| Contrainte  | Description                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| Motif       | `^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$` — lettres minuscules, chiffres, traits d'union, points, tildes. |
| Longueur    | 1 à 214 caractères (préfixe `@scope/` inclus s'il y a une portée).                                                        |
| Début       | Ne peut pas commencer par un point ou un tiret bas ; aucune espace en début ou fin.                                       |
| Avec portée | Les noms à portée de style npm sont autorisés : `@scope/name` (par ex. `@acme/dashboard`).                                |

```yaml
# Valid names
name: my-app
name: task-tracker-v2
name: '@acme/dashboard'
```

## `version`

Une chaîne Semantic Versioning 2.0.0 ([semver.org](https://semver.org)). Optionnelle, mais recommandée — lorsqu'elle est présente, elle alimente le registre de versions décrit ci-dessous.

| Règle                | Description                                                                            |
| -------------------- | -------------------------------------------------------------------------------------- |
| Format               | `MAJOR.MINOR.PATCH` (par ex. `1.0.0`). Chaque composant est un entier non négatif.     |
| Pas de 0 initial     | `01.0.0` est rejeté — les composants de version ne doivent pas avoir de zéros en tête. |
| Pré-version          | Suffixe optionnel avec trait d'union : `1.0.0-alpha`, `1.0.0-beta.1`, `2.0.0-rc.1`.    |
| Métadonnées de build | Suffixe optionnel avec signe plus : `1.0.0+build.123`, `1.0.0-alpha+001`.              |

```yaml
version: 1.0.0 # Stable release
version: 2.0.0-beta.1 # Pre-release
version: 1.0.0+build.42 # Build metadata
```

## `description`

Une description sur une seule ligne affichée dans l'interface d'administration et les métadonnées.

| Contrainte   | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| Format       | Une seule ligne — les sauts de ligne (`\n`, `\r`) sont rejetés. |
| Longueur max | 2000 caractères.                                                |
| Unicode      | Prise en charge complète d'Unicode, y compris les emojis.       |

```yaml
description: 'Full-featured e-commerce platform with cart, checkout & payment processing'
```

## Historique des versions

Chaque application Sovrium conserve un **registre de versions immuable** — un journal d'audit en ajout seul des instantanés du schéma. Chaque publication réussie ajoute une ligne contenant l'instantané encodé du schéma, une somme de contrôle SHA-256 de cet instantané, et la `source` qui l'a produit. Restaurer une version antérieure copie son instantané dans une _nouvelle_ ligne ; l'historique n'est jamais modifié.

### Les quatre transports

Une modification du schéma peut arriver par l'un des quatre transports. Chaque transition ajoute exactement une ligne au registre, et la colonne `source` enregistre quel transport l'a produite.

| Transport             | Valeur `source` | Comment une modification arrive                                                                  |
| --------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| **Fichier de config** | `config-file`   | `sovrium start app.yaml` au démarrage, ou `sovrium reload` pour un serveur en cours d'exécution. |
| **Variable d'env**    | `env`           | La variable d'environnement `APP_SCHEMA` (JSON/YAML en ligne ou instantané d'URL distante).      |
| **API d'admin**       | `api`           | L'API HTTP d'administration (`POST /api/admin/schema/draft/publish`).                            |
| **MCP**               | `mcp`           | Un outil d'édition de schéma MCP (`{app}_schema_draft_publish`).                                 |

Une cinquième `source`, `restore`, marque les lignes créées par la restauration d'une version antérieure. Les sommes de contrôle sont autonomes (chaque ligne hache son propre instantané, pas celui d'un parent), ce qui rend sûre l'élagage des lignes intérieures.

## Détection de dérive du schéma

Comme le schéma actif peut être modifié à l'exécution (via l'API d'admin ou MCP) alors qu'un `config-file` reste sur le disque, l'application active peut **dériver** de son fichier source. Sovrium calcule une posture de dérive à partir du registre et l'expose pour que l'outillage puisse avertir avant d'écraser un travail.

| Statut de dérive    | Signification                                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `in-sync`           | La version active provient d'un transport `config-file`/`env` — l'application en cours correspond à sa source.                            |
| `drifted-from-file` | La version active provient de `api`/`mcp`/`restore` — l'application active a été modifiée à l'exécution et ne correspond plus au fichier. |
| `file-ahead`        | La somme de contrôle normalisée du fichier sur le disque a changé — le fichier source est désormais en avance sur l'application active.   |

:::callout
**`sovrium reload` respecte la dérive.** Recharger un serveur lancé par `config-file` sonde d'abord le statut de dérive actif. Si l'application active est en `drifted-from-file`, le rechargement est refusé sauf si vous passez `--force` — empêchant un écrasement accidentel des modifications d'exécution par un contenu de fichier obsolète.
:::

## Obsolescence des brouillons

L'édition à l'exécution se fait sur un **brouillon modifiable** — une copie de travail unique dérivée de la version active. Le brouillon enregistre la `baseVersion` dont il est issu, qui sert à la fois de jeton de concurrence optimiste à la publication et d'**ancre d'obsolescence**.

Un brouillon devient **obsolète** dès que `draft.baseVersion` ne correspond plus au numéro de version active. Cela se produit lorsqu'un autre administrateur publie, ou lorsqu'un rechargement `config-file`/`env` déplace la base sous un brouillon ouvert.

| Opération sur un brouillon obsolète | Autorisée ?                                  |
| ----------------------------------- | -------------------------------------------- |
| Aperçu / validation / édition       | Oui                                          |
| Publication                         | Non — bloquée jusqu'au rebasage du brouillon |

Pour lever l'obsolescence, **rebasez** le brouillon : repointez sa `baseVersion` vers la version active, en laissant le contenu du brouillon intact. Il n'y a pas de fusion au niveau des champs — la prochaine publication est une opération d'instantané complet, le dernier auteur l'emportant, cohérente avec le système de schéma instantané-atomique de Sovrium.

## Étapes suivantes

- [Vue d'ensemble du schéma](/fr/overview) — toutes les propriétés racines en un coup d'œil.
- [Fichiers de configuration](/fr/configuration-files) — comment les transports `config-file` et `env` chargent votre application.
- [Référence CLI](/fr/cli) — `sovrium reload` et la gestion de la dérive.

# Thème

La propriété `theme` définit votre système de design à travers des catégories de jetons optionnelles. Tous les jetons génèrent des propriétés CSS personnalisées et des classes utilitaires Tailwind CSS. Chaque catégorie est optionnelle — un thème minimal peut se limiter aux couleurs.

## Propriétés du thème

| Propriété      | Description                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `baseline`     | `'extend'` (défaut) conserve l'apparence du système de design par défaut de Sovrium ; `'replace'` la remplace par un socle neutre. |
| `colors`       | Jetons de couleur nommés. Chacun génère `--color-{name}` et les utilitaires `bg-{name}`/`text-{name}`/`border-{name}`.             |
| `darkColors`   | Surcharges de couleur pour le mode sombre, reflétant la structure de `colors`.                                                     |
| `fonts`        | Typographie pour les polices de titre, corps et monospace.                                                                         |
| `spacing`      | Jetons d'espacement nommés sous forme de chaînes de classes Tailwind.                                                              |
| `animations`   | Jetons de design pour les keyframes et le mouvement. Voir [Animations](/fr/animations).                                            |
| `breakpoints`  | Points de rupture responsifs en valeurs de pixels. Voir [Design responsive](/fr/responsive-design).                                |
| `shadows`      | Jetons de box-shadow nommés, chacun devenant un utilitaire `shadow-{name}`.                                                        |
| `borderRadius` | Jetons de rayon nommés, chacun devenant un utilitaire `rounded-{name}`.                                                            |
| `codeBlock`    | Thème de coloration syntaxique pour les blocs de code délimités en markdown.                                                       |

## `colors`

Jetons de couleur nommés sous forme de paires clé-valeur. Chacun devient une variable CSS (`--color-{name}`) et une classe Tailwind (`bg-{name}`, `text-{name}`).

| Propriété  | Description                                                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `{name}`   | Nom du jeton (par ex. `primary`, `accent`). Utilisé pour générer la variable CSS `--color-{name}` et les utilitaires Tailwind. |
| Sortie CSS | Génère la variable CSS `--color-{name}` ainsi que les classes utilitaires `bg-{name}`, `text-{name}`, `border-{name}`.         |

```yaml
theme:
  colors:
    primary: '#3b82f6'
    secondary: '#8b5cf6'
    accent: '#f59e0b'
    background: '#0a0e1a'
    text: '#e8ecf4'
    muted: '#64748b'
```

## `fonts`

Configuration typographique pour les polices de titre, corps et monospace. Prend en charge la famille, la pile de secours, les graisses, le style, la taille, l'interligne, l'espacement des lettres, la transformation et l'url.

| Propriété       | Description                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `family`        | Nom de la famille de police (par ex. `"Inter"`, `"Roboto"`). Correspond à la propriété CSS `font-family`.              |
| `fallback`      | Pile de polices de secours utilisée lorsque la police principale est indisponible (par ex. `"system-ui, sans-serif"`). |
| `weights`       | Tableau de graisses numériques à charger (par ex. `[400, 600, 700]`). Optimise la taille du téléchargement.            |
| `style`         | Style de police : `normal`, `italic` ou `oblique` (défaut : `normal`).                                                 |
| `size`          | Taille de police de base en valeur CSS (par ex. `"16px"`, `"1rem"`). Appliquée au texte du corps.                      |
| `lineHeight`    | Multiplicateur d'interligne ou valeur CSS (par ex. `"1.5"`, `"1.2"`). Contrôle l'espacement vertical entre les lignes. |
| `letterSpacing` | Espacement des lettres en valeur CSS (par ex. `"0.05em"`, `"-0.01em"`).                                                |
| `transform`     | Transformation du texte : `none`, `uppercase`, `lowercase` ou `capitalize`.                                            |
| `url`           | URL de fichier de police ou URL Google Fonts. Injectée comme `<link>` dans `<head>`.                                   |

```yaml
theme:
  fonts:
    heading:
      family: Inter
      weights: [600, 700]
      lineHeight: '1.2'
    body:
      family: Inter
      size: '16px'
      url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700'
```

:::callout
**Google Fonts.** Ajoutez une `url` pour charger automatiquement des polices personnalisées. L'URL est injectée comme balise `<link>` dans le head de la page.
:::

## `spacing`

Jetons d'espacement nommés sous forme de chaînes de classes Tailwind. Définissez les largeurs de conteneur, le padding de section, les gaps et l'espacement des composants.

```yaml
theme:
  spacing:
    container: 'max-w-7xl mx-auto px-4'
    section: 'py-16 sm:py-20'
    card: 'p-6'
    gap: 'gap-8'
```

## `baseline` et mode sombre

`baseline` contrôle si les composants préconstruits de Sovrium étendent l'apparence par défaut ou partent d'un socle neutre.

| Valeur      | Comportement                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------- |
| `'extend'`  | _(défaut)_ Les composants héritent des jetons du système de design v1 par défaut de Sovrium. |
| `'replace'` | Les composants abandonnent l'apparence par défaut et partent d'un socle neutre, sans style.  |

`darkColors` reflète la structure de `colors` et fournit des surcharges appliquées en mode sombre, de sorte qu'un même thème peut livrer les deux palettes.

```yaml
theme:
  baseline: extend
  colors:
    background: '#ffffff'
    text: '#0f172a'
  darkColors:
    background: '#0f172a'
    text: '#f8fafc'
```

## Ombres, rayons de bordure et blocs de code

Jetons de design supplémentaires pour l'élévation, le style des coins et la coloration syntaxique.

### `shadows`

Jetons d'ombre nommés sous forme de valeurs CSS `box-shadow`. Chacun devient un utilitaire `shadow-{name}`.

### `borderRadius`

Jetons de rayon de bordure nommés sous forme de valeurs CSS. Chacun devient une classe utilitaire `rounded-{name}`.

### `codeBlock`

Sélectionne le thème de coloration syntaxique utilisé pour les blocs de code délimités en markdown.

```yaml
theme:
  shadows:
    card: '0 4px 6px rgba(0, 0, 0, 0.1)'
    elevated: '0 10px 30px rgba(0, 0, 0, 0.2)'
  borderRadius:
    card: '0.75rem'
    button: '0.5rem'
```

## Points de rupture responsifs et animations

`breakpoints` et `animations` disposent chacun d'une page de référence dédiée :

- [Design responsive](/fr/responsive-design) — valeurs de pixels des points de rupture et surcharges par point de rupture.
- [Animations](/fr/animations) — jetons de keyframe et de mouvement.

```yaml
theme:
  breakpoints:
    sm: '640px'
    md: '768px'
    lg: '1024px'
```

:::callout
**Les valeurs de point de rupture sont des chaînes de pixels.** Chaque valeur de `breakpoints` doit respecter le format `<number>px` (par ex. `'768px'`) — les nombres bruts et les unités non pixel sont rejetés par le schéma.
:::

## Exemple complet

Une configuration de thème complète combinant couleurs, polices, espacement et ombres.

```yaml
theme:
  colors:
    primary: '#6366f1'
    secondary: '#8b5cf6'
    accent: '#f59e0b'
    background: '#0f172a'
    surface: '#1e293b'
    text: '#f8fafc'
    muted: '#94a3b8'
  fonts:
    heading:
      family: Inter
      weights: [600, 700]
      url: 'https://fonts.googleapis.com/css2?family=Inter:wght@600;700&display=swap'
    body:
      family: Inter
      weights: [400, 500]
  spacing:
    container: 'max-w-6xl mx-auto px-4'
    section: 'py-16 sm:py-20'
```

![Une application CRM rendue avec des couleurs, polices et espacements personnalisés.](/docs/screenshots/app-page-en.png)

# Design responsive

Le système responsive de Sovrium repose sur des **points de rupture** définis dans `theme.breakpoints`. Chaque point de rupture devient une media query `min-width`, et les propriétés des composants peuvent être surchargées par point de rupture pour des mises en page mobile-first.

## `theme.breakpoints`

Une table associant des noms de points de rupture à des valeurs de pixels. Les noms sont alphanumériques en minuscules ; les valeurs sont des chaînes de pixels.

| Propriété | Description                                                                                    |
| --------- | ---------------------------------------------------------------------------------------------- |
| clé       | Nom du point de rupture (alphanumérique en minuscules, par ex. `sm`, `md`, `lg`, `xl`, `2xl`). |
| valeur    | Seuil de largeur minimale sous forme de chaîne de pixels (par ex. `'640px'`, `'768px'`).       |

```yaml
theme:
  breakpoints:
    sm: '640px'
    md: '768px'
    lg: '1024px'
    xl: '1280px'
    '2xl': '1536px'
```

Ceux-ci correspondent aux paliers responsifs standards :

| Point de rupture | Largeur min | Cible typique         |
| ---------------- | ----------- | --------------------- |
| `sm`             | `640px`     | Grand mobile          |
| `md`             | `768px`     | Tablette              |
| `lg`             | `1024px`    | Ordinateur portable   |
| `xl`             | `1280px`    | Ordinateur de bureau  |
| `2xl`            | `1536px`    | Grand écran de bureau |

:::callout
**Les valeurs doivent être des chaînes de pixels.** Chaque valeur de point de rupture doit respecter le format `<number>px` (par ex. `'768px'`). Les unités non pixel (`rem`, `em`, `%`) sont rejetées par le schéma.
:::

## Surcharges par point de rupture

Les points de rupture alimentent les variantes utilitaires mobile-first de Tailwind. Un utilitaire de base s'applique à toutes les tailles ; une variante préfixée (`md:`, `lg:`, …) s'applique à partir de ce point de rupture vers le haut. C'est ainsi qu'un même composant s'adapte aux différentes tailles d'écran.

```yaml
pages:
  - name: home
    path: /
    components:
      - type: container
        element: section
        props:
          # 1 column on mobile, 2 from md, 3 from lg
          className: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4'
        children:
          - { type: card, props: { className: 'p-4 md:p-6' } }
          - { type: card, props: { className: 'p-4 md:p-6' } }
          - { type: card, props: { className: 'p-4 md:p-6' } }
```

Dans l'exemple ci-dessus :

- `grid-cols-1` s'applique sur tous les écrans.
- `md:grid-cols-2` le remplace à partir de `768px` vers le haut.
- `lg:grid-cols-3` le remplace à nouveau à partir de `1024px` vers le haut.
- `p-4` est le padding de base ; `md:p-6` l'augmente à partir du point de rupture `md`.

:::callout
**Mobile-first.** Déclarez toujours la plus petite mise en page comme utilitaire de base (sans préfixe), puis superposez les surcharges pour grands écrans avec des préfixes de point de rupture. Cela garantit une valeur par défaut sensée sur le plus petit viewport avant que toute media query ne s'applique.
:::

## Points de rupture personnalisés

Définissez vos propres noms en complément ou à la place des paliers standards. Un point de rupture personnalisé génère un préfixe utilitaire correspondant.

```yaml
theme:
  breakpoints:
    phone: '480px'
    tablet: '834px'
    wide: '1440px'
```

```yaml
props:
  className: 'flex-col tablet:flex-row wide:gap-12'
```

## Étapes suivantes

- [Thème](/fr/theme) — la référence complète des jetons de thème.
- [Animations](/fr/animations) — jetons de keyframe et de mouvement.
- [Vue d'ensemble des pages](/fr/pages-overview) — propriétés des composants et la propriété `className`.

# Animations

Le bloc `theme.animations` définit des jetons de design de mouvement — animations nommées, durées et courbes d'accélération réutilisables, et définitions `@keyframes`. Les jetons génèrent du CSS que tout composant peut référencer via sa `className`.

## `theme.animations`

`animations` est une table indexée par nom de jeton (alphanumérique, doit commencer par une lettre). Chaque valeur prend l'une des quatre formes, offrant un éventail allant d'une bascule sur une ligne à une définition de keyframe complète.

| Forme de valeur        | À utiliser pour                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Booléen                | Activer ou désactiver une animation nommée : `fadeIn: true`.                                     |
| Chaîne                 | Une valeur d'animation CSS brute ou un nom de classe utilitaire : `slideUp: 'animate-slide-up'`. |
| Objet de configuration | Contrôle détaillé : `enabled`, `duration`, `easing`, `delay`, `keyframes`.                       |
| Table de jetons        | Une table imbriquée de jetons de design `duration`, `easing` ou `keyframes` nommés.              |

### Formes booléenne et chaîne

Le moyen le plus rapide d'activer une animation intégrée, ou de créer un alias de nom de classe.

```yaml
theme:
  animations:
    fadeIn: true
    slideUp: 'animate-slide-up'
```

### Forme objet de configuration

Une animation détaillée avec contrôle du timing.

| Propriété   | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| `enabled`   | Booléen. Indique si l'animation est active.                                               |
| `duration`  | Durée CSS (par ex. `'300ms'`, `'0.5s'`).                                                  |
| `easing`    | Fonction CSS d'accélération/temporisation (par ex. `'ease-in-out'`, `cubic-bezier(...)`). |
| `delay`     | Durée CSS à attendre avant de démarrer (par ex. `'0ms'`).                                 |
| `keyframes` | Table de définition de keyframe en ligne.                                                 |

```yaml
theme:
  animations:
    modalOpen:
      enabled: true
      duration: '300ms'
      easing: 'ease-in-out'
      delay: '0ms'
```

### Tables de jetons imbriquées

Pour un système de mouvement réutilisable, déclarez `duration`, `easing` et `keyframes` comme tables de jetons nommés. Les autres animations et classes de composants peuvent alors référencer ces jetons au lieu de répéter des valeurs brutes.

```yaml
theme:
  animations:
    duration:
      fast: '200ms'
      normal: '300ms'
      slow: '500ms'
    easing:
      smooth: 'cubic-bezier(0.4, 0, 0.2, 1)'
      bounce: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)'
    keyframes:
      fadeIn:
        from: { opacity: '0' }
        to: { opacity: '1' }
      colorPulse:
        '0%': { backgroundColor: '$colors.primary' }
        '50%': { backgroundColor: '$colors.accent' }
        '100%': { backgroundColor: '$colors.primary' }
```

| Table de jetons | Règle de clé                             | Valeur                                                         |
| --------------- | ---------------------------------------- | -------------------------------------------------------------- |
| `duration`      | Alphanumérique, commence par une lettre. | Chaîne de durée CSS.                                           |
| `easing`        | Alphanumérique, commence par une lettre. | Fonction CSS d'accélération/temporisation.                     |
| `keyframes`     | Alphanumérique, commence par une lettre. | Une table de keyframe (`from`/`to` ou paliers en pourcentage). |

:::callout
**Référencez les couleurs du thème dans les keyframes.** Les valeurs de keyframe peuvent référencer d'autres jetons de thème avec la syntaxe `$colors.<name>` (par ex. `backgroundColor: '$colors.primary'`), gardant le mouvement synchronisé avec votre palette.
:::

## Note d'écoconception

Le mouvement est un enjeu d'empreinte. Préférez des durées courtes et évitez les longues animations infinies au premier rendu. La posture éco de Sovrium est contrôlée par l'opérateur via des variables d'environnement, et non par le schéma de thème — consultez la référence des [Variables d'environnement](/fr/env-vars) pour les contrôles `ECO_*` qui régissent le comportement client.

## Étapes suivantes

- [Thème](/fr/theme) — la référence complète des jetons de thème.
- [Design responsive](/fr/responsive-design) — points de rupture et surcharges par point de rupture.
- [Vue d'ensemble des pages](/fr/pages-overview) — application des classes d'animation aux composants.

# Langues

Prise en charge multilingue avec clés de traduction, détection de la langue du navigateur et routage automatique par URL (`/en/...`, `/fr/...`). Référencez les traductions dans les pages avec le préfixe `$t:`.

## Définir les langues

Définissez une langue par défaut et listez les langues prises en charge avec code, locale, libellé et direction du texte.

| Propriété          | Description                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `default`          | Code ISO 639-1 de la langue par défaut (par ex. `"en"`). Utilisé quand aucune langue n'est détectée.                  |
| `supported`        | Tableau d'objets d'entrée de langue. Chacun définit une langue prise en charge.                                       |
| `fallback`         | Code de langue de secours (2 lettres). Utilisé quand une clé de traduction est manquante dans la langue active.       |
| `detectBrowser`    | Booléen. Lorsque `true`, détecte automatiquement la langue du navigateur de l'utilisateur lors de la première visite. |
| `persistSelection` | Booléen. Lorsque `true`, mémorise le choix de langue de l'utilisateur entre les sessions.                             |

```yaml
languages:
  default: en
  supported:
    - code: en
      locale: en-US
      label: English
      direction: ltr
    - code: fr
      locale: fr-FR
      label: 'Français'
      direction: ltr
    - code: ar
      locale: ar-SA
      label: 'العربية'
      direction: rtl
```

## Propriétés d'entrée de langue

Chaque entrée du tableau `supported` décrit une langue avec ces propriétés.

| Propriété   | Description                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | Code de langue ISO 639-1 (par ex. `"en"`, `"fr"`, `"ar"`). Utilisé dans le routage par URL (`/en/`, `/fr/`).                       |
| `locale`    | Identifiant de locale complet (par ex. `"en-US"`, `"fr-FR"`, `"ar-SA"`). Utilisé pour le formatage des nombres et dates.           |
| `label`     | Nom lisible de la langue affiché dans les sélecteurs de langue (par ex. `"English"`, `"Français"`).                                |
| `direction` | Direction du texte : `"ltr"` (gauche à droite) pour la plupart des langues, `"rtl"` (droite à gauche) pour l'arabe, l'hébreu, etc. |
| `flag`      | Emoji drapeau ou chemin d'icône affiché dans les sélecteurs de langue.                                                             |

:::callout
**Prise en charge RTL.** Définissez `direction: rtl` pour les langues droite-à-gauche comme l'arabe ou l'hébreu. Sovrium inverse automatiquement la mise en page, aligne le texte à droite et applique l'attribut `dir="rtl"` à la racine HTML.
:::

## Clés de traduction

Définissez des paires clé-valeur pour chaque langue. Les clés utilisent la notation pointée pour l'organisation.

```yaml
languages:
  translations:
    en:
      hero.title: 'Welcome to My App'
      hero.description: 'Build faster with Sovrium'
      nav.home: 'Home'
      nav.about: 'About'
    fr:
      hero.title: 'Bienvenue sur Mon App'
      hero.description: 'Construisez plus vite avec Sovrium'
      nav.home: 'Accueil'
      nav.about: 'À propos'
```

## Utiliser les traductions

Référencez les traductions dans tout contenu ou valeur de propriété avec le préfixe `$t:`.

```yaml
# Reference translations with $t: prefix
pages:
  - name: home
    path: /
    sections:
      - type: section
        children:
          - type: h1
            content: '$t:hero.title'
          - type: paragraph
            content: '$t:hero.description'
```

:::callout
**Syntaxe de traduction `$t:`.** Utilisez `$t:key.path` dans tout contenu ou valeur de propriété de page pour référencer une traduction. Exemple : `$t:hero.title` se résout en `"Welcome"` en anglais et `"Bienvenue"` en français.
:::

![Version anglaise de l'application](/docs/screenshots/app-translation-en.png)

![Version française de l'application](/docs/screenshots/app-translation-fr.png)

## Ajouter une nouvelle langue

Suivez ces étapes pour ajouter une nouvelle langue à votre application.

1. **Ajouter l'entrée de langue** — Ajoutez un nouvel élément au tableau `supported` avec `code`, `locale`, `label` et `direction`.
2. **Ajouter les traductions** — Créez une nouvelle section `translations` pour le code de langue avec toutes les clés nécessaires.
3. **Tester la langue** — Visitez `/[lang-code]/` dans votre navigateur pour vérifier que la nouvelle langue s'affiche correctement.

# Aperçu des tables

Les tables définissent vos modèles de données. Chaque table est une entité distincte (utilisateurs, produits, commandes) dont les `fields` déclarent les colonnes que les enregistrements peuvent stocker. Les tables sont le fondement d'une application Sovrium : les pages affichent leurs enregistrements, les formulaires y écrivent, les automatisations réagissent à leurs changements et les API REST/MCP les exposent.

Une table comporte au minimum un `id`, un `name` et un tableau `fields`. Tout le reste — clés primaires, index, contraintes, vues, permissions, webhooks et exposition à l'IA — est optionnel et vient s'ajouter par-dessus.

```yaml
tables:
  - id: 1
    name: Contacts
    fields:
      - { id: 1, name: email, type: email, required: true, unique: true }
      - { id: 2, name: full_name, type: single-line-text, required: true }
      - { id: 3, name: created_at, type: created-at, indexed: true }
```

## Propriétés de la table

Chaque entrée du tableau `tables` accepte les propriétés suivantes.

| Propriété             | Description                                                                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | Identifiant entier unique de la table. Généré automatiquement lorsqu'il est omis.                                                                                                       |
| `name`                | Nom convivial de la table. Peut contenir des espaces et une casse mixte ; assaini pour l'usage en base de données (minuscules avec underscores). Maximum 63 caractères.                 |
| `fields`              | Tableau de définitions de champs. Au moins un champ est requis. Les noms et identifiants de champs doivent être uniques au sein de la table.                                            |
| `primaryKey`          | Configuration de la clé primaire. Par défaut, une colonne `id` générée automatiquement. Voir [Index et contraintes](/fr/table-indexes-constraints).                                     |
| `unique`              | Tableau de déclarations de contraintes d'unicité de premier niveau. Chaque entrée couvre un ou plusieurs champs (par ex. `[{ fields: [slug] }]`).                                       |
| `indexes`             | Tableau de définitions d'index pour les performances des requêtes et l'application de l'unicité.                                                                                        |
| `uniqueConstraints`   | _(via `unique`)_ Unicité multi-champs. Les entrées mono-champ se replient dans `field.unique` ; les entrées composites deviennent des index btree uniques.                              |
| `foreignKeys`         | Définitions de clés étrangères composites (multi-colonnes). Les clés étrangères mono-colonne sont créées automatiquement à partir des champs `relationship`.                            |
| `constraints`         | Tableau de contraintes CHECK avec des expressions SQL pour la validation de données inter-champs.                                                                                       |
| `views`               | Vues enregistrées avec filtres, tri, regroupement et champs visibles préconfigurés. Voir [Vues](/fr/table-views).                                                                       |
| `permissions`         | Permissions RBAC contrôlant la création, la lecture, la mise à jour, la suppression, la restauration, les commentaires et l'accès par champ. Voir [Permissions](/fr/table-permissions). |
| `rowLevelPermissions` | Prédicats `when` côté serveur par opération CRUD pour un cloisonnement des lignes en défense en profondeur.                                                                             |
| `webhooks`            | Webhooks sortants déclenchés lors des événements de création/mise à jour/suppression d'enregistrements. Voir [Webhooks](/fr/table-webhooks).                                            |
| `comments`            | Configuration du système de commentaires (commentaires invités, modération, fils de discussion).                                                                                        |
| `aiAccess`            | Déclare la table éligible à l'exposition via le serveur MCP de Sovrium afin que les assistants IA puissent lister/lire/écrire des enregistrements (sous réserve du RBAC).               |
| `allowDestructive`    | Booléen. Lorsqu'il vaut `true`, autorise les migrations de schéma destructrices (suppression de colonnes, changements de type). Par défaut `false`.                                     |
| `allowForceDelete`    | Booléen. Activation par table autorisant la suppression définitive via le tableau de bord d'administration (effacement RGPD). Par défaut `false`. Voir la note ci-dessous.              |

:::callout
**Suppression douce par défaut.** Supprimer un enregistrement définit `deleted_at`/`deleted_by` et laisse la ligne récupérable via `/restore`. Ne définissez `allowForceDelete: true` que lorsqu'une table nécessite une suppression définitive irréversible (par ex. le droit à l'effacement RGPD sur une table RH). Les registres financiers et les tables liées à l'audit devraient conserver la valeur par défaut `false` — le point de terminaison de suppression définitive de l'administration renvoie `404` lorsque la suppression définitive n'est pas autorisée.
:::

## Propriétés de base des champs

Chaque champ — quel que soit son type — étend une base commune. Ces propriétés sont disponibles sur les 49 types de champs.

| Propriété      | Description                                                                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Identifiant entier unique du champ au sein de la table. Généré automatiquement de manière séquentielle lorsqu'il est omis.                                                                      |
| `name`         | Identifiant de colonne. Doit commencer par une lettre et ne contenir que des lettres minuscules, des chiffres et des underscores (`^[a-z][a-z0-9_]*`). Maximum 63 caractères.                   |
| `type`         | L'un des 49 types de champs disponibles (par ex. `single-line-text`, `integer`, `relationship`). Voir [Types de champs](/fr/field-types-overview).                                              |
| `required`     | Booléen. Lorsqu'il vaut `true`, le champ doit avoir une valeur pour chaque enregistrement.                                                                                                      |
| `unique`       | Booléen. Lorsqu'il vaut `true`, deux enregistrements ne peuvent pas partager la même valeur.                                                                                                    |
| `indexed`      | Booléen. Lorsqu'il vaut `true`, crée un index de base de données sur ce champ pour accélérer les requêtes.                                                                                      |
| `searchWeight` | Poids de pertinence pour la recherche plein texte PostgreSQL : `A` (le plus élevé) à `D` (le plus bas). Effectif uniquement lorsque `indexed: true` et que la source de données utilise la FTS. |
| `storage`      | Objet de configuration du stockage. `storage.compression` (booléen) active la compression pour les grandes valeurs de texte ou de pièce jointe.                                                 |

:::callout
**`default` est spécifique au type, et non une propriété de base.** La plupart des champs porteurs de valeur (texte, numérique, sélection, date, couleur, …) exposent un `default` dont le type de valeur correspond au champ. Les champs système (`created-at`, relationnels, calculés, IA) ne le font pas. Chaque page de type de champ indique si `default` est disponible.
:::

### Exemple : une table plus riche

```yaml
tables:
  - id: 2
    name: Products
    fields:
      - { id: 1, name: sku, type: single-line-text, required: true, unique: true }
      - {
          id: 2,
          name: title,
          type: single-line-text,
          required: true,
          searchWeight: A,
          indexed: true,
        }
      - { id: 3, name: description, type: long-text, searchWeight: B }
      - { id: 4, name: price, type: currency, required: true, currency: USD }
      - { id: 5, name: in_stock, type: checkbox, default: true }
    primaryKey: { type: auto-increment, field: id }
    indexes:
      - { name: idx_products_sku, fields: [sku], unique: true }
    permissions:
      read: all
      create: [admin, editor]
      update: [admin, editor]
      delete: [admin]
```

## Pages connexes

- [Aperçu des types de champs](/fr/field-types-overview) — les 49 types de champs par catégorie.
- [Permissions](/fr/table-permissions) — RBAC et contrôle d'accès par champ.
- [Index et contraintes](/fr/table-indexes-constraints) — clés primaires, index, contraintes CHECK.
- [Relations](/fr/table-relationships) — relier les tables entre elles.
- [Vues](/fr/table-views) — filtres, tris et regroupements enregistrés.
- [Validation](/fr/table-validation) — règles de validation au niveau du champ et de la table.
- [Webhooks](/fr/table-webhooks) — HTTP sortant sur les événements d'enregistrement.

# Types de champs

Sovrium fournit **49 types de champs**, organisés en 9 catégories. Chaque champ partage les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs) (`id`, `name`, `type`, `required`, `unique`, `indexed`, `searchWeight`, `storage`) et y ajoute des propriétés spécifiques au type.

:::callout
**Note sur le comptage.** Cette documentation décrit **49** types de champs, dérivés directement de l'union de champs du schéma (`FieldUnionSchema`, en excluant le fourre-tout interne `unknown`). L'aperçu des fonctionnalités du produit (`FEATURES.md`) indique actuellement **52** — ce chiffre est une dérive et ne doit pas être propagé. La répartition faisant autorité est le tableau par catégorie ci-dessous, dont la somme vaut exactement 49.
:::

## Les 9 catégories

| Catégorie                                     | Nombre | Types de champs                                                                                      |
| --------------------------------------------- | :----: | ---------------------------------------------------------------------------------------------------- |
| [Texte](/fr/text-fields)                      |   6    | `single-line-text`, `long-text`, `rich-text`, `email`, `url`, `phone-number`                         |
| [Numérique](/fr/number-fields)                |   6    | `integer`, `decimal`, `currency`, `percentage`, `rating`, `progress`                                 |
| [Date et heure](/fr/datetime-fields)          |   7    | `date`, `datetime`, `time`, `duration`, `created-at`, `updated-at`, `deleted-at`                     |
| [Sélection](/fr/selection-fields)             |   4    | `checkbox`, `single-select`, `multi-select`, `status`                                                |
| [Relationnel](/fr/relational-fields)          |   3    | `relationship`, `lookup`, `rollup`                                                                   |
| [Utilisateur et audit](/fr/user-audit-fields) |   4    | `user`, `created-by`, `updated-by`, `deleted-by`                                                     |
| [Pièce jointe / Média](/fr/attachment-fields) |   3    | `single-attachment`, `multiple-attachments`, `barcode`                                               |
| [Avancé](/fr/advanced-fields)                 |   9    | `formula`, `count`, `autonumber`, `button`, `json`, `array`, `color`, `code`, `geolocation`          |
| [IA](/fr/ai-fields)                           |   7    | `ai-generate`, `ai-summary`, `ai-categorize`, `ai-extract`, `ai-sentiment`, `ai-tag`, `ai-translate` |
| **Total**                                     | **49** |                                                                                                      |

## Résumé rapide

| Type                   | Catégorie         | Ce qu'il stocke                                                        |
| ---------------------- | ----------------- | ---------------------------------------------------------------------- |
| `single-line-text`     | Texte             | Texte court sur une seule ligne (noms, titres, libellés).              |
| `long-text`            | Texte             | Texte brut multiligne (notes, descriptions).                           |
| `rich-text`            | Texte             | HTML formaté via un éditeur WYSIWYG.                                   |
| `email`                | Texte             | Adresse e-mail avec validation RFC 5322.                               |
| `url`                  | Texte             | Adresse web avec validation d'URL.                                     |
| `phone-number`         | Texte             | Numéro de téléphone stocké comme texte (formats internationaux).       |
| `integer`              | Numérique         | Nombres entiers avec min/max optionnels.                               |
| `decimal`              | Numérique         | Décimaux à précision fixe (1–10 décimales).                            |
| `currency`             | Numérique         | Valeurs monétaires avec code ISO 4217 et mise en forme.                |
| `percentage`           | Numérique         | Valeurs en pourcentage, affichées avec `%`.                            |
| `rating`               | Numérique         | Note en étoiles/icônes (`max` 1–10).                                   |
| `progress`             | Numérique         | Barre de progression 0–100 avec couleur optionnelle.                   |
| `date`                 | Date et heure     | Date calendaire, heure optionnelle.                                    |
| `datetime`             | Date et heure     | Date et heure, sensible au fuseau horaire.                             |
| `time`                 | Date et heure     | Heure de la journée sans date.                                         |
| `duration`             | Date et heure     | Temps écoulé / heures travaillées.                                     |
| `created-at`           | Date et heure     | Horodatage de création défini par le système.                          |
| `updated-at`           | Date et heure     | Horodatage de modification mis à jour par le système.                  |
| `deleted-at`           | Date et heure     | Horodatage de suppression douce (NULL = actif).                        |
| `checkbox`             | Sélection         | Booléen vrai/faux.                                                     |
| `single-select`        | Sélection         | Une option d'une liste.                                                |
| `multi-select`         | Sélection         | Plusieurs options d'une liste.                                         |
| `status`               | Sélection         | États de workflow colorés.                                             |
| `relationship`         | Relationnel       | Lien par clé étrangère vers une autre table.                           |
| `lookup`               | Relationnel       | Un champ lu depuis un enregistrement lié.                              |
| `rollup`               | Relationnel       | Agrégation sur des enregistrements liés.                               |
| `user`                 | Utilisateur/Audit | Référence à un utilisateur (unique ou multiple).                       |
| `created-by`           | Utilisateur/Audit | Utilisateur créateur défini par le système.                            |
| `updated-by`           | Utilisateur/Audit | Dernier utilisateur modificateur défini par le système.                |
| `deleted-by`           | Utilisateur/Audit | Utilisateur ayant supprimé, défini par le système.                     |
| `single-attachment`    | Pièce jointe      | Un fichier téléversé.                                                  |
| `multiple-attachments` | Pièce jointe      | Plusieurs fichiers téléversés.                                         |
| `barcode`              | Pièce jointe      | Valeur de code-barres (identification de produit).                     |
| `formula`              | Avancé            | Valeur calculée à partir d'une expression de formule.                  |
| `count`                | Avancé            | Comptage d'enregistrements liés.                                       |
| `autonumber`           | Avancé            | Nombre auto-incrémenté avec préfixe/remplissage.                       |
| `button`               | Avancé            | Bouton interactif déclenchant une URL ou une automatisation.           |
| `json`                 | Avancé            | Données JSON structurées.                                              |
| `array`                | Avancé            | Tableau de valeurs typées.                                             |
| `color`                | Avancé            | Valeur de couleur hexadécimale.                                        |
| `code`                 | Avancé            | Code source avec coloration syntaxique.                                |
| `geolocation`          | Avancé            | Coordonnées latitude/longitude.                                        |
| `ai-generate`          | IA                | Texte généré par l'IA à partir d'une invite.                           |
| `ai-summary`           | IA                | Résumé par l'IA des champs sources.                                    |
| `ai-categorize`        | IA                | Classification à catégorie unique par l'IA.                            |
| `ai-extract`           | IA                | Extraction structurée par l'IA (JSON Schema).                          |
| `ai-sentiment`         | IA                | Analyse de sentiment par l'IA.                                         |
| `ai-tag`               | IA                | Attribution multi-étiquettes par l'IA depuis une liste d'autorisation. |
| `ai-translate`         | IA                | Traduction par l'IA vers une langue cible.                             |

## Pages par catégorie

- [Champs texte](/fr/text-fields)
- [Champs numériques](/fr/number-fields)
- [Champs date et heure](/fr/datetime-fields)
- [Champs de sélection](/fr/selection-fields)
- [Champs relationnels](/fr/relational-fields)
- [Champs utilisateur et audit](/fr/user-audit-fields)
- [Champs pièce jointe](/fr/attachment-fields)
- [Champs avancés](/fr/advanced-fields)
- [Champs IA](/fr/ai-fields)

# Champs texte

Six types de champs stockent du contenu textuel, des libellés courts au texte enrichi formaté en passant par les chaînes validées. Tous partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs).

| Type               | Stocke                                                                             |
| ------------------ | ---------------------------------------------------------------------------------- |
| `single-line-text` | Texte court sur une seule ligne (noms, titres, libellés).                          |
| `long-text`        | Texte brut multiligne (descriptions, notes, commentaires).                         |
| `rich-text`        | HTML formaté rendu avec un éditeur WYSIWYG.                                        |
| `email`            | Adresse e-mail validée selon la RFC 5322.                                          |
| `url`              | Adresse web validée comme URL absolue.                                             |
| `phone-number`     | Numéro de téléphone stocké comme texte ; préserve la mise en forme internationale. |

## `single-line-text`

Texte court limité à une seule ligne. Stocké tel quel sans mise en forme.

| Propriété | Description                                               |
| --------- | --------------------------------------------------------- |
| `default` | Chaîne par défaut attribuée aux nouveaux enregistrements. |

```yaml
- { id: 1, name: title, type: single-line-text, required: true, indexed: true, default: Untitled }
```

## `long-text`

Texte brut multiligne. Prend en charge les sauts de ligne ; aucune mise en forme enrichie (pas de gras/italique).

| Propriété | Description                                               |
| --------- | --------------------------------------------------------- |
| `default` | Chaîne par défaut attribuée aux nouveaux enregistrements. |

```yaml
- { id: 2, name: description, type: long-text, default: 'Enter description here...' }
```

## `rich-text`

Texte formaté avec gras, italique, liens, listes, titres et plus encore. Rendu avec un éditeur WYSIWYG Tiptap et stocké en HTML.

| Propriété        | Description                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxLength`      | Longueur maximale en caractères (entier ≥ 1). Valide à la saisie.                                                                                                                         |
| `fullTextSearch` | Booléen. Active l'indexation pour la recherche plein texte sur ce champ.                                                                                                                  |
| `toolbar`        | Tableau des actions de barre d'outils autorisées (par ex. `bold`, `italic`, `link`, `heading`, `list`, `image`, `code-block`, `table`). Lorsqu'omis, toutes les actions sont disponibles. |
| `placeholder`    | Texte indicatif affiché lorsque l'éditeur est vide.                                                                                                                                       |
| `collaborative`  | Booléen. Active l'édition collaborative en temps réel (Yjs).                                                                                                                              |

```yaml
- id: 3
  name: article_content
  type: rich-text
  required: true
  maxLength: 10000
  toolbar: [bold, italic, link, heading, list]
  placeholder: 'Write your article...'
```

## `email`

Champ texte qui valide les adresses e-mail (RFC 5322). Souvent défini avec `unique: true` et `indexed: true` pour l'authentification et les recherches.

| Propriété | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `default` | Adresse e-mail par défaut attribuée aux nouveaux enregistrements. |

```yaml
- { id: 4, name: email, type: email, required: true, unique: true, indexed: true }
```

## `url`

Champ texte qui valide les adresses web. Prend en charge plusieurs protocoles (`http://`, `https://`, `ftp://`, …).

| Propriété | Description                                            |
| --------- | ------------------------------------------------------ |
| `default` | URL par défaut attribuée aux nouveaux enregistrements. |

```yaml
- { id: 5, name: website, type: url, indexed: true, default: 'https://example.com' }
```

## `phone-number`

Champ texte pour les numéros de téléphone. Les numéros sont stockés exactement tels que saisis (espaces, tirets, parenthèses conservés) ; aucune mise en forme automatique n'est appliquée, ce qui autorise tout format international.

| Propriété | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `default` | Numéro de téléphone par défaut attribué aux nouveaux enregistrements. |

```yaml
- { id: 6, name: mobile_phone, type: phone-number, unique: true, default: '+1 (555) 000-0000' }
```

:::callout
**Recherche plein texte et pertinence.** Définissez `indexed: true` ainsi que `searchWeight` (`A`–`D`) sur les champs texte dont la source de données utilise la recherche plein texte, afin de contrôler le classement par pertinence. `rich-text` expose également `fullTextSearch` pour intégrer cette colonne dans l'index de recherche.
:::

# Champs numériques

Six types de champs stockent des nombres, des devises, des pourcentages, des notes et des indicateurs de progression. Tous partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs).

| Type         | Stocke                                                   |
| ------------ | -------------------------------------------------------- |
| `integer`    | Nombres entiers avec une plage min/max optionnelle.      |
| `decimal`    | Décimaux à précision fixe (1–10 décimales).              |
| `currency`   | Valeurs monétaires avec code ISO 4217 et mise en forme.  |
| `percentage` | Valeurs en pourcentage, affichées avec `%`.              |
| `rating`     | Note en étoiles/icônes avec un maximum configurable.     |
| `progress`   | Une barre de progression 0–100 avec couleur optionnelle. |

## `integer`

Nombres entiers sans décimales. Optimisé pour la performance.

| Propriété | Description                                          |
| --------- | ---------------------------------------------------- |
| `min`     | Valeur minimale autorisée (incluse).                 |
| `max`     | Valeur maximale autorisée (incluse).                 |
| `default` | Entier par défaut pour les nouveaux enregistrements. |

```yaml
- { id: 1, name: quantity, type: integer, required: true, min: 0, max: 1000, default: 1 }
```

## `decimal`

Nombres avec décimales, stockés avec une précision `DECIMAL` exacte.

| Propriété   | Description                                           |
| ----------- | ----------------------------------------------------- |
| `precision` | Nombre de décimales. Entier de **1 à 10**.            |
| `min`       | Valeur minimale autorisée (incluse).                  |
| `max`       | Valeur maximale autorisée (incluse).                  |
| `default`   | Décimal par défaut pour les nouveaux enregistrements. |

```yaml
- { id: 2, name: weight, type: decimal, precision: 2, min: 0.01, max: 999.99, default: 1.0 }
```

## `currency`

Valeurs monétaires avec une mise en forme d'affichage adaptée à la locale.

| Propriété            | Description                                                                           |
| -------------------- | ------------------------------------------------------------------------------------- |
| `currency`           | **Requis.** Code ISO 4217 à trois lettres (par ex. `USD`, `EUR`, `GBP`, `JPY`).       |
| `precision`          | Nombre de décimales. Entier de **0 à 10** (par défaut 2 pour la plupart des devises). |
| `min`                | Valeur minimale autorisée (incluse).                                                  |
| `max`                | Valeur maximale autorisée (incluse).                                                  |
| `symbolPosition`     | Placement du symbole monétaire : `before` ($100) ou `after` (100€).                   |
| `negativeFormat`     | Affichage des valeurs négatives : `minus` (-100) ou `parentheses` ((100)).            |
| `thousandsSeparator` | Caractère de groupement des milliers : `comma`, `period`, `space` ou `none`.          |

```yaml
- id: 3
  name: price
  type: currency
  required: true
  currency: USD
  precision: 2
  symbolPosition: before
  negativeFormat: parentheses
  thousandsSeparator: comma
```

:::callout
**Corrigé par rapport aux docs antérieures.** `currency` utilise `thousandsSeparator` — une énumération (`comma | period | space | none`), et **non** un booléen. `negativeFormat` accepte `minus` ou `parentheses` (il n'y a pas d'option `red`), et `precision` varie de **0 à 10**.
:::

## `percentage`

Valeurs en pourcentage (typiquement 0–100), affichées avec un symbole `%`.

| Propriété   | Description                                               |
| ----------- | --------------------------------------------------------- |
| `precision` | Nombre de décimales. Entier de **0 à 10** (par défaut 0). |
| `min`       | Valeur minimale autorisée (incluse, typiquement 0).       |
| `max`       | Valeur maximale autorisée (incluse, typiquement 100).     |
| `default`   | Pourcentage par défaut pour les nouveaux enregistrements. |

```yaml
- { id: 4, name: discount_rate, type: percentage, precision: 1, min: 0, max: 100, default: 10.0 }
```

## `rating`

Une valeur de note rendue sous forme d'étoiles ou d'autres indicateurs.

| Propriété | Description                                                   |
| --------- | ------------------------------------------------------------- |
| `max`     | Valeur de note maximale. Entier de **1 à 10** (par défaut 5). |
| `style`   | Style visuel de la note (par ex. `stars`).                    |
| `default` | Valeur de note par défaut pour les nouveaux enregistrements.  |

```yaml
- { id: 5, name: product_rating, type: rating, max: 5, style: stars }
```

:::callout
**Corrigé par rapport aux docs antérieures.** Le champ rating utilise `max` et `style` — et **non** `ratingMax` / `ratingStyle`.
:::

## `progress`

Affiche une valeur 0–100 sous forme de barre de progression. Utilisé pour suivre l'avancement vers un objectif.

| Propriété | Description                                                                           |
| --------- | ------------------------------------------------------------------------------------- |
| `color`   | Couleur de la barre de progression en hexadécimal sur 6 chiffres (par ex. `#10B981`). |
| `default` | Valeur de progression par défaut (0–100) pour les nouveaux enregistrements.           |

```yaml
- { id: 6, name: task_completion, type: progress, color: '#10B981', default: 0 }
```

:::callout
**Corrigé par rapport aux docs antérieures.** Le champ progress utilise `color` (une chaîne hexadécimale) — et **non** `progressColor`.
:::

# Champs date et heure

Sept types de champs stockent des dates, des heures, des durées et des horodatages d'audit gérés par le système. Tous partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs).

| Type         | Stocke                                                                          |
| ------------ | ------------------------------------------------------------------------------- |
| `date`       | Une date calendaire, avec composante heure optionnelle.                         |
| `datetime`   | Une date et une heure, sensible au fuseau horaire.                              |
| `time`       | Une heure de la journée sans date.                                              |
| `duration`   | Une valeur de temps écoulé / d'heures travaillées (stockée en secondes).        |
| `created-at` | Horodatage défini par le système, capturé à la création d'un enregistrement.    |
| `updated-at` | Horodatage mis à jour par le système, rafraîchi à chaque modification.          |
| `deleted-at` | Horodatage de suppression douce ; NULL signifie que l'enregistrement est actif. |

## `date`

Dates calendaires, incluant éventuellement une composante heure.

| Propriété     | Description                                                                                |
| ------------- | ------------------------------------------------------------------------------------------ |
| `format`      | Chaîne de format d'affichage libre (par ex. `YYYY-MM-DD`, `MM/DD/YYYY`, `DD-MM-YYYY`).     |
| `dateFormat`  | Préréglage d'affichage : `US`, `European` ou `ISO`.                                        |
| `timeFormat`  | Affichage de l'heure : `12-hour` ou `24-hour`.                                             |
| `includeTime` | Booléen. Lorsqu'il vaut `true`, le champ date capture aussi une heure.                     |
| `timezone`    | Identifiant de fuseau horaire IANA (par ex. `UTC`, `America/New_York`, `Europe/London`).   |
| `timeZone`    | Réglage de fuseau horaire acceptant une zone spécifique ou `local` (fuseau du navigateur). |
| `default`     | Valeur de date par défaut pour les nouveaux enregistrements.                               |

```yaml
- { id: 1, name: due_date, type: date, dateFormat: ISO, includeTime: false }
```

## `datetime`

Date et heure. Sensible au fuseau horaire pour une planification inter-régions précise.

| Propriété    | Description                                                                            |
| ------------ | -------------------------------------------------------------------------------------- |
| `format`     | Chaîne de format d'affichage libre (par ex. `YYYY-MM-DD HH:mm`, `MM/DD/YYYY hh:mm A`). |
| `dateFormat` | Préréglage d'affichage : `US`, `European` ou `ISO`.                                    |
| `timeFormat` | Affichage de l'heure : `12-hour` ou `24-hour`.                                         |
| `timezone`   | Identifiant de fuseau horaire IANA.                                                    |
| `timeZone`   | Réglage de fuseau horaire acceptant une zone spécifique ou `local`.                    |
| `default`    | Valeur datetime par défaut pour les nouveaux enregistrements.                          |

```yaml
- { id: 2, name: published_at, type: datetime, timeFormat: 24-hour, timezone: UTC }
```

## `time`

Valeurs d'heure uniquement, sans date. Utilisé pour les horaires, les heures d'ouverture et les créneaux horaires.

| Propriété    | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `timeFormat` | Affichage de l'heure : `12-hour` ou `24-hour`.              |
| `default`    | Heure par défaut au format `HH:MM:SS` (par ex. `09:00:00`). |

```yaml
- { id: 3, name: start_time, type: time, required: true, timeFormat: 24-hour }
```

## `duration`

Temps écoulé ou heures travaillées, stockés sous forme d'un nombre de secondes.

| Propriété       | Description                                                                     |
| --------------- | ------------------------------------------------------------------------------- |
| `format`        | Chaîne de format d'affichage libre pour la durée.                               |
| `displayFormat` | Préréglage d'affichage : `h:mm`, `h:mm:ss` ou `decimal`.                        |
| `default`       | Valeur de durée par défaut, en **secondes**, pour les nouveaux enregistrements. |

```yaml
- { id: 4, name: work_hours, type: duration, displayFormat: 'h:mm' }
```

## Horodatages d'audit système

`created-at`, `updated-at` et `deleted-at` sont **gérés par le système** — leurs valeurs sont définies automatiquement et ne peuvent pas être éditées manuellement. Ils ne prennent aucune propriété spécifique au type au-delà des propriétés de base des champs (souvent `indexed: true`).

| Type         | Comportement                                                                                                                |
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `created-at` | Capturé une fois lors de la création de l'enregistrement. En lecture seule.                                                 |
| `updated-at` | Rafraîchi automatiquement à chaque modification de l'enregistrement. En lecture seule.                                      |
| `deleted-at` | Défini lors de la suppression douce de l'enregistrement. `NULL` indique un enregistrement actif ; un horodatage = supprimé. |

```yaml
fields:
  - { id: 5, name: created_at, type: created-at, indexed: true }
  - { id: 6, name: updated_at, type: updated-at, indexed: true }
  - { id: 7, name: deleted_at, type: deleted-at, indexed: true }
```

:::callout
**Cycle de vie de la suppression douce.** Ajouter un champ `deleted-at` active le comportement de suppression douce par défaut de Sovrium : supprimer un enregistrement définit l'horodatage au lieu de retirer la ligne, et `/restore` l'efface. Associez-le à [`deleted-by`](/fr/user-audit-fields) pour enregistrer qui a effectué la suppression.
:::

# Champs de sélection

Quatre types de champs permettent aux enregistrements de choisir parmi des options prédéfinies. Tous partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs).

| Type            | Stocke                                                                          |
| --------------- | ------------------------------------------------------------------------------- |
| `checkbox`      | Une valeur booléenne vrai/faux.                                                 |
| `single-select` | Une option choisie dans une liste prédéfinie.                                   |
| `multi-select`  | Plusieurs options choisies dans une liste prédéfinie.                           |
| `status`        | Un état de workflow coloré, choisi dans une liste d'options `{ value, color }`. |

## `checkbox`

Champ booléen, généralement rendu sous forme de case à cocher.

| Propriété | Description                                     |
| --------- | ----------------------------------------------- |
| `default` | Valeur booléenne par défaut (`true` / `false`). |

```yaml
- { id: 1, name: is_active, type: checkbox, required: true, default: false }
```

## `single-select`

Un choix unique dans une liste d'options de type chaîne.

| Propriété    | Description                                                                                                                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options`    | Tableau de chaînes définissant les choix disponibles.                                                                                                                                                                |
| `default`    | Option sélectionnée par défaut (une chaîne).                                                                                                                                                                         |
| `conditions` | Conditions comportementales optionnelles : `[{ when: <option>, then: { …changements de propriétés } }]` — applique des changements de propriétés (par ex. `readOnly`) lorsqu'une option spécifique est sélectionnée. |

```yaml
- id: 2
  name: category
  type: single-select
  options: [Electronics, Clothing, Food]
  default: Electronics
```

## `multi-select`

Plusieurs choix dans une liste d'options de type chaîne.

| Propriété       | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| `options`       | Tableau de chaînes définissant les choix disponibles.                     |
| `maxSelections` | Nombre maximal de choix (entier ≥ 1 ; ne peut dépasser `options.length`). |
| `default`       | Sélections par défaut (un tableau de chaînes).                            |

```yaml
- id: 3
  name: tags
  type: multi-select
  options: [Urgent, Important, Review]
  maxSelections: 3
```

## `status`

Un état de workflow coloré. Chaque option est un objet avec un `value` et un `color`, idéal pour les colonnes Kanban et les étapes de pipeline.

| Propriété | Description                                                                          |
| --------- | ------------------------------------------------------------------------------------ |
| `options` | Tableau d'objets `{ value, color }` définissant les états colorés.                   |
| `default` | Valeur de statut par défaut (une chaîne correspondant à l'une des valeurs d'option). |

```yaml
- id: 4
  name: status
  type: status
  options:
    - { value: todo, color: '#94A3B8' }
    - { value: in_progress, color: '#3B82F6' }
    - { value: done, color: '#10B981' }
  default: todo
```

:::callout
**Single-select vs status.** Utilisez `single-select` pour de simples valeurs énumérées (`options` de type chaîne). Utilisez `status` lorsque chaque état nécessite une couleur pour des affichages de workflow visuels tels que les tableaux Kanban.
:::

# Champs relationnels

Trois types de champs connectent les tables et dérivent des données à partir de ces connexions. Ils forment une chaîne : une `relationship` définit le lien, puis `lookup` et `rollup` lisent ou agrègent les données à travers lui. (Le champ apparenté [`count`](/fr/advanced-fields#count) — classé dans la catégorie Avancé — traverse également une relation.)

| Type           | Objectif                                                                       |
| -------------- | ------------------------------------------------------------------------------ |
| `relationship` | Crée un lien par clé étrangère vers une autre table. Fondation du reste.       |
| `lookup`       | Lit une valeur de champ unique depuis un enregistrement lié. En lecture seule. |
| `rollup`       | Agrège un champ sur de nombreux enregistrements liés (somme, moyenne, …).      |

## `relationship`

Crée un lien par clé étrangère vers une autre table.

| Propriété         | Description                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `relatedTable`    | **Requis.** Nom de la table cible à relier. Doit correspondre à une table existante.                                   |
| `relationType`    | Cardinalité. Par défaut `many-to-one`. Valeurs courantes : `one-to-one`, `many-to-one`, `one-to-many`, `many-to-many`. |
| `foreignKey`      | Nom personnalisé de la colonne de clé étrangère (utilisé pour `one-to-many`). Généré automatiquement lorsqu'omis.      |
| `displayField`    | Champ de la table liée affiché dans l'interface (par ex. `name` au lieu de l'identifiant brut).                        |
| `onDelete`        | Action référentielle lorsque la ligne liée est supprimée (par ex. `cascade`, `set-null`, `restrict`, `no-action`).     |
| `onUpdate`        | Action référentielle lorsque la clé primaire liée est mise à jour.                                                     |
| `reciprocalField` | Nom du champ pour le lien inverse (bidirectionnel) sur la table liée.                                                  |
| `allowMultiple`   | Booléen. Autorise la liaison à plusieurs enregistrements (par défaut `true` pour `many-to-many`).                      |
| `limitToView`     | Restreint les enregistrements liés sélectionnables à ceux visibles dans une vue nommée de la table liée.               |

```yaml
- id: 1
  name: customer
  type: relationship
  relatedTable: Customers
  relationType: many-to-one
  displayField: full_name
  onDelete: set-null
  reciprocalField: orders
```

## `lookup`

Affiche une valeur de champ tirée d'un enregistrement lié via une relation existante. En lecture seule et mis à jour automatiquement.

| Propriété           | Description                                                                            |
| ------------------- | -------------------------------------------------------------------------------------- |
| `relationshipField` | **Requis.** Nom du champ de relation à traverser (doit exister dans la même table).    |
| `relatedField`      | **Requis.** Champ de la table liée dont la valeur doit être affichée.                  |
| `filters`           | Expression de filtre optionnelle restreignant les enregistrements liés pris en compte. |

```yaml
- id: 2
  name: customer_email
  type: lookup
  relationshipField: customer
  relatedField: email
```

## `rollup`

Agrège des valeurs provenant de nombreux enregistrements liés.

| Propriété           | Description                                                                         |
| ------------------- | ----------------------------------------------------------------------------------- |
| `relationshipField` | **Requis.** Nom du champ de relation reliant à la table liée.                       |
| `relatedField`      | **Requis.** Champ de la table liée à agréger.                                       |
| `aggregation`       | **Requis.** Fonction d'agrégation (par ex. `SUM`, `AVG`, `MIN`, `MAX`, `COUNT`).    |
| `format`            | Format d'affichage du résultat agrégé (par ex. `currency`, `number`, `percentage`). |
| `filters`           | Filtre optionnel appliqué avant l'agrégation.                                       |

```yaml
- id: 3
  name: total_sales
  type: rollup
  relationshipField: orders
  relatedField: amount
  aggregation: SUM
  format: currency
```

:::callout
**La chaîne relationnelle.** Commencez par une `relationship` pour créer le lien, puis dérivez des données sans duplication : `orders → customer (relationship) → customer_email (lookup)`, ou agrégez avec `rollup`/`count`. Les champs `count`, `lookup` et `rollup` sont validés au moment de la configuration pour garantir que leur `relationshipField` référence un véritable champ `relationship` dans la même table.
:::

Voir [Relations](/fr/table-relationships) pour un examen plus approfondi des cardinalités, des actions référentielles, des liens réciproques et de `displayField`.

# Champs utilisateur et audit

Quatre types de champs référencent des utilisateurs issus du système d'authentification. Trois sont des champs d'audit auto-renseignés qui suivent qui a créé, mis à jour ou supprimé un enregistrement ; l'un est une référence utilisateur éditable. Tous nécessitent que `auth` soit configuré et partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs).

| Type         | Comportement                                                                                        |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `user`       | Référence éditable vers un utilisateur. Sélection unique ou multiple.                               |
| `created-by` | Défini automatiquement sur l'utilisateur ayant créé l'enregistrement. En lecture seule.             |
| `updated-by` | Défini automatiquement sur le dernier utilisateur ayant modifié l'enregistrement. En lecture seule. |
| `deleted-by` | Défini automatiquement sur l'utilisateur ayant effectué la suppression douce. NULL lorsque actif.   |

## `user`

Une référence éditable vers un ou plusieurs utilisateurs (par ex. un assigné).

| Propriété       | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| `allowMultiple` | Booléen. Lorsqu'il vaut `true`, autorise la sélection de plusieurs utilisateurs. |

```yaml
- { id: 1, name: assigned_to, type: user, required: true, allowMultiple: false }
```

## Champs d'audit système

`created-by`, `updated-by` et `deleted-by` sont **gérés par le système** — leurs valeurs sont définies automatiquement et ne peuvent pas être éditées manuellement. Ils stockent une référence à un identifiant d'utilisateur et ne prennent aucune propriété spécifique au type au-delà des propriétés de base des champs (souvent `indexed: true`).

| Type         | Comportement                                                                                                                                                   |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created-by` | Capture l'utilisateur ayant créé l'enregistrement. En lecture seule.                                                                                           |
| `updated-by` | Capture le dernier utilisateur ayant modifié l'enregistrement. En lecture seule.                                                                               |
| `deleted-by` | Capture l'utilisateur ayant effectué la suppression douce de l'enregistrement. `NULL` lorsque l'enregistrement est actif ou supprimé par un processus système. |

```yaml
fields:
  - { id: 2, name: created_by, type: created-by, indexed: true }
  - { id: 3, name: updated_by, type: updated-by, indexed: true }
  - { id: 4, name: deleted_by, type: deleted-by, indexed: true }
```

:::callout
**Authentification requise.** Tous les champs utilisateur et audit résolvent les références d'identifiant d'utilisateur via le système d'authentification, donc `auth` doit être configuré. Associez `deleted-by` à l'horodatage [`deleted-at`](/fr/datetime-fields) pour une piste d'audit complète de la suppression douce (qui a supprimé, et quand).
:::

# Champs pièce jointe

La catégorie média couvre les téléversements de fichiers et le champ barcode. `single-attachment` et `multiple-attachments` téléversent des fichiers dans un bucket de stockage ; `barcode` stocke une valeur scannable (documentée en détail sur la page [Champs avancés](/fr/advanced-fields#barcode)). Tous partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs).

| Type                   | Stocke                                                                          |
| ---------------------- | ------------------------------------------------------------------------------- |
| `single-attachment`    | Un seul fichier téléversé.                                                      |
| `multiple-attachments` | Plusieurs fichiers téléversés.                                                  |
| `barcode`              | Une valeur de code-barres — voir [Champs avancés](/fr/advanced-fields#barcode). |

## `single-attachment`

Un seul fichier téléversé (avatar, document, image).

| Propriété           | Description                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `bucket`            | Nom du bucket de stockage. Référence un bucket dans `app.buckets`. Utilise le bucket `default` implicite lorsqu'omis.  |
| `allowedFileTypes`  | Tableau des types MIME autorisés (par ex. `["image/png", "image/jpeg"]`). Tous les types autorisés lorsqu'il est vide. |
| `maxFileSize`       | Taille maximale du fichier en **octets** (entier ≥ 1). Exemple : `5242880` pour 5 Mo.                                  |
| `generateThumbnail` | Booléen. Générer des miniatures d'image lors du téléversement.                                                         |
| `storeMetadata`     | Booléen. Stocker les métadonnées (dimensions de l'image, durée de la vidéo).                                           |

```yaml
- id: 1
  name: avatar
  type: single-attachment
  bucket: avatars
  allowedFileTypes: [image/png, image/jpeg, image/gif]
  maxFileSize: 5242880
  generateThumbnail: true
  storeMetadata: true
```

## `multiple-attachments`

Plusieurs fichiers téléversés (une galerie, un ensemble de documents).

| Propriété            | Description                                                                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bucket`             | Nom du bucket de stockage. Référence un bucket dans `app.buckets`. Utilise `default` lorsqu'omis.                                                    |
| `maxFiles`           | Nombre maximal de fichiers autorisés (entier ≥ 1).                                                                                                   |
| `allowedFileTypes`   | Tableau des types MIME autorisés (par ex. `["application/pdf", "application/msword"]`).                                                              |
| `maxFileSize`        | Taille maximale en **octets** par pièce jointe (entier ≥ 1). Exemple : `10485760` pour 10 Mo.                                                        |
| `generateThumbnails` | Booléen. Générer des miniatures d'image lors du téléversement. _(Notez le pluriel — le singulier `generateThumbnail` concerne `single-attachment`.)_ |
| `storeMetadata`      | Booléen. Stocker les métadonnées pour chaque pièce jointe.                                                                                           |

```yaml
- id: 2
  name: documents
  type: multiple-attachments
  bucket: documents
  maxFiles: 10
  allowedFileTypes: [application/pdf, application/msword]
  maxFileSize: 10485760
  generateThumbnails: true
```

:::callout
**Des buckets, pas du stockage en ligne.** Les champs pièce jointe écrivent dans des buckets nommés définis dans `app.buckets` (local ou S3). La propriété `bucket` sélectionne lequel ; l'omettre utilise le bucket `default` implicite. `maxFileSize` est toujours spécifié en **octets**. Voir la documentation des buckets pour la configuration des buckets.
:::

Le champ `barcode` est le troisième membre de la catégorie média mais est documenté aux côtés des autres champs de valeur spécialisés — voir [Champs avancés → barcode](/fr/advanced-fields#barcode).

# Champs avancés

Neuf types de champs spécialisés couvrent les valeurs calculées, les identifiants générés, les contrôles interactifs et les données structurées. Cette page documente également `barcode` (un champ de la catégorie média). Tous partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs).

| Type          | Stocke / fait                                                    |
| ------------- | ---------------------------------------------------------------- |
| `formula`     | Une valeur calculée à partir d'une expression de formule.        |
| `count`       | Un comptage d'enregistrements liés.                              |
| `autonumber`  | Un nombre auto-incrémenté avec préfixe et remplissage par zéros. |
| `button`      | Un bouton interactif déclenchant une URL ou une automatisation.  |
| `json`        | Données JSON structurées.                                        |
| `array`       | Un tableau de valeurs typées.                                    |
| `color`       | Une valeur de couleur hexadécimale.                              |
| `code`        | Code source avec coloration syntaxique.                          |
| `geolocation` | Coordonnées latitude/longitude.                                  |
| `barcode`     | Une valeur de code-barres (catégorie média — voir ci-dessous).   |

## `formula`

Calcule une valeur à partir d'une expression de formule référençant d'autres champs.

| Propriété    | Description                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| `formula`    | **Requis.** Expression à calculer. Prend en charge les références de champs, les opérateurs et les fonctions. |
| `resultType` | Type de données attendu du résultat (par ex. `string`, `number`, `boolean`, `date`).                          |
| `format`     | Format d'affichage du résultat (par ex. `currency`, `percentage`, `decimal`, `date`).                         |

```yaml
- { id: 1, name: total_price, type: formula, formula: 'price * quantity', resultType: number }
```

## `count`

Compte le nombre d'enregistrements liés via un champ de relation dans la même table. Un `rollup` simplifié.

| Propriété           | Description                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `relationshipField` | **Requis.** Nom du champ de relation dont les enregistrements liés doivent être comptés.  |
| `filters`           | Expression de filtre optionnelle — ne compte que les enregistrements liés correspondants. |

```yaml
- {
    id: 2,
    name: completed_task_count,
    type: count,
    relationshipField: tasks,
    filters: { field: status, operator: equals, value: completed },
  }
```

## `autonumber`

Un nombre auto-incrémenté avec un préfixe optionnel et un remplissage par zéros.

| Propriété   | Description                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| `prefix`    | Texte optionnel ajouté avant le nombre (par ex. `INV-`, `ORD-`).             |
| `startFrom` | Nombre de départ (entier ≥ 1).                                               |
| `digits`    | Nombre minimal de chiffres avec remplissage par zéros. Entier de **1 à 10**. |

```yaml
- { id: 3, name: invoice_number, type: autonumber, prefix: 'INV-', startFrom: 1000, digits: 5 }
```

## `button`

Un bouton interactif rendu sur les enregistrements qui déclenche une action.

| Propriété    | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `label`      | **Requis.** Texte du bouton.                                             |
| `action`     | **Requis.** Type d'action à déclencher (par ex. `url`, `automation`).    |
| `url`        | URL à ouvrir (lorsque `action` vaut `url`).                              |
| `automation` | Nom de l'automatisation à exécuter (lorsque `action` vaut `automation`). |

```yaml
- {
    id: 4,
    name: approve,
    type: button,
    label: Approve,
    action: automation,
    automation: approve_request,
  }
```

:::callout
**Corrigé par rapport aux docs antérieures.** Le champ button utilise `label`, `action`, `url` et `automation` — et **non** `buttonLabel` / `buttonAction` / `buttonUrl`.
:::

## `json`

Stocke des données JSON structurées avec une validation de schéma optionnelle.

| Propriété | Description                                          |
| --------- | ---------------------------------------------------- |
| `schema`  | Objet JSON Schema optionnel pour valider le contenu. |

```yaml
- { id: 5, name: metadata, type: json, required: false }
```

## `array`

Stocke un tableau de valeurs avec des contraintes de type et de longueur optionnelles.

| Propriété  | Description                                                 |
| ---------- | ----------------------------------------------------------- |
| `itemType` | Type de données des éléments du tableau (par ex. `string`). |
| `maxItems` | Nombre maximal d'éléments (entier ≥ 1).                     |

```yaml
- { id: 6, name: tags, type: array, itemType: string, maxItems: 10 }
```

## `color`

Stocke une valeur de couleur au format hexadécimal. Rendu avec un sélecteur de couleur.

| Propriété | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `default` | Couleur par défaut en hexadécimal sur 6 chiffres (par ex. `#3B82F6`). |

```yaml
- { id: 7, name: brand_color, type: color, required: true, default: '#3B82F6' }
```

## `code`

Stocke du code source en texte brut avec coloration syntaxique (CodeMirror 6).

| Propriété     | Description                                                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `language`    | **Requis.** Langage pour la coloration (par ex. `javascript`, `typescript`, `yaml`, `json`, `python`, `sql`, `html`, `css`, `markdown`). |
| `lineNumbers` | Booléen. Afficher les numéros de ligne.                                                                                                  |
| `readOnly`    | Booléen. Rendre l'éditeur en lecture seule.                                                                                              |
| `minLines`    | Nombre minimal de lignes visibles (entier ≥ 1).                                                                                          |
| `maxLines`    | Nombre maximal de lignes visibles avant défilement (entier ≥ 1).                                                                         |
| `tabSize`     | Taille de tabulation en espaces. Entier de **1 à 8** (par défaut 2).                                                                     |

```yaml
- { id: 8, name: snippet, type: code, language: typescript, lineNumbers: true, tabSize: 2 }
```

## `geolocation`

Stocke des coordonnées géographiques (latitude et longitude) pour les fonctionnalités basées sur la localisation. Ne prend aucune propriété spécifique au type au-delà des propriétés de base des champs.

```yaml
- { id: 9, name: office_location, type: geolocation, required: true }
```

## `barcode`

Stocke une valeur de code-barres pour l'identification de produit et l'inventaire. (Classé dans la catégorie média, documenté ici avec les autres champs de valeur spécialisés.)

| Propriété | Description                                          |
| --------- | ---------------------------------------------------- |
| `format`  | Format de code-barres (par ex. `EAN-13`, `CODE128`). |

```yaml
- { id: 10, name: product_barcode, type: barcode, required: true, format: EAN-13 }
```

:::callout
**Les champs calculés se mettent à jour automatiquement.** `formula`, `count` et `rollup` (voir [Champs relationnels](/fr/relational-fields)) sont dérivés — ils se recalculent lorsque leurs entrées changent et ne sont pas directement éditables.
:::

# Champs IA

Sept types de champs calculent leur valeur avec un LLM à partir d'un ou plusieurs `sourceFields`. Tous partagent les [propriétés de base des champs](/fr/tables-overview#proprietes-de-base-des-champs) et un ensemble commun de contrôles IA.

| Type            | Produit                                                      |
| --------------- | ------------------------------------------------------------ |
| `ai-generate`   | Texte généré en forme libre à partir d'un modèle d'invite.   |
| `ai-summary`    | Un résumé des champs sources.                                |
| `ai-categorize` | Une catégorie unique choisie dans une liste prédéfinie.      |
| `ai-extract`    | Données structurées conformes à un JSON Schema.              |
| `ai-sentiment`  | Analyse de sentiment du texte source.                        |
| `ai-tag`        | Plusieurs étiquettes choisies dans une liste d'autorisation. |
| `ai-translate`  | Une traduction d'un champ source vers une langue cible.      |

## Propriétés IA communes

La plupart des champs IA acceptent ces propriétés partagées (en plus de leurs propriétés spécifiques au type) :

| Propriété      | Description                                                                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceFields` | **Requis.** Noms des champs utilisés comme contexte d'entrée. Au moins un (exactement un pour `ai-translate`).                                                  |
| `prompt`       | Invite personnalisée pour guider l'IA. `ai-generate` utilise un modèle `{{fieldName}}` ; les autres se rabattent sur une valeur par défaut sensée lorsqu'omise. |
| `systemPrompt` | Invite système définissant la persona et le contexte de l'IA.                                                                                                   |
| `model`        | Remplacement du modèle IA (par ex. `gpt-4o`, `claude-sonnet`). Chaîne non vide.                                                                                 |
| `temperature`  | Créativité de la sortie, de `0` à `1`.                                                                                                                          |

## `ai-generate`

Génère du texte en forme libre à partir d'un modèle d'invite.

| Propriété | Description                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `prompt`  | Modèle d'invite avec substitution de variables `{{fieldName}}`. _(Recommandé pour les champs generate.)_ |

```yaml
- id: 1
  name: marketing_copy
  type: ai-generate
  sourceFields: [product_name, features]
  prompt: 'Write a compelling 2-paragraph marketing description for {{product_name}}. Key features: {{features}}.'
```

## `ai-summary`

Résume les champs sources. Utilise une invite « Summarize the following » par défaut lorsque `prompt` est omis.

```yaml
- { id: 2, name: ticket_summary, type: ai-summary, sourceFields: [body, thread] }
```

## `ai-categorize`

Classe la source dans exactement l'une d'une liste fixe de catégories.

| Propriété    | Description                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------ |
| `categories` | **Requis.** Catégories prédéfinies parmi lesquelles l'IA doit choisir. Minimum 2, sans doublons. |

```yaml
- {
    id: 3,
    name: ticket_category,
    type: ai-categorize,
    sourceFields: [subject, body],
    categories: [billing, technical, account, general],
  }
```

## `ai-extract`

Extrait des données structurées décrites par un JSON Schema. Prend en charge les objets et tableaux imbriqués.

| Propriété | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `schema`  | **Requis.** Objet JSON Schema décrivant la structure des données extraites. |

```yaml
- id: 4
  name: invoice_data
  type: ai-extract
  sourceFields: [raw_text]
  schema:
    type: object
    properties:
      vendor_name: { type: string, description: Name of the vendor }
      total_amount: { type: number, description: Total amount due }
```

## `ai-sentiment`

Analyse le sentiment du texte source. `prompt` peut ajuster la focalisation (par ex. urgence, satisfaction).

```yaml
- { id: 5, name: review_sentiment, type: ai-sentiment, sourceFields: [review_text] }
```

## `ai-tag`

Attribue plusieurs étiquettes à partir d'une liste d'autorisation prédéfinie.

| Propriété | Description                                                                          |
| --------- | ------------------------------------------------------------------------------------ |
| `tags`    | **Requis.** Étiquettes autorisées que l'IA peut attribuer. Minimum 2, sans doublons. |
| `maxTags` | Nombre maximal d'étiquettes à attribuer (entier positif). Aucune limite lorsqu'omis. |

```yaml
- {
    id: 6,
    name: article_tags,
    type: ai-tag,
    sourceFields: [title, body],
    tags: [technology, business, science, health, politics],
    maxTags: 3,
  }
```

## `ai-translate`

Traduit un champ source vers une langue cible.

| Propriété        | Description                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `sourceFields`   | **Requis.** Exactement **un** nom de champ.                                                                      |
| `targetLanguage` | **Requis.** Code de langue ISO 639-1, éventuellement suffixé par une région (par ex. `fr`, `es`, `ja`, `zh-CN`). |
| `prompt`         | Invite personnalisée pour contrôler le ton, le registre et le style de la traduction.                            |

```yaml
- {
    id: 7,
    name: description_fr,
    type: ai-translate,
    sourceFields: [description],
    targetLanguage: fr,
  }
```

:::callout
**Routage des fournisseurs IA.** Les champs IA passent par le résolveur de précédence de fournisseurs de Sovrium (contrôlé par variables d'environnement, local-first par défaut). La propriété optionnelle `model` remplace le modèle par défaut pour ce champ. Le rôle de connexion conditionne toujours l'exécution partout où la table est exposée via le serveur MCP.
:::

# Permissions des tables

Sovrium contrôle l'accès aux enregistrements avec un **contrôle d'accès basé sur les rôles (RBAC)** au niveau de la table, des **permissions par champ** pour un contrôle granulaire des colonnes, et des **prédicats au niveau ligne** optionnels pour un cloisonnement par ligne. Un accès non autorisé renvoie **404** (jamais 403) afin d'empêcher l'énumération des enregistrements.

## Valeurs de permission

Chaque opération accepte l'un de trois formats :

| Valeur                | Signification                                            |
| --------------------- | -------------------------------------------------------- |
| `all`                 | Tout le monde, y compris les visiteurs non authentifiés. |
| `authenticated`       | Tout utilisateur connecté.                               |
| `['admin', 'editor']` | Uniquement les noms de rôles listés (un tableau).        |

Les trois rôles intégrés sont `admin`, `member` et `viewer` (du plus élevé au plus bas). Des noms de rôles personnalisés sont également acceptés dans la forme tableau.

## Permissions au niveau de la table

Définissez `permissions` sur une table pour conditionner chaque opération.

| Opération         | Contrôle qui peut…                                               |
| ----------------- | ---------------------------------------------------------------- |
| `read`            | Consulter les enregistrements.                                   |
| `comment`         | Ajouter des commentaires aux enregistrements.                    |
| `create`          | Créer de nouveaux enregistrements.                               |
| `update`          | Modifier les enregistrements existants.                          |
| `delete`          | Effectuer la suppression douce d'enregistrements.                |
| `restore`         | Restaurer les enregistrements supprimés en douceur.              |
| `permanentDelete` | Retirer définitivement les enregistrements supprimés en douceur. |
| `fields`          | Permissions de lecture/écriture par champ (voir ci-dessous).     |
| `inherit`         | Hériter de toutes les permissions d'une table parente nommée.    |

```yaml
permissions:
  read: all
  comment: authenticated
  create: [admin, editor]
  update: [admin, editor]
  delete: [admin]
  restore: [admin]
  permanentDelete: [admin]
```

## Permissions par champ

Restreignez l'accès en lecture/écriture à des colonnes spécifiques sous `permissions.fields`. Chaque entrée nomme un `field` et, optionnellement, ses audiences `read` et `write` (mêmes trois formats). Lorsqu'une permission de champ est omise, elle hérite du `read` au niveau de la table (pour la lecture) ou de `create`/`update` (pour l'écriture).

| Propriété | Description                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| `field`   | Nom du champ auquel cette permission s'applique.                             |
| `read`    | Qui peut lire (SELECT) ce champ. Hérite du `read` de la table si non défini. |
| `write`   | Qui peut écrire (INSERT/UPDATE) ce champ. Hérite si non défini.              |

```yaml
permissions:
  read: authenticated
  fields:
    - { field: salary, read: [admin, hr], write: [admin] }
    - { field: department, read: all, write: [admin] }
```

## Permissions au niveau ligne

Définissez `rowLevelPermissions` pour un cloisonnement en défense en profondeur. Chaque opération CRUD peut porter un prédicat `when` côté serveur qui est ajouté comme filtre à chaque requête retournant des enregistrements. La barrière de rôle s'exécute en premier ; le prédicat au niveau ligne filtre ensuite dans la portée du rôle autorisé.

Un prédicat est `{ field, operator, value }` :

| Champ      | Description                                                                                                            |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| `field`    | Le champ de la table, ou une chaîne de relation comme `project.client_id`, sur lequel filtrer.                         |
| `operator` | `eq`, `neq` ou `in` (appartenance à un tableau).                                                                       |
| `value`    | Un littéral (chaîne/nombre/booléen/tableau) **ou** une référence `$currentUser` résolue par requête depuis la session. |

```yaml
rowLevelPermissions:
  read:
    when:
      field: client_id
      operator: in
      value: { kind: currentUser, path: { kind: assignment, tableSlug: clients } }
  write:
    when:
      field: client_id
      operator: in
      value: { kind: currentUser, path: { kind: assignment, tableSlug: clients } }
```

:::callout
**404, pas 403 — anti-énumération.** Lorsqu'une requête échoue à l'autorisation (au niveau de la table, du champ ou de la ligne), Sovrium renvoie **404 Not Found** plutôt que 403 Forbidden. Cela empêche les attaquants de découvrir quels enregistrements ou tables existent en sondant les codes de statut.
:::

## Permissions Ressource:Action

Pour des contextes de permission plus larges (plugin admin, clés API), Sovrium prend également en charge une carte `resource: [actions]` où chaque ressource liste les actions autorisées et `*` signifie toutes les actions :

```yaml
users: [read, list]
posts: [create, read, update, delete]
analytics: ['*']
```

# Index et contraintes

Au-delà des champs, une table peut déclarer une clé primaire, des index pour les performances des requêtes et l'unicité, du sucre syntaxique pour les contraintes d'unicité, des contraintes CHECK pour les règles inter-champs et des clés étrangères composites.

## Clé primaire

Définissez `primaryKey` pour contrôler la façon dont chaque ligne est identifiée de manière unique. Lorsqu'elle est omise, une colonne `id` générée automatiquement est la clé primaire.

| Propriété | Description                                                                                                                               |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `type`    | Stratégie de génération : `auto-increment` (entiers séquentiels), `uuid` (identifiants uniques aléatoires) ou `composite` (multi-champs). |
| `field`   | Nom du champ pour une clé mono-colonne. Utilisé uniquement avec `auto-increment` ou `uuid`. Doit correspondre à `^[a-z][a-z0-9_]*`.       |
| `fields`  | Tableau de noms de champs pour une clé primaire composite.                                                                                |

```yaml
primaryKey: { type: auto-increment, field: id }
```

```yaml
# Clé primaire composite
primaryKey: { type: composite, fields: [tenant_id, slug] }
```

## Index

`indexes` est un tableau de définitions d'index. Les noms d'index doivent être uniques au sein de la table.

| Propriété | Description                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | Nom de l'index. Doit correspondre à `^[a-z][a-z0-9_]*`. Utilisez des noms descriptifs comme `idx_users_email`.                        |
| `fields`  | Tableau de noms de champs couverts par l'index. Au moins un requis.                                                                   |
| `unique`  | Booléen. Lorsqu'il vaut `true`, applique l'unicité sur les champs indexés.                                                            |
| `where`   | Clause SQL `WHERE` pour un **index partiel** — indexe uniquement les lignes satisfaisant la condition (par ex. `deleted_at IS NULL`). |

```yaml
indexes:
  - { name: idx_users_email, fields: [email], unique: true }
  - { name: idx_orders_status, fields: [status] }
  # Index unique partiel — unicité uniquement sur les lignes non supprimées
  - { name: idx_active_slug, fields: [slug], unique: true, where: 'deleted_at IS NULL' }
```

## Contraintes d'unicité (`unique` de premier niveau)

Le tableau `unique` au niveau de la table est du sucre syntaxique pour déclarer l'unicité sur un ou plusieurs champs. Les entrées mono-champ se replient dans l'équivalent de `field.unique = true` ; les entrées multi-champs deviennent un index btree unique.

```yaml
unique:
  - { fields: [slug] } # unicité mono-champ
  - { fields: [tenant_id, slug] } # unicité composite
```

## Contraintes CHECK

`constraints` applique des règles métier complexes au niveau de la base de données avec des expressions booléennes SQL. Les noms de contraintes doivent être uniques au sein de la table et correspondre à `^[a-z][a-z0-9_]*`.

| Propriété | Description                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| `name`    | Nom de contrainte unique (minuscules, alphanumérique, underscores).               |
| `check`   | Expression booléenne PostgreSQL devant s'évaluer à TRUE pour des données valides. |

```yaml
constraints:
  - { name: chk_price_positive, check: 'price > 0' }
  - { name: chk_end_after_start, check: 'end_date > start_date' }
  - { name: chk_active_members_have_email, check: '(is_active = false) OR (email IS NOT NULL)' }
```

## Clés étrangères composites

Les clés étrangères mono-colonne sont créées automatiquement à partir des champs [`relationship`](/fr/relational-fields). Utilisez `foreignKeys` pour des références **multi-colonnes** vers une clé primaire composite d'une autre table.

| Propriété          | Description                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `name`             | Nom de la contrainte (minuscules, underscores, 63 caractères max).                        |
| `fields`           | Colonnes locales formant la clé étrangère.                                                |
| `referencedTable`  | Table parente contenant les colonnes référencées.                                         |
| `referencedFields` | Colonnes de la table parente qui sont référencées.                                        |
| `onDelete`         | Action référentielle à la suppression : `cascade`, `set-null`, `restrict` ou `no-action`. |
| `onUpdate`         | Action référentielle à la mise à jour : `cascade`, `set-null`, `restrict` ou `no-action`. |

```yaml
foreignKeys:
  - name: fk_permissions_tenant_user
    fields: [tenant_id, user_id]
    referencedTable: tenant_users
    referencedFields: [tenant_id, user_id]
    onDelete: cascade
    onUpdate: cascade
```

:::callout
**Index vs contraintes.** Utilisez `indexes` pour les performances des requêtes et l'unicité mono/multi-champs ; utilisez `constraints` (CHECK) pour la validation conditionnelle et inter-champs que l'unicité ne peut exprimer. Les deux sont validés par rapport aux noms de champs de la table au moment de la configuration.
:::

# Relations

Les tables se connectent via le champ [`relationship`](/fr/relational-fields#relationship), qui crée un lien par clé étrangère vers une autre table. Une fois qu'une relation existe, [`lookup`](/fr/relational-fields#lookup), [`rollup`](/fr/relational-fields#rollup) et [`count`](/fr/advanced-fields#count) dérivent des données à travers elle sans dupliquer les valeurs.

## Définir une relation

```yaml
- id: 1
  name: customer
  type: relationship
  relatedTable: Customers
  relationType: many-to-one
  displayField: full_name
  onDelete: set-null
  onUpdate: cascade
  reciprocalField: orders
```

## Cardinalités

`relationType` définit la forme du lien. Par défaut `many-to-one`.

| Cardinalité    | Signification                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `one-to-one`   | Chaque enregistrement est lié à exactement un enregistrement, et inversement.                                 |
| `many-to-one`  | Plusieurs enregistrements ici sont liés à un enregistrement de la table liée (par défaut).                    |
| `one-to-many`  | Un enregistrement ici est lié à plusieurs dans la table liée (utilise `foreignKey`).                          |
| `many-to-many` | Les enregistrements des deux côtés sont liés à plusieurs de l'autre (`allowMultiple` vaut `true` par défaut). |

## Actions référentielles

`onDelete` et `onUpdate` définissent ce qui arrive aux lignes dépendantes lorsque la ligne liée est supprimée ou que sa clé est mise à jour.

| Action      | Effet                                                           |
| ----------- | --------------------------------------------------------------- |
| `cascade`   | Propage la suppression/mise à jour aux lignes dépendantes.      |
| `set-null`  | Définit la clé étrangère à NULL sur les lignes dépendantes.     |
| `restrict`  | Empêche l'opération tant que des dépendants existent.           |
| `no-action` | Diffère la vérification ; n'effectue aucune action automatique. |

## Liens réciproques et champ d'affichage

| Propriété         | Description                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `reciprocalField` | Nom du champ créé sur la table liée pour le lien inverse (bidirectionnel).                                        |
| `displayField`    | Champ de la table liée affiché dans l'interface à la place de l'identifiant brut (par ex. `full_name`).           |
| `foreignKey`      | Nom personnalisé de la colonne de clé étrangère (utilisé pour `one-to-many`). Généré automatiquement lorsqu'omis. |
| `allowMultiple`   | Autorise la liaison à plusieurs enregistrements liés (par défaut `true` pour `many-to-many`).                     |
| `limitToView`     | Restreint les enregistrements liés sélectionnables à ceux visibles dans une vue nommée de la table liée.          |

## Exemple complet

Une table `Orders` reliée à `Customers`, exposant l'e-mail du client via un lookup et un total de commandes par client via un rollup :

```yaml
tables:
  - id: 1
    name: Customers
    fields:
      - { id: 1, name: full_name, type: single-line-text, required: true }
      - { id: 2, name: email, type: email, unique: true }
  - id: 2
    name: Orders
    fields:
      - { id: 1, name: amount, type: currency, currency: USD, required: true }
      - id: 2
        name: customer
        type: relationship
        relatedTable: Customers
        relationType: many-to-one
        displayField: full_name
        onDelete: restrict
        reciprocalField: orders
      - {
          id: 3,
          name: customer_email,
          type: lookup,
          relationshipField: customer,
          relatedField: email,
        }
```

Et du côté `Customers`, un rollup des montants de commandes via le lien réciproque `orders` :

```yaml
- {
    id: 3,
    name: lifetime_value,
    type: rollup,
    relationshipField: orders,
    relatedField: amount,
    aggregation: SUM,
    format: currency,
  }
```

:::callout
**Validation.** `lookup`, `rollup` et `count` sont validés au moment de la configuration : leur `relationshipField` doit nommer un véritable champ `relationship` dans la même table. Une faute de frappe ou une référence à un champ non relationnel échoue au décodage avec une erreur claire.
:::

# Vues

Les vues sont des configurations enregistrées et nommées décrivant comment les enregistrements d'une table sont filtrés, triés, regroupés et projetés. Ajoutez-les sous le tableau `views` d'une table. Une vue fonctionne dans l'un de deux modes : **mode config JSON** (filtres/tris/champs/regroupement déclaratifs) ou **mode SQL** (une `query` PostgreSQL brute).

## Propriétés des vues

| Propriété            | Description                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | Identifiant unique de la vue.                                                                                                 |
| `name`               | Nom lisible de la vue.                                                                                                        |
| `isDefault`          | Booléen. Lorsqu'il vaut `true`, la configuration de cette vue s'applique lorsqu'aucune vue spécifique n'est demandée.         |
| `filters`            | Conditions de filtre (mode config JSON). Voir ci-dessous.                                                                     |
| `sorts`              | Tableau de règles de tri `{ field, direction }` (mode config JSON). `direction` vaut `asc` ou `desc`.                         |
| `fields`             | Tableau de noms de champs à inclure, dans l'ordre d'affichage (mode config JSON).                                             |
| `groupBy`            | Configuration de regroupement `{ field, direction? }` (mode config JSON).                                                     |
| `query`              | SQL brut pour une `VIEW` PostgreSQL (mode SQL). Lorsqu'elle est définie, les propriétés de config JSON ne sont pas utilisées. |
| `materialized`       | Booléen. Avec `query`, crée une `MATERIALIZED VIEW` qui met les résultats en cache. Mode SQL uniquement.                      |
| `refreshOnMigration` | Booléen. Avec `materialized`, rafraîchit la vue matérialisée lors des migrations.                                             |

## Mode config JSON

Déclaratif — filtrez, triez, regroupez et choisissez des colonnes sans écrire de SQL.

```yaml
views:
  - id: active_high_priority
    name: Active — High Priority
    isDefault: true
    filters:
      and:
        - { field: status, operator: equals, value: active }
        - { field: priority, operator: equals, value: high }
    sorts:
      - { field: created_at, direction: desc }
    fields: [title, status, priority, assigned_to]
    groupBy: { field: status, direction: asc }
```

### Filtres

Un filtre est soit une condition unique `{ field, operator, value }`, soit un groupe booléen combinant des conditions avec `and` / `or` (pouvant s'imbriquer) :

```yaml
filters:
  or:
    - { field: priority, operator: equals, value: high }
    - { field: priority, operator: equals, value: urgent }
```

Les opérateurs courants incluent `equals`, `greaterThan`, `lessThan` et des opérateurs de comparaison similaires. Voir [Validation](/fr/table-validation) pour la façon dont les champs de filtre sont vérifiés par rapport à la table.

## Mode SQL

Pour les rapports avancés, fournissez une `query` brute. Définissez `materialized: true` pour mettre les résultats en cache, et `refreshOnMigration: true` pour maintenir le cache à jour à travers les migrations de schéma.

```yaml
views:
  - id: monthly_revenue
    name: Monthly Revenue
    query: >
      SELECT date_trunc('month', created_at) AS month, SUM(amount) AS revenue
      FROM orders GROUP BY 1 ORDER BY 1
    materialized: true
    refreshOnMigration: true
```

:::callout
**Vue par défaut.** Marquez exactement une vue par table avec `isDefault: true` pour contrôler quels enregistrements apparaissent lorsqu'un consommateur demande la table sans nommer de vue. Les identifiants de vue et la règle de vue par défaut unique sont validés au moment de la configuration.
:::

# Validation

Sovrium valide les données à deux niveaux : **au moment de la configuration** (le schéma est décodé avec Effect Schema au démarrage de l'application, capturant les définitions invalides) et **à l'exécution** (les enregistrements sont vérifiés par rapport aux règles de champ, aux contraintes et aux permissions à chaque écriture). Cette page résume la surface de validation des tables.

## Validation au niveau du champ

De nombreux types de champs portent une validation intégrée dérivée de leurs propriétés :

| Règle                 | S'applique à                                     | Effet                                                                |
| --------------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
| `required`            | Tous les champs                                  | La valeur doit être présente sur chaque enregistrement.              |
| `unique`              | Tous les champs                                  | Deux enregistrements ne peuvent partager la valeur.                  |
| `min` / `max`         | `integer`, `decimal`, `currency`, `percentage`   | La valeur doit tomber dans la plage inclusive.                       |
| `precision`           | `decimal` (1–10), `currency`/`percentage` (0–10) | Restreint les décimales.                                             |
| `currency` (ISO 4217) | `currency`                                       | Doit être un code à trois lettres valide.                            |
| `maxLength`           | `rich-text`                                      | Plafonne la longueur de caractères.                                  |
| `maxSelections`       | `multi-select`                                   | Plafonne les choix ; ne peut dépasser le nombre d'`options`.         |
| `options`             | `single-select`, `multi-select`, `status`        | Les valeurs doivent provenir de la liste d'options déclarée.         |
| validation de format  | `email`, `url`                                   | Doit correspondre à la RFC 5322 / une URL absolue valide.            |
| `targetLanguage`      | `ai-translate`                                   | Doit être un code ISO 639-1 (éventuellement suffixé par une région). |
| `categories` / `tags` | `ai-categorize` / `ai-tag`                       | Minimum 2 entrées, sans doublons.                                    |

## Validation au niveau de la table (au moment de la configuration)

Lorsque le schéma est décodé, Sovrium applique des règles structurelles et rejette les configurations invalides avec des erreurs descriptives :

- **Les noms et identifiants de champs** doivent être uniques au sein d'une table.
- **Les noms de champs et de tables** doivent correspondre à `^[a-z][a-z0-9_]*` (après assainissement) et rester dans la limite de 63 caractères.
- **Les noms d'index** et **les noms de contraintes** doivent être uniques au sein de la table et correspondre au motif d'identifiant.
- **Les champs de clé primaire** doivent référencer de véritables champs.
- **Les index, permissions, vues, webhooks** sont vérifiés afin que leurs références de champ nomment de véritables champs de la table.
- **Les champs `count` / `rollup` / `lookup`** doivent référencer un champ `relationship` existant dans la même table.
- **Les champs formula** sont validés pour des références de champs correctes.
- **Les noms de webhooks** doivent être uniques, et les sélecteurs de champs `payload` doivent nommer de véritables champs (l'`id` implicite est toujours valide).

## Contraintes CHECK

Utilisez les [contraintes CHECK](/fr/table-indexes-constraints#contraintes-check) pour les règles inter-champs et conditionnelles que la validation au niveau du champ ne peut exprimer :

```yaml
constraints:
  - { name: chk_end_after_start, check: 'end_date > start_date' }
  - { name: chk_active_members_have_email, check: '(is_active = false) OR (email IS NOT NULL)' }
```

## Unicité et intégrité

- Unicité mono-champ : `field.unique: true` ou un `unique: [{ fields: [x] }]` de premier niveau.
- Unicité composite : `unique: [{ fields: [a, b] }]` de premier niveau (devient un index unique) ou un [index](/fr/table-indexes-constraints#index) unique.
- Unicité partielle : un index unique avec une clause `where` (par ex. slug unique uniquement parmi les lignes non supprimées).
- Intégrité relationnelle : les champs [`relationship`](/fr/relational-fields) créent des clés étrangères avec des actions `onDelete`/`onUpdate` ; les références composites utilisent `foreignKeys`.

:::callout
**Échouez rapidement au démarrage.** Parce que la configuration est décodée avec Effect Schema, une définition de table mal formée (nom de champ en double, référence de relation orpheline, code de devise invalide, précision hors plage) échoue au démarrage de l'application — et non silencieusement à l'exécution. Exécutez `sovrium validate app.yaml` pour vérifier une configuration avant de déployer.
:::

# Webhooks

Ajoutez `webhooks` à une table pour déclencher des requêtes HTTP `POST` sortantes lorsque des enregistrements sont créés, mis à jour ou supprimés. Chaque webhook est du sucre syntaxique au-dessus des automatisations — en interne, il se déploie en un déclencheur d'enregistrement plus une action `webhook.send`. Les noms de webhooks doivent être uniques au sein de la table.

## Propriétés des webhooks

| Propriété | Description                                                                                                                |
| --------- | -------------------------------------------------------------------------------------------------------------------------- |
| `name`    | **Requis.** Identifiant unique du webhook au sein de la table.                                                             |
| `url`     | **Requis.** URL de destination. Doit être une URL `http(s)` absolue valide.                                                |
| `events`  | **Requis.** Événements d'enregistrement qui déclenchent la livraison : l'un de `create`, `update`, `delete` (au moins un). |
| `enabled` | Booléen. Indique si le webhook est actif (par défaut `true`).                                                              |
| `auth`    | Authentification de la requête sortante (HMAC, clé API ou bearer). Voir ci-dessous.                                        |
| `retry`   | Politique de réessai pour les livraisons échouées. Voir ci-dessous.                                                        |
| `payload` | Sélection des champs du payload et options de métadonnées. Voir ci-dessous.                                                |

```yaml
webhooks:
  - name: order_created
    url: https://hooks.example.com/orders
    events: [create]
    enabled: true
```

## Authentification

`auth` sécurise la requête. Trois types sont pris en charge ; les secrets/clés/jetons prennent en charge les références `$env.`.

| Type     | Propriétés                                                                                                 |
| -------- | ---------------------------------------------------------------------------------------------------------- |
| `hmac`   | `secret` (requis), `algorithm` (`sha256` par défaut, ou `sha1`), `header` (nom de l'en-tête de signature). |
| `apiKey` | `key` (requis), `header` (nom de l'en-tête portant la clé).                                                |
| `bearer` | `token` (requis) envoyé en tant que jeton bearer.                                                          |

```yaml
auth: { type: hmac, secret: '$env.PARTNER_WEBHOOK_SECRET', algorithm: sha256 }
```

```yaml
auth: { type: apiKey, key: '$env.SERVICE_API_KEY', header: X-API-Key }
```

```yaml
auth: { type: bearer, token: '$env.API_BEARER_TOKEN' }
```

## Politique de réessai

`retry` contrôle la façon dont les livraisons échouées sont réessayées.

| Propriété      | Description                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `maxAttempts`  | Nombre de tentatives de réessai après l'échec initial. `0` désactive les réessais. Par défaut `3`. |
| `backoff`      | Stratégie de backoff : `exponential` ou `fixed`.                                                   |
| `initialDelay` | Millisecondes avant le premier réessai (par défaut `1000`).                                        |
| `maxDelay`     | Délai maximal en millisecondes entre les réessais.                                                 |

```yaml
retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
```

## Sélection du payload

`payload` façonne les données envoyées. `includeFields` (liste blanche) et `excludeFields` (liste noire) sont mutuellement exclusifs, et chaque champ nommé doit exister sur la table (l'`id` implicite est toujours valide).

| Propriété               | Description                                                                      |
| ----------------------- | -------------------------------------------------------------------------------- |
| `includeFields`         | N'inclut que ces champs (liste blanche).                                         |
| `excludeFields`         | Exclut ces champs (liste noire).                                                 |
| `includePreviousValues` | Inclut les valeurs précédentes de l'enregistrement lors des événements `update`. |
| `includeMetadata`       | Inclut les métadonnées de l'événement dans le payload.                           |

```yaml
payload: { includeFields: [customer, status, total], includePreviousValues: true }
```

## Exemple complet

```yaml
webhooks:
  - name: order_lifecycle
    url: https://hooks.example.com/orders
    events: [create, update, delete]
    enabled: true
    auth: { type: hmac, secret: '$env.ORDER_WEBHOOK_SECRET', algorithm: sha256 }
    retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
    payload: { excludeFields: [internal_notes], includePreviousValues: true }
```

:::callout
**Validation.** Les `name` de webhooks doivent être uniques au sein d'une table, et tout champ référencé par `payload.includeFields` / `excludeFields` doit nommer un véritable champ (ou l'`id` implicite). Les URL invalides et les schémas non-`http(s)` sont rejetés au moment du décodage de la configuration.
:::

# Vue d'ensemble des enregistrements

Chaque table que vous déclarez expose automatiquement une API REST complète pour ses enregistrements. Il n'y a aucun résolveur à écrire ni aucun point de terminaison à enregistrer — dès qu'une table existe dans votre configuration, sa collection `records` est accessible sous `/api/tables/:tableId/records`. Cette page documente la surface d'API partagée : la structure des URL, l'enveloppe de réponse, les métadonnées d'auteur et les règles transversales (authentification, permissions, mise en forme) que tout point de terminaison d'enregistrements respecte.

Les enregistrements sont les lignes d'une [table](tables-overview). Les tables définissent les colonnes (champs) ; les enregistrements contiennent les valeurs. L'API des enregistrements est le chemin canonique de lecture/écriture de ces données — les pages l'affichent, les formulaires y écrivent, les automatisations y réagissent et les intégrations externes la consomment.

## Surface des points de terminaison

`:tableId` accepte soit l'`id` numérique de la table, soit son `name`/slug. Tous les points de terminaison acceptent et renvoient du JSON.

| Méthode et chemin                                                          | Description                                                                                         |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `POST /api/tables/:tableId/records`                                        | Créer un enregistrement unique                                                                      |
| `GET /api/tables/:tableId/records`                                         | Lister les enregistrements (pagination, tri, filtre, sélection de champs, regroupement, agrégation) |
| `GET /api/tables/:tableId/records/:recordId`                               | Lire un enregistrement unique par ID                                                                |
| `PATCH /api/tables/:tableId/records/:recordId`                             | Mettre à jour un enregistrement unique (partiel)                                                    |
| `DELETE /api/tables/:tableId/records/:recordId`                            | Supprimer (réversible) un enregistrement (`?permanent=true` pour suppression définitive)            |
| `POST /api/tables/:tableId/records/upsert`                                 | Créer ou mettre à jour selon des champs de correspondance                                           |
| `POST /api/tables/:tableId/records/batch`                                  | Création en lot                                                                                     |
| `PATCH /api/tables/:tableId/records/batch`                                 | Mise à jour en lot                                                                                  |
| `DELETE /api/tables/:tableId/records/batch`                                | Suppression (réversible) en lot                                                                     |
| `POST /api/tables/:tableId/records/:recordId/restore`                      | Restaurer un enregistrement supprimé de façon réversible                                            |
| `POST /api/tables/:tableId/records/batch/restore`                          | Restauration en lot                                                                                 |
| `GET /api/tables/:tableId/records/:recordId/history`                       | Historique des modifications d'un enregistrement                                                    |
| `GET\|POST\|PATCH\|DELETE /api/tables/:tableId/records/:recordId/comments` | Commentaires d'un enregistrement                                                                    |
| `GET /api/tables/:tableId/trash`                                           | Parcourir les enregistrements supprimés de façon réversible (vue corbeille)                         |
| `GET /api/tables/:tableSlug/subscribe`                                     | Abonnement WebSocket en temps réel                                                                  |

Le comportement détaillé est réparti sur des pages dédiées : [CRUD et upsert](records-crud), [filtrage, tri et pagination](records-filtering-sorting), [opérations en lot](records-batch), [historique et commentaires](record-history), [suppression réversible et corbeille](records-soft-delete), [abonnements en temps réel](records-realtime) et [import/export](records-import-export).

## L'enveloppe `fields`

Les corps d'écriture d'enregistrements utilisent l'enveloppe canonique de style Airtable : un objet `fields` associant les noms de champs à leurs valeurs.

```json
POST /api/tables/contacts/records
{
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

Une création réussie renvoie `201 Created` avec l'enregistrement stocké, y compris son `id` généré et ses métadonnées d'auteur :

```json
{
  "id": "42",
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "createdBy": "user-uuid-123",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

:::callout
**Les corps plats sont également acceptés.** Un corps sans clé `fields` (par ex. `{ "email": "john@example.com" }`) est automatiquement enveloppé dans la forme canonique `{ "fields": { ... } }`. La forme enveloppée est préférée et constitue la seule forme acceptée par les points de terminaison en lot et upsert.
:::

## Enveloppe de réponse de liste

`GET .../records` renvoie une enveloppe paginée, jamais un simple tableau :

```json
{
  "records": [{ "id": "1", "fields": {} }],
  "pagination": { "total": 128, "limit": 20, "offset": 0 }
}
```

`records` est la page de résultats ; `pagination` porte le nombre total `total` de lignes correspondantes ainsi que les valeurs `limit`/`offset` ayant produit cette page. Voir [Filtrage, tri et pagination](records-filtering-sorting) pour la grammaire complète des paramètres de requête.

## Métadonnées d'auteur

L'API estampille et expose automatiquement l'auteur de chaque écriture. Ces champs sont contrôlés par le serveur et **en lecture seule** — les valeurs fournies dans le corps d'une requête sont ignorées, de sorte que la piste d'audit ne peut pas être falsifiée.

| Champ                     | Renseigné quand                            | Effacé/mis à jour              |
| ------------------------- | ------------------------------------------ | ------------------------------ |
| `createdBy` / `createdAt` | L'enregistrement est créé                  | Ne change jamais               |
| `updatedBy` / `updatedAt` | L'enregistrement est créé ou mis à jour    | Réestampillé à chaque écriture |
| `deletedBy` / `deletedAt` | L'enregistrement est supprimé (réversible) | Effacé lors de la restauration |

`createdBy`, `updatedBy` et `deletedBy` se résolvent en l'ID de l'utilisateur authentifié. Ils sont exposés via des [types de champs d'audit utilisateur](user-audit-fields) dédiés (`created-by`, `updated-by`, `deleted-by`) et le champ système `updated-at` incrémente automatiquement l'horodatage à chaque écriture — ce qui permet le contrat de [verrouillage optimiste](records-crud).

## Règles transversales

Chaque point de terminaison d'enregistrements applique les mêmes garanties :

| Préoccupation                        | Comportement                                                                                                                                                |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentification**                 | Les points de terminaison nécessitent une session. Les requêtes non authentifiées renvoient `401`.                                                          |
| **Existence de la table**            | Un `:tableId` inconnu renvoie `404` — jamais un 403, pour éviter l'énumération.                                                                             |
| **RBAC**                             | La création/lecture/mise à jour/suppression est régulée par [permission de table](table-permissions) et les attributions [RBAC](auth-roles-rbac) du rôle.   |
| **Permissions au niveau des champs** | Les réponses omettent les champs que l'appelant ne peut pas lire ; les écritures vers des champs que l'appelant ne peut pas modifier sont rejetées.         |
| **Validation**                       | Les valeurs des champs sont validées par rapport au type de champ ; les champs requis manquants et les violations de contraintes renvoient `400`.           |
| **Anti-énumération**                 | Un accès non autorisé à un enregistrement existant renvoie `404`, et non `403`, de sorte qu'un attaquant ne peut pas distinguer « interdit » de « absent ». |

:::callout
**404 plutôt que 403 est intentionnel.** Pour empêcher l'énumération des enregistrements, l'API renvoie `404 Not Found` pour les enregistrements auxquels l'appelant n'a pas accès — identique à la réponse pour les enregistrements qui n'existent pas. Voir la [vue d'ensemble de l'authentification](auth-overview).
:::

## Mise en forme d'affichage vs brute

Par défaut, les valeurs des champs sont renvoyées brutes (la valeur stockée). Passez `?format=display` pour recevoir des valeurs lisibles par un humain, sensibles à la locale et au fuseau horaire (devises, dates, durées et noms d'affichage des pièces jointes mis en forme). La forme brute est préférée pour les clients programmatiques ; la forme d'affichage est préférée pour le rendu direct. Voir [Mise en forme des enregistrements](records-crud) pour les contrôles.

## Pages associées

- [CRUD et upsert](records-crud) — créer, lire, mettre à jour, supprimer, upsert, mise en forme
- [Filtrage, tri et pagination](records-filtering-sorting) — paramètres de requête
- [Opérations en lot](records-batch) — création/mise à jour/suppression en masse
- [Historique et commentaires des enregistrements](record-history) — journal des modifications et collaboration
- [Suppression réversible et restauration](records-soft-delete) — corbeille et récupération
- [Abonnements en temps réel](records-realtime) — WebSocket/SSE/sondage
- [Import et export](records-import-export) — CSV/JSON et presse-papiers
- [Référence de l'API](api-reference) — le catalogue de points de terminaison généré

# CRUD et upsert des enregistrements

Cette page couvre les opérations de cycle de vie d'un enregistrement unique : créer, lire, mettre à jour, supprimer et upsert. Pour lister de nombreux enregistrements, voir [Filtrage, tri et pagination](records-filtering-sorting) ; pour les écritures en masse, voir [Opérations en lot](records-batch). Tous les corps d'écriture utilisent l'enveloppe canonique `{ "fields": { ... } }` décrite dans la [vue d'ensemble des enregistrements](records-overview).

## Créer un enregistrement

```json
POST /api/tables/contacts/records
{
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

| Statut             | Signification                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `201 Created`      | Enregistrement créé ; le corps est l'enregistrement stocké avec `id` et auteur               |
| `400 Bad Request`  | Champ requis manquant, valeur de type de champ invalide ou violation de contrainte d'unicité |
| `401 Unauthorized` | Aucune session active                                                                        |
| `404 Not Found`    | La table n'existe pas (ou l'appelant n'y a pas accès)                                        |

La réponse porte l'`id` généré, l'écho des `fields` et les [métadonnées d'auteur](records-overview) (`createdBy`, `createdAt`, `updatedAt`).

## Lire un enregistrement

```
GET /api/tables/contacts/records/42
```

| Statut             | Signification                                                              |
| ------------------ | -------------------------------------------------------------------------- |
| `200 OK`           | Enregistrement renvoyé                                                     |
| `401 Unauthorized` | Aucune session active                                                      |
| `404 Not Found`    | Enregistrement absent **ou** non visible par l'appelant (anti-énumération) |

Les champs pour lesquels l'appelant n'a pas la permission de lecture sont omis de la réponse — le même enregistrement peut renvoyer un ensemble de champs différent selon le rôle de l'appelant et les [permissions au niveau des champs](table-permissions).

## Mettre à jour un enregistrement

`PATCH` effectue une mise à jour partielle : seuls les champs présents dans le corps sont écrits ; les champs omis sont laissés intacts.

```json
PATCH /api/tables/contacts/records/42
{
  "fields": {
    "status": "active"
  }
}
```

| Statut             | Signification                                                     |
| ------------------ | ----------------------------------------------------------------- |
| `200 OK`           | Enregistrement mis à jour ; `updatedBy`/`updatedAt` réestampillés |
| `400 Bad Request`  | Valeur de type de champ invalide ou violation de contrainte       |
| `401 Unauthorized` | Aucune session active                                             |
| `404 Not Found`    | Enregistrement absent ou non visible                              |
| `409 Conflict`     | Échec du verrouillage optimiste (écriture obsolète)               |

### Verrouillage optimiste

Incluez un jeton `updatedAt` de premier niveau à côté de `fields` pour vous prémunir contre les mises à jour perdues. Le serveur le compare à la colonne `updated_at` stockée et rejette une écriture divergente avec `409 Conflict`.

```json
PATCH /api/tables/contacts/records/42
{
  "fields": { "status": "active" },
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

:::callout
**Les tables y adhèrent via le champ système `updated-at`.** Ajoutez un champ de `type: 'updated-at'` afin que la colonne soit automatiquement incrémentée à chaque écriture. Un champ `datetime` ordinaire est modifiable par l'utilisateur et **n'est pas** géré automatiquement, il ne peut donc pas étayer le contrat de verrouillage optimiste.
:::

## Supprimer un enregistrement

Par défaut, `DELETE` est une **suppression réversible** : il renseigne `deletedAt`/`deletedBy` et laisse la ligne récupérable.

```
DELETE /api/tables/contacts/records/42
DELETE /api/tables/contacts/records/42?permanent=true
```

| Statut                      | Signification                                                                          |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `200 OK` / `204 No Content` | Enregistrement supprimé de façon réversible (ou définitivement avec `?permanent=true`) |
| `401 Unauthorized`          | Aucune session active                                                                  |
| `403`/`404`                 | L'appelant n'a pas la permission de suppression, ou l'enregistrement n'est pas visible |

La suppression définitive (`?permanent=true`) requiert la permission `permanentDelete` et est irréversible. Voir [Suppression réversible et restauration](records-soft-delete) pour la corbeille, la restauration et le comportement en cascade sur les enregistrements associés.

## Upsert d'un enregistrement

L'upsert crée un enregistrement ou met à jour un enregistrement existant correspondant à un ou plusieurs champs uniques, en un seul appel. Utilisez `matchFields` (alias : `fieldsToMergeOn`) pour nommer la ou les clés de fusion.

```json
POST /api/tables/contacts/records/upsert
{
  "fields": {
    "email": "john@example.com",
    "name": "John Doe",
    "status": "active"
  },
  "matchFields": ["email"]
}
```

La réponse indique si la ligne a été `created` (créée) ou `updated` (mise à jour) :

```json
{
  "id": 123,
  "operation": "created",
  "record": {
    "id": 123,
    "email": "john@example.com",
    "name": "John Doe",
    "status": "active"
  }
}
```

Lorsqu'une ligne existante correspond aux `matchFields`, `operation` vaut `"updated"` à la place et la ligne correspondante est mise à jour. L'upsert est idéal pour la synchronisation idempotente depuis des systèmes externes — voir [Opérations en lot](records-batch) pour la variante `upsert` multi-enregistrements.

## Mise en forme d'affichage vs brute

Le paramètre de requête `format` contrôle la manière dont les valeurs des champs sont sérialisées sur les points de terminaison de lecture.

| `format`       | Comportement                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `raw` (défaut) | Valeurs stockées, inchangées — préféré pour les clients programmatiques                                     |
| `display`      | Valeurs lisibles par un humain : devises, dates, durées et noms d'affichage des pièces jointes mis en forme |

```
GET /api/tables/orders/records?format=display&timezone=Europe/Paris
```

La mise en forme est pilotée par type de champ :

| Type de champ                         | Mise en forme d'affichage                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `currency`                            | Symbole, nombre de décimales et séparateurs selon la locale                           |
| `datetime`                            | Format date/heure configuré ; `?timezone=` (IANA) remplace le fuseau horaire de rendu |
| `duration`                            | `h:mm`, `h:mm:ss` ou heures décimales selon la configuration du champ                 |
| `attachment` / `multiple-attachments` | URL plus métadonnées et noms d'affichage                                              |
| `json`                                | Sérialisé selon la configuration du champ et le paramètre `format`                    |

:::callout
**Le brut est la source de vérité.** `format=display` est une commodité de présentation superposée à la valeur stockée. L'aller-retour (lecture avec `display`, réécriture) n'est pas garanti — écrivez toujours la valeur brute. Les champs numériques et de date conservent leur forme brute disponible pour les calculs.
:::

## Pages associées

- [Vue d'ensemble des enregistrements](records-overview) — enveloppe, auteur, règles transversales
- [Filtrage, tri et pagination](records-filtering-sorting) — grammaire des requêtes de liste
- [Opérations en lot](records-batch) — création/mise à jour/suppression/upsert en masse
- [Suppression réversible et restauration](records-soft-delete) — corbeille et récupération
- [Permissions de table](table-permissions) — RBAC et accès au niveau des champs

# Filtrage, tri et pagination

`GET /api/tables/:tableId/records` renvoie une enveloppe paginée et accepte un riche ensemble de paramètres de requête pour paginer, trier, filtrer, sélectionner des champs, regrouper et agréger des enregistrements — afin que vous puissiez façonner de grands ensembles de données sans écrire de points de terminaison personnalisés. Chaque paramètre est facultatif ; combinez-les librement.

```
GET /api/tables/tasks/records?limit=10&offset=0&sort=priority:desc,name:asc&fields=id,name,status
```

La réponse est toujours l'enveloppe de liste (jamais un simple tableau) :

```json
{
  "records": [{ "id": "1", "fields": {} }],
  "pagination": { "total": 128, "limit": 10, "offset": 0 }
}
```

## Référence des paramètres de requête

| Paramètre        | Description                                                                                         | Exemple                          |
| ---------------- | --------------------------------------------------------------------------------------------------- | -------------------------------- |
| `limit`          | Nombre maximal d'enregistrements à renvoyer                                                         | `?limit=20`                      |
| `offset`         | Nombre d'enregistrements à ignorer                                                                  | `?offset=40`                     |
| `page`           | Numéro de page (indexé à partir de 1) — alternative à `offset`                                      | `?page=3`                        |
| `sort`           | Champ(s) et direction de tri                                                                        | `?sort=name:asc,created_at:desc` |
| `order`          | Ordre de tri (`asc`/`desc`) pour un tri sur un seul champ                                           | `?sort=name&order=desc`          |
| `fields`         | Noms de champs séparés par des virgules à inclure                                                   | `?fields=id,name,status`         |
| `filter`         | Expression de filtre (JSON)                                                                         | `?filter={"status":"active"}`    |
| `view`           | Appliquer la configuration d'une [vue](table-views) enregistrée                                     | `?view=2`                        |
| `groupBy`        | Regrouper les enregistrements par un champ                                                          | `?groupBy=status`                |
| `aggregate`      | Fonctions d'agrégation                                                                              | `?aggregate=sum:amount,count:id` |
| `q`              | Requête de recherche en texte libre                                                                 | `?q=invoice`                     |
| `format`         | Valeurs de champ `raw` (défaut) ou `display`                                                        | `?format=display`                |
| `timezone`       | Fuseau horaire IANA pour la mise en forme des dates                                                 | `?timezone=Europe/Paris`         |
| `includeDeleted` | `true` pour inclure les lignes supprimées de façon réversible ; `only` pour la corbeille uniquement | `?includeDeleted=true`           |

## Pagination

Deux styles de pagination équivalents sont pris en charge. Utilisez `limit` + `offset` pour un balayage de style curseur, ou `limit` + `page` pour des interfaces paginées par numéro. `pagination.total` est le nombre de toutes les lignes correspondantes (indépendant de la page), de sorte qu'un client peut calculer le nombre de pages comme `ceil(total / limit)`.

```
GET /api/tables/tasks/records?limit=20&offset=40   # lignes 41–60
GET /api/tables/tasks/records?limit=20&page=3       # lignes 41–60 (indexé à partir de 1)
```

## Tri

Triez par un ou plusieurs champs, chacun avec une direction, en utilisant des segments `field:direction` séparés par des virgules. Le champ le plus à gauche est la clé de tri primaire.

```
GET /api/tables/tasks/records?sort=priority:desc,name:asc
```

Pour un seul champ de tri, vous pouvez plutôt répartir le champ et la direction entre `sort` et `order` (`?sort=name&order=desc`). La forme `field:direction` est préférée car elle se compose proprement pour les tris à plusieurs clés.

## Sélection de champs

Demandez un sous-ensemble de colonnes avec `fields`. Cela réduit la charge utile de la réponse — utile pour les vues de liste qui n'affichent que quelques colonnes. Les champs que l'appelant ne peut pas lire sont omis, qu'ils figurent ou non dans la liste `fields`.

```
GET /api/tables/contacts/records?fields=id,name,status
```

## Filtrage

Passez une expression de filtre JSON dans le paramètre `filter`. Un objet plat filtre par égalité sur chaque clé :

```
GET /api/tables/tasks/records?filter={"status":"active"}
```

Pour des conditions plus riches, les filtres utilisent la même forme structurée que les [vues](table-views) enregistrées — un arbre de groupes `and`/`or` dont les feuilles sont des conditions `{ field, operator, value }` :

```yaml
filters:
  and:
    - field: status
      operator: in
      value: [todo, in_progress]
    - field: priority
      operator: equals
      value: high
```

Les conditions nomment un `field`, un `operator` (par ex. `equals`, `in`, `greaterThan`) et une `value`. Les opérateurs sont résolus selon le type de champ.

:::callout
**Préférez les vues enregistrées pour les requêtes récurrentes.** Une vue regroupe un arbre de filtres, un ordre de tri et une sélection de champs sous un `id` stable. Référencez-la avec `?view=2` plutôt que de réencoder le même filtre à chaque requête. Voir [Vues de table](table-views).
:::

## Regroupement et agrégation

`groupBy` partitionne les enregistrements selon la valeur d'un champ ; `aggregate` calcule des fonctions de synthèse. Combinez-les pour produire des regroupements agrégés (par ex. le montant total par statut).

```
GET /api/tables/orders/records?groupBy=status
GET /api/tables/orders/records?aggregate=sum:amount,count:id,avg:quantity
```

Chaque entrée `aggregate` est de la forme `function:field` — les fonctions prises en charge incluent `sum`, `count`, `avg`, `min` et `max`. Lorsqu'elles sont associées à `groupBy`, les agrégats sont calculés par groupe.

## Vues enregistrées

Une vue (`?view=2`) applique son filtre, son tri et sa configuration de champs stockés côté serveur. Les paramètres de requête explicites se superposent à la vue, permettant à un client d'affiner davantage une vue de base sans la redéfinir.

```yaml
tables:
  - id: 1
    name: tasks
    views:
      - id: 2
        name: Active Tasks
        filters:
          and:
            - field: status
              operator: in
              value: [todo, in_progress]
        sorts:
          - field: priority
            direction: desc
```

## Inclure les enregistrements supprimés

Par défaut, les lignes supprimées de façon réversible sont exclues. Utilisez `includeDeleted=true` pour fusionner les lignes actives et supprimées, ou `includeDeleted=only` pour une vue corbeille uniquement. Voir [Suppression réversible et restauration](records-soft-delete) pour le flux complet de récupération.

## Pages associées

- [Vue d'ensemble des enregistrements](records-overview) — enveloppe de liste et règles transversales
- [CRUD et upsert](records-crud) — opérations sur un enregistrement unique et mise en forme
- [Vues de table](table-views) — configurations de filtre/tri/champs enregistrées
- [Suppression réversible et restauration](records-soft-delete) — requêtes sur la corbeille

# Opérations en lot

Les points de terminaison en lot écrivent de nombreux enregistrements en une seule requête, afin que vous puissiez importer, synchroniser ou modifier des données en masse efficacement — et de façon atomique. Chaque lot s'exécute dans une seule transaction : si un enregistrement échoue à la validation, l'ensemble du lot est annulé et aucune ligne n'est écrite. Passez `returnRecords: true` pour recevoir les enregistrements affectés dans la réponse (sinon, seul un résumé est renvoyé).

| Méthode et chemin                                 | Opération              | Max par lot |
| ------------------------------------------------- | ---------------------- | ----------- |
| `POST /api/tables/:tableId/records/batch`         | Créer                  | 1000        |
| `PATCH /api/tables/:tableId/records/batch`        | Mettre à jour          | 100         |
| `DELETE /api/tables/:tableId/records/batch`       | Suppression réversible | 100         |
| `POST /api/tables/:tableId/records/batch/restore` | Restaurer              | 100         |
| `POST /api/tables/:tableId/records/upsert`        | Upsert                 | 100         |

Tous les corps en lot requièrent la forme enveloppée canonique (`{ "fields": { ... } }`) — le raccourci de corps plat accepté par la création d'un enregistrement unique n'est **pas** disponible dans les requêtes en lot. Chaque lot doit contenir au moins un enregistrement.

## Création en lot

Envoyez un tableau `records`, chaque élément étant une enveloppe. Jusqu'à 1000 enregistrements par appel.

```json
POST /api/tables/contacts/records/batch
{
  "records": [
    { "fields": { "email": "alice@example.com", "name": "Alice" } },
    { "fields": { "email": "bob@example.com", "name": "Bob" } }
  ],
  "returnRecords": true
}
```

| Statut             | Signification                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `201 Created`      | Tous les enregistrements créés                                                                                   |
| `400 Bad Request`  | Tableau vide, au-delà de la limite de 1000, ou un enregistrement échoue à la validation (tout le lot est annulé) |
| `401 Unauthorized` | Aucune session active                                                                                            |
| `404 Not Found`    | Table introuvable ou non visible                                                                                 |

## Mise à jour en lot

Chaque élément nomme l'`id` de l'enregistrement (chaîne ou nombre) plus les `fields` à mettre à jour. Jusqu'à 100 enregistrements par appel.

```json
PATCH /api/tables/contacts/records/batch
{
  "records": [
    { "id": "1", "fields": { "status": "active" } },
    { "id": 2, "fields": { "status": "archived" } }
  ],
  "returnRecords": true
}
```

Les mises à jour sont partielles par enregistrement — seuls les champs nommés sont écrits. Si un `id` est manquant ou une valeur invalide, la transaction est annulée.

## Suppression en lot

Envoyez un tableau `ids`. Suppression réversible par défaut ; définissez `permanent: true` pour supprimer définitivement des enregistrements déjà supprimés de façon réversible (réservé aux administrateurs, appliqué dans la couche applicative). Jusqu'à 100 ID par appel.

```json
DELETE /api/tables/contacts/records/batch
{
  "ids": ["1", "2", 3],
  "permanent": false
}
```

:::callout
**`permanent` peut aussi être une chaîne de requête.** Les variantes de route qui conservent le contrat hérité acceptent `?permanent=true`. La forme par corps JSON est préférée. La suppression définitive en lot est irréversible et requiert la permission `permanentDelete` — voir [Suppression réversible et restauration](records-soft-delete).
:::

## Restauration en lot

Récupérez plusieurs enregistrements supprimés de façon réversible en une seule fois. Les enregistrements qui ne sont pas actuellement supprimés sont ignorés ; un `id` manquant annule l'ensemble du lot.

```json
POST /api/tables/contacts/records/batch/restore
{
  "ids": ["1", "2", "3"]
}
```

La restauration efface les champs `deletedAt`/`deletedBy` de chaque enregistrement et est consignée dans l'[historique des modifications](record-history) de l'enregistrement.

## Upsert en lot

Créez ou mettez à jour de nombreux enregistrements correspondant à un ou plusieurs champs uniques, en une seule transaction. Nommez la ou les clés de fusion avec `fieldsToMergeOn` (alias : `matchFields`). Jusqu'à 100 enregistrements par appel.

```json
POST /api/tables/contacts/records/upsert
{
  "records": [
    { "fields": { "email": "alice@example.com", "name": "Alice" } },
    { "fields": { "email": "carol@example.com", "name": "Carol" } }
  ],
  "fieldsToMergeOn": ["email"],
  "returnRecords": true
}
```

Chaque enregistrement est mis en correspondance sur les champs de fusion : une correspondance existante est mise à jour, sinon une nouvelle ligne est créée. L'upsert en lot est le chemin canonique pour la synchronisation idempotente depuis une source de vérité externe.

## Résumé des limites et de la sémantique

| Propriété       | Comportement                                                                                         |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| Atomicité       | Chaque lot est une seule transaction — tout ou rien                                                  |
| `returnRecords` | `false` par défaut ; `true` renvoie les enregistrements affectés                                     |
| Taille minimale | Au moins un enregistrement/ID requis (`400` sinon)                                                   |
| Auteur          | `createdBy`/`updatedBy`/`deletedBy` estampillés par enregistrement, comme pour les écritures uniques |
| Permissions     | RBAC et permissions au niveau des champs appliqués par enregistrement                                |

## Pages associées

- [CRUD et upsert](records-crud) — opérations sur un enregistrement unique et contrat d'upsert
- [Suppression réversible et restauration](records-soft-delete) — suppression définitive et restauration
- [Historique et commentaires des enregistrements](record-history) — les opérations en lot sont consignées
- [Vue d'ensemble des enregistrements](records-overview) — règles d'enveloppe et d'auteur

# Historique et commentaires des enregistrements

Chaque enregistrement porte deux surfaces d'activité : un **historique des modifications** automatique (une piste d'audit maintenue par le système indiquant qui a modifié quoi et quand) et un **fil de commentaires** (une discussion rédigée par les utilisateurs attachée à l'enregistrement). Les deux sont accessibles sous l'URL de l'enregistrement.

| Méthode et chemin                                                   | Description                                                  |
| ------------------------------------------------------------------- | ------------------------------------------------------------ |
| `GET /api/tables/:tableId/records/:recordId/history`                | Récupérer l'historique des modifications d'un enregistrement |
| `GET /api/tables/:tableId/records/:recordId/comments`               | Lister les commentaires d'un enregistrement                  |
| `GET /api/tables/:tableId/records/:recordId/comments/:commentId`    | Lire un commentaire unique                                   |
| `POST /api/tables/:tableId/records/:recordId/comments`              | Créer un commentaire                                         |
| `PATCH /api/tables/:tableId/records/:recordId/comments/:commentId`  | Modifier un commentaire                                      |
| `DELETE /api/tables/:tableId/records/:recordId/comments/:commentId` | Supprimer un commentaire                                     |

## Historique des modifications

L'historique est suivi automatiquement pour toutes les tables — il n'y a rien à activer. Chaque création, mise à jour, suppression et restauration est enregistrée avec l'utilisateur agissant et un différentiel structuré au niveau des champs. Lisez-le avec :

```
GET /api/tables/orders/records/123/history
```

```json
{
  "history": [
    {
      "id": 1,
      "action": "update",
      "changes": {
        "status": { "from": "pending", "to": "approved" }
      },
      "user": { "id": 1, "name": "Alice" },
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}
```

| Champ       | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `action`    | `create`, `update`, `delete` ou `restore`                  |
| `changes`   | Différentiel `{ from, to }` par champ pour la modification |
| `user`      | L'utilisateur agissant (`id`, `name`)                      |
| `timestamp` | Heure ISO 8601 à laquelle la modification s'est produite   |

L'historique enregistre les modifications de **toutes** les sources — écritures via l'API REST, modifications administrateur, automatisations et opérations en lot — de sorte que la piste est complète. Il complète les [champs d'auteur](records-overview) par enregistrement (`createdBy`/`updatedBy`/`deletedBy`), qui capturent le dernier acteur sur l'enregistrement lui-même.

:::callout
**La configuration de la rétention et du suivi des champs n'est pas encore disponible.** L'historique est actuellement suivi automatiquement pour chaque table sans aucune option par table. Les politiques de rétention configurables et le suivi sélectif des champs arriveront dans une future version du schéma.
:::

## Commentaires

Les commentaires sont des notes rédigées par les utilisateurs attachées à un enregistrement, prenant en charge les `@mentions`. L'utilisateur courant est injecté automatiquement comme auteur — vous ne fournissez que le `content`.

```json
POST /api/tables/orders/records/123/comments
{
  "content": "This looks good! @alice can you confirm the numbers?"
}
```

Une création réussie renvoie `201 Created` avec le commentaire stocké, y compris les mentions analysées et l'auteur résolu :

```json
{
  "id": 2,
  "content": "This looks good! @alice can you confirm the numbers?",
  "mentions": [{ "userId": 1, "username": "alice", "position": 21 }],
  "author": { "id": 2, "name": "Bob" },
  "created_at": "2025-01-15T11:00:00Z"
}
```

`content` est requis et limité à 10 000 caractères. Les jetons `@username` sont analysés en un tableau `mentions` (chacun avec le `userId`, le `username` et la `position` de caractère résolus), que les fonctionnalités en aval (par ex. les [notifications](notifications)) consomment.

### Lire les commentaires

```
GET /api/tables/orders/records/123/comments       # lister tout
GET /api/tables/orders/records/123/comments/2      # commentaire unique
```

Le point de terminaison de liste renvoie le fil de commentaires de l'enregistrement. L'objet auteur est projeté sous une forme d'affichage sûre (`id`, `name`) — l'e-mail et les autres données personnelles ne sont jamais exposés dans les réponses de commentaires.

### Modifier et supprimer

```
PATCH  /api/tables/orders/records/123/comments/2
DELETE /api/tables/orders/records/123/comments/2
```

La modification remplace `content` (en réanalysant les mentions) ; la suppression retire le commentaire. Les deux respectent le RBAC et les [permissions](table-permissions) de la table — généralement, un utilisateur peut modifier/supprimer ses propres commentaires, avec des droits plus étendus accordés aux rôles élevés.

## Règles transversales

| Préoccupation        | Comportement                                                                                        |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| Authentification     | Tous les points de terminaison nécessitent une session (`401` sinon)                                |
| Existence            | Une table/un enregistrement/un commentaire inconnu renvoie `404` (anti-énumération)                 |
| Sécurité de l'auteur | L'auteur du commentaire est injecté par le serveur ; les auteurs fournis par le client sont ignorés |
| Données personnelles | La projection de l'auteur n'expose que `id` et `name`                                               |

## Pages associées

- [Vue d'ensemble des enregistrements](records-overview) — métadonnées d'auteur vs historique des modifications
- [CRUD et upsert](records-crud) — les écritures que l'historique enregistre
- [Suppression réversible et restauration](records-soft-delete) — les suppressions/restaurations sont consignées dans l'historique
- [Permissions de table](table-permissions) — qui peut commenter, modifier et supprimer

# Suppression réversible et restauration

Supprimer un enregistrement est **non destructif par défaut** : la ligne est marquée comme supprimée (`deletedAt`/`deletedBy` estampillés) et disparaît des requêtes normales, mais reste récupérable. Cela protège contre les suppressions accidentelles, prend en charge un flux corbeille/annulation et conserve une piste d'audit. La suppression définitive (irréversible) est une opération distincte, régulée par permission, pour les cas qui exigent un effacement irréversible.

| Méthode et chemin                                              | Description                                                 |
| -------------------------------------------------------------- | ----------------------------------------------------------- |
| `DELETE /api/tables/:tableId/records/:recordId`                | Supprimer (réversible) un enregistrement                    |
| `DELETE /api/tables/:tableId/records/:recordId?permanent=true` | Supprimer définitivement un enregistrement                  |
| `GET /api/tables/:tableId/trash`                               | Parcourir les enregistrements supprimés de façon réversible |
| `POST /api/tables/:tableId/records/:recordId/restore`          | Restaurer un enregistrement supprimé de façon réversible    |
| `POST /api/tables/:tableId/records/batch/restore`              | Restaurer plusieurs enregistrements                         |

## Suppression réversible

```
DELETE /api/tables/orders/records/123
```

Ceci renseigne `deletedAt` avec l'heure courante et `deletedBy` avec l'utilisateur agissant, puis exclut la ligne des réponses de liste et de lecture par défaut. L'opération est consignée dans l'[historique des modifications](record-history) de l'enregistrement.

## Suppression définitive (irréversible)

```
DELETE /api/tables/orders/records/123?permanent=true
```

La suppression définitive retire la ligne de façon irréversible et requiert la permission `permanentDelete`. Lorsque la suppression forcée n'est pas autorisée pour une table, le point de terminaison renvoie `404` (anti-énumération) plutôt que `403`.

:::callout
**La suppression définitive est optionnelle et réservée aux administrateurs.** Réservez `?permanent=true` aux véritables besoins d'effacement — par ex. le droit à l'effacement RGPD sur des données personnelles. Les registres financiers et les tables proches de l'audit ne devraient s'appuyer que sur la suppression réversible. La suppression définitive est une opération irréversible : il n'y a pas de restauration.
:::

## Comportement en cascade sur les enregistrements associés

Lorsqu'un enregistrement est supprimé, les enregistrements associés sont traités selon la politique `onDelete` du champ de relation. Configurez-la sur le [champ relationnel](relational-fields).

```yaml
tables:
  - id: 1
    name: orders
    permissions:
      delete: ['admin', 'member']
      permanentDelete: ['admin'] # Permanent delete requires admin role
    fields:
      - id: 1
        name: customer_id
        type: relationship
        relatedTable: customers
        onDelete: cascade # cascade | set-null | restrict
```

| `onDelete` | Effet lorsque le parent est supprimé                         |
| ---------- | ------------------------------------------------------------ |
| `cascade`  | Supprimer également les enregistrements dépendants (enfants) |
| `set-null` | Effacer la référence de clé étrangère sur les dépendants     |
| `restrict` | Bloquer la suppression tant que des dépendants existent      |

## Vue corbeille

`GET /api/tables/:tableId/trash` liste les enregistrements supprimés de façon réversible afin qu'une interface puisse présenter une corbeille récupérable. Le même résultat est disponible sur le point de terminaison de liste via `includeDeleted=only`.

## Restauration

```
POST /api/tables/orders/records/123/restore
```

La restauration efface `deletedAt` (ramenant la ligne aux requêtes normales), estampille un `restored_at`, capture l'utilisateur restaurant et consigne l'opération dans l'historique.

```json
{
  "id": 123,
  "deleted_at": null,
  "restored_at": "2025-01-15T11:00:00Z"
}
```

| Statut             | Signification                                    |
| ------------------ | ------------------------------------------------ |
| `200 OK`           | Enregistrement restauré                          |
| `400 Bad Request`  | L'enregistrement n'est pas actuellement supprimé |
| `401 Unauthorized` | Aucune session active                            |
| `404 Not Found`    | Enregistrement absent ou non visible             |

### Restauration en lot

Récupérez plusieurs enregistrements en une seule transaction. Les enregistrements qui ne sont pas actuellement supprimés sont ignorés ; un `id` manquant annule l'ensemble du lot (`404`). Voir [Opérations en lot](records-batch).

```json
POST /api/tables/orders/records/batch/restore
{
  "ids": ["123", "124", "125"]
}
```

## Interroger les enregistrements supprimés

Par défaut, les lignes supprimées de façon réversible sont exclues des réponses de liste et de lecture. Remplacez ce comportement avec le paramètre de requête `includeDeleted` :

| Valeur   | Comportement                                                                             |
| -------- | ---------------------------------------------------------------------------------------- |
| _(omis)_ | Enregistrements actifs uniquement (défaut)                                               |
| `true`   | Enregistrements actifs **et** supprimés                                                  |
| `only`   | Enregistrements supprimés de façon réversible uniquement (équivalent à la vue corbeille) |

```
GET /api/tables/orders/records?includeDeleted=true
GET /api/tables/orders/records?includeDeleted=only
```

## Résumé des permissions

| Opération              | Permission                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| Suppression réversible | `delete` (selon les [permissions de table](table-permissions) + [RBAC](auth-roles-rbac)) |
| Suppression définitive | `permanentDelete` (généralement réservé aux administrateurs)                             |
| Restauration           | attribution `delete` / restauration pour le rôle                                         |

## Pages associées

- [Vue d'ensemble des enregistrements](records-overview) — auteur `deletedBy`/`deletedAt`
- [CRUD et upsert](records-crud) — le point de terminaison de suppression d'un enregistrement unique
- [Opérations en lot](records-batch) — suppression et restauration en lot
- [Champs relationnels](relational-fields) — configuration de la cascade `onDelete`
- [Historique et commentaires des enregistrements](record-history) — les suppressions et restaurations sont consignées

# Abonnements en temps réel

Les composants de page liés aux données peuvent rester à jour sans rechargement complet en s'abonnant aux modifications d'enregistrements. Une source de données déclare un `refreshMode` — `static` (par défaut), `poll` ou `realtime` — et Sovrium fait le reste : le mode poll récupère à nouveau les données à intervalle régulier, le mode realtime ouvre un WebSocket (avec un repli SSE) et applique les événements `insert`/`update`/`delete` à mesure qu'ils arrivent. Les intégrations externes peuvent s'abonner programmatiquement via les mêmes points de terminaison.

| Point de terminaison                       | Transport                            |
| ------------------------------------------ | ------------------------------------ |
| `GET /api/tables/:tableSlug/subscribe`     | Mise à niveau WebSocket (par table)  |
| `GET /api/tables/:tableSlug/subscribe/sse` | Repli Server-Sent Events (par table) |
| `GET /api/realtime/subscribe`              | WebSocket global                     |

## refreshMode sur une source de données

Définissez `refreshMode` sur la `dataSource` de n'importe quel composant. Le `filter` et le `sort` existants du composant délimitent également le flux en direct — les clients ne reçoivent que les modifications qui correspondent toujours aux critères de la source de données.

```yaml
pages:
  - name: Live Dashboard
    path: /dashboard
    components:
      - type: dataTable
        dataSource:
          table: orders
          filter:
            - field: status
              operator: eq
              value: processing
          sort:
            - field: createdAt
              direction: desc
          refreshMode: realtime
```

## Mode poll

Le mode poll récupère périodiquement à nouveau la source de données — aucun WebSocket nécessaire. Utilisez-le lorsqu'un quasi-temps-réel suffit et que la surcharge de gestion de connexion est indésirable.

```yaml
dataSource:
  table: inventory
  refreshMode: poll
  pollIntervalMs: 10000 # Re-fetch every 10 seconds
```

| Propriété        | Défaut         | Contrainte                                            |
| ---------------- | -------------- | ----------------------------------------------------- |
| `pollIntervalMs` | `30000` (30 s) | Minimum `1000` (1 s) pour éviter d'inonder le serveur |

## Mode temps réel (WebSocket)

`refreshMode: realtime` ouvre un WebSocket vers `/api/tables/:tableSlug/subscribe`. Le serveur pousse les événements de modification à mesure que les enregistrements sont créés, mis à jour ou supprimés — depuis **n'importe quelle** source (API REST, interface administrateur, écritures directes en base de données, automatisations).

```
GET /api/tables/orders/subscribe
Upgrade: websocket
```

Le serveur diffuse alors des messages tels que :

```json
{ "type": "change", "event": "insert", "record": { "id": "42", "fields": {  } } }
{ "type": "change", "event": "update", "record": {  }, "oldRecord": {  } }
{ "type": "change", "event": "delete", "recordId": 42 }
{ "type": "heartbeat", "timestamp": "2026-04-05T12:00:00Z" }
```

Les événements insert/update portent l'enregistrement complet `record` (filtré côté serveur selon les permissions de champ) ; les événements delete ne portent que `recordId`. La connexion requiert une authentification (`401` lors d'une mise à niveau non authentifiée) et un slug de table valide (`404` sinon).

## Filtrage des abonnements

Les abonnements respectent les `filter` et `sort` courants de la source de données, de sorte que les clients ne sont pas inondés d'événements non pertinents. Une modification qui ne correspond plus au filtre est livrée comme la transition appropriée (par ex. une mise à jour qui fait sortir une ligne de l'ensemble filtré est exposée afin que le client puisse l'abandonner).

## Contrat de message

Tous les messages temps réel — les trames WebSocket et les événements SSE `data:` utilisent le format **identique** — sont une union discriminée indexée sur `type`.

| `type`              | Objet                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `change`            | Mutation `insert`/`update`/`delete` ; `record`/`oldRecord` utilisent la charge utile `{ id, fields }`    |
| `conflict`          | Une modification concurrente a écrasé un changement optimiste en attente (déclenche le toast de conflit) |
| `heartbeat`         | Maintien de connexion émis tous les `heartbeatIntervalMs`                                                |
| `subscribed`        | Confirmation de handshake ; renvoie les `filter`/`fields`/`subscriptionId` résolus                       |
| `unsubscribed`      | Confirmation de désabonnement                                                                            |
| `join` / `leave`    | Un utilisateur a ouvert/quitté une page `presence: true` (délimité par `pagePath`)                       |
| `presence-sync`     | Instantané complet de présence envoyé une fois à la connexion                                            |
| `connection-status` | Connectivité du transport (`connected` / `reconnecting`)                                                 |

La charge utile `record` de `change` reflète l'enveloppe `{ id, fields }` de l'API des enregistrements, de sorte qu'un client peut appliquer un événement à un cache lié aux données sans aucune traduction de forme. Les `fields` sont déjà filtrés selon les permissions de champ.

:::callout
**Constantes de transport figées.** Le client et le serveur partagent `REALTIME_TRANSPORT_CONFIG` : recul de reconnexion `[1000, 2000, 4000, 8000]` ms, délai de reconnexion maximal `30000` ms, battement de cœur `30000` ms, maximum `10` connexions par utilisateur, délai d'inactivité `300000` ms, délai d'obsolescence de présence `60000` ms, maximum `50` entrées de présence par page.
:::

## Conscience de présence

Lorsqu'une page définit `presence: true`, le serveur diffuse des messages `join`/`leave`/`presence-sync` afin que les équipes puissent voir qui d'autre consulte la même page ou table — réduisant les conflits accidentels. La présence est délimitée par `pagePath`.

## Résolution de conflit et verrouillage optimiste

Le temps réel pilote un flux d'interface optimiste : le client applique sa modification immédiatement, puis se réconcilie avec le serveur. Si une modification concurrente a écrasé un changement optimiste en attente, le serveur émet un message `conflict` et la valeur canonique (le serveur l'emporte) prévaut.

Un `PATCH` d'enregistrement peut porter un jeton `updatedAt` de premier niveau. Lorsqu'il est présent, le serveur rejette une écriture obsolète avec `409 Conflict`. Les tables qui y participent déclarent un champ système `updated-at` afin que la colonne soit automatiquement incrémentée à chaque écriture — voir [CRUD et upsert](records-crud).

## Gestion de la connexion

Le client se reconnecte automatiquement avec le recul configuré, envoie/attend des battements de cœur et se replie sur SSE lorsque le WebSocket n'est pas disponible — de sorte que les fonctionnalités temps réel fonctionnent de manière fiable dans diverses conditions réseau.

## Abonnement programmatique

Les clients externes ouvrent `/api/tables/:tableSlug/subscribe` (ou le `/api/realtime/subscribe` global) et envoient un handshake nommant la `table` (et, en option, `subscriptionId`, `filter`, `fields`). Le serveur répond par une confirmation `subscribed`, puis diffuse les événements `change` ; un désabonnement produit une confirmation `unsubscribed`.

## Pages associées

- [CRUD et upsert](records-crud) — le contrat de verrouillage optimiste `updatedAt`
- [Filtrage, tri et pagination](records-filtering-sorting) — le filtre/tri qui délimite un abonnement
- [Vue d'ensemble des enregistrements](records-overview) — l'enveloppe `{ id, fields }` que le flux reflète
- [Vue d'ensemble des pages](pages-overview) — composants liés aux données et configuration de `dataSource`

# Import et export des enregistrements

Sovrium déplace des données en masse vers et depuis les tables de trois manières : **import CSV** (téléverser un fichier pour créer des enregistrements en masse), **export** (télécharger la vue courante en CSV ou JSON) et **presse-papiers** (copier/coller des lignes entre une table de données et un tableur). L'import et l'export sont un comportement natif intégré sur chaque table — aucune configuration requise.

:::callout
**Statut : planifié.** Les points de terminaison d'import/export CSV ci-dessous constituent une surface conçue mais non encore livrée (les user stories d'import/export sont `Not Started`). Le copier/coller du presse-papiers repose sur les points de terminaison [batch](records-batch) et [list](records-filtering-sorting) existants. Cette page documente l'API prévue ; les formes concrètes de requête/réponse seront finalisées lors de l'implémentation.
:::

## Import CSV

Téléversez un fichier CSV pour charger des enregistrements en masse, avec mappage colonne-vers-champ, gestion configurable des doublons et rapport d'erreurs par ligne en cas d'échecs partiels.

```
POST /api/tables/:tableId/import
Content-Type: multipart/form-data

Body:
  file              (CSV file)
  mapping           (JSON: { "csvColumn": "tableField" })
  duplicateStrategy ("skip" | "overwrite" | "create")
  uniqueField       (field used to detect duplicates)
```

La réponse résume le résultat et signale les erreurs par ligne sans faire échouer tout l'import :

```json
{
  "imported": 120,
  "skipped": 4,
  "updated": 11,
  "failed": 2,
  "errors": [
    { "row": 17, "field": "email", "error": "Invalid email format" },
    { "row": 92, "field": "amount", "error": "Expected a number" }
  ]
}
```

| Concept                        | Comportement                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| Mappage de colonnes            | `mapping` associe chaque colonne CSV à un champ de table ; les colonnes non mappées sont ignorées |
| `duplicateStrategy: skip`      | Ignorer les lignes dont le `uniqueField` existe déjà                                              |
| `duplicateStrategy: overwrite` | Mettre à jour l'enregistrement correspondant existant                                             |
| `duplicateStrategy: create`    | Toujours insérer un nouvel enregistrement                                                         |
| Échec partiel                  | Les lignes valides sont importées ; les lignes invalides sont signalées dans `errors`             |

Les enregistrements importés passent la même [validation](table-validation) de type de champ et les mêmes [permissions](table-permissions) au niveau des champs qu'une création normale.

## Export

Exportez la vue courante d'une table — toutes les lignes visibles, une sélection choisie à la main, ou les mêmes données au format JSON pour l'outillage développeur.

```
GET /api/tables/:tableId/export?format=csv&viewId=2&filters=JSON&fields=id,name,status
GET /api/tables/:tableId/export?format=json&fields=id,name,status
GET /api/tables/:tableId/export?format=csv&recordIds=1,2,3&fields=id,name,status
```

La réponse diffuse le fichier avec une disposition de pièce jointe :

```
Content-Type: text/csv            (or application/json)
Content-Disposition: attachment; filename="orders.csv"
```

| Paramètre   | Description                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `format`    | `csv` (défaut) ou `json`                                                                         |
| `viewId`    | Exporter les lignes d'une [vue](table-views) enregistrée                                         |
| `filters`   | Expression de filtre JSON (même grammaire que le [filtrage de liste](records-filtering-sorting)) |
| `fields`    | Colonnes à inclure séparées par des virgules                                                     |
| `recordIds` | Exporter uniquement les ID d'enregistrements nommés (une sélection choisie à la main)            |

L'export respecte les permissions de lecture au niveau des champs — les colonnes que l'appelant ne peut pas lire sont omises du fichier.

## Presse-papiers

Le composant table de données prend en charge le copier/coller de style tableur, construit sur les points de terminaison standard des enregistrements.

| Action            | Comportement                                                                                         | Point de terminaison sous-jacent          |
| ----------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Coller des lignes | Coller des données séparées par des tabulations depuis Excel/Google Sheets dans une table de données | `POST /api/tables/:tableId/records/batch` |
| Aperçu du collage | Prévisualiser les données collées avec mappage de colonnes avant validation                          | (côté client, puis création en lot)       |
| Copier des lignes | Sélectionner des lignes et les copier en valeurs séparées par des tabulations dans le presse-papiers | `GET /api/tables/:tableId/records`        |

Le collage associe les colonnes séparées par des tabulations aux champs de table (avec une étape d'aperçu/mappage pour que l'utilisateur puisse confirmer avant l'écriture), puis valide via une seule [création en lot](records-batch) — gardant l'opération atomique. La copie sérialise les colonnes visibles des lignes sélectionnées en TSV.

## Pages associées

- [Opérations en lot](records-batch) — le chemin d'écriture en masse atomique utilisé par le collage du presse-papiers
- [Filtrage, tri et pagination](records-filtering-sorting) — la grammaire de filtre/champs que l'export réutilise
- [Vues de table](table-views) — exporter une vue enregistrée par `viewId`
- [Validation de table](table-validation) — les lignes importées passent la validation de type de champ
- [Permissions de table](table-permissions) — les permissions de lecture/écriture au niveau des champs régulent l'import et l'export

# Personnalisation des données à l'exécution

Les développeurs déclarent le modèle de données et les pages ; les **utilisateurs finaux** façonnent la manière dont ils voient les données. Sovrium offre à chaque vue liée aux données un ensemble de comportements de personnalisation à l'exécution — filtrage, tri, regroupement, visibilité des colonnes, vues enregistrées et import/export CSV — afin que les utilisateurs puissent adapter leur espace de travail sans qu'un développeur modifie la configuration.

Ces comportements sont des **fonctionnalités natives de la plateforme**, et non des propriétés du schéma. Dès que vous affichez un [`data-table`](/fr/data-components) sur une table, la surface de personnalisation à l'exécution l'accompagne. Il n'y a rien à activer dans `app.yaml` au-delà du composant lui-même ; les options de la barre d'outils contrôlent quels contrôles sont exposés.

:::callout
**Deux couches de vues.** Les développeurs définissent des _vues de configuration_ sur le tableau `views` d'une table ([Vues](/fr/table-views)) — les points de départ nommés et soignés. Les utilisateurs finaux superposent leurs propres _vues à l'exécution_, enregistrées par utilisateur. Les deux coexistent : un utilisateur peut partir d'une vue développeur et l'affiner sans toucher à la configuration.
:::

## Vues à l'exécution

Lorsqu'un tableau de données est affiché, les utilisateurs peuvent ajuster l'ensemble des résultats en direct :

| Capacité                | Ce que l'utilisateur peut faire                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Filtrer                 | Construire des conditions de filtre dans la barre d'outils ; elles s'empilent sur le filtre de base du développeur. |
| Trier                   | Réordonner par une ou plusieurs colonnes, croissant/décroissant.                                                    |
| Grouper                 | Regrouper les lignes par valeur de champ en sections repliables.                                                    |
| Visibilité des colonnes | Afficher/masquer des colonnes via un bouton (exposé avec `toolbar: { columnVisibility: true }`).                    |
| Vues enregistrées       | Enregistrer le filtre + tri + sélection de champs courants comme une vue nommée et réutilisable.                    |
| Partager                | Partager une vue enregistrée avec d'autres utilisateurs.                                                            |

Les filtres et tris à l'exécution sont appliqués via la même couche de requête de l'API Records décrite dans [Filtrage et tri](/fr/records-filtering-sorting) — l'interface compose les paramètres `filter`, `sort`, `fields` et `groupBy` que le serveur comprend déjà. Une vue enregistrée conserve cette composition sous un identifiant stable afin de pouvoir être réappliquée d'un seul clic.

Le point d'entrée côté développeur est le composant `data-table` et ses propriétés `view`, `filter`, `sort`, `toolbar` et `groupBy` :

```yaml
components:
  - type: data-table
    dataSource:
      table: contacts
    view: active-customers # vue de départ optionnelle définie par le développeur
    toolbar:
      columnVisibility: true # exposer le bouton de visibilité des colonnes
```

Voir [Composants de données → data-table](/fr/data-components) pour la référence complète des propriétés et [Vues](/fr/table-views) pour les vues de configuration définies par le développeur.

## Import et export CSV

Les utilisateurs peuvent déplacer des données tabulaires vers et depuis une table sans quitter la page :

- **Exporter** la table entière ou seulement les lignes sélectionnées vers un fichier CSV.
- **Importer** un CSV via un assistant de correspondance qui apparie les colonnes du tableur aux champs de la table.

L'import et l'export respectent les mêmes permissions au niveau des champs que le reste de l'API Records — un utilisateur n'exporte que les champs qu'il peut lire et n'importe que dans les champs qu'il peut écrire. Les chemins d'API sous-jacents sont décrits dans [Import et export](/fr/records-import-export).

## Opérations du presse-papiers

Les tableaux de données prennent en charge des interactions de presse-papiers à la manière d'un tableur : copier une ou plusieurs lignes et les coller — y compris coller des lignes copiées depuis un tableur externe — avec un aperçu de collage avant que la modification ne soit validée. Les modifications en masse ressemblent à un travail dans un tableur tout en exécutant chaque écriture via l'API Records soumise aux permissions.

## Les permissions s'appliquent toujours

La personnalisation à l'exécution n'élargit jamais l'accès. Chaque vue à l'exécution, export, import et collage du presse-papiers passe par les permissions RBAC et au niveau des champs de la table. Un utilisateur qui personnalise son espace de travail ne peut filtrer, lire, écrire et partager que les données auxquelles il est déjà autorisé — et l'accès non autorisé à un enregistrement renvoie `404` (anti-énumération), exactement comme décrit dans [Vue d'ensemble des enregistrements](/fr/records-overview).

## Pages associées

- [Composants de données](/fr/data-components) — le `data-table` et les autres composants qui exposent la personnalisation à l'exécution.
- [Vues](/fr/table-views) — les vues de configuration définies par le développeur sur lesquelles s'appuient les vues à l'exécution.
- [Filtrage et tri](/fr/records-filtering-sorting) — la couche de requête de l'API Records derrière les filtres et tris à l'exécution.
- [Import et export](/fr/records-import-export) — l'API d'import/export CSV.
- [Vue d'ensemble des enregistrements](/fr/records-overview) — les permissions et la règle d'anti-énumération `404` que la personnalisation à l'exécution respecte.

# Présentation des pages

Les pages sont rendues côté serveur (SSR) à l'aide d'un arbre de composants déclaratif. Chaque page déclare un `name`, un `path`, des métadonnées SEO `meta` optionnelles et un tableau `components` de composants imbriqués. Les pages affichent les enregistrements de vos tables, hébergent des formulaires qui y écrivent, intègrent des îlots interactifs et exposent du contenu public — le tout à partir de la configuration, sans React personnalisé requis.

Une page nécessite au minimum un `name` et un `path`. Tout le reste — métadonnées, contrôle d'accès, scripts, routes de collection dynamiques, contenu markdown, transitions de vue et toasts par page — est optionnel et superposé.

```yaml
pages:
  - name: Home
    path: /
    meta:
      title: Welcome
      description: The fastest way to ship internal tools.
    components:
      - type: hero
        content: Build apps from config
      - type: container
        children:
          - { type: text, content: 'Get started in minutes.' }
```

## Propriétés de page

Chaque entrée du tableau `pages` accepte les propriétés suivantes.

| Propriété        | Description                                                                                                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Identifiant unique optionnel de la page. Généré automatiquement s'il est omis.                                                                                                          |
| `name`           | Nom de page lisible (utilisé dans la navigation et les listes d'administration).                                                                                                        |
| `path`           | Route URL. Statique (`/about`), racine (`/`), ou dynamique avec un segment `:param` (`/blog/:slug`). Voir [Routage](#routage).                                                          |
| `meta`           | Métadonnées SEO et d'en-tête de document : titre, description, Open Graph, cartes Twitter, favicons, données structurées. Voir [SEO et métadonnées](/fr/seo-meta).                      |
| `components`     | Tableau de définitions de composants formant l'arbre de rendu de la page. Voir [le modèle de composants](#le-modèle-de-composants).                                                     |
| `access`         | Contrôle d'accès : `'all'` (public), `'authenticated'`, un tableau de rôles `['admin']`, ou `{ require, redirectTo }`. Par défaut `'all'`.                                              |
| `collection`     | Configuration de modèle qui génère une route par enregistrement de table (pages dynamiques). Voir [Pages de collection](#pages-de-collection).                                          |
| `markdown`       | Rend tout le corps de la page à partir d'un fichier markdown ou d'une chaîne inline, avec options de mise en page et de table des matières. Voir [Pages markdown](#pages-markdown).     |
| `source`         | Source de contenu basée sur fichier (`source.file`) pour un composant `content` — charge le markdown depuis le disque avec frontmatter. Mutuellement exclusif avec `content`.           |
| `layout`         | Sections de mise en page nommées (p. ex. une `sidebar` liée à des données) entourant le corps de la page. Voir [Mises en page et barres latérales](#mises-en-page-et-barres-latérales). |
| `scripts`        | Scripts côté client, indicateurs de fonctionnalités, dépendances externes et données de config injectés dans la page. Voir [Interactivité et scripts](/fr/interactivity-scripts).       |
| `vars`           | Variables à portée de page (paires `key`/`value`) référençables via `$vars.*` dans les modèles de composants.                                                                           |
| `toasts`         | Configuration des notifications toast au niveau de la page (position, durée par défaut).                                                                                                |
| `viewTransition` | Animation de navigation de page : `fade`, `slide` (avec `direction`), ou `none`, plus `duration`.                                                                                       |
| `sitemap`        | Entrée de sitemap par page (priorité, fréquence de modification) ou `false` pour exclure la page du sitemap.                                                                            |
| `rss`            | Active un flux RSS pour une page de collection — `true` pour les valeurs par défaut, ou `{ limit }` pour limiter le nombre d'éléments.                                                  |

```yaml
pages:
  - name: About
    path: /about
    access: all
    meta: { title: 'About Us' }
    viewTransition: { type: fade, duration: 200 }
    components:
      - { type: text, tag: h1, content: 'About' }
```

## Routage

La propriété `path` déclare l'URL où une page est servie.

| Forme de chemin     | Exemple       | Description                                                                                    |
| ------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| Racine              | `/`           | La page d'accueil.                                                                             |
| Statique            | `/about`      | Une route fixe.                                                                                |
| Statique imbriquée  | `/checkout`   | Un nombre quelconque de segments statiques.                                                    |
| Dynamique           | `/blog/:slug` | Un segment `:param` capture une valeur disponible pour la page en tant que paramètre de route. |
| Id d'enregistrement | `/tasks/$id`  | Les routes de détail dynamiques résolvent l'enregistrement correspondant dans `$record.*`.     |

Les routes dynamiques sont le plus souvent associées à un bloc `collection` afin qu'une seule définition de page génère une route par enregistrement. Voir [Pages de collection](#pages-de-collection).

## Le modèle de composants

Le tableau `components` d'une page est un arbre. Chaque composant a un `type` (parmi ~80 types de composants intégrés) et un ensemble de propriétés. Les composants se composent à travers un système de modules partagé, de sorte que les mêmes propriétés transversales sont disponibles presque partout :

| Propriété partagée | Disponible sur                     | Description                                                                                                                                     |
| ------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `props`            | Presque tous les composants        | Ensemble clé-valeur d'attributs de style/config rendus comme attributs HTML (p. ex. `className`, `variant`).                                    |
| `content`          | Composants de contenu/mise en page | Texte ou markdown inline ; prend en charge la substitution `$record.*`, `$vars.*` et `$t:key` (traduction).                                     |
| `children`         | Composants de type conteneur       | Définitions de composants enfants imbriqués.                                                                                                    |
| `dataSource`       | Composants liés à des données      | Lie le composant à une table (filtre, tri, pagination, mode unique/recherche). Voir [Liaison de données](#liaison-de-données).                  |
| `visibility`       | La plupart des composants          | Affichage conditionnel basé sur l'état d'authentification — rendu côté serveur, masqué côté client lorsque les conditions ne sont pas remplies. |
| `responsive`       | La plupart des composants          | Surcharges par point de rupture pour un comportement responsive.                                                                                |
| `interactions`     | Composants interactifs             | Actions de clic, effets de survol et animations d'entrée. Voir [Interactivité et scripts](/fr/interactivity-scripts).                           |
| `action`           | Composants formulaire/bouton       | Comportement à exécuter lors d'une interaction — `crud`, `auth`, `navigate`, `automation`, avec gestionnaires `onSuccess`/`onError`.            |
| `i18n`             | Composants de contenu              | Variantes de contenu localisées par langue.                                                                                                     |

:::callout
**Substitution de variables.** Les valeurs de `content` et `props` des composants résolvent trois familles de références au moment du rendu : `$record.<field>` (enregistrement de la source de données courante), `$vars.<key>` / `$currentUser.<path>` (contexte de page et de session), et `$t:key` (clés de traduction, avec repli). La source `markdown` au niveau de la page expose en plus `$frontmatter.*`.
:::

Les composants sont regroupés en catégories, chacune documentée sur sa propre page :

| Catégorie                                             | Exemples                                                                                         |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [Mise en page](/fr/layout-components)                 | hero, container, flex, grid, responsiveGrid, card, sidebar, modal, tab-panel                     |
| [Contenu](/fr/content-components)                     | text, code, toc, accordion, blockquote, alert, custom-html                                       |
| [Données](/fr/data-components)                        | data-table, list, gallery, kanban, calendar, chart, kpi, timeline                                |
| [Contrôles de formulaire](/fr/form-controls)          | input, textarea, select, checkbox, radio, switch, slider, date-picker, file-upload, number-input |
| [Superpositions](/fr/overlay-components)              | dialog, drawer, popover, tooltip, hover-card, alert-dialog, toast, progress, skeleton            |
| [Navigation](/fr/navigation-components)               | navigation-menu, dropdown-menu, breadcrumb, tabs, pagination, toggle, button-group, menubar      |
| [Média](/fr/media-components)                         | image, icon, video, audio, iframe, carousel, aspect-ratio                                        |
| [Affichage](/fr/display-components)                   | static-table, command, empty-state, resizable, scroll-area, speech-bubble, status-indicator      |
| [Retour d'information](/fr/feedback-components)       | progress, spinner, skeleton                                                                      |
| [Interactif](/fr/interactive-components)              | button, link, alert, badge, button-group                                                         |
| [Spécialité](/fr/specialty-components)                | wizard, reorderable-list, language-switcher, comments, ai-chat                                   |
| [Social](/fr/social-components)                       | comments, commentCount, ai-chat, sharing                                                         |
| [SEO et métadonnées](/fr/seo-meta)                    | title, description, Open Graph, cartes Twitter, JSON-LD, favicons                                |
| [Interactivité et scripts](/fr/interactivity-scripts) | scripts, interactions, auto-save, custom-html                                                    |

## Liaison de données

Liez n'importe quel composant de données (ou conteneur) à une table avec `dataSource`. Les enregistrements liés exposent leurs champs aux descendants via des références `$record.<field>`.

| Propriété `dataSource` | Description                                                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `table`                | Nom de la table à lier (validé contre `app.tables`).                                                                                  |
| `fields`               | Champs spécifiques à récupérer (omettre pour tout récupérer).                                                                         |
| `filter`               | Tableau de conditions `{ field, operator, value }` combinées par AND. Opérateurs : `eq`, `neq`, `contains`, `gt`, `lt`, `gte`, `lte`. |
| `sort`                 | Tableau de règles `{ field, direction }` appliquées dans l'ordre (primaire, secondaire).                                              |
| `pagination`           | `{ pageSize, style }` — `style: numbered` rend une navigation par pages ; `style: loadMore` rend un bouton Charger plus.              |
| `mode`                 | `single` résout un seul enregistrement par un `param` de route ; `search` filtre sur `searchFields` avec `debounce` et `maxResults`.  |
| `id`                   | Identifiant pour les références de source de données entre composants.                                                                |

```yaml
- type: data-table
  dataSource:
    table: tasks
    filter:
      - { field: status, operator: neq, value: archived }
    sort:
      - { field: created_at, direction: desc }
    pagination: { pageSize: 25, style: numbered }
```

:::callout
**Cadrage par utilisateur courant.** `$currentUser.*` se résout par requête durant le SSR (jamais mis en cache entre utilisateurs) : `$currentUser.id`, `$currentUser.role`, `$currentUser.email`, `$currentUser.isUnrestricted` (contournement administrateur global) et `$currentUser.assignments.<table>` (ids d'enregistrements aplatis auxquels l'utilisateur est affecté). Les pages utilisant `$currentUser` renvoient `401` lorsqu'elles sont consultées sans authentification.
:::

## Pages de collection

Un bloc `collection` transforme une seule définition de page en une route par enregistrement de table. Le `path` de la page doit inclure un segment dynamique `:param` correspondant à `slugField`.

| Propriété `collection` | Description                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `table`                | Nom de la table à partir de laquelle générer les pages de collection (doit exister dans `app.tables`).  |
| `slugField`            | Champ dont la valeur devient le paramètre URL (p. ex. `slug`, `id`).                                    |
| `filter`               | Conditions `{ field, operator, value }` optionnelles limitant quels enregistrements génèrent des pages. |

```yaml
pages:
  - name: Blog Post
    path: /blog/:slug
    collection:
      table: posts
      slugField: slug
      filter:
        - { field: published, operator: eq, value: true }
    rss: { limit: 20 }
    components:
      - { type: text, tag: h1, content: '$record.title' }
      - { type: text, content: '$record.body', props: { format: markdown } }
```

Une requête vers `/blog/123` qui ne correspond à aucun enregistrement renvoie un `404`.

## Pages markdown

Rendez une page entière à partir de markdown — soit inline, soit à partir d'un fichier — avec frontmatter, mise en page et table des matières générée automatiquement.

| Propriété `markdown` | Description                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `content`            | Chaîne markdown inline.                                                                                                              |
| `file`               | Chemin vers un fichier markdown (p. ex. `content/docs.md`), résolu depuis la racine du projet. Mutuellement exclusif avec `content`. |
| `layout`             | Style d'encadrement : `prose` (défaut), `docs`, `full`, ou `none`.                                                                   |
| `toc`                | Config de table des matières — `true` pour les valeurs par défaut, ou `{ maxDepth, position }` (`inline` ou `sidebar`).              |

Le frontmatter YAML (entre les délimiteurs `---`) est analysé et exposé comme `$frontmatter.*` dans `meta` et les propriétés frères. Le HTML markdown est assaini pour prévenir les attaques XSS (cohérent avec les composants de contenu `text`/`alert`).

```yaml
pages:
  - name: Docs Home
    path: /docs
    markdown:
      file: content/docs/home.md
      layout: docs
      toc: { maxDepth: 3, position: sidebar }
```

Pour la collection `contentDir` (une page par fichier markdown dans un répertoire, avec une barre latérale dérivée), utilisez un composant `content` avec une source `contentDir` :

| Propriété `contentDir` | Description                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `directory`            | Répertoire contenant les fichiers de contenu markdown.                                 |
| `slugFrom`             | Dérive le slug URL depuis `filename` ou `filepath`.                                    |
| `include`              | Motif glob pour filtrer les fichiers (p. ex. `*.md`).                                  |
| `sort`                 | `{ field, order }` — trie par un champ de frontmatter (p. ex. `date`, `desc`).         |
| `filter`               | Conditions de filtre sur les champs de frontmatter.                                    |
| `nav`                  | Config de barre latérale dérivée de la collection : `{ enabled, groupBy, labelFrom }`. |

## Mises en page et barres latérales

La propriété `layout` encadre le corps de la page dans des sections nommées. La plus courante est une `sidebar` liée à des données rendue à l'intérieur du `<aside>` de la page.

| Propriété de section de barre latérale | Description                                                                                   |
| -------------------------------------- | --------------------------------------------------------------------------------------------- |
| `dataSource`                           | Lie les entrées à une table avec `{ table, filter, sort }`.                                   |
| `label`                                | Expression de libellé par enregistrement (prend en charge `$record.<field>`).                 |
| `href`                                 | Href d'ancre par enregistrement (prend en charge `$record.<field>`).                          |
| `archivedField`                        | Champ dont la valeur vraie masque une entrée de la barre latérale.                            |
| `activeIndicator`                      | Met en évidence l'entrée correspondant au cadre actif (p. ex. cookie de sélecteur de tenant). |

Une barre latérale cadrée liée à `$currentUser.assignments.<table>` rend une entrée par enregistrement affecté ; un administrateur global (`isUnrestricted=true`) voit tous les enregistrements.

## Contrôle d'accès

La propriété `access` protège une page :

| Forme                                                | Signification                                                           |
| ---------------------------------------------------- | ----------------------------------------------------------------------- |
| `'all'`                                              | Tout le monde, y compris les visiteurs non authentifiés (défaut).       |
| `'authenticated'`                                    | Tout utilisateur connecté.                                              |
| `['admin', 'editor']`                                | Noms de rôles spécifiques.                                              |
| `{ require: 'authenticated', redirectTo: '/login' }` | Redirige les utilisateurs non autorisés au lieu de renvoyer une erreur. |

## Pages connexes

- [Composants de mise en page](/fr/layout-components) — blocs de construction structurels.
- [Composants de contenu](/fr/content-components) — texte, code, encarts, accordéons.
- [Composants de données](/fr/data-components) — tables, listes, graphiques, KPI liés à vos données.
- [Contrôles de formulaire](/fr/form-controls) — entrées, sélecteurs, sélecteurs de date, bascules.
- [SEO et métadonnées](/fr/seo-meta) — en-tête de document, cartes sociales, données structurées.
- [Interactivité et scripts](/fr/interactivity-scripts) — actions, animations, sauvegarde automatique.
- [Présentation des tables](/fr/tables-overview) — les modèles de données que les pages rendent.
- [Formulaires](/fr/forms-overview) — définitions de formulaires autonomes.
- [Recherche](/fr/search-overview) — configuration de recherche plein texte et publique.
- [Thème](/fr/theme) — jetons de design consommés par le style des composants.

# Composants de mise en page

Les composants de mise en page organisent la page. Ils définissent le squelette visuel — bandeaux pleine largeur, conteneurs centrés, pistes flex et grid, cartes, barres latérales et fenêtres modales — et hébergent d'autres composants en tant que `children`. Chaque composant de mise en page accepte l'ensemble partagé `props` (rendu comme attributs HTML tels que `className`), ainsi que les modules `responsive`, `visibility` et `i18n`. Les composants de type conteneur acceptent en plus `children`.

```yaml
components:
  - type: hero
    content: Ship internal tools from config
    props: { className: 'bg-primary text-white py-24' }
  - type: container
    props: { className: 'max-w-4xl mx-auto px-6' }
    children:
      - type: grid
        props: { className: 'grid-cols-3 gap-6' }
        children:
          - { type: card, children: [{ type: text, content: 'Fast' }] }
```

## `hero`

Une section de bandeau pleine largeur, généralement le premier bloc d'une page d'accueil. Rend `content` comme titre principal et accepte `children` pour les appels à l'action et le contenu de support.

| Propriété      | Description                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------- |
| `content`      | Texte du titre principal (prend en charge la substitution `$record.*`, `$vars.*`, `$t:key`).   |
| `children`     | Composants imbriqués rendus à l'intérieur du hero (sous-titres, boutons, médias).              |
| `props`        | Attributs HTML — généralement `className` pour l'arrière-plan, le rembourrage et l'alignement. |
| `interactions` | Comportements de clic/survol/entrée (p. ex. une animation d'entrée au chargement).             |
| `responsive`   | Surcharges par point de rupture.                                                               |
| `visibility`   | Affichage conditionnel basé sur l'état d'authentification.                                     |

## `container`

Un encadreur générique de niveau bloc. Utilisez-le pour contraindre la largeur, appliquer du rembourrage et regrouper les enfants.

| Propriété  | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `element`  | Élément HTML à rendre. Par défaut `div` (p. ex. `section`, `main`, `article`). |
| `children` | Définitions de composants imbriqués.                                           |
| `content`  | Contenu inline optionnel rendu lorsqu'aucun `children` n'est présent.          |
| `props`    | Attributs HTML (p. ex. `className`).                                           |

## `flex`

Un conteneur flexbox. Disposez les enfants en ligne ou en colonne avec espacement, alignement et retour à la ligne contrôlés via les classes Tailwind dans `props.className`.

| Propriété    | Description                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `children`   | Composants imbriqués disposés le long de l'axe flex.                                                     |
| `props`      | Attributs HTML — définissez `className` sur `flex flex-row`/`flex-col`, `gap-*`, `items-*`, `justify-*`. |
| `responsive` | Surcharges de direction/alignement par point de rupture.                                                 |

## `grid`

Un conteneur CSS grid avec des pistes de colonnes fixes. Les enfants s'écoulent dans les cellules de la grille.

| Propriété  | Description                                                                             |
| ---------- | --------------------------------------------------------------------------------------- |
| `children` | Composants imbriqués placés dans les cellules de la grille.                             |
| `props`    | Attributs HTML — définissez `className` sur `grid grid-cols-*`, `gap-*`, `auto-rows-*`. |

## `responsiveGrid`

Une grille dont le nombre de colonnes s'adapte par point de rupture. Préférez celle-ci à `grid` lorsque vous souhaitez des colonnes responsives déclaratives sans écrire à la main les classes de point de rupture.

| Propriété    | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| `children`   | Composants imbriqués placés dans la grille responsive.            |
| `responsive` | Nombre de colonnes par point de rupture (mobile, sm, md, lg, xl). |
| `props`      | Attributs HTML (p. ex. `gap-*`).                                  |

## `card`

Une surface bordée et rembourrée pour regrouper du contenu connexe. Couramment utilisée dans les grilles et les galeries.

| Propriété      | Description                                                                |
| -------------- | -------------------------------------------------------------------------- |
| `children`     | Composants imbriqués rendus à l'intérieur du corps de la carte.            |
| `content`      | Contenu inline optionnel lorsqu'aucun `children` n'est fourni.             |
| `props`        | Attributs HTML — `className` pour l'élévation, le rayon et le rembourrage. |
| `interactions` | Effets de clic/survol (p. ex. élévation au survol, navigation au clic).    |

## `sidebar`

Un panneau de navigation vertical, généralement associé à une région principale `container` pour former une mise en page de type app-shell. Peut être composée statiquement à partir de `children` ou liée à des données via la config `layout.sidebar` de la page (voir [Présentation des pages → Mises en page et barres latérales](/fr/pages-overview#mises-en-page-et-barres-latérales)).

| Propriété    | Description                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------- |
| `children`   | Éléments et sections de navigation rendus comme menu vertical.                              |
| `props`      | Attributs HTML — `className` pour la largeur et le positionnement (panneau à largeur fixe). |
| `visibility` | Affichage conditionnel (p. ex. masquer pour les utilisateurs non authentifiés).             |

## `modal`

Une superposition de dialogue ouverte par un déclencheur d'interaction. Le composant de mise en page `modal` contient le corps du dialogue ; ouvrez-le via `interactions.onClick` d'un bouton avec `modalId`. (Pour les superpositions de type confirmation, voir [`dialog`/`alert-dialog`](/fr/overlay-components).)

| Propriété  | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| `id`       | Identifiant ciblé par un déclencheur d'ouverture (`onClick.modalId`).   |
| `children` | Composants imbriqués rendus à l'intérieur du panneau modal.             |
| `props`    | Attributs HTML (p. ex. `className` pour le dimensionnement du panneau). |

Cliquer sur l'arrière-plan ou appuyer sur Échap ferme la fenêtre modale ; le focus est piégé dans la fenêtre modale tant qu'elle est ouverte.

## `tab-panel`

Un panneau unique au sein d'un conteneur `tabs`. Chaque panneau a un libellé de déclencheur et son propre contenu/enfants. Voir [`tabs`](/fr/navigation-components#tabs) pour le conteneur.

| Propriété  | Description                                                                         |
| ---------- | ----------------------------------------------------------------------------------- |
| `label`    | Texte affiché sur le bouton déclencheur de l'onglet.                                |
| `content`  | Contenu textuel inline du panneau (omettre lorsque le panneau rend des `children`). |
| `children` | Composants imbriqués rendus à l'intérieur du panneau.                               |

## `divider`

Un trait horizontal séparant des sections de contenu.

| Propriété     | Description                                          |
| ------------- | ---------------------------------------------------- |
| `props.style` | Style de ligne : `solid`, `dashed`, ou `dotted`.     |
| `props.label` | Texte centré rendu dans la ligne du séparateur.      |
| `props`       | Attributs HTML supplémentaires (p. ex. `className`). |

## `spacer`

Espace blanc vertical entre les blocs.

| Propriété    | Description                                          |
| ------------ | ---------------------------------------------------- |
| `props.size` | Préréglage d'espacement : `sm`, `md`, `lg`, ou `xl`. |
| `props`      | Attributs HTML supplémentaires (p. ex. `className`). |

```yaml
components:
  - { type: text, tag: h2, content: 'Section A' }
  - { type: spacer, props: { size: lg } }
  - { type: divider, props: { style: dashed, label: 'or' } }
  - { type: text, tag: h2, content: 'Section B' }
```

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — structure de page, routage et modèle de composants.
- [Composants de contenu](/fr/content-components) — texte, code, encarts, accordéons.
- [Composants de navigation](/fr/navigation-components) — onglets, fils d'Ariane, menus.
- [Composants de superposition](/fr/overlay-components) — dialogues, tiroirs, popovers.
- [Thème](/fr/theme) — jetons de design consommés par le style `className`.

# Composants de contenu

Les composants de contenu rendent du texte et de la prose. Ils couvrent le texte enrichi et le markdown, les blocs de code avec coloration syntaxique, les accordéons repliables, les encarts stylisés, les citations, une table des matières générée automatiquement et l'interface de recherche au niveau de la page. Tous les composants de contenu prennent en charge la substitution de variables dans leur `content` (`$record.*`, `$vars.*`, `$t:key`) et acceptent l'ensemble partagé `props`, ainsi que les modules `visibility`, `responsive` et `i18n`.

```yaml
components:
  - type: text
    tag: h1
    content: Getting Started
  - type: text
    content: '$record.body'
    props: { format: markdown }
  - type: alert
    props: { variant: info, dismissible: true }
    content: 'Heads up — this is a callout.'
```

## `text`

Le composant de contenu principal. Rend du texte inline, un élément sémantique (titre, paragraphe, citation) ou du markdown complet. Le même type `text` couvre les titres, paragraphes, blocs de code et citations via son `tag`/`props`.

| Propriété           | Description                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `content`           | Source texte ou markdown (prend en charge `$record.*`, `$vars.*`, `$t:key`).                                                |
| `tag`               | Élément sémantique : `h1`–`h6`, `p`, `span`, `blockquote`, `code`, etc.                                                     |
| `props.format`      | Définir sur `markdown` pour rendre `content` comme HTML assaini (titres, gras, italique, liens, images, listes imbriquées). |
| `props.language`    | Lorsque `tag: code`, la langue pour la coloration syntaxique.                                                               |
| `props.lineNumbers` | Lorsque `tag: code`, définir sur `true` pour afficher les numéros de ligne.                                                 |
| `props.cite`        | Lorsque `tag: blockquote`, l'URL de la source de citation.                                                                  |
| `props`             | Attributs HTML supplémentaires (p. ex. `className`).                                                                        |

La sortie markdown est assainie pour prévenir les attaques XSS (pas de balises `<script>` ni d'attributs gestionnaires d'événements). Les blocs de code incluent un bouton de copie vers le presse-papiers.

## `code`

Un bloc de code autonome (équivalent à `text` avec `tag: code`, exposé comme type propre pour plus de clarté).

| Propriété           | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| `content`           | La source du code.                                                  |
| `props.language`    | Langue pour la coloration syntaxique (p. ex. `ts`, `yaml`, `bash`). |
| `props.lineNumbers` | Afficher les numéros de ligne à côté du code.                       |
| `props`             | Attributs HTML supplémentaires.                                     |

## `toc`

Génère automatiquement une table des matières à partir de la hiérarchie de titres de la page. Cliquer sur un lien fait défiler en douceur jusqu'à l'ancre du titre ; la section active est mise en évidence selon la position de défilement.

| Propriété      | Description                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------- |
| `props.sticky` | Définir sur `true` pour garder la table des matières fixée à la fenêtre lors du défilement. |
| `props`        | Attributs HTML supplémentaires (p. ex. `className`).                                        |

## `accordion`

Sections de contenu repliables, chacune avec un déclencheur de résumé et un panneau de détail.

| Propriété           | Description                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `children`          | Éléments d'accordéon (chacun avec un libellé de résumé et un contenu de détail).                             |
| `props.mode`        | `single` replie les autres sections quand l'une s'ouvre ; `multiple` permet d'en ouvrir plusieurs à la fois. |
| `props.defaultOpen` | Définir sur `true` pour rendre une section développée au chargement de la page.                              |
| `props`             | Attributs HTML supplémentaires.                                                                              |

## `blockquote`

Un bloc de citation stylisé (équivalent à `text` avec `tag: blockquote`). Les citations imbriquées sont rendues avec une indentation croissante.

| Propriété    | Description                     |
| ------------ | ------------------------------- |
| `content`    | Le texte cité.                  |
| `props.cite` | URL de la source de citation.   |
| `props`      | Attributs HTML supplémentaires. |

## `alert`

Un bloc d'encart stylisé pour mettre en évidence des informations.

| Propriété           | Description                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `content`           | Le message d'alerte (prend en charge la substitution).                                                                             |
| `props.variant`     | Style visuel : `info`, `warning`, `error`, ou `success` — chacun sélectionne automatiquement une icône et une couleur appropriées. |
| `props.dismissible` | Définir sur `true` pour rendre un bouton de fermeture qui masque l'alerte.                                                         |
| `props`             | Attributs HTML supplémentaires.                                                                                                    |

## `searchInput`

Un contrôle de champ de recherche au niveau de la page qui pilote le filtrage côté client d'une liste ou d'une table liée. (La configuration du _moteur_ plein texte — indexation, poids, recherche publique — se trouve dans la section [Recherche](/fr/search-overview) ; ceci est le bloc de construction de l'interface.)

| Propriété           | Description                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `props.placeholder` | Texte indicatif affiché dans le champ de recherche.                                                                    |
| `props.debounceMs`  | Délai d'anti-rebond avant le déclenchement de la recherche (les résultats se mettent à jour en direct après le délai). |
| `props.minLength`   | Longueur minimale de requête avant la recherche (empêche les recherches vides/courtes).                                |
| `dataSource`        | Liaison optionnelle lorsque le champ filtre une source de données en mode `search`.                                    |

## `pageSearch`

Une expérience de recherche à portée de page composée d'un champ et d'une région de résultats, liée à une table consultable. À utiliser pour le filtrage d'enregistrements au sein de la page.

| Propriété           | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `dataSource`        | Liaison de table en mode `search` (`searchFields`, `debounce`, `maxResults`). |
| `props.placeholder` | Texte indicatif pour le champ de recherche.                                   |
| `children`          | Composants optionnels de modèle de résultat.                                  |

:::callout
**Contenu markdown vs. pages markdown.** Un composant `text` avec `props.format: markdown` rend un _fragment_ de markdown inline. Pour rendre une page _entière_ à partir d'un fichier markdown (avec frontmatter, mise en page et table des matières), utilisez la propriété `markdown` au niveau de la page — voir [Présentation des pages → Pages markdown](/fr/pages-overview#pages-markdown).
:::

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — structure de page et substitution de variables.
- [Composants de mise en page](/fr/layout-components) — conteneurs, grilles, cartes.
- [Composants média](/fr/media-components) — images, vidéo, icônes, intégrations.
- [Recherche](/fr/search-overview) — moteur de recherche plein texte et recherche publique.
- [Composants de recherche](/fr/search-components) — blocs de construction de l'interface de recherche (dans la section Recherche).
- [SEO et métadonnées](/fr/seo-meta) — en-tête de document et données structurées.

# Composants de données

Les composants de données rendent les enregistrements de vos tables. Chacun se lie à une table via le module partagé `dataSource` (`table`, `filter`, `sort`, `pagination`, `mode`) et rend les enregistrements correspondants sous forme de table, liste, galerie, tableau kanban, calendrier, graphique, KPI ou chronologie. Les champs d'enregistrement sont référencés avec `$record.<field>` dans les modèles. Voir [Présentation des pages → Liaison de données](/fr/pages-overview#liaison-de-données) pour le contrat `dataSource` complet.

```yaml
components:
  - type: data-table
    dataSource: { table: tasks, sort: [{ field: due_date, direction: asc }] }
    columns:
      - { field: title, sortable: true }
      - { field: status, format: badge }
      - { field: due_date, format: relative-date }
```

## `data-table`

Une table riche en fonctionnalités avec tri, filtrage, regroupement, sélection, actions groupées, résumés et édition en ligne.

| Propriété      | Description                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataSource`   | Liaison de table (filtre/tri appliqués côté serveur avec logique AND).                                                                                         |
| `view`         | Nom d'une [vue de table](/fr/table-views) enregistrée pour hériter des filtres, tris et champs visibles.                                                       |
| `columns`      | Définitions de colonnes (voir ci-dessous). Générées automatiquement à partir des champs de table si omises.                                                    |
| `filter`       | Conditions de filtre supplémentaires empilées par-dessus les filtres de vue.                                                                                   |
| `sort`         | Règles de tri par défaut (état initial, ou appliquées quand aucun tri de vue n'existe).                                                                        |
| `rowHeight`    | Préréglage de hauteur de ligne (défaut : `medium`).                                                                                                            |
| `striped`      | Couleurs de lignes alternées (défaut : `false`).                                                                                                               |
| `bordered`     | Afficher les bordures de cellules (défaut : `false`).                                                                                                          |
| `rowNumbers`   | Afficher une colonne de numéros de ligne (défaut : `false`).                                                                                                   |
| `emptyMessage` | Message affiché lorsqu'aucun enregistrement ne correspond.                                                                                                     |
| `toolbar`      | Contrôles de barre d'outils — p. ex. `{ columnVisibility: true }` pour afficher une bascule de visibilité de colonnes.                                         |
| `selection`    | Configuration de sélection de lignes (voir ci-dessous).                                                                                                        |
| `bulkActions`  | Actions disponibles lorsque des lignes sont sélectionnées (voir ci-dessous).                                                                                   |
| `groupBy`      | Configuration de regroupement de lignes (voir ci-dessous).                                                                                                     |
| `summary`      | Ligne de résumé avec calculs d'agrégats (voir ci-dessous).                                                                                                     |
| `autoSave`     | Comportement de sauvegarde de l'édition en ligne — voir [Interactivité et scripts → Sauvegarde automatique](/fr/interactivity-scripts#sauvegarde-automatique). |

### `columns`

Chaque entrée définit une colonne.

| Propriété           | Description                                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `field`             | Nom du champ de la table source de données.                                                                                   |
| `label`             | Remplacement du libellé d'en-tête (par défaut le nom d'affichage du champ).                                                   |
| `width`             | Largeur de colonne en pixels.                                                                                                 |
| `minWidth`          | Largeur minimale de colonne en pixels.                                                                                        |
| `align`             | Alignement du texte : `left` (défaut), `center`, `right`.                                                                     |
| `format`            | Remplacement du format d'affichage pour le rendu de cellule (p. ex. `badge`, `currency`, `relative-date`).                    |
| `pinned`            | Épingler la colonne au côté gauche de la table.                                                                               |
| `sortable`          | Autoriser le tri sur cette colonne (défaut : `true`).                                                                         |
| `filterable`        | Autoriser le filtrage sur cette colonne (défaut : `true`).                                                                    |
| `editable`          | Autoriser l'édition en ligne (par défaut les permissions de la table).                                                        |
| `hidden`            | Visibilité de la colonne (défaut : `true` = visible).                                                                         |
| `conditionalStyles` | Règles `{ when: { operator: value }, className }` appliquant des classes Tailwind quand une condition de cellule est remplie. |
| `actions`           | Boutons d'action (p. ex. modifier/supprimer) avec `label`, `icon` et un message de confirmation (prend en charge `{count}`).  |

### `selection`

| Propriété      | Description                                                                            |
| -------------- | -------------------------------------------------------------------------------------- |
| `mode`         | `none` (défaut), `single`, ou `multiple`.                                              |
| `showCheckbox` | Afficher une colonne de cases à cocher (défaut : `true` quand le mode est `multiple`). |

### `bulkActions`

| Propriété | Description                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `label`   | Libellé du bouton d'action groupée.                                                                     |
| `icon`    | Nom d'icône Lucide (p. ex. `truck`, `trash`).                                                           |
| `confirm` | Message du dialogue de confirmation ; prend en charge `{count}` pour le nombre de lignes sélectionnées. |
| `action`  | L'action invoquée sur les lignes sélectionnées.                                                         |

### `groupBy`

| Propriété   | Description                                      |
| ----------- | ------------------------------------------------ |
| `field`     | Champ par lequel regrouper les lignes.           |
| `direction` | Direction de tri des groupes (défaut : `asc`).   |
| `collapsed` | Démarrer les groupes repliés (défaut : `false`). |
| `hideEmpty` | Masquer les groupes vides (défaut : `false`).    |

### `summary`

| Propriété   | Description                                               |
| ----------- | --------------------------------------------------------- |
| `field`     | Champ sur lequel calculer le résumé.                      |
| `aggregate` | Fonction d'agrégat (`sum`, `avg`, `count`, `min`, `max`). |

## `list`

Une liste verticale d'enregistrements, chacun rendu à partir d'un modèle utilisant des références `$record.*`.

| Propriété           | Description                                                                    |
| ------------------- | ------------------------------------------------------------------------------ |
| `dataSource`        | Liaison de table.                                                              |
| `template.title`    | Texte principal (référence `$record.*`).                                       |
| `template.subtitle` | Texte secondaire.                                                              |
| `template.image`    | URL d'image (référence `$record.*`).                                           |
| `template.badge`    | Texte de badge.                                                                |
| `template.meta`     | Champs de métadonnées affichés dans le pied de l'élément (`field` + `format`). |
| `pagination`        | `button` (Charger plus) ou `infinite` (chargement au défilement).              |
| `highlightSearch`   | Surligner les termes de recherche correspondants (défaut : `false`).           |
| `divided`           | Afficher des séparateurs entre les éléments (défaut : `false`).                |
| `maxItems`          | Nombre maximal d'éléments à afficher.                                          |
| `emptyMessage`      | Message lorsqu'aucun résultat de recherche ne correspond.                      |

## `gallery`

Une grille de cartes responsive d'enregistrements.

| Propriété          | Description                                                                  |
| ------------------ | ---------------------------------------------------------------------------- |
| `dataSource`       | Liaison de table.                                                            |
| `gridColumns`      | Nombre de colonnes responsive par point de rupture (mobile, sm, md, lg, xl). |
| `card.image`       | URL d'image de couverture ou référence `$record.*`.                          |
| `card.aspectRatio` | Ratio d'aspect de la couverture (p. ex. `4:3`, `16:9`, `1:1`).               |
| `card.children`    | Composants enfants pour le corps de la carte.                                |
| `card.overlay`     | Composants rendus dans une superposition au survol de la carte.              |

## `kanban`

Un tableau glisser-déposer regroupant les enregistrements en colonnes par valeur de champ.

| Propriété          | Description                                                                   |
| ------------------ | ----------------------------------------------------------------------------- |
| `dataSource`       | Liaison de table.                                                             |
| `groupBy`          | Champ dont les valeurs deviennent les colonnes kanban.                        |
| `card.children`    | Composants enfants pour le corps de la carte.                                 |
| `card.image`       | URL d'image ou référence `$record.*` pour la couverture de la carte.          |
| `card.colorField`  | Champ dont les valeurs définissent la couleur d'arrière-plan de la carte.     |
| `card.footer`      | Champs de métadonnées affichés dans le pied de la carte (`field` + `format`). |
| `dragDrop.enabled` | Activer le glisser-déposer entre les colonnes (défaut : `true`).              |

## `calendar`

Un calendrier mois/semaine/jour d'enregistrements porteurs de dates.

| Propriété                  | Description                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------- |
| `dataSource`               | Liaison de table.                                                                                       |
| `mode`                     | Mode d'affichage : `month`, `week`, ou `day`.                                                           |
| `event`                    | Comment les enregistrements se mappent aux événements de calendrier (champs début/fin, titre, couleur). |
| `interaction.slotMinutes`  | Intervalle de créneau horaire en minutes pour les vues semaine/jour (défaut : 60).                      |
| `interaction.nowIndicator` | Afficher une ligne à l'heure actuelle dans les vues semaine/jour.                                       |

## `chart`

Une visualisation de données (barres, lignes, aires) calculée à partir d'enregistrements agrégés.

| Propriété         | Description                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `dataSource`      | Liaison de table.                                                                                                |
| `series`          | Une ou plusieurs séries `{ field, color, stackGroup, fillOpacity }`. La couleur est un jeton de thème ou un hex. |
| `xAxis` / `yAxis` | Config d'axe — `{ field, scale, format, gridLines }`.                                                            |
| `aggregate`       | `{ function, field, groupBy, interval }` pour les données résumées (omettre `field` pour le comptage).           |
| `legend`          | Affichage de la légende `{ position, show }`.                                                                    |
| `tooltip`         | Modèle de texte d'info-bulle (prend en charge `{label}` et `{value}`).                                           |

## `kpi`

Une métrique de résumé unique (une « carte de statistique ») avec tendance et sparkline optionnelles.

| Propriété    | Description                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `dataSource` | Liaison de table.                                                                                  |
| `aggregate`  | Agrégat `{ function, field }` (omettre `field` pour le comptage).                                  |
| `format`     | Formatage de valeur `{ type, options }` (p. ex. `{ type: currency, options: { currency: USD } }`). |
| `trend`      | Comparaison `{ period, direction, color, change }` par rapport à une période précédente.           |
| `sparkline`  | Mini-courbe de tendance `{ field, groupBy, interval, days }`.                                      |

## `data-timeline`

Un fil chronologique d'enregistrements ordonnés par un champ date/heure. Rend chaque enregistrement comme une entrée de chronologie.

| Propriété    | Description                                                                                |
| ------------ | ------------------------------------------------------------------------------------------ |
| `dataSource` | Liaison de table.                                                                          |
| `template`   | Modèle d'entrée par enregistrement (références `$record.*` pour titre, corps, horodatage). |
| `props`      | Attributs HTML supplémentaires (p. ex. `className`).                                       |

## `data-form` / `form`

Un formulaire adossé à des enregistrements pour les opérations de création/mise à jour sur une table. L'`action` (`crud`) détermine s'il crée ou édite, et les champs du formulaire sont générés à partir du schéma de table (remplaçables par champ). Pour la référence complète des champs et la gestion de la soumission, voir [Formulaires](/fr/forms-overview) et [Contrôles de formulaire](/fr/form-controls).

| Propriété    | Description                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------- |
| `dataSource` | Liaison de table (mode unique pour l'édition, fournissant les valeurs courantes).                                    |
| `fields`     | Config par champ — `{ field, label, placeholder, readonly, disabled, default, hidden, accept, dropZone, maxFiles }`. |
| `layout`     | Mode de disposition des champs (défaut : `single-column`).                                                           |
| `groups`     | Regrouper les champs sous un séparateur de section étiqueté (`{ label, fields }`).                                   |
| `action`     | Action `crud` avec `operation: create                                                                                | update | delete`, `confirm`, et gestionnaires `onSuccess`/`onError`. |

```yaml
- type: data-form
  dataSource: { table: contacts, mode: single, param: id }
  action:
    type: crud
    operation: update
    onSuccess: { type: navigate, url: /contacts }
  fields:
    - { field: email, label: 'Email Address' }
    - { field: notes, placeholder: 'Internal notes…' }
```

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — liaison `dataSource`, filtres, pagination, cadrage `$currentUser`.
- [Présentation des tables](/fr/tables-overview) — les modèles de données que ces composants rendent.
- [Vues](/fr/table-views) — filtres/tris enregistrés réutilisés via `data-table.view`.
- [Contrôles de formulaire](/fr/form-controls) — composants d'entrée individuels.
- [Formulaires](/fr/forms-overview) — définitions de formulaires autonomes.
- [Interactivité et scripts](/fr/interactivity-scripts) — sauvegarde automatique pour l'édition en ligne.

# Contrôles de formulaire

Les contrôles de formulaire sont les composants de saisie individuels qui composent un formulaire. Ils rendent les saisies interactives standard — texte, sélection, bascules, curseurs, sélecteurs, téléversements de fichiers — et s'intègrent à un `form`/`data-form` parent pour la soumission. Chaque contrôle accepte l'ensemble partagé `props` ainsi que les modules `visibility`, `responsive` et `i18n`. La plupart des contrôles partagent un ensemble commun d'attributs (`name`, `label`, `placeholder`, `disabled`, `required`, `defaultValue`).

```yaml
components:
  - type: form
    action: { type: crud, operation: create }
    children:
      - { type: input, name: email, props: { type: email, placeholder: 'you@example.com' } }
      - {
          type: select,
          name: plan,
          options: [{ label: Free, value: free }, { label: Pro, value: pro }],
        }
      - { type: switch, name: subscribe, props: { checked: true } }
```

## `input`

Une saisie de texte sur une seule ligne.

| Propriété            | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `name`               | Nom du champ (clé dans la charge utile soumise).                                    |
| `props.type`         | Type d'entrée HTML : `text`, `email`, `password`, `number`, `tel`, `url`, `search`. |
| `props.placeholder`  | Texte indicatif.                                                                    |
| `props.defaultValue` | Valeur initiale.                                                                    |
| `props.disabled`     | Désactiver la saisie.                                                               |
| `props.required`     | Marquer le champ comme requis.                                                      |

## `textarea`

Une saisie de texte multiligne.

| Propriété           | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `name`              | Nom du champ.                                                               |
| `props.rows`        | Nombre visible de lignes de texte.                                          |
| `props.maxLength`   | Nombre maximal de caractères (empêche la saisie au-delà de la limite).      |
| `props.autoResize`  | Définir sur `true` pour étendre la hauteur à mesure que le contenu grandit. |
| `props.placeholder` | Texte indicatif.                                                            |

## `select`

Une liste déroulante qui affiche la valeur sélectionnée et ouvre une liste d'options au clic.

| Propriété            | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| `name`               | Nom du champ.                                                         |
| `options`            | Tableau de `{ label, value, disabled?, icon? }` (au moins un requis). |
| `props.placeholder`  | Texte affiché quand aucune valeur n'est sélectionnée.                 |
| `props.searchable`   | Définir sur `true` pour activer le filtrage anticipé des options.     |
| `props.defaultValue` | Valeur présélectionnée.                                               |

## `combobox`

Une sélection consultable et à complétion automatique pour de grands ensembles d'options.

| Propriété            | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| `name`               | Nom du champ.                                                          |
| `options`            | Tableau d'options `{ label, value }` (filtrées par la requête saisie). |
| `props.placeholder`  | Texte indicatif pour le champ de recherche.                            |
| `props.defaultValue` | Valeur présélectionnée.                                                |

## `checkbox`

Une saisie de case à cocher unique.

| Propriété             | Description                                   |
| --------------------- | --------------------------------------------- |
| `name`                | Nom du champ.                                 |
| `props.checked`       | Rendre à l'état coché.                        |
| `props.indeterminate` | Rendre avec un indicateur tiret (état mixte). |
| `props.disabled`      | Désactiver le basculement.                    |

## `radio-group`

Un groupe d'options radio mutuellement exclusives.

| Propriété            | Description                                      |
| -------------------- | ------------------------------------------------ |
| `name`               | Nom du champ.                                    |
| `options`            | Tableau d'options `{ label, value, disabled? }`. |
| `props.defaultValue` | Option présélectionnée.                          |
| `props.orientation`  | Disposition `horizontal` ou `vertical`.          |

## `switch`

Un interrupteur à bascule marche/arrêt avec un rôle accessible.

| Propriété        | Description                |
| ---------------- | -------------------------- |
| `name`           | Nom du champ.              |
| `props.checked`  | Rendre en position marche. |
| `props.disabled` | Désactiver le basculement. |

## `toggle` / `toggle-group`

`toggle` est un bouton bascule unique pressable. `toggle-group` regroupe plusieurs bascules avec un comportement de sélection unique ou multiple.

| Propriété           | Description                                                                       |
| ------------------- | --------------------------------------------------------------------------------- |
| `name`              | Nom du champ (toggle-group).                                                      |
| `props.type`        | `single` ou `multiple` (selon qu'une ou plusieurs bascules peuvent être actives). |
| `props.orientation` | `horizontal` ou `vertical` (toggle-group).                                        |
| `options`           | Options de bascule (toggle-group).                                                |

## `slider`

Une saisie de plage pour sélectionner une valeur ou une plage numérique.

| Propriété            | Description               |
| -------------------- | ------------------------- |
| `name`               | Nom du champ.             |
| `props.min`          | Valeur minimale.          |
| `props.max`          | Valeur maximale.          |
| `props.step`         | Incrément de pas.         |
| `props.defaultValue` | Valeur ou plage initiale. |

## `date-picker`

Une saisie de date basée sur un calendrier.

| Propriété    | Description                                          |
| ------------ | ---------------------------------------------------- |
| `name`       | Nom du champ.                                        |
| `props.mode` | `single` (une date) ou `range` (une plage de dates). |
| `props.min`  | Date sélectionnable la plus précoce.                 |
| `props.max`  | Date sélectionnable la plus tardive.                 |

## `time-picker`

Une saisie d'heure acceptant des valeurs d'heure saisies par l'utilisateur.

| Propriété          | Description                                  |
| ------------------ | -------------------------------------------- |
| `name`             | Nom du champ.                                |
| `props.timeFormat` | `12h` (affiche un sélecteur AM/PM) ou `24h`. |
| `props.minTime`    | Heure sélectionnable la plus précoce.        |
| `props.maxTime`    | Heure sélectionnable la plus tardive.        |

## `number-input`

Une saisie numérique avec boutons d'incrémentation.

| Propriété    | Description                                                                       |
| ------------ | --------------------------------------------------------------------------------- |
| `name`       | Nom du champ.                                                                     |
| `props.min`  | Valeur minimale (contraint les valeurs saisies et incrémentées).                  |
| `props.max`  | Valeur maximale.                                                                  |
| `props.step` | Quantité d'incrément pour les boutons d'incrémentation et les flèches du clavier. |

## `file-upload`

Un sélecteur de fichiers avec glisser-déposer optionnel.

| Propriété           | Description                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `name`              | Nom du champ.                                                                                  |
| `props.accept`      | Types MIME/extensions autorisés (p. ex. `image/*,.pdf`).                                       |
| `props.maxFiles`    | Nombre maximal de fichiers pouvant être sélectionnés.                                          |
| `props.maxFileSize` | Taille maximale en octets (les fichiers trop volumineux sont rejetés avec une erreur).         |
| `props.dropZone`    | Définir sur `true` pour rendre une zone de glisser-déposer avec un indicateur de dépôt visuel. |

## `input-otp`

Une saisie segmentée de mot de passe à usage unique / code de vérification.

| Propriété      | Description                              |
| -------------- | ---------------------------------------- |
| `name`         | Nom du champ.                            |
| `props.length` | Nombre de chiffres/segments du code.     |
| `props.type`   | Caractères autorisés (p. ex. numérique). |

## `field`

Un encadreur de champ de formulaire composé qui rend un libellé, un contrôle, une description et un message d'erreur comme une seule unité accessible.

| Propriété          | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| `fieldLabel`       | Élément de libellé associé au contrôle enfant.                             |
| `fieldDescription` | Texte d'aide rendu sous le contrôle.                                       |
| `fieldError`       | Message d'erreur rendu dans la couleur destructive sous le contrôle.       |
| `props.required`   | Afficher un indicateur de champ requis (astérisque) sur le libellé.        |
| `children`         | Le composant de contrôle encadré, qui reçoit le contexte de champ composé. |

```yaml
- type: field
  fieldLabel: 'Email'
  fieldDescription: "We'll never share it."
  props: { required: true }
  children:
    - { type: input, name: email, props: { type: email } }
```

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — le modèle de composants et les actions.
- [Formulaires](/fr/forms-overview) — définitions de formulaires autonomes et cibles de soumission.
- [Composants de données](/fr/data-components) — `data-form` pour les formulaires adossés à des enregistrements.
- [Composants de superposition](/fr/overlay-components) — dialogues et tiroirs hébergeant des formulaires.
- [Présentation des types de champs](/fr/field-types-overview) — les types de champs de table dans lesquels les formulaires écrivent.

# Composants de superposition

Les composants de superposition flottent au-dessus de la page : dialogues de confirmation, tiroirs latéraux, popovers, info-bulles, toasts et espaces réservés d'état de chargement. Les composants flottants (popover, tooltip, hover-card) partagent le positionnement `floatingSide`/`floatingAlign`, et les composants de la famille dialog s'ouvrent depuis un `trigger` et piègent le focus tant qu'ils sont ouverts. Tous acceptent l'ensemble partagé `props` ainsi que les modules `visibility` et `responsive`.

```yaml
components:
  - type: dialog
    title: Confirm
    trigger: { type: button, content: 'Open' }
    children:
      - { type: text, content: 'Are you sure?' }
```

## `dialog`

Un dialogue modal ouvert depuis un déclencheur. Cliquer sur l'arrière-plan ou appuyer sur Échap le ferme ; le focus est piégé dans le dialogue tant qu'il est ouvert.

| Propriété     | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| `title`       | Titre du dialogue.                                                      |
| `description` | Texte de support sous le titre.                                         |
| `trigger`     | L'élément qui ouvre le dialogue au clic.                                |
| `children`    | Composants rendus à l'intérieur du panneau du dialogue.                 |
| `props`       | Attributs HTML (p. ex. `className` pour le dimensionnement du panneau). |

## `alert-dialog`

Un dialogue de confirmation pour les actions destructives, avec des boutons de confirmation/annulation explicites.

| Propriété      | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| `content`      | Le message de confirmation.                                          |
| `confirmLabel` | Libellé du bouton de confirmation.                                   |
| `cancelLabel`  | Libellé du bouton d'annulation.                                      |
| `trigger`      | L'élément qui ouvre le dialogue d'alerte.                            |
| `action`       | L'action invoquée à la confirmation (p. ex. une suppression `crud`). |

## `drawer`

Un panneau qui glisse depuis un bord de l'écran.

| Propriété    | Description                                                             |
| ------------ | ----------------------------------------------------------------------- |
| `drawerSide` | Bord depuis lequel le tiroir glisse : `left`, `right`, `top`, `bottom`. |
| `drawerSize` | Préréglage de taille : `sm`, `md`, `lg`, `full`.                        |
| `trigger`    | L'élément qui ouvre le tiroir.                                          |
| `children`   | Composants rendus à l'intérieur du panneau du tiroir.                   |

## `popover`

Un panneau flottant ancré à un déclencheur, ouvert au clic.

| Propriété       | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `trigger`       | L'élément qui ouvre le popover.                                             |
| `floatingSide`  | Côté préféré par rapport au déclencheur (`top`, `right`, `bottom`, `left`). |
| `floatingAlign` | Alignement le long de ce côté (`start`, `center`, `end`).                   |
| `children`      | Composants rendus à l'intérieur du popover.                                 |

## `tooltip`

Un petit indice au survol ancré à un déclencheur.

| Propriété        | Description                                    |
| ---------------- | ---------------------------------------------- |
| `tooltipContent` | Le texte de l'indice.                          |
| `tooltipDelay`   | Délai avant l'apparition de l'info-bulle (ms). |
| `floatingSide`   | Côté préféré par rapport au déclencheur.       |
| `floatingAlign`  | Alignement le long de ce côté.                 |

## `hover-card`

Un popover plus riche qui s'ouvre au survol (p. ex. un aperçu de profil).

| Propriété       | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `trigger`       | L'élément qui révèle la carte au survol.                   |
| `floatingSide`  | Côté préféré par rapport au déclencheur.                   |
| `floatingAlign` | Alignement le long de ce côté.                             |
| `openDelay`     | Délai avant l'ouverture au survol (ms).                    |
| `closeDelay`    | Délai avant la fermeture après le départ du pointeur (ms). |
| `children`      | Composants rendus à l'intérieur de la carte.               |

## `toast`

Une notification transitoire. Les toasts sont généralement émis depuis le gestionnaire `onSuccess`/`onError` d'une action plutôt que placés directement dans l'arbre ; le placement au niveau de la page se configure via [`page.toasts`](/fr/pages-overview#propriétés-de-page).

| Propriété     | Description                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| `variant`     | Style : `success`, `error`, `warning`, `info` (aussi `default`/`destructive`). |
| `message`     | Texte du toast (prend en charge les références `$variable`).                   |
| `duration`    | Durée de masquage automatique en millisecondes (défaut : 5000).                |
| `actionLabel` | Libellé optionnel de bouton d'action.                                          |
| `actionUrl`   | URL optionnelle vers laquelle le bouton d'action navigue.                      |

Plusieurs toasts s'empilent sans se chevaucher ; la position se configure par page (p. ex. `top-right`, `bottom-center`).

## `progress`

Une barre de progression ou un indicateur circulaire affichant l'achèvement.

| Propriété               | Description                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| `progressValue`         | Valeur courante.                                                                                         |
| `progressMax`           | Valeur maximale.                                                                                         |
| `props.showLabel`       | Afficher le texte de pourcentage à côté de la barre.                                                     |
| `props.size`            | Préréglage de taille (p. ex. `sm` pour une barre plus fine).                                             |
| `props.progressVariant` | Définir sur `circle` pour un indicateur de progression circulaire avec le pourcentage affiché au centre. |

## `skeleton`

Un espace réservé de chargement affiché pendant que le contenu se charge.

| Propriété         | Description                                     |
| ----------------- | ----------------------------------------------- |
| `skeletonVariant` | Forme : `text`, `circular`, ou `rectangular`.   |
| `skeletonWidth`   | Largeur de l'espace réservé.                    |
| `skeletonHeight`  | Hauteur de l'espace réservé.                    |
| `props.animate`   | Définir sur `true` pour une animation pulsante. |

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — actions, gestionnaires `onSuccess`/`onError`, toasts de page.
- [Composants de mise en page](/fr/layout-components) — le composant de mise en page `modal`.
- [Contrôles de formulaire](/fr/form-controls) — entrées couramment hébergées dans les dialogues et tiroirs.
- [Composants de retour d'information](/fr/feedback-components) — progress, spinner, skeleton.
- [Composants de données](/fr/data-components) — tiroirs de détail d'enregistrement déclenchés depuis une data-table.

# Composants de navigation

Les composants de navigation déplacent les utilisateurs : menus de premier niveau, menus déroulants et contextuels, fils d'Ariane, panneaux d'onglets, contrôles de pagination et contrôles groupés de bascule/bouton. Les éléments de menu et de fil d'Ariane suivent des schémas partagés (`MenuItemSchema`, `NavItemSchema`, `BreadcrumbItemSchema`). Tous acceptent l'ensemble partagé `props` ainsi que les modules `visibility` et `responsive`.

```yaml
components:
  - type: navigation-menu
    items:
      - { label: Home, href: / }
      - label: Products
        children:
          - { label: Catalog, href: /catalog, description: 'Browse everything' }
  - type: breadcrumb
    items:
      - { label: Home, href: / }
      - { label: Contacts }
```

## `navigation-menu`

Une barre de navigation de premier niveau prenant en charge les éléments imbriqués et les dispositions de méga-menu.

| Propriété | Description                                         |
| --------- | --------------------------------------------------- |
| `items`   | Tableau d'éléments de navigation (voir ci-dessous). |
| `props`   | Attributs HTML (p. ex. `className`).                |

Chaque élément de navigation (`NavItemSchema`) :

| Propriété d'élément | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `label`             | Texte d'affichage de l'élément.                                             |
| `href`              | URL ou chemin de route (omettre pour les éléments parents avec `children`). |
| `description`       | Texte affiché sous le libellé dans le style méga-menu.                      |
| `icon`              | Nom d'icône Lucide affiché à côté du libellé.                               |
| `target`            | Cible de l'ancre (généralement `_blank` pour les liens externes).           |
| `rel`               | Attribut `rel` de l'ancre (couramment `noopener noreferrer` avec `_blank`). |
| `children`          | Éléments de navigation enfants formant un sous-menu ou un méga-menu.        |

## `dropdown-menu`

Un menu qui s'ouvre depuis un bouton déclencheur, avec des sous-menus imbriqués optionnels.

| Propriété   | Description                                   |
| ----------- | --------------------------------------------- |
| `trigger`   | L'élément qui ouvre le menu.                  |
| `menuItems` | Tableau d'éléments de menu (voir ci-dessous). |

Chaque élément de menu (`MenuItemSchema`) :

| Propriété d'élément | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `label`             | Texte d'affichage (omettre pour un séparateur).              |
| `icon`              | Nom d'icône Lucide à côté du libellé.                        |
| `shortcut`          | Indice de raccourci clavier à droite (p. ex. `Ctrl+C`).      |
| `disabled`          | Visible mais non cliquable.                                  |
| `separator`         | Rend une ligne de séparation au lieu d'un élément cliquable. |
| `variant`           | Style visuel (p. ex. `destructive` pour du texte rouge).     |
| `children`          | Éléments de sous-menu imbriqués.                             |
| `action`            | L'action invoquée lorsque l'élément est cliqué.              |

## `context-menu`

Un menu clic droit utilisant les mêmes éléments `MenuItemSchema` que `dropdown-menu`, ancré à la position du pointeur plutôt qu'à un bouton déclencheur.

| Propriété   | Description                                        |
| ----------- | -------------------------------------------------- |
| `menuItems` | Éléments de menu (même forme que `dropdown-menu`). |
| `children`  | L'élément auquel le menu contextuel est attaché.   |

## `menubar`

Une barre de menu d'application horizontale (style Fichier / Édition / Affichage), chaque élément de premier niveau ouvrant un menu `MenuItemSchema`.

| Propriété | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `menus`   | Tableau de menus de premier niveau, chacun avec un libellé et des éléments. |

## `breadcrumb`

Un fil d'Ariane de segments de navigation.

| Propriété | Description                                           |
| --------- | ----------------------------------------------------- |
| `items`   | Tableau d'éléments de fil d'Ariane (voir ci-dessous). |

Chaque élément de fil d'Ariane (`BreadcrumbItemSchema`) :

| Propriété d'élément | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `label`             | Texte d'affichage du segment.                                     |
| `href`              | URL ou chemin de route (omettre pour l'élément de page courante). |
| `icon`              | Nom d'icône Lucide affiché avant le libellé.                      |

## `tabs`

Un conteneur à onglets. Le contenu de chaque onglet est un enfant [`tab-panel`](/fr/layout-components#tab-panel).

| Propriété            | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `children`           | Composants `tab-panel`, un par onglet.                                            |
| `props.orientation`  | Direction de disposition des déclencheurs d'onglets : `horizontal` ou `vertical`. |
| `props.defaultValue` | L'onglet ouvert au rendu initial.                                                 |

## `pagination`

Contrôles de navigation de page pour les listes/tables paginées.

| Propriété      | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `totalPages`   | Nombre total de pages.                                                  |
| `currentPage`  | La page actuellement active.                                            |
| `siblingCount` | Combien de numéros de page afficher de chaque côté de la page courante. |

## `toggle` / `toggle-group`

Boutons bascule pour la navigation/le filtrage. `toggle` est une bascule unique ; `toggle-group` en regroupe plusieurs. (Aussi documentés comme contrôles de formulaire — voir [Contrôles de formulaire](/fr/form-controls#toggle--toggle-group).)

| Propriété           | Description                              |
| ------------------- | ---------------------------------------- |
| `props.type`        | Bascules actives `single` ou `multiple`. |
| `props.orientation` | `horizontal` ou `vertical`.              |
| `options`           | Options de bascule (toggle-group).       |

## `button-group`

Une rangée de boutons connexes. Combinez avec un `dropdown-menu` pour construire un motif de bouton fractionné (un bouton principal plus une liste déroulante d'actions secondaires) ; la navigation au clavier fonctionne sur les deux.

| Propriété  | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| `children` | Les composants `button` groupés (et `dropdown-menu` optionnel). |
| `props`    | Attributs HTML (p. ex. `className`).                            |

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — le modèle de composants et les actions.
- [Composants de mise en page](/fr/layout-components) — `tab-panel`, `sidebar`, mise en page app-shell.
- [Composants interactifs](/fr/interactive-components) — boutons et liens utilisés dans les menus.
- [Composants de superposition](/fr/overlay-components) — popovers et dialogues ouverts depuis les menus.

# Composants média

Les composants média rendent des images, icônes, vidéos, audio et cadres intégrés. Ils gèrent le dimensionnement responsive, le chargement différé, les attributs d'accessibilité et le bac à sable de sécurité. Tous acceptent l'ensemble partagé `props` (où vivent la plupart des attributs média) ainsi que les modules `visibility` et `responsive` ; les références `$record.*` se résolvent dans `props.src`, `props.alt`, etc.

```yaml
components:
  - type: image
    props: { src: '$record.cover', alt: '$record.title', loading: lazy, objectFit: cover }
  - type: icon
    props: { name: check-circle, size: 20, color: 'var(--color-primary)' }
```

## `image`

Une image responsive.

| Propriété         | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `props.src`       | URL de l'image (requis ; prend en charge `$record.*`).        |
| `props.alt`       | Texte alternatif (requis pour l'accessibilité).               |
| `props.loading`   | `lazy` diffère le chargement jusqu'à proximité de la fenêtre. |
| `props.srcset`    | Sources candidates pour la sélection responsive.              |
| `props.sizes`     | Indices de taille de source associés à `srcset`.              |
| `props.width`     | Largeur intrinsèque (empêche le décalage de mise en page).    |
| `props.height`    | Hauteur intrinsèque.                                          |
| `props.objectFit` | Mise à l'échelle : `cover`, `contain`, `fill`, `none`.        |

Un chargement échoué affiche un espace réservé. Encadrez une `image` dans un [`link`](/fr/interactive-components#link) pour la rendre cliquable.

## `icon`

Une icône SVG inline du jeu d'icônes Lucide.

| Propriété           | Description                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `props.name`        | Nom d'icône Lucide (mappe vers le SVG correspondant ; prend en charge `$variable`).             |
| `props.size`        | Largeur/hauteur en pixels (défaut : 24).                                                        |
| `props.color`       | Couleur de trait SVG (par défaut `currentColor` ; prend en charge `$variable`).                 |
| `props.strokeWidth` | Largeur de trait SVG (défaut : 2).                                                              |
| `props.className`   | Classes Tailwind (p. ex. utilitaires de couleur).                                               |
| `props.ariaLabel`   | Libellé accessible — définit `role="img"` et `aria-label` ; sans lui l'icône est `aria-hidden`. |

Les icônes se rendent correctement comme enfants de `button` et `link`, et émettent `data-testid="icon-{name}"`.

## `video`

Un lecteur vidéo prenant en charge les fichiers directs et les intégrations YouTube/Vimeo.

| Propriété           | Description                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `props.src`         | URL vidéo directe ou URL d'intégration (YouTube/Vimeo se convertissent automatiquement en iframe). |
| `props.poster`      | Image d'aperçu affichée avant la lecture.                                                          |
| `props.controls`    | Afficher les contrôles de lecture.                                                                 |
| `props.autoplay`    | Lecture automatique au chargement.                                                                 |
| `props.muted`       | Démarrer en sourdine.                                                                              |
| `props.loop`        | Lecture en boucle.                                                                                 |
| `props.aspectRatio` | Dimensionnement responsive (`16:9`, `4:3`, ou personnalisé).                                       |
| `props.tracks`      | Pistes de sous-titres/légendes (format VTT).                                                       |

## `audio`

Un lecteur audio.

| Propriété        | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| `props.src`      | URL audio (requis pour l'audio à source unique).                  |
| `props.controls` | Afficher les contrôles de lecture.                                |
| `props.autoplay` | Lecture automatique au chargement.                                |
| `props.loop`     | Lecture en boucle.                                                |
| `props.sources`  | Formats multiples avec types MIME (pour repli inter-navigateurs). |

## `iframe`

Un cadre externe intégré.

| Propriété                                            | Description                                                      |
| ---------------------------------------------------- | ---------------------------------------------------------------- |
| `props.src`                                          | URL du cadre (requis).                                           |
| `props.title`                                        | Titre accessible (requis pour l'accessibilité).                  |
| `props.sandbox`                                      | Attribut sandbox restreignant les capacités du cadre (sécurité). |
| `props.allow`                                        | Permissions accordées (p. ex. caméra, microphone).               |
| `props.width` / `props.height` / `props.aspectRatio` | Dimensionnement responsive.                                      |

## `carousel`

Un diaporama de diapositives enfants défilant horizontalement ou verticalement.

| Propriété           | Description                                                                    |
| ------------------- | ------------------------------------------------------------------------------ |
| `children`          | Composants de diapositive.                                                     |
| `props.orientation` | Direction de défilement : `horizontal` ou `vertical`.                          |
| `props`             | Attributs HTML supplémentaires (p. ex. options de lecture automatique/boucle). |

## `aspect-ratio`

Un encadreur qui maintient un ratio d'aspect fixe pour son enfant (généralement un élément média).

| Propriété     | Description                                  |
| ------------- | -------------------------------------------- |
| `props.ratio` | Le ratio d'aspect à imposer (p. ex. `16:9`). |
| `children`    | Le composant média (ou autre) à contraindre. |

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — le modèle de composants et la substitution de variables.
- [Composants de contenu](/fr/content-components) — blocs de texte et de prose.
- [Composants de mise en page](/fr/layout-components) — conteneurs et grilles pour la mise en page média.
- [SEO et métadonnées](/fr/seo-meta) — images Open Graph et indices de préchargement.
- [Buckets](/fr/buckets-overview) — stockage des médias téléversés référencés par `src`.

# Composants sociaux

Les composants sociaux ajoutent de l'engagement aux pages : commentaires en fil de discussion (authentifiés et publics/invités), comptes de commentaires, un panneau de chat avec agent IA et des contrôles de partage. Les composants de commentaires s'intègrent au système de commentaires de table et respectent la permission `comment` de la table. Tous acceptent l'ensemble partagé `props` ainsi que les modules `visibility` et `responsive`.

```yaml
components:
  - type: comments
    props: { placeholder: 'Add a comment…', limit: 20, sort: newest, paginationStyle: loadMore }
  - type: commentCount
    props: { format: '{count} comments', emptyText: 'No comments yet' }
```

## `comments`

Un fil de commentaires complet pour un enregistrement. Sur une page de collection, il résout automatiquement `$record.id` et `collection.table` pour les appels API. Affiche le nom de l'auteur, l'avatar, le contenu et l'horodatage relatif ; respecte la permission `comment` de la table (masqué lorsque l'utilisateur ne la possède pas).

| Propriété               | Description                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `props.placeholder`     | Texte indicatif pour la zone de texte du formulaire de commentaire.                    |
| `props.limit`           | Commentaires chargés par page (défaut : 20).                                           |
| `props.sort`            | Ordre : `newest` (décroissant, défaut) ou `oldest` (croissant).                        |
| `props.paginationStyle` | `loadMore` (défaut, un bouton Charger plus) ou `numbered` (numéros de page).           |
| `props.showCount`       | Afficher un badge de nombre de commentaires (défaut : `true`).                         |
| `props.emptyText`       | Message personnalisé lorsqu'aucun commentaire n'existe (défaut : « No comments yet »). |

Le formulaire de commentaire est affiché aux utilisateurs authentifiés ayant la permission `comment` et masqué aux visiteurs non authentifiés (qui voient à la place une invite « Connectez-vous pour commenter » lorsque `comment: authenticated`). Les auteurs peuvent modifier/supprimer leurs propres commentaires ; les administrateurs peuvent supprimer n'importe lequel. Le contenu est limité à 10 000 caractères (correspondant à l'API).

### Commentaires publics / d'invités

Lorsque la config de commentaires de la table active `guestComments`, le formulaire accepte aussi le nom et l'e-mail de l'invité, et prend en charge la modération, les fils de discussion et la protection anti-spam :

| Préoccupation        | Comportement                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Champs d'invité      | Nom requis (1–100 caractères) ; e-mail requis lorsque `guestEmailRequired` (défaut), validé comme e-mail. Stocké avec `userId: null`.                                                                   |
| Fils de discussion   | `threading: true` affiche une Réponse à un seul niveau sur les commentaires de premier niveau ; les réponses stockent un `parentId`. `threading: false` (défaut) est plat.                              |
| Modération           | `moderation: true` crée les nouveaux commentaires comme `pending` ; les administrateurs approuvent/rejettent. `autoApprove.authenticated` / `autoApprove.previouslyApproved` contournent la modération. |
| Protection anti-spam | Champ pot de miel, limitation de débit par IP (`rateLimitPerIp`, défaut 5/min → 429), seuil de liens (`maxLinksBeforeModeration`) et rejet automatique de mots bloqués — tous appliqués côté serveur.   |

## `commentCount`

Un affichage compact du nombre de commentaires. Sur les pages de collection, il résout automatiquement `$record.id` et `collection.table` ; sur les parents liés à un dataSource, il se résout par `$record.id` pour chaque enregistrement d'une liste.

| Propriété         | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `props.format`    | Modèle de comptage avec un espace réservé `{count}` (défaut : `'{count} comments'`). |
| `props.emptyText` | Affichage lorsque le compte est 0 (défaut : `'0 comments'`).                         |

Le compte est lu depuis les métadonnées de pagination de l'API de commentaires et n'inclut que les commentaires `approved` lorsque la modération est activée.

## `ai-chat`

Un panneau de chat intégré soutenu par un agent IA configuré. Voir [Agents](/fr/ai-agents) pour la configuration des agents.

| Propriété          | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `agent`            | Nom d'agent depuis `app.agents[]`.                                 |
| `placeholder`      | Texte indicatif pour le champ de chat.                             |
| `height`           | Hauteur du conteneur de chat en pixels.                            |
| `showHistory`      | Afficher l'historique des conversations précédentes au chargement. |
| `allowAttachments` | Autoriser les pièces jointes dans le chat.                         |

```yaml
- type: ai-chat
  agent: support-assistant
  height: 480
  placeholder: 'Ask a question…'
  allowAttachments: true
```

## `sharing`

Contrôles de partage pour la page ou l'enregistrement courant (liens sociaux, copier le lien). Les surfaces de partage sont composées de composants `link`/`button` avec des interactions `navigate` ; pour le comportement de copie vers le presse-papiers, voir [Interactivité et scripts](/fr/interactivity-scripts).

| Propriété  | Description                                                                               |
| ---------- | ----------------------------------------------------------------------------------------- |
| `props`    | Attributs HTML et options de cible de partage (p. ex. `className`, URL/texte de partage). |
| `children` | Boutons/liens de partage personnalisés.                                                   |

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — pages de collection et résolution `$record.*`.
- [Agents](/fr/ai-agents) — configurer les agents IA qui alimentent `ai-chat`.
- [Permissions de table](/fr/table-permissions) — la permission `comment` qui protège les commentaires.
- [Interactivité et scripts](/fr/interactivity-scripts) — actions de presse-papiers et de navigation pour le partage.
- [Notifications](/fr/automation-email-actions) — déclencheurs d'automatisation de commentaires.

# SEO et métadonnées

La propriété `meta` au niveau de la page contrôle tout ce qui est rendu dans le `<head>` du document : le titre et la description, les cartes de partage social, les données structurées, les favicons et les indices de performance. Les métadonnées prennent en charge la substitution `$record.*` et `$frontmatter.*`, de sorte que les pages de collection et markdown produisent automatiquement un SEO par enregistrement.

```yaml
pages:
  - name: Blog Post
    path: /blog/:slug
    collection: { table: posts, slugField: slug }
    meta:
      title: '$record.title'
      description: '$record.excerpt'
      openGraph: { type: article, image: '$record.cover' }
      twitter: { card: summary_large_image }
```

## Métadonnées principales

| Propriété      | Description                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| `title`        | Titre de la page pour l'onglet du navigateur et le SEO (max ~60 caractères pour un affichage optimal). |
| `description`  | Description de la page pour le SEO et le partage social (max ~160 caractères).                         |
| `keywords`     | Mots-clés SEO séparés par des virgules.                                                                |
| `author`       | Nom de l'auteur de la page ou de l'organisation.                                                       |
| `canonical`    | URL canonique pour prévenir les problèmes de contenu dupliqué.                                         |
| `robots`       | Directives pour les robots (p. ex. `noindex, nofollow`).                                               |
| `noindex`      | Raccourci pour `robots: noindex` — empêche l'indexation par les moteurs de recherche.                  |
| `lang`         | Code de langue de la page (ISO 639-1 avec pays optionnel ; détecté automatiquement si omis).           |
| `image`        | Image de partage social par défaut (raccourci alimentant aussi Open Graph/Twitter).                    |
| `siteName`     | Nom du site (raccourci pour `openGraph.siteName`).                                                     |
| `stylesheet`   | Chemin vers la feuille de style principale.                                                            |
| `googleFonts`  | URL Google Fonts.                                                                                      |
| `translations` | Métadonnées localisées (`title`/`description` traduits) par langue.                                    |

## `openGraph`

Métadonnées du protocole Open Graph pour un partage enrichi sur les réseaux sociaux.

| Propriété     | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `type`        | Type d'objet Open Graph (p. ex. `website`, `article`).         |
| `title`       | Titre OG (peut différer du titre de la page).                  |
| `description` | Description OG.                                                |
| `url`         | URL canonique pour cette page.                                 |
| `image`       | URL de l'image pour le partage social (recommandé 1200×630px). |
| `imageAlt`    | Texte alternatif pour l'image OG.                              |
| `siteName`    | Nom du site web global.                                        |
| `locale`      | Locale au format `language_TERRITORY`.                         |
| `video`       | URL vidéo lors du partage de contenu vidéo.                    |
| `audio`       | URL audio lors du partage de contenu audio.                    |

## `twitter`

Métadonnées de carte Twitter/X.

| Propriété     | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| `card`        | Type de carte (`summary`, `summary_large_image`, `app`, `player`).                        |
| `title`       | Titre de la carte Twitter.                                                                |
| `description` | Description de la carte Twitter.                                                          |
| `image`       | URL de l'image (min 144×144 pour `summary`, 300×157 pour large).                          |
| `imageAlt`    | Texte alternatif pour l'image.                                                            |
| `site`        | `@username` Twitter du site web.                                                          |
| `creator`     | `@username` Twitter du créateur de contenu.                                               |
| `player`      | URL HTTPS vers un lecteur vidéo plus `width`/`height` (cartes player).                    |
| `app`         | Nom de l'application, identifiants de magasin et URL de lien profond pour les cartes app. |

## `structuredData`

Données structurées JSON-LD Schema.org émises comme un bloc `<script type="application/ld+json">`. Les assistants pris en charge incluent `Article`, `Organization` et `PostalAddress`.

| Propriété  | Description                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `@context` | Contexte Schema.org (`https://schema.org`).                                                                                                  |
| `@type`    | Type Schema.org (p. ex. `Article`, `Organization`, `Product`).                                                                               |
| `...`      | Champs spécifiques au type — p. ex. pour `Article` : `headline`, `author` (`{ name, url }`), `publisher` (`{ name, logo }`), `image`, dates. |

```yaml
meta:
  structuredData:
    '@context': https://schema.org
    '@type': Article
    headline: '$record.title'
    author: { name: '$record.author', url: '$record.author_url' }
    image: '$record.cover'
```

## `favicons`

Configuration des favicons pour les navigateurs et les appareils.

| Propriété  | Description                                                                      |
| ---------- | -------------------------------------------------------------------------------- |
| `default`  | Chemin de l'icône par défaut (SVG ou ICO).                                       |
| `apple`    | Icône d'écran d'accueil iOS.                                                     |
| `sizes`    | Favicons spécifiques à une taille (`{ src, sizes, type }`, p. ex. 32×32, 16×16). |
| `maskIcon` | Chemin et couleur de l'icône de masque d'onglet épinglé Safari.                  |

## Indices de performance

Indices de ressources injectés dans l'en-tête pour accélérer le chargement.

| Propriété     | Description                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| `preload`     | Ressources critiques à précharger — chacune `{ href, as, type?, media?, crossorigin? }`. |
| `dnsPrefetch` | Domaines à préextraire via DNS (tableau de domaines).                                    |
| `customHead`  | Éléments `<head>` personnalisés supplémentaires (`{ tag, attributes, content }`).        |

```yaml
meta:
  preload:
    - { href: /fonts/inter.woff2, as: font, type: font/woff2, crossorigin: anonymous }
  dnsPrefetch: ['https://cdn.example.com']
  favicons:
    default: /favicon.svg
    apple: /apple-touch-icon.png
```

:::callout
**Sitemap et RSS par page.** La capacité d'exploration SEO est complétée par la propriété `sitemap` au niveau de la page (`{ priority, changefreq }`, ou `false` pour exclure) et `rss` (pour les pages de collection). Voir [Présentation des pages → Propriétés de page](/fr/pages-overview#propriétés-de-page).
:::

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — structure de page, pages de collection, sitemap, RSS.
- [Composants de contenu](/fr/content-components) — contenu du corps de la page.
- [Composants média](/fr/media-components) — images référencées par Open Graph et preload.
- [Langues](/fr/languages) — traductions de métadonnées localisées.

# Interactivité et scripts

Les pages Sovrium sont rendues côté serveur, puis progressivement enrichies avec une interactivité déclarative. Cette page couvre le bloc `scripts` (scripts externes/inline, indicateurs de fonctionnalités, données de config), le module `interactions` (actions de clic, effets de survol, animations d'entrée), la sauvegarde automatique pour l'édition en ligne, les listes réordonnables et le HTML personnalisé. Aucun câblage d'événements écrit à la main n'est requis pour les motifs intégrés.

```yaml
pages:
  - name: Dashboard
    path: /dashboard
    scripts:
      external:
        - { src: 'https://cdn.example.com/widget.js', async: true, position: body-end }
      features: { betaPanel: true }
    components:
      - type: button
        content: Save
        interactions:
          onClick: { animation: pulse, submitForm: settings-form }
```

## `scripts`

Gestion des scripts côté client au niveau de la page.

| Propriété  | Description                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------- |
| `external` | Dépendances JavaScript externes — chacune `{ src, async, defer, module, integrity, crossorigin, position }`.    |
| `inline`   | Extraits JavaScript inline — chacun `{ code, async? }`. `async: true` encadre le code dans une IIFE asynchrone. |
| `features` | Bascules de fonctionnalités côté client — un indicateur booléen ou `{ enabled, config }` par fonctionnalité.    |
| `config`   | Données de configuration arbitraires côté client exposées aux scripts.                                          |

### Attributs de script externe

| Attribut      | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `src`         | URL source du script.                                          |
| `async`       | Charger de façon asynchrone (non bloquant).                    |
| `defer`       | Différer l'exécution jusqu'à ce que le DOM soit analysé.       |
| `module`      | Charger comme module ES (`type="module"`).                     |
| `integrity`   | Hash d'intégrité de sous-ressource pour la sécurité.           |
| `crossorigin` | Paramètre CORS : `anonymous` ou `use-credentials`.             |
| `position`    | Emplacement d'insertion : `head`, `body-start`, ou `body-end`. |

## `interactions`

Le module partagé `interactions` attache un comportement côté client à un composant : actions de clic, effets de survol et animations d'entrée.

### `onClick`

| Propriété    | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `animation`  | Animation à jouer au clic (`pulse`, `ripple`, `bounce`, ou `none`).          |
| `navigate`   | Chemin vers lequel naviguer (route interne ou ancre de même page).           |
| `url`        | URL externe à ouvrir (dans le même onglet, ou nouvel onglet avec une cible). |
| `scrollTo`   | Section d'ancre vers laquelle défiler en douceur.                            |
| `toggle`     | Id d'élément à afficher/masquer.                                             |
| `submitForm` | Id de formulaire à soumettre.                                                |
| `modalId`    | Id de section modale à ouvrir.                                               |

Les comportements de clic peuvent se combiner — p. ex. jouer une animation, puis naviguer.

### `onHover`

| Propriété         | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| `transform`       | Transformation CSS au survol (échelle/rotation/translation ; p. ex. `scale: 1.05`). |
| `opacity`         | Valeur d'opacité au survol (0–1).                                                   |
| `backgroundColor` | Couleur d'arrière-plan au survol.                                                   |
| `textColor`       | Couleur du texte au survol.                                                         |
| `borderColor`     | Couleur de bordure au survol.                                                       |
| `boxShadow`       | Ombre portée au survol.                                                             |
| `duration`        | Durée de transition (ms ; `0` applique les effets instantanément).                  |
| `easing`          | Fonction de cadence : `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`.       |

Tous les effets de survol s'appliquent simultanément avec une cadence coordonnée.

### `onEntrance`

| Propriété   | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `animation` | Type d'animation déclenché lorsque l'élément entre dans la fenêtre. |
| `threshold` | Fraction de l'élément visible avant déclenchement (0–1).            |
| `delay`     | Délai avant le démarrage de l'animation.                            |
| `once`      | Déclencher une seule fois.                                          |

## Actions et gestionnaires de réponse

Les composants interactifs portent une `action` (p. ex. `crud`, `auth`, `navigate`, `automation`) avec des gestionnaires de réponse `onSuccess`/`onError`. Un gestionnaire peut afficher un `toast`, `navigate`, `reset` le formulaire, afficher un `message`, ou rendre un `successPage` avec des `actions` de suivi. `action.type: automation` invoque une [automatisation](/fr/automations-overview) nommée.

```yaml
- type: button
  content: Submit
  action:
    type: crud
    operation: create
    onSuccess: { type: navigate, url: /thanks }
    onError: { type: message, toast: { variant: error, message: 'Save failed' } }
```

## Sauvegarde automatique

Les composants de données prennent en charge la sauvegarde automatique de l'édition en ligne via le module `autoSave` (le plus souvent sur `data-table`).

| Propriété               | Description                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `saveMode`              | `auto` (anti-rebond), `onBlur` (sauvegarder quand le champ édité perd le focus), ou `manual` (défaut).                            |
| `autoSaveDebounceMs`    | Délai d'anti-rebond après la dernière frappe (défaut : 500 ; min : 100). Les éditions rapides se regroupent en une seule requête. |
| `showSaveIndicator`     | Afficher le statut : Inactif / Sauvegarde… / Sauvegardé / Erreur (avec nouvelle tentative en cas d'échec).                        |
| `saveIndicatorPosition` | `inline` (près de la cellule éditée), `toast`, ou `toolbar`.                                                                      |

Seule la valeur de cellule modifiée est envoyée dans la charge utile PATCH ; quitter la page vide immédiatement les sauvegardes en attente.

## `reorderable-list`

Une liste dont les éléments peuvent être réordonnés par glisser-déposer ou clavier, déclenchant une action `onReorder`.

| Propriété    | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `dataSource` | Liaison de table optionnelle pour les éléments de la liste.                   |
| `children`   | Les éléments de la liste (chacun rendu avec une poignée de glissement).       |
| `onReorder`  | Action invoquée lorsque les éléments sont réordonnés (glissement ou clavier). |

## `custom-html` (`customHTML`)

Intégrer du HTML brut — inline ou depuis un fichier — dans un contexte de bac à sable avec accès aux variables CSS du thème.

| Propriété | Description                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------- |
| `content` | Chaîne HTML inline.                                                                             |
| `htmlSrc` | Chemin vers un fichier HTML externe, relatif à la racine du projet. Prend le pas sur `content`. |

Le HTML est rendu dans un contexte de bac à sable (sans accès au JS de la page parente) et peut référencer les variables du thème (p. ex. `var(--color-primary)`). Un `htmlSrc` invalide rend une erreur claire au lieu de planter.

```yaml
- type: customHTML
  content: '<div style="color: var(--color-primary)">Custom block</div>'
```

## Presse-papiers et motifs

Les motifs interactifs courants sont construits à partir des primitives ci-dessus : boutons de copie vers le presse-papiers (un `button` avec une action), champs de recherche à anti-rebond (`searchInput` avec `debounceMs`), fenêtres modales ouvertes via `onClick.modalId`, et contrôle de visibilité via le module `visibility` (rendu côté serveur mais masqué côté client lorsque les conditions d'authentification ne sont pas remplies — les composants masqués ne laissent jamais fuiter de données sensibles dans le HTML).

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — le modèle de composants, les actions et `scripts`/`vars`.
- [Contrôles de formulaire](/fr/form-controls) — entrées qui se sauvegardent automatiquement ou se soumettent via des actions.
- [Composants de données](/fr/data-components) — sauvegarde automatique de l'édition en ligne de `data-table`.
- [Composants de superposition](/fr/overlay-components) — toasts et dialogues déclenchés par des interactions.
- [Automatisations](/fr/automations-overview) — automatisations invoquées par `action.type: automation`.

# Composants d'affichage

Les composants d'affichage présentent du contenu statique ou structurel non lié à une source de données de table : tables codées en dur, palettes de commandes, états vides, panneaux divisés redimensionnables, zones de défilement, bulles de dialogue de chat, carrousels, accordéons et conteneurs d'onglets. Tous acceptent l'ensemble partagé `props` ainsi que les modules `visibility` et `responsive`.

```yaml
components:
  - type: static-table
    headers: [Plan, Price, Seats]
    rows:
      - [Free, '$0', '1']
      - [Pro, '$29', '10']
    caption: 'Pricing tiers'
```

## `static-table`

Une table peuplée à partir de données inline (pas d'une source de données).

| Propriété | Description                                                     |
| --------- | --------------------------------------------------------------- |
| `headers` | Libellés des en-têtes de colonnes.                              |
| `rows`    | Données de lignes sous forme de tableau de tableaux de chaînes. |
| `caption` | Texte de légende affiché au-dessus ou en dessous de la table.   |

## `command`

Une palette de commandes (style ⌘K) de groupes de commandes consultables.

| Propriété | Description                                                                                  |
| --------- | -------------------------------------------------------------------------------------------- |
| `groups`  | Groupes de commandes. Chaque groupe a un titre et des `items` (`{ label, icon, shortcut }`). |

## `empty-state`

Un espace réservé affiché lorsqu'il n'y a rien à afficher.

| Propriété     | Description                               |
| ------------- | ----------------------------------------- |
| `icon`        | Nom d'icône Lucide pour l'illustration.   |
| `title`       | Texte du titre.                           |
| `description` | Texte de support sous le titre.           |
| `children`    | Composants d'appel à l'action optionnels. |

## `resizable`

Panneaux divisés redimensionnables séparés par une poignée déplaçable.

| Propriété      | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `direction`    | Direction de disposition des panneaux : `horizontal` ou `vertical`.     |
| `defaultSizes` | Tailles de panneaux par défaut en pourcentages (doivent totaliser 100). |
| `minSize`      | Taille minimale de panneau en pourcentage.                              |
| `children`     | Les composants des panneaux.                                            |

## `scroll-area`

Une région défilable avec barres de défilement personnalisées.

| Propriété     | Description                                              |
| ------------- | -------------------------------------------------------- |
| `orientation` | Axe de défilement : `vertical`, `horizontal`, ou `both`. |
| `maxHeight`   | Hauteur maximale CSS pour la zone (p. ex. `400px`).      |
| `children`    | Le contenu défilable.                                    |

## `speech-bubble`

Une bulle de message de style chat (utilisée dans les interfaces de conversation).

| Propriété | Description                                                                             |
| --------- | --------------------------------------------------------------------------------------- |
| `content` | Le texte du message.                                                                    |
| `props`   | Attributs HTML — généralement `className` pour l'alignement/la couleur de l'expéditeur. |

## `list-item`

Un élément de liste unique, utilisé comme bloc de construction dans les listes et les menus.

| Propriété  | Description           |
| ---------- | --------------------- |
| `content`  | Contenu inline.       |
| `children` | Composants imbriqués. |
| `props`    | Attributs HTML.       |

## `aspect-ratio`

Contraint un enfant à un ratio largeur/hauteur fixe.

| Propriété  | Description                                                 |
| ---------- | ----------------------------------------------------------- |
| `ratio`    | Ratio largeur/hauteur (p. ex. `16/9` = 1,778, `1` = carré). |
| `children` | Le composant contraint.                                     |

## `carousel`

Un diaporama de diapositives enfants avec lecture automatique et navigation optionnelles.

| Propriété          | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `orientation`      | Direction de défilement : `horizontal` ou `vertical`.         |
| `autoplay`         | Avancer automatiquement les diapositives.                     |
| `autoplayInterval` | Intervalle entre les transitions de lecture automatique (ms). |
| `showDots`         | Afficher les indicateurs à points sous le carrousel.          |
| `showArrows`       | Afficher les flèches de navigation précédente/suivante.       |
| `children`         | Les composants de diapositive.                                |

## `accordion`

Sections de contenu repliables. (Aussi documenté dans [Composants de contenu](/fr/content-components#accordion).)

| Propriété     | Description                               |
| ------------- | ----------------------------------------- |
| `type`        | Sections ouvertes `single` ou `multiple`. |
| `defaultOpen` | IDs des éléments ouverts par défaut.      |
| `children`    | Les éléments d'accordéon.                 |

## `tabs`

Un conteneur à onglets contenant des enfants [`tab-panel`](/fr/layout-components#tab-panel). (Aussi documenté dans [Composants de navigation](/fr/navigation-components#tabs).)

| Propriété      | Description                                                |
| -------------- | ---------------------------------------------------------- |
| `orientation`  | Disposition des déclencheurs : `horizontal` ou `vertical`. |
| `defaultValue` | ID de l'onglet actif par défaut.                           |
| `children`     | Les composants `tab-panel`.                                |

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — le modèle de composants.
- [Composants de mise en page](/fr/layout-components) — conteneurs, cartes, panneaux d'onglets.
- [Composants de données](/fr/data-components) — tables liées à des données vs. `static-table`.
- [Composants de contenu](/fr/content-components) — texte, code, encarts.

# Composants de retour d'information

Les composants de retour d'information communiquent la progression et l'état de chargement : une barre/cercle de progression, un spinner et des espaces réservés skeleton. Tous acceptent l'ensemble partagé `props` ainsi que les modules `visibility` et `responsive`.

```yaml
components:
  - type: progress
    progressValue: 60
    progressMax: 100
    props: { showLabel: true, size: sm }
  - type: skeleton
    skeletonVariant: rectangular
    props: { animate: true }
```

## `progress`

Un indicateur de progression déterminé, rendu comme une barre ou un cercle.

| Propriété               | Description                                                             |
| ----------------------- | ----------------------------------------------------------------------- |
| `progressValue`         | Valeur courante (0 à `progressMax`).                                    |
| `progressMax`           | Valeur maximale (défaut : 100).                                         |
| `props.showLabel`       | Afficher le libellé de pourcentage.                                     |
| `props.size`            | Préréglage de taille (p. ex. `sm` pour une barre plus fine).            |
| `props.progressVariant` | `circle` rend une progression circulaire avec le pourcentage au centre. |

## `spinner`

Un spinner de chargement indéterminé pour les attentes courtes.

| Propriété    | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `props.size` | Préréglage de taille du spinner.                                     |
| `props`      | Attributs HTML supplémentaires (p. ex. `className` pour la couleur). |

## `skeleton`

Un espace réservé de chargement avec une forme affiché pendant que le contenu se charge.

| Propriété         | Description                                     |
| ----------------- | ----------------------------------------------- |
| `skeletonVariant` | Forme : `text`, `circular`, ou `rectangular`.   |
| `skeletonWidth`   | Largeur CSS (p. ex. `200px`, `100%`).           |
| `skeletonHeight`  | Hauteur CSS (p. ex. `20px`, `3rem`).            |
| `props.animate`   | Activer l'animation pulsante (défaut : `true`). |

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — le modèle de composants.
- [Composants de superposition](/fr/overlay-components) — `progress` et `skeleton` sont aussi adjacents aux superpositions.
- [Interactivité et scripts](/fr/interactivity-scripts) — indicateurs de statut de sauvegarde automatique.
- [Composants de données](/fr/data-components) — états de chargement pour les composants liés à des données.

# Composants interactifs

Les composants interactifs sont les primitives cliquables et inline : boutons qui déclenchent des actions, liens qui naviguent, alertes et badges qui transmettent un statut. Ils portent les modules partagés `action` et `interactions` (comportement clic/survol/entrée) ainsi que `props`, `visibility` et `responsive`.

```yaml
components:
  - type: button
    label: Save
    action: { type: crud, operation: create, onSuccess: { type: navigate, url: /done } }
  - type: link
    content: Learn more
    props: { href: /docs, target: _blank }
```

## `button`

Un bouton cliquable qui déclenche une `action` et/ou des `interactions`.

| Propriété        | Description                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`          | Libellé de texte du bouton.                                                                                                                                              |
| `content`        | Contenu inline (alternative à `label` ; peut contenir un enfant `icon`).                                                                                                 |
| `action`         | Action à exécuter au clic — `crud`, `auth`, `navigate`, `automation` — avec gestionnaires `onSuccess`/`onError`.                                                         |
| `interactions`   | Animation de clic, navigation, défilement, bascule, soumission de formulaire ou ouverture de fenêtre modale. Voir [Interactivité et scripts](/fr/interactivity-scripts). |
| `props.loading`  | Afficher un spinner de chargement à l'intérieur du bouton.                                                                                                               |
| `props.confirm`  | Invite de confirmation au clic avant l'exécution de l'action.                                                                                                            |
| `props.variant`  | Variante de style visuel (p. ex. `primary`, `secondary`, `destructive`).                                                                                                 |
| `props.disabled` | Désactiver le bouton.                                                                                                                                                    |

## `link`

Un élément d'ancre pour la navigation.

| Propriété      | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| `content`      | Texte du lien (prend en charge la substitution).                          |
| `props.href`   | URL ou chemin de route.                                                   |
| `props.target` | Cible de l'ancre (p. ex. `_blank` pour un nouvel onglet).                 |
| `props.rel`    | Attribut `rel` de l'ancre (p. ex. `noopener noreferrer`).                 |
| `children`     | Contenu imbriqué optionnel (p. ex. une `image` pour une image cliquable). |

## `alert`

Un bloc d'encart inline. (Aussi documenté dans [Composants de contenu](/fr/content-components#alert).)

| Propriété           | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `content`           | Le message d'alerte.                                                          |
| `props.variant`     | `info`, `warning`, `error`, ou `success` (chacun avec une icône automatique). |
| `props.dismissible` | Rendre un bouton de fermeture qui masque l'alerte.                            |

## `badge`

Une petite puce de statut/libellé.

| Propriété | Description                                                                |
| --------- | -------------------------------------------------------------------------- |
| `content` | Texte du libellé du badge.                                                 |
| `variant` | Mode de rendu (p. ex. `status` pour un point d'indicateur de statut).      |
| `color`   | Jeton de couleur pour le point de statut (`variant: status`).              |
| `label`   | Texte du libellé de statut à côté du point (`variant: status`).            |
| `pulse`   | Activer une animation pulsante sur le point de statut (`variant: status`). |

## `button-group`

Une rangée de boutons connexes. (Aussi documenté dans [Composants de navigation](/fr/navigation-components#button-group) ; combinez avec `dropdown-menu` pour un bouton fractionné.)

| Propriété  | Description                                                        |
| ---------- | ------------------------------------------------------------------ |
| `children` | Les composants `button` groupés (et liste déroulante optionnelle). |
| `props`    | Attributs HTML (p. ex. `className`).                               |

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — actions et gestionnaires de réponse.
- [Interactivité et scripts](/fr/interactivity-scripts) — comportement clic/survol/entrée en profondeur.
- [Contrôles de formulaire](/fr/form-controls) — entrées que les boutons soumettent.
- [Composants de navigation](/fr/navigation-components) — menus et motifs de bouton fractionné.

# Composants spécialisés

Les composants spécialisés servent des cas d'usage ciblés : assistants multi-étapes, listes à réordonner par glissement, changement de langue, points de statut et entrées avancées autonomes. Plusieurs sont référencés depuis d'autres pages de catégorie (contrôles de formulaire, social) où ils remplissent plus d'un rôle. Tous acceptent l'ensemble partagé `props` ainsi que les modules `visibility` et `responsive`.

```yaml
components:
  - type: wizard
    steps:
      - { id: account, label: Account, description: 'Set up your account' }
      - { id: profile, label: Profile }
    children:
      - { type: input, name: email }
      - { type: input, name: name }
```

## `wizard`

Un flux multi-pages par étapes avec un indicateur de progression.

| Propriété     | Description                             |
| ------------- | --------------------------------------- |
| `steps`       | Définitions d'étapes (voir ci-dessous). |
| `initialStep` | L'`id` de l'étape affichée en premier.  |
| `children`    | Les composants rendus par étape.        |

Chaque étape :

| Propriété d'étape | Description                                                               |
| ----------------- | ------------------------------------------------------------------------- |
| `id`              | Identifiant d'étape unique (utilisé pour la navigation et `initialStep`). |
| `label`           | Texte d'affichage dans l'indicateur de progression.                       |
| `icon`            | Nom d'icône Lucide dans l'indicateur d'étape.                             |
| `description`     | Brève description sous le libellé de l'étape.                             |

## `reorderable-list`

Une liste dont les éléments peuvent être réordonnés par glisser-déposer ou clavier. (Aussi documenté dans [Interactivité et scripts](/fr/interactivity-scripts#reorderable-list).)

| Propriété    | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `dragHandle` | Activer le réordonnancement par glisser-déposer des éléments de la liste. |
| `onReorder`  | Action déclenchée lorsque les éléments sont réordonnés.                   |
| `children`   | Les éléments de la liste (chacun avec une poignée de glissement).         |

## `language-switcher`

Un contrôle qui change la langue active pour une application internationalisée.

| Propriété | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| `props`   | Attributs HTML et options d'affichage (p. ex. `className`, style de libellé). |

Voir [Langues](/fr/languages) pour la configuration i18n.

## `status-indicator`

Un point de statut coloré avec un libellé (aussi exprimable comme `badge` avec `variant: status`).

| Propriété | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `label`   | Texte du libellé de statut à côté du point.                        |
| `color`   | Couleur du point (valeur de couleur CSS ou nom de jeton de thème). |
| `pulse`   | Activer une animation pulsante sur le point.                       |

## `file-upload`

Un sélecteur de fichiers avec glisser-déposer optionnel. (Aussi documenté dans [Contrôles de formulaire](/fr/form-controls#file-upload).)

| Propriété     | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| `accept`      | Types MIME/extensions acceptés (p. ex. `image/*, .pdf`).             |
| `dropZone`    | Activer une zone de dépôt par glisser-déposer.                       |
| `maxFiles`    | Nombre maximal de fichiers par téléversement.                        |
| `maxFileSize` | Taille maximale de fichier en octets (p. ex. `10485760` pour 10 Mo). |

## `number-input`

Une saisie numérique avec boutons d'incrémentation. (Aussi documenté dans [Contrôles de formulaire](/fr/form-controls#number-input).)

| Propriété      | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `min`          | Valeur minimale.                                                        |
| `max`          | Valeur maximale.                                                        |
| `step`         | Incrément de pas.                                                       |
| `showStepper`  | Afficher les boutons d'incrémentation/décrémentation (défaut : `true`). |
| `defaultValue` | Valeur numérique initiale.                                              |

## `time-picker`

Une saisie d'heure. (Aussi documenté dans [Contrôles de formulaire](/fr/form-controls#time-picker).)

| Propriété     | Description                                           |
| ------------- | ----------------------------------------------------- |
| `minTime`     | Heure sélectionnable minimale (HH:mm).                |
| `maxTime`     | Heure sélectionnable maximale (HH:mm).                |
| `stepMinutes` | Incrément en minutes pour la sélection (défaut : 15). |

## `comments` / `ai-chat`

Composants d'engagement documentés dans [Composants sociaux](/fr/social-components) : `comments` (commentaires en fil de discussion, publics/invités), `commentCount` et `ai-chat` (un panneau de chat avec agent IA).

## Pages connexes

- [Présentation des pages](/fr/pages-overview) — le modèle de composants et les actions.
- [Contrôles de formulaire](/fr/form-controls) — `file-upload`, `number-input`, `time-picker`.
- [Composants sociaux](/fr/social-components) — `comments`, `commentCount`, `ai-chat`.
- [Langues](/fr/languages) — i18n pour `language-switcher`.
- [Agents](/fr/ai-agents) — agents alimentant `ai-chat`.

# Présentation des formulaires

Les formulaires recueillent les saisies des contributeurs et les acheminent vers une destination utile — dans une table, via une automatisation, dans le registre de soumissions intégré, ou n'importe quelle combinaison des trois. Ils sont déclarés dans le tableau de premier niveau `forms`, chacun accessible à sa propre URL, intégrable dans une page et adressable depuis un déclencheur d'automatisation.

Un formulaire est le pendant public d'une table : là où une table définit _à quoi_ ressemblent les données, un formulaire définit _comment_ les gens y contribuent. Le même formulaire peut écrire directement dans une entrée `tables[]`, déclencher une automatisation `notify-sales`, ou simplement atterrir dans le registre `form_submissions` de la plateforme pour une révision ultérieure.

```yaml
forms:
  - id: 1
    name: contact
    title: Contact Sales
    path: /contact
    submitTo:
      table: leads
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: table-field, column: message }
```

## Propriétés du formulaire

Chaque entrée du tableau `forms` accepte les propriétés suivantes.

| Propriété      | Description                                                                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Entier positif unique identifiant le formulaire. Doit être unique dans `forms[]`.                                                                                                                                   |
| `name`         | Identifiant unique en kebab-case (`^[a-z][a-z0-9-]*`, 1 à 64 caractères). Référencé par les composants de page (`formRef`) et le déclencheur d'automatisation de formulaire. Doit être unique dans `forms[]`.       |
| `title`        | Titre lisible affiché aux contributeurs. Prend en charge les clés i18n `$t:`.                                                                                                                                       |
| `description`  | Paragraphe d'introduction optionnel affiché au-dessus du premier champ.                                                                                                                                             |
| `path`         | URL publique conviviale optionnelle (par ex. `/contact`). Lorsqu'elle est définie, le formulaire est servi à cet emplacement _et_ à la route canonique `/forms/{name}`. Voir [Routes publiques](#routes-publiques). |
| `submitTo`     | Où la soumission est persistée et/ou acheminée : une table, une automatisation, le registre, ou une combinaison. Obligatoire. Voir [Cibles de soumission](#cibles-de-soumission).                                   |
| `fields`       | Liste ordonnée de définitions de champs affichés dans le formulaire. Au moins un requis. Voir [Champs de formulaire](/fr/form-fields).                                                                              |
| `layout`       | Mode de rendu : `single-page` (par défaut), `multi-step` ou `one-question`. Voir [Formulaires multi-étapes](/fr/form-multi-step).                                                                                   |
| `steps`        | Définitions d'étapes pour les mises en page `multi-step` / `one-question`. Voir [Formulaires multi-étapes](/fr/form-multi-step).                                                                                    |
| `fieldGroups`  | Séparateurs de section libellés regroupant les champs au sein d'une mise en page sur une seule page.                                                                                                                |
| `display`      | Options cosmétiques (colonnes, barre de progression, libellé du bouton de soumission, thème par formulaire). Voir [Formulaires multi-étapes](/fr/form-multi-step).                                                  |
| `access`       | Contrôle d'accès : `all`, `authenticated`, ou une liste de rôles, avec un `redirectTo` optionnel. Voir [Contrôle d'accès](#contrôle-daccès).                                                                        |
| `availability` | Fenêtre de soumission (`opensAt`, `closesAt`) et plafond de soumissions (`maxSubmissions`), avec une page de formulaire fermé personnalisée optionnelle.                                                            |
| `antiSpam`     | Pot de miel, limites de débit à fenêtre glissante, et un stub de connexion CAPTCHA.                                                                                                                                 |
| `analytics`    | Désactivation par formulaire (`enabled: false`) excluant le formulaire des analyses agrégées. Activé par défaut.                                                                                                    |
| `prefill`      | Mappage champ de formulaire → référence `$query.{name}` / `$user.{prop}` / `$parent.{path}` ou valeur littérale par défaut. Voir [Champs de formulaire](/fr/form-fields).                                           |
| `submitter`    | Règles d'enregistrement-et-reprise, de modification-après-soumission et de soumission unique.                                                                                                                       |
| `onSuccess`    | Comportement post-soumission (page de succès, redirection, réinitialisation, toast, message en ligne). Voir [Soumissions](/fr/form-submissions).                                                                    |
| `onError`      | Ce qu'il faut afficher quand une soumission échoue côté serveur (toast, message en ligne, page d'erreur). Voir [Soumissions](/fr/form-submissions).                                                                 |

## Cibles de soumission

L'objet `submitTo` découple un formulaire de tout modèle de persistance unique. Au moins l'un de `table`, `automation`, ou `storeSubmission: true` (la valeur par défaut) doit être défini — sinon la soumission serait silencieusement rejetée et le schéma rejette la configuration.

| Propriété         | Description                                                                                                                                                                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table`           | Persiste la soumission comme un enregistrement dans cette table. Référence un `tables[].name` ; validé par rapport au tableau `tables[]` de l'application.                                                                                   |
| `automation`      | Invoque cette automatisation _après_ la validation des écritures. Référence un `automations[].name` ; validé par rapport au tableau `automations[]` de l'application.                                                                        |
| `mapping`         | Mappe les noms de champs de formulaire vers les noms de colonnes de destination. Par défaut l'identité (nom du champ de formulaire = nom de la colonne de table). Une cible de mappage qui n'existe pas sur la table échoue à la validation. |
| `storeSubmission` | Persiste la soumission dans le registre intégré `form_submissions`. Vaut `true` par défaut — définissez `false` pour vous désinscrire (et alors `table` ou `automation` devient obligatoire).                                                |

```yaml
submitTo:
  table: support_tickets
  automation: page-on-call
  mapping:
    userEmail: email # form field 'userEmail' -> table column 'email'
```

:::callout
**Tables, automatisations, le registre — ou les trois.** Un formulaire peut écrire en double dans une `table` et le registre, déclencher une automatisation, ou tout faire à la fois. L'écriture dans la table et l'écriture dans le registre se produisent au sein d'une seule transaction ; l'automatisation ne s'exécute qu'après la validation des deux. Voir [Soumissions](/fr/form-submissions) pour le contrat complet d'écriture double.
:::

## Routes publiques

Chaque formulaire est accessible à la route canonique `/forms/{name}` quelle que soit la configuration — un formulaire sans `path` n'est pas privé, il est simplement uniquement accessible à cet emplacement. Lorsque `path` est défini, le formulaire est servi à ce chemin personnalisé **et** à `/forms/{name}` simultanément (pas de redirection ; les deux URL affichent le même formulaire).

| Règle               | Description                                                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Route canonique     | `/forms/{name}` sert toujours le formulaire (HTTP 200). Un nom inconnu renvoie 404.                                                                 |
| Chemin personnalisé | Optionnel. Doit commencer par `/`, 2 à 256 caractères compatibles URL ; statique (pas de segments dynamiques `:id`).                                |
| Préfixes réservés   | `/api/`, `/admin/`, `/forms/` et `/auth/` sont rejetés afin qu'un formulaire ne puisse pas masquer une route intégrée.                              |
| Règle de collision  | Un `forms[].path` NE DOIT PAS entrer en collision avec un `pages[].path`. Les collisions échouent à la validation avec une erreur nommant les deux. |
| Route d'intégration | `/forms/{name}/embed` sert une coquille HTML minimale pour l'intégration en iframe sur des sites tiers.                                             |

## Contrôle d'accès

L'objet `access` réutilise le modèle de permission partagé employé par les tables, les pages, les buckets, les automatisations et les agents.

| Propriété    | Description                                                                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `require`    | `'all'` (tout le monde, y compris anonyme), `'authenticated'` (tout utilisateur connecté), ou une liste de rôles (`['admin', 'editor']`).    |
| `redirectTo` | Chemin optionnel (par ex. `/login`) vers lequel rediriger les contributeurs refusés, au lieu de renvoyer un 401/403. Doit commencer par `/`. |

```yaml
forms:
  - id: 2
    name: member-survey
    title: Member Survey
    access:
      require: authenticated
      redirectTo: /login
    submitTo: { table: survey_responses }
    fields:
      - { kind: standalone, name: rating, inputType: rating, required: true }
```

:::callout
**Les références `$user.*` nécessitent une authentification.** Un formulaire dont `access.require` vaut `'all'` (la valeur par défaut) ne peut pas porter de `defaultValue` par champ référençant `$user.*` — la valeur se résoudrait toujours à vide pour les visiteurs anonymes et pourrait divulguer l'état de session. Définissez `access.require` à `authenticated` ou une liste de rôles, ou utilisez le `prefill` de premier niveau (qui ignore silencieusement les références `$user` non résolvables sur les formulaires publics). Voir [Champs de formulaire](/fr/form-fields).
:::

## Intégrer un formulaire dans une page

Un formulaire de premier niveau peut être affiché en ligne dans une page via le `formRef` du contrôle de formulaire. Le formulaire est défini une fois et réutilisé n'importe où — les champs, la validation, la logique conditionnelle, la mise en page multi-étapes, les téléversements de fichiers, et `onSuccess`/`onError` proviennent tous de `app.forms[]`. Le contrôle d'accès de la page hôte est croisé avec les propres règles du formulaire au moment du rendu.

```yaml
pages:
  - id: 1
    name: landing
    path: /
    components:
      - type: form
        formRef: contact # renders the top-level "contact" form inline
        props:
          label: Get in touch # display-only override of the submit label
```

Voir [Contrôles de formulaire](/fr/form-controls) pour le côté composant de page de `formRef`.

## Pages associées

- [Champs de formulaire](/fr/form-fields) — champs autonomes vs liés à une table, préremplissage, création de relation en ligne.
- [Logique conditionnelle](/fr/form-conditional-logic) — règles visible / requis / désactivé.
- [Formulaires multi-étapes](/fr/form-multi-step) — étapes, branchement, mises en page une question, surcharges d'affichage.
- [Soumissions](/fr/form-submissions) — le registre d'écriture double, la gestion du succès et des erreurs.
- [Téléversements de fichiers](/fr/form-file-uploads) — champs de pièce jointe adossés à des buckets.
- [Présentation des tables](/fr/tables-overview) — les modèles de données dans lesquels les formulaires écrivent.
- [Contrôles de formulaire](/fr/form-controls) — intégrer un formulaire dans une page.
- [Authentification](/fr/auth-overview) — rôles et authentification derrière `access`.

# Champs de formulaire

Le tableau `fields` d'un formulaire est une liste ordonnée de définitions de champs affichés de haut en bas. Chaque champ est l'un de cinq **types** (`kinds`), distingués par une propriété `kind`. Les champs liés à une table héritent de leur type et de leur validation d'une colonne de table ; les champs autonomes sont typés en ligne ; les champs de calcul, de section et de signature couvrent les valeurs calculées, les séparateurs et les signatures.

```yaml
forms:
  - id: 1
    name: signup
    title: Create your account
    submitTo: { table: users }
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: newsletter, inputType: checkbox, label: Subscribe to updates }
```

## Types de champs

| Type          | Description                                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `table-field` | Lié à une colonne de `submitTo.table`. Le type, la validation et la persistance proviennent du schéma de table ; le formulaire ne surcharge que l'affichage.             |
| `standalone`  | Typé en ligne via `inputType` ; non persisté directement dans une colonne. À utiliser pour les formulaires qui n'acheminent que vers des automatisations ou le registre. |
| `calculation` | Valeur calculée en lecture seule dérivée d'autres champs via une formule `{{fieldName}}`. N'affiche aucune saisie.                                                       |
| `section`     | Séparateur visuel avec un titre et une description optionnels. N'affiche aucune saisie.                                                                                  |
| `signature`   | Capture une signature manuscrite ou saisie au clavier.                                                                                                                   |

## Propriétés communes des champs

Chaque type de champ portant une saisie (`table-field`, `standalone`, `calculation`, `signature`) partage une base commune.

| Propriété      | Description                                                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `label`        | Libellé affiché au contributeur. Prend en charge les clés i18n `$t:`.                                                                  |
| `placeholder`  | Texte indicatif affiché lorsque le champ est vide.                                                                                     |
| `helpText`     | Texte d'aide affiché sous le champ.                                                                                                    |
| `required`     | Booléen. Lorsque `true`, le champ doit avoir une valeur. Pour une obligation conditionnelle, utilisez `requiredWhen`.                  |
| `readOnly`     | Booléen. Affiche le champ en lecture seule.                                                                                            |
| `hidden`       | Booléen. Masque le champ de l'interface mais le soumet quand même (valeur côté serveur uniquement).                                    |
| `defaultValue` | Valeur littérale, ou une référence `$query.{name}` / `$user.{prop}` résolue au moment du rendu.                                        |
| `visibleWhen`  | Règle de visibilité conditionnelle. Voir [Logique conditionnelle](/fr/form-conditional-logic).                                         |
| `requiredWhen` | Règle d'obligation conditionnelle (même forme que `visibleWhen`).                                                                      |
| `disabledWhen` | Règle de désactivation conditionnelle (même forme que `visibleWhen`).                                                                  |
| `permissions`  | Permission `read` par champ. Lorsque le rôle demandeur est exclu, la valeur est masquée des exports admin et du détail par soumission. |

## Champs liés à une table

Un `kind: table-field` référence une `column` sur la `submitTo.table` du formulaire. Le type de champ, la validation et la persistance proviennent tous du schéma de table — le formulaire ne fournit que les aspects d'affichage plus, pour les colonnes de pièce jointe, les options de téléversement.

| Propriété     | Description                                                                          |
| ------------- | ------------------------------------------------------------------------------------ |
| `column`      | Nom de la colonne sur `submitTo.table`. Obligatoire.                                 |
| `accept`      | Types MIME ou extensions séparés par des virgules pour les colonnes de pièce jointe. |
| `maxFileSize` | Taille maximale (octets) par fichier téléversé (colonnes de pièce jointe).           |
| `maxFiles`    | Nombre maximal de fichiers pour les colonnes `multiple-attachments`.                 |
| `dropZone`    | Affiche une zone de glisser-déposer à côté du sélecteur de fichiers.                 |

```yaml
fields:
  - kind: table-field
    column: subject
    label: What can we help with?
    placeholder: Briefly describe the issue
  - kind: table-field
    column: priority
    helpText: Urgent issues are triaged first
```

Les colonnes de pièce jointe (`single-attachment`, `multiple-attachments`) affichent automatiquement une saisie de fichier. Voir [Téléversements de fichiers](/fr/form-file-uploads) pour le pipeline de téléversement et la liaison au bucket.

## Champs autonomes

Un champ `kind: standalone` est typé en ligne via `inputType` et n'est pas écrit directement dans une colonne de table. Il est idéal pour les formulaires qui acheminent vers une automatisation ou vivent uniquement dans le registre de soumissions.

| Propriété     | Description                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `name`        | Nom de champ unique au sein du formulaire (`^[a-zA-Z][a-zA-Z0-9_-]*`, ≤64 caractères). Obligatoire. |
| `inputType`   | Type de contrôle (voir ci-dessous). Obligatoire.                                                    |
| `options`     | Choix `{ value, label }` pour `select` / `multi-select` / `radio`.                                  |
| `accept`      | Types MIME acceptés pour la saisie `attachment`.                                                    |
| `maxFiles`    | Nombre maximal de fichiers pour la saisie `attachment`.                                             |
| `maxFileSize` | Taille maximale (octets) par fichier téléversé.                                                     |
| `dropZone`    | Affiche une zone de glisser-déposer à côté du sélecteur de fichiers.                                |

**Valeurs `inputType` disponibles :** `short-text`, `long-text`, `email`, `url`, `phone`, `number`, `date`, `datetime`, `select`, `multi-select`, `checkbox`, `radio`, `rating`, `attachment`.

```yaml
fields:
  - kind: standalone
    name: rating
    inputType: rating
    label: How was your experience?
    required: true
  - kind: standalone
    name: source
    inputType: select
    label: How did you hear about us?
    options:
      - { value: search, label: Search engine }
      - { value: referral, label: Referral }
      - { value: social, label: Social media }
```

## Champs de calcul, de section et de signature

| Type          | Propriétés clés                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `calculation` | `name`, `formula` (référence d'autres champs via `{{name}}`), `format` optionnel (`number` / `currency` / `percent` / `text`). Lecture seule. |
| `section`     | `heading`, `description` optionnels, et une règle `visibleWhen` pour toute la section. N'affiche aucune saisie.                               |
| `signature`   | `name`. Capture une signature manuscrite ou saisie au clavier.                                                                                |

```yaml
fields:
  - { kind: standalone, name: quantity, inputType: number, label: Quantity }
  - { kind: standalone, name: unit_price, inputType: number, label: Unit price }
  - kind: calculation
    name: total
    label: Total
    formula: '{{quantity}} * {{unit_price}}'
    format: currency
```

## Préremplissage

Le mappage `prefill` de premier niveau initialise les valeurs des champs au moment du rendu. Les clés sont des noms de champs de formulaire ; les valeurs sont soit une valeur littérale par défaut, soit une référence :

| Référence        | Se résout en                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `$query.{name}`  | Un paramètre de chaîne de requête d'URL (par ex. `$query.utm_source`).                                                               |
| `$user.{prop}`   | Une propriété de l'utilisateur authentifié (par ex. `$user.email`). Silencieusement ignoré sur les formulaires publics sans session. |
| `$parent.{path}` | Un champ de l'enregistrement parent — valide uniquement pour les formulaires de relation en ligne (voir ci-dessous).                 |

```yaml
forms:
  - id: 1
    name: lead-capture
    title: Request a demo
    submitTo: { table: leads }
    prefill:
      utm_source: $query.utm_source
      utm_campaign: $query.utm_campaign
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: utm_source, inputType: short-text, hidden: true }
      - { kind: standalone, name: utm_campaign, inputType: short-text, hidden: true }
```

:::callout
**Deux façons de définir une valeur par défaut.** Le `defaultValue` par champ accepte les références `$query` / `$user` en ligne, tandis que le mappage `prefill` de premier niveau garde le câblage de préremplissage au même endroit. Sur un formulaire public (`access.require: all`), un `defaultValue: $user.*` par champ est rejeté au moment de la validation — utilisez le `prefill` de premier niveau (qui tolère une résolution `$user` vide) ou exigez l'authentification.
:::

## Création de relation en ligne

Lorsqu'un formulaire est intégré dans la page de détail d'un enregistrement parent (par ex. un bouton « + Nouveau ticket » sur une page Projet), la source de préremplissage `$parent.{path}` relie automatiquement le nouvel enfant à son parent. Cela se configure sur le contrôle de formulaire de page via `inlinePrefill`.

| Propriété     | Description                                                                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `prefill`     | Mappage nom-de-champ → source-de-préremplissage (même union `$query` / `$user` / `$parent`).                                                   |
| `lockPrefill` | Lorsque `true`, les champs préremplis sont masqués et ne peuvent pas être surchargés (toujours validés côté serveur). Vaut `false` par défaut. |

```yaml
forms:
  - id: 1
    name: new-ticket
    submitTo: { table: tickets }
    fields:
      - { kind: table-field, column: title, required: true }
      - { kind: table-field, column: project_id }
      - { kind: table-field, column: reporter_id }

pages:
  - id: 1
    name: project-detail
    path: /portal/projects/:id
    components:
      - type: form
        formRef: new-ticket
        inlinePrefill:
          prefill:
            project_id: $parent.id # locked to the current project
            reporter_id: $user.id
          lockPrefill: true
```

À la soumission, le moteur revalide l'existence du parent pour se prémunir contre les références `$parent` obsolètes. Les colonnes de relation simple et multiple sont toutes deux prises en charge.

## Pages associées

- [Présentation des formulaires](/fr/forms-overview) — métadonnées de formulaire, cibles de soumission, contrôle d'accès.
- [Logique conditionnelle](/fr/form-conditional-logic) — `visibleWhen` / `requiredWhen` / `disabledWhen`.
- [Formulaires multi-étapes](/fr/form-multi-step) — distribuer les champs sur plusieurs étapes.
- [Téléversements de fichiers](/fr/form-file-uploads) — options de saisie de pièce jointe et liaison au bucket.
- [Champs relationnels](/fr/relational-fields) — les colonnes de relation ciblées par `$parent`.
- [Contrôles de formulaire](/fr/form-controls) — le composant de page qui héberge `formRef` + `inlinePrefill`.

# Logique conditionnelle des formulaires

La logique conditionnelle fait réagir un formulaire à ce que le contributeur saisit : les champs apparaissent, deviennent obligatoires ou se grisent selon les valeurs d'autres champs. Trois propriétés de règle pilotent cela — `visibleWhen`, `requiredWhen` et `disabledWhen` — et toutes les trois partagent la même forme de condition, donc une fois que vous en apprenez une, vous les connaissez toutes les trois.

```yaml
fields:
  - {
      kind: standalone,
      name: has_company,
      inputType: checkbox,
      label: I'm signing up on behalf of a company,
    }
  - kind: standalone
    name: company_name
    inputType: short-text
    label: Company name
    visibleWhen: { field: has_company, operator: eq, value: true }
    requiredWhen: { field: has_company, operator: eq, value: true }
```

## Propriétés des règles

| Propriété      | Effet lorsque la condition est **vraie**                                         |
| -------------- | -------------------------------------------------------------------------------- |
| `visibleWhen`  | Le champ (ou la section) est affiché. Lorsque faux, il est masqué et non soumis. |
| `requiredWhen` | Le champ devient obligatoire. Lorsque faux, il est optionnel.                    |
| `disabledWhen` | Le champ est désactivé (grisé, non modifiable). Lorsque faux, il est modifiable. |

Chaque règle réside sur la base commune d'un champ, elle peut donc s'appliquer à tout type de champ portant une saisie. Les champs `section` prennent en charge `visibleWhen` pour afficher ou masquer un groupe libellé entier.

## Conditions simples

Une condition simple compare la valeur actuelle d'un champ à une cible à l'aide d'un opérateur.

| Propriété  | Description                                                                                                                          |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `field`    | Nom du champ dont la valeur est évaluée.                                                                                             |
| `operator` | Opérateur de comparaison (voir le tableau ci-dessous).                                                                               |
| `value`    | Valeur à comparer. Un scalaire pour les opérateurs de comparaison ; un tableau pour l'appartenance ; omis pour `empty` / `notEmpty`. |

### Opérateurs de condition

| Opérateur  | Signification                                 |
| ---------- | --------------------------------------------- |
| `eq`       | Égal à la valeur.                             |
| `neq`      | N'est pas égal à la valeur.                   |
| `contains` | La chaîne/le tableau contient la valeur.      |
| `empty`    | Le champ n'a aucune valeur (ignore `value`).  |
| `notEmpty` | Le champ a une valeur (ignore `value`).       |
| `gt`       | Supérieur à la valeur.                        |
| `gte`      | Supérieur ou égal à la valeur.                |
| `lt`       | Inférieur à la valeur.                        |
| `lte`      | Inférieur ou égal à la valeur.                |
| `in`       | La valeur est l'un des membres du tableau.    |
| `notIn`    | La valeur n'est aucun des membres du tableau. |

```yaml
fields:
  - kind: standalone
    name: contact_method
    inputType: select
    label: Preferred contact method
    options:
      - { value: email, label: Email }
      - { value: phone, label: Phone }
  - kind: standalone
    name: phone
    inputType: phone
    label: Phone number
    visibleWhen: { field: contact_method, operator: eq, value: phone }
    requiredWhen: { field: contact_method, operator: eq, value: phone }
```

## Conditions composées (ET / OU)

Les conditions se composent avec `and` / `or` et peuvent s'imbriquer arbitrairement. Un bloc `and` est vrai lorsque **chaque** enfant est vrai ; un bloc `or` est vrai lorsque **n'importe quel** enfant est vrai.

```yaml
fields:
  - kind: standalone
    name: expedite_reason
    inputType: long-text
    label: Why does this need to be expedited?
    visibleWhen:
      and:
        - { field: priority, operator: in, value: [high, urgent] }
        - or:
            - { field: budget, operator: gte, value: 10000 }
            - { field: vip_customer, operator: eq, value: true }
```

:::callout
**`disabledWhen` garde un champ présent.** Un champ désactivé s'affiche toujours et soumet toujours sa valeur actuelle — il ne peut simplement pas être modifié. Utilisez `visibleWhen` lorsqu'un champ doit disparaître et cesser entièrement d'être soumis ; utilisez `disabledWhen` lorsque la valeur doit rester mais être verrouillée.
:::

## Branchement d'étapes

Dans les mises en page multi-étapes, les conditions pilotent aussi le contrôle de flux. Les règles `goToWhen` d'une étape permettent à une condition vraie de sauter vers une étape différente plutôt que vers la suivante linéaire, et un `visibleWhen` au niveau de l'étape saute l'étape entière. Voir [Formulaires multi-étapes](/fr/form-multi-step) pour le modèle de branchement complet.

```yaml
steps:
  - id: account-type
    title: Account type
    fields: [plan]
    goToWhen:
      - when: { field: plan, operator: eq, value: enterprise }
        goTo: sales-contact
  - id: billing
    title: Billing
    fields: [card_number, billing_email]
  - id: sales-contact
    title: Talk to sales
    fields: [company, seats]
```

## Conditions via `formRef`

Lorsqu'un formulaire de premier niveau est intégré dans une page via le `formRef` du contrôle de formulaire, toute sa logique conditionnelle l'accompagne — `visibleWhen`, `requiredWhen`, `disabledWhen` et le branchement d'étapes se comportent de manière identique que le formulaire soit affiché à `/forms/{name}` ou en ligne sur une page hôte. Définissez les conditions une fois sur le formulaire ; chaque intégration en hérite. Voir [Contrôles de formulaire](/fr/form-controls).

## Pages associées

- [Champs de formulaire](/fr/form-fields) — où résident `visibleWhen` / `requiredWhen` / `disabledWhen`.
- [Formulaires multi-étapes](/fr/form-multi-step) — visibilité au niveau de l'étape et branchement `goToWhen`.
- [Présentation des formulaires](/fr/forms-overview) — métadonnées de formulaire et cibles de soumission.
- [Contrôles de formulaire](/fr/form-controls) — intégrer un formulaire conditionnel dans une page.

# Formulaires multi-étapes

Les longs formulaires sont plus faciles à remplir lorsqu'ils sont découpés en morceaux gérables. La propriété `layout` choisit comment les champs d'un formulaire sont présentés : tous à la fois, répartis en étapes avec navigation précédent/suivant, ou un champ par écran à la manière de Typeform. Les étapes prennent en charge le saut et le branchement conditionnels afin que le parcours à travers le formulaire puisse s'adapter aux réponses du contributeur.

```yaml
forms:
  - id: 1
    name: onboarding
    title: Set up your workspace
    layout: multi-step
    submitTo: { table: workspaces }
    fields:
      - { kind: standalone, name: workspace_name, inputType: short-text, required: true }
      - { kind: standalone, name: team_size, inputType: number }
      - { kind: standalone, name: use_case, inputType: long-text }
    steps:
      - { id: basics, title: The basics, fields: [workspace_name] }
      - { id: team, title: Your team, fields: [team_size] }
      - { id: goals, title: Your goals, fields: [use_case] }
```

## Modes de mise en page

| Mode           | Description                                                                        |
| -------------- | ---------------------------------------------------------------------------------- |
| `single-page`  | Tous les champs sur une seule page (par défaut). Les étapes sont ignorées.         |
| `multi-step`   | Champs regroupés en `steps[]` avec navigation précédent/suivant.                   |
| `one-question` | Un champ par écran, avançant automatiquement. Piloté par le même modèle `steps[]`. |

## Définitions d'étapes

Lorsque `layout` vaut `multi-step` ou `one-question`, le tableau `steps` partitionne les champs du formulaire en écrans ordonnés. Chaque étape référence des noms de champs définis dans le tableau parent `fields`.

| Propriété     | Description                                                                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | Id d'étape unique au sein du formulaire (kebab-case recommandé, ≤64 caractères). Obligatoire.                                                                           |
| `title`       | Titre de l'étape affiché au-dessus des champs.                                                                                                                          |
| `description` | Paragraphe d'introduction de l'étape.                                                                                                                                   |
| `fields`      | Noms de champs appartenant à cette étape. Chacun doit correspondre au `name` d'un champ (standalone/calculation/signature) ou à la `column` (table-field). Au moins un. |
| `visibleWhen` | Règle de visibilité pour toute l'étape. Lorsque faux, l'étape entière est sautée. Utilise la forme [conditionnelle](/fr/form-conditional-logic).                        |
| `goToWhen`    | Règles de branchement. La première règle correspondante saute vers son étape `goTo` plutôt que vers l'étape suivante linéaire.                                          |

## Navigation et branchement

Par défaut, un formulaire multi-étapes avance linéairement : étape 1 → étape 2 → étape 3. Deux mécanismes surchargent ce flux.

**Sauter une étape** avec un `visibleWhen` au niveau de l'étape — lorsque la condition est fausse, l'étape est entièrement retirée de la séquence.

**Brancher vers une étape différente** avec `goToWhen`. Chaque règle a une condition `when` et un id d'étape cible `goTo` ; la première règle correspondante l'emporte, sinon le flux linéaire continue.

```yaml
steps:
  - id: plan
    title: Choose a plan
    fields: [plan]
    goToWhen:
      # Enterprise plans skip self-serve billing and route to a sales step
      - when: { field: plan, operator: eq, value: enterprise }
        goTo: sales
  - id: billing
    title: Payment
    fields: [card_number]
  - id: sales
    title: Talk to sales
    fields: [company, seats]
    # only relevant for enterprise; hidden otherwise
    visibleWhen: { field: plan, operator: eq, value: enterprise }
```

:::callout
**Les cibles `goTo` doivent exister.** Chaque `goToWhen[].goTo` doit correspondre à un `steps[].id` dans le même formulaire. Une étape suivante linéaire est prise dès qu'aucune règle `goToWhen` ne correspond.
:::

## Une question à la fois

La mise en page `one-question` présente un seul champ par écran pour une expérience ciblée et conversationnelle. Elle réutilise le même modèle `steps[]` — typiquement un champ par étape — et le même branchement `visibleWhen` / `goToWhen` s'applique.

```yaml
forms:
  - id: 2
    name: survey
    title: Quick survey
    layout: one-question
    submitTo: { storeSubmission: true }
    display:
      progressBar: true
    fields:
      - {
          kind: standalone,
          name: nps,
          inputType: rating,
          label: How likely are you to recommend us?,
        }
      - {
          kind: standalone,
          name: reason,
          inputType: long-text,
          label: What's the main reason for your score?,
        }
    steps:
      - { id: q1, fields: [nps] }
      - { id: q2, fields: [reason] }
```

## Surcharges d'affichage

L'objet `display` ajuste l'apparence du formulaire sans affecter la sémantique de soumission.

| Propriété     | Description                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `columns`     | Nombre de colonnes dans lesquelles les champs sont disposés (1 à 4). S'applique aux mises en page sur une seule page et par étape. |
| `progressBar` | Affiche une barre de progression dans les mises en page `multi-step` / `one-question`. Aucun effet sur `single-page`.              |
| `submitLabel` | Libellé du bouton de soumission (`Submit` par défaut). Prend en charge les clés `$t:`.                                             |
| `theme`       | Surcharges par formulaire : `primaryColor`, `backgroundColor`, `borderRadius`.                                                     |

```yaml
forms:
  - id: 3
    name: registration
    title: Event registration
    layout: multi-step
    display:
      columns: 2
      progressBar: true
      submitLabel: Complete registration
      theme:
        primaryColor: '#4f46e5'
        borderRadius: 0.5rem
    submitTo: { table: registrations }
    fields:
      - { kind: table-field, column: first_name, required: true }
      - { kind: table-field, column: last_name, required: true }
      - { kind: table-field, column: email, required: true }
      - { kind: table-field, column: dietary_notes }
    steps:
      - { id: name, title: Your name, fields: [first_name, last_name] }
      - { id: contact, title: Contact & preferences, fields: [email, dietary_notes] }
```

## Pages associées

- [Champs de formulaire](/fr/form-fields) — les champs répartis sur les étapes.
- [Logique conditionnelle](/fr/form-conditional-logic) — la forme de condition utilisée par `visibleWhen` et `goToWhen`.
- [Présentation des formulaires](/fr/forms-overview) — `layout`, `steps` et `display` dans le schéma de formulaire complet.
- [Soumissions](/fr/form-submissions) — ce qui se passe après la dernière étape.

# Soumissions de formulaire

Chaque soumission de formulaire produit un enregistrement durable. Par défaut, elle atterrit dans le registre intégré `form_submissions` — le journal canonique de la plateforme « ce formulaire a reçu une réponse » — et, lorsque `submitTo.table` est défini, dans votre propre table également. Les deux écritures sont transactionnelles, vous ne vous retrouvez donc jamais avec une entrée de registre promettant un enregistrement qui n'a jamais été écrit. Après la validation des écritures, `onSuccess` décide ce que le contributeur voit et `onError` couvre les échecs.

```yaml
forms:
  - id: 1
    name: contact
    submitTo:
      table: leads
      # storeSubmission defaults to true — table AND ledger
    fields:
      - { kind: table-field, column: email, required: true }
    onSuccess:
      type: toast
      variant: success
      message: Thanks! We'll be in touch.
```

## Le registre de soumissions

Le registre `form_submissions` réside dans un schéma interne géré par Sovrium (reflétant l'isolation de `auth.*`) — vous ne le créez ni ne le gérez jamais vous-même. Chaque soumission écrit une ligne de registre par défaut ; définissez `submitTo.storeSubmission: false` pour vous désinscrire (auquel cas `table` ou `automation` devient obligatoire).

| Colonne                | Type           | Description                                                                                     |
| ---------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `id`                   | UUID           | Id de soumission stable ; exposé aux modèles `onSuccess` via `$submission.id`.                  |
| `form_name`            | text           | Le `forms[].name` au moment de la soumission.                                                   |
| `form_id`              | integer        | Le `forms[].id` au moment de la soumission (dénormalisé pour les jointures).                    |
| `submitted_at`         | timestamptz    | Horodatage serveur de la création de la ligne.                                                  |
| `submitter_user_id`    | UUID, nullable | L'utilisateur authentifié, lorsque le formulaire requiert l'authentification.                   |
| `submitter_ip`         | inet, nullable | IP du contributeur (stockée hachée par défaut) — utilisée par l'anti-spam et l'audit.           |
| `submitter_user_agent` | text, nullable | Chaîne user-agent du contributeur.                                                              |
| `data`                 | jsonb          | La charge utile complète de réponse validée (reflète ce qui a été écrit dans `submitTo.table`). |
| `linked_record_table`  | text, nullable | Le nom de la table liée, lorsque `submitTo.table` est défini.                                   |
| `linked_record_id`     | text, nullable | L'id de l'enregistrement inséré (typé text pour gérer les id integer / UUID / string).          |
| `status`               | enum           | État du cycle de vie (voir ci-dessous).                                                         |
| `status_reason`        | text, nullable | Brève raison lorsque `status` vaut `failed` ou `spam`.                                          |

## Statut du cycle de vie

| État         | Signification                                                                                | Transitions vers                                           |
| ------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `received`   | Accepté ; écrit dans le registre et la table liée (le cas échéant).                          | `processing` (si automatisation), `done` (sinon).          |
| `processing` | L'automatisation liée s'exécute.                                                             | `done` en cas de succès, `failed` en cas d'échec terminal. |
| `done`       | Terminal — toutes les écritures et l'automatisation liée sont achevées.                      | —                                                          |
| `spam`       | Terminal — le pipeline anti-spam l'a classé comme spam ; conservé pour modération.           | —                                                          |
| `failed`     | Terminal — une étape en aval a échoué et n'a pas été réessayée ; `status_reason` est défini. | —                                                          |

## Le contrat d'écriture double

Lorsque `submitTo.table` est défini, la soumission écrit une ligne dans cette table **et** une ligne de registre au sein d'une seule transaction. Si l'écriture dans la table échoue — violation de contrainte, erreur de type ou clé étrangère manquante — la ligne de registre est annulée elle aussi, et le contributeur reçoit une erreur HTTP 4xx/5xx avec `fieldErrors:[{ name, message }]` nommant la colonne fautive. Aucune entrée de registre « fantôme » n'est jamais laissée derrière.

Lorsque `submitTo.automation` est défini, l'automatisation est invoquée **après** la validation des deux écritures. Un échec d'automatisation **n'annule pas** les écritures — la soumission est enregistrée, `status` passe à `failed`, et la propre machinerie de réessai/échec de l'automatisation s'applique.

```yaml
forms:
  - id: 2
    name: stream-event
    submitTo:
      automation: post-event-to-stream
      storeSubmission: false # opt out — ledger is skipped; automation handles persistence
    fields:
      - { kind: standalone, name: event_payload, inputType: long-text }
```

:::callout
**Ne contournez le registre que lorsque vous le voulez vraiment.** `storeSubmission: false` est le seul moyen de sauter le registre et est destiné aux formulaires à très haut volume qui acheminent vers un flux ou une file d'attente. Chaque fois qu'il est défini, `submitTo` doit toujours spécifier une `table` ou une `automation`, sinon la validation échoue — un formulaire qui ne persiste nulle part est un bug de configuration.
:::

## En cas de succès

L'objet `onSuccess` décide ce que le contributeur voit après une soumission réussie. C'est une union discriminée sur `type`.

| `type`        | Comportement                                                                                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `successPage` | Affiche une page de succès personnalisée (`title`, `message`, `buttonLabel` + `buttonHref` optionnels, `actions[]` optionnels, `showSummary`).                   |
| `redirect`    | Navigue vers `url` après un `delaySeconds` optionnel (par défaut 2 ; `0` est immédiat). Prend en charge les variables de modèle `$submission.id` / `$record.id`. |
| `reset`       | Vide le formulaire pour une nouvelle soumission, avec un `message` optionnel et `preserveFields[]` à conserver.                                                  |
| `toast`       | Affiche un toast transitoire (`message`, `variant` optionnel : `success` / `info`).                                                                              |
| `message`     | Remplace le formulaire par un `message` en ligne à sa place.                                                                                                     |

```yaml
onSuccess:
  type: redirect
  url: /thank-you?ref=$submission.id
  delaySeconds: 0
```

Une `successPage` peut afficher des boutons `actions[]` — chacun est soit `action: reset` (soumettre à nouveau) soit `action: navigate` (lien vers `url`) — et `showSummary: true` liste les valeurs soumises, en respectant les champs masqués et les permissions de lecture par champ.

## En cas d'erreur

L'objet `onError` contrôle le message affiché lorsqu'une soumission échoue côté serveur.

| Propriété | Description                                                                              |
| --------- | ---------------------------------------------------------------------------------------- |
| `type`    | `toast`, `message` (en ligne), ou `errorPage` (page complète).                           |
| `message` | Message du corps. Prend en charge les clés `$t:`.                                        |
| `title`   | Titre optionnel (utilisé par `errorPage`).                                               |
| `variant` | Variante de toast (`error` / `warning`) — significatif uniquement lorsque `type: toast`. |

```yaml
onError:
  type: message
  message: Something went wrong saving your request. Please try again.
```

:::callout
**Les erreurs de validation au niveau du champ sont distinctes.** Les échecs de validation côté serveur (par ex. un e-mail invalide ou une violation de clé étrangère) renvoient HTTP 400 avec une enveloppe `fieldErrors:[{ name, message }]` et sont affichés en ligne sur le champ fautif — indépendamment de `onError`, qui couvre les échecs de soumission entière.
:::

## Pages associées

- [Présentation des formulaires](/fr/forms-overview) — `submitTo`, `storeSubmission`, et le schéma `onSuccess` / `onError`.
- [Champs de formulaire](/fr/form-fields) — `permissions` par champ qui masquent les exports de registre.
- [Téléversements de fichiers](/fr/form-file-uploads) — métadonnées de fichier stockées dans la charge utile `data` du registre.
- [Présentation des tables](/fr/tables-overview) — la table liée que l'écriture double cible.

# Téléversements de fichiers de formulaire

Les formulaires peuvent collecter des fichiers — CV, factures, photos, documents — et les persister dans votre propre stockage plutôt que dans un CDN tiers. Les champs de pièce jointe affichent un sélecteur de fichiers (et une zone de glisser-déposer optionnelle), valident le type et la taille avant le téléversement, montrent la progression et les aperçus, et soumettent un objet de métadonnées canonique `{ url, name, size, mimeType }`. Les fichiers atterrissent dans une destination `app.buckets[]` configurée sur votre stockage S3, disque local ou base de données.

```yaml
buckets:
  - name: applications
    default: true
    backend: s3
    config: { bucket: $env.S3_BUCKET, region: us-east-1 }

forms:
  - id: 1
    name: apply
    title: Job Application
    path: /apply
    submitTo: { table: applications }
    fields:
      - { kind: standalone, name: full_name, inputType: single-line-text, required: true }
      - kind: standalone
        name: resume
        inputType: attachment
        label: Resume
        required: true
        accept: 'application/pdf,.doc,.docx'
        maxFileSize: 10485760 # 10 MB
        dropZone: true
```

## Configuration du champ de pièce jointe

Le comportement de pièce jointe se configure de la même manière sur les deux types de champs : un champ `kind: standalone` avec `inputType: attachment`, ou un champ `kind: table-field` dont la colonne sous-jacente est `single-attachment` / `multiple-attachments`. Les propriétés de téléversement sont partagées.

| Propriété     | Description                                                                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accept`      | Types MIME ou extensions séparés par des virgules restreignant la boîte de dialogue de fichiers (par ex. `image/*`, `application/pdf`, `.doc,.docx`). |
| `maxFileSize` | Taille maximale en octets par fichier. Les fichiers plus volumineux sont rejetés avec une erreur en ligne avant le début du téléversement.            |
| `maxFiles`    | Nombre maximal de fichiers (champs multi-fichiers uniquement). En sélectionner davantage affiche une erreur en ligne.                                 |
| `dropZone`    | Affiche une zone de glisser-déposer à côté du sélecteur, acceptant les mêmes fichiers.                                                                |

:::callout
**Simple vs multiple.** Une pièce jointe simple soumet un objet `FileMetadata` (ou `null` lorsqu'elle est vide) ; une pièce jointe multiple soumet un tableau `FileMetadata[]` (ou `[]`). Pour les champs liés à une table, la multiplicité est déduite du type de colonne (`single-attachment` vs `multiple-attachments`) ; pour les champs autonomes, elle suit l'interface de téléversement présentée par `inputType: attachment` et `maxFiles`.
:::

## Liaison au bucket

La destination de stockage provient de `app.buckets[]`. Un formulaire hérite d'un **bucket par défaut** : le bucket dont l'indicateur `default: true` est défini, ou le seul bucket lorsqu'un seul est défini. Les fichiers y sont téléversés à la soumission, et la charge utile du formulaire porte les métadonnées canoniques de chaque fichier. Les surcharges de bucket par champ sont réservées à une version ultérieure.

```yaml
buckets:
  - name: documents
    default: true
    backend: local
    config: { path: ./storage/documents }

forms:
  - id: 2
    name: invoice-upload
    title: Upload Invoice
    submitTo: { automation: process-invoice }
    fields:
      - { kind: standalone, name: vendor, inputType: single-line-text, required: true }
      - kind: standalone
        name: document
        inputType: attachment
        accept: 'application/pdf,image/*'
        maxFileSize: 20971520 # 20 MB
        dropZone: true
```

## Expérience de téléversement

Le champ de pièce jointe affiche une expérience de téléversement complète :

| Comportement                | Description                                                                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filtre de type              | `accept` restreint à la fois la boîte de dialogue du navigateur et le glisser-déposer ; les fichiers non conformes affichent une erreur en ligne.        |
| Validation de taille        | `maxFileSize` rejette les fichiers trop volumineux avant le début du téléversement.                                                                      |
| Indicateur de progression   | Une barre de progression ou un indicateur de chargement est affiché pendant le téléversement de chaque fichier.                                          |
| Aperçu                      | Les fichiers image affichent une vignette après le téléversement ; les fichiers non image affichent le nom + la taille.                                  |
| Suppression                 | Les fichiers sélectionnés peuvent être supprimés avant la soumission (accessible au clavier) ; en supprimer un parmi plusieurs n'affecte pas les autres. |
| Application de l'obligation | Un champ de pièce jointe `required` sans fichier bloque la soumission avec une erreur en ligne.                                                          |

## Forme des métadonnées de fichier

Lorsque le formulaire est soumis, chaque valeur de pièce jointe est normalisée en un objet de métadonnées canonique — la même forme consommée par `submitTo.table`, les déclencheurs `submitTo.automation`, et la charge utile `data` du registre `form_submissions`.

```typescript
type FileMetadata = {
  url: string // canonical URL into the bucket (signed when the bucket is private)
  name: string // original filename
  size: number // bytes
  mimeType: string // detected MIME type
}
```

Un champ simple soumet `FileMetadata | null` ; un champ multiple soumet `FileMetadata[]`. Acheminer le téléversement vers une automatisation rend les mêmes métadonnées disponibles dans la charge utile du déclencheur — par exemple pour exécuter une extraction par IA sur `{{trigger.data.document.url}}`.

## Pages associées

- [Champs de formulaire](/fr/form-fields) — les types de champs que les téléversements de pièces jointes étendent.
- [Présentation des formulaires](/fr/forms-overview) — les cibles `submitTo` qui reçoivent les métadonnées de fichier.
- [Soumissions](/fr/form-submissions) — métadonnées de fichier stockées dans la charge utile `data` du registre.
- [Buckets](/fr/buckets-overview) — configurer les backends de stockage S3, local et base de données.

# Présentation de l'authentification

Sovrium propose l'authentification comme une capacité de plateforme de premier ordre, propulsée par [Better Auth](https://better-auth.com). Un unique bloc `auth` dans la configuration de votre application active l'inscription, la connexion, les sessions, le contrôle d'accès basé sur les rôles et la gestion administrateur des utilisateurs — aucun code d'authentification à écrire.

Le bloc `auth` répond à une seule question : **cette application a-t-elle des utilisateurs ?** Lorsqu'il est présent, l'authentification est activée ; lorsqu'il est omis, chaque route `/api/auth/*` renvoie `404` et l'application est entièrement publique.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
```

Cette configuration de quatre lignes vous offre une inscription et une connexion par e-mail/mot de passe fonctionnelles, des sessions gérées côté serveur, les trois rôles intégrés et les points de terminaison de gestion administrateur des utilisateurs.

## Activer l'authentification

L'authentification est activée par la **présence** de l'objet `auth`. Il n'existe pas de drapeau `auth.enabled: true`.

| État           | Résultat                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auth` omis    | L'application est publique. Toutes les routes `/api/auth/*` renvoient `404`. Pas d'identité, pas de sessions.                                                      |
| `auth` présent | L'authentification est activée. Les routes d'inscription/connexion sont montées, les sessions sont émises, le RBAC et les fonctions d'administration s'appliquent. |

Au minimum, le bloc `auth` exige un tableau `strategies` non vide (au moins une stratégie, sans types en double). Tout le reste est optionnel et vient s'ajouter par-dessus.

:::callout
**Les fonctions d'administration sont toujours actives.** Lorsque `auth` est configuré, les points de terminaison de gestion des utilisateurs, d'attribution des rôles et d'usurpation d'identité sont montés automatiquement — il n'y a pas de bascule distincte. Le premier utilisateur à s'inscrire devient administrateur (`firstUserAdmin`).
:::

## Le bloc de configuration `auth`

L'objet `auth` accepte les propriétés de premier niveau suivantes. Chacune renvoie à sa page dédiée.

| Propriété               | Description                                                                                                                                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `strategies`            | **Obligatoire.** Tableau de stratégies d'authentification (e-mail/mot de passe, lien magique, OAuth). Au moins une ; sans types en double. Voir [Stratégies](/fr/auth-strategies).                   |
| `allowSignUp`           | Booléen. Contrôle l'auto-inscription. `true` (par défaut) permet à quiconque de s'inscrire ; `false` réserve la création d'utilisateurs aux administrateurs. Voir [Stratégies](/fr/auth-strategies). |
| `roles`                 | Tableau de définitions de rôles personnalisés ajoutées par-dessus les rôles intégrés. Voir [Rôles & RBAC](/fr/auth-roles-rbac).                                                                      |
| `defaultRole`           | Rôle attribué aux nouveaux utilisateurs lors de leur inscription. Par défaut `member`. Voir [Rôles & RBAC](/fr/auth-roles-rbac).                                                                     |
| `groups`                | Groupes d'utilisateurs pour une appartenance plusieurs-à-plusieurs et des permissions à l'échelle d'un groupe. Voir [Groupes](/fr/auth-groups).                                                      |
| `twoFactor`             | Authentification à deux facteurs basée sur TOTP. Nécessite la stratégie `emailAndPassword`. Voir [Deux facteurs](/fr/auth-two-factor).                                                               |
| `emailTemplates`        | Objet et corps personnalisés pour les e-mails d'authentification (vérification, réinitialisation, lien magique, OTP, invitation, …). Voir [Stratégies](/fr/auth-strategies).                         |
| `invitationTokenExpiry` | Durée de vie des jetons d'invitation administrateur à usage unique. Chaîne de durée (`72h`, `7d`) ou millisecondes. Par défaut `72h`.                                                                |
| `scopeTables`           | Tables référencées par la table de jonction multi-locataire `user_access`. Pilote le périmètre `$currentUser.assignments`. Voir [Sessions](/fr/auth-sessions).                                       |
| `landingPath`           | Chemin de montage du résolveur de moteur pour l'atterrissage après connexion par rôle. Voir [Atterrissage après connexion](/fr/auth-post-login).                                                     |
| `noAccessPath`          | Chemin de repli lorsqu'aucun `defaultLanding` de rôle ne correspond à la session. Par défaut `/403`. Voir [Atterrissage après connexion](/fr/auth-post-login).                                       |

Les secrets d'infrastructure (clés de signature, URL de rappel, identifiants OAuth) résident dans les variables d'environnement — **pas** dans ce schéma. Voir [Variables d'environnement](/fr/env-vars).

## Rôles par défaut

Chaque application Sovrium dont l'authentification est configurée dispose de trois rôles intégrés, disponibles sans aucune configuration. Ils ne peuvent pas être redéfinis.

| Rôle     | Niveau | Accès                                                                                                |
| -------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `admin`  | 80     | Accès complet — gérer les utilisateurs, les rôles, les paramètres ; toutes les permissions de table. |
| `member` | 40     | Accès standard aux ressources de l'application (le rôle par défaut des nouveaux utilisateurs).       |
| `viewer` | 10     | Accès en lecture seule.                                                                              |

Le **niveau** numérique établit une hiérarchie (plus élevé = plus privilégié) utilisée par la résolution des permissions. Les rôles personnalisés s'insèrent dans cette hiérarchie avec leur propre `level`. Voir [Rôles & RBAC](/fr/auth-roles-rbac) pour les définitions, la hiérarchie et les rôles administrateur.

## Variables d'environnement requises

Deux variables d'environnement sont requises pour l'authentification en production :

| Variable      | Rôle                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_SECRET` | Clé secrète pour signer les jetons et chiffrer les sessions. Utilisez une chaîne aléatoire forte (32+ caractères).                    |
| `BASE_URL`    | URL de base de l'application (par ex. `https://myapp.com`). Utilisée pour les URL de rappel d'authentification et les liens d'e-mail. |

```bash
AUTH_SECRET=your-strong-random-secret-32-chars-min
BASE_URL=https://myapp.com
```

:::callout
**Ne committez jamais `AUTH_SECRET`.** Traitez-le comme un mot de passe de base de données. Sa rotation invalide toutes les sessions actives. Voir [Variables d'environnement](/fr/env-vars) pour la liste complète, y compris les paires OAuth `{PROVIDER}_CLIENT_ID` / `{PROVIDER}_CLIENT_SECRET`.
:::

## Exemple complet

```yaml
auth:
  # Two ways in: credentials + Google social login
  strategies:
    - type: emailAndPassword
      minPasswordLength: 12
      requireEmailVerification: true
    - type: oauth
      providers: [google, github]

  # Self-registration on, new users start as viewers
  allowSignUp: true
  defaultRole: viewer

  # One extra role beyond the built-ins
  roles:
    - name: editor
      description: Can edit content
      level: 30

  # Group membership for field-level permissions
  groups:
    - name: marketing
    - name: finance

  # TOTP 2FA (requires emailAndPassword above)
  twoFactor:
    issuer: MyApp
    backupCodes: true
```

## Pour aller plus loin

- [Stratégies](/fr/auth-strategies) — e-mail/mot de passe, lien magique, OTP par e-mail, connexion sociale/OAuth, contrôle de l'inscription et modèles d'e-mail.
- [Rôles & RBAC](/fr/auth-roles-rbac) — définitions de rôles, hiérarchie et rôles administrateur.
- [Groupes](/fr/auth-groups) — appartenance plusieurs-à-plusieurs et permissions basées sur les groupes.
- [Sessions](/fr/auth-sessions) — configuration des sessions, révocation et sessions à périmètre actif.
- [Deux facteurs](/fr/auth-two-factor) — configuration TOTP et codes de récupération.
- [Serveur OAuth](/fr/auth-oauth-server) — Sovrium en tant que serveur d'autorisation OAuth/OIDC.
- [Atterrissage après connexion](/fr/auth-post-login) — atterrissage par rôle et interpolation `$currentUser.assignments`.
- [Permissions de table](/fr/table-permissions) — comment les rôles et les groupes contrôlent l'accès par table et par champ.

# Stratégies d'authentification

`auth.strategies` est un **tableau obligatoire et non vide** déclarant comment les utilisateurs s'authentifient. Chaque entrée est une union discriminée indexée par `type`. Au moins une stratégie est requise, et **deux entrées ne peuvent jamais partager le même `type`**.

```yaml
auth:
  strategies:
    - type: emailAndPassword
    - type: oauth
      providers: [google, github]
```

| `type`             | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `emailAndPassword` | Inscription et connexion traditionnelles par identifiants.                       |
| `magicLink`        | Connexion sans mot de passe via un lien e-mail à usage unique.                   |
| `oauth`            | Connexion sociale avec des fournisseurs d'identité externes (Google, GitHub, …). |

:::callout
**L'OTP par e-mail s'active différemment.** Il n'existe pas de stratégie `type: emailOtp`. L'OTP par e-mail s'active automatiquement lorsque vous fournissez un modèle `auth.emailTemplates.emailOtp` (voir [OTP par e-mail](#email-otp) ci-dessous).
:::

## E-mail & mot de passe

La stratégie la plus courante. Les identifiants sont validés côté serveur et une session est émise en cas de succès.

```yaml
auth:
  strategies:
    - type: emailAndPassword
      minPasswordLength: 12
      maxPasswordLength: 128
      requireEmailVerification: true
      autoSignIn: true
```

| Propriété                  | Description                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `minPasswordLength`        | Longueur minimale du mot de passe, 6–128. Par défaut `8`.                                                         |
| `maxPasswordLength`        | Longueur maximale du mot de passe, 8–256. Par défaut `128`.                                                       |
| `requireEmailVerification` | Booléen. Lorsque `true`, les utilisateurs doivent vérifier leur e-mail avant de se connecter. Par défaut `false`. |
| `autoSignIn`               | Booléen. Lorsque `true`, les utilisateurs sont connectés automatiquement après l'inscription. Par défaut `true`.  |

Lorsque `requireEmailVerification: true`, un e-mail de vérification est envoyé à l'inscription à l'aide du modèle `verification` (voir [Modèles d'e-mail](#email-templates)).

## Lien magique

Authentification sans mot de passe. L'utilisateur saisit son e-mail, reçoit un lien à usage unique, et se connecte en cliquant dessus. Nécessite la configuration de SMTP (voir [Variables d'environnement](/fr/env-vars)).

```yaml
auth:
  strategies:
    - type: magicLink
      expirationMinutes: 30
```

| Propriété           | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `expirationMinutes` | Durée de vie du lien en minutes (entier positif). Par défaut `15`. |

Le corps du lien est rendu à partir du modèle d'e-mail `magicLink` lorsqu'il est fourni.

## OTP par e-mail

L'OTP par e-mail délivre un code numérique à usage unique par e-mail au lieu d'un lien. **Ce n'est pas une entrée de stratégie** — il s'active lorsque vous définissez le modèle d'e-mail `emailOtp` :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  emailTemplates:
    emailOtp:
      subject: Your sign-in code
      text: 'Your verification code is $code. It expires shortly.'
```

La présence de `emailTemplates.emailOtp` monte le plugin d'OTP par e-mail. La variable `$code` est remplacée par le code à usage unique généré.

## Fournisseurs sociaux / OAuth

Connexion fédérée via des fournisseurs d'identité externes. Les identifiants ne sont **jamais** dans le schéma — ils sont chargés depuis les variables d'environnement.

```yaml
auth:
  strategies:
    - type: oauth
      providers: [google, github, microsoft, slack, gitlab]
```

| Propriété   | Description                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `providers` | Tableau non vide d'identifiants de fournisseurs. Identifiants chargés depuis les variables d'environnement. |

Fournisseurs pris en charge :

| Fournisseur | Cas d'usage                        |
| ----------- | ---------------------------------- |
| `google`    | Intégration Google Workspace.      |
| `github`    | Authentification des développeurs. |
| `microsoft` | Entreprise / Azure AD.             |
| `slack`     | Communication d'espace de travail. |
| `gitlab`    | Intégration développeur / CI-CD.   |

Chaque fournisseur activé nécessite une paire d'identifiants dans l'environnement :

```bash
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
```

La forme générale est `{PROVIDER}_CLIENT_ID` et `{PROVIDER}_CLIENT_SECRET`. Les URL de rappel sont dérivées de `BASE_URL`. Voir [Variables d'environnement](/fr/env-vars).

## Contrôle de l'inscription

`auth.allowSignUp` détermine si le public peut créer ses propres comptes.

```yaml
auth:
  allowSignUp: false
  strategies:
    - type: emailAndPassword
```

| Valeur              | Comportement                                                                                                                                    |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `true` (par défaut) | Quiconque peut s'auto-inscrire via les stratégies activées.                                                                                     |
| `false`             | L'auto-inscription est désactivée. Seuls les administrateurs créent des utilisateurs via `POST /api/auth/admin/create-user` ou des invitations. |

Lorsque l'auto-inscription est désactivée, les administrateurs intègrent les utilisateurs avec des jetons d'invitation à usage unique :

```yaml
auth:
  allowSignUp: false
  strategies:
    - type: emailAndPassword
  invitationTokenExpiry: 7d
```

| Propriété               | Description                                                                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `invitationTokenExpiry` | Durée de vie des jetons issus de `POST /api/auth/admin/invite-user`. Chaîne de durée (`72h`, `7d`) ou millisecondes. Par défaut `72h`. |

:::callout
Des expirations plus courtes conviennent aux portails clients à haute sécurité ; la valeur par défaut `72h` convient à l'intégration B2B où les invités ne consultent pas forcément leur e-mail immédiatement. Les jetons d'invitation sont à usage unique et consommés lors de la première acceptation réussie.
:::

## Modèles d'e-mail

`auth.emailTemplates` personnalise l'objet et le corps des e-mails d'authentification. Chaque modèle est optionnel — Better Auth fournit des valeurs par défaut judicieuses. Définir le modèle `emailOtp` **active** en outre le flux d'OTP par e-mail.

```yaml
auth:
  strategies:
    - type: emailAndPassword
    - type: magicLink
  emailTemplates:
    verification:
      subject: Verify your email for MyApp
      text: 'Hi $name, confirm your email: $url'
    resetPassword:
      subject: Reset your password
      text: 'Reset your password: $url'
      html: '<p>Click <a href="$url">here</a> to reset your password.</p>'
    magicLink:
      subject: Your sign-in link
      text: 'Sign in to MyApp: $url'
```

| Modèle                 | Quand il est envoyé                                                     |
| ---------------------- | ----------------------------------------------------------------------- |
| `verification`         | Vérification de l'e-mail après l'inscription.                           |
| `resetPassword`        | Demande de réinitialisation du mot de passe.                            |
| `magicLink`            | Connexion par lien magique.                                             |
| `emailOtp`             | Code e-mail à usage unique (sa présence active l'OTP par e-mail).       |
| `twoFactorBackupCodes` | Envoi des codes de secours à deux facteurs.                             |
| `welcome`              | E-mail de bienvenue après la vérification.                              |
| `accountDeletion`      | Confirmation de suppression de compte.                                  |
| `invitation`           | Invitation émise par un administrateur (intégration sans mot de passe). |

Chaque modèle accepte un `subject` obligatoire et des corps `text` et/ou `html` optionnels. Les corps prennent en charge la substitution `$variable` :

| Variable            | Signification                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `$url`              | Lien d'action (vérifier, réinitialiser, lien magique, accepter une invitation).            |
| `$name`             | Nom du destinataire.                                                                       |
| `$email`            | Adresse e-mail du destinataire.                                                            |
| `$code`             | Code à usage unique (OTP par e-mail).                                                      |
| `$organizationName` | Nom de l'organisation (invitations).                                                       |
| `$inviterName`      | Nom de l'administrateur qui a envoyé l'invitation (invitations administrateur uniquement). |

:::callout
Les e-mails de lien magique, d'OTP par e-mail, de réinitialisation du mot de passe et de vérification nécessitent tous SMTP. Lorsque SMTP n'est pas défini, l'application démarre avec l'e-mail désactivé et consigne un avertissement — ces stratégies ne pourront pas délivrer leurs messages. Voir [Variables d'environnement](/fr/env-vars).
:::

## Pages associées

- [Présentation de l'authentification](/fr/auth-overview) — le bloc `auth` et la place des stratégies.
- [Sessions](/fr/auth-sessions) — ce qui se passe après une connexion réussie.
- [Deux facteurs](/fr/auth-two-factor) — ajouter le TOTP par-dessus l'e-mail/mot de passe.
- [Variables d'environnement](/fr/env-vars) — `AUTH_SECRET`, `BASE_URL` et identifiants OAuth.

# Rôles & RBAC

Sovrium utilise le **contrôle d'accès basé sur les rôles (RBAC)** avec une couche optionnelle de [groupes](/fr/auth-groups). Chaque utilisateur authentifié possède exactement un rôle ; les rôles sont organisés selon une **hiérarchie** numérique ; et les [permissions de table](/fr/table-permissions) référencent les rôles pour contrôler la création/lecture/mise à jour/suppression et l'accès par champ.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
  roles:
    - name: editor
      description: Can edit content
      level: 30
```

## Rôles intégrés

Trois rôles sont fournis avec chaque application dont l'authentification est activée. Ils sont toujours disponibles et **ne peuvent pas être redéfinis** par des rôles personnalisés.

| Rôle     | Niveau | Accès                                                                                         |
| -------- | ------ | --------------------------------------------------------------------------------------------- |
| `admin`  | 80     | Accès complet — gérer les utilisateurs, les rôles et les paramètres ; toutes les permissions. |
| `member` | 40     | Accès standard aux ressources de l'application.                                               |
| `viewer` | 10     | Accès en lecture seule.                                                                       |

## Hiérarchie & niveaux de rôle

Chaque rôle possède un `level` numérique. Les niveaux plus élevés sont plus privilégiés. Le niveau établit un ordre utilisé par la résolution des permissions et par les fonctionnalités qui comparent l'ancienneté des rôles (par exemple, un rôle équivalent à un administrateur est celui qui se situe au niveau configuré le plus élevé).

Les niveaux intégrés sont fixés à `admin=80`, `member=40`, `viewer=10`. Les rôles personnalisés s'insèrent n'importe où sur cette échelle via leur propre `level` :

```yaml
auth:
  roles:
    - name: editor
      level: 30 # between viewer (10) and member (40)
    - name: moderator
      level: 50 # between member (40) and admin (80)
```

:::callout
**Le plus permissif l'emporte.** Lorsque les permissions d'un utilisateur proviennent de plusieurs sources (son rôle et ses groupes), c'est l'union des opérations accordées qui s'applique. Si le rôle accorde `read` et qu'un groupe accorde `update`, l'utilisateur obtient les deux. Voir [Groupes](/fr/auth-groups).
:::

## Définitions de rôles personnalisés

`auth.roles` est un tableau de définitions de rôles personnalisés ajoutées par-dessus les rôles intégrés. Un tableau vide (ou l'omission du champ) signifie que seuls les rôles intégrés existent.

```yaml
auth:
  roles:
    - name: editor
      description: Can edit content
      level: 30
    - name: moderator
      level: 20
    - name: contributor
```

| Propriété        | Description                                                                                                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | **Obligatoire.** Identifiant du rôle. Minuscules, alphanumérique, traits d'union ; doit commencer par une lettre. Doit être unique et ne doit pas entrer en conflit avec le nom d'un rôle intégré ou d'un groupe. |
| `description`    | Description lisible de la finalité du rôle.                                                                                                                                                                       |
| `level`          | Niveau de hiérarchie (plus élevé = plus privilégié). Références intégrées : `admin=80`, `member=40`, `viewer=10`.                                                                                                 |
| `defaultLanding` | URL d'atterrissage après connexion par rôle. Voir [Atterrissage après connexion](/fr/auth-post-login).                                                                                                            |
| `pickerLanding`  | Repli multi-enregistrements pour un `defaultLanding` à modèle. Voir [Atterrissage après connexion](/fr/auth-post-login).                                                                                          |

**Règles de nommage** — les noms de rôle correspondent à `^[a-z][a-z0-9-]*$` :

| Nom               | Valide ? | Raison                        |
| ----------------- | -------- | ----------------------------- |
| `editor`          | ✅       | lettres minuscules            |
| `content-manager` | ✅       | trait d'union autorisé        |
| `Editor`          | ❌       | majuscule non autorisée       |
| `123role`         | ❌       | doit commencer par une lettre |

La validation rejette :

- Les noms de rôle personnalisés en double.
- Les noms personnalisés qui entrent en conflit avec les rôles intégrés (`admin`, `member`, `viewer`).
- Les noms personnalisés qui entrent en conflit avec un nom de [groupe](/fr/auth-groups) (les rôles et les groupes partagent un espace de noms).

## Rôle par défaut

`auth.defaultRole` est le rôle attribué aux nouveaux utilisateurs lors de leur inscription. Il vaut `member` par défaut lorsqu'il est omis, et doit référencer un rôle intégré **ou** un rôle personnalisé défini dans `auth.roles`.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: viewer # new users start read-only
  roles:
    - name: editor
      level: 30
```

| Propriété     | Description                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `defaultRole` | Rôle accordé aux utilisateurs nouvellement inscrits. Nom intégré ou personnalisé. Par défaut `member`. |

:::callout
Un `defaultRole` référençant un rôle personnalisé non défini échoue à la validation au démarrage. Définissez le rôle dans `auth.roles` avant de le nommer comme rôle par défaut. Définir `defaultRole: viewer` est un schéma courant pour les applications où les nouveaux utilisateurs doivent rester en lecture seule jusqu'à ce qu'un administrateur les promeuve.
:::

## Rôles administrateur

Lorsque `auth` est configuré, la surface de gestion administrateur des utilisateurs est toujours montée (il n'y a pas de bascule distincte). Le **premier utilisateur à s'inscrire devient administrateur** (`firstUserAdmin`). Les administrateurs peuvent :

- Créer des utilisateurs (`POST /api/auth/admin/create-user`) — y compris lorsque `allowSignUp: false`.
- Inviter des utilisateurs avec des jetons à usage unique (`POST /api/auth/admin/invite-user`).
- Attribuer et modifier des rôles.
- Usurper l'identité d'utilisateurs pour les flux de support.
- Bannir / débannir des utilisateurs.

Le rôle du niveau le plus élevé est traité comme équivalent à un administrateur pour ces vérifications, de sorte qu'un rôle personnalisé à `level: 80` (ou plus) participe au contrôle d'administration aux côtés du rôle intégré `admin`.

## Comment les rôles contrôlent les données

Les rôles n'accordent pas l'accès aux données par eux-mêmes — ils sont référencés par le bloc `permissions` de chaque table. Un rôle sans entrée de permission correspondante n'a aucun accès à cette table. Voir [Permissions de table](/fr/table-permissions) pour le modèle complet de création/lecture/mise à jour/suppression/restauration/commentaire et par champ, y compris la façon dont les entrées préfixées par `group:` se combinent avec les rôles.

## Pages associées

- [Présentation de l'authentification](/fr/auth-overview) — les rôles par défaut en contexte.
- [Groupes](/fr/auth-groups) — appartenance plusieurs-à-plusieurs ajoutée par-dessus les rôles.
- [Atterrissage après connexion](/fr/auth-post-login) — règles d'atterrissage par rôle.
- [Permissions de table](/fr/table-permissions) — là où les rôles contrôlent réellement les données.

# Groupes

Les **groupes** complètent les [rôles](/fr/auth-roles-rbac) en ajoutant une couche plusieurs-à-plusieurs : un utilisateur possède exactement un rôle, mais peut appartenir à **n'importe quel nombre de groupes**. Les permissions peuvent référencer les groupes avec le préfixe `group:`, ce qui les rend idéaux pour l'accès à l'échelle d'une équipe et au niveau du champ.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  groups:
    - name: marketing
    - name: finance
      description: Finance team with access to financial data
    - name: project-alpha
      description: Cross-functional team
      maxMembers: 50
```

Les équipes sont configurées via les groupes — définissez un groupe par équipe (ingénierie, marketing, …) et référencez-le dans les permissions.

## Définir des groupes

`auth.groups` est un tableau de définitions de groupes.

| Propriété     | Description                                                                                                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | **Obligatoire.** Identifiant du groupe. Minuscules, alphanumérique, traits d'union ; doit commencer par une lettre. Doit être unique et ne doit pas entrer en conflit avec le nom d'un rôle. |
| `description` | Description lisible de la finalité du groupe.                                                                                                                                                |
| `maxMembers`  | Nombre maximal de membres (entier ≥ 1). Illimité lorsqu'il est omis.                                                                                                                         |

**Règles de nommage** — les noms de groupe correspondent à `^[a-z][a-z0-9-]*$` (la même convention que les noms de rôle) :

| Nom             | Valide ? | Raison                        |
| --------------- | -------- | ----------------------------- |
| `marketing`     | ✅       | lettres minuscules            |
| `dev-team`      | ✅       | trait d'union autorisé        |
| `project-alpha` | ✅       | trait d'union autorisé        |
| `Marketing`     | ❌       | majuscule non autorisée       |
| `123team`       | ❌       | doit commencer par une lettre |

:::callout
**Les rôles et les groupes partagent un seul espace de noms.** Un groupe nommé `admin` est rejeté car il entre en conflit avec le rôle intégré. Gardez les noms de groupe distincts de tous les noms de rôle intégrés et personnalisés. La validation rejette aussi les noms de groupe en double.
:::

## Appartenance

Un utilisateur peut être membre de plusieurs groupes simultanément. L'appartenance est gérée à l'exécution (attribuée par les administrateurs ou par les [automatisations](/fr/automations-overview)) — le schéma déclare quels groupes _existent_, pas qui en fait partie. Lorsque `maxMembers` est défini, les tentatives d'ajout d'un membre au-delà du plafond sont rejetées.

## Permissions basées sur les groupes

Référencez un groupe dans le bloc `permissions` d'une table en préfixant son nom par `group:`. Les entrées de groupe se placent aux côtés des noms de rôle dans les mêmes tableaux de permissions :

```yaml
tables:
  - id: 1
    name: Campaigns
    fields:
      - { id: 1, name: title, type: single-line-text, required: true }
      - { id: 2, name: budget, type: number }
    permissions:
      read: [member, 'group:marketing']
      update: ['group:marketing']
      # field-level: only finance can read the budget column
      fields:
        budget:
          read: ['group:finance']
```

| Forme d'entrée    | Signification                                     |
| ----------------- | ------------------------------------------------- |
| `member`          | Accorder à toute personne ayant le rôle `member`. |
| `group:marketing` | Accorder à chaque membre du groupe `marketing`.   |
| `admin`           | Accorder au rôle `admin`.                         |

La résolution des permissions suit le principe **le plus permissif l'emporte** : les permissions effectives d'un utilisateur sont l'union de celles accordées par son rôle et par chaque groupe auquel il appartient. Si le rôle d'un utilisateur accorde `read` et que son groupe `marketing` accorde `update`, il obtient les deux.

:::callout
Les groupes brillent pour les **permissions au niveau du champ** — par ex. exposer une colonne `salary` ou `budget` uniquement à un `group:finance` tandis que le reste de la table est largement lisible. Voir [Permissions de table](/fr/table-permissions) pour le modèle complet au niveau du champ.
:::

## Pages associées

- [Rôles & RBAC](/fr/auth-roles-rbac) — la couche à rôle unique sur laquelle s'appuient les groupes.
- [Permissions de table](/fr/table-permissions) — modèle complet de permission `group:` et au niveau du champ.
- [Automatisations](/fr/automations-overview) — attribuer des utilisateurs à des groupes en réponse à des événements.

# Sessions

Lorsqu'un utilisateur s'authentifie, Sovrium émet une **session gérée côté serveur** (un cookie `httpOnly` adossé à une ligne de la table `auth.session`). Les sessions sont inspectables, listables et révocables via l'API d'authentification et — pour les applications multi-locataires — augmentées par une **API de session à périmètre actif** qui permet à un utilisateur de choisir l'affectation actuellement en contexte.

## Configuration des sessions

Le comportement central des sessions (durée de vie, fenêtre de rafraîchissement) est géré au **niveau du serveur Better Auth**, pas dans le schéma de l'application. Il n'y a pas de bloc de configuration `auth.session`.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  # Session lifetime/refresh are Better Auth server defaults — not schema fields.
```

| Préoccupation                              | Où elle réside                                                                          |
| ------------------------------------------ | --------------------------------------------------------------------------------------- |
| Durée de vie / rafraîchissement de session | Valeurs par défaut du serveur Better Auth (non exposées dans `app.auth`).               |
| Signature & chiffrement                    | Variable d'environnement `AUTH_SECRET`. Voir [Variables d'environnement](/fr/env-vars). |
| Sécurité du cookie                         | Cookies `secure` en production ; dérivés de `BASE_URL` / `NODE_ENV`.                    |

:::callout
La rotation de `AUTH_SECRET` invalide toutes les sessions actives — tous les utilisateurs sont déconnectés. Traitez-le comme un identifiant et effectuez sa rotation de manière réfléchie. Voir [Renforcement de la sécurité](/fr/security-hardening).
:::

## Inspecter & terminer des sessions

Les points de terminaison suivants sont montés automatiquement lorsque `auth` est configuré.

| Méthode | Point de terminaison              | Rôle                                                                     |
| ------- | --------------------------------- | ------------------------------------------------------------------------ |
| `GET`   | `/api/auth/get-session`           | Renvoie la session et l'utilisateur courants, ou un corps null si aucun. |
| `GET`   | `/api/auth/list-sessions`         | Liste toutes les sessions actives de l'utilisateur authentifié.          |
| `POST`  | `/api/auth/sign-out`              | Invalide la session courante (idempotent — toujours `200`).              |
| `POST`  | `/api/auth/revoke-session`        | Révoque une session spécifique par son id.                               |
| `POST`  | `/api/auth/revoke-other-sessions` | Révoque toutes les sessions sauf la session courante.                    |

Comportements à noter :

- `get-session` renvoie un **corps null** (et non une erreur) lorsqu'on n'est pas authentifié ou après la déconnexion, de sorte qu'un client peut l'interroger en toute sécurité pour afficher l'état d'authentification.
- `list-sessions` est **isolé par session** — un utilisateur ne voit jamais que ses propres sessions, chacune avec `id`, `userId`, horodatages de création et d'expiration.
- `sign-out` est **idempotent** : l'appeler sans session, ou de manière répétée, renvoie toujours `200`.

## Sessions à périmètre actif (multi-locataire)

Les applications qui cloisonnent les données par locataire utilisent la jonction `user_access` : un utilisateur peut avoir plusieurs lignes d'accès pour la même table (par ex. un directeur financier à temps partagé affecté à trois entreprises clientes). L'**API de session à périmètre actif** permet à cet utilisateur de choisir l'affectation actuellement active, persistée dans un cookie par table et résolue par `$currentUser.activeAssignment`.

D'abord, déclarez les tables de périmètre :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  roles:
    - name: customer-admin
  scopeTables: [clients]
  landingPath: /portal
  # No extra config — active-scope endpoints auto-mount for every scopeTables entry.
```

| Propriété     | Description                                                                                                                                                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scopeTables` | Tableau de slugs de table (issus de `app.tables[].name`) que les lignes `user_access` peuvent référencer. Non vide ; les entrées doivent être des identifiants slug valides ; sans doublons. Validé contre `app.tables[].name` au démarrage. |

Le moteur monte ensuite automatiquement ces points de terminaison pour chaque entrée de `scopeTables` :

| Méthode  | Chemin                                 | Comportement                                                                                                                                                             |
| -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST`   | `/api/session/active-scope/:tableSlug` | Corps `{ recordId }`. Définit le cookie de périmètre actif lorsque `recordId` figure dans le `user_access` de l'utilisateur ; renvoie `403` sinon (aucun cookie défini). |
| `GET`    | `/api/session/active-scope/:tableSlug` | Renvoie `{ tableSlug, recordId }` depuis le cookie, ou `null` lorsqu'il n'est pas défini.                                                                                |
| `DELETE` | `/api/session/active-scope/:tableSlug` | Efface le cookie (renvoie `204`).                                                                                                                                        |

Un `:tableSlug` absent de `scopeTables` renvoie `404`.

### Modèle de sécurité

Le cookie de périmètre actif est nommé `sovrium_active_assignment_<tableSlug>` (un par table de périmètre).

1. **Attributs du cookie** — `httpOnly`, `sameSite=lax`, et `secure` en production. Non lisible par le JavaScript client.
2. **Toute écriture est validée côté serveur** — `POST` vérifie que le `recordId` figure dans les lignes `user_access` de l'utilisateur pour ce slug. Les écritures hors périmètre renvoient `403` sans changement d'état.
3. **Toute lecture est validée côté serveur** — lors de la résolution de `$currentUser.activeAssignment`, le moteur revérifie le cookie contre `user_access`. Les valeurs falsifiées, obsolètes ou désormais révoquées sont écartées et le résolveur se replie sur le premier enregistrement accessible de l'utilisateur.

:::callout
**Inviolable par construction.** Un utilisateur ne peut pas modifier le cookie pour atteindre un enregistrement hors de ses affectations — la valeur est revalidée contre `user_access` à chaque requête, à la fois lors de sa définition et de sa lecture. Cela rend le changement de contexte sûr sans nouvelle authentification.
:::

`$currentUser.activeAssignment` est consommable dans les prédicats `dataSource.filter` et les clauses `when` de permission au niveau de la ligne, de sorte que chaque vue liée à une affectation se rafraîchit automatiquement lorsque le périmètre actif change. Le jeton associé `$currentUser.assignments.<table>` (l'ensemble complet des affectations d'un utilisateur) est traité dans [Atterrissage après connexion](/fr/auth-post-login).

## Pages associées

- [Présentation de l'authentification](/fr/auth-overview) — activer l'authentification et le bloc `auth`.
- [Atterrissage après connexion](/fr/auth-post-login) — interpolation `$currentUser.assignments` et atterrissage par rôle.
- [Permissions de table](/fr/table-permissions) — prédicats `when` au niveau de la ligne qui consomment `$currentUser`.
- [Renforcement de la sécurité](/fr/security-hardening) — rotation de `AUTH_SECRET` et renforcement des cookies.

# Authentification à deux facteurs

`auth.twoFactor` active l'**authentification à deux facteurs basée sur TOTP** (mots de passe à usage unique basés sur le temps). Les utilisateurs ajoutent un second facteur avec une application d'authentification (Google Authenticator, 1Password, Authy, …) et saisissent un code rotatif à la connexion.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
```

:::callout
**La 2FA nécessite la stratégie `emailAndPassword`.** Le TOTP superpose un second facteur par-dessus la connexion par mot de passe. Configurer `twoFactor` sans une stratégie `emailAndPassword` dans `auth.strategies` échoue à la validation au démarrage.
:::

## Activer la 2FA

La forme la plus simple est un booléen — activer avec les valeurs par défaut :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor: true
```

Pour contrôler le nom de l'émetteur, les codes de secours et le format des codes, utilisez la forme objet :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
    digits: 6
    period: 30
```

## Configuration

`auth.twoFactor` accepte soit un booléen, soit un objet de configuration.

| Propriété     | Description                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| _(booléen)_   | `true` active la 2FA avec les valeurs par défaut ; `false` (ou l'omission du champ) la désactive.                   |
| `issuer`      | Nom affiché dans l'application d'authentification de l'utilisateur (par ex. `MyApp`). Identifie l'entrée du compte. |
| `backupCodes` | Booléen. Lorsque `true`, génère des codes de secours à usage unique pour la récupération du compte.                 |
| `digits`      | Nombre de chiffres dans le code TOTP, 4–8. Par défaut `6`.                                                          |
| `period`      | Intervalle de rotation du code en secondes (positif). Par défaut `30`.                                              |

:::callout
Conservez `digits: 6` et `period: 30` sauf besoin de compatibilité spécifique — ils correspondent aux valeurs par défaut que presque toutes les applications d'authentification attendent. Des valeurs non standard peuvent dérouter certaines applications.
:::

## Codes de secours

Lorsque `backupCodes: true`, les utilisateurs reçoivent un ensemble de codes de récupération à usage unique lors de l'inscription à la 2FA — essentiels s'ils perdent l'accès à leur appareil d'authentification. La livraison est personnalisable via le [modèle d'e-mail](/fr/auth-strategies#email-templates) `twoFactorBackupCodes` :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
  emailTemplates:
    twoFactorBackupCodes:
      subject: Your MyApp recovery codes
      text: 'Keep these recovery codes safe: $code'
```

## Flux d'inscription

1. L'utilisateur se connecte avec son e-mail et son mot de passe comme d'habitude.
2. Il s'inscrit à la 2FA — l'application affiche un secret TOTP (généralement sous forme de QR code) étiqueté avec `issuer`.
3. Il le scanne dans une application d'authentification, qui commence à générer des codes toutes les `period` secondes.
4. Lors des connexions ultérieures, après l'étape du mot de passe, il saisit le code courant de longueur `digits`.
5. S'ils sont activés, les codes de secours offrent une voie de récupération lorsque l'appareil est indisponible.

## Pages associées

- [Stratégies](/fr/auth-strategies) — la stratégie `emailAndPassword` dont dépend la 2FA, ainsi que le modèle d'e-mail `twoFactorBackupCodes`.
- [Sessions](/fr/auth-sessions) — sessions émises après la réussite du second facteur.
- [Présentation de l'authentification](/fr/auth-overview) — le bloc `auth` en contexte.

# Serveur OAuth

Au-delà de la consommation de connexions sociales (voir [Stratégies](/fr/auth-strategies)), Sovrium peut agir **en tant que serveur d'autorisation OAuth 2.1 / OpenID Connect 1.0** — émettant des jetons d'accès et de rafraîchissement pour les applications en aval et les clients IA/MCP qui s'authentifient auprès de votre référentiel d'identités Sovrium.

C'est ainsi que Sovrium devient le fournisseur d'identité d'une flotte d'applications : une instance Sovrium détient les utilisateurs, et d'autres services lui délèguent la connexion.

## Activation

Les points de terminaison du serveur OAuth sont **montés automatiquement dès que `auth` est configuré** — il n'y a rien à activer dans le schéma.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  # OAuth-server endpoints mount automatically under /api/auth/oauth2/* once auth is configured.
```

:::callout
**Aucun réglage de schéma (pour l'instant).** Les durées de vie des jetons et autres réglages relèvent de l'opérateur et sont régis par des valeurs par défaut et des variables d'environnement, pas par des champs `app.auth`. Un futur bloc `app.auth.oauthServer.{...}` pourra exposer certains réglages une fois le câblage des routes stabilisé et que nous saurons quels paramètres les auteurs de schémas souhaitent réellement. Sans `auth` configuré, toutes les routes `/api/auth/*` renvoient `404` — il n'y a aucune identité à autoriser.
:::

## Points de terminaison

Le serveur d'autorisation expose la surface standard OAuth 2.1 / OIDC sous `/api/auth/oauth2/*`, plus des documents de découverte aux chemins well-known.

| Méthode | Chemin                                    | Rôle                                                                    |
| ------- | ----------------------------------------- | ----------------------------------------------------------------------- |
| `GET`   | `/.well-known/oauth-authorization-server` | Métadonnées du serveur d'autorisation RFC 8414.                         |
| `GET`   | `/.well-known/openid-configuration`       | Métadonnées OIDC Discovery 1.0.                                         |
| `GET`   | `/.well-known/jwks.json`                  | JSON Web Key Set — clés publiques pour la vérification des jetons.      |
| `POST`  | `/api/auth/oauth2/register`               | Enregistrement dynamique de client RFC 7591.                            |
| `GET`   | `/api/auth/oauth2/authorize`              | Point de terminaison d'autorisation (PKCE-S256 requis).                 |
| `POST`  | `/api/auth/oauth2/consent`                | Accusé de réception du consentement de l'utilisateur.                   |
| `POST`  | `/api/auth/oauth2/continue`               | Reprise après sélection de compte / post-connexion.                     |
| `POST`  | `/api/auth/oauth2/token`                  | Point de terminaison de jeton (`authorization_code` + `refresh_token`). |
| `GET`   | `/api/auth/oauth2/userinfo`               | Revendications OIDC UserInfo pour le jeton d'accès.                     |
| `POST`  | `/api/auth/oauth2/introspect`             | Introspection de jeton RFC 7662.                                        |
| `POST`  | `/api/auth/oauth2/revoke`                 | Révocation de jeton RFC 7009.                                           |

## Valeurs par défaut

Sovrium règle le serveur d'autorisation pour l'auto-hébergement et l'usage par des clients IA dès le départ :

| Paramètre                                 | Par défaut           | Pourquoi                                                                                                |
| ----------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| Enregistrement dynamique de client        | Activé               | Les clients MCP (Claude Desktop, ChatGPT Dev Mode) s'enregistrent eux-mêmes sans action de l'opérateur. |
| Durée de vie du jeton d'accès             | 1 heure              | Standard de l'industrie.                                                                                |
| Durée de vie du jeton de rafraîchissement | 30 jours             | Standard de l'industrie.                                                                                |
| Page de connexion                         | `/login`             | Page du moteur Sovrium.                                                                                 |
| Page de consentement                      | `/oauth/consent`     | Page du moteur Sovrium.                                                                                 |
| PKCE                                      | Requis (S256)        | OAuth 2.1 impose PKCE pour le flux de code d'autorisation.                                              |
| Signature des jetons                      | Clés EdDSA rotatives | `id_token` et jetons d'accès signés publiés via le point de terminaison JWKS.                           |

## Clients MCP & IA

L'enregistrement dynamique de client est activé spécifiquement pour que les assistants IA et les clients MCP puissent s'enregistrer eux-mêmes et obtenir des jetons, puis appeler les tables exposées via MCP de votre application (soumises au même [RBAC](/fr/auth-roles-rbac) et aux mêmes [permissions de table](/fr/table-permissions) que tout autre appelant). Cela permet à un client IA d'agir au nom d'un utilisateur réel, avec le même accès que cet utilisateur aurait dans l'interface.

## Pages associées

- [Stratégies](/fr/auth-strategies) — Sovrium en tant que _client_ OAuth (connexion sociale), la direction inverse.
- [Rôles & RBAC](/fr/auth-roles-rbac) — le modèle d'accès auquel les jetons sont liés.
- [Permissions de table](/fr/table-permissions) — ce qu'un jeton autorisé peut atteindre.
- [Variables d'environnement](/fr/env-vars) — `AUTH_SECRET` (signature des jetons) et `BASE_URL` (URL d'émetteur / de découverte).

# Atterrissage après connexion

Après la connexion, différents utilisateurs devraient atterrir sur différentes pages — un administrateur sur l'accueil d'administration, un client sur son enregistrement (ou un sélecteur lorsqu'il en a plusieurs). Sovrium exprime cela comme une **configuration d'authentification**, et non comme une logique de redirection par page : chaque rôle déclare un `defaultLanding`, le bloc `auth` déclare un point de montage `landingPath`, et `noAccessPath` gère le cas non concordant.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  scopeTables: [clients]
  defaultRole: customer-admin
  landingPath: /portal
  noAccessPath: /403
  roles:
    - name: engineer
      defaultLanding: /admin
    - name: customer-admin
      defaultLanding: /portal/clients/$currentUser.assignments.clients[0]
      pickerLanding: /portal/select/clients
```

## Champs de configuration

Deux champs sur `auth`, deux sur chaque rôle :

| Champ            | Niveau    | Description                                                                                                                                                                                                                              |
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `landingPath`    | `auth`    | Chemin de montage du résolveur de moteur. Les sessions qui naviguent ici sont redirigées vers le `defaultLanding` du rôle correspondant. Doit commencer par `/`. Obligatoire dès qu'un rôle définit `defaultLanding` ou `pickerLanding`. |
| `noAccessPath`   | `auth`    | Chemin de repli lorsqu'aucun `defaultLanding` de rôle ne correspond à la session. Doit commencer par `/`. Par défaut `/403`.                                                                                                             |
| `defaultLanding` | `roles[]` | URL d'atterrissage par rôle. Doit commencer par `/`. Peut contenir au plus un jeton `$currentUser.assignments.<table>[0]`.                                                                                                               |
| `pickerLanding`  | `roles[]` | Repli multi-enregistrements pour un `defaultLanding` _à modèle_. Doit commencer par `/`. Ne doit **pas** contenir de jeton d'affectation.                                                                                                |

:::callout
`landingPath` est **contrôlé par l'utilisateur** — choisissez `/portal`, `/dashboard`, `/home`, ou n'importe quoi d'autre. Il n'y a pas de convention de moteur. Il en va de même pour `pickerLanding` : `/portal/select/clients`, `/companies-picker`, comme bon vous semble.
:::

## Logique de résolution

Lorsqu'une session authentifiée navigue vers `auth.landingPath`, le moteur parcourt `auth.roles[]` dans l'**ordre de déclaration** et applique le premier rôle que l'utilisateur détient. Pour le `defaultLanding` de ce rôle :

| Forme de `defaultLanding`                  | Nombre d'affectations pour la `<table>` à modèle | Action du moteur                                   |
| ------------------------------------------ | ------------------------------------------------ | -------------------------------------------------- |
| URL simple (sans jeton)                    | s.o.                                             | Rediriger vers `defaultLanding` sans condition.    |
| À modèle (un jeton)                        | Exactement une affectation                       | Substituer l'ID d'affectation, rediriger là.       |
| À modèle (un jeton)                        | Plus d'une affectation                           | Rediriger vers le `pickerLanding` du rôle.         |
| Aucun rôle concordant / aucune affectation | s.o.                                             | Rediriger vers `noAccessPath` (par défaut `/403`). |

## Interpolation `$currentUser.assignments`

Le jeton `$currentUser.assignments.<table>` se résout en l'ensemble des ID d'enregistrement issus des lignes `user_access` de l'utilisateur pour `<table>` (une [table de périmètre](/fr/auth-sessions)). Il apparaît de deux manières distinctes :

**Dans une URL `defaultLanding`** — la forme à enregistrement unique `$currentUser.assignments.<table>[0]` substitue le _premier_ ID d'affectation, produisant un lien direct vers cet enregistrement :

```yaml
roles:
  - name: customer-admin
    defaultLanding: /portal/clients/$currentUser.assignments.clients[0]
    pickerLanding: /portal/select/clients
```

Un rôle peut contenir **au plus un** tel jeton (le résolveur ne peut pas déduire quel périmètre compter avec deux). Un `pickerLanding` ne doit en contenir **aucun** — par définition, le cas multi-enregistrements n'a pas d'ID unique à substituer.

**Dans un `dataSource.filter`** — la forme non indexée `$currentUser.assignments.<table>` se résout en la liste complète des ID, de sorte que la page de sélection liste exactement les enregistrements que l'utilisateur peut atteindre :

```yaml
pages:
  - name: client-picker
    path: /portal/select/clients
    access: authenticated
    components:
      - type: list
        props: { id: clients }
        dataSource:
          table: clients
          filter:
            - field: id
              operator: in
              value: $currentUser.assignments.clients
        children:
          - type: text
            content: $record.name
```

## La page `landingPath` est le garde d'accès

`landingPath` doit être adossé à une **page co-localisée** déclarée au même `path`. Cette page est le garde d'accès non authentifié : son bloc `access` renvoie les visiteurs anonymes vers `/login` avant que le résolveur d'atterrissage ne s'exécute. Pour les visiteurs authentifiés, le résolveur redirige avant que cette page (généralement vide) ne soit rendue.

```yaml
auth:
  landingPath: /portal
  # ...

pages:
  - name: portal-landing
    path: /portal
    access:
      require: authenticated
      redirectTo: /login
    components: [] # never rendered for authed users — resolver redirects first
```

:::callout
Oublier la page de garde co-localisée est l'erreur la plus courante : `landingPath: /portal` sans page `/portal` laisse les visiteurs anonymes sans protection. Associez toujours le chemin de montage à une page qui exige l'authentification.
:::

## Exemple complet

```yaml
auth:
  strategies:
    - type: emailAndPassword
  scopeTables: [clients]
  defaultRole: customer-admin
  landingPath: /portal
  noAccessPath: /403
  roles:
    - name: engineer
      defaultLanding: /admin
    - name: customer-admin
      defaultLanding: /portal/clients/$currentUser.assignments.clients[0]
      pickerLanding: /portal/select/clients

pages:
  - name: portal-landing
    path: /portal
    access: { require: authenticated, redirectTo: /login }
    components: []
  - name: client-detail
    path: /portal/clients/:id
    access: authenticated
    components: []
  - name: client-picker
    path: /portal/select/clients
    access: authenticated
    components: []
  - name: admin-home
    path: /admin
    access: [engineer]
    components: []
  - name: forbidden
    path: /403
    access: authenticated
    components: []
```

Dans cette application : un `engineer` atterrit sur `/admin` ; un `customer-admin` avec un seul client atterrit sur la page de détail de ce client ; avec plusieurs, sur le sélecteur ; et quiconque que le résolveur ne peut pas placer atteint `/403`.

## Pages associées

- [Rôles & RBAC](/fr/auth-roles-rbac) — là où `defaultLanding` / `pickerLanding` sont définis sur les rôles.
- [Sessions](/fr/auth-sessions) — `scopeTables`, `user_access` et `$currentUser.activeAssignment`.
- [Pages](/fr/pages-overview) — `path`, `access` et `dataSource.filter` de page.

# Vue d'ensemble des automatisations

Les automatisations constituent le moteur de workflows de Sovrium. Chaque automatisation associe **un déclencheur** (l'événement qui la démarre) à une **liste ordonnée d'actions** (les étapes qu'elle exécute). Lorsque le déclencheur se déclenche, les actions s'exécutent séquentiellement — en transmettant les données vers l'avant via des variables de gabarit — jusqu'à ce que le workflow se termine, s'arrête ou échoue.

Les automatisations sont déclarées dans le tableau de premier niveau `app.automations[]`. Les déclencheurs réagissent aux changements d'enregistrements, aux planifications, aux webhooks entrants, aux événements d'authentification, aux soumissions de formulaires, aux boutons manuels, aux appels de sous-workflows, aux échecs d'autres automatisations et aux commentaires. Les actions couvrent plus de 20 familles : HTTP, CRUD d'enregistrements, e-mail, IA, opérations sur fichiers, contrôle de flux, approbations, et plus encore.

```yaml
automations:
  - name: new-order-alert
    label: Notify the team about new orders
    trigger:
      type: record
      table: orders
      events: [create]
    actions:
      - name: notifyTeam
        type: email
        operator: send
        props:
          to: '{{trigger.data.owner_email}}'
          subject: 'New order {{trigger.data.id}}'
          body: 'Amount: ${{trigger.data.amount}}'
    timeout: 60000
```

## Anatomie

Une automatisation possède exactement un `trigger` et au moins une entrée dans `actions`. Tout le reste — timeout, retry, concurrence, tags, permissions, exposition à l'IA — est optionnel.

| Propriété     | Description                                                                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | Identifiant unique en kebab-case (`^[a-z][a-z0-9-]*$`, max 100 caractères). Utilisé dans les URL de webhook et comme cible de `automation/call`.                                                              |
| `label`       | Libellé lisible affiché dans l'interface d'administration.                                                                                                                                                    |
| `description` | Description en texte libre de ce que fait l'automatisation.                                                                                                                                                   |
| `enabled`     | Booléen. Lorsqu'il vaut `false`, l'automatisation est enregistrée mais ne se déclenche jamais. Vaut `true` par défaut.                                                                                        |
| `trigger`     | L'événement unique qui démarre ce workflow. Voir [Déclencheurs](/fr/automation-triggers).                                                                                                                     |
| `actions`     | Tableau ordonné d'étapes d'action (minimum 1). Les étapes s'exécutent séquentiellement sauf si une action `path`/`loop` crée une branche. Voir [Vue d'ensemble des actions](/fr/automation-actions-overview). |
| `retry`       | Politique de relance au niveau de l'automatisation appliquée à l'ensemble de l'exécution. Voir [Relance et échec](/fr/automation-retry-failure).                                                              |
| `timeout`     | Timeout total de l'exécution en millisecondes (1000–900000, par défaut 300000).                                                                                                                               |
| `concurrency` | `{ limit }` — nombre maximal d'exécutions simultanées de cette automatisation (1–50). Voir la note sur la concurrence ci-dessous.                                                                             |
| `tags`        | Tableau de chaînes de caractères pour organiser et filtrer les automatisations.                                                                                                                               |
| `permissions` | `{ trigger }` — qui peut invoquer manuellement cette automatisation (`all`, `authenticated`, ou un tableau de rôles).                                                                                         |
| `aiAccess`    | Déclare une automatisation à **déclenchement manuel** comme invocable via le serveur MCP de Sovrium. La définir sur un déclencheur non manuel est une erreur de décodage.                                     |

:::callout
**Les données circulent entre les étapes via des variables de gabarit.** Référencez la charge utile du déclencheur avec `{{trigger.data.fieldName}}`, la sortie d'une étape précédente avec `{{stepName.result}}`, un secret d'environnement avec `$env.VAR_NAME` (jamais journalisé), et une information d'identification stockée avec `$connection.NAME`. Voir [Helpers de gabarit](#variables-de-gabarit) ci-dessous.
:::

## Variables de gabarit

Chaque propriété de chaîne de caractères dans une action peut interpoler des valeurs à l'exécution. Les sources de résolution sont :

| Source                      | Syntaxe                    | Notes                                                                                                                                                     |
| --------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Charge utile du déclencheur | `{{trigger.data.field}}`   | Les données transportées par le déclencheur (ligne d'enregistrement, corps de webhook, valeurs de formulaire, …).                                         |
| Étape précédente            | `{{stepName.result}}`      | La sortie de toute action antérieure, référencée par son `name`.                                                                                          |
| Variable d'environnement    | `$env.VAR_NAME`            | Résolue depuis `app.env`. Masquée dans les journaux. Voir [Variables d'environnement](/fr/automation-env-vars).                                           |
| Connexion                   | `$connection.NAME`         | Informations d'identification résolues pour un service externe. Voir [Connexions](/fr/automation-connections).                                            |
| Fonctions helper            | `{{helperName arg "lit"}}` | Plus de 100 helpers de formatage (texte, nombre, date, logique, collection, encodage). Imbriquez avec des parenthèses : `{{uppercase (trim step.text)}}`. |

## Concurrence

Chaque automatisation possède un sémaphore FIFO indépendant. Lorsque `concurrency.limit` est défini, les déclencheurs entrants au-delà de la limite sont persistés en `queued` et promus en `running` à mesure que des créneaux en cours d'exécution se libèrent. Sans ce bloc, la variable d'environnement globale `AUTOMATION_CONCURRENCY_DEFAULT` (par défaut 5) s'applique. La mise en file d'attente est en mémoire et mono-processus — conçue pour le modèle de déploiement mono-locataire de Sovrium.

## Surface de configuration

Les automatisations côtoient trois blocs frères de premier niveau qu'elles référencent régulièrement :

| Bloc              | Objectif                                                                     | Page                                                          |
| ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `app.automations` | Les workflows eux-mêmes.                                                     | cette page                                                    |
| `app.actions`     | Modèles d'action réutilisables référencés via l'action `ref`.                | [Vue d'ensemble des actions](/fr/automation-actions-overview) |
| `app.connections` | Informations d'identification stockées pour les appels HTTP/IA authentifiés. | [Connexions](/fr/automation-connections)                      |
| `app.env`         | Variables d'environnement / secrets déclarés.                                | [Variables d'environnement](/fr/automation-env-vars)          |

## Pages connexes

- [Déclencheurs](/fr/automation-triggers) — les 9 types de déclencheurs.
- [Vue d'ensemble des actions](/fr/automation-actions-overview) — le modèle d'action et les ~22 familles.
- [Exécutions](/fr/automation-runs) — surveillance de l'historique d'exécution et des statuts.
- [Relance et échec](/fr/automation-retry-failure) — politiques de relance, timeouts, idempotence.
- [Connexions](/fr/automation-connections) — informations d'identification OAuth2, clé API, basic, bearer.
- [Variables d'environnement](/fr/automation-env-vars) — secrets pour les automatisations.

# Déclencheurs d'automatisation

Un déclencheur est l'événement unique qui démarre une automatisation. Sovrium propose **9 types de déclencheurs**. Chaque automatisation déclare exactement un objet `trigger` dont le `type` sélectionne la variante ; les propriétés restantes la configurent.

```yaml
automations:
  - name: order-webhook
    trigger:
      type: webhook
      method: POST
    actions:
      - { name: ack, type: webhook, operator: response, props: { status: 202 } }
```

## Catalogue des déclencheurs

| `type`               | Se déclenche lorsque…                                                          | Contexte clé exposé                          |
| -------------------- | ------------------------------------------------------------------------------ | -------------------------------------------- |
| `webhook`            | Une requête HTTP entrante atteint le point de terminaison de l'automatisation. | `{{trigger.body}}`, en-têtes, query          |
| `cron`               | Une planification cron s'écoule.                                               | heure planifiée                              |
| `record`             | Un enregistrement est créé, mis à jour ou supprimé dans une table surveillée.  | `{{trigger.data.*}}` (la ligne)              |
| `auth`               | Un événement d'authentification se produit (inscription, connexion, …).        | l'événement d'authentification + utilisateur |
| `form`               | Un formulaire de premier niveau est soumis.                                    | `{{trigger.data.*}}` (valeurs du formulaire) |
| `manual`             | Un administrateur clique sur un bouton ou appelle l'API de déclenchement.      | `{{trigger.inputData.*}}`                    |
| `automation-call`    | Une autre automatisation invoque celle-ci via l'action `automation/call`.      | `{{trigger.inputData.*}}`                    |
| `automation-failure` | Une automatisation surveillée échoue.                                          | l'exécution échouée + erreur                 |
| `comment`            | Un commentaire est créé sur un enregistrement.                                 | `$trigger.comment.*`, `$trigger.record.*`    |

## Déclencheur webhook

Expose un point de terminaison HTTP qui, lorsqu'il est atteint, démarre l'automatisation. Accepte une ou plusieurs méthodes et prend en charge l'authentification entrante, les réponses personnalisées, la validation de requête/query, la limitation de débit et la déduplication.

| Propriété             | Description                                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `method`              | Méthode(s) HTTP à accepter — `GET`/`POST`/`PUT`/`PATCH`/`DELETE`, ou un tableau de celles-ci. **Requis.**                    |
| `secret`              | Secret pour la vérification de signature HMAC (par ex. `$env.WEBHOOK_SECRET`).                                               |
| `respondImmediately`  | Lorsqu'il vaut `true` (par défaut), répond `202` immédiatement ; lorsqu'il vaut `false`, attend la fin de l'exécution.       |
| `auth`                | Configuration d'authentification entrante — `type` vaut `bearer`, `apiKey`, `hmac` ou `basic` (voir le tableau ci-dessous).  |
| `response`            | Réponse personnalisée : `statusCode`/`status`, `body` (gabarit de chaîne ou JSON), `headers`.                                |
| `requestSchema`       | JSON Schema validant le corps de la requête.                                                                                 |
| `querySchema`         | JSON Schema validant les paramètres de query.                                                                                |
| `rateLimit`           | Configuration de limitation de débit `{ maxRequests, windowSeconds }` pour le point de terminaison.                          |
| `deduplicationKey`    | Gabarit calculant une clé de déduplication (par ex. `"{{body.orderId}}"`) — les clés répétées dans la fenêtre sont rejetées. |
| `deduplicationWindow` | Fenêtre de déduplication en secondes (par défaut 300).                                                                       |

**Options de `auth.type` entrant :** `bearer` (avec `token`, `prefix`), `apiKey` (avec `key`, `header`), `hmac` (avec `secret`, `algorithm`), `basic` (avec `username`, `password`). Toutes les valeurs d'identification prennent en charge `$env.VAR`.

```yaml
trigger:
  type: webhook
  method: [POST]
  auth: { type: hmac, secret: $env.STRIPE_SIGNING_SECRET, algorithm: sha256 }
  deduplicationKey: '{{body.id}}'
  deduplicationWindow: 600
```

## Déclencheur cron

Exécute l'automatisation selon une planification.

| Propriété    | Description                                                                                                                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expression` | Expression cron — standard à 5 champs ou à 6 champs avec secondes (par ex. `0 9 * * 1-5`). Aucun alias `@daily`/`@hourly` — utilisez l'équivalent numérique. **Validée au décodage de la configuration.** |
| `timezone`   | Fuseau horaire IANA (par ex. `America/New_York`). Vaut `UTC` par défaut. Validé par rapport à la base de données IANA.                                                                                    |

```yaml
trigger:
  type: cron
  expression: '0 9 * * 1-5'
  timezone: Europe/Paris
```

## Déclencheur d'enregistrement

Se déclenche lorsque des enregistrements changent dans une table.

| Propriété     | Description                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `table`       | Nom de la table à surveiller. **Requis.**                                                       |
| `events`      | Tableau de `create` / `update` / `delete` (minimum 1). **Requis.**                              |
| `watchFields` | Lors d'un `update`, ne se déclenche que lorsque l'un de ces champs change.                      |
| `condition`   | Un groupe de conditions — ne se déclenche que lorsque la ligne modifiée correspond au prédicat. |

```yaml
trigger:
  type: record
  table: orders
  events: [create, update]
  watchFields: [status]
  condition:
    conditions: [{ field: '{{trigger.data.status}}', operator: equals, value: paid }]
```

## Déclencheur d'authentification

Se déclenche sur les événements du cycle de vie d'authentification.

| Propriété | Description                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------- |
| `events`  | Tableau de `signUp`, `signIn`, `signOut`, `passwordReset`, `emailVerified` (minimum 1). **Requis.** |

```yaml
trigger:
  type: auth
  events: [signUp]
```

## Déclencheur de formulaire

Se déclenche lorsqu'un formulaire de premier niveau (`forms[].name`) est soumis.

| Propriété | Description                                                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `form`    | Référence `forms[].name`. **Requis.** _(Rupture forte : il s'agissait auparavant d'un chemin de page.)_ Voir [Formulaires](/fr/forms-overview). |

```yaml
trigger:
  type: form
  form: contact-request
```

## Déclencheur manuel

Exécution initiée par un administrateur via un bouton ou un appel d'API.

| Propriété      | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `label`        | Libellé du bouton dans l'interface d'administration (par ex. `Export Report`).        |
| `inputSchema`  | JSON Schema décrivant les champs de saisie requis fournis au moment du déclenchement. |
| `requiredRole` | Rôle d'authentification requis pour déclencher (par défaut `admin`).                  |

Les déclencheurs manuels sont les **seuls** déclencheurs éligibles à `aiAccess` (invocation MCP), puisqu'ils ne se déclenchent pas d'eux-mêmes.

```yaml
trigger:
  type: manual
  label: Sync inventory
  requiredRole: admin
  inputSchema: { warehouse: { type: string } }
```

## Déclencheur automation-call

Se déclenche lorsqu'une autre automatisation invoque celle-ci via l'action `automation/call` — permettant la composition de sous-workflows.

| Propriété     | Description                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `inputSchema` | Contrat d'entrée attendu (de type JSON Schema). S'il est omis, accepte n'importe quelles `inputData` de l'appelant. |

```yaml
trigger:
  type: automation-call
  inputSchema: { customerId: { type: string } }
```

Voir [Contrôle de flux](/fr/automation-flow-control) pour les actions `automation/call` et `automation/return`.

## Déclencheur automation-failure

Se déclenche lorsqu'une automatisation surveillée échoue — gestion d'échec composable sans configuration de notification par automatisation.

| Propriété     | Description                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| `automations` | Tableau de noms d'automatisations (kebab-case) à surveiller. S'il est omis, se déclenche sur **tout** échec. |

```yaml
trigger:
  type: automation-failure
  automations: [nightly-sync, billing-run]
```

## Déclencheur de commentaire

Se déclenche lorsqu'un commentaire est créé sur un enregistrement dans une table avec commentaires activés.

| Propriété                | Description                                                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `table`                  | Nom de la table avec commentaires activés. **Requis.**                                                                            |
| `when`                   | `approved` (uniquement les commentaires modérés-approuvés), `created` (tout nouveau commentaire), ou `any`. Par défaut `created`. |
| `filter`                 | `{ topLevelOnly, repliesOnly, mentionsOnly }` (top-level et replies-only sont mutuellement exclusifs).                            |
| `respectReadPermissions` | Lorsqu'il vaut true, ne se déclenche que si le contexte déclencheur peut lire l'enregistrement.                                   |

Les déclencheurs de commentaire exposent `$trigger.comment.*`, `$trigger.record.*`, `$trigger.threadParticipants` et `$trigger.mentions`.

```yaml
trigger:
  type: comment
  table: tickets
  when: created
  filter: { mentionsOnly: true }
```

## Pages connexes

- [Vue d'ensemble des automatisations](/fr/automations-overview) — anatomie et variables de gabarit.
- [Vue d'ensemble des actions](/fr/automation-actions-overview) — ce qui s'exécute après le déclenchement d'un déclencheur.
- [Webhooks (tables)](/fr/table-webhooks) — webhooks de table _sortants_ (distincts des déclencheurs webhook entrants).
- [Contrôle de flux](/fr/automation-flow-control) — `automation/call` et `automation/return`.

# Vue d'ensemble des actions d'automatisation

Les actions sont les étapes individuelles qu'une automatisation exécute. Chaque action partage la même forme : un **`type`** et un **`operator`** qui sélectionnent ensemble l'opération, plus un objet **`props`** transportant ses entrées. Les étapes s'exécutent séquentiellement (de haut en bas) sauf si une action `path` ou `loop` crée une branche d'exécution.

```yaml
actions:
  - name: fetchUser # step name — referenced as {{fetchUser.result}}
    type: http # action family
    operator: get # operation within the family
    props: # operation-specific inputs
      url: 'https://api.example.com/users/{{trigger.data.userId}}'
      connection: example-api
```

## Le modèle d'action

| Élément    | Description                                                                                                                       |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | La **famille** d'action (par ex. `http`, `record`, `email`). Sélectionne la capacité générale.                                    |
| `operator` | L'**opération** au sein de la famille (par ex. `get`, `create`, `send`). Détermine la forme de `props`.                           |
| `props`    | Entrées spécifiques à l'opération. Les valeurs de chaîne prennent en charge les [variables de gabarit](/fr/automations-overview). |

## Propriétés de base communes

Chaque action — quel que soit son `type`/`operator` — accepte ces champs de base :

| Propriété         | Description                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | Nom de l'étape pour référencer les sorties (par ex. `fetchUser`). Doit correspondre à `^[a-zA-Z][a-zA-Z0-9_]*$`. **Requis.**                          |
| `label`           | Libellé lisible pour l'étape.                                                                                                                         |
| `retry`           | Politique de relance par action — `{ maxAttempts, delayMs?, strategy? }`. Voir [Relance et échec](/fr/automation-retry-failure).                      |
| `continueOnError` | Booléen. Lorsqu'il vaut `true`, le workflow continue même si cette action échoue. Vaut `false` par défaut.                                            |
| `timeout`         | Timeout par action en millisecondes (1000–900000). Termine l'action de manière uniforme lorsqu'il est dépassé — distinct du `props.timeout` par type. |

:::callout
**Deux timeouts, deux portées.** Le champ `timeout` de premier niveau encadre l'action entière et est appliqué pour **chaque** type d'action. Un `props.timeout` (par ex. sur `http`, `code`, `automation/call`) encadre l'opération interne du gestionnaire. Le plus petit des deux l'emporte.
:::

## Exécution conditionnelle

Le branchement et le saut conditionnel sont gérés par des actions de contrôle de flux dédiées plutôt que par un champ `condition` par action :

- **`filter/continue`** — évalue un groupe de conditions ; si faux, `stop` (arrête) l'exécution ou `skip` (saute) à l'action suivante.
- **`path/branch`** — achemine vers des branches nommées en fonction de conditions par branche.

Voir [Contrôle de flux](/fr/automation-flow-control) et [Actions de données et d'état](/fr/automation-data-actions).

## Les ~22 familles d'actions

Chaque famille regroupe un ou plusieurs operators. Les pages ci-dessous documentent chaque operator.

| Famille      | Operators                                                                                                                                   | Page                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `data`       | set, aggregate, sort, limit, deduplicate, merge, split, compare, lookup                                                                     | [Données et état](/fr/automation-data-actions)             |
| `state`      | get, set, increment, delete, list                                                                                                           | [Données et état](/fr/automation-data-actions)             |
| `filter`     | continue                                                                                                                                    | [Données et état](/fr/automation-data-actions)             |
| `crypto`     | hash, hmac                                                                                                                                  | [Données et état](/fr/automation-data-actions)             |
| `digest`     | collect, release                                                                                                                            | [Données et état](/fr/automation-data-actions)             |
| `http`       | request, get, post, put, patch, delete                                                                                                      | [HTTP et webhooks](/fr/automation-http-actions)            |
| `webhook`    | send, response                                                                                                                              | [HTTP et webhooks](/fr/automation-http-actions)            |
| `record`     | create, read, update, delete, upsert, batchCreate, batchUpdate, batchDelete, batchUpsert                                                    | [Enregistrement et fichier](/fr/automation-record-actions) |
| `file`       | upload, download, delete, copy, move, list, getMetadata, signUrl, generatePdf, generateCsv, parseCsv, extractText, transformImage, compress | [Enregistrement et fichier](/fr/automation-record-actions) |
| `path`       | branch                                                                                                                                      | [Contrôle de flux](/fr/automation-flow-control)            |
| `loop`       | each                                                                                                                                        | [Contrôle de flux](/fr/automation-flow-control)            |
| `automation` | call, return                                                                                                                                | [Contrôle de flux](/fr/automation-flow-control)            |
| `flow`       | stop                                                                                                                                        | [Contrôle de flux](/fr/automation-flow-control)            |
| `email`      | send                                                                                                                                        | [E-mail et notifications](/fr/automation-email-actions)    |
| `analytics`  | track                                                                                                                                       | [E-mail et notifications](/fr/automation-email-actions)    |
| `ai`         | generate, classify, extract, agent                                                                                                          | [Actions IA](/fr/automation-ai-actions)                    |
| `approval`   | request                                                                                                                                     | [Approbation et délai](/fr/automation-approval-delay)      |
| `delay`      | wait, queue, webhook                                                                                                                        | [Approbation et délai](/fr/automation-approval-delay)      |
| `auth`       | createUser, assignRole, banUser, unbanUser                                                                                                  | [Actions d'authentification](/fr/automation-auth-actions)  |
| `code`       | runTypescript                                                                                                                               | [Actions de code](/fr/automation-code-actions)             |
| `cloud`      | provision-db, spawn-app, route-add, disable-app, destroy-app                                                                                | [Actions cloud](/fr/automation-cloud-actions)              |
| `ref`        | _(aucun operator)_                                                                                                                          | cette page                                                 |

## Modèles d'action réutilisables (`ref`)

Définissez une action réutilisable dans le tableau de premier niveau `app.actions[]`, puis invoquez-la depuis n'importe quelle automatisation avec une action `ref`. L'action `ref` n'a pas d'`operator` — elle transporte un `$ref` (nom du modèle) et un `$vars` optionnel (remplacements de substitution).

| Propriété | Description                                                                                  |
| --------- | -------------------------------------------------------------------------------------------- |
| `$ref`    | Nom du modèle d'action à invoquer (doit correspondre à un modèle dans `app.actions[]`).      |
| `$vars`   | Variables à substituer dans le modèle référencé (remplace les valeurs par défaut du modèle). |

```yaml
# Top-level reusable template
actions:
  - name: notify-slack
    type: http
    operator: post
    props:
      url: $env.SLACK_WEBHOOK_URL
      body: { text: '{{message}}' }

# Invoking it inside an automation
automations:
  - name: order-alert
    trigger: { type: record, table: orders, events: [create] }
    actions:
      - name: alert
        type: ref
        $ref: notify-slack
        $vars: { message: 'New order {{trigger.data.id}}' }
```

## Pages connexes

- [Vue d'ensemble des automatisations](/fr/automations-overview) — l'anatomie déclencheur + actions.
- [Déclencheurs](/fr/automation-triggers) — événements qui démarrent un workflow.
- [Relance et échec](/fr/automation-retry-failure) — relance, timeout, idempotence.
- [Connexions](/fr/automation-connections) — informations d'identification pour les actions authentifiées.

# Actions de données et d'état

Ces cinq familles manipulent les données **en transit** entre les étapes et persistent les valeurs **entre les exécutions** : `data` (transformations), `state` (magasin clé-valeur), `filter` (filtrage conditionnel), `crypto` (hachage) et `digest` (regroupement d'événements pour une libération ultérieure).

## Data — Transformations en mémoire

La famille `data` transforme les tableaux et valeurs qui ont déjà circulé dans le workflow. Neuf operators.

| Operator      | Props                                     | Description                                                                              |
| ------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
| `set`         | `value`                                   | Définit une valeur (ou en calcule une à partir de gabarits) pour les étapes ultérieures. |
| `aggregate`   | `input`, `function`, `field?`, `groupBy?` | Réduit un tableau — `sum`/`avg`/`min`/`max`/`count`, éventuellement groupé.              |
| `sort`        | `input`, `field`, `direction?`            | Trie un tableau par `field` (`asc` par défaut / `desc`).                                 |
| `limit`       | `input`, `count`                          | Prend les `count` premiers éléments.                                                     |
| `deduplicate` | `input`, `key`                            | Supprime les éléments en double par `key`.                                               |
| `merge`       | `left`, `right`, `joinKey?`               | Fusionne deux tableaux, en joignant éventuellement sur `joinKey`.                        |
| `split`       | `input`, `size`                           | Découpe un tableau en sous-tableaux de taille `size`.                                    |
| `compare`     | `left`, `right`, `key`                    | Compare deux tableaux par `key` (ajoutés / supprimés / modifiés).                        |
| `lookup`      | `input`, `key`, `value`                   | Construit une carte de correspondance clé→valeur à partir d'un tableau.                  |

```yaml
- name: revenueByRegion
  type: data
  operator: aggregate
  props:
    input: '{{fetchOrders.result}}'
    function: sum
    field: amount
    groupBy: region
```

## State — Magasin clé-valeur inter-exécutions

La famille `state` persiste les valeurs entre les exécutions d'automatisation (compteurs, curseurs, marqueurs de déduplication). Un `namespace` optionnel délimite les clés ; `ttl` les fait expirer. Cinq operators.

| Operator    | Props                                | Description                                                   |
| ----------- | ------------------------------------ | ------------------------------------------------------------- |
| `get`       | `key`, `namespace?`                  | Lit une valeur stockée.                                       |
| `set`       | `key`, `value`, `namespace?`, `ttl?` | Stocke une valeur, éventuellement avec une durée de vie.      |
| `increment` | `key`, `amount?`, `namespace?`       | Incrémente atomiquement une valeur numérique (par défaut +1). |
| `delete`    | `key`, `namespace?`                  | Supprime une valeur stockée.                                  |
| `list`      | `prefix?`, `namespace?`, `limit?`    | Liste les clés (éventuellement filtrées par préfixe).         |

```yaml
- name: bumpCounter
  type: state
  operator: increment
  props: { key: 'orders:{{trigger.data.region}}', namespace: metrics }
```

## Filter — Filtrage conditionnel

La famille `filter` décide si le workflow se poursuit. Un operator.

| Operator   | Props                   | Description                                                                                                                                        |
| ---------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `continue` | `condition`, `onFalse?` | Évalue un [groupe de conditions](/fr/automation-flow-control) ; si faux, `stop` (arrête) ou `skip` (saute à l'action suivante). Par défaut `stop`. |

```yaml
- name: onlyPaid
  type: filter
  operator: continue
  props:
    condition:
      conditions: [{ field: '{{trigger.data.status}}', operator: equals, value: paid }]
    onFalse: stop
```

## Crypto — Hachage et HMAC

La famille `crypto` calcule des empreintes et des signatures (par ex. vérification de signature de webhook). Deux operators.

| Operator | Props                                       | Description                                                              |
| -------- | ------------------------------------------- | ------------------------------------------------------------------------ |
| `hash`   | `input`, `algorithm`, `encoding?`           | Hache avec `md5` / `sha256` / `sha512` ; `hex` (par défaut) ou `base64`. |
| `hmac`   | `input`, `secret`, `algorithm`, `encoding?` | HMAC avec `sha256` / `sha512` ; clé fournie par `secret`.                |

```yaml
- name: signPayload
  type: crypto
  operator: hmac
  props:
    input: '{{trigger.body}}'
    secret: $env.SIGNING_SECRET
    algorithm: sha256
    encoding: hex
```

## Digest — Regroupement et libération

La famille `digest` collecte des éléments à travers plusieurs exécutions dans un seau nommé, puis les libère sous forme de lot (par ex. regrouper des notifications dans un résumé quotidien). Deux operators.

| Operator  | Props                              | Description                                                               |
| --------- | ---------------------------------- | ------------------------------------------------------------------------- |
| `collect` | `bucket`, `item`, `deduplicateBy?` | Ajoute un élément à un seau nommé, en dédupliquant éventuellement.        |
| `release` | `bucket`, `sort?`, `limit?`        | Vide un seau — éventuellement trié (`{ field, direction? }`) et plafonné. |

```yaml
# Producer automation (record trigger) collects
- name: queueDigest
  type: digest
  operator: collect
  props: { bucket: daily-summary, item: '{{trigger.data}}', deduplicateBy: id }

# Consumer automation (cron trigger) releases
- name: drain
  type: digest
  operator: release
  props: { bucket: daily-summary, sort: { field: created_at, direction: desc }, limit: 50 }
```

## Pages connexes

- [Vue d'ensemble des actions](/fr/automation-actions-overview) — le modèle type + operator + props.
- [Contrôle de flux](/fr/automation-flow-control) — groupes de conditions, `path`, `loop`.
- [HTTP et webhooks](/fr/automation-http-actions) — récupération de données depuis des API externes.
- [CRUD d'enregistrements](/fr/records-crud) — l'API de données derrière les lectures d'enregistrements.

# Actions HTTP et webhook

La famille `http` effectue des appels HTTP sortants vers des API externes (éventuellement authentifiés via une connexion stockée). La famille `webhook` envoie des webhooks sortants signés et écrit une réponse personnalisée vers un déclencheur webhook entrant.

## HTTP — Requêtes sortantes

Six operators. L'operator générique `request` prend un `method` explicite ; les operators de verbe (`get`/`post`/`put`/`patch`/`delete`) sont des raccourcis et acceptent une référence `connection` pour les appels authentifiés.

| Operator  | Props clés                                                                               | Description                                                 |
| --------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `request` | `url`, `method`, `headers?`, `body?`, `contentType?`, `timeout?`, `expectedStatus?`      | Requête générique avec une méthode explicite (templatable). |
| `get`     | `url`, `headers?`, `timeout?`, `expectedStatus?`, `connection?`                          | HTTP GET.                                                   |
| `post`    | `url`, `headers?`, `body?`, `contentType?`, `timeout?`, `expectedStatus?`, `connection?` | HTTP POST.                                                  |
| `put`     | _(identique à post)_                                                                     | HTTP PUT.                                                   |
| `patch`   | _(identique à post)_                                                                     | HTTP PATCH.                                                 |
| `delete`  | `url`, `headers?`, `body?`, `timeout?`, `expectedStatus?`, `connection?`                 | HTTP DELETE.                                                |

| Prop partagée    | Description                                                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `url`            | URL de la requête (templatable).                                                                                                   |
| `headers`        | Carte des en-têtes de requête (valeurs templatables, par ex. `Authorization: 'Bearer $env.API_KEY'`).                              |
| `body`           | Corps de chaîne ou d'objet JSON.                                                                                                   |
| `contentType`    | `json` (par défaut) / `form` / `text` / `xml`.                                                                                     |
| `timeout`        | Timeout par requête en ms.                                                                                                         |
| `expectedStatus` | Tableau de codes de statut HTTP acceptables ; tout autre fait échouer l'étape.                                                     |
| `connection`     | Nom d'une [connexion](/fr/automation-connections) stockée — injecte les informations d'identification OAuth2/clé API/basic/bearer. |

```yaml
- name: createContact
  type: http
  operator: post
  props:
    url: 'https://api.crm.example/contacts'
    connection: crm-oauth
    contentType: json
    body: { email: '{{trigger.data.email}}', name: '{{trigger.data.name}}' }
    expectedStatus: [200, 201]
```

:::callout
**Utilisez `connection` plutôt que d'incorporer des secrets en ligne.** Lorsqu'une `connection` est référencée, Sovrium attache le bon en-tête `Authorization` et (pour OAuth2) rafraîchit les jetons automatiquement. Définissez les connexions sous `app.connections`. Voir [Connexions](/fr/automation-connections).
:::

## Webhook — Sortant et réponse

Deux operators. `send` déclenche un webhook sortant signé ; `response` écrit la réponse HTTP pour une automatisation démarrée par un **déclencheur webhook**.

| Operator   | Props                              | Description                                                                                     |
| ---------- | ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| `send`     | `url`, `event`, `data?`, `secret?` | Envoie un webhook sortant avec un nom d'`event` et un `secret` HMAC optionnel.                  |
| `response` | `status?`, `body?`, `headers?`     | Définit la réponse HTTP renvoyée à l'appelant entrant (uniquement pour le déclencheur webhook). |

```yaml
# Notify a downstream service
- name: notifyDownstream
  type: webhook
  operator: send
  props:
    url: 'https://hooks.example.com/orders'
    event: order.created
    data: { id: '{{trigger.data.id}}' }
    secret: $env.OUTGOING_WEBHOOK_SECRET

# Reply to the inbound caller
- name: ack
  type: webhook
  operator: response
  props: { status: 200, body: { ok: true } }
```

:::callout
**Webhooks entrants vs sortants vs de table.** Le **déclencheur** `webhook` reçoit du HTTP entrant (voir [Déclencheurs](/fr/automation-triggers)). L'**action** `webhook/send` poste du HTTP sortant depuis une automatisation en cours d'exécution. Séparément, les [webhooks de table](/fr/table-webhooks) se déclenchent automatiquement à la création/mise à jour/suppression d'enregistrement sans automatisation. L'action `webhook/response` ne s'applique qu'aux automatisations démarrées par un déclencheur webhook.
:::

## Pages connexes

- [Connexions](/fr/automation-connections) — informations d'identification OAuth2, clé API, basic, bearer.
- [Variables d'environnement](/fr/automation-env-vars) — secrets `$env` utilisés dans les en-têtes.
- [Déclencheurs](/fr/automation-triggers) — le déclencheur webhook entrant.
- [Webhooks de table](/fr/table-webhooks) — webhooks sortants automatiques sur les événements d'enregistrement.
- [Actions de données et d'état](/fr/automation-data-actions) — transformation des réponses HTTP.

# Actions d'enregistrement et de fichier

La famille `record` lit et écrit des enregistrements de table (unitaire et par lots). La famille `file` effectue des opérations de stockage — upload, download, génération et transformation.

## Record — CRUD de table

Les operators couvrent le CRUD ligne par ligne ainsi que les opérations par lots. Les lectures/mises à jour/suppressions utilisent un `filter` de [groupe de conditions](/fr/automation-flow-control) ; les créations/mises à jour portent une carte `data`. Les operators par lots itèrent sur un tableau `items` (un gabarit se résolvant en une liste).

| Operator      | Props                                                  | Description                                                                  |
| ------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `create`      | `table`, `data`                                        | Insère un enregistrement.                                                    |
| `read`        | `table`, `filter`                                      | Lit les enregistrements correspondant au filtre.                             |
| `update`      | `table`, `data`, `filter`                              | Met à jour les enregistrements correspondant au filtre.                      |
| `delete`      | `table`, `filter`                                      | Supprime en douceur les enregistrements correspondant au filtre.             |
| `upsert`      | `table`, `data`, `filter`                              | Met à jour si une correspondance existe, sinon crée.                         |
| `batchCreate` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Insère plusieurs enregistrements à partir d'un tableau.                      |
| `batchUpdate` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Met à jour plusieurs enregistrements à partir d'un tableau.                  |
| `batchUpsert` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Upsert de plusieurs enregistrements à partir d'un tableau.                   |
| `batchDelete` | `table`, `filter`, `limit?`                            | Supprime les enregistrements correspondant au filtre (plafonné par `limit`). |

```yaml
- name: logActivity
  type: record
  operator: create
  props:
    table: activity_log
    data:
      action: 'order.created'
      order_id: '{{trigger.data.id}}'
      occurred_at: '{{now}}'
```

```yaml
- name: importRows
  type: record
  operator: batchCreate
  props:
    table: contacts
    items: '{{parseLeads.result}}'
    batchSize: 100
    continueOnItemError: true
```

:::callout
**Les actions d'enregistrement respectent les permissions de table et la suppression en douceur.** Les écritures passent par le même RBAC et la même validation que l'[API d'enregistrements](/fr/records-overview) ; `delete` est doux par défaut (définit `deleted_at`). Voir [Permissions de table](/fr/table-permissions) et [CRUD d'enregistrements](/fr/records-crud).
:::

## File — Opérations de stockage

Quatorze operators couvrant le stockage, les métadonnées/accès, la génération et les transformations avancées. Ils opèrent sur le stockage configuré de Sovrium (local ou S3) — voir [Opérations sur fichiers](/fr/file-operations).

### Stockage

| Operator   | Props                             | Description                              |
| ---------- | --------------------------------- | ---------------------------------------- |
| `upload`   | `source`, `path?`, `contentType?` | Téléverse un fichier vers le stockage.   |
| `download` | `key`                             | Télécharge un fichier stocké par sa clé. |
| `delete`   | `key`                             | Supprime un fichier stocké.              |
| `copy`     | `source`, `destination`           | Copie un fichier stocké.                 |
| `move`     | `source`, `destination`           | Déplace/renomme un fichier stocké.       |
| `list`     | `prefix`, `limit?`                | Liste les fichiers sous un préfixe.      |

### Métadonnées et accès

| Operator      | Props                             | Description                                                                                         |
| ------------- | --------------------------------- | --------------------------------------------------------------------------------------------------- |
| `getMetadata` | `key`                             | Lit les métadonnées d'un fichier (taille, type de contenu, …).                                      |
| `signUrl`     | `key`, `expiresIn?`, `operation?` | Génère une URL signée à durée limitée (`download` / `upload`). Voir [URL signées](/fr/signed-urls). |

### Génération

| Operator      | Props                                                                                    | Description                                               |
| ------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `generatePdf` | `template`, `filename`, `data?`, `pageSize?`, `orientation?`, `margins?`, `destination?` | Rend un gabarit HTML en PDF (`A4`/`A3`/`Letter`/`Legal`). |
| `generateCsv` | `data`, `filename`, `columns?`, `delimiter?`, `includeHeaders?`, `destination?`          | Génère un CSV à partir d'un tableau.                      |

### Avancé

| Operator         | Props                                                                                 | Description                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `parseCsv`       | `source`, `columns?`, `skipRows?`, `delimiter?`                                       | Analyse un fichier CSV en un tableau de lignes.                                                                        |
| `extractText`    | `source`, `format?`                                                                   | Extrait le texte d'un document (`plain` / `markdown`).                                                                 |
| `transformImage` | `source`, `width?`, `height?`, `fit?`, `format?`, `quality?`, `crop?`, `destination?` | Redimensionne/convertit une image (`jpeg`/`png`/`webp`/`avif`). Voir [Transformations d'images](/fr/image-transforms). |
| `compress`       | `files`, `filename`, `destination?`                                                   | Compresse plusieurs fichiers en une seule archive.                                                                     |

```yaml
- name: invoice
  type: file
  operator: generatePdf
  props:
    template: invoice-template
    filename: 'invoice-{{trigger.data.id}}.pdf'
    data: '{{trigger.data}}'
    pageSize: A4
    orientation: portrait
    destination: invoices/
```

```yaml
- name: thumbnail
  type: file
  operator: transformImage
  props:
    source: '{{upload.result.key}}'
    width: 320
    fit: cover
    format: avif
    quality: 70
```

:::callout
**Transformations d'images éco-responsables.** Privilégiez `avif` et la livraison différée pour les images générées ; le transcodage d'images est régi par la variable d'environnement `ECO_IMAGE_FORMAT` contrôlée par l'opérateur. Voir [Transformations d'images](/fr/image-transforms).
:::

## Pages connexes

- [Vue d'ensemble des enregistrements](/fr/records-overview) — le modèle de données et l'API des enregistrements.
- [CRUD d'enregistrements](/fr/records-crud) — le contrat create/read/update/delete.
- [Opérations sur fichiers](/fr/file-operations) — la couche de stockage derrière les actions de fichier.
- [URL signées](/fr/signed-urls) — liens d'accès à durée limitée.
- [Transformations d'images](/fr/image-transforms) — traitement d'images à la volée.

# Actions de contrôle de flux

Les actions de contrôle de flux modifient la **forme** d'un workflow plutôt que ses données : elles branchent, itèrent, interrompent et composent d'autres automatisations en sous-workflows.

## Groupes de conditions

Les branches `path` et le filtre `filter/continue` évaluent des **groupes de conditions** — une ou plusieurs comparaisons combinées avec `and`/`or`.

| Élément      | Description                                                                               |
| ------------ | ----------------------------------------------------------------------------------------- |
| `logic`      | `and` (toutes doivent correspondre, par défaut) ou `or` (au moins une doit correspondre). |
| `conditions` | Tableau de `{ field, operator, value? }` (minimum 1).                                     |

**Opérateurs de comparaison :** `equals`, `notEquals`, `contains`, `notContains`, `startsWith`, `endsWith`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`, `isEmpty`, `isNotEmpty`, `isNull`, `isNotNull`, `matches`.

```yaml
condition:
  logic: and
  conditions:
    - { field: '{{trigger.data.status}}', operator: equals, value: paid }
    - { field: '{{trigger.data.amount}}', operator: greaterThan, value: 100 }
```

## Path — Branchement

L'operator `path/branch` achemine l'exécution vers des branches nommées. Chaque branche possède sa propre `condition` et ses `actions` imbriquées.

| Prop    | Description                                                                                                             |
| ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `paths` | Tableau de branches : `{ name, condition?, actions[] }`.                                                                |
| `mode`  | `first-match` (exécute la première branche correspondante) ou `all-matching` (exécute toutes celles qui correspondent). |

```yaml
- name: route
  type: path
  operator: branch
  props:
    mode: first-match
    paths:
      - name: vip
        condition:
          conditions: [{ field: '{{trigger.data.tier}}', operator: equals, value: vip }]
        actions:
          - {
              name: vipEmail,
              type: email,
              operator: send,
              props: { to: '{{trigger.data.email}}', subject: 'VIP welcome', body: 'Thanks!' },
            }
      - name: standard
        actions:
          - {
              name: stdEmail,
              type: email,
              operator: send,
              props: { to: '{{trigger.data.email}}', subject: 'Welcome', body: 'Hi!' },
            }
```

## Loop — Itération

L'operator `loop/each` itère sur un tableau, exécutant ses `actions` imbriquées par élément.

| Prop                  | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| `items`               | Gabarit se résolvant en le tableau à itérer.                           |
| `actions`             | Actions imbriquées exécutées pour chaque élément.                      |
| `maxIterations`       | Plafond sur le nombre d'itérations.                                    |
| `continueOnItemError` | Lorsqu'il vaut `true`, un élément en échec n'interrompt pas la boucle. |

```yaml
- name: notifyEach
  type: loop
  operator: each
  props:
    items: '{{fetchSubscribers.result}}'
    maxIterations: 500
    continueOnItemError: true
    actions:
      - name: send
        type: email
        operator: send
        props: { to: '{{item.email}}', subject: 'Update', body: 'Hi {{item.name}}' }
```

## Flow — Arrêt

L'operator `flow/stop` interrompt immédiatement l'exécution avec un statut et une sortie optionnels.

| Prop      | Description                                     |
| --------- | ----------------------------------------------- |
| `message` | Raison de l'arrêt de l'exécution (templatable). |
| `status`  | `success` ou `error` (par défaut `error`).      |
| `output`  | Sortie clé-valeur renvoyée à l'appelant.        |

```yaml
- name: bail
  type: flow
  operator: stop
  props: { status: success, message: 'Nothing to do', output: { processed: 0 } }
```

## Automation — Call et Return (sous-workflows)

La famille `automation` compose des workflows. `call` invoque une autre automatisation (une avec un déclencheur `automation-call`) ; `return` renvoie une sortie à l'appelant.

| Operator | Props                                                  | Description                                                                                                                                                           |
| -------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call`   | `name`, `inputData?`, `waitForCompletion?`, `timeout?` | Invoque une sous-automatisation par `name` ; attend éventuellement sa fin et expire au bout d'un délai.                                                               |
| `return` | `output`                                               | Renvoie une sortie clé-valeur à l'automatisation appelante (uniquement avec un déclencheur `automation-call`). Accessible via `steps.{name}.result.*` dans le parent. |

```yaml
# Parent: invoke a reusable sub-workflow and wait
- name: enrich
  type: automation
  operator: call
  props:
    name: enrich-lead
    inputData: { email: '{{trigger.data.email}}' }
    waitForCompletion: true
    timeout: 30000

# Sub-workflow (trigger: { type: automation-call }): return result
- name: done
  type: automation
  operator: return
  props: { output: { score: '{{computeScore.result}}' } }
```

:::callout
**Sous-workflow vs gestion d'échec.** `automation/call` invoque une cible qui déclare un déclencheur `automation-call`. Pour réagir à un workflow qui _échoue_, utilisez plutôt le [déclencheur `automation-failure`](/fr/automation-triggers).
:::

## Pages connexes

- [Vue d'ensemble des actions](/fr/automation-actions-overview) — propriétés de base et carte des familles.
- [Déclencheurs](/fr/automation-triggers) — déclencheurs `automation-call` et `automation-failure`.
- [Actions de données et d'état](/fr/automation-data-actions) — filtrage conditionnel `filter/continue`.
- [Approbation et délai](/fr/automation-approval-delay) — mise en pause d'une exécution pour des humains ou du temps.

# Actions d'e-mail et de notification

La famille `email` envoie des e-mails transactionnels depuis une automatisation en cours d'exécution. La famille `analytics` émet des événements nommés utilisés pour les notifications, les métriques et le suivi en aval.

## Email — Envoyer

Un operator. Les destinataires prennent en charge les gabarits ; `cc`/`bcc`/`replyTo` acceptent une adresse unique ou un tableau.

| Prop      | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `to`      | Adresse du destinataire (templatable). **Requis.**                |
| `subject` | Objet de l'e-mail (templatable). **Requis.**                      |
| `body`    | Corps de l'e-mail (templatable). **Requis.**                      |
| `from`    | Adresse de l'expéditeur (par défaut l'expéditeur SMTP configuré). |
| `cc`      | Adresse(s) en copie carbone — chaîne ou tableau.                  |
| `bcc`     | Adresse(s) en copie cachée — chaîne ou tableau.                   |
| `replyTo` | Adresse(s) de réponse — chaîne ou tableau.                        |

```yaml
- name: orderConfirmation
  type: email
  operator: send
  props:
    to: '{{trigger.data.customer_email}}'
    subject: 'Order {{trigger.data.id}} confirmed'
    body: 'Thanks for your order! Total: ${{trigger.data.amount}}'
    cc: [sales@example.com]
    replyTo: support@example.com
```

:::callout
**L'e-mail nécessite que le SMTP soit configuré.** Lorsque `SMTP_HOST` n'est pas défini, l'e-mail est désactivé et l'envoi est journalisé plutôt que livré — Sovrium ne se rabat pas silencieusement sur un capteur de mail local en production. Configurez le SMTP via des variables d'environnement (voir [Variables d'environnement](/fr/automation-env-vars) et les paramètres d'authentification/e-mail de l'application).
:::

## Analytics — Track (notifications et métriques)

Un operator. Émet un événement nommé avec des propriétés arbitraires — le socle des notifications dans l'application, des métriques d'utilisation et des collecteurs en aval.

| Prop         | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `event`      | Nom de l'événement (par ex. `order.created`, `user.invited`). **Requis.** |
| `properties` | Propriétés clé-valeur de l'événement (templatable).                       |

```yaml
- name: trackSignup
  type: analytics
  operator: track
  props:
    event: user.signed_up
    properties:
      userId: '{{trigger.data.id}}'
      plan: '{{trigger.data.plan}}'
```

:::callout
**Les notifications sont pilotées par les événements.** Plutôt qu'un bloc de configuration de notifications autonome, Sovrium pilote les notifications dans l'application et par e-mail à partir des événements d'automatisation : un événement `analytics/track` (ou un déclencheur d'enregistrement/d'authentification) se diffuse vers les canaux, et une action `email/send` délivre le message. Composez-les avec le [contrôle de flux](/fr/automation-flow-control) et le [regroupement par lots digest](/fr/automation-data-actions) pour les résumés quotidiens.
:::

## Pages connexes

- [Vue d'ensemble des actions](/fr/automation-actions-overview) — propriétés de base et carte des familles.
- [Variables d'environnement](/fr/automation-env-vars) — secrets SMTP et de fournisseur.
- [Actions de données et d'état](/fr/automation-data-actions) — `digest` pour le regroupement des notifications.
- [Analytique](/fr/analytics) — la surface analytique qui consomme les événements suivis.

# Actions IA

La famille `ai` exécute des opérations de modèle de langage comme étapes d'automatisation. Quatre operators couvrent la génération libre, la classification, l'extraction structurée et l'exécution d'agents autonomes. Le fournisseur et le modèle sont explicites par action ; les informations d'identification proviennent d'une [connexion](/fr/automation-connections) stockée. Pour les points de terminaison auto-hébergés ou personnalisés (par ex. Ollama), l'URL de base se configure une seule fois via la variable d'environnement `AI_BASE_URL`, et non par action.

| Operator   | Objectif                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------ |
| `generate` | Produit du texte libre (ou du JSON) à partir d'un prompt.                                  |
| `classify` | Affecte une entrée à l'une d'un ensemble fixe de catégories.                               |
| `extract`  | Extrait des données structurées correspondant à un schéma à partir de texte non structuré. |
| `agent`    | Invoque un agent autonome configuré pour effectuer une tâche multi-étapes.                 |

**Props de fournisseur partagées :** `provider` vaut `openai` / `anthropic` / `ollama` / `custom` ; `model` est l'identifiant du modèle ; `connection` référence des informations d'identification stockées. Les points de terminaison auto-hébergés (par ex. Ollama) sont ciblés via la variable d'environnement `AI_BASE_URL`.

## generate

| Prop             | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `provider`       | `openai` / `anthropic` / `ollama` / `custom`. **Requis.**        |
| `model`          | Identifiant du modèle. **Requis.**                               |
| `prompt`         | Le prompt utilisateur (templatable). **Requis.**                 |
| `systemPrompt`   | Prompt système optionnel.                                        |
| `temperature`    | Température d'échantillonnage.                                   |
| `maxTokens`      | Nombre maximal de tokens à générer.                              |
| `responseFormat` | `text` (par défaut) ou `json`.                                   |
| `connection`     | Connexion stockée fournissant les informations d'identification. |

```yaml
- name: draftReply
  type: ai
  operator: generate
  props:
    provider: anthropic
    model: claude-sonnet
    systemPrompt: 'You are a concise support agent.'
    prompt: 'Draft a reply to: {{trigger.comment.body}}'
    responseFormat: text
    connection: anthropic-key
```

## classify

| Prop            | Description                                               |
| --------------- | --------------------------------------------------------- |
| `input`         | Texte à classer (templatable). **Requis.**                |
| `categories`    | Tableau de libellés de catégories candidates. **Requis.** |
| _(fournisseur)_ | `provider`, `model`, `connection?`                        |

```yaml
- name: triage
  type: ai
  operator: classify
  props:
    provider: openai
    model: gpt-4o-mini
    input: '{{trigger.data.message}}'
    categories: [bug, billing, feature-request, spam]
    connection: openai-key
```

## extract

| Prop            | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `input`         | Texte non structuré à partir duquel extraire (templatable). **Requis.** |
| `schema`        | JSON Schema décrivant la forme de sortie souhaitée. **Requis.**         |
| _(fournisseur)_ | `provider`, `model`, `connection?`                                      |

```yaml
- name: parseInvoice
  type: ai
  operator: extract
  props:
    provider: openai
    model: gpt-4o
    input: '{{extractText.result}}'
    schema:
      total: { type: number }
      due_date: { type: string }
      vendor: { type: string }
    connection: openai-key
```

## agent

Invoque un agent autonome configuré dans les agents IA de l'application. L'agent planifie et exécute plusieurs étapes avec ses outils délimités.

| Prop             | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `agent`          | Nom d'un agent configuré. **Requis.**                            |
| `task`           | L'instruction de tâche (templatable). **Requis.**                |
| `context`        | Contexte clé-valeur transmis à l'agent.                          |
| `maxSteps`       | Plafond sur les étapes de raisonnement/d'outil de l'agent.       |
| `responseFormat` | `text` (par défaut) ou `json`.                                   |
| `timeout`        | Timeout par invocation en ms.                                    |
| `connection`     | Connexion stockée fournissant les informations d'identification. |

```yaml
- name: resolve
  type: ai
  operator: agent
  props:
    agent: support-resolver
    task: 'Resolve ticket {{trigger.data.id}} using the knowledge base.'
    context: { customerTier: '{{trigger.data.tier}}' }
    maxSteps: 8
    responseFormat: json
```

:::callout
**Routage de fournisseur éco-responsable.** Les appels IA passent par le résolveur de précédence de fournisseurs régi par `ECO_AI_PROVIDER_PRECEDENCE` (par défaut `local-first`) — ne codez jamais en dur un fournisseur cloud unique lorsqu'un modèle local peut servir la requête. Voir [Vue d'ensemble de l'IA](/fr/ai-overview).
:::

## Pages connexes

- [Vue d'ensemble de l'IA](/fr/ai-overview) — fournisseurs, modèles et routage éco.
- [Agents IA](/fr/ai-agents) — configuration des agents autonomes invoqués par `ai/agent`.
- [Connexions](/fr/automation-connections) — informations d'identification pour les fournisseurs IA.
- [Approbation et délai](/fr/automation-approval-delay) — filtres humains autour de la sortie IA.

# Actions d'approbation et de délai

Ces deux familles **mettent en pause** un workflow en cours d'exécution. La famille `approval` attend une décision humaine (human-in-the-loop). La famille `delay` attend une durée, une date-heure, un rappel de webhook externe, ou cadence une file d'éléments.

## Approval — Human-in-the-loop

Un operator, `request`. Il suspend l'exécution, notifie les approbateurs, et reprend une fois qu'une décision est enregistrée (ou que le timeout se déclenche). Nécessite que `app.auth` soit configuré.

| Prop        | Description                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `approvers` | `all-admins`, ou un tableau d'adresses e-mail / noms de rôles. **Requis.**                                                                                   |
| `message`   | Message affiché aux approbateurs (templatable). **Requis.**                                                                                                  |
| `options`   | Choix d'approbation, minimum 2 (`{ value, label? }`). Par défaut `[{ value: approve }, { value: reject }]`. La `value` choisie devient la sortie de l'étape. |
| `timeout`   | Durée d'attente (par ex. `24h`, `7d`). Aucun timeout par défaut.                                                                                             |
| `onTimeout` | En cas de timeout : `approve` (approbation automatique), `reject` (rejet automatique), ou `escalate` (notifier l'escalade).                                  |
| `notifyVia` | Canal de notification : `email` (par défaut), `webhook`, ou `both`.                                                                                          |

```yaml
- name: approveRefund
  type: approval
  operator: request
  props:
    approvers: all-admins
    message: 'Approve refund of ${{trigger.data.amount}} for order {{trigger.data.id}}?'
    options:
      - { value: approve, label: 'Approve refund' }
      - { value: reject, label: 'Deny' }
    timeout: 48h
    onTimeout: reject
    notifyVia: email
```

:::callout
**Branchez sur la décision.** La sortie de l'étape d'approbation (la `value` de l'option choisie) alimente naturellement un [`path/branch`](/fr/automation-flow-control) afin que le workflow puisse emprunter des chemins différents selon approve ou reject.
:::

## Delay — Wait, Queue, Webhook

Trois operators qui mettent l'exécution en pause de différentes manières.

### wait

Met en pause pendant une durée fixe ou jusqu'à une date-heure précise.

| Prop       | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `duration` | Délai sous forme de nombre + unité (`ms`/`s`/`m`/`h`/`d`), par ex. `30s`, `24h`, `7d`.      |
| `until`    | Date-heure ISO 8601 (ou gabarit) jusqu'à laquelle attendre, par ex. `2025-12-01T09:00:00Z`. |

```yaml
- name: cooldown
  type: delay
  operator: wait
  props: { duration: 15m }
```

### queue

Traite les éléments en file un par un avec un espacement configurable — idéal pour les API en aval à débit limité.

| Prop           | Description                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `interval`     | Délai minimal entre le traitement de chaque élément — nombre + unité (`ms`/`s`/`m`/`h`), par ex. `500ms`, `2s`. **Requis.** |
| `maxQueueSize` | Nombre maximal d'éléments dans la file avant que les nouvelles entrées soient rejetées (par défaut illimité).               |

```yaml
- name: paceApiCalls
  type: delay
  operator: queue
  props: { interval: 1s, maxQueueSize: 1000 }
```

### webhook

Met en pause jusqu'à ce qu'un rappel de webhook externe soit reçu (par ex. la fin d'une tâche tierce asynchrone).

| Prop           | Description                                                                             |
| -------------- | --------------------------------------------------------------------------------------- |
| `callbackId`   | Identifiant de rappel personnalisé (templatable). Généré automatiquement s'il est omis. |
| `timeout`      | Temps maximal d'attente du rappel — nombre + unité, par ex. `1h`, `7d`.                 |
| `onTimeout`    | En cas de timeout : `continue`, `stop`, ou `error` (par défaut `error`).                |
| `expectedData` | Forme attendue utilisée pour valider la charge utile du rappel entrant.                 |

```yaml
- name: awaitProcessing
  type: delay
  operator: webhook
  props:
    callbackId: 'job-{{trigger.data.id}}'
    timeout: 2h
    onTimeout: error
```

## Pages connexes

- [Vue d'ensemble des actions](/fr/automation-actions-overview) — propriétés de base et carte des familles.
- [Contrôle de flux](/fr/automation-flow-control) — brancher sur une décision d'approbation.
- [HTTP et webhooks](/fr/automation-http-actions) — réponses de webhook entrant et envois sortants.
- [Vue d'ensemble de l'authentification](/fr/auth-overview) — `app.auth` (requis pour les approbations).

# Connexions

Les connexions stockent les informations d'identification de services externes **une seule fois** dans le tableau de premier niveau `app.connections[]`, puis les référencent depuis les actions HTTP et IA via `$connection.NAME`. Sovrium attache la bonne authentification à chaque requête et — pour OAuth2 — rafraîchit les jetons automatiquement.

```yaml
connections:
  - name: crm-oauth
    label: Acme CRM
    type: oauth2
    props:
      provider: google
      clientId: $env.GOOGLE_CLIENT_ID
      clientSecret: $env.GOOGLE_CLIENT_SECRET
      scopes: [openid, email, profile]
```

Chaque connexion partage trois champs de base et un objet `props` typé :

| Propriété     | Description                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`        | Identifiant en kebab-case (`^[a-z][a-z0-9-]*$`, max 100). Référencé comme `$connection.NAME`. **Requis.**           |
| `label`       | Libellé lisible.                                                                                                    |
| `description` | À quoi sert la connexion.                                                                                           |
| `type`        | `oauth2` / `apiKey` / `basic` / `bearer`. **Requis.** Détermine la forme de `props`.                                |
| `props`       | Configuration d'identification spécifique au type (ci-dessous). Les valeurs secrètes devraient utiliser `$env.VAR`. |

Les noms de connexion doivent être uniques dans toute l'application.

## OAuth2

OAuth2 complet avec les grants authorization-code ou client-credentials, PKCE, rafraîchissement de jeton, et jetons par utilisateur vs partagés (application).

| Champ `props`          | Description                                                                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`             | Raccourci de fournisseur connu (par ex. `google`, `github`, `slack`). Peut inférer les URL d'auth/de jeton.                                                                                        |
| `clientId`             | ID client OAuth2 (prend en charge `$env.VAR`). **Requis.**                                                                                                                                         |
| `clientSecret`         | Secret client OAuth2 (prend en charge `$env.VAR`). **Requis.**                                                                                                                                     |
| `authorizationUrl`     | Point de terminaison d'autorisation (requis pour les fournisseurs personnalisés).                                                                                                                  |
| `tokenUrl`             | Point de terminaison de jeton (requis pour les fournisseurs personnalisés).                                                                                                                        |
| `scopes`               | Tableau de scopes à demander.                                                                                                                                                                      |
| `redirectUri`          | URI de redirection enregistrée auprès du fournisseur. Requise à l'exécution — la génération automatique n'est pas implémentée.                                                                     |
| `grantType`            | `authorizationCode` (par défaut) ou `clientCredentials`.                                                                                                                                           |
| `pkce`                 | Méthode PKCE : `S256` (recommandée), `plain`, ou `none` (par défaut).                                                                                                                              |
| `audience`             | Audience d'API / identifiant de ressource (par ex. une URL d'audience Auth0).                                                                                                                      |
| `authenticationMethod` | Comment les identifiants client sont envoyés sur les requêtes de jeton : `header` (HTTP Basic, par défaut RFC 6749) ou `body` (paramètres de formulaire). Honoré par le grant de rafraîchissement. |
| `extraAuthParams`      | Paramètres supplémentaires ajoutés à l'URL d'autorisation (par ex. `access_type: offline`, `prompt: consent`).                                                                                     |
| `extraTokenParams`     | Paramètres supplémentaires ajoutés aux requêtes d'échange de jeton.                                                                                                                                |
| `scope`                | Portée de la connexion : `app` (jeton partagé réservé aux administrateurs, par défaut) ou `user` (jetons par utilisateur).                                                                         |

```yaml
- name: hubspot
  type: oauth2
  props:
    clientId: $env.HUBSPOT_CLIENT_ID
    clientSecret: $env.HUBSPOT_CLIENT_SECRET
    authorizationUrl: 'https://app.hubspot.com/oauth/authorize'
    tokenUrl: 'https://api.hubapi.com/oauth/v1/token'
    scopes: [crm.objects.contacts.read]
    redirectUri: 'https://myapp.example.com/oauth/callback'
    pkce: S256
    scope: user
    extraAuthParams: { access_type: offline, prompt: consent }
```

:::callout
**Jetons d'application vs par utilisateur.** `scope: app` stocke un jeton partagé unique utilisable par les administrateurs. `scope: user` émet et stocke des jetons par utilisateur final, de sorte que les actions HTTP/IA de chaque utilisateur agissent en son nom. Les flux **client-credentials** (machine à machine, sans utilisateur) définissent `grantType: clientCredentials`. Le rafraîchissement de jeton se produit automatiquement ; la requête de rafraîchissement honore `authenticationMethod`.
:::

## Clé API

Clé API envoyée dans un en-tête configurable, avec un préfixe optionnel.

| Champ `props` | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `key`         | Valeur de la clé API (généralement `$env.VAR`). **Requis.**         |
| `header`      | Nom de l'en-tête pour la clé (par défaut `X-API-Key`).              |
| `prefix`      | Préfixe avant la valeur dans l'en-tête (par ex. `Bearer`, `Token`). |

```yaml
- name: github-api
  type: apiKey
  props: { key: $env.GITHUB_TOKEN, header: Authorization, prefix: Bearer }
```

## Authentification basic

Authentification HTTP Basic.

| Champ `props` | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| `username`    | Nom d'utilisateur (prend en charge `$env.VAR`). **Requis.** |
| `password`    | Mot de passe (prend en charge `$env.VAR`). **Requis.**      |

```yaml
- name: legacy-api
  type: basic
  props: { username: $env.LEGACY_USER, password: $env.LEGACY_PASS }
```

## Jeton bearer

Un jeton bearer statique envoyé dans l'en-tête `Authorization`.

| Champ `props` | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| `token`       | Valeur du jeton bearer (généralement `$env.VAR`). **Requis.** |

```yaml
- name: internal-svc
  type: bearer
  props: { token: $env.INTERNAL_SERVICE_TOKEN }
```

## Référencer une connexion

Attachez une connexion à une action HTTP ou IA via la prop `connection` :

```yaml
- name: fetch
  type: http
  operator: get
  props: { url: 'https://api.example.com/me', connection: github-api }
```

## Pages connexes

- [HTTP et webhooks](/fr/automation-http-actions) — actions qui consomment les connexions.
- [Actions IA](/fr/automation-ai-actions) — fournisseurs IA authentifiés via des connexions.
- [Variables d'environnement](/fr/automation-env-vars) — secrets `$env` référencés par les props de connexion.
- [Vue d'ensemble de l'authentification](/fr/auth-overview) — authentification de l'utilisateur final (distincte des connexions sortantes).

# Variables d'environnement

Déclarez les variables d'environnement dont vos automatisations ont besoin dans le tableau de premier niveau `app.env[]`. Chaque entrée documente une variable, indique si elle est requise, et fournit une valeur par défaut optionnelle. À l'exécution, référencez une valeur partout où une prop de gabarit ou de connexion est acceptée avec `$env.VAR_NAME`.

```yaml
env:
  - { key: SLACK_WEBHOOK_URL, description: Slack incoming webhook URL }
  - { key: STRIPE_SECRET, description: Stripe API secret, required: true }
  - { key: REGION, description: Default region, required: false, default: eu-west }
```

## Propriétés des variables d'environnement

| Propriété     | Description                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | Nom de la variable en snake*case majuscule (`^[A-Z]A-Z0-9*]\*$`, par ex. `API_KEY`). **Requis.**                                                  |
| `description` | À quoi sert la variable.                                                                                                                          |
| `required`    | Indique si la variable doit être définie (par défaut `true`). Lorsqu'elle est requise et non définie, la validation échoue au démarrage.          |
| `default`     | Valeur de repli utilisée lorsque la variable n'est pas définie. Lorsque `required` et `default` sont tous deux présents, `default` sert de repli. |

Les clés doivent être uniques dans toute l'application.

## Référencer des secrets

Utilisez `$env.VAR_NAME` dans les props d'action, les props de connexion et l'authentification de webhook :

```yaml
connections:
  - name: openai-key
    type: bearer
    props: { token: $env.OPENAI_API_KEY }

automations:
  - name: notify
    trigger: { type: record, table: orders, events: [create] }
    actions:
      - name: ping
        type: http
        operator: post
        props:
          url: $env.SLACK_WEBHOOK_URL
          body: { text: 'New order {{trigger.data.id}}' }
```

:::callout
**Les secrets ne sont jamais journalisés.** Les valeurs résolues depuis `$env` sont masquées des journaux d'exécution, des sorties d'étape affichées dans l'interface d'administration, et de l'API des exécutions. Stockez les informations d'identification dans `$env` (ou une connexion) plutôt que de les incorporer en ligne dans les props d'action.
:::

## Variables d'environnement opérateur frugales par défaut

Au-delà de `app.env` (que l'auteur du schéma déclare), l'empreinte d'exécution de Sovrium est régie par des variables d'environnement `ECO_*` contrôlées par l'opérateur (par ex. `ECO_IMAGE_FORMAT`, `ECO_AI_PROVIDER_PRECEDENCE`). Celles-ci ne font **pas** partie du schéma d'application — les opérateurs se désengagent, jamais ne s'engagent. Les actions IA et les transformations d'images invoquées depuis les automatisations honorent ces valeurs par défaut automatiquement. Voir [Vue d'ensemble de l'IA](/fr/ai-overview) et [Transformations d'images](/fr/image-transforms).

## Pages connexes

- [Connexions](/fr/automation-connections) — blocs d'identification qui consomment `$env`.
- [Vue d'ensemble des actions](/fr/automation-actions-overview) — où `$env` est interpolé.
- [HTTP et webhooks](/fr/automation-http-actions) — secrets dans les en-têtes de requête.

# Exécutions d'automatisation

Chaque fois qu'un déclencheur se déclenche, Sovrium enregistre une **exécution** — une ligne capturant la charge utile du déclencheur, le statut et la sortie de chaque étape, et le résultat final. L'API des exécutions vous permet de lister, inspecter, rejouer et annuler les exécutions à des fins de surveillance et de débogage.

## API des exécutions

| Méthode et chemin                       | Objectif                                                                   |
| --------------------------------------- | -------------------------------------------------------------------------- |
| `GET /api/automations/runs`             | Liste les exécutions (paginé, filtrable par statut / automatisation).      |
| `GET /api/automations/runs/:id`         | Détail de l'exécution incluant les résultats par étape.                    |
| `POST /api/automations/runs/:id/replay` | Rejoue une exécution, en reprenant à partir de la première étape en échec. |
| `POST /api/automations/runs/:id/cancel` | Annule une exécution en attente ou en cours.                               |

```bash
# List failed runs of a specific automation
GET /api/automations/runs?status=failed&automationName=welcome-email

# Replay a failed run
POST /api/automations/runs/550e8400-.../replay
```

## Statuts d'exécution

| Statut                  | Signification                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `pending`               | En file d'attente, en attente d'exécution (ou en attente d'un créneau de concurrence).         |
| `running`               | En cours d'exécution.                                                                          |
| `completed`             | Toutes les actions ont réussi.                                                                 |
| `completed-with-errors` | Terminée, mais une ou plusieurs étapes ont échoué sous `continueOnError`.                      |
| `failed`                | Une action a généré une erreur (déclenche le déclencheur `automation-failure` + les relances). |
| `timed-out`             | A dépassé le `timeout` au niveau de l'automatisation ou de l'action. Distinct de `failed`.     |
| `exhausted`             | A échoué après épuisement de toutes les tentatives de relance configurées (dead-letter).       |
| `cancelled`             | Annulée manuellement via l'API.                                                                |

## Statuts d'étape

| Statut      | Signification                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `running`   | En cours d'exécution.                                                                               |
| `completed` | A réussi.                                                                                           |
| `failed`    | A généré une erreur.                                                                                |
| `skipped`   | Non exécutée — par ex. après un arrêt `filter/continue` ou lors d'une récupération d'échec partiel. |

## Rejeu et reprise idempotente

Le rejeu d'une exécution partiellement échouée **saute les étapes déjà terminées** et reprend à partir de la première étape en échec (reprise idempotente) — les étapes terminées ne sont jamais réexécutées. Le rejeu crée toujours une **nouvelle** exécution plutôt que de muter l'originale, préservant l'historique d'audit.

:::callout
**Distinguez la durée de l'erreur.** Une exécution qui dépasse son `timeout` est enregistrée comme `timed-out`, et non `failed`, afin que les opérateurs puissent distinguer les workflows emballés des véritables erreurs. Une fois les relances épuisées, le statut devient `exhausted` et le [déclencheur `automation-failure`](/fr/automation-triggers) se déclenche avec l'historique complet des tentatives.
:::

## Pages connexes

- [Relance et échec](/fr/automation-retry-failure) — politiques de relance, timeouts, dead-letter, idempotence.
- [Déclencheurs](/fr/automation-triggers) — le déclencheur `automation-failure` qui réagit aux exécutions `failed`/`exhausted`.
- [Vue d'ensemble des automatisations](/fr/automations-overview) — concurrence et cycle de vie de l'exécution.

# Gestion des relances et des échecs

Les automatisations sont résilientes par configuration : relancez les échecs transitoires avec un backoff, encadrez les étapes emballées avec des timeouts, récupérez les exécutions partiellement échouées de manière idempotente, et acheminez les exécutions épuisées vers un gestionnaire d'échec.

## Politique de relance

Un bloc `retry` peut être défini au niveau de l'**automatisation** (exécution entière) ou au niveau de l'**action** (étape unique).

| Propriété     | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| `maxAttempts` | Nombre maximal de tentatives de relance (1–10). **Requis.**                |
| `delayMs`     | Délai de base entre les relances en ms (100–60000, par défaut 1000).       |
| `strategy`    | `fixed` (délai constant, par défaut) ou `exponential` (backoff croissant). |

```yaml
automations:
  - name: sync-inventory
    trigger: { type: cron, expression: '0 * * * *' }
    retry: { maxAttempts: 5, delayMs: 2000, strategy: exponential }
    actions:
      - name: pull
        type: http
        operator: get
        props: { url: $env.INVENTORY_API, expectedStatus: [200] }
        retry: { maxAttempts: 3, strategy: fixed } # per-action override
```

## Timeouts

Deux portées de timeout indépendantes :

| Portée                | Où                                 | Effet                                                                                         |
| --------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
| Automatisation        | `automation.timeout` (1000–900000) | Plafonne la durée totale de l'exécution. À l'expiration, l'exécution est marquée `timed-out`. |
| Action (uniforme)     | `action.timeout` (1000–900000)     | Plafonne une étape ; `retry`/`continueOnError` s'appliquent toujours.                         |
| Action (gestionnaire) | `action.props.timeout`             | Encadrement interne par type (par ex. `http`, `code`, `automation/call`).                     |

Une exécution `timed-out` est **distincte de `failed`** afin que les opérateurs puissent distinguer une durée emballée des erreurs.

## Continuer en cas d'erreur

Définissez `continueOnError: true` sur une action afin que son échec n'interrompe pas l'exécution. Les actions suivantes s'exécutent toujours et l'exécution se termine en `completed-with-errors`.

```yaml
- name: bestEffortLog
  type: analytics
  operator: track
  continueOnError: true
  props: { event: order.created, properties: { id: '{{trigger.data.id}}' } }
```

## Dead-letter et épuisement

Lorsqu'une exécution échoue après avoir épuisé tous les `maxAttempts` configurés, elle passe au statut `exhausted` (dead-letter). Chaque tentative est enregistrée avec un horodatage, un message d'erreur et une trace de pile. Le [déclencheur `automation-failure`](/fr/automation-triggers) se déclenche après l'épuisement, transmettant au gestionnaire d'échec l'historique complet des tentatives — permettant une gestion d'échec centralisée sans configuration de notification par automatisation.

## Récupération d'échec partiel et idempotence

Lorsqu'une exécution échoue au milieu du pipeline, les étapes terminées affichent `completed`, l'étape en échec affiche `failed`, et les étapes en aval affichent `skipped`. Le rejeu de l'exécution **reprend à partir de l'étape en échec**, en sautant les étapes déjà terminées (reprise idempotente). Le rejeu crée toujours une nouvelle exécution, sans jamais muter l'originale.

:::callout
**Déduplication des webhooks.** Les déclencheurs webhook acceptent une `deduplicationKey` (un gabarit sur la charge utile) et une `deduplicationWindow` (secondes) pour rejeter les exécutions en double issues de charges utiles identiques. Combinée à la reprise idempotente, cela rend la livraison au-moins-une-fois sûre. Voir [Déclencheurs](/fr/automation-triggers).
:::

## Pages connexes

- [Exécutions](/fr/automation-runs) — statuts d'exécution/d'étape, rejeu et annulation.
- [Déclencheurs](/fr/automation-triggers) — déclencheur `automation-failure` et déduplication de webhook.
- [Vue d'ensemble des actions](/fr/automation-actions-overview) — props de base `retry`, `timeout`, `continueOnError`.

# Actions d'authentification

La famille `auth` gère les comptes utilisateurs dans le cadre d'un workflow — provisionnement d'utilisateurs, changement de rôles, et modération de comptes. Ces actions nécessitent que `app.auth` soit configuré et passent par le même RBAC que le reste de la plateforme. Quatre operators.

| Operator     | Props                                 | Description                                                                                                                                  |
| ------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `createUser` | `email`, `name`, `password?`, `role?` | Crée un nouveau compte utilisateur (mot de passe généré automatiquement s'il est omis ; le rôle vaut par défaut le `defaultRole` configuré). |
| `assignRole` | `userId`, `role`                      | Attribue un rôle (`admin`, `member`, `viewer`, ou personnalisé) à un utilisateur existant.                                                   |
| `banUser`    | `userId`, `reason?`                   | Bannit un compte utilisateur ; `reason` est stocké pour la piste d'audit.                                                                    |
| `unbanUser`  | `userId`                              | Lève un bannissement sur un compte utilisateur.                                                                                              |

```yaml
# Provision a teammate when an invite record is created
- name: provision
  type: auth
  operator: createUser
  props:
    email: '{{trigger.data.email}}'
    name: '{{trigger.data.name}}'
    role: member

# Promote on approval
- name: promote
  type: auth
  operator: assignRole
  props: { userId: '{{trigger.data.user_id}}', role: admin }
```

:::callout
**Les actions d'authentification nécessitent `app.auth`.** Elles opèrent sur le même magasin d'utilisateurs et les mêmes rôles que l'authentification de l'utilisateur final. Voir [Vue d'ensemble de l'authentification](/fr/auth-overview) et [Rôles et RBAC](/fr/auth-roles-rbac).
:::

## Pages connexes

- [Vue d'ensemble de l'authentification](/fr/auth-overview) — configuration de l'authentification.
- [Rôles et RBAC](/fr/auth-roles-rbac) — les rôles attribués par `assignRole`.
- [Vue d'ensemble des actions](/fr/automation-actions-overview) — propriétés de base et carte des familles.

# Actions de code

La famille `code` exécute du TypeScript personnalisé comme étape d'automatisation pour la logique que les actions déclaratives ne couvrent pas. Un operator, `runTypescript`. La source est une fonction nommée `execute(context)` dont le corps est **vérifié au niveau des types au démarrage du serveur**.

| Prop        | Description                                                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | Source TypeScript pour une fonction nommée `execute(context)`. Dans les configurations TS, enveloppez avec `String(function execute(context: CodeContext) { … })` pour l'autocomplétion de l'IDE. **Requis.** |
| `inputData` | Paires clé-valeur résolues par gabarit transmises comme `context.inputData`.                                                                                                                                  |
| `input`     | Paires clé-valeur résolues par gabarit transmises comme `context.input` (mêmes règles de résolution que `inputData`).                                                                                         |
| `packages`  | Spécificateurs de paquets npm avec épinglage de version optionnel (par ex. `lodash`, `date-fns@3.6.0`, `@scope/pkg@1.2.3`). Résolus/installés au démarrage de l'application ou via `sovrium install`.         |
| `timeout`   | Timeout d'exécution en ms (1000–300000, par défaut 30000).                                                                                                                                                    |

## Contexte de code

La fonction `execute` reçoit un objet `context` :

| Membre              | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| `context.trigger`   | La charge utile du déclencheur.                                           |
| `context.steps`     | Sorties des étapes précédentes, indexées par nom d'étape.                 |
| `context.inputData` | Entrées résolues par gabarit depuis la prop `inputData`.                  |
| `context.input`     | Entrées résolues par gabarit depuis la prop `input`.                      |
| `context.env`       | Variables d'environnement (valeurs sensibles masquées dans les journaux). |
| `context.actions`   | Invoque des actions natives ou des modèles réutilisables depuis le code.  |
| `context.packages`  | Les paquets npm déclarés, accessibles par nom.                            |
| `context.log`       | Journalisation structurée : `info`, `warn`, `error`.                      |

```yaml
- name: enrich-lead
  type: code
  operator: runTypescript
  props:
    packages: [date-fns]
    inputData: { url: '{{trigger.data.profile_url}}' }
    code: |
      async function execute(context) {
        const res = await context.actions.http.get({ url: context.inputData.url })
        context.log.info('fetched', res.status)
        return { score: res.body.score, fetchedAt: new Date().toISOString() }
      }
```

:::callout
**Vérifié au niveau des types au démarrage, isolé en sandbox à l'exécution.** Le corps de `execute` est validé au démarrage de l'application, de sorte qu'une fonction malformée échoue rapidement plutôt qu'en cours d'exécution. Les `packages` déclarés sont résolus à l'avance et exposés via `context.packages` — ils ne sont pas récupérés à la demande à l'intérieur de la sandbox.
:::

## Pages connexes

- [Vue d'ensemble des actions](/fr/automation-actions-overview) — invocation des actions natives (également disponibles via `context.actions`) et des modèles `ref` réutilisables.
- [Variables d'environnement](/fr/automation-env-vars) — `context.env` et masquage des secrets.
- [HTTP et webhooks](/fr/automation-http-actions) — les actions HTTP accessibles depuis le code.

# Actions cloud

La famille `cloud` orchestre les applications locataires de **Sovrium Cloud** — provisionnement de leurs bases de données, démarrage de leurs processus, attachement de routes d'ingress, et démantèlement. Cinq operators. Ces actions sont **verrouillées** : elles ne s'exécutent que lorsque le processus hôte est démarré avec le drapeau d'environnement `SOVRIUM_CLOUD_MODE`.

| Operator       | Props                  | Description                                                                                     |
| -------------- | ---------------------- | ----------------------------------------------------------------------------------------------- |
| `provision-db` | `dbName`               | Provisionne une base de données logique pour un locataire (par ex. `tenant_acme`).              |
| `spawn-app`    | `appSlug`, `configRef` | Démarre un processus d'application locataire à partir d'une référence de configuration validée. |
| `route-add`    | `domain`, `port`       | Attache une route d'ingress (domaine → port) à une application locataire.                       |
| `disable-app`  | `appSlug`              | Arrête une application locataire tout en préservant ses données.                                |
| `destroy-app`  | `appSlug`              | Démantèle une application locataire et supprime ses données.                                    |

| Prop        | Description                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `appSlug`   | Slug de l'application locataire — identifiant stable en minuscules-kebab (par ex. `acme-crm`). Templatable. |
| `dbName`    | Nom de la base de données logique du locataire (par ex. `tenant_acme`). Templatable.                        |
| `configRef` | Référence à la configuration locataire validée à démarrer (id / réf de ligne / URL). Templatable.           |
| `domain`    | Domaine de route à attacher — un hôte nu (par ex. `acme.sovrium.app`). Templatable.                         |
| `port`      | Port d'écoute de l'application locataire ciblé par la route (1–65535).                                      |

```yaml
# Onboard a new tenant when a signup record is approved
automations:
  - name: onboard-tenant
    trigger: { type: record, table: tenant_signups, events: [update] }
    actions:
      - name: db
        type: cloud
        operator: provision-db
        props: { dbName: 'tenant_{{trigger.data.slug}}' }
      - name: boot
        type: cloud
        operator: spawn-app
        props: { appSlug: '{{trigger.data.slug}}', configRef: '{{trigger.data.config_ref}}' }
      - name: route
        type: cloud
        operator: route-add
        props: { domain: '{{trigger.data.slug}}.sovrium.app', port: 3000 }
```

:::callout
**Verrouillé, jamais contrôlé par le schéma.** Les actions cloud sont acceptées partout par le schéma, mais une configuration qui les utilise est **rejetée au moment de la validation** sauf si l'hôte s'exécute avec le verrou d'environnement de processus `SOVRIUM_CLOUD_MODE`. Le verrou est une préoccupation de l'hôte — jamais un champ de schéma. N'utilisez ces actions que dans une application de plan de contrôle Sovrium Cloud.
:::

## Pages connexes

- [Vue d'ensemble des actions](/fr/automation-actions-overview) — propriétés de base et carte des familles.
- [Déclencheurs](/fr/automation-triggers) — déclencheurs d'enregistrement/manuels qui pilotent l'intégration des locataires.
- [Variables d'environnement](/fr/automation-env-vars) — environnement hôte contrôlé par l'opérateur (distinct de `app.env`).

# Présentation des buckets

Les buckets sont des conteneurs nommés pour les fichiers téléversés. Chaque bucket porte sa propre limite de taille, ses types MIME autorisés, sa visibilité publique/privée et ses permissions d'accès. Les tables référencent les buckets via des [champs de pièce jointe](/fr/attachment-fields), les [formulaires](/fr/form-file-uploads) y écrivent des fichiers, et l'API REST expose des points de terminaison de téléversement, de téléchargement, d'URL signée et de transformation d'image.

Deux préoccupations sont délibérément séparées :

- **Où les fichiers sont stockés** — le _backend_ de stockage — est contrôlé par l'opérateur via des variables d'environnement (`STORAGE_PROVIDER` et consorts). Il n'apparaît jamais dans le schéma de l'application.
- **Comment les fichiers sont organisés** — les _buckets_ — est une configuration d'application déclarée dans le tableau de premier niveau `buckets[]` de votre configuration.

```yaml
buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/jpeg, image/png, image/webp]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]
```

Lorsque `buckets` est entièrement omis, Sovrium provisionne un bucket `default` implicite (`public: false`, permissions par défaut standard).

## Backends de stockage

Le backend est choisi au moment du déploiement avec `STORAGE_PROVIDER`. Les trois backends prennent en charge l'intégralité de la surface des opérations de fichiers, des URL signées et des transformations d'image.

| Backend                   | `STORAGE_PROVIDER`                     | Idéal pour                                      | Évolutivité          | URL présignées natives         |
| ------------------------- | -------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------ |
| Système de fichiers local | `local` (par défaut)                   | Développement, mononœud, auto-hébergé           | Limité par le disque | Non (Sovrium signe en interne) |
| S3 / compatible S3        | `s3`                                   | Production, scale-out                           | Illimité             | Oui (délégué au fournisseur)   |
| MinIO                     | `s3` + `STORAGE_FORCE_PATH_STYLE=true` | Magasin d'objets compatible S3 auto-hébergé     | Illimité             | Oui                            |
| PostgreSQL `bytea`        | `bytea`                                | Petits fichiers, déploiements mono-base simples | Limité par la base   | Non (Sovrium signe en interne) |

:::callout
**Frugal par défaut.** Le backend par défaut est `local` — zéro dépendance externe, reflétant la posture de base de données SQLite par défaut de Sovrium. N'optez _pour_ S3 que lorsque vous avez besoin de scale-out ou de déploiements multinœuds. Voir [Écoconception](/fr/ecoconception).
:::

### Variables d'environnement du backend

| Variable                   | Requis  | Par défaut  | Objectif                                                                        |
| -------------------------- | ------- | ----------- | ------------------------------------------------------------------------------- |
| `STORAGE_PROVIDER`         | Non     | `local`     | Backend de stockage : `s3`, `local` ou `bytea`.                                 |
| `STORAGE_ENDPOINT`         | S3 seul | —           | URL du point de terminaison compatible S3.                                      |
| `STORAGE_BUCKET`           | S3 seul | —           | Nom du bucket S3 sous-jacent (le magasin d'objets hôte, pas un bucket Sovrium). |
| `STORAGE_REGION`           | S3 seul | `us-east-1` | Région AWS.                                                                     |
| `STORAGE_ACCESS_KEY`       | S3 seul | —           | ID de clé d'accès S3.                                                           |
| `STORAGE_SECRET_KEY`       | S3 seul | —           | Clé d'accès secrète S3.                                                         |
| `STORAGE_FORCE_PATH_STYLE` | Non     | `false`     | Utiliser des URL de style chemin (requis pour MinIO).                           |

:::callout
**Les buckets Sovrium sont des préfixes de chemin, pas des buckets S3.** Chaque bucket que vous déclarez dans `buckets[]` correspond à un préfixe de chemin à l'intérieur du bucket hôte unique configuré par `STORAGE_BUCKET` (par ex. `avatars/`, `documents/`). Un seul bucket S3 contient tous vos buckets Sovrium.
:::

Voir [Variables d'environnement](/fr/env-vars) pour la référence complète des variables côté opérateur.

## Propriétés du bucket

Chaque entrée du tableau `buckets[]` accepte les propriétés suivantes.

| Propriété          | Description                                                                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`             | Nom de bucket unique. Minuscules, alphanumérique, traits d'union ; doit commencer par une lettre ; 63 caractères max (compatibilité de préfixe S3). Utilisé comme préfixe de chemin de stockage. |
| `public`           | Booléen. Lorsque `true`, les fichiers sont servis sans URL signées. Vaut `false` par défaut (privé).                                                                                             |
| `maxFileSize`      | Taille maximale de fichier en octets pour les téléversements vers ce bucket. Surcharge le `STORAGE_MAX_FILE_SIZE` global. Doit être ≥ 1.                                                         |
| `allowedMimeTypes` | Tableau des types MIME autorisés pour les téléversements. Prend en charge les caractères génériques (par ex. `image/*`). Lorsqu'il est omis, tous les types sont acceptés. Minimum une entrée.   |
| `permissions`      | Contrôle d'accès par opération. Voir [Permissions](#permissions) ci-dessous.                                                                                                                     |

:::callout
**La validation du nom est stricte.** `Avatars` (majuscule) et `123-bucket` (chiffre en tête) sont rejetés par `sovrium validate`. Exemples valides : `avatars`, `documents`, `public-assets`, `user-uploads`. Les noms en double dans le tableau sont également rejetés au moment de la validation.
:::

## Permissions

Les permissions de bucket utilisent le même format partagé `PermissionValueSchema` que les [permissions de table](/fr/table-permissions) : chaque opération accepte `all`, `authenticated`, ou une liste de noms de rôles.

| Opération    | Description                                         | Par défaut                                |
| ------------ | --------------------------------------------------- | ----------------------------------------- |
| `upload`     | Qui peut téléverser des fichiers vers ce bucket.    | `authenticated`                           |
| `download`   | Qui peut télécharger des fichiers depuis ce bucket. | `all` si public, `authenticated` si privé |
| `sign`       | Qui peut générer des URL de téléchargement signées. | `authenticated`                           |
| `signUpload` | Qui peut générer des URL de téléversement signées.  | `[admin]`                                 |
| `delete`     | Qui peut supprimer des fichiers de ce bucket.       | `[admin]`                                 |

Valeurs de permission :

- `all` — tout le monde, y compris les requêtes non authentifiées.
- `authenticated` — tout utilisateur connecté.
- `['admin', 'editor']` — uniquement les rôles listés.

```yaml
buckets:
  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf, text/csv]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]
```

Lorsqu'un bucket omet entièrement `permissions`, les valeurs par défaut par opération ci-dessus s'appliquent — notamment, seul le rôle `admin` peut générer des URL signées.

## Public vs privé

| Visibilité                   | Comportement                                                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `public: true`               | Fichiers servis directement sans authentification ni URL signées. Convient aux avatars, logos, ressources marketing.                        |
| `public: false` (par défaut) | Les fichiers requièrent soit une authentification (correspondant à la permission `download`) soit une [URL signée](/fr/signed-urls) valide. |

Les opérateurs peuvent en outre exposer des préfixes de chemin globalement via `STORAGE_PUBLIC_PATHS` (voir [URL signées](/fr/signed-urls)).

## Exemple : buckets multiples

Un bucket d'images public aux côtés d'un bucket de documents privé, restreint par rôle.

```yaml
buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/*]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]
```

## Pages associées

- [Opérations sur les fichiers](/fr/file-operations) — points de terminaison de téléversement, téléchargement, liste et suppression.
- [URL signées](/fr/signed-urls) — accès limité dans le temps aux fichiers privés.
- [Transformations d'image](/fr/image-transforms) — redimensionnement, recadrage et conversion de format à la volée.
- [Champs de pièce jointe](/fr/attachment-fields) — stocker des fichiers sur des enregistrements de table.
- [Téléversements de fichiers de formulaire](/fr/form-file-uploads) — accepter des fichiers via des formulaires.
- [Variables d'environnement](/fr/env-vars) — configuration du backend côté opérateur.

# Opérations sur les fichiers

Chaque bucket expose une API REST pour le cycle de vie principal des fichiers : téléversement, téléchargement et suppression. Les opérations sont authentifiées par rapport aux [permissions](/fr/buckets-overview#permissions) du bucket, durcies contre la traversée de chemin et le XSS, et intégrées au [modèle de soft-delete](/fr/tables-overview) de Sovrium.

Le paramètre de chemin `{bucket}` référence un nom de bucket déclaré dans votre tableau `buckets[]`. Voir [Présentation des buckets](/fr/buckets-overview).

## Points de terminaison

| Méthode  | Point de terminaison                | Description                                                                                           |
| -------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `POST`   | `/api/buckets/{bucket}/files`       | Téléverse un fichier (données de formulaire multipart). Renvoie `201` avec la clé de fichier générée. |
| `GET`    | `/api/buckets/{bucket}/files/{key}` | Télécharge un fichier par clé. Renvoie le contenu du fichier avec le bon `Content-Type`.              |
| `DELETE` | `/api/buckets/{bucket}/files/{key}` | Supprime un fichier par clé du stockage.                                                              |
| `GET`    | `/api/admin/buckets/quota`          | _(Admin)_ Renvoie l'utilisation actuelle du stockage en octets.                                       |

## Téléversement

Envoyez le fichier sous forme de données de formulaire multipart. Le serveur le valide par rapport aux `maxFileSize` et `allowedMimeTypes` du bucket, génère une clé imprévisible, et le stocke dans le backend configuré.

```bash
curl -X POST https://app.example.com/api/buckets/documents/files \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@report.pdf"
```

```json
{
  "key": "documents/9f3c1e2a-7b44-4d10-9e21-8a6f0c1d2e3b.pdf",
  "filename": "report.pdf",
  "size": 245760,
  "mimeType": "application/pdf"
}
```

| Comportement                                        | Résultat                                                                  |
| --------------------------------------------------- | ------------------------------------------------------------------------- |
| Fichier valide dans les limites                     | `201` avec la clé de fichier générée.                                     |
| Corps de requête vide                               | `400 Bad Request`.                                                        |
| Dépasse la taille max du bucket ou globale          | `413 Payload Too Large` (rejeté tôt, avant la lecture complète du corps). |
| Dépasse le quota `STORAGE_MAX_TOTAL_SIZE`           | `507 Insufficient Storage`.                                               |
| Requête non authentifiée vers un bucket authentifié | `401 Unauthorized`.                                                       |

:::callout
**Les clés sont aléatoires.** Les téléversements reçoivent toujours une clé basée sur UUID, de sorte que les fichiers ne s'écrasent jamais l'un l'autre et que les URL de stockage sont indevinables. Deux téléversements du même nom de fichier produisent deux clés distinctes.
:::

## Téléchargement

```bash
curl https://app.example.com/api/buckets/documents/files/{key} \
  -H "Authorization: Bearer $TOKEN" -O
```

| Comportement                                                     | Résultat                                                   |
| ---------------------------------------------------------------- | ---------------------------------------------------------- |
| Le fichier existe, l'appelant a la permission `download`         | `200` avec le contenu du fichier et le bon `Content-Type`. |
| Clé inexistante                                                  | `404 Not Found`.                                           |
| Fichier privé, pas d'auth et pas d'[URL signée](/fr/signed-urls) | `403 Forbidden`.                                           |

Les réponses incluent un en-tête `Content-Disposition` — les fichiers non image sont servis en `attachment` pour empêcher le navigateur de les afficher en ligne.

## Suppression

```bash
curl -X DELETE https://app.example.com/api/buckets/documents/files/{key} \
  -H "Authorization: Bearer $TOKEN"
```

| Comportement                                           | Résultat                           |
| ------------------------------------------------------ | ---------------------------------- |
| Le fichier existe, l'appelant a la permission `delete` | `200`, fichier retiré du stockage. |
| Clé inexistante                                        | `404 Not Found`.                   |

## Durcissement de sécurité

Les opérations sur les fichiers appliquent automatiquement la [base de sécurité de pré-lancement](/fr/buckets-overview) récurrente pour les téléversements :

| Mesure                            | Comportement                                                                   |
| --------------------------------- | ------------------------------------------------------------------------------ |
| Traversée de chemin               | Les séquences `../` dans les noms de fichiers sont assainies ou rejetées.      |
| Octets nuls                       | Les noms de fichiers contenant des octets nuls sont rejetés.                   |
| Caractères spéciaux / unicode     | Encodés en toute sécurité pour le stockage.                                    |
| Clés aléatoires                   | Les clés basées sur UUID empêchent les URL devinables.                         |
| `X-Content-Type-Options: nosniff` | Envoyé sur chaque fichier servi.                                               |
| `Content-Security-Policy`         | Envoyé sur chaque fichier servi.                                               |
| Types sujets au XSS (HTML, SVG)   | Servis avec un `Content-Type` sûr ou forcés au téléchargement en pièce jointe. |

## Cycle de vie des fichiers

Les pièces jointes suivent le cycle de vie soft-delete-par-défaut de Sovrium. La présence du fichier suit l'enregistrement propriétaire :

| Action sur l'enregistrement                   | Comportement du fichier                                        |
| --------------------------------------------- | -------------------------------------------------------------- |
| Soft-delete de l'enregistrement               | Fichier préservé dans le stockage.                             |
| Restauration de l'enregistrement              | Accès au fichier restauré.                                     |
| Hard-delete (purge)                           | Fichier retiré du stockage.                                    |
| Remplacement de la pièce jointe               | Ancien fichier retiré du stockage.                             |
| Effacement de la pièce jointe (mettre `null`) | Fichier retiré du stockage.                                    |
| Référence partagée                            | Fichier préservé tant qu'un autre enregistrement le référence. |

## Téléversements volumineux et quota

Les téléversements diffusent en flux plutôt que de tamponner en bloc, donc les gros fichiers ne font pas grimper la mémoire. Les limites sont contrôlées par l'opérateur via des variables d'environnement.

| Variable                 | Par défaut           | Objectif                                                                                               |
| ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------ |
| `STORAGE_MAX_FILE_SIZE`  | `104857600` (100 Mo) | Taille maximale d'un fichier unique en octets. Le `maxFileSize` d'un bucket surcharge ceci par bucket. |
| `STORAGE_MAX_TOTAL_SIZE` | Illimité             | Stockage total maximal par application en octets (sécurité multi-locataire).                           |

```bash
STORAGE_MAX_FILE_SIZE=52428800
STORAGE_MAX_TOTAL_SIZE=10737418240
```

Le point de terminaison de quota admin rapporte l'utilisation :

```bash
curl https://app.example.com/api/admin/buckets/quota \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

```json
{ "usedBytes": 524288000, "maxBytes": 10737418240 }
```

La suppression de fichiers réduit l'utilisation suivie. Lorsqu'aucun `STORAGE_MAX_TOTAL_SIZE` n'est configuré, les téléversements sont illimités.

## Pages associées

- [Présentation des buckets](/fr/buckets-overview) — déclarer les buckets, les backends et les permissions.
- [URL signées](/fr/signed-urls) — téléchargement limité dans le temps et téléversements directs depuis le navigateur.
- [Transformations d'image](/fr/image-transforms) — redimensionnement et reformatage au téléchargement.
- [Champs de pièce jointe](/fr/attachment-fields) — fichiers attachés aux enregistrements de table.
- [Téléversements de fichiers de formulaire](/fr/form-file-uploads) — accepter des téléversements via des formulaires.
- [Variables d'environnement](/fr/env-vars) — configuration de la taille et du quota.

# URL signées

Les URL signées accordent un accès temporaire et restreint aux fichiers privés sans exposer les identifiants de stockage ni rendre le fichier publiquement permanent. Une URL signée intègre un jeton HMAC-SHA256 (signé avec `AUTH_SECRET`) qui encode le chemin, l'opération et l'expiration. Falsifier n'importe quelle partie invalide le jeton.

Les URL signées fonctionnent sur les trois backends de stockage. Pour les backends S3, Sovrium délègue à la présignature S3 native ; pour les [backends local et bytea](/fr/buckets-overview#storage-backends), il génère et valide les signatures en interne — aucun SDK AWS requis à la couche application.

## Accès public vs privé

Par défaut, les fichiers sont privés et requièrent soit une authentification soit une URL signée. Les opérateurs peuvent découper des préfixes de chemin toujours publics.

| Variable                 | Par défaut | Objectif                                                                                 |
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------- |
| `STORAGE_DEFAULT_ACCESS` | `private`  | Niveau d'accès par défaut pour les nouveaux fichiers (`private` ou `public`).            |
| `STORAGE_PUBLIC_PATHS`   | (aucun)    | Préfixes de chemin séparés par des virgules servis sans authentification ni URL signées. |

```bash
STORAGE_DEFAULT_ACCESS=private
STORAGE_PUBLIC_PATHS=assets/,avatars/,logos/
```

| Comportement                                              | Résultat                                        |
| --------------------------------------------------------- | ----------------------------------------------- |
| Fichier sous un préfixe `STORAGE_PUBLIC_PATHS`            | Servi sans authentification ni URL signée.      |
| Fichier hors des chemins publics, pas d'URL signée valide | `403 Forbidden`.                                |
| `STORAGE_DEFAULT_ACCESS=public`                           | Tous les fichiers accessibles sans URL signées. |

La configuration des chemins publics est validée au démarrage — pas de caractères génériques en fin, pas de préfixes qui se chevauchent. Un bucket marqué `public: true` dans le schéma est l'équivalent par bucket (voir [Présentation des buckets](/fr/buckets-overview#public-vs-private)).

## URL signées de téléchargement

Demandez une URL de téléchargement limitée dans le temps pour un fichier privé.

```http
POST /api/buckets/{bucket}/sign
Content-Type: application/json
Authorization: Bearer <token>

{
  "path": "documents/contract.pdf",
  "expiresIn": 3600,
  "operation": "download"
}
```

```json
{
  "signedUrl": "https://app.example.com/api/buckets/documents/files/documents/contract.pdf?token=eyJhbGciOiJIUzI1NiJ9...",
  "path": "documents/contract.pdf",
  "expiresAt": "2026-04-05T11:00:00Z"
}
```

| Paramètre   | Type    | Requis | Par défaut | Description                                            |
| ----------- | ------- | ------ | ---------- | ------------------------------------------------------ |
| `path`      | string  | Oui    | —          | Chemin du fichier relatif à la racine de stockage.     |
| `expiresIn` | integer | Non    | `3600`     | Expiration en secondes. Plage : 60 à 604800 (7 jours). |
| `operation` | string  | Non    | `download` | `download` ou `upload`.                                |

| Comportement                   | Résultat                                            |
| ------------------------------ | --------------------------------------------------- |
| Chemin valide                  | URL signée plus horodatage `expiresAt`.             |
| Accès à l'URL avant expiration | Fichier servi sans authentification supplémentaire. |
| Accès après expiration         | `403 Forbidden`.                                    |
| `expiresIn` < 60 ou > 604800   | `400 Bad Request`.                                  |
| Chemin inexistant              | `404 Not Found`.                                    |
| Jeton falsifié                 | `403 Forbidden`.                                    |

## URL signées de téléversement

Émettez un jeton d'écriture pour qu'un navigateur puisse téléverser directement vers le stockage sans faire transiter les octets par le serveur d'application.

```http
POST /api/buckets/{bucket}/sign
Content-Type: application/json
Authorization: Bearer <token>

{
  "path": "uploads/user-123/profile-photo.jpg",
  "expiresIn": 600,
  "operation": "upload",
  "contentType": "image/jpeg",
  "maxSize": 5242880
}
```

```json
{
  "signedUrl": "https://app.example.com/api/buckets/uploads/files/uploads/user-123/profile-photo.jpg?token=eyJhbGciOiJIUzI1NiJ9...",
  "path": "uploads/user-123/profile-photo.jpg",
  "expiresAt": "2026-04-05T10:10:00Z",
  "method": "PUT",
  "headers": { "Content-Type": "image/jpeg" }
}
```

| Paramètre     | Type    | Requis | Par défaut         | Description                                         |
| ------------- | ------- | ------ | ------------------ | --------------------------------------------------- |
| `contentType` | string  | Non    | —                  | Type MIME requis, appliqué côté serveur sur le PUT. |
| `maxSize`     | integer | Non    | `10485760` (10 Mo) | Taille maximale de téléversement en octets.         |

| Comportement                                          | Résultat                                        |
| ----------------------------------------------------- | ----------------------------------------------- |
| Téléversement via l'URL PUT                           | Fichier stocké au chemin spécifié.              |
| Téléversement après expiration                        | `403 Forbidden`.                                |
| Mauvais type MIME (quand `contentType` est défini)    | `400 Bad Request`.                              |
| Dépasse `maxSize`                                     | `413 Payload Too Large`.                        |
| Réutiliser un jeton de téléversement pour télécharger | Rejeté — l'opération est encodée dans le jeton. |

## Signature par lot

Générez des URL signées pour jusqu'à 100 fichiers en une seule requête — utile pour afficher une page pleine d'images privées.

```http
POST /api/buckets/{bucket}/sign/batch
Content-Type: application/json
Authorization: Bearer <token>

{
  "files": [
    { "path": "photos/photo-1.jpg", "expiresIn": 3600 },
    { "path": "photos/photo-2.jpg", "expiresIn": 3600 },
    { "path": "documents/report.pdf", "expiresIn": 7200 }
  ]
}
```

Chaque fichier peut porter son propre `expiresIn`. Les fichiers inexistants sont renvoyés avec une entrée `error: "not_found"` (succès partiel plutôt que d'échouer tout le lot). Demander plus de 100 fichiers renvoie `400 Bad Request`.

## Récapitulatif des points de terminaison

| Méthode | Point de terminaison                           | Auth                                      |
| ------- | ---------------------------------------------- | ----------------------------------------- |
| `POST`  | `/api/buckets/{bucket}/sign`                   | Requise (session).                        |
| `POST`  | `/api/buckets/{bucket}/sign/batch`             | Requise (session).                        |
| `GET`   | `/api/buckets/{bucket}/files/{path}?token=...` | Aucune — le jeton est l'authentification. |
| `PUT`   | `/api/buckets/{bucket}/files/{path}?token=...` | Aucune — le jeton est l'authentification. |

Appeler l'un ou l'autre des points de terminaison `sign` sans session valide renvoie `401`.

## Contrôle d'accès

Qui peut signer est régi par deux couches indépendantes, toutes deux utilisant le format partagé `PermissionValueSchema` (`all` | `authenticated` | liste de rôles).

### Permissions par bucket

Définissez `sign` et `signUpload` sur le bucket.

```yaml
buckets:
  - name: documents
    permissions:
      sign: authenticated
      signUpload: [admin, editor]
      download: authenticated
      delete: [admin]

  - name: public-assets
    public: true
    permissions:
      sign: all
      signUpload: [admin]
      download: all
```

| Comportement                                     | Résultat                                        |
| ------------------------------------------------ | ----------------------------------------------- |
| L'appelant correspond à `permissions.sign`       | Peut générer des URL signées de téléchargement. |
| L'appelant correspond à `permissions.signUpload` | Peut générer des URL signées de téléversement.  |
| L'appelant ne correspond pas                     | `403 Forbidden`.                                |
| Le bucket n'a pas de bloc `permissions`          | Seul le rôle `admin` peut signer (par défaut).  |

### Permissions de stockage par rôle

Les rôles peuvent accorder ou révoquer indépendamment la signature via `storage.sign` / `storage.signUpload`.

```yaml
auth:
  roles:
    - name: member
      permissions:
        storage:
          sign: true
          signUpload: false
    - name: viewer
      permissions:
        storage:
          sign: false
          signUpload: false
```

Admin dispose des pleins droits de signature par défaut. Lorsqu'aucune permission de stockage n'est définie nulle part, la signature est par défaut réservée à admin.

## Intégration au champ de pièce jointe

Lorsqu'un [champ de pièce jointe](/fr/attachment-fields) de table pointe vers un fichier privé, la réponse de l'API d'enregistrement intègre automatiquement une URL de téléchargement signée (expiration par défaut d'1 heure) :

```json
{
  "id": 1,
  "name": "Q1 Report",
  "attachment": {
    "path": "documents/q1-report.pdf",
    "filename": "q1-report.pdf",
    "size": 245760,
    "mimeType": "application/pdf",
    "signedUrl": "https://app.example.com/api/buckets/documents/files/documents/q1-report.pdf?token=...",
    "signedUrlExpiresAt": "2026-04-05T11:00:00Z"
  }
}
```

Les fichiers publics incluent une URL directe sans jeton. Les pièces jointes d'image peuvent porter des [paramètres de transformation](/fr/image-transforms) à l'intérieur de l'URL signée.

## Pages associées

- [Présentation des buckets](/fr/buckets-overview) — buckets, backends et le commutateur `public`.
- [Opérations sur les fichiers](/fr/file-operations) — téléversement, téléchargement et suppression directs.
- [Transformations d'image](/fr/image-transforms) — combiner les transformations avec les URL signées.
- [Champs de pièce jointe](/fr/attachment-fields) — auto-signature dans les réponses d'enregistrement.
- [Variables d'environnement](/fr/env-vars) — configuration des chemins publics et du niveau d'accès.

# Transformations d'image

Sovrium transforme les images stockées à la volée via des paramètres de requête d'URL. La largeur, la hauteur, le format, la qualité et le recadrage sont appliqués au moment de la requête à l'aide de la bibliothèque [Sharp](https://sharp.pixelplumbing.com/) — aucun service d'image externe. Les sorties transformées sont mises en cache, et le fichier original n'est jamais modifié.

Les transformations fonctionnent sur les fichiers de n'importe quel [backend de stockage](/fr/buckets-overview#storage-backends) (S3, local, bytea) et s'appliquent au point de terminaison de téléchargement standard :

```http
GET /api/buckets/{bucket}/files/photos/team-photo.jpg?width=400&height=300&fit=cover
```

## Redimensionnement

| Paramètre | Type    | Plage           | Par défaut | Description                     |
| --------- | ------- | --------------- | ---------- | ------------------------------- |
| `width`   | integer | 1–2500          | original   | Largeur cible en pixels.        |
| `height`  | integer | 1–2500          | original   | Hauteur cible en pixels.        |
| `fit`     | string  | voir ci-dessous | `contain`  | Stratégie de redimensionnement. |

Ne fournir qu'une seule dimension calcule automatiquement l'autre, en préservant le rapport d'aspect. Les valeurs hors de 1–2500 renvoient `400 Bad Request`.

### Modes de fit

| Mode      | Comportement                                                                         |
| --------- | ------------------------------------------------------------------------------------ |
| `contain` | Tient dans les limites, en préservant le rapport d'aspect (peut ajouter des bandes). |
| `cover`   | Remplit les limites, en préservant le rapport d'aspect (peut recadrer les bords).    |
| `fill`    | Étire aux dimensions exactes, en ignorant le rapport d'aspect.                       |
| `inside`  | Comme `contain`, mais n'agrandit jamais.                                             |
| `outside` | Comme `cover`, mais ne réduit jamais.                                                |

## Conversion de format

Convertissez vers des formats modernes pour réduire la taille des fichiers et améliorer les temps de chargement.

```http
# Explicit format
GET /api/buckets/{bucket}/files/photos/banner.png?format=webp

# Preserve source format, skip negotiation
GET /api/buckets/{bucket}/files/photos/banner.png?format=origin

# Automatic: negotiated from the Accept header
GET /api/buckets/{bucket}/files/photos/banner.png
Accept: image/avif,image/webp,image/*
```

| Format   | Extension | Cas d'usage                                             |
| -------- | --------- | ------------------------------------------------------- |
| `avif`   | `.avif`   | Meilleure compression, navigateurs les plus récents.    |
| `webp`   | `.webp`   | Forte compression, large prise en charge moderne.       |
| `jpeg`   | `.jpg`    | Compatibilité universelle.                              |
| `png`    | `.png`    | Transparence, sans perte.                               |
| `origin` | (source)  | Préserve le format source, opte hors de la négociation. |

Sans paramètre `format`, le serveur négocie le meilleur format pris en charge à partir de l'en-tête `Accept`. Le `Content-Type` de la réponse reflète toujours la sortie réelle. Une valeur `format` non prise en charge renvoie `400 Bad Request`.

:::callout
**AVIF est la valeur par défaut éco.** La posture frugale-par-défaut de Sovrium définit `ECO_IMAGE_FORMAT=avif` afin que le transcodage côté serveur favorise la charge utile la plus petite. Les opérateurs optent hors via [Écoconception](/fr/ecoconception) ; `format=origin` opte hors par requête.
:::

## Qualité

```http
GET /api/buckets/{bucket}/files/photos/hero.jpg?quality=95
GET /api/buckets/{bucket}/files/photos/hero.jpg?width=100&quality=30
```

| Comportement                      | Résultat                                                          |
| --------------------------------- | ----------------------------------------------------------------- |
| `quality` accepte 1–100           | Les valeurs plus élevées produisent des fichiers plus volumineux. |
| Par défaut                        | `80` lorsqu'omis.                                                 |
| Hors plage                        | `400 Bad Request`.                                                |
| S'applique aux formats avec perte | JPEG, WebP, AVIF.                                                 |
| Ignoré pour                       | La sortie PNG sans perte.                                         |

## Recadrage

Les stratégies de recadrage ne s'appliquent que lorsque `fit=cover` ; sinon le paramètre `crop` est ignoré.

```http
GET /api/buckets/{bucket}/files/photos/team.jpg?width=300&height=300&fit=cover&crop=entropy
GET /api/buckets/{bucket}/files/photos/team.jpg?width=300&height=300&fit=cover&crop=50,30
```

| Stratégie | Syntaxe                    | Description                                                      |
| --------- | -------------------------- | ---------------------------------------------------------------- |
| center    | `crop=center` (par défaut) | Recadre depuis le centre de l'image.                             |
| entropy   | `crop=entropy`             | Recadrage intelligent par entropie de Shannon.                   |
| attention | `crop=attention`           | Recadrage intelligent par la stratégie d'attention de Sharp.     |
| focal     | `crop=x,y`                 | Recadre autour d'un point focal (`x`,`y` en pourcentages 0–100). |

Les valeurs de point focal hors de 0–100 renvoient `400 Bad Request`.

## Presets

Définissez des presets de transformation nommés une fois via une variable d'environnement, puis demandez-les par leur nom.

| Variable                    | Par défaut | Objectif                       |
| --------------------------- | ---------- | ------------------------------ |
| `STORAGE_TRANSFORM_PRESETS` | (aucun)    | Chaîne JSON de presets nommés. |

```bash
STORAGE_TRANSFORM_PRESETS='{"thumbnail":{"width":150,"height":150,"fit":"cover"},"preview":{"width":600,"quality":80},"avatar":{"width":64,"height":64,"fit":"cover","crop":"attention"}}'
```

```http
# Apply a preset
GET /api/buckets/{bucket}/files/photos/profile.jpg?preset=avatar

# Preset with overrides — explicit params win
GET /api/buckets/{bucket}/files/photos/profile.jpg?preset=thumbnail&quality=95
```

| Comportement                                  | Résultat                                                 |
| --------------------------------------------- | -------------------------------------------------------- |
| Preset connu                                  | Applique sa largeur, hauteur, fit, qualité et recadrage. |
| Params d'URL explicites aux côtés d'un preset | Surchargent les valeurs du preset.                       |
| Nom de preset inconnu                         | `400 Bad Request`.                                       |
| `preset` utilisé quand aucun n'est configuré  | `400 Bad Request`.                                       |

Les noms de preset doivent être alphanumériques avec des traits d'union (validés au démarrage).

## Mise en cache

Les images transformées sont mises en cache afin que les requêtes répétées soient servies instantanément.

| Mécanisme          | Détail                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------- |
| En-tête de réponse | `Cache-Control: public, max-age=31536000, immutable` (1 an, adressé par contenu).             |
| `ETag`             | Hachage du fichier source plus les paramètres de transformation.                              |
| `If-None-Match`    | Un ETag correspondant renvoie `304 Not Modified`.                                             |
| Cache disque       | Stocké dans `STORAGE_TRANSFORM_CACHE_DIR`, indexé par `sha256(file_path + transform_params)`. |
| Éviction           | LRU, borné par `STORAGE_TRANSFORM_CACHE_MAX_SIZE`.                                            |

| Variable                           | Par défaut      | Objectif                                      |
| ---------------------------------- | --------------- | --------------------------------------------- |
| `STORAGE_TRANSFORM_CACHE_DIR`      | Dossier temp OS | Répertoire pour les transformations en cache. |
| `STORAGE_TRANSFORM_CACHE_MAX_SIZE` | `500`           | Taille maximale du cache en Mo.               |

## Préservation de l'original

| Garantie                         | Comportement                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Les octets source sont immuables | Le fichier original est identique octet pour octet après n'importe quel nombre de requêtes de transformation. |
| Requête sans param               | Renvoie l'original non modifié.                                                                               |
| Suppression du cache             | N'affecte jamais la disponibilité du fichier original.                                                        |
| Fichiers non image (PDF, CSV)    | Les params de transformation renvoient `400 Bad Request`.                                                     |
| Types pris en charge             | JPEG, PNG, WebP, AVIF, GIF, TIFF, SVG (SVG est transmis tel quel).                                            |

## Pages associées

- [Présentation des buckets](/fr/buckets-overview) — backends et configuration des buckets.
- [Opérations sur les fichiers](/fr/file-operations) — téléversement, téléchargement, suppression.
- [URL signées](/fr/signed-urls) — les transformations peuvent être intégrées dans des URL signées.
- [Champs de pièce jointe](/fr/attachment-fields) — transformations de vignettes sur les pièces jointes d'enregistrement.
- [Écoconception](/fr/ecoconception) — `ECO_IMAGE_FORMAT` et la posture frugale-par-défaut.
- [Variables d'environnement](/fr/env-vars) — configuration des presets et du cache.

# Présentation de la recherche

La recherche Sovrium **n'est pas un domaine de fonctionnalité autonome**. Elle étend les schémas que vous utilisez déjà : les tables déclarent _ce qui_ est cherchable (pondérations de champs, indexation), et les composants de page déclarent _comment_ la recherche se comporte (moteur, anti-rebond, surlignage, affichage des résultats). Il n'y a pas de configuration `app.search` de premier niveau — la configuration vit là où elle est utilisée.

Le backend est entièrement bâti sur PostgreSQL : la recherche plein texte (`tsvector`/`tsquery`) plus l'extension `pg_trgm` pour une correspondance floue, tolérante aux fautes de frappe. Pas d'Elasticsearch, pas d'Algolia, pas de service externe — la recherche reste à l'intérieur de votre propre base de données, conformément au principe de souveraineté numérique de Sovrium.

:::callout
Deux couches de recherche distinctes existent. La **recherche d'enregistrements** (cette page) interroge les données de table via le mode de source de données `search` et les quatre moteurs ci-dessous. La **recherche de pages publiques** indexe le _contenu_ des pages statiques via le composant `pageSearch` — voir [search-components](/fr/search-components#pagesearch). Ce sont des fonctionnalités différentes à des couches différentes.
:::

## Moteurs de recherche

Une source de données en `mode: 'search'` sélectionne son backend avec `searchEngine`. La même table peut utiliser des moteurs différents sur des pages différentes.

| Moteur    | Où il s'exécute          | Idéal pour                                                                                        |
| --------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
| `client`  | JavaScript du navigateur | Petits jeux de données déjà chargés dans la page ; instantané, sans aller-retour. **Par défaut.** |
| `fts`     | FTS PostgreSQL           | Pertinence classée côté serveur sur du texte indexé ; grands jeux de données.                     |
| `trigram` | `pg_trgm` PostgreSQL     | Correspondance floue et tolérance aux fautes de frappe ; requêtes partielles/mal orthographiées.  |
| `hybrid`  | FTS PostgreSQL + trigram | FTS pour la pertinence avec un repli flou trigram ; le meilleur des deux.                         |

### `client` — filtrage dans le navigateur

Filtrage JavaScript dans le navigateur. Les enregistrements sont déjà récupérés, et la requête les restreint en mémoire. Aucun aller-retour serveur, mais l'ensemble du jeu de résultats doit tenir dans la page. À utiliser pour les petites listes de référence et les sélecteurs.

```yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: client
    debounceMs: 300
```

### `fts` — recherche plein texte PostgreSQL

Recherche classée côté serveur utilisant `tsvector`/`tsquery`. Les résultats reviennent triés par pertinence, pondérés par le [`searchWeight`](/fr/full-text-search#field-relevance-weights) de chaque champ. Requiert que les champs cherchés soient `indexed: true`. À utiliser pour les grands jeux de données riches en texte où le classement importe.

```yaml
- type: data-table
  dataSource:
    table: articles
    mode: search
    searchFields: [title, body]
    searchEngine: fts
    debounceMs: 300
    limit: 20
```

### `trigram` — correspondance floue

Utilise l'extension `pg_trgm` pour faire correspondre les trigrammes de caractères, tolérant les fautes de frappe et les mots partiels. Idéal quand les utilisateurs font des fautes ou tapent des fragments (par ex. `prodct` correspond toujours à `product`). Voir [full-text-search](/fr/full-text-search#trigram-fuzzy-matching) pour les détails d'indexation.

```yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name]
    searchEngine: trigram
```

### `hybrid` — pertinence plus tolérance

Combine le FTS pour le classement par pertinence avec le trigram comme repli flou, de sorte que les correspondances exactes et classées remontent en premier tandis que les requêtes mal orthographiées renvoient quand même des résultats. Le moteur le plus indulgent pour la recherche destinée à l'utilisateur final.

```yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: hybrid
    debounceMs: 300
    limit: 50
```

:::callout
`searchEngine` vaut `client` par défaut. Les moteurs `fts`, `trigram` et `hybrid` ne s'exécutent que dans PostgreSQL — ils requièrent un corpus indexé. Sur SQLite, le classement côté serveur se rabat sur une correspondance plus simple ; concevez la recherche adossée à un index contre Postgres. Voir [full-text-search](/fr/full-text-search#postgresql-vs-sqlite).
:::

## Le mode de source de données `search`

La recherche est l'un des trois modes de source de données (`list`, `single`, `search`). Définir `mode: 'search'` transforme un composant lié à des données en une expérience de recherche interactive et anti-rebondie.

| Propriété      | Description                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| `table`        | Table à interroger (validée par rapport à `app.tables`).                                                   |
| `searchFields` | Tableau (≥ 1) de noms de champs sur lesquels chercher. Requis pour le mode recherche.                      |
| `searchEngine` | Backend : `client` (par défaut), `fts`, `trigram` ou `hybrid`.                                             |
| `debounceMs`   | Délai d'anti-rebond pour la saisie de recherche en millisecondes (entier ≥ 0), par ex. `300`, `500`.       |
| `limit`        | Nombre maximal de résultats à renvoyer (entier ≥ 1), par ex. `10`, `20`, `50`.                             |
| `bindTo`       | ID d'un composant `searchInput` dont la requête pilote cette source de données (liaison inter-composants). |
| `filter`       | Conditions de filtre (logique ET) appliquées aux côtés de la requête de recherche.                         |
| `sort`         | Règles de tri appliquées aux résultats.                                                                    |
| `refreshMode`  | Comment les résultats se rafraîchissent après le chargement : `none` (par défaut), `poll` ou `realtime`.   |

```yaml
# Interactive search with debounce and a result limit
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: hybrid
    debounceMs: 300
    limit: 20
```

Pour le filtrage et le tri statiques de résultats hors recherche, utilisez le mode `list` avec `filter`/`sort` à la place — voir [records-filtering-sorting](/fr/records-filtering-sorting).

## Choisir une approche

| Besoin                                                             | Utiliser                                                                  |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| Restreindre une petite liste déjà sur la page                      | `searchEngine: client`                                                    |
| Classer de grands jeux de données textuelles par pertinence        | `searchEngine: fts` + `indexed: true` + `searchWeight`                    |
| Tolérer les fautes de frappe et les mots partiels                  | `searchEngine: trigram`                                                   |
| À la fois classement par pertinence et tolérance aux fautes        | `searchEngine: hybrid`                                                    |
| Chercher le contenu de pages statiques à l'échelle du site         | `pageSearch` component — voir [search-components](/fr/search-components)  |
| Définir quels champs sont cherchables et comment ils sont pondérés | Config au niveau du champ — voir [full-text-search](/fr/full-text-search) |

## Associé

- [Recherche plein texte](/fr/full-text-search) — `fullTextSearch`, `indexed` et `searchWeight` au niveau du champ.
- [Composants de recherche](/fr/search-components) — `searchInput`, `pageSearch`, `list`, `command` et la recherche de barre d'outils.
- [Champs texte](/fr/text-fields) — l'indicateur `fullTextSearch` du champ `rich-text`.
- [Présentation des tables](/fr/tables-overview) — les propriétés de base des champs incluant `indexed` et `searchWeight`.

# Recherche plein texte

Les tables déclarent _ce qui_ est cherchable. Trois propriétés au niveau du champ contrôlent comment un champ participe à la recherche : `indexed` le rend interrogeable, `searchWeight` classe sa pertinence, et `fullTextSearch` (sur `rich-text`) active l'indexation FTS pour le contenu formaté. Les composants choisissent ensuite le moteur qui les consomme — voir [search-overview](/fr/search-overview#search-engines).

## Propriétés des champs

| Propriété        | S'applique à             | Description                                                                                                                            |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `indexed`        | Tous les types de champs | Booléen. Crée un index de base de données sur le champ. Requis pour les moteurs `fts`, `trigram` et `hybrid`.                          |
| `searchWeight`   | Tous les types de champs | `A`–`D`. Pondération de pertinence FTS PostgreSQL. Effectif uniquement lorsque `indexed: true` et que le moteur est `fts` ou `hybrid`. |
| `fullTextSearch` | `rich-text`              | Booléen. Active l'indexation de recherche plein texte pour le contenu formaté du champ.                                                |

Ces propriétés étendent les [propriétés de base des champs](/fr/tables-overview#base-field-properties) partagées par chaque type de champ.

## Pondérations de pertinence des champs

`searchWeight` correspond directement aux pondérations FTS de PostgreSQL, ordonnant la force avec laquelle une correspondance dans chaque champ influence le rang de pertinence. Une correspondance de titre surclasse une correspondance de corps.

| Pondération | Pertinence     | Champs typiques                                    |
| ----------- | -------------- | -------------------------------------------------- |
| `A`         | La plus élevée | Titre, nom, accroche.                              |
| `B`         | Élevée         | Description, résumé, extrait.                      |
| `C`         | Moyenne        | Tags, catégories, libellés.                        |
| `D`         | La plus basse  | Notes internes, métadonnées, notes de bas de page. |

```yaml
tables:
  - name: articles
    fields:
      - { id: 1, name: title, type: single-line-text, indexed: true, searchWeight: A }
      - { id: 2, name: summary, type: long-text, indexed: true, searchWeight: B }
      - { id: 3, name: tags, type: single-line-text, indexed: true, searchWeight: C }
      - { id: 4, name: body, type: rich-text, indexed: true, fullTextSearch: true, searchWeight: B }
```

:::callout
`searchWeight` n'est significatif que lorsque le champ est `indexed: true` **et** qu'une source de données l'interroge avec `searchEngine: 'fts'` ou `'hybrid'`. Avec les moteurs `client` ou `trigram`, la pondération est ignorée.
:::

## `fullTextSearch` sur le texte enrichi

Le champ `rich-text` stocke du HTML formaté. Définir `fullTextSearch: true` active l'indexation de recherche plein texte de son contenu textuel afin que le champ puisse participer aux requêtes `fts`/`hybrid` aux côtés des champs de texte brut.

```yaml
- id: 5
  name: article_content
  type: rich-text
  required: true
  maxLength: 10000
  fullTextSearch: true
  searchWeight: B
  toolbar: [bold, italic, link, heading, list]
```

Les champs `long-text` et `single-line-text` simples n'ont pas besoin de `fullTextSearch` — définissez `indexed: true` et un `searchWeight`, et ils sont prêts pour le FTS. L'indicateur `fullTextSearch` existe spécifiquement pour `rich-text` car sa valeur stockée est du balisage HTML plutôt que du texte brut. Voir [text-fields](/fr/text-fields#rich-text) pour l'ensemble complet des propriétés `rich-text`.

## PostgreSQL vs SQLite

| Aspect               | PostgreSQL                                                                 | SQLite                                                                      |
| -------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Moteur FTS           | `tsvector`/`tsquery` natif avec classement pondéré.                        | Correspondance plus simple ; le classement pondéré est réduit.              |
| Correspondance floue | Extension `pg_trgm` (trigram, tolérant aux fautes).                        | Non disponible — le moteur trigram cible Postgres.                          |
| `searchWeight` A–D   | Pleinement honoré dans le classement par pertinence.                       | Au mieux ; l'ordonnancement des pondérations peut être approximatif.        |
| Recommandation       | À utiliser pour une recherche `fts`/`trigram`/`hybrid` adossée à un index. | Par défaut sans configuration ; concevez la recherche classée sur Postgres. |

:::callout
SQLite est la base de données par défaut sans configuration de Sovrium. Pour une recherche de production qui dépend de la pertinence classée (`searchWeight`) ou de la correspondance floue (`trigram`/`hybrid`), exécutez contre PostgreSQL où `tsvector` et `pg_trgm` sont disponibles.
:::

## Correspondance floue trigram

L'extension `pg_trgm` décompose le texte en séquences de trois caractères (trigrammes) et fait correspondre sur le chevauchement, tolérant les fautes de frappe et les mots partiels. Cela alimente les moteurs `trigram` et `hybrid`. Un champ utilisé pour la recherche floue devrait être `indexed: true` afin que PostgreSQL puisse construire un index trigram (GIN/GiST).

```yaml
tables:
  - name: products
    fields:
      - { id: 1, name: name, type: single-line-text, indexed: true, searchWeight: A }
```

```yaml
# Component side — fuzzy matching on the indexed field
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name]
    searchEngine: trigram
```

Une requête de `prodct` correspond toujours à `product` ; `lapto` correspond à `laptop`. Associez le trigram au FTS avec `searchEngine: 'hybrid'` pour conserver le classement par pertinence pour les termes exacts tout en conservant la tolérance aux fautes pour le reste.

## Associé

- [Présentation de la recherche](/fr/search-overview) — les quatre moteurs de recherche et le mode de source de données `search`.
- [Composants de recherche](/fr/search-components) — `searchInput`, `list`, `pageSearch` et la recherche de barre d'outils.
- [Champs texte](/fr/text-fields) — `rich-text`, `long-text` et l'indicateur `fullTextSearch`.
- [Présentation des tables](/fr/tables-overview) — `indexed`, `searchWeight` et autres propriétés de base des champs.

# Composants de recherche

Là où les tables déclarent _ce qui_ est cherchable et où les moteurs déclarent _comment_ une requête s'exécute (voir [search-overview](/fr/search-overview)), les composants sont l'_endroit_ où la recherche apparaît sur la page. Sovrium fournit cinq pièces complémentaires : un `searchInput` qui pilote une requête, une `list` qui affiche les résultats, un `pageSearch` qui indexe le contenu des pages statiques, une palette `command` pour la navigation au clavier, et la recherche de barre d'outils intégrée aux composants de données.

| Composant                   | Objectif                                                                                              |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `searchInput`               | Champ de recherche autonome qui pilote un autre composant via `dataSource.bindTo`.                    |
| `list`                      | Affichage de résultats orienté recherche avec modèles d'élément, surlignage et pagination.            |
| `pageSearch`                | Recherche statique à l'échelle du site sur le contenu des pages publiques (index au build/démarrage). |
| `command`                   | Palette de commandes (style ⌘K) pour des actions groupées et pilotées au clavier.                     |
| recherche de barre d'outils | Barre de recherche intégrée au composant sur `data-table`, kanban, calendrier, etc.                   |

## `searchInput`

Un champ de recherche autonome. Seul, il affiche une saisie accessible ; lié à une source de données, il devient le pilote de requête pour un composant frère. Associez-le à une `list` (ou `data-table`) dont la source de données définit `bindTo` sur l'`id` de la saisie.

| Propriété    | Description                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `id`         | Identifiant que les autres composants référencent via `dataSource.bindTo`. |
| `visibility` | Contrôles de visibilité standard (partagés entre composants).              |
| `i18n`       | Champs d'internationalisation standard (libellé/placeholder traduisibles). |

```yaml
components:
  # 1. The input drives the query
  - type: searchInput
    id: product-query

  # 2. The list consumes it via bindTo
  - type: list
    dataSource:
      table: products
      mode: search
      searchFields: [name, description]
      searchEngine: hybrid
      debounceMs: 300
      bindTo: product-query
    listDisplay:
      itemTemplate:
        title: '$record.name'
        subtitle: '$record.description'
      highlight: true
```

:::callout
`debounceMs` réside sur la **source de données** du composant consommateur, pas sur `searchInput` — la saisie émet les frappes et la source de données liée les anti-rebondit avant d'interroger. Voir [search-overview](/fr/search-overview#the-search-data-source-mode).
:::

## `list` — affichage de résultats

Le composant `list` est conçu comme un affichage orienté recherche : le compagnon naturel de `searchInput`. Il affiche chaque enregistrement via un modèle d'élément avec surlignage optionnel, séparateurs et pagination « charger plus ».

| Propriété               | Description                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `itemTemplate.title`    | Texte principal via une référence `$record.*` (par ex. `$record.name`).                                                        |
| `itemTemplate.subtitle` | Texte secondaire (par ex. `$record.description`).                                                                              |
| `itemTemplate.image`    | URL d'image (par ex. `$record.thumbnail`).                                                                                     |
| `itemTemplate.badge`    | Texte de badge (par ex. `$record.category`).                                                                                   |
| `itemTemplate.metadata` | Tableau de `{ field, format }` affiché dans le pied de l'élément (`currency`, `relative-date`, `badge`, `text`, `short-date`). |
| `emptyMessage`          | Message affiché lorsqu'aucun résultat ne correspond.                                                                           |
| `loadMore`              | `button` (bouton Charger plus) ou `infinite` (charger au défilement).                                                          |
| `highlight`             | Booléen. Surligne les termes de recherche correspondants dans le texte de l'élément (par défaut `false`).                      |
| `divider`               | Booléen. Affiche des séparateurs visuels entre les éléments (par défaut `false`).                                              |
| `maxItems`              | Nombre maximal d'éléments à afficher (entier ≥ 1).                                                                             |

```yaml
- type: list
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    bindTo: product-query
  listDisplay:
    itemTemplate:
      title: '$record.name'
      subtitle: '$record.description'
      image: '$record.thumbnail'
      badge: '$record.category'
      metadata:
        - field: price
          format: currency
    emptyMessage: No products found
    loadMore: infinite
    highlight: true
    divider: true
    maxItems: 50
```

## `pageSearch` — index de pages statiques

Un composant de recherche à l'échelle du site qui indexe les **pages publiques** (`access` absent ou `access: 'all'`) au moment de `sovrium build` et au démarrage de `sovrium start`. L'index est un fichier JSON plus un minuscule runtime client sous `<outputDir>/sovrium-search/`, servi par la route de répertoire public. C'est une couche différente de la recherche d'enregistrements — il recherche le _contenu_ des pages, pas les lignes de table.

| Propriété     | Description                                              |
| ------------- | -------------------------------------------------------- |
| `placeholder` | Texte indicatif affiché dans la saisie de recherche.     |
| `maxResults`  | Nombre maximal de résultats à afficher (entier positif). |
| `visibility`  | Contrôles de visibilité standard.                        |
| `i18n`        | Champs d'internationalisation standard.                  |

```yaml
pages:
  - id: home
    name: home
    path: /
    components:
      - type: pageSearch
        placeholder: Search the site...
        maxResults: 10
```

:::callout
`pageSearch` est **auto-activant** : dès qu'un composant `type: 'pageSearch'` apparaît n'importe où dans `app.pages[].components[]`, `sovrium build` et `sovrium start` émettent l'index de recherche statique. Pas de variable d'environnement, pas de configuration `app.search` de premier niveau. L'indexeur n'explore que les pages publiques — les pages avec `access: 'authenticated'`, des tableaux de rôles, ou un accès basé sur `require` sont exclues de l'index.
:::

## `command` — palette de commandes

Une palette de commandes de style ⌘K pour la navigation et les actions pilotées au clavier. Les commandes sont organisées en groupes, chacun faisant surgir des entrées cherchables que l'utilisateur filtre en tapant.

| Propriété       | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `commandGroups` | Tableau (≥ 1) de commandes groupées affichées dans la palette. |
| `visibility`    | Contrôles de visibilité standard.                              |
| `i18n`          | Champs d'internationalisation standard.                        |

```yaml
- type: command
  commandGroups:
    - heading: Navigation
      commands:
        - label: Go to Dashboard
          href: /dashboard
        - label: Go to Settings
          href: /settings
    - heading: Actions
      commands:
        - label: New Product
          href: /products/new
```

## Recherche de barre d'outils

Les composants de données exposent une barre de recherche intégrée au composant via leur barre d'outils. Sur un `data-table`, définissez `toolbar.search: true` pour afficher une saisie de recherche globale sur les lignes liées — un filtre rapide sans `searchInput` distinct.

| Indicateur de barre d'outils | Description                             |
| ---------------------------- | --------------------------------------- |
| `search`                     | Affiche la saisie de recherche globale. |
| `filters`                    | Affiche le constructeur de filtres.     |
| `sort`                       | Affiche le constructeur de tri.         |

```yaml
- type: data-table
  dataSource:
    table: orders
    mode: search
    searchFields: [customer, reference]
  toolbar:
    search: true
    filters: true
    sort: true
```

Les composants kanban et calendrier partagent une configuration `search` pour leur propre barre de recherche intégrée via le même modèle.

## Surlignage et anti-rebond

- **Surlignage** — définissez `highlight: true` sur `list` (`listDisplay.highlight`) pour entourer les termes correspondants dans le texte des résultats. Désactivé par défaut.
- **Anti-rebond** — définissez `debounceMs` sur la source de données (par ex. `300`) afin que la requête ne se déclenche qu'après une pause de saisie de l'utilisateur, évitant une requête par frappe.

Ces fonctionnalités fonctionnent ensemble : un `searchInput` émet des frappes, la source de données liée anti-rebondit et interroge, et la `list` surligne les correspondances dans les résultats affichés.

## Associé

- [Présentation de la recherche](/fr/search-overview) — les moteurs et le mode de source de données `search`.
- [Recherche plein texte](/fr/full-text-search) — `indexed`, `searchWeight` et `fullTextSearch` au niveau du champ.
- [Composants de données](/fr/data-components) — `data-table`, kanban, calendrier et leurs barres d'outils.
- [Composants de contenu](/fr/content-components) — texte, média et contenu de page structurel.
- [Enregistrements : filtrage et tri](/fr/records-filtering-sorting) — filtrage et ordonnancement de listes hors recherche.

# Vue d'ensemble de l'IA

Sovrium fournit une couche IA complète et auto-hébergeable. Chaque capacité est activable à la demande et régie par le RBAC et les permissions au niveau des champs déjà en place — l'IA ne contourne jamais le modèle de sécurité. La couche IA est **désactivée par défaut** : rien de lié à l'IA ne s'exécute tant que vous n'avez pas défini la variable d'environnement `AI_PROVIDER`.

La philosophie de conception reflète le reste de la plateforme : **les opérateurs contrôlent l'infrastructure via des variables d'environnement, les auteurs de schéma déclarent leur intention dans la configuration.** Quel fournisseur répond à un appel, où vivent les embeddings, et si le serveur MCP est monté sont des préoccupations d'opérateur (`AI_PROVIDER`, `MCP_ENABLED`, …). Quelles tables un agent peut manipuler et quelles entités sont éligibles à l'IA sont des préoccupations d'auteur de schéma (`agents[]`, `aiAccess`).

## L'écosystème IA

Huit briques se composent pour former l'expérience IA complète.

| Capacité              | Ce qu'elle fait                                                                                                              | Documentation                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **Fournisseurs**      | Choisir le backend LLM et d'embedding (Anthropic, OpenAI, Mistral, Gemini, Ollama local, compatible OpenAI).                 | [Fournisseurs IA](/fr/ai-providers)    |
| **Routage éco**       | Précédence de fournisseur frugale par défaut — privilégier un modèle local, basculer vers le cloud en secours.               | [Routage éco IA](/fr/ai-eco-routing)   |
| **Champs IA**         | Colonnes de table calculées qui résument, catégorisent, extraient, traduisent, etc. via un LLM.                              | [Champs IA](/fr/ai-fields)             |
| **Chat IA**           | Une interface conversationnelle sur vos données — interroger, modifier et déclencher des automatisations en langage naturel. | [Chat IA](/fr/ai-chat)                 |
| **Agents IA**         | Utilisateurs virtuels autonomes avec outils restreints, garde-fous d'approbation, planifications et limites opérationnelles. | [Agents IA](/fr/ai-agents)             |
| **Connaissances RAG** | Ancrer les réponses dans vos tables et documents via des embeddings vectoriels et la recherche sémantique.                   | [RAG IA](/fr/ai-rag)                   |
| **Mémoire d'agent**   | Historique de conversation, connaissances soutenues par RAG, et faits appris persistants par agent.                          | [Mémoire IA](/fr/ai-memory)            |
| **Intégration MCP**   | Exposer Sovrium comme serveur MCP, et laisser les agents consommer des outils MCP externes.                                  | [Intégration MCP](/fr/mcp-integration) |

:::callout
**Les champs IA sont documentés sous Tables.** Les sept types de champs calculés (`ai-summary`, `ai-categorize`, `ai-extract`, `ai-sentiment`, `ai-tag`, `ai-translate`, `ai-generate`) vivent sur les enregistrements de table et sont couverts dans [Champs IA](/fr/ai-fields). Cette section couvre les couches conversationnelle, agentique et d'interopérabilité.
:::

## Philosophie de configuration

L'IA se comporte comme les couches de base de données (`DATABASE_URL`), de stockage (`STORAGE_PROVIDER`) et d'authentification (`AUTH_SECRET`) : **l'infrastructure est une configuration par variable d'environnement, l'intention est du schéma.**

| Préoccupation                                        | Contrôlée par    | Où                                                |
| ---------------------------------------------------- | ---------------- | ------------------------------------------------- |
| Quel fournisseur/modèle/clé utiliser                 | Opérateur        | Variables `AI_PROVIDER`, `AI_MODEL`, `AI_API_KEY` |
| Précédence de routage des fournisseurs (éco)         | Opérateur        | Variable `ECO_AI_PROVIDER_PRECEDENCE`             |
| Si le serveur MCP est monté                          | Opérateur        | Variables `MCP_ENABLED`, `MCP_TRANSPORT`, …       |
| Quelles entités sont éligibles à l'IA                | Auteur de schéma | `aiAccess` sur tables / automatisations / actions |
| Identité, outils, approbation, planification d'agent | Auteur de schéma | `app.agents[]`                                    |
| Colonnes calculées IA                                | Auteur de schéma | Champs `type: ai-*` sur une table                 |

L'unique interrupteur principal est `AI_PROVIDER`. Lorsqu'il n'est pas défini (ou vidé), l'ensemble de la couche IA est silencieusement désactivé — les champs IA ignorent le calcul, le point d'accès du chat renvoie une réponse désactivée, les agents ne s'exécutent pas, et l'infrastructure RAG/embedding n'est pas provisionnée. Aucune erreur n'est levée au démarrage ; l'IA reste simplement dormante jusqu'à sa configuration.

```bash
# Activation minimale : un modèle Ollama local (pas de clé API, pas de cloud).
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
```

```bash
# Un fournisseur cloud.
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
AI_MODEL=claude-sonnet-4-5
```

## Comment les pièces s'assemblent

```
                         AI_PROVIDER (interrupteur principal)
                                  │
        ┌─────────────────┬───────┴────────┬──────────────────┐
        ▼                 ▼                ▼                  ▼
   Champs IA          Chat IA          Agents IA          Serveur MCP
 (cols calculées)  (conversation)  (utilisateurs virtuels) (clients externes)
        │                 │                │                  │
        │                 └──── outils ────┤                  │
        │                                  │                  │
        ▼                                  ▼                  ▼
                          RBAC + permissions au niveau des champs (toujours appliquées)
                                  │
                                  ▼
                    Connaissances RAG + mémoire d'agent (pgvector / BLOB SQLite)
```

Chaque surface IA — champs, chat, agents, MCP — passe par la même couche d'autorisation. Un agent hérite des permissions de son rôle ; un utilisateur de chat ne peut voir que les enregistrements autorisés par sa session ; un client MCP est borné par le rôle de son jeton. Il n'existe aucun contournement IA privilégié.

## Prérequis

| Exigence                     | Pourquoi                                                                                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AI_PROVIDER` défini         | Interrupteur principal. Sans lui, toute la couche IA est dormante.                                                                                |
| `app.auth` (le plus souvent) | Les agents sont stockés comme utilisateurs auth ; le chat et le RBAC MCP nécessitent des rôles. Les champs IA fonctionnent sans authentification. |
| pgvector / SQLite            | Les embeddings RAG nécessitent PostgreSQL + pgvector **ou** SQLite (BLOB Float32 + cosinus côté application). Aucune base vectorielle externe.    |

## Pages connexes

- [Fournisseurs IA](/fr/ai-providers) — choisir et configurer le backend LLM.
- [Routage éco IA](/fr/ai-eco-routing) — précédence de fournisseur local d'abord.
- [Champs IA](/fr/ai-fields) — colonnes calculées propulsées par un LLM.
- [Chat IA](/fr/ai-chat) — interaction conversationnelle avec les données.
- [Agents IA](/fr/ai-agents) — utilisateurs virtuels autonomes.
- [RAG IA](/fr/ai-rag) — connaissances augmentées par récupération.
- [Mémoire IA](/fr/ai-memory) — conversation, connaissances et faits d'agent.
- [Intégration MCP](/fr/mcp-integration) — Sovrium comme serveur et client MCP.
- [Variables d'environnement](/fr/env-vars) — référence complète des variables d'environnement.

# Fournisseurs IA

Le fournisseur IA est le backend LLM (et d'embedding) qui propulse chaque capacité IA. Vous le sélectionnez avec des variables d'environnement — jamais dans le schéma de l'application. Définir `AI_PROVIDER` est l'interrupteur principal qui active toute la couche IA ; le laisser non défini maintient l'IA dormante.

```bash
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
AI_MODEL=claude-sonnet-4-5
```

## Fournisseurs pris en charge

| Fournisseur           | Valeur `AI_PROVIDER`      | Clé API requise | URL de base requise | Notes                                                                         |
| --------------------- | ------------------------- | --------------- | ------------------- | ----------------------------------------------------------------------------- |
| **Anthropic**         | `anthropic`               | Oui             | Non                 | Modèles Claude. Modèle par défaut : `claude-sonnet-4-5`.                      |
| **OpenAI**            | `openai`                  | Oui             | Non                 | Modèles GPT / série o. Modèle par défaut : `gpt-4o`.                          |
| **Mistral**           | `mistral`                 | Oui             | Non                 | Mistral / Codestral. Modèle par défaut : `mistral-large-latest`.              |
| **Google Gemini**     | `google` (alias `gemini`) | Oui             | Non                 | Modèles Gemini. Modèle par défaut : `gemini-2.0-flash`.                       |
| **Ollama**            | `ollama`                  | Non             | Oui                 | Local, auto-hébergé. Aucune clé nécessaire. Modèle par défaut : `llama3.1`.   |
| **Compatible OpenAI** | `openai-compatible`       | Oui             | Oui                 | Tout point d'accès parlant l'API OpenAI. Définissez `AI_MODEL` explicitement. |

:::callout
**`gemini` est un alias accepté** pour la valeur canonique `google`. Les deux résolvent vers Google Gemini ; `google` est préféré dans les nouvelles configurations.
:::

## Variables d'environnement principales

| Variable                  | Description                                                                                                                         | Exemple                  |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `AI_PROVIDER`             | Identifiant du fournisseur. Interrupteur principal — non défini désactive toute l'IA.                                               | `anthropic`              |
| `AI_API_KEY`              | Clé API pour les fournisseurs cloud. Non utilisée par Ollama.                                                                       | `sk-ant-...`             |
| `AI_BASE_URL`             | URL du point d'accès. Requise pour Ollama et compatible OpenAI ; les fournisseurs cloud utilisent des valeurs par défaut intégrées. | `http://localhost:11434` |
| `AI_MODEL`                | Modèle LLM par défaut. Bascule vers le modèle par défaut recommandé du fournisseur lorsque non défini.                              | `claude-sonnet-4-5`      |
| `AI_TEMPERATURE`          | Température d'échantillonnage par défaut, `0`–`1` inclus.                                                                           | `0.7`                    |
| `AI_MAX_TOKENS`           | Nombre maximal de jetons de sortie par défaut (entier positif).                                                                     | `4096`                   |
| `AI_EMBEDDING_MODEL`      | Modèle d'embedding pour le RAG. Bascule vers le modèle d'embedding du fournisseur par défaut.                                       | `text-embedding-3-small` |
| `AI_EMBEDDING_DIMENSIONS` | Dimensions du vecteur (doit correspondre à la sortie du modèle d'embedding).                                                        | `1536`                   |

Une valeur vide ou composée uniquement d'espaces est traitée de manière identique à une valeur non définie — les opérateurs qui vident `AI_PROVIDER` ont l'intention de le désactiver, et non de fournir une valeur invalide. Le serveur démarre proprement avec l'IA désactivée plutôt que de lever une erreur d'analyse.

## Alias de clés et d'URL spécifiques aux fournisseurs

En plus des génériques `AI_API_KEY` / `AI_BASE_URL`, chaque fournisseur cloud accepte une variable d'environnement alias conventionnelle. La valeur générique `AI_*` a toujours la priorité ; l'alias est le repli.

| Fournisseur       | Alias de clé API       | Alias d'URL de base     |
| ----------------- | ---------------------- | ----------------------- |
| Anthropic         | `ANTHROPIC_API_KEY`    | —                       |
| OpenAI            | `OPENAI_API_KEY`       | —                       |
| Mistral           | `MISTRAL_API_KEY`      | —                       |
| Google Gemini     | `GOOGLE_API_KEY`       | —                       |
| Ollama            | — (pas de clé)         | `OLLAMA_BASE_URL`       |
| Compatible OpenAI | (utilise `AI_API_KEY`) | (utilise `AI_BASE_URL`) |

## Modèles par défaut

Lorsque `AI_MODEL` n'est pas défini, chaque fournisseur résout vers une valeur par défaut raisonnable :

| Fournisseur       | Modèle par défaut            |
| ----------------- | ---------------------------- |
| Anthropic         | `claude-sonnet-4-5`          |
| OpenAI            | `gpt-4o`                     |
| Mistral           | `mistral-large-latest`       |
| Google Gemini     | `gemini-2.0-flash`           |
| Ollama            | `llama3.1`                   |
| Compatible OpenAI | _aucun_ — définir `AI_MODEL` |

Les points d'accès compatibles OpenAI pointent vers un backend arbitraire, il n'y a donc pas de modèle par défaut universel — vous devez définir `AI_MODEL` explicitement.

## Validation des modèles

Pour les fournisseurs ayant un catalogue connu (Anthropic, OpenAI, Mistral, Google), Sovrium émet un **avertissement de démarrage non fatal** lorsque `AI_MODEL` (ou un remplacement `model` d'un agent) ne correspond pas à un modèle reconnu — typiquement une confusion inter-fournisseurs (`gpt-4o` sur `anthropic`) ou une faute de frappe (`claud-sonet`). C'est un avertissement, pas une erreur ; le serveur démarre quand même.

Les fournisseurs Ollama et compatible OpenAI ont des **catalogues ouverts** (modèles installés localement, points d'accès arbitraires), la validation du nom de modèle est donc entièrement ignorée pour eux.

## Exemples de configuration

```bash
# Auto-hébergé, sans coût, frugal par défaut : Ollama local.
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434     # ou OLLAMA_BASE_URL
AI_MODEL=llama3.1
AI_EMBEDDING_MODEL=nomic-embed-text
```

```bash
# Anthropic avec un remplacement de température.
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...           # ou AI_API_KEY
AI_MODEL=claude-sonnet-4-5
AI_TEMPERATURE=0.3
AI_MAX_TOKENS=4096
```

```bash
# Une passerelle compatible OpenAI (vLLM, LiteLLM, Azure OpenAI, etc.).
AI_PROVIDER=openai-compatible
AI_BASE_URL=https://my-gateway.internal/v1
AI_API_KEY=...
AI_MODEL=my-deployed-model             # requis — aucune valeur par défaut
```

:::callout
**Remplacements par agent.** Tout agent dans `app.agents[]` peut remplacer `model`, `temperature` et `maxTokens` pour lui-même, en revenant à ces valeurs par défaut des variables d'environnement lorsqu'ils sont omis. Voir [Agents IA](/fr/ai-agents).
:::

## Pages connexes

- [Vue d'ensemble de l'IA](/fr/ai-overview) — la carte complète de l'écosystème IA.
- [Routage éco IA](/fr/ai-eco-routing) — précédence de fournisseur local d'abord.
- [Agents IA](/fr/ai-agents) — remplacements de modèle par agent.
- [RAG IA](/fr/ai-rag) — modèle d'embedding et stockage vectoriel.
- [Variables d'environnement](/fr/env-vars) — référence complète des variables d'environnement.

# Routage éco IA

Sovrium traite l'empreinte environnementale comme une propriété de plateforme de premier ordre. L'inférence IA est l'une des opérations les plus gourmandes en ressources qu'une plateforme puisse effectuer, c'est pourquoi Sovrium route les appels IA **local d'abord par défaut** : lorsqu'un modèle local (Ollama) est accessible, il répond ; ce n'est que lorsqu'il ne l'est pas que l'appel bascule vers un fournisseur cloud configuré.

Ceci est contrôlé par une seule variable d'environnement d'opérateur — `ECO_AI_PROVIDER_PRECEDENCE` — jamais par le schéma de l'application. Comme toute variable `ECO_*`, sa valeur par défaut est le réglage aligné sur l'écologie ; les opérateurs se _désengagent_, jamais ne s'engagent.

```bash
ECO_AI_PROVIDER_PRECEDENCE=local-first   # la valeur par défaut — généralement à omettre entièrement
AI_PROVIDER=anthropic                    # cible de repli cloud
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434   # point d'accès du fournisseur local
```

## Modes de précédence

| Valeur        | Comportement                                                                                                                                                |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local-first` | **(par défaut)** Privilégier un Ollama local accessible ; basculer vers le fournisseur cloud `AI_PROVIDER` configuré lorsque Ollama est inaccessible.       |
| `cloud-first` | Utiliser le fournisseur cloud configuré ; utiliser un Ollama accessible uniquement lorsqu'aucun fournisseur cloud n'est configuré.                          |
| `local-only`  | Utiliser un fournisseur local exclusivement. Les appels IA n'ont aucun repli cloud — lorsqu'aucun Ollama accessible n'est configuré, l'IA est indisponible. |

Une valeur non définie, vide ou non reconnue résout vers la valeur par défaut alignée sur l'écologie, `local-first`.

## Comment le routage se résout

Le résolveur combine trois entrées : la précédence active, si un point d'accès Ollama est **configuré** (via `OLLAMA_BASE_URL`, ou `AI_BASE_URL` lorsque `AI_PROVIDER=ollama`), et si la sonde d'accessibilité de l'exécution a trouvé Ollama **utilisable** (configuré _et_ répondant).

| Précédence    | Ollama utilisable | Cloud configuré | Route vers     | Notes                                                                           |
| ------------- | ----------------- | --------------- | -------------- | ------------------------------------------------------------------------------- |
| `local-first` | oui               | —               | Ollama         | Chemin local privilégié.                                                        |
| `local-first` | non               | oui             | cloud          | Repli. Signalé avec une raison lorsqu'Ollama était configuré mais inaccessible. |
| `local-first` | non               | non             | Ollama / aucun | Désactivé lorsqu'aucun fournisseur n'est configuré du tout.                     |
| `cloud-first` | —                 | oui             | cloud          | Le cloud l'emporte toujours lorsqu'il est configuré.                            |
| `cloud-first` | oui               | non             | Ollama         | Local utilisé uniquement parce qu'aucun cloud n'est configuré.                  |
| `local-only`  | oui               | —               | Ollama         | Local exclusivement.                                                            |
| `local-only`  | non               | —               | aucun          | Aucun repli — IA indisponible jusqu'à ce qu'un Ollama accessible existe.        |

:::callout
**L'accessibilité est sondée, pas supposée.** L'exécution vérifie si le point d'accès Ollama configuré répond réellement avant de router vers lui. Sous `local-first`, lorsqu'Ollama est _configuré mais inaccessible_, le repli vers le cloud est enregistré avec une raison destinée à l'opérateur ; lorsqu'Ollama n'a jamais été configuré, le repli se produit silencieusement.
:::

## Observabilité

La décision de routage éco active est exposée sur le point d'accès de santé (`GET /api/health`, sous `body.ai`) :

| Champ              | Signification                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| `precedence`       | La valeur `ECO_AI_PROVIDER_PRECEDENCE` active.                                                           |
| `resolvedProvider` | Le fournisseur canonique vers lequel les appels IA sont routés (ou absent lorsque l'IA est désactivée).  |
| `ollamaReachable`  | Si la sonde Ollama locale a réussi.                                                                      |
| `configured`       | La valeur brute `AI_PROVIDER`.                                                                           |
| `fallbackReason`   | Pourquoi le résolveur a basculé vers un fournisseur non privilégié (présent uniquement en cas de repli). |

Cela rend le routage auditable : les opérateurs peuvent confirmer si un déploiement s'exécute réellement sur son modèle local ou consomme silencieusement des jetons cloud.

## Exemples de configuration

```bash
# Valeur par défaut frugale : Ollama local avec un filet de sécurité Anthropic.
# (ECO_AI_PROVIDER_PRECEDENCE=local-first est la valeur par défaut — affichée pour clarté.)
ECO_AI_PROVIDER_PRECEDENCE=local-first
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434
AI_MODEL=claude-sonnet-4-5
```

```bash
# Déploiement strict local-only — aucune donnée ne quitte jamais l'hôte.
ECO_AI_PROVIDER_PRECEDENCE=local-only
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
```

```bash
# Qualité d'abord : toujours utiliser le fournisseur cloud.
ECO_AI_PROVIDER_PRECEDENCE=cloud-first
AI_PROVIDER=openai
OPENAI_API_KEY=...
AI_MODEL=gpt-4o
```

## Pages connexes

- [Fournisseurs IA](/fr/ai-providers) — configuration du fournisseur, de la clé et de l'URL de base.
- [Vue d'ensemble de l'IA](/fr/ai-overview) — l'écosystème IA et la philosophie de configuration.
- [Variables d'environnement](/fr/env-vars) — référence complète `ECO_*` et `AI_*`.

# Chat IA

Le Chat IA est une interface conversationnelle sur les données de votre application. Les utilisateurs posent des questions et émettent des commandes en langage naturel ; la plateforme les traduit en requêtes, mutations et déclenchements d'automatisations autorisés, puis renvoie une réponse structurée. Il est disponible à la fois comme point d'accès REST (`POST /api/ai/chat`) et comme composant de page intégrable (`type: ai-chat`).

Le chat est **natif** une fois `AI_PROVIDER` configuré — la plateforme détecte automatiquement chaque table et champ, aucun YAML par table n'est donc nécessaire pour la prise en charge des requêtes. Toutes les actions effectuées via le chat sont régies par le RBAC et les permissions au niveau des champs de l'utilisateur demandeur, et sont écrites dans le journal d'activité pour une auditabilité complète.

## Ce que le chat peut et ne peut pas faire

| Le chat **peut**                                                                            | Le chat **ne peut pas**                                                         |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Interroger des enregistrements à travers les tables en langage naturel                      | Modifier les schémas de table (ajouter/supprimer des champs, changer des types) |
| Créer, mettre à jour et supprimer des enregistrements (opérations destructrices confirmées) | Créer ou modifier des automatisations                                           |
| Déclencher des automatisations à déclenchement manuel que l'utilisateur peut exécuter       | Accéder aux enregistrements hors des permissions RBAC de l'utilisateur          |
| Maintenir le contexte conversationnel au sein d'une session                                 | Contourner les permissions au niveau des champs                                 |

## Architecture

```
Message utilisateur
    │
    ▼
POST /api/ai/chat ──▶ Résoudre l'agent (ou IA par défaut) ──▶ Injecter le contexte
    │                                                            │
    │   ┌────────────────────────────────────────────────────────┘
    ▼   ▼
Fournisseur IA ──▶ Appels d'outils (requête, mutation, déclenchement) ──▶ Vérification RBAC ──▶ Journal d'activité
    │
    ▼
Réponse structurée (texte de réponse + actions effectuées)
```

Le chat résout un agent (lorsqu'un est nommé) ou revient au fournisseur IA par défaut. Le modèle interagit avec les données exclusivement par **appels d'outils** — des opérations structurées que Sovrium exécute après une vérification RBAC — plutôt que de fabriquer des données en texte libre.

## Utiliser le chat comme composant de page

Le composant `ai-chat` intègre un panneau de chat dans n'importe quelle page.

```yaml
pages:
  - name: dashboard
    path: /dashboard
    components:
      - type: ai-chat
        agent: support-agent # optionnel — revient au fournisseur IA par défaut
        placeholder: Posez une question sur vos tickets...
        chatHeight: 600
        showHistory: true
        allowAttachments: false
```

| Propriété          | Description                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `agent`            | Nom de l'agent depuis `app.agents[]`. Omettre pour utiliser le fournisseur IA par défaut. |
| `placeholder`      | Texte d'invite pour le champ de saisie du chat.                                           |
| `chatHeight`       | Hauteur du conteneur de chat en pixels (doit être > 0).                                   |
| `showHistory`      | Si l'historique de conversation précédent doit être affiché au chargement.                |
| `allowAttachments` | Si les pièces jointes de fichiers sont autorisées dans le chat.                           |

## Utiliser l'API REST

```http
POST /api/ai/chat
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "message": "How many open tickets are there?",
  "context": { "table": "tickets" },
  "sessionId": "sess_abc123"
}
```

```json
{
  "reply": "There are 42 open tickets — 5 critical, 12 high, 18 medium, 7 low.",
  "actions": [
    {
      "type": "query",
      "table": "tickets",
      "description": "Counted tickets where status = 'open', grouped by priority"
    }
  ],
  "sessionId": "sess_abc123"
}
```

## Requêtes d'enregistrements

Lorsque `AI_PROVIDER` est défini, l'API de chat traduit nativement les questions en langage naturel en requêtes SQL/API contre les tables **autorisées** de l'utilisateur, les exécute, et formate le résultat dans la conversation. Aucune configuration n'est requise — la plateforme introspecte le schéma automatiquement. Les requêtes n'atteignent jamais des tables ou des champs que le rôle demandeur ne peut pas lire.

## Mutations d'enregistrements

Le chat peut créer, mettre à jour et supprimer des enregistrements pour le compte de l'utilisateur. Les mutations respectent les permissions au niveau des champs (un rôle qui ne peut pas écrire un champ ne peut pas le définir via le chat), et les **opérations destructrices nécessitent une confirmation** avant de s'exécuter. Chaque mutation est enregistrée dans le journal d'activité avec l'utilisateur qui l'a initiée.

## Déclencher des automatisations

Le chat peut invoquer les automatisations à **déclenchement manuel** que l'utilisateur est autorisé à exécuter, puis rapporter le résultat dans la conversation. Le chat ne peut pas exécuter des automatisations d'autres types de déclenchement, ni créer ou éditer des définitions d'automatisation.

## Appel d'outils

Le chat est construit sur l'appel de fonctions/outils. Sovrium présente au modèle un ensemble de définitions d'outils (requête, mutation, déclenchement) ; le modèle retourne un `tool_call` ; Sovrium l'exécute **après une vérification RBAC** et renvoie le résultat au modèle, qui compose alors la réponse finale. L'appel d'outils structuré — plutôt que la génération de données en texte libre — est ce qui maintient le chat ancré et auditable.

```
Message utilisateur → Fournisseur IA (avec définitions d'outils)
                    │
                    ▼
              L'IA retourne tool_call
                    │
                    ▼
         Sovrium exécute l'outil (RBAC vérifié)
                    │
                    ▼
         Résultat de l'outil renvoyé à l'IA
                    │
                    ▼
              L'IA retourne la réponse textuelle finale
```

## Réponses en streaming

Le chat prend en charge le streaming Server-Sent Events (SSE) afin que les utilisateurs voient la génération de texte progressive au lieu d'attendre la réponse complète.

| Comportement                    | Détail                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Livraison par fragments         | Le contenu partiel du message arrive sous forme de fragments SSE, transmis en temps réel à mesure que le fournisseur les émet. |
| Marqueur d'achèvement           | L'événement SSE final porte un marqueur `[DONE]` ; le message complet est assemblé à partir de tous les fragments.             |
| Persistance                     | Les messages diffusés sont persistés dans l'historique de conversation une fois terminés.                                      |
| Permissions                     | Le streaming applique le même RBAC que le chat non diffusé.                                                                    |
| Temps jusqu'au premier fragment | Un `504` est retourné lorsque le fournisseur n'envoie aucun premier fragment avant `AI_CHAT_STREAM_TIMEOUT`.                   |
| Coupure de connexion            | Gérée gracieusement — une réponse partielle est rejetée si la connexion se coupe avant l'achèvement.                           |

## Limitation de débit

Les limites de débit par utilisateur protègent le fournisseur IA d'une surcharge et plafonnent le coût. Les limites sont configurées via des variables d'environnement, et non le schéma de l'application.

| Variable                 | Description                                                                  | Défaut   |
| ------------------------ | ---------------------------------------------------------------------------- | -------- |
| `AI_CHAT_RATE_LIMIT`     | Messages autorisés par fenêtre, par utilisateur.                             | `60`     |
| `AI_CHAT_RATE_WINDOW`    | Durée de la fenêtre de limitation de débit.                                  | 1 minute |
| `AI_CHAT_STREAM_TIMEOUT` | Délai pour le temps jusqu'au premier fragment sur les requêtes en streaming. | —        |

Une requête limitée en débit retourne `429` avec un en-tête `Retry-After` et des informations de quota restant. Chaque utilisateur a un compteur indépendant, et la fenêtre se réinitialise après son expiration. Les appels API d'agent respectent les mêmes limites que le chat utilisateur.

## Gestion des erreurs

Lorsque le fournisseur IA échoue, le chat retourne une erreur conviviale plutôt que de divulguer les rouages internes bruts du fournisseur. Lorsque `AI_PROVIDER` n'est pas défini, le point d'accès du chat répond avec un état désactivé au lieu d'échouer — conformément au contrat « IA dormante jusqu'à configuration » de la plateforme.

## Pages connexes

- [Vue d'ensemble de l'IA](/fr/ai-overview) — l'écosystème IA complet.
- [Fournisseurs IA](/fr/ai-providers) — configurer le backend LLM.
- [Agents IA](/fr/ai-agents) — agents qui propulsent les panneaux de chat nommés.
- [Mémoire IA](/fr/ai-memory) — historique de conversation et faits appris.
- [Vue d'ensemble des enregistrements](/fr/records-overview) — le modèle CRUD d'enregistrements sur lequel le chat opère.
- [Rôles & RBAC](/fr/auth-roles-rbac) — les permissions que le chat applique toujours.

# Agents IA

Un agent est un acteur IA autonome qui opère **comme un utilisateur virtuel** à l'intérieur de votre application. Chaque agent se lie à un rôle auth, est restreint à une liste blanche explicite de tables et d'actions, et peut être encadré par une approbation humaine, s'exécuter selon une planification et être borné par des limites opérationnelles. Les agents sont déclarés dans le tableau de premier niveau `app.agents[]`.

Les agents nécessitent que `app.auth` soit configuré (ils sont stockés comme utilisateurs auth) et que `AI_PROVIDER` soit défini.

```yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: You are a courteous support assistant. Resolve tickets accurately.
    tools:
      tables: [tickets, customers]
      actions: [record.read, record.update, email.send]
    approval:
      mode: selective
      required: [email.send]
    limits:
      maxActionsPerMinute: 20
      maxTokensPerDay: 100000
```

## Modèle agent-en-tant-qu'utilisateur

Chaque agent est matérialisé à l'exécution comme un enregistrement `auth.user` avec `type: 'agent'` et un e-mail synthétique (`{name}@agents.sovrium.local`). C'est le fondement de la sécurité des agents :

- L'agent **hérite de chaque permission de table et de champ de son rôle assigné**, exactement comme un utilisateur humain.
- Les agents **ne peuvent pas s'authentifier** via un quelconque point d'accès de connexion (e-mail/mot de passe, lien magique, OTP).
- Les actions d'agent apparaissent dans le journal d'activité avec `actor.type = 'agent'`.
- Les utilisateurs agents sont exclus de la liste des utilisateurs par défaut, et inclus uniquement lorsque `?includeAgents=true` est passé.

Les enregistrements d'utilisateurs agents sont gérés automatiquement : créés au premier démarrage, mis à jour lorsque le rôle change, et supprimés en douceur lorsque l'agent est retiré de la configuration.

## Propriétés de définition

Les champs d'identité principaux sont intégrés au niveau supérieur de chaque entrée d'agent.

| Propriété      | Description                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `name`         | Identifiant unique en kebab-case (ex. `support-agent`). Lettres minuscules, chiffres, tirets simples.    |
| `role`         | Rôle auth sous lequel l'agent opère. Doit référencer un rôle dans `auth.roles`.                          |
| `systemPrompt` | Invite système définissant la personnalité, le rôle et les règles de l'agent.                            |
| `instructions` | Tableau optionnel d'instructions comportementales, ajoutées comme règles numérotées à l'invite système.  |
| `model`        | Remplacement du modèle LLM (par défaut `AI_MODEL`).                                                      |
| `temperature`  | Remplacement de la température, `0`–`1` inclus (par défaut `AI_TEMPERATURE`).                            |
| `maxTokens`    | Remplacement du nombre maximal de jetons de sortie (par défaut `AI_MAX_TOKENS`).                         |
| `enabled`      | Si l'agent peut s'exécuter. Par défaut `true`. Les agents désactivés ignorent les exécutions planifiées. |

## Outils & sécurité à double garde-fou

Le bloc `tools` est la liste blanche de capacités de l'agent. Sovrium applique un modèle de sécurité à **double garde-fou** — les deux garde-fous doivent passer :

1. **Garde-fou RBAC** — le rôle de l'agent a-t-il la permission pour cette table/action ?
2. **Garde-fou liste blanche** — cette table/action est-elle listée dans les `tools` de l'agent ?

Un agent sans `tools` n'a **aucun accès** (sécurisé par défaut).

| Propriété       | Description                                                                               |
| --------------- | ----------------------------------------------------------------------------------------- |
| `tools.tables`  | Noms de tables auxquels l'agent peut accéder (au moins une ; doit exister dans `tables`). |
| `tools.actions` | Types d'actions que l'agent peut effectuer (au moins une ; voir ci-dessous).              |

### Actions disponibles

Les actions suivent le motif `type.operator` utilisé par le moteur d'automatisation.

| Catégorie  | Actions                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------- |
| **Record** | `record.read`, `record.create`, `record.update`, `record.delete`                                |
| **State**  | `state.get`, `state.set`, `state.increment`, `state.delete`, `state.list` (KV inter-exécutions) |
| **HTTP**   | `http.request`                                                                                  |
| **AI**     | `ai.generate`, `ai.classify`, `ai.extract` (chaîner des sous-tâches LLM)                        |
| **Code**   | `code.runTypescript` (en bac à sable)                                                           |
| **Email**  | `email.send`                                                                                    |
| **Auth**   | `auth.createUser`, `auth.assignRole`, `auth.banUser`, `auth.unbanUser`                          |
| **File**   | `file.upload`, `file.download`, `file.delete`, `file.list`, `file.getMetadata`                  |

## Permissions : qui peut invoquer l'agent

Le bloc optionnel `permissions` décrit l'intégration RBAC de l'agent et qui peut le déclencher.

| Propriété                 | Description                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| `permissions.type`        | Discriminateur de type d'utilisateur — toujours `agent`.                                              |
| `permissions.trigger`     | Qui peut invoquer cet agent : `all`, `authenticated`, ou un tableau de rôles comme `[admin, member]`. |
| `permissions.emailDomain` | Domaine pour l'e-mail synthétique de l'agent (par défaut `agents.sovrium.local`).                     |

## Approbation humaine dans la boucle

Le bloc `approval` encadre les actions de l'agent derrière une revue humaine.

| Propriété             | Description                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `approval.mode`       | `none` (exécuter immédiatement), `all` (chaque action nécessite une approbation), ou `selective`.            |
| `approval.required`   | Actions nécessitant une approbation (un sous-ensemble de `tools.actions`). Requis lorsque `mode: selective`. |
| `approval.timeout`    | Secondes avant qu'une approbation en attente n'expire (par défaut `3600`).                                   |
| `approval.escalation` | Escalade lorsqu'une approbation reste en attente — `{ after: <seconds>, to: <role> }`.                       |

```yaml
approval:
  mode: selective
  required: [record.delete, email.send]
  timeout: 1800
  escalation:
    after: 600
    to: admin
```

:::callout
**L'`after` d'escalade doit être inférieur au `timeout`.** Une approbation qui n'est pas traitée dans les `after` secondes escalade vers le rôle `to` ; si toujours non traitée au `timeout`, elle expire.
:::

## Exécution planifiée

Le bloc `schedule` fait s'exécuter un agent automatiquement à un intervalle cron. Le `taskPrompt` est envoyé au LLM comme message utilisateur à chaque exécution.

| Propriété             | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `schedule.cron`       | Expression cron standard à 5 champs (ex. `*/15 * * * *`, `0 9 * * MON`). |
| `schedule.timezone`   | Identifiant de fuseau horaire IANA (par défaut `UTC`).                   |
| `schedule.taskPrompt` | Invite envoyée au LLM à chaque exécution planifiée.                      |

```yaml
schedule:
  cron: '0 9 * * MON'
  timezone: Europe/Paris
  taskPrompt: Summarize last week's new tickets and post the digest.
```

Les exécutions planifiées respectent `enabled` (les agents désactivés les ignorent) et `approval` (ex. `mode: all` met en pause l'exécution planifiée pour validation humaine).

## Limites opérationnelles

Le bloc `limits` plafonne la consommation de ressources pour empêcher les agents emballés. Tous les champs sont optionnels et reviennent aux valeurs par défaut du système.

| Propriété                    | Défaut   | Description                                                       |
| ---------------------------- | -------- | ----------------------------------------------------------------- |
| `limits.maxActionsPerMinute` | `30`     | Nombre maximal d'actions BD/e-mail par minute.                    |
| `limits.maxTokensPerDay`     | `200000` | Nombre maximal de jetons LLM par 24 h. Réinitialisé à minuit UTC. |
| `limits.maxConcurrentTasks`  | `5`      | Nombre maximal d'exécutions de tâches simultanées.                |

## Mémoire, connaissances et MCP

Les agents se composent avec trois capacités supplémentaires, chacune documentée dans sa propre page :

| Bloc        | Objectif                                                                                    | Documentation                          |
| ----------- | ------------------------------------------------------------------------------------------- | -------------------------------------- |
| `memory`    | Historique de conversation, récupération de connaissances RAG, et faits appris persistants. | [Mémoire IA](/fr/ai-memory)            |
| `knowledge` | Tables et documents à intégrer comme base de connaissances RAG de l'agent.                  | [RAG IA](/fr/ai-rag)                   |
| `mcp`       | Liste blanche d'outils MCP externes que l'agent peut invoquer.                              | [Intégration MCP](/fr/mcp-integration) |

## Multi-agent & invocation

Les agents peuvent être invoqués depuis l'interface de chat IA (un composant `ai-chat` nommé), via l'API, selon une planification, et depuis les automatisations via l'[action `ai:agent`](/fr/automation-ai-actions). Parce que chaque agent est un utilisateur virtuel distinct avec son propre rôle et sa propre liste blanche d'outils, plusieurs agents peuvent coexister avec des frontières de privilèges différentes — un agent analyste en lecture seule et un agent de triage capable d'écrire, par exemple.

## Exemple complet

```yaml
agents:
  - name: data-analyst
    role: analyst
    systemPrompt: You are an expert data analyst. Be precise and cite the records you used.
    instructions:
      - Never expose customer PII in summaries.
      - Prefer aggregates over row-level dumps.
    tools:
      tables: [orders, customers]
      actions: [record.read]
    approval:
      mode: none
    limits:
      maxActionsPerMinute: 20
      maxTokensPerDay: 150000
    schedule:
      cron: '0 7 * * *'
      timezone: UTC
      taskPrompt: Produce the daily orders summary.
```

## Pages connexes

- [Vue d'ensemble de l'IA](/fr/ai-overview) — l'écosystème IA complet.
- [Fournisseurs IA](/fr/ai-providers) — valeurs par défaut de modèle, température et jetons dont héritent les agents.
- [Chat IA](/fr/ai-chat) — intégrer un agent comme panneau conversationnel.
- [Mémoire IA](/fr/ai-memory) — conversation, connaissances et faits d'agent.
- [RAG IA](/fr/ai-rag) — sources de connaissances que les agents intègrent.
- [Intégration MCP](/fr/mcp-integration) — agents comme clients MCP.
- [Actions IA](/fr/automation-ai-actions) — l'action d'automatisation `ai:agent` et le vocabulaire d'actions IA.
- [Rôles & RBAC](/fr/auth-roles-rbac) — les permissions de rôle dont héritent les agents.

# RAG IA

La génération augmentée par récupération (RAG) permet aux agents et à l'interface de chat de répondre aux questions ancrées dans **les données réelles de votre application** — enregistrements de table et documents téléversés — au lieu de s'appuyer uniquement sur les données d'entraînement du modèle. Avant de générer une réponse, l'exécution récupère le contenu le plus pertinent depuis une base de connaissances indexée vectoriellement et l'injecte dans le contexte.

Le RAG est **natif** une fois `AI_PROVIDER` configuré : l'infrastructure d'embedding est provisionnée automatiquement, sans YAML requis pour câbler le stockage. Les auteurs de schéma déclarent _ce qu'il faut_ intégrer (dans le bloc `knowledge` d'un agent) ; les opérateurs ajustent le _comment_ via des variables d'environnement.

## Architecture

```
Sources de connaissances                  Magasin vectoriel
    │                                          │
    ├── Enregistrements de table ─▶ Découper + Intégrer ─▶  │
    │   (champs spécifiés)                     │
    │                                          │
    └── Documents ─────────────▶ Découper + Intégrer ─▶  │
        (PDF, MD, TXT)                         ▼
                                       Recherche par similarité
                                              │
                                              ▼
                       Fournisseur IA (génère une réponse ancrée)
```

## Stockage adapté au dialecte

Le RAG fonctionne sur **les deux** dialectes de base de données via le port `AiEmbeddingRepository` — il n'y a aucune base de données vectorielle externe pour l'un ou l'autre.

| Dialecte   | Stockage                                                  | Similarité                                           |
| ---------- | --------------------------------------------------------- | ---------------------------------------------------- |
| PostgreSQL | Extension pgvector ; colonne `vector` dans le schéma `ai` | Distance cosinus calculée en SQL (indexée HNSW).     |
| SQLite     | Colonne BLOB `Float32` (octets compactés)                 | Similarité cosinus calculée dans le code applicatif. |

:::callout
**La valeur par défaut frugale — SQLite + Ollama — prend en charge le RAG.** SQLite stocke les vecteurs comme BLOB `Float32` compactés et calcule la similarité cosinus dans le code applicatif, normalisée pour correspondre au contrat Postgres. L'enveloppe de réponse et la forme de chaque résultat (`agentName`, `sourceRef`, `content`, `similarity`) sont identiques entre dialectes, de sorte que les appelants ne se ramifient jamais selon le moteur de stockage.
:::

## Sources de connaissances

Le bloc `knowledge` d'un agent définit les sources de données d'entrée intégrées dans sa base de connaissances. Les deux types de sources sont optionnels et peuvent être combinés.

### Connaissances de table

Intégrer des champs spécifiés depuis une table. Seuls les champs de type texte (single-line-text, long-text, rich-text, markdown) devraient être intégrés. Un `filter` optionnel limite quelles lignes sont incluses.

```yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: Answer using the FAQ and published docs.
    knowledge:
      tables:
        - { table: faq, fields: [question, answer] }
        - { table: docs, fields: [content], filter: { status: published } }
```

| Propriété | Description                                                                        |
| --------- | ---------------------------------------------------------------------------------- |
| `table`   | Nom de table à intégrer (doit référencer une table dans `app.tables`).             |
| `fields`  | Noms de champs à inclure dans les embeddings (au moins un).                        |
| `filter`  | Filtre d'égalité clé-valeur optionnel sélectionnant quelles lignes sont intégrées. |

Lorsque les enregistrements sources changent, les embeddings sont mis à jour automatiquement (auto-synchronisation).

### Connaissances de document

Intégrer des fichiers de documents (PDF, Markdown, texte brut) découverts dans le répertoire de connaissances.

```yaml
knowledge:
  documents:
    - { path: /knowledge/product-manual.pdf, label: Product Manual }
```

| Propriété | Description                                   |
| --------- | --------------------------------------------- |
| `path`    | Chemin du fichier vers le document.           |
| `label`   | Étiquette lisible optionnelle pour la source. |

Les documents placés dans `AI_KNOWLEDGE_DIR` sont nativement découverts, analysés, découpés, intégrés et stockés.

| Format     | Extension | Notes                                                            |
| ---------- | --------- | ---------------------------------------------------------------- |
| PDF        | `.pdf`    | Texte uniquement ; les PDF numérisés ne sont pas pris en charge. |
| Markdown   | `.md`     | Formatage retiré, structure conservée.                           |
| Texte brut | `.txt`    | Ingéré directement.                                              |

## Restriction de connaissances par agent

Chaque agent a sa propre base de connaissances **isolée**, indexée par le nom de l'agent. Un agent ne récupère jamais les embeddings d'un autre agent. Le chat peut en outre accéder aux connaissances restreintes aux permissions de l'utilisateur demandeur. Cette isolation permet à un agent de support et à un agent commercial d'intégrer des corpus entièrement différents sans contamination croisée.

## Configuration d'embedding et de récupération

Le découpage, l'embedding et la récupération sont ajustés via des variables d'environnement.

| Variable                  | Description                                                      | Défaut                                       |
| ------------------------- | ---------------------------------------------------------------- | -------------------------------------------- |
| `AI_EMBEDDING_MODEL`      | Modèle d'embedding à utiliser.                                   | Modèle d'embedding par défaut du fournisseur |
| `AI_EMBEDDING_DIMENSIONS` | Dimensions du vecteur (doit correspondre à la sortie du modèle). | Auto-détecté depuis le modèle                |
| `AI_KNOWLEDGE_DIR`        | Chemin vers le dossier des documents de connaissances.           | `./knowledge`                                |
| `AI_RAG_CHUNK_SIZE`       | Caractères par fragment.                                         | `512`                                        |
| `AI_RAG_CHUNK_OVERLAP`    | Chevauchement entre fragments adjacents.                         | `50`                                         |
| `AI_RAG_SIMILARITY`       | Similarité cosinus minimale pour conserver un résultat (0–1).    | `0.7`                                        |
| `AI_RAG_MAX_RESULTS`      | Nombre maximal de fragments retournés par requête.               | `5`                                          |

## API de reconstruction & de recherche

| Point d'accès              | Objectif                                                                                                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/ai/rag/rebuild` | Réintègre les connaissances configurées d'agent/document et persiste les vecteurs. Réservé à l'admin lorsque `app.auth` est configuré.                                    |
| `POST /api/ai/rag/search`  | Intègre une requête, exécute une recherche par similarité (optionnellement restreinte par `agent`), filtre par le seuil de similarité, et retourne des résultats classés. |

Les deux points d'accès se comportent de manière identique entre PostgreSQL et SQLite — même autorisation, même forme de réponse.

## Pages connexes

- [Vue d'ensemble de l'IA](/fr/ai-overview) — l'écosystème IA complet.
- [Agents IA](/fr/ai-agents) — agents qui possèdent des bases de connaissances.
- [Mémoire IA](/fr/ai-memory) — récupération de connaissances à l'exécution vs sources intégrées.
- [Fournisseurs IA](/fr/ai-providers) — configuration du modèle d'embedding.
- [Variables d'environnement](/fr/env-vars) — référence complète `AI_RAG_*`.

# Mémoire IA

La mémoire d'agent donne à un agent un contexte qui persiste au-delà d'un seul message. Elle est configurée sous le bloc `memory` d'un agent et est composée de **trois niveaux indépendants**, chacun désactivé par défaut et activé individuellement. Avant que l'exécution n'invoque le LLM (par exemple, lorsque l'action d'automatisation `ai:agent` dispatche une tâche), elle assemble le contexte à partir des niveaux activés.

| Niveau         | Persistance                        | Direction        | Objectif                                                                |
| -------------- | ---------------------------------- | ---------------- | ----------------------------------------------------------------------- |
| `conversation` | Niveau session (éphémère, fenêtré) | Lecture          | Maintenir le contexte de dialogue à travers les messages récents.       |
| `knowledge`    | Sources RAG en lecture seule       | Lecture          | Récupérer des documents pertinents via la recherche sémantique.         |
| `facts`        | Persistant à travers les sessions  | Lecture/écriture | Mémoriser les faits gérés par l'IA que l'agent apprend au fil du temps. |

```yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: Be helpful and remember the customer's preferences.
    memory:
      conversation:
        enabled: true
        windowSize: 10
        summarize: true
      knowledge:
        enabled: true
        sources: [faq, docs]
        retrievalLimit: 5
        similarityThreshold: 0.7
      facts:
        enabled: true
        maxFacts: 100
        namespace: support
```

## Mémoire de conversation

Retient les messages récents de la session de l'agent. Lorsqu'elle est activée, l'exécution charge les `windowSize` derniers messages dans le contexte avant chaque invocation.

| Propriété    | Défaut  | Description                                                                                    |
| ------------ | ------- | ---------------------------------------------------------------------------------------------- |
| `enabled`    | `false` | Si la mémoire de conversation est active.                                                      |
| `windowSize` | `10`    | Nombre de messages récents conservés dans le contexte.                                         |
| `summarize`  | `false` | Lorsque `true`, les messages plus anciens sont compressés en résumé au lieu d'être abandonnés. |

## Mémoire de connaissances

Récupération sémantique basée sur RAG depuis les sources de connaissances configurées. Lorsqu'elle est activée, l'exécution exécute une recherche par similarité contre les sources listées avant chaque invocation et injecte les documents les plus pertinents dans le contexte. C'est le côté _récupération à l'exécution_ du RAG — distinct du bloc `knowledge` de l'agent, qui définit les _sources d'entrée_ qui sont intégrées.

| Propriété             | Défaut  | Description                                                                                                 |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `enabled`             | `false` | Si la récupération de connaissances est active.                                                             |
| `sources`             | —       | Noms des sources de connaissances à rechercher (doivent référencer des bases de connaissances configurées). |
| `retrievalLimit`      | `5`     | Nombre maximal de documents récupérés par requête.                                                          |
| `similarityThreshold` | `0.7`   | Score de similarité minimal (`0`–`1`) pour qu'un document récupéré soit inclus.                             |

:::callout
**La mémoire de connaissances réutilise le pipeline RAG.** La récupération s'exécute contre le même magasin vectoriel décrit dans [RAG IA](/fr/ai-rag) — pgvector sur PostgreSQL ou BLOB `Float32` + cosinus côté application sur SQLite.
:::

## Mémoire de faits

Faits clé-valeur persistants que l'agent apprend à travers les sessions. Contrairement à l'action d'automatisation `state` (KV défini explicitement par le développeur), les faits sont **gérés par l'IA** : l'agent lui-même décide ce qui vaut la peine d'être mémorisé. Les faits sont récupérés par pertinence sémantique à la tâche courante, et non par recherche de clé exacte.

| Propriété   | Défaut         | Description                                                                                         |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------- |
| `enabled`   | `false`        | Si la mémoire de faits est active.                                                                  |
| `maxFacts`  | `100`          | Nombre maximal de faits que l'agent peut stocker.                                                   |
| `namespace` | nom de l'agent | Espace de noms pour l'isolation des faits. Minuscule, commence par une lettre (`^[a-z][a-z0-9-]*`). |

### Isolation d'espace de noms & restriction par utilisateur

Les faits sont partitionnés par `namespace` (par défaut le nom de l'agent), de sorte que deux agents ne lisent jamais les faits appris l'un de l'autre. Combiné au modèle agent-en-tant-qu'utilisateur — chaque agent est un `auth.user` distinct — cela donne une isolation des faits par agent et, lorsque le chat restreint par session, par utilisateur. Un agent ne peut pas faire fuiter les faits appris d'un client dans la conversation d'un autre client.

## Composition des niveaux

Les trois niveaux sont optionnels et se combinent librement. Un agent analyste en lecture seule pourrait n'activer que `knowledge` ; un agent de support de longue durée pourrait activer les trois. Lorsque plusieurs niveaux sont activés, l'exécution assemble le contexte à partir de chacun avant d'invoquer le LLM :

```
conversation (dialogue récent)
        +
knowledge (documents récupérés sémantiquement)
        +
facts (faits appris pertinents)
        ▼
   contexte assemblé → LLM
```

## Pages connexes

- [Agents IA](/fr/ai-agents) — l'agent auquel appartient le bloc `memory`.
- [RAG IA](/fr/ai-rag) — le pipeline d'embedding/récupération que la mémoire de connaissances utilise.
- [Chat IA](/fr/ai-chat) — historique de conversation dans l'interface de chat.
- [Vue d'ensemble de l'IA](/fr/ai-overview) — l'écosystème IA complet.

# Intégration MCP

Le Model Context Protocol (MCP) est un standard ouvert pour connecter les assistants IA aux outils et données. Sovrium parle MCP dans **les deux sens** :

- **Mode serveur** — des clients IA externes (Claude Desktop, Claude Code, ChatGPT Dev Mode, Cursor) se connectent à Sovrium et appellent des outils générés : CRUD de table, invocation d'automatisation manuelle, et exécution de modèle d'action.
- **Mode client** — les agents Sovrium appellent des outils hébergés sur des serveurs MCP _externes_ (recherche web, récupération de documents, exécution de code) dans le cadre de leurs flux de travail.

Les deux modes sont configurés indépendamment et servent des rôles opposés.

| Mode    | Contrôlé par     | Où                                 | LLM requis sur Sovrium ?                 |
| ------- | ---------------- | ---------------------------------- | ---------------------------------------- |
| Serveur | Opérateur (env)  | `MCP_ENABLED`, `MCP_TRANSPORT`, …  | Non — le LLM vit chez le client connecté |
| Client  | Auteur de schéma | Bloc `mcp.allowedTools` d'un agent | Oui — `AI_PROVIDER` défini               |

:::callout
**Le mode serveur ne nécessite pas `AI_PROVIDER`.** Lorsque Sovrium est le _serveur_ MCP, le LLM s'exécute chez le client connecté. La plateforme expose uniquement des outils ; elle n'appelle pas de modèle. `AI_PROVIDER` n'est requis que pour le mode client (et le reste de la couche IA).
:::

## Mode serveur

### Activation

Le serveur MCP est **désactivé par défaut**. L'opérateur s'engage via des variables d'environnement ; le serveur ne monte la route `/mcp` que lorsque `MCP_ENABLED=true`.

| Variable                    | Description                                                                                            | Défaut                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------- |
| `MCP_ENABLED`               | Interrupteur principal — monte la route MCP uniquement lorsque `true`.                                 | `false`                     |
| `MCP_TRANSPORT`             | `streamable-http` pour les clients distants, `stdio` pour l'intégration IDE locale.                    | `streamable-http`           |
| `MCP_MOUNT_PATH`            | Préfixe de route lorsque le transport est `streamable-http`.                                           | `/mcp`                      |
| `MCP_AUTH_STRATEGY`         | `oauth2` (lorsque `app.auth` est configuré) ou `token`.                                                | `oauth2` lorsque auth câblé |
| `MCP_TOKEN_ADMIN`           | Jeton bearer accordant le rôle admin (≥32 caractères ; `openssl rand -hex 32`).                        | —                           |
| `MCP_TOKEN_MEMBER`          | Jeton bearer accordant le rôle member (≥32 caractères).                                                | —                           |
| `MCP_TOKEN_VIEWER`          | Jeton bearer accordant le rôle viewer (≥32 caractères).                                                | —                           |
| `MCP_RATE_LIMIT_PER_MINUTE` | Requêtes par jeton par minute.                                                                         | `60`                        |
| `MCP_RATE_LIMIT_PER_DAY`    | Requêtes par jeton par jour.                                                                           | `5000`                      |
| `MCP_AUDIT_ENABLED`         | Journaliser chaque appel d'outil dans `system.ai_tool_calls` + le flux d'activité.                     | `true`                      |
| `MCP_EXPOSE_INTERNALS`      | Exposer les tables auth/system en lecture seule au rôle admin.                                         | `true`                      |
| `MCP_CONFIRM_DESTRUCTIVE`   | Compiler `destructiveHint=true` sur les outils de suppression et les automatisations non idempotentes. | `true`                      |

```bash
MCP_ENABLED=true
MCP_TRANSPORT=streamable-http
MCP_AUTH_STRATEGY=token
MCP_TOKEN_ADMIN=$(openssl rand -hex 32)
MCP_TOKEN_VIEWER=$(openssl rand -hex 32)
```

### Surfaces exposées

Lorsqu'il est monté, le serveur génère des outils à partir de quatre surfaces — toutes encadrées par RBAC et `aiAccess` :

```
/mcp ─── tools/list ───▶ filtré par le rôle connecté
            │
   ┌────────┴───────────────────────────────────┐
   │ 1. Tables utilisateur  {app}_{table}_{op}     │  CRUD
   │ 2. Automatisations manuelles {app}_automation_{name}│ invocation
   │ 3. Modèles d'action    {app}_action_{name}    │  exécution
   │ 4. Internes admin      {app}_auth_*_read/_list │  lecture seule, secrets en liste noire
   └─────────────────────────────────────────────┘
            │
   Audit → system.ai_tool_calls   Limite de débit → par jeton / client_id OAuth
```

### Déclarer les entités éligibles à l'IA

Un auteur de schéma marque une entité comme éligible à l'exposition MCP avec `aiAccess`. Cela déclare l'_intention_ ; l'opérateur doit encore activer le serveur avec `MCP_ENABLED`. `aiAccess` s'applique de manière identique à `app.tables[]`, aux `app.automations[]` à déclenchement manuel, et à `app.actions[]`.

Il prend deux formes — un raccourci booléen ou un objet de configuration riche :

```yaml
# Raccourci booléen — activer avec les valeurs par défaut.
tables:
  - name: contacts
    aiAccess: true
```

```yaml
# Config riche — fournir un objet EST le signal d'activation (pas de champ `enabled`).
tables:
  - name: contacts
    aiAccess:
      description: Customer contacts. Use this when the user asks about people.
      operations: [read, list, create, update]
      fieldExposure: permissioned
      annotations:
        readOnly: false
        destructive: false
```

| Propriété             | Description                                                                                                             |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `description`         | Description d'outil écrite à la main montrée au client IA — le plus grand levier pour orienter le comportement de l'IA. |
| `operations`          | Sous-ensemble de `read`, `list`, `create`, `update`, `delete` à exposer (les tables exposent les cinq par défaut).      |
| `fieldExposure`       | `permissioned` (par défaut — uniquement les champs que le rôle peut lire/écrire), `all`, ou `whitelist`.                |
| `whitelistFields`     | Champs à exposer lorsque `fieldExposure: whitelist` (requis et non vide dans ce mode).                                  |
| `annotations`         | Indices de risque MCP — voir ci-dessous.                                                                                |
| `requireConfirmation` | Forcer `destructiveHint=true` quel que soit le type d'opération (ex. pour les automatisations envoyant des e-mails).    |

### Annotations de risque d'outil

Les annotations se compilent dans les définitions d'outils MCP afin que les clients puissent décider d'approuver automatiquement un appel ou d'exiger une confirmation. Elles correspondent directement à la spécification MCP :

| Annotation    | Indice MCP        | Signification                                                                          |
| ------------- | ----------------- | -------------------------------------------------------------------------------------- |
| `readOnly`    | `readOnlyHint`    | L'outil lit uniquement des données ; sûr à approuver automatiquement.                  |
| `destructive` | `destructiveHint` | Effectue des opérations destructrices ; les clients devraient exiger une confirmation. |
| `idempotent`  | `idempotentHint`  | Appeler deux fois avec les mêmes arguments est sûr (pas d'effets de bord dupliqués).   |
| `openWorld`   | `openWorldHint`   | Atteint l'extérieur de l'application locale (API externe, appel réseau).               |

Des valeurs par défaut raisonnables sont dérivées du type d'opération lorsque les annotations ne sont pas définies.

### Authentification

| Stratégie | Quand                                    | Comment                                                                                           |
| --------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `token`   | Par défaut lorsque `app.auth` est absent | Jetons bearer statiques par rôle (`MCP_TOKEN_ADMIN/MEMBER/VIEWER`). Au moins un doit être défini. |
| `oauth2`  | Par défaut lorsque `app.auth` est câblé  | OAuth 2.1 contre le plugin serveur OAuth de Better Auth.                                          |

Le rôle de la crédentielle connectée pilote le RBAC : un jeton `viewer` ne peut que lire/lister même lorsque l'`aiAccess.operations` d'une entité autorise les écritures. La validation de démarrage rejette `MCP_AUTH_STRATEGY=token` sans jeton défini, et `oauth2` lorsque `app.auth` n'est pas configuré.

### RBAC, audit & limitation de débit

- **RBAC** — les clients MCP sont régis par les mêmes permissions de rôle et règles au niveau des lignes que les sessions humaines. Il n'y a aucun contournement IA.
- **Audit** — chaque appel d'outil est journalisé dans `system.ai_tool_calls` et le flux d'activité lorsque `MCP_AUDIT_ENABLED` est `true` (la valeur par défaut).
- **Limitation de débit** — appliquée par jeton (ou `client_id` OAuth) ; les requêtes hors limite retournent `429` avec des en-têtes de limitation de débit standard.

### Internes admin

Lorsque `MCP_EXPOSE_INTERNALS=true` (la valeur par défaut), le rôle admin obtient des outils en lecture seule sur les tables des schémas `auth` et `system` (`{app}_auth_*_read/_list`, `{app}_system_*_read/_list`), avec les colonnes de secrets en liste noire. Définissez-le à `false` pour retirer tous les outils internes de `tools/list`, même pour les admins.

## Mode client

Les agents Sovrium peuvent consommer des outils depuis des serveurs MCP externes. Le bloc `mcp` d'un agent définit la liste blanche de noms d'outils externes qu'il peut invoquer.

```yaml
agents:
  - name: research-agent
    role: analyst
    systemPrompt: Research topics using approved external tools.
    mcp:
      allowedTools: [web_search, fetch_url]
```

| Propriété          | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| `mcp.allowedTools` | Noms d'outils MCP externes que l'agent est autorisé à utiliser. |

Ceci complète la liste blanche `tools` interne de l'agent : `tools` délimite ce que l'agent peut faire _à l'intérieur_ de Sovrium, tandis que `mcp.allowedTools` délimite quels outils MCP _externes_ il peut appeler.

## Pages connexes

- [Vue d'ensemble de l'IA](/fr/ai-overview) — l'écosystème IA complet et la philosophie de configuration.
- [Agents IA](/fr/ai-agents) — agents qui agissent comme clients MCP.
- [Vue d'ensemble des tables](/fr/tables-overview) — la propriété de table `aiAccess`.
- [Actions](/fr/automation-actions-overview) — modèles d'action exposés comme outils MCP.
- [Rôles & RBAC](/fr/auth-roles-rbac) — les permissions que MCP applique toujours.
- [Variables d'environnement](/fr/env-vars) — référence complète `MCP_*`.

# Gestion des utilisateurs

Sovrium provisionne et gère les utilisateurs sans jamais exiger que vous touchiez directement à la base de données. Le premier administrateur est créé au démarrage (à partir de variables d'environnement, d'un jeton à usage unique ou de la CLI) ; les utilisateurs suivants sont créés, listés, dotés de rôles et invités via l'API d'administration authentifiée. Chaque opération est protégée par RBAC et consignée dans le journal d'audit.

La gestion des utilisateurs n'est disponible que lorsque l'[authentification](/fr/auth-overview) est configurée. Le plugin d'administration est activé automatiquement dès qu'un bloc `auth` existe — il n'y a pas d'indicateur distinct à définir.

## Amorçage de l'administrateur

Le tout premier administrateur ne peut pas être créé par un autre administrateur (il n'en existe aucun encore) ni par auto-inscription (vous ne voulez pas que n'importe qui s'approprie le siège d'administrateur). Sovrium propose **trois chemins d'amorçage complémentaires** pour provisionner ce premier compte sur une base de données vierge.

| Chemin                        | Quand l'utiliser                                   | Mécanisme                                                                                                                                                                                         |
| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Amorçage par variable env** | Déploiements automatisés / IaC                     | Définissez `AUTH_ADMIN_EMAIL` + `AUTH_ADMIN_PASSWORD` (+ `AUTH_ADMIN_NAME` optionnel) ; l'administrateur est créé au premier démarrage.                                                           |
| **Jeton à usage unique**      | Vous ne voulez pas d'identifiants en variables env | Démarrez sans `AUTH_ADMIN_EMAIL` et sans utilisateur ; un jeton hexadécimal de 64 caractères est affiché dans la bannière de démarrage et réclamé une fois via `POST /api/admin/bootstrap/claim`. |
| **CLI**                       | Provisionnement interactif                         | `sovrium admin create <email>` fonctionne sur la base de données configurée (ou le fichier SQLite par défaut) sans `app.yaml` requis.                                                             |

### Amorçage par variable d'environnement (sans configuration)

```bash
AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=SecureP@ssw0rd!
AUTH_ADMIN_NAME=System Administrator   # optional, defaults to "Administrator"
```

Au premier démarrage sur une base de données vierge, le serveur provisionne l'administrateur avec une adresse e-mail vérifiée et lui accorde l'accès à chaque point de terminaison réservé aux administrateurs. Lors des démarrages suivants, ce chemin ne fait rien — il ne crée jamais de doublon et ne modifie jamais un utilisateur existant, même si l'adresse e-mail correspond déjà à un rôle différent. Le succès est consigné **sans** exposer le mot de passe.

| Variable env          | Description                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `AUTH_ADMIN_EMAIL`    | E-mail de l'administrateur d'amorçage. Requis pour le chemin par variable env. Doit être un format d'e-mail valide. |
| `AUTH_ADMIN_PASSWORD` | Mot de passe initial. Requis pour le chemin par variable env. Doit respecter la longueur minimale (8 caractères).   |
| `AUTH_ADMIN_NAME`     | Nom affiché. Optionnel — par défaut `Administrator`.                                                                |

:::callout
**L'amorçage dépend d'un bloc `auth` configuré.** Si `auth` est absent, ou si `AUTH_ADMIN_EMAIL`/`AUTH_ADMIN_PASSWORD` manque, aucun administrateur n'est créé — le serveur démarre sans administrateur. Le chemin par variable env ne fait rien dès qu'un utilisateur existe déjà.
:::

### Amorçage par jeton à usage unique

Lorsque le serveur démarre **sans** `AUTH_ADMIN_EMAIL` défini **et** sans utilisateur dans la base de données, il génère un jeton aléatoire cryptographique de 256 bits, l'affiche une fois dans la bannière de démarrage et accepte une seule réclamation :

```bash
# Token appears in the banner as:
#   → First-admin token (POST /api/admin/bootstrap/claim): <64-hex-token>

curl -X POST http://localhost:3000/api/admin/bootstrap/claim \
  -H 'Content-Type: application/json' \
  -d '{ "token": "<64-hex-token>", "email": "admin@example.com", "password": "SecureP@ssw0rd!", "name": "Admin" }'
```

Propriétés de sécurité :

- Seul le hachage SHA-256 du jeton est conservé ; le texte en clair est affiché sur stdout exactement une fois et n'est jamais consigné.
- Le jeton expire après **1 heure** et peut être réclamé **une seule fois** — les rejeux renvoient `401`.
- Dès qu'un administrateur existe, la route renvoie **404** : la fenêtre d'amorçage est fermée, et même un jeton valide divulgué ne peut pas la rouvrir.

C'est le chemin qui rend possible « lancer le binaire sur un serveur vierge avec seulement `DATABASE_URL` défini, ouvrir l'URL, construire l'application en direct ». Voir [Infrastructure de base de données](/fr/database-infrastructure) pour la base de données sans configuration qui l'accompagne.

## Création et gestion des utilisateurs

Une fois qu'un administrateur existe, toutes les opérations de cycle de vie des utilisateurs suivantes passent par l'API d'administration. Chaque point de terminaison exige une session d'administrateur authentifiée — les requêtes non authentifiées renvoient `401`, les sessions non administrateur renvoient `403`.

| Opération               | Point de terminaison                       | Notes                                                                                                                 |
| ----------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Créer un utilisateur    | `POST /api/auth/admin/create-user`         | L'ingénieur choisit le mot de passe ; **aucun e-mail** n'est envoyé. Renvoie `201`.                                   |
| Lister les utilisateurs | `GET /api/auth/admin/list-users`           | Paginé (`limit`/`offset`), renvoie des métadonnées de comptage, prend en charge la recherche par e-mail ou nom.       |
| Obtenir un utilisateur  | `GET /api/auth/admin/get-user/:id`         | Détail complet incl. rôle, statut de bannissement, indicateur d'e-mail vérifié. `404` pour les identifiants inconnus. |
| Définir le rôle         | `POST /api/auth/admin/set-role`            | Attribue `admin` / `member` / `viewer` (ou tout [rôle personnalisé](/fr/auth-roles-rbac)).                            |
| Définir le mot de passe | `POST /api/auth/admin/set-user-password`   | Réinitialise le mot de passe d'un utilisateur de manière administrative.                                              |
| Lister les sessions     | `GET /api/auth/admin/list-user-sessions`   | [Sessions](/fr/auth-sessions) actives pour un utilisateur.                                                            |
| Révoquer une session    | `POST /api/auth/admin/revoke-user-session` | Force la déconnexion d'une session spécifique.                                                                        |
| Usurper l'identité      | `POST /api/auth/admin/impersonate-user`    | Démarre/arrête l'usurpation d'identité pour les flux de support.                                                      |

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
```

:::callout
**La validation est appliquée côté serveur.** Create-user renvoie `400` pour un e-mail manquant/mal formé ou un mot de passe manquant, et `422` lorsque l'e-mail existe déjà. Les rôles attribués doivent être l'un des rôles déclarés de l'application — voir [Rôles & RBAC](/fr/auth-roles-rbac).
:::

## Attribution de rôle

Sovrium fournit trois rôles par défaut — `admin`, `member`, `viewer` — et prend en charge des rôles personnalisés déclarés dans le bloc `auth`. Les nouveaux utilisateurs reçoivent `auth.defaultRole` (par défaut `member`) sauf si un rôle explicite est fourni à la création. Le premier administrateur d'amorçage est toujours créé avec le rôle `admin` et une adresse e-mail vérifiée.

Les rôles pilotent chaque décision d'autorisation dans la plateforme : les [permissions](/fr/table-permissions) de table, l'accès par champ, l'accès aux pages et l'API d'administration elle-même. Voir [Rôles & RBAC](/fr/auth-roles-rbac) pour le modèle de rôle complet et la matrice de permissions par champ.

## Flux d'invitation

Le point de terminaison `create-user` exige que l'administrateur choisisse le mot de passe du client et n'envoie aucun e-mail — ce qui ne convient pas à un véritable accueil de clients. Le **flux d'invitation sans mot de passe** parallèle comble cette lacune : l'administrateur émet une invitation avec `{ email, name, role }` (sans mot de passe), Sovrium envoie par e-mail un lien à usage unique, et le client définit son propre mot de passe et atterrit authentifié.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  invitationTokenExpiry: '72h' # default lifetime; accepts '30s' / '15m' / '72h' / '7d' / ms
  emailTemplates:
    invitation:
      subject: 'You are invited to join, $name'
      text: |
        Hi $name,
        $inviterName invited you to join.
        Set your password: $url
        This invitation expires in 72 hours.
```

| Point de terminaison                     | Comportement                                                                                                                                                                                                                                 |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/auth/admin/invite-user`       | Accepte `{ email, name, role }` (sans mot de passe). Renvoie `200` avec `{ user, invitationSent: true }`. `401`/`403` pour non authentifié/non administrateur ; `422` lorsque l'e-mail correspond déjà à un utilisateur entièrement intégré. |
| `POST /api/auth/admin/accept-invitation` | Sous-tend la page publique `/accept-invitation?token=...`. Le client définit un mot de passe et atterrit dans une session authentifiée.                                                                                                      |

Les jetons d'invitation réutilisent la table `auth.verification` (la même forme que Better Auth utilise pour la réinitialisation de mot de passe), expirent après `invitationTokenExpiry` (par défaut 72h) et sont à usage unique — les rejeux renvoient `400`/`410`. Variables de substitution d'e-mail : `$name`, `$url`, `$email`, `$inviterName`. `auth.allowSignUp: false` ne **bloque pas** les invitations — la création d'utilisateur pilotée par l'administrateur est toujours disponible lorsque l'authentification est configurée.

:::callout
**L'accueil est découplé de l'attribution d'accès.** Inviter un utilisateur crée le compte mais ne lui accorde aucune portée de locataire. Relier un utilisateur à un accès aux données est une étape distincte via l'API standard des enregistrements — un administrateur peut inviter d'abord et attribuer ensuite, ou inversement.
:::

## Pages connexes

- [Aperçu de l'authentification](/fr/auth-overview) — stratégies, configuration, le bloc `auth`.
- [Rôles & RBAC](/fr/auth-roles-rbac) — modèle de rôle et permissions par champ.
- [Sessions](/fr/auth-sessions) — durée de vie des sessions, révocation, multi-appareils.
- [Tableau de bord d'administration](/fr/admin-dashboard) — API de lecture de niveau opérateur sur les utilisateurs, tables, automatisations.
- [Surveillance de l'activité](/fr/activity-monitoring) — piste d'audit des actions des utilisateurs et des administrateurs.
- [Infrastructure de base de données](/fr/database-infrastructure) — la base de données sans configuration que l'amorçage sans configuration accompagne.
- [Variables d'environnement](/fr/env-vars) — référence complète des variables env incl. `AUTH_ADMIN_*`.

# Surveillance de l'activité

Sovrium enregistre chaque action significative dans l'application — création/mise à jour/suppression d'enregistrements, événements d'authentification et opérations administratives — dans un journal d'activité à l'échelle du système. Le journal est interrogeable via une API authentifiée avec filtrage et pagination, offrant aux opérateurs et aux auditeurs un endroit unique pour répondre à « qui a fait quoi, et quand ».

Il s'agit de la surface de lecture destinée à l'opérateur sur le magasin d'événements canonique du journal d'audit de la plateforme. Chaque entrée est immuable et survit aux lignes qu'elle référence lorsque la conformité l'exige (un événement `account.deletion.purged` survit à l'effacement de l'utilisateur qui l'a déclenché — voir [GDPR & Confidentialité](/fr/gdpr-privacy)).

## Ce qui est suivi

| Catégorie                         | Exemples                                                                                                  |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **CRUD sur enregistrements**      | `create`, `update`, `delete`, `restore` sur tout enregistrement de table.                                 |
| **Événements d'authentification** | Connexion, inscription, réinitialisation de mot de passe, révocation de session.                          |
| **Actions administratives**       | Création d'utilisateur, changements de rôle, bannissements, publications de schéma, suppressions forcées. |
| **Événements système**            | Migrations, planification et purge de suppression de compte.                                              |

Chaque entrée porte l'action, la table et l'identifiant d'enregistrement concernés (le cas échéant), un horodatage et l'utilisateur agissant (id, nom, e-mail). La référence à l'acteur est liée par clé étrangère avec `ON DELETE SET NULL`, de sorte qu'une entrée d'audit reste un enregistrement de conformité valide même après l'effacement du compte de l'acteur.

## Interrogation du journal d'activité

L'API d'activité est protégée par administration. Les requêtes non authentifiées renvoient `401` ; les sessions non administrateur renvoient `403`.

```
GET /api/activity?page=1&pageSize=20&table=orders&action=update
```

```json
{
  "activities": [
    {
      "id": "act_123",
      "action": "update",
      "tableName": "orders",
      "recordId": 456,
      "createdAt": "2025-01-15T10:30:00Z",
      "user": { "id": "1", "name": "Alice", "email": "alice@example.com" }
    }
  ],
  "pagination": { "total": 150, "page": 1, "pageSize": 20, "totalPages": 8 }
}
```

| Point de terminaison            | Description                                        |
| ------------------------------- | -------------------------------------------------- |
| `GET /api/activity`             | Liste paginée et filtrable des entrées d'activité. |
| `GET /api/activity/:activityId` | Détail complet pour une seule entrée d'activité.   |

### Paramètres de requête

| Paramètre  | Type   | Description                                                     |
| ---------- | ------ | --------------------------------------------------------------- |
| `page`     | number | Numéro de page (par défaut : `1`).                              |
| `pageSize` | number | Entrées par page.                                               |
| `table`    | string | Filtre sur une seule table par nom.                             |
| `action`   | string | Filtre par action (`create`, `update`, `delete`, `restore`, …). |

:::callout
**Journal d'activité vs historique d'enregistrement.** Le journal d'activité est un flux inter-tables, à l'échelle du système, répondant à « ce qui s'est passé dans l'application ». Pour l'ensemble de modifications avant/après au niveau du champ d'un seul enregistrement, utilisez l'[Historique des enregistrements](/fr/record-history) — il capture le diff de chaque édition individuelle. Les deux se complètent : l'activité pour la largeur, l'historique pour la profondeur.
:::

## Conservation

Les entrées d'activité sont conservées conformément à la politique de conservation de la plateforme. Les lignes sources supprimées en douceur vieillissent elles-mêmes selon l'horizon `ECO_RETENTION_PURGE_DAYS` (voir [Écoconception](/fr/ecoconception)), mais les entrées d'audit requises pour la conformité — notamment les enregistrements d'effacement — sont préservées indépendamment des lignes qu'elles décrivent.

## Usage de conformité

La même forme renvoyée aux administrateurs est renvoyée aux auditeurs, de sorte que la documentation de revue SOC2 / GDPR reflète exactement ce que voient les opérateurs. Combiné au magasin d'événements canonique immuable, le journal d'activité fournit la « piste d'audit de l'effacement » requise lors de l'honneur d'une demande de [droit à l'oubli](/fr/gdpr-privacy) : la suppression est elle-même consignée, avec la référence à l'acteur null-ifiée une fois le compte purgé.

## Pages connexes

- [Historique des enregistrements](/fr/record-history) — diffs avant/après au niveau du champ par enregistrement.
- [Suppression en douceur](/fr/records-soft-delete) — suppressions récupérables et la pierre tombale `deleted_at`.
- [Tableau de bord d'administration](/fr/admin-dashboard) — API de lecture opérateur sur le reste de la plateforme.
- [GDPR & Confidentialité](/fr/gdpr-privacy) — enregistrements d'effacement et la piste d'audit de la suppression.
- [Gestion des utilisateurs](/fr/user-management) — les actions administratives qui produisent les entrées d'activité.

# Analytique

Sovrium fournit un moteur d'analytique intégré et propriétaire. Il suit les vues de pages, les sessions, les référents, les campagnes UTM et les répartitions par appareil sur un modèle d'événements unifié unique — sans cookies, sans empreinte digitale et sans services externes. Toutes les données restent sur votre serveur, ce qui le rend compatible GDPR par défaut.

L'analytique est configurée via la propriété `analytics` dans le schéma de l'application. Lorsqu'elle est activée, Sovrium injecte un script de suivi léger (~1 Ko) qui enregistre les vues de pages via `navigator.sendBeacon()` vers `POST /api/analytics/collect`.

## Configuration

`analytics` accepte un raccourci booléen ou un objet pour un contrôle fin.

```yaml
# Boolean shorthand — enable with all defaults
analytics: true

# Object form — override individual settings, keep defaults for the rest
analytics:
  enabled: true
  retentionDays: 365
  excludedPaths:
    - /admin/*
    - /api/*
  respectDoNotTrack: true
  sessionTimeout: 30
```

| Propriété           | Par défaut | Plage / Valeurs     | Description                                                                                            |
| ------------------- | ---------- | ------------------- | ------------------------------------------------------------------------------------------------------ |
| `enabled`           | `true`     | boolean             | Active/désactive le suivi analytique.                                                                  |
| `retentionDays`     | `365`      | `1`–`730`           | Jours de conservation des données analytiques. Les lignes plus anciennes sont automatiquement purgées. |
| `excludedPaths`     | `[]`       | string[] (glob)     | Motifs d'URL exclus du suivi (par ex. `/admin/*`, `/api/*`).                                           |
| `respectDoNotTrack` | `true`     | boolean             | Honore l'en-tête de navigateur `DNT:1` — ces visiteurs ne sont pas suivis.                             |
| `sessionTimeout`    | `30`       | `1`–`120` (minutes) | Période d'inactivité après laquelle une nouvelle session commence.                                     |

:::callout
**Booléen vs objet.** `analytics: true` active les valeurs par défaut (conservation de 365 jours, DNT respecté, sessions de 30 minutes). Utilisez la forme objet pour remplacer des réglages spécifiques tout en conservant les valeurs par défaut pour le reste. `analytics: false` (ou l'omission de la propriété) désactive l'analytique — aucun point de terminaison n'est monté.
:::

## Modèle d'événements unifié

Tous les événements analytiques — vues de pages, appels de suivi personnalisés et sources futures — partagent une table `system.analytics_events` unique avec une colonne discriminante `event_type`. Cela suit le modèle standard de l'industrie utilisé par PostHog, Mixpanel et Amplitude, mais auto-hébergé sans dépendance externe (voir DEC-019).

```
system.analytics_events
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid()
  app_name        TEXT NOT NULL
  event_type      TEXT NOT NULL          -- 'page_view' | 'track' | extensible
  event_name      TEXT NOT NULL          -- path for page_view, custom name for track
  org_id          TEXT                   -- organization scope (nullable pre-auth)
  timestamp       TIMESTAMPTZ NOT NULL DEFAULT now()
  visitor_hash    TEXT NOT NULL          -- privacy-preserving visitor identifier
  session_hash    TEXT NOT NULL          -- privacy-preserving session identifier
  properties      JSONB NOT NULL DEFAULT '{}'
```

| Type d'événement | `event_name`                    | Charge utile `properties`                                                                           |
| ---------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
| `page_view`      | Le chemin de la page            | `path`, `referrer`, `utm_*`, `device_type`, `browser_*`, `os_*`, `screen_*`, `language`, `country`. |
| `track`          | Le nom d'événement personnalisé | Métadonnées clé-valeur arbitraires provenant d'une action d'automatisation ou de l'API de suivi.    |

Les colonnes promues (`event_type`, `event_name`, `org_id`, `visitor_hash`, `session_hash`, `timestamp`) pilotent des requêtes `WHERE`/`GROUP BY` efficaces ; tout le reste vit dans JSONB. Les mêmes primitives de confidentialité — hachage côté serveur du visiteur/de la session (SHA-256, aucune donnée personnelle stockée), respect de DNT et l'horizon de conservation — s'appliquent uniformément à chaque type d'événement, et chaque ligne est limitée à l'organisation pour l'isolation multi-locataires.

:::callout
**Parité des moteurs de stockage.** La table d'événements unifiée est exercée à la fois par les chemins de requête PostgreSQL (`->>` sur `system.analytics_events`) et [SQLite](/fr/database-infrastructure) (`json_extract` sur `system_analytics_events`). Les deux produisent des formes de réponse identiques pour collect, la série temporelle de vue d'ensemble, les pages principales, les référents/UTM et la répartition par appareil.
:::

## Interrogation de l'analytique

L'analytique agrégée est exposée via des points de terminaison de lecture protégés par administration. Inspectez les événements bruts pour le débogage ou des tableaux de bord personnalisés.

| Point de terminaison           | Renvoie                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------ |
| `POST /api/analytics/collect`  | Point de terminaison d'ingestion public sollicité par le script de suivi.            |
| `GET /api/analytics/overview`  | Totaux + série temporelle quotidienne par paliers.                                   |
| `GET /api/analytics/pages`     | Pages principales par nombre de vues.                                                |
| `GET /api/analytics/referrers` | Répartition des référents et des campagnes UTM.                                      |
| `GET /api/analytics/devices`   | Répartition par type d'appareil et navigateur.                                       |
| `GET /api/analytics/campaigns` | Analyse des campagnes UTM.                                                           |
| `GET /api/analytics/events`    | Inspection d'événements bruts **réservée aux administrateurs** (paginée, filtrable). |

### Inspection des événements bruts

`GET /api/analytics/events` offre une visibilité au niveau de la ligne sur le flux unifié — complétant les points de terminaison agrégés. Il est réservé aux administrateurs et prend en charge le filtrage par `event_type`, `event_name` et plage de dates.

```
GET /api/analytics/events?event_type=track&limit=50&offset=0&from=2026-01-01&to=2026-04-15
```

| Paramètre     | Description                                      |
| ------------- | ------------------------------------------------ |
| `event_type`  | Filtre par type (`page_view`, `track`, …).       |
| `event_name`  | Nom d'événement à correspondance exacte.         |
| `from` / `to` | Plage de dates ISO 8601 (inclusive).             |
| `limit`       | Résultats maximum (par défaut `50`, max `1000`). |
| `offset`      | Décalage de pagination (par défaut `0`).         |

## Confidentialité & Conformité

- **Sans cookies, sans empreinte digitale.** Les visiteurs sont identifiés par un hachage SHA-256 calculé côté serveur ; aucun identifiant côté client n'est stocké.
- **DNT respecté par défaut.** Les visiteurs envoyant `DNT:1` ne sont pas suivis lorsque `respectDoNotTrack` est activé.
- **Toutes les données sont locales.** Aucun service tiers et aucun appel externe — l'analytique ne quitte jamais votre serveur.
- **Conservation bornée.** Les données plus anciennes que `retentionDays` sont automatiquement purgées, s'alignant sur la posture de minimisation des données de la plateforme (voir [Écoconception](/fr/ecoconception)).

## Pages connexes

- [Tableau de bord d'administration](/fr/admin-dashboard) — API de lecture opérateur sur l'ensemble de la plateforme.
- [Surveillance de l'activité](/fr/activity-monitoring) — piste d'audit des actions des utilisateurs et des administrateurs.
- [Automatisations](/fr/automations-overview) — émettez des événements `track` personnalisés depuis les actions d'automatisation.
- [Écoconception](/fr/ecoconception) — conservation des données et empreinte environnementale.
- [Infrastructure de base de données](/fr/database-infrastructure) — la parité SQLite/PostgreSQL derrière la table d'événements.

# Tableau de bord d'administration

Sovrium fournit un tableau de bord d'administration d'application intégré : une famille de points de terminaison d'API en lecture seule qui donnent aux opérateurs et aux auditeurs une surface unique et cohérente sur la santé et l'inventaire de l'application en cours d'exécution. Chaque point de terminaison est protégé par RBAC, émet un événement de journal d'audit canonique et renvoie `404` (jamais `403`) en cas d'accès non autorisé pour déjouer l'énumération.

Le tableau de bord est une surface de **lecture**. Les opérations de mutation — création d'utilisateurs, changement de rôles, publication de schéma — vivent dans leurs propres points de terminaison ([Gestion des utilisateurs](/fr/user-management)) ; le tableau de bord reflète l'état, il ne le modifie pas. Trois publics partagent exactement les mêmes formes de réponse : **administrateurs** (décisions de détail), **opérateurs** (rapports d'incident, passations d'astreinte) et **auditeurs** (documentation de revue SOC2 / GDPR).

## Deux formes de réponse

Chaque point de terminaison du tableau de bord adopte l'une des deux formes, de sorte que le contrat se généralise proprement à travers les domaines.

| Forme              | Modèle de point de terminaison     | Corps                                                                                                                                                 |
| ------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Vue d'ensemble** | `GET /api/admin/{domain}/overview` | Compteurs agrégés tenant compte de la période (`totals`), une série temporelle par paliers (`series`) et des métriques de santé dérivées. Non paginé. |
| **Liste**          | `GET /api/admin/{domain}`          | Éléments paginés par curseur, chacun portant un bloc `_admin` de niveau opérateur avec `metadata` (comptes, horodatages de dernière activité).        |

Les points de terminaison de vue d'ensemble acceptent un préréglage de période partagé (`24h` \| `7d` \| `30d`) via `resolvePeriodWindow()` ; les points de terminaison de liste acceptent la pagination par curseur, la recherche en texte libre et `?include_deleted=true`.

## Surface des points de terminaison

| Domaine             | Point(s) de terminaison                                                  | Renvoie                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Config**          | `GET /api/admin/config/version`                                          | Version en cours d'exécution, commit de build, runtime de base de données actif, version de Bun, heure de démarrage du processus.            |
| **Automatisations** | `GET /api/admin/automations/overview`, `GET /api/admin/automations/runs` | Totaux d'exécutions, nombre d'échecs, `success_rate`, séries par paliers ; liste d'exécutions paginée.                                       |
| **Utilisateurs**    | `GET /api/admin/users/overview`                                          | Total des utilisateurs, récemment actifs, nouvelles inscriptions pour la période, distribution des rôles, séries d'inscriptions/de sessions. |
| **Tables**          | `GET /api/admin/tables/overview`                                         | `rowCount`, `softDeletedCount`, `lastWriteAt`, `writesInPeriod` par table, totaux, séries d'écritures.                                       |
| **Buckets**         | `GET /api/admin/buckets`, `GET /api/admin/buckets/overview`              | Liste de buckets paginée par curseur avec filtre par fournisseur ; vue d'ensemble du quota/de l'utilisation.                                 |
| **Formulaires**     | `GET /api/admin/forms`, `GET /api/admin/forms/:formName`                 | Formulaires configurés avec nombre de soumissions et horodatages de dernière soumission ; détail par formulaire.                             |

```bash
# Version reflection — the smallest read endpoint, the cross-cutting shake-down test
curl -H 'Cookie: <admin session>' http://localhost:3000/api/admin/config/version

# Period-scoped overview
curl -H 'Cookie: <admin session>' 'http://localhost:3000/api/admin/tables/overview?period=7d'

# Cursor-paginated list with search
curl -H 'Cookie: <admin session>' 'http://localhost:3000/api/admin/forms?search=contact&limit=20'
```

:::callout
**Les préréglages de période sont partagés, pas par point de terminaison.** Les points de terminaison de vue d'ensemble réutilisent un seul `periodPresetSchema` (`24h` \| `7d` \| `30d`) et un seul assistant `resolvePeriodWindow()` plutôt que de redéclarer l'énumération, de sorte qu'une fenêtre signifie la même chose partout. Les domaines clairsemés (inscriptions d'utilisateurs) et denses (exécutions d'automatisation) partagent le corps `totals + series` identique.
:::

## Garanties transversales

Chaque point de terminaison du tableau de bord hérite des mêmes primitives de sécurité et d'observabilité :

| Garantie                                | Comportement                                                                                                                                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **RBAC**                                | Un middleware à trois niveaux protège chaque route en fonction du rôle de l'appelant.                                                                                                         |
| **Anti-énumération**                    | L'accès non autorisé renvoie **404**, jamais `403` — l'espace des id est indevinable et l'existence de la route est inobservable. Voir [Durcissement de la sécurité](/fr/security-hardening). |
| **Journal d'audit**                     | Chaque appel émet un événement canonique (par ex. `form.detail.queried`) exactement une fois. Voir [Surveillance de l'activité](/fr/activity-monitoring).                                     |
| **OpenAPI**                             | Les routes sont déclarées via l'assistant partagé `adminRoute`, de sorte que la surface est documentée et vérifiée en types.                                                                  |
| **Contrat de compatibilité ascendante** | `?include_deleted=true` s'analyse sans `400` afin que les auditeurs obtiennent une interface stable au fur et à mesure que la visibilité des lignes supprimées arrive.                        |

## Points de terminaison frères (pas le tableau de bord)

Certaines lectures pertinentes pour l'opérateur vivent en dehors de la famille du tableau de bord `/api/admin/{domain}` parce qu'elles le précèdent ou appartiennent à un autre sous-système :

- **Enregistrements par utilisateur** (id, e-mail, nom) → `GET /api/auth/admin/list-users`. Voir [Gestion des utilisateurs](/fr/user-management).
- **Analytique de trafic agrégée** → `GET /api/analytics/overview` et frères. Voir [Analytique](/fr/analytics).
- **Flux d'activité à l'échelle du système** → `GET /api/activity`. Voir [Surveillance de l'activité](/fr/activity-monitoring).

## Pages connexes

- [Gestion des utilisateurs](/fr/user-management) — les opérations administratives de mutation que le tableau de bord reflète.
- [Surveillance de l'activité](/fr/activity-monitoring) — le flux du journal d'audit dans lequel chaque appel du tableau de bord écrit.
- [Analytique](/fr/analytics) — la surface de lecture de l'analytique de trafic.
- [Durcissement de la sécurité](/fr/security-hardening) — RBAC, 404-pas-403, limitation de débit.
- [Aperçu des buckets](/fr/buckets-overview) — les buckets de stockage exposés par les points de terminaison de buckets.
- [Aperçu des formulaires](/fr/forms-overview) — les formulaires exposés par les points de terminaison de formulaires.

# Migrations de schéma

Sovrium fait évoluer le schéma de votre base de données automatiquement. Il compare la configuration de l'application à la base de données physique, génère le SQL approprié et l'exécute à l'intérieur d'une transaction — sans fichiers de migration écrits à la main. Le système valide les sommes de contrôle pour détecter la dérive, prend en charge le retour arrière pour récupérer après des échecs et enregistre une piste d'audit complète de chaque changement.

Il existe deux points de déclenchement : l'**évolution au démarrage** (la configuration a changé depuis le dernier démarrage) et la **migration en direct à la publication** (un brouillon publié via l'API). Les changements additifs s'appliquent en direct sans redémarrage ; les changements destructifs sont reportés à un redémarrage par sécurité.

## Évolution automatique du schéma

Lorsque la configuration diffère de la base de données, Sovrium détecte le changement et applique la migration automatiquement — le tout dans une transaction afin qu'un échec partiel revienne proprement en arrière.

Changements structurels pris en charge :

```yaml
# Before
tables:
  - id: 1
    name: users
    fields:
      - { id: 1, name: email, type: email }

# After — add a phone field; Sovrium generates ADD COLUMN
tables:
  - id: 1
    name: users
    fields:
      - { id: 1, name: email, type: email }
      - { id: 2, name: phone, type: single-line-text }
```

| Classe de changement   | Exemples                                                                    |
| ---------------------- | --------------------------------------------------------------------------- |
| **Structurel**         | Ajouter/supprimer/renommer des champs et des tables.                        |
| **Propriété de champ** | Changement de type, contrainte, valeur par défaut, options, bascule requis. |
| **Index & vue**        | Ajouter/supprimer des index ; créer/mettre à jour des vues enregistrées.    |

Les ID de champ sont l'ancre de renommage — gardez l'`id` stable et changez le `name` pour renommer une colonne sans perdre de données. Voir [Index & contraintes de table](/fr/table-indexes-constraints) et [Validation](/fr/table-validation) pour les propriétés par champ que les migrations suivent.

## Validation de somme de contrôle

Sovrium calcule une empreinte du schéma pour éviter le travail de migration inutile et détecter la dérive.

1. À la première migration, Sovrium calcule une **somme de contrôle SHA-256** du schéma et la stocke.
2. À chaque démarrage suivant, il compare la somme de contrôle du schéma actuel à celle stockée.
3. **Inchangé** → le serveur démarre rapidement, sans exécuter de migration.
4. **Changé** → Sovrium exécute les migrations nécessaires et enregistre la nouvelle somme de contrôle.

Cela rend les redémarrages peu coûteux lorsque rien n'a changé et garantit que la base de données correspond au schéma déclaré lorsque quelque chose a changé.

## Migration en direct à la publication

Publier un brouillon via l'API d'administration en fait le schéma en direct **sans redémarrage** — et pour les changements additifs de structure de données, la table ou colonne physique est créée immédiatement sur le serveur en cours d'exécution.

| Changement                                           | Appliqué                                                                                                        | Pourquoi                                                                                                                                                        |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Additif** (ajouter table, ajouter colonne)         | **En direct** — la table/colonne existe sur le serveur en cours d'exécution et est immédiatement interrogeable. | Ajouter de la structure ne peut pas perdre de données ; sûr à appliquer sur du trafic en direct.                                                                |
| **Destructif** (supprimer/renommer colonne ou table) | **Reporté au redémarrage**                                                                                      | Une suppression/renommage sur un serveur en cours d'exécution avec du trafic risque une perte de données irréversible sans une action délibérée de l'opérateur. |

Le pipeline de publication exécute **migrer-avant-permuter** : `validate → vérification de concurrence optimiste → appliquer le DDL additif → insérer la ligne de version → permuter l'application en direct → réenregistrer les routes`. Comme le DDL s'exécute avant la permutation des routes, les routes `/api/tables/:slug/records` nouvellement enregistrées ne pointent jamais vers une table qui n'existe pas encore.

:::callout
**L'additif s'applique en direct, le destructif attend un redémarrage** (DEC-024). Cela assouplit l'ancienne règle « éditer la config → redémarrer → tables prêtes » uniquement pour le cas additif sûr. Une migration en direct échouée **interrompt la publication** — la version n'est pas avancée et l'application en direct n'est pas permutée, de sorte qu'une migration cassée ne laisse jamais les routes pointer vers une table manquante.
:::

## Retour arrière

Lorsqu'une migration échoue, la transaction revient en arrière et le schéma est laissé dans son état cohérent précédent. Le retour arrière est actuellement disponible **par programmation** ; des commandes CLI de retour arrière dédiées (`migrate:rollback`, `--to <version>`, `--force`) sont prévues. Le registre des versions enregistre chaque version de schéma appliquée, de sorte qu'un instantané de version antérieure peut être réappliqué.

## Piste d'audit

Le système de migration enregistre, pour chaque migration :

- Horodatage de la migration
- Numéro de version du schéma
- Somme de contrôle du schéma (SHA-256)
- Instantané complet du schéma
- Opérations de retour arrière et raison

Cette piste d'audit est la source de vérité pour « quel schéma a produit cette base de données » — les auditeurs la recoupent avec le [journal d'activité](/fr/activity-monitoring) pour corréler les changements de données avec la version de schéma en vigueur à ce moment-là.

## Gestion des erreurs

Les migrations échouent de manière bruyante et sûre. Chacun de ces scénarios interrompt avant ou pendant l'exécution et annule tout travail partiel :

| Scénario                    | Comportement                                                                     |
| --------------------------- | -------------------------------------------------------------------------------- |
| **Schéma invalide**         | Les erreurs de validation sont révélées avant le démarrage de toute migration.   |
| **Échec de migration**      | Une erreur d'exécution SQL annule la transaction.                                |
| **Erreur de connexion**     | L'indisponibilité de la base de données interrompt l'exécution.                  |
| **Violation de contrainte** | Un échec de clé étrangère ou de contrainte d'unicité provoque un retour arrière. |

## Pages connexes

- [Infrastructure de base de données](/fr/database-infrastructure) — les moteurs SQLite/PostgreSQL que les migrations ciblent.
- [Index & contraintes de table](/fr/table-indexes-constraints) — les définitions d'index et de contraintes que les migrations appliquent.
- [Validation](/fr/table-validation) — les règles au niveau du champ et de la table suivies au fil de l'évolution.
- [Surveillance de l'activité](/fr/activity-monitoring) — le flux d'audit corrélé aux versions de schéma.
- [Tableau de bord d'administration](/fr/admin-dashboard) — `config/version` rapporte le runtime et le build actifs.

# Infrastructure de base de données

Sovrium fonctionne sur une base de données SQLite embarquée avec **zéro configuration** et passe à PostgreSQL en définissant une seule variable d'environnement. L'intégralité du runtime — migrations, bundles client, le moteur CSS, les configurations d'exemple — est regroupée dans un seul binaire autonome, et un cache de rendu de page statique maintient le CPU du serveur frugal. Cette page documente la couche de persistance et de distribution qui rend possible « lancer le binaire, ouvrir l'URL ».

## Valeur par défaut SQLite sans configuration

Lorsqu'aucune `DATABASE_URL` n'est définie, Sovrium résout le dialecte `sqlite`, crée `./.sovrium/database.db`, applique automatiquement l'ensemble de migrations SQLite au premier démarrage et sert toute la surface de base — schéma, authentification, CRUD d'enregistrements, migrations et formulaires. La bannière de démarrage affiche `Database: SQLite (<absolute path>)`.

Cela reflète la philosophie frugale-par-défaut de la plateforme (jumeau de `STORAGE_PROVIDER` et de la famille `ECO_*`) : l'opérateur opte **pour** PostgreSQL en définissant `DATABASE_URL`, jamais l'inverse.

## PostgreSQL lorsqu'il est configuré

Définissez `DATABASE_URL` sur une URL `postgresql://` et Sovrium résout le dialecte `postgres`, se connecte, applique l'ensemble de migrations PostgreSQL et affiche `Database: PostgreSQL`. Aucun fichier SQLite n'est créé. Ce chemin est identique octet pour octet aux déploiements PostgreSQL préexistants.

Une source unique de vérité — `parseDatabaseDialectConfig()` — discrimine par schéma l'unique variable `DATABASE_URL` :

| Valeur de `DATABASE_URL`                 | Se résout en                                                                          |
| ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `postgres://…` / `postgresql://…`        | PostgreSQL à cette URL.                                                               |
| _non définie / vide_                     | SQLite à `./.sovrium/database.db` (la valeur par défaut sans configuration).          |
| `file:./x.db` / `file:/abs.db`           | SQLite au chemin résolu.                                                              |
| `sqlite:./x.db` / `sqlite:///abs.db`     | Alias SQLite pour le même fichier sur disque.                                         |
| `:memory:`                               | SQLite éphémère (niveau dialecte uniquement — pas une cible de déploiement complète). |
| tout le reste (chemin nu, `mysql://`, …) | Lève `Unsupported DATABASE_URL scheme: …` au démarrage (échec bruyant).               |

:::callout
**`SQLITE_PATH` a été supprimé** (changement cassant pré-1.0, sans pont de compatibilité). L'emplacement du fichier SQLite est désormais choisi exclusivement via `DATABASE_URL` au moyen des schémas `file:` / `sqlite:`. Un chemin de système de fichiers nu sans schéma (`DATABASE_URL=./database.db`) est **rejeté** au démarrage — préfixez-le avec `file:`.
:::

Le dialecte sélectionné pilote le client Drizzle (`bun:sqlite` ou `bun:sql`), l'ensemble de migrations, le fournisseur d'adaptateur Better Auth et l'étiquette `runtime` destinée à l'opérateur de `GET /api/admin/config/version` (`sqlite-aio` sur SQLite, `postgres` sur PostgreSQL).

### Dégradation gracieuse

Le mode SQLite prend en charge le sous-ensemble de base. Les fonctionnalités avancées réservées à PostgreSQL — notamment la recherche sémantique RAG pgvector — renvoient un `501 { error: 'requires-postgres' }` typé plutôt que de planter. Passez à PostgreSQL pour les débloquer ; aucune modification de code requise.

## Répertoire de données embarqué

Tout l'état local vit sous un seul répertoire de données relocalisable.

| Variable env       | Par défaut             | Description                                                                                                                                                  |
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DATABASE_URL`     | _non définie → SQLite_ | Sélecteur de moteur + emplacement de base de données.                                                                                                        |
| `SOVRIUM_DATA_DIR` | `./.sovrium`           | Racine du fichier de base de données SQLite, des fichiers de verrou et du stockage local. Relocalisez tout le répertoire de données avec une seule variable. |

Le `./.sovrium/database.db` par défaut se trouve sous ce répertoire de données ; le répertoire parent est créé automatiquement au premier démarrage.

## Cache de rendu de page statique

Sovrium rend les pages côté serveur à chaque requête. Pour une page dont le HTML ne dépend pas de l'état par requête (une page marketing, à propos ou tarification), c'est du CPU gaspillé. Le cache de rendu en mémoire rend une telle page une fois et la sert depuis la mémoire lors des requêtes anonymes suivantes, en sautant entièrement `renderToString` — un gain d'écoconception et de latence.

| Variable env     | Par défaut | Options       | Description                                                                                                                |
| ---------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `ECO_PAGE_CACHE` | `on`       | `on` \| `off` | Cache en mémoire du HTML de page invariant par requête. Les opérateurs opèrent un opt-out ; ils n'opèrent jamais d'opt-in. |

Comment cela fonctionne :

- **La mise en cache est dérivée, jamais déclarée.** Une page n'est cachable que lorsque son HTML rendu ne peut pas varier selon la requête — elle est exclue si elle a un `access` non public, une `collection`, un `dataSource` de page/composant, un `contentDir`, une `source` de fichier, un corps `markdown`, une `presence`, une barre latérale liée aux données ou un segment de route dynamique `:param`.
- **Modèle de sécurité.** Le cache n'est consulté que pour les requêtes **anonymes, hors aperçu** ; le filtrage dépendant de la session est déterministe lorsqu'aucune session n'existe, de sorte que la vue d'un utilisateur ne peut jamais fuiter vers un autre.
- **Invalidation par somme de contrôle.** Chaque entrée est indexée par `${appRenderChecksum}:${path}:${language}`. La somme de contrôle est un SHA-256 de la tranche de schéma affectant le rendu (`pages`, `components`, `theme`, `languages`, `analytics`) ; toute édition de schéma change chaque clé, de sorte que les entrées périmées deviennent inaccessibles. Aucune durée de vie, aucune logique de purge.
- **Observabilité.** Chaque réponse de page porte `X-Render-Cache: hit | miss | bypass` et un en-tête `Cache-Control` (`public, max-age=300` pour cachable, `private, no-cache` pour contourné). Les variantes de langue (`/` vs `/fr/`) sont isolées par clé.

Voir [Écoconception](/fr/ecoconception) pour le contrat complet des variables env `ECO_*`.

## Distribution en binaire autonome

Le canal de distribution principal de Sovrium est un **binaire autonome** (`bun build --compile`) qui s'exécute sans Bun ni Node.js sur l'hôte cible. Le binaire embarque l'intégralité du runtime dans un seul exécutable :

- Surface de commandes CLI (`--version`, `validate`, `build`, `schema`, `init`, `agents list`)
- Ensembles de migrations (les deux dialectes)
- Bundles client et chunks d'îlots
- Modèles d'agents et configurations d'exemple
- Le moteur CSS thématisé sans dépendance native

En mode compilé, le binaire lit ses assets **embarqués**, jamais les arborescences `dist/`/`src/`/`specs/` du dépôt sur disque — de sorte qu'il se comporte de façon identique lorsqu'il est lancé depuis n'importe quel répertoire de travail sur une machine cliente. Les bundles client embarqués, les chunks d'îlots et le script de changement de langue sont servis via HTTP depuis un serveur lancé par le binaire (`GET /assets/output.css`, `GET /assets/client.js`, `GET /assets/islands/*`).

## Pages connexes

- [Installation](/fr/installation) — obtenir le binaire et l'exécuter.
- [Variables d'environnement](/fr/env-vars) — référence complète des variables env incl. `DATABASE_URL`, `SOVRIUM_DATA_DIR`.
- [Migrations de schéma](/fr/migrations) — les ensembles de migrations que chaque dialecte applique.
- [Aperçu des buckets](/fr/buckets-overview) — stockage local vs S3, le jumeau `STORAGE_PROVIDER`.
- [Écoconception](/fr/ecoconception) — le `ECO_PAGE_CACHE` et le contrat frugal-par-défaut plus large.
- [Tableau de bord d'administration](/fr/admin-dashboard) — `config/version` rapporte le runtime actif.

# Durcissement de la sécurité

Sovrium conçoit pour éliminer les modes de défaillance récurrents des applications non sécurisées — surfaces exposées, authentification manquante, autorisation au niveau de l'objet cassée, points de terminaison énumérables — à la couche de la plateforme, de sorte que chaque application hérite des défenses sans configuration par application. Chaque réponse HTTP porte un ensemble d'en-têtes durcis, le CSRF est appliqué en production, les points de terminaison sensibles sont limités en débit et l'accès non autorisé renvoie `404` plutôt que `403`.

Ces garanties sont appliquées **dans le code** (pas seulement à l'entrée du proxy inverse), de sorte qu'elles tiennent même pour un déploiement auto-hébergé sans proxy attaché.

## En-têtes de sécurité HTTP

Chaque réponse — page, API, asset statique ou `404` — porte un ensemble d'en-têtes durcis, appliqué via le middleware `secureHeaders` de Hono enregistré comme **premier** middleware `*` afin qu'il s'exécute avant la correspondance de route et couvre les réponses d'erreur.

| En-tête                               | Valeur / comportement                                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Strict-Transport-Security`           | `max-age=31536000; includeSubDomains` (HSTS d'un an, couvre les sous-domaines).                                 |
| `X-Content-Type-Options`              | `nosniff` (désactive le sniffing MIME).                                                                         |
| `X-Frame-Options`                     | `SAMEORIGIN` / `DENY` (anti-détournement de clic).                                                              |
| `Referrer-Policy`                     | `strict-origin-when-cross-origin`.                                                                              |
| `Cross-Origin-Opener-Policy`          | `same-origin`.                                                                                                  |
| `Cross-Origin-Resource-Policy`        | `same-origin`.                                                                                                  |
| `Permissions-Policy`                  | Refuse la caméra, le microphone, la géolocalisation, le paiement, l'usb, l'accéléromètre, …                     |
| `Content-Security-Policy-Report-Only` | `default-src 'self'`, `frame-ancestors 'none'`, `object-src 'none'`, `base-uri 'self'`, `form-action 'self'`, … |
| `Content-Security-Policy` (appliqué)  | **Absent** — report-only d'abord ; la CSP appliquée à base de nonce est une promotion de Phase 2.               |

:::callout
**La CSP est livrée en report-only d'abord.** Elle fait remonter les violations sans bloquer pendant que la couche SSR émet encore des `<script>`/`<style>` en ligne. L'en-tête appliqué est délibérément absent pour l'instant, et une spécification verrouille cette absence afin qu'un basculement prématuré fasse échouer la CI. Les directives dans le code reflètent le filet de sécurité de l'entrée Caddy afin que les deux couches s'accordent.
:::

HSTS est émis sans condition même sur du HTTP en clair — les navigateurs l'ignorent sur une connexion `http://`, et un proxy de terminaison TLS transmet exactement la valeur que le serveur produit.

## Application CSRF & Cross-Origin

Sovrium s'appuie sur le middleware de vérification d'origine intégré de Better Auth. Une requête modifiant l'état, porteuse de cookies, dont l'`Origin` est falsifié ou supprimé est rejetée — une falsification inter-sites ne peut pas chevaucher le cookie de session d'une victime.

| Environnement          | `disableCSRFCheck` | Comportement                                                                         |
| ---------------------- | ------------------ | ------------------------------------------------------------------------------------ |
| `NODE_ENV=development` | `true`             | Vérification d'origine contournée — `Origin` falsifié accepté (DX cross-port local). |
| `NODE_ENV=production`  | `false`            | Vérification d'origine active — `Origin` falsifié / manquant rejeté `403`.           |

- `trustedOrigins` est limité à l'origine `BASE_URL` propre à l'application — **jamais** `'*'`. Un caractère générique est un contournement de redirection ouverte / de validation d'origine ; le limiter fait aussi que Better Auth rejette un `redirectTo` d'origine externe lors de la réinitialisation de mot de passe.
- `useSecureCookies` est activé en production. La barrière CSRF et les cookies sécurisés se dégradent silencieusement si `NODE_ENV` n'est pas défini, de sorte qu'un risque de `NODE_ENV` manquant est révélé **bruyamment** dans la bannière de démarrage de production (et supprimé en dev pour garder la sortie propre).

:::callout
**Définissez `NODE_ENV=production` en production.** L'application CSRF et les cookies sécurisés en dépendent tous deux. Lorsqu'elle n'est pas définie, le serveur avertit bruyamment dans la bannière de démarrage — tenez-en compte avant la mise en ligne.
:::

## Limitation de débit

Sovrium remplace la limitation de débit native de Better Auth (bugs amont connus) par un middleware Hono personnalisé sur les points de terminaison sensibles.

| Point de terminaison                    | Limite                          | Fenêtre |
| --------------------------------------- | ------------------------------- | ------- |
| `POST /api/auth/sign-in/email`          | 5 tentatives                    | 60 s    |
| `POST /api/auth/sign-up/email`          | 5 tentatives                    | 60 s    |
| `POST /api/auth/request-password-reset` | 3 tentatives                    | 60 s    |
| `POST /api/auth/admin/*`                | Limite de débit générale par IP | —       |

Dépasser une limite renvoie `429 Too Many Requests`. Les routes d'administration exécutent en plus un middleware de vérification d'authentification qui renvoie `401` **avant** la validation des paramètres, de sorte qu'un appelant non authentifié n'apprend jamais la forme d'un point de terminaison protégé.

## Anti-énumération : 404, pas 403

L'accès non autorisé à une ressource protégée renvoie **`404 Not Found`**, jamais `403 Forbidden`. Un `403` confirme que la ressource existe ; un `404` rend l'existence de la ressource — et l'espace des id — inobservable. Cela s'applique uniformément aux lectures d'enregistrements, au [tableau de bord d'administration](/fr/admin-dashboard) et au point de terminaison de suppression forcée par table (qui renvoie `404` lorsque la suppression forcée n'est pas autorisée pour cette table).

L'autorisation au niveau de l'objet est appliquée avant l'exécution de toute logique sensible : une requête est authentifiée, puis vérifiée pour l'accès à l'objet spécifique, et en cas d'échec renvoie `404`. Combiné à des id indevinables, cela déjoue l'énumération même si le `404` lui-même est observable.

## Synthèse défense en profondeur

| Préoccupation               | Mécanisme                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| Sécurité du transport       | HSTS (`max-age=31536000; includeSubDomains`).                                              |
| MIME / détournement de clic | `nosniff`, `X-Frame-Options`.                                                              |
| Isolation cross-origin      | COOP + CORP `same-origin`, CSP report-only.                                                |
| CSRF                        | Vérification d'origine Better Auth (production), `trustedOrigins` limité.                  |
| Force brute                 | Limitation de débit par point de terminaison (`429`).                                      |
| Énumération                 | `404`-pas-`403`, id indevinables, vérification d'authentification avant validation.        |
| Autorisation                | RBAC + [permissions par champ](/fr/table-permissions), vérifications au niveau de l'objet. |

## Pages connexes

- [Aperçu de l'authentification](/fr/auth-overview) — stratégies d'authentification et le bloc `auth`.
- [Sessions](/fr/auth-sessions) — durée de vie des sessions, révocation, cookies sécurisés.
- [Rôles & RBAC](/fr/auth-roles-rbac) — modèle de rôle et permissions par champ.
- [Permissions de table](/fr/table-permissions) — contrôle d'accès par table et par champ.
- [Tableau de bord d'administration](/fr/admin-dashboard) — la surface de lecture 404-en-cas-de-non-autorisation.
- [GDPR & Confidentialité](/fr/gdpr-privacy) — garanties d'export et d'effacement des données.
- [Variables d'environnement](/fr/env-vars) — `NODE_ENV`, `BASE_URL` et réglages associés.

# GDPR & Confidentialité

Sovrium donne aux utilisateurs finaux un contrôle en libre-service sur leurs données personnelles, satisfaisant les droits GDPR fondamentaux sans intervention de l'opérateur. Un utilisateur authentifié peut télécharger une copie complète et lisible par machine de tout ce que Sovrium détient à son sujet, et peut planifier un effacement irréversible de son compte selon un calendrier sûr et réversible jusqu'au dernier moment.

Ce sont des points de terminaison destinés à l'utilisateur final — ils agissent sur les propres données de l'appelant, limitées exclusivement par la session authentifiée. Aucun id n'est jamais pris du corps de la requête.

## Export de données (Articles 15 & 20)

`GET /api/account/export` renvoie l'empreinte complète des données personnelles de l'appelant sous forme de JSON structuré, satisfaisant le **droit d'accès** (art. 15) et le **droit à la portabilité des données** (art. 20) du GDPR.

```
GET /api/account/export
Cookie: <session cookie>
```

Aucun corps de requête, paramètre de requête ou de chemin — l'id utilisateur provient uniquement de la session. La réponse agrège quatre sources pour l'appelant :

| Source                    | Contenu                                                                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Profil**                | La ligne `auth.user` de l'appelant.                                                                                                    |
| **Sessions**              | Les lignes `auth.session` de l'appelant.                                                                                               |
| **Comptes liés**          | Les lignes `auth.account` de l'appelant (fournisseurs OAuth + identifiant e-mail/mot de passe), **avec tout le matériel secret omis**. |
| **Enregistrements créés** | Chaque enregistrement de table dans l'application où `created_by = caller`.                                                            |

:::callout
**Les secrets ne sont jamais exportés.** Les hachages de mots de passe, les jetons OAuth et autres matériels d'identification sont retirés de la section des comptes liés. L'export est un artefact de portabilité, pas un déversement d'identifiants.
:::

## Suppression et effacement de compte (Article 17)

`POST /api/account/delete` permet à un utilisateur de demander l'effacement irréversible de son compte, satisfaisant le **droit à l'effacement** (art. 17) du GDPR. La suppression suit un **modèle d'effacement planifié avec un délai de grâce de 7 jours** — jamais une destruction immédiate.

```
POST /api/account/delete
Cookie: <session cookie>
Content-Type: application/json

{ "confirm": true }
```

| Étape            | Requête                           | Effet                                                                                                                                                                                                                                                           |
| ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Planifier** | `{ "confirm": true }`             | Marque `scheduledErasureAt = now + 7 days`, révoque toutes les sessions de l'appelant (déconnecté partout), écrit un événement d'audit `account.deletion.scheduled`, renvoie `202 Accepted`. **Ne supprime pas encore.**                                        |
| **2. Annuler**   | `{ "cancel": true }`              | Pendant la fenêtre, l'utilisateur se reconnecte et annule — efface `scheduledErasureAt`, renvoie `200 OK`.                                                                                                                                                      |
| **3. Purger**    | _(automatique, après la fenêtre)_ | Une tâche de purge **supprime définitivement** les lignes `auth.user`, `auth.session`, `auth.account`, `auth.verification` de l'appelant et chaque enregistrement de table où `created_by = caller`, puis écrit un événement d'audit `account.deletion.purged`. |

Un `POST` nu sans indicateur `confirm`/`cancel` est rejeté `400` (anti-faux-pas).

## Suppression définitive, pas suppression en douceur

L'effacement effectue une **suppression physique des lignes** — pas la pierre tombale `deleted_at` de suppression en douceur utilisée ailleurs dans la plateforme. Après la purge, aucune donnée personnelle récupérable ne subsiste, comme l'exige l'art. 17.

C'est l'exception délibérée à la posture de [suppression-en-douceur-par-défaut](/fr/records-soft-delete) de Sovrium : les suppressions ordinaires sont des pierres tombales récupérables, mais un effacement GDPR ne doit rien laisser derrière. Les suppressions irréversibles par table via le tableau de bord d'administration nécessitent l'opt-in explicite `allowForceDelete: true` (voir [Permissions de table](/fr/table-permissions)) ; le point de terminaison de suppression forcée renvoie `404` lorsque la suppression forcée n'est pas autorisée.

:::callout
**La piste d'audit de l'effacement survit à l'utilisateur.** L'événement `account.deletion.purged` survit à la ligne utilisateur supprimée — la clé étrangère `audit_log.actor_id` est `ON DELETE SET NULL`, de sorte que l'entrée reste un enregistrement de conformité valide avec un acteur null-ifié. Supprimer les données et prouver que les données ont été supprimées sont deux obligations distinctes.
:::

## Confidentialité dès la conception

Au-delà des droits en libre-service, la confidentialité est intégrée aux valeurs par défaut de la plateforme :

- **Analytique sans cookies** — les visiteurs sont identifiés par des hachages SHA-256 côté serveur ; aucune donnée personnelle ni identifiant client n'est stocké, et Do Not Track est respecté. Voir [Analytique](/fr/analytics).
- **Conservation bornée** — les lignes supprimées en douceur vieillissent selon `ECO_RETENTION_PURGE_DAYS` (voir [Écoconception](/fr/ecoconception)) ; moins de données stockées est à la fois un gain de confidentialité et de frugalité.
- **Aucun service externe** — toutes les données personnelles restent sur votre serveur ; rien n'est expédié à un tiers.

## Pages connexes

- [Surveillance de l'activité](/fr/activity-monitoring) — la piste d'audit des événements de suppression et d'accès.
- [Suppression en douceur](/fr/records-soft-delete) — le modèle de pierre tombale récupérable que l'effacement contourne délibérément.
- [Permissions de table](/fr/table-permissions) — `allowForceDelete` et accès par champ.
- [Durcissement de la sécurité](/fr/security-hardening) — authentification, CSRF, anti-énumération.
- [Analytique](/fr/analytics) — suivi sans cookies et respectueux de la vie privée.
- [Écoconception](/fr/ecoconception) — conservation et minimisation des données.

# Écoconception

Sovrium traite l'empreinte environnementale comme une **propriété de premier ordre de la plateforme** — pas une fonctionnalité, pas un palier payant, pas une case à cocher. La plateforme est frugale par défaut, la posture est contrôlée par l'opérateur via des variables d'environnement, et l'empreinte est mesurable plutôt qu'aspirationnelle. Posséder vos données et minimiser leur coût environnemental relèvent du même combat contre l'infrastructure absente.

La posture éco vit dans les variables d'environnement `ECO_*` — le jumeau de `DATABASE_URL`, `STORAGE_PROVIDER` et `AI_PROVIDER`. Elle ne fait **jamais** partie du schéma de l'application : un auteur de schéma ne doit pas pouvoir désactiver silencieusement la frugalité pour les utilisateurs finaux de son application (ADR 013).

## Principes fondamentaux

| Principe                                        | Signification                                                                                                                              |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Frugal par défaut**                           | Chaque bascule destinée à l'opérateur prend par défaut le réglage aligné sur l'éco. Les opérateurs opèrent un opt-_out_, jamais un opt-in. |
| **Contrôlé par l'opérateur, pas par le schéma** | La posture éco est dans les variables env, pas `app.eco.*`. Les champs de schéma pour l'éco sont explicitement rejetés.                    |
| **Mesurable, pas aspirationnel**                | La plateforme s'engage sur un en-tête de réponse `X-Eco-Index` et un budget de poids de page ; les badges éco sans mesure sont interdits.  |

## Le contrat des variables env `ECO_*`

Frugal par défaut — les opérateurs opèrent un opt-out en remplaçant. Ce sont les boutons d'opérateur pour la posture environnementale de la plateforme.

| Variable env                 | Par défaut      | Options                                                             | Objectif                                                                                                                   |
| ---------------------------- | --------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `ECO_MODE`                   | `balanced`      | `balanced` \| `lenient` (héritage `on`→`balanced`, `off`→`lenient`) | Bascule maîtresse de posture éco ; protège les sous-boutons en aval.                                                       |
| `ECO_IMAGE_FORMAT`           | `avif`          | `avif` \| `webp` \| `jpeg` \| `png`                                 | Format de transcodage d'image côté serveur par défaut. AVIF est ~50 % plus petit que JPEG.                                 |
| `ECO_PAGE_CACHE`             | `on`            | `on` \| `off`                                                       | Cache en mémoire du HTML de page statique invariant par requête — saute `renderToString` lors des hits.                    |
| `ECO_INDEX_HEADER`           | `on`            | `on` \| `off`                                                       | Émet l'en-tête de réponse `X-Eco-Index` noté à partir de la taille de transfert.                                           |
| `ECO_LOW_DATA_DEFAULT`       | `off`           | `on` \| `off` \| `respect-client`                                   | Posture de mode données réduites de l'utilisateur final (réduit les assets quand activé / sur indice client).              |
| `ECO_AI_PROVIDER_PRECEDENCE` | `local-first`   | `local-first` \| `cloud-first` \| `local-only`                      | Précédence de routage pour les appels IA ; s'associe à `AI_PROVIDER`.                                                      |
| `ECO_AI_MAX_CARBON_CLASS`    | `G` (permissif) | `A`–`G`                                                             | Borne supérieure sur la classe carbone d'un fournisseur/d'une région IA sélectionnés.                                      |
| `ECO_PAGE_WEIGHT_BUDGET_KB`  | `500`           | entier                                                              | Budget de transfert par page pour la barrière de poids de page.                                                            |
| `ECO_RETENTION_PURGE_DAYS`   | `365`           | entier (`0` désactive)                                              | Horizon de purge par défaut des lignes supprimées en douceur pour les tables qui s'inscrivent.                             |
| `ECO_DESIGN_LAYER`           | `on`            | `on` \| `off`                                                       | Émet la couche de conception par défaut toujours active (une surface de remplacement, pas une valeur par défaut porteuse). |

:::callout
**Les opérateurs opèrent un opt-out, jamais un opt-in.** Chaque bascule `ECO_*` prend par défaut la valeur alignée sur l'éco. Pour assouplir la frugalité, vous devez explicitement définir la variable — à l'image de la façon dont `DATABASE_URL` prend par défaut SQLite et `STORAGE_PROVIDER` sélectionne automatiquement le stockage local. La posture éco n'est jamais déclarée dans le schéma de l'application.
:::

## Fondations déjà alignées

Plusieurs décisions de Sovrium servent la frugalité avant qu'une variable `ECO_*` ne soit touchée :

| Décision                                                      | Bénéfice d'empreinte                                                                                                                               |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Distribution en binaire autonome                              | Un binaire statique, aucun runtime Node, moins de dépendances au démarrage. Voir [Infrastructure de base de données](/fr/database-infrastructure). |
| Valeurs par défaut sans configuration SQLite + stockage local | Processus unique, aucune base de données cloud gérée requise.                                                                                      |
| Architecture SSR + îlots                                      | Seul l'îlot actif est expédié ; les éditeurs lourds se chargent en différé.                                                                        |
| Compilateur CSS programmatique                                | Compilé par thème à la demande, cache en mémoire — pas de feuille de style statique d'un mégaoctet. Voir [Thème](/fr/theme).                       |
| Suppression en douceur avec horizon de conservation           | Posture explicite de purger-ou-garder au lieu d'une accumulation infinie. Voir [Suppression en douceur](/fr/records-soft-delete).                  |
| Option IA locale d'abord                                      | L'inférence locale évite les allers-retours transatlantiques.                                                                                      |

## Mode données réduites

`ECO_LOW_DATA_DEFAULT` contrôle l'agressivité avec laquelle Sovrium réduit le poids des assets pour les utilisateurs finaux. Lorsqu'il est sur `on`, les variantes données réduites (images de résolution inférieure, rendus plus simples) sont servies par défaut ; avec `respect-client`, la posture suit les indices client `Save-Data` / `prefers-reduced-data` du visiteur ; `off` sert toujours la variante complète.

Le mode données réduites **réduit avec grâce** — il ne refuse jamais de rendre un graphique ou un éditeur de texte enrichi. Le blocage paternaliste de fonctionnalités est un anti-modèle explicite ; la posture éco abaisse la fidélité, elle ne casse pas le flux de travail d'un utilisateur.

## Mesure : `X-Eco-Index`

Lorsque `ECO_INDEX_HEADER=on`, les réponses de page portent un en-tête `X-Eco-Index` noté (A–G) à partir de la taille de transfert de la réponse par rapport à des seuils en paliers (le plus grand se situant à `ECO_PAGE_WEIGHT_BUDGET_KB`). Cela rend l'empreinte observable par réponse plutôt qu'une affirmation marketing — les badges éco sans un nombre mesuré sont interdits (ADR 013).

## Tableau de bord éco

Le tableau de bord éco d'administration fait remonter la posture en cours d'exécution : une tuile d'auto-évaluation RGESN, le mélange de fournisseurs IA par classe carbone, les principaux consommateurs de stockage et les réglages `ECO_*` actuellement en vigueur. Il lit les mêmes signaux mesurés (les notes `X-Eco-Index`, le budget de poids de page) que la plateforme émet — jamais un badge synthétique « Mode Éco activé ».

## Anti-modèles

- **Badges d'écoblanchiment** — afficher un badge « Mode Éco activé » sans un nombre d'empreinte mesuré.
- **Blocage paternaliste de fonctionnalités** — refuser de rendre du contenu à cause d'une posture éco ; toujours réduire avec grâce.
- **Palier éco payant** — verrouiller les fonctionnalités éco derrière une clé de licence. Toute la posture éco est gratuite en mode auto-hébergé.
- **Configuration éco au niveau du schéma** — ajouter `app.eco.lowDataMode = true`. L'éco est contrôlé par l'opérateur ; utilisez des variables env.
- **Appels IA cloud codés en dur** — contourner `ECO_AI_PROVIDER_PRECEDENCE` et appeler un fournisseur cloud directement. Toujours router via le résolveur de précédence.

## Pages connexes

- [Infrastructure de base de données](/fr/database-infrastructure) — `ECO_PAGE_CACHE` et le cache de rendu statique.
- [Thème](/fr/theme) — le compilateur CSS programmatique et `ECO_DESIGN_LAYER`.
- [Suppression en douceur](/fr/records-soft-delete) — l'horizon de conservation que `ECO_RETENTION_PURGE_DAYS` régit.
- [GDPR & Confidentialité](/fr/gdpr-privacy) — la minimisation des données comme jumeau confidentialité-et-frugalité.
- [Analytique](/fr/analytics) — conservation bornée et suivi sans cookies.
- [Variables d'environnement](/fr/env-vars) — référence complète des variables env.

# Schéma JSON

Le schéma d'application Sovrium définit la structure complète de la configuration de votre application. Il est publié sous forme de **schéma JSON standard (Draft-07)**, dérivé directement du schéma Effect canonique (`AppSchema`). Utilisez-le pour l'autocomplétion dans l'éditeur, la validation en temps réel, les vérifications de configuration en CI et la vérification programmatique.

Trois artefacts partagent cette source unique de vérité :

| Artefact             | Format             | Généré par         | À utiliser pour                                        |
| -------------------- | ------------------ | ------------------ | ------------------------------------------------------ |
| Schéma JSON          | JSON (Draft-07)    | `sovrium schema`   | Autocomplétion dans l'éditeur, validation CI           |
| `@sovrium/types`     | TypeScript `.d.ts` | paquet npm         | Autocomplétion `defineConfig()` dans `app.ts`          |
| Validateur AppSchema | décodage runtime   | `sovrium validate` | Vérifier un fichier de configuration avant déploiement |

:::callout
**Explorateur de schéma interactif.** Parcourez le schéma complet visuellement avec le JSON Schema Viewer. Dépliez les propriétés, consultez les types et explorez les structures imbriquées.

[Ouvrir l'explorateur de schéma ↗](https://json-schema.app/view/%23?url=https%3A%2F%2Fsovrium.com%2Fschema%2Fapp.json)
:::

## Générer le schéma

La CLI affiche le schéma JSON de la configuration d'application Sovrium. Par défaut, elle écrit sur la sortie standard ; passez `--output <chemin>` pour écrire dans un fichier à la place.

```bash
# Print the JSON Schema to stdout
sovrium schema

# Write the JSON Schema to a file
sovrium schema --output app.schema.json
```

Le document généré est un schéma Draft-07 autonome avec une déclaration `$schema` de premier niveau, de sorte que tout outil compatible avec JSON Schema peut le consommer sans configuration supplémentaire. Consultez la [Référence CLI](/fr/cli) pour la surface complète des commandes.

## Propriétés racine en un coup d'œil

L'objet racine du schéma accepte les propriétés de premier niveau suivantes. Chaque propriété sauf `name` est optionnelle et vient se superposer.

| Propriété     | Type       | Description                                                       |
| ------------- | ---------- | ----------------------------------------------------------------- |
| `name`        | `string`   | Nom de l'application (requis)                                     |
| `version`     | `string`   | Chaîne de version de la configuration                             |
| `description` | `string`   | Description lisible par un humain                                 |
| `tables`      | `object[]` | Tables de données (voir [Aperçu des tables](/fr/tables-overview)) |
| `pages`       | `object[]` | Pages et leurs sections                                           |
| `forms`       | `object[]` | Formulaires autonomes                                             |
| `auth`        | `object`   | Configuration de l'authentification et du RBAC                    |
| `theme`       | `object`   | Tokens de design (couleurs, polices, espacements)                 |
| `components`  | `object[]` | Composants réutilisables                                          |
| `automations` | `object[]` | Flux de travail déclencheur/action                                |
| `connections` | `object[]` | Connexions à des services externes                                |
| `languages`   | `object`   | Internationalisation / i18n                                       |
| `analytics`   | `object`   | Analytique respectueuse de la vie privée                          |
| `agents`      | `object[]` | Agents IA                                                         |

## URLs du schéma

Référencez le schéma JSON Sovrium hébergé par son URL dans votre éditeur, votre pipeline CI ou vos scripts de validation.

### Versionné (recommandé)

Épinglez à une version spécifique pour la stabilité en production. L'URL du schéma inclut la version exacte du paquet.

```
https://sovrium.com/schema/app-0.10.0.json
```

### Dernière version

Pointe toujours vers la version la plus récente. Pratique pour le développement, mais peut introduire des changements incompatibles.

```
https://sovrium.com/schema/app.json
```

## Intégration à l'éditeur

Ajoutez le schéma JSON à votre éditeur pour bénéficier de l'autocomplétion, de la documentation en ligne et de la validation en temps réel au fil de l'écriture de votre configuration Sovrium.

### VS Code

VS Code prend en charge nativement le schéma JSON pour les fichiers JSON et YAML (l'extension YAML est requise pour les fichiers `.yaml`/`.yml`).

**Option 1 : ajouter `$schema` directement dans votre fichier de configuration**

```yaml
# yaml-language-server: $schema=https://sovrium.com/schema/app.json
name: my-app
```

Vous pouvez également faire pointer la directive vers un fichier généré localement :

```yaml
# yaml-language-server: $schema=./app.schema.json
name: my-app
```

**Option 2 : configurer dans le `settings.json` de VS Code**

```json
{
  "yaml.schemas": {
    "https://sovrium.com/schema/app.json": ["app.yaml", "*.sovrium.yaml"]
  },
  "json.schemas": [
    {
      "fileMatch": ["app.json", "*.sovrium.json"],
      "url": "https://sovrium.com/schema/app.json"
    }
  ]
}
```

### JetBrains

IntelliJ IDEA, WebStorm et les autres IDE JetBrains prennent en charge nativement le mappage de schéma JSON.

Allez dans **Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings**. Cliquez sur **+** pour ajouter un nouveau mappage, collez l'URL du schéma (ou le chemin vers un fichier `app.schema.json` généré) et définissez le motif de fichier pour correspondre à votre fichier de configuration (par exemple, `app.yaml` ou `app.json`).

## Autocomplétion TypeScript avec `@sovrium/types`

Lorsque vous rédigez votre configuration sous forme de fichier TypeScript (`app.ts`) plutôt qu'en YAML/JSON, le paquet sans dépendance `@sovrium/types` vous offre l'autocomplétion complète dans l'IDE, les erreurs de type en ligne et le saut à la définition — le tout adossé au même `AppSchema`.

```bash
bun add -d @sovrium/types
```

Enveloppez votre configuration dans `defineConfig()` pour obtenir une autocomplétion typée au fil de la saisie :

```typescript
import { defineConfig } from '@sovrium/types'

export default defineConfig({
  name: 'my-app',
  description: 'My Sovrium application',
  tables: [
    {
      id: 1,
      name: 'contacts',
      fields: [{ id: 1, name: 'email', type: 'email', required: true }],
    },
  ],
})
```

:::callout
**Zéro dépendance d'exécution.** `@sovrium/types` ne livre que des définitions de types TypeScript (générées à partir d'`AppSchema`), il n'ajoute donc rien à votre bundle et reste sous licence MIT. La CLI accepte directement `app.ts` — `sovrium start app.ts`, `sovrium validate app.ts`.
:::

## Valider un fichier de configuration

Utilisez `sovrium validate` pour vérifier un fichier de configuration par rapport à `AppSchema` avant déploiement. Il accepte les fichiers `.json`, `.yaml`, `.yml` et `.ts`, en résolvant d'abord toute inclusion `$ref`.

```bash
# Validate a YAML config
sovrium validate app.yaml

# Validate a JSON config
sovrium validate config.json

# Validate a TypeScript config
sovrium validate app.ts
```

En cas de succès, il affiche `Valid configuration: <name>` et se termine avec le code `0`. En cas d'échec, il affiche les erreurs de décodage structurel (formatées en arborescence) ainsi que tout constat post-décodage — types de champ inconnus et actions `type: cloud` restreintes — puis se termine avec le code `1`.

| Code de sortie | Signification                                                                               |
| -------------- | ------------------------------------------------------------------------------------------- |
| `0`            | La configuration est valide                                                                 |
| `1`            | La configuration est invalide (erreur de décodage, type de champ inconnu, fichier manquant) |

:::callout
**Les types de champ inconnus sont détectés au moment de la validation.** Un champ dont le `type` ne fait pas partie des [49 types de champ connus](/fr/field-types-overview) passe le décodage structurel mais est signalé par `sovrium validate` (et échouerait sinon lors de la génération SQL). Valider tôt fait remonter ces problèmes avant l'exécution.
:::

## Validation programmatique

Pour les pipelines CI, exécutez `sovrium validate` comme étape de build et conditionnez sur son code de sortie :

```bash
sovrium validate app.yaml || exit 1
```

Pour des intégrations plus riches, vous pouvez également servir le schéma en direct via HTTP depuis une instance en cours d'exécution (réservé aux administrateurs) et l'alimenter vers des outils externes — consultez [OpenAPI](/fr/openapi) pour la surface complète du schéma HTTP.

# Référence API

Sovrium expose une API REST complète pour gérer les tables, les enregistrements, les vues, les journaux d'activité, l'analytique, l'authentification et la gestion de schéma par les administrateurs. Tous les endpoints acceptent et retournent du JSON, appliquent le RBAC avec des permissions au niveau des champs et émettent une enveloppe d'erreur canonique unique.

:::callout
**Aperçu anticipé.** La surface de l'API évolue. Les endpoints peuvent changer avant la v1.0.
:::

## URL de base

Tous les endpoints sont relatifs à l'URL de base de votre instance Sovrium.

```
http://localhost:3000/api
```

## Authentification et contrôle d'accès

L'API utilise une authentification basée sur les sessions (Better Auth). Les requêtes qui touchent à des ressources protégées doivent porter un cookie de session valide ou un en-tête `Authorization: Bearer <token>`. L'accès est régi par le **RBAC** (admin, member, viewer) avec des **permissions au niveau des champs** superposées par-dessus.

Conformément à la politique anti-énumération, une requête authentifiée qui ne dispose pas d'un accès en lecture à une ressource retourne **404** (et non 403), de sorte que l'appelant ne peut pas distinguer « introuvable » de « pas d'accès ». Un véritable **403** est réservé aux surfaces où la ressource est connue pour exister mais où l'action est refusée (par exemple, un non-administrateur appelant `GET /api/admin/schema/versions`).

## Contrat de réponse d'erreur

Toutes les réponses 4xx/5xx utilisent une enveloppe JSON canonique unique, de sorte qu'un seul décodeur couvre toutes les erreurs.

**Enveloppe 4xx/5xx générique :**

```json
{
  "success": false,
  "message": "Authentication required",
  "code": "UNAUTHORIZED"
}
```

Le `code` est tiré d'une énumération stable : `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `VALIDATION_ERROR`, `CONFLICT`, `RATE_LIMITED`, `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE`. Les champs optionnels `error` (identifiant de type hérité) et `details` peuvent également être présents.

**Enveloppe de validation 400** — lorsque l'échec se situe au niveau des champs, un tableau `errors[]` nomme chaque champ fautif :

```json
{
  "success": false,
  "message": "One or more fields failed validation",
  "code": "VALIDATION_ERROR",
  "errors": [{ "field": "id", "message": "Cannot write to readonly field 'id'" }]
}
```

| Statut | `code`              | Signification                                               |
| ------ | ------------------- | ----------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR`  | Échec de validation au niveau des champs (porte `errors[]`) |
| `401`  | `UNAUTHORIZED`      | Session absente / expirée                                   |
| `403`  | `FORBIDDEN`         | Authentifié, action refusée (ressource connue)              |
| `404`  | `NOT_FOUND`         | Introuvable, ou refus d'accès anti-énumération              |
| `413`  | `PAYLOAD_TOO_LARGE` | La charge utile du lot dépasse la limite                    |
| `429`  | `RATE_LIMITED`      | Limite de débit dépassée                                    |
| `500`  | `INTERNAL_ERROR`    | Erreur serveur inattendue (détails masqués)                 |

## Santé

Endpoint de vérification de l'état du serveur (non authentifié).

| Méthode | Chemin        | Description                |
| ------- | ------------- | -------------------------- |
| `GET`   | `/api/health` | Vérifier l'état du serveur |

## Tables

Lecture des définitions de tables, y compris les schémas de champs et les règles de permissions.

| Méthode | Chemin                              | Description                         |
| ------- | ----------------------------------- | ----------------------------------- |
| `GET`   | `/api/tables`                       | Lister toutes les tables            |
| `GET`   | `/api/tables/{tableId}`             | Obtenir une table par ID            |
| `GET`   | `/api/tables/{tableId}/permissions` | Obtenir les permissions d'une table |

## Enregistrements

CRUD complet, opérations par lot, cycle de vie de suppression douce, historique des révisions et commentaires d'enregistrements. Consultez [Aperçu des enregistrements](/fr/records-overview) pour le modèle de données.

### CRUD

| Méthode  | Chemin                                     | Description                        |
| -------- | ------------------------------------------ | ---------------------------------- |
| `GET`    | `/api/tables/{tableId}/records`            | Lister les enregistrements         |
| `POST`   | `/api/tables/{tableId}/records`            | Créer un enregistrement            |
| `GET`    | `/api/tables/{tableId}/records/{recordId}` | Obtenir un enregistrement par ID   |
| `PATCH`  | `/api/tables/{tableId}/records/{recordId}` | Modifier un enregistrement         |
| `DELETE` | `/api/tables/{tableId}/records/{recordId}` | Supprimer un enregistrement (soft) |

### Opérations par lot

| Méthode  | Chemin                                 | Description                                |
| -------- | -------------------------------------- | ------------------------------------------ |
| `POST`   | `/api/tables/{tableId}/records/batch`  | Créer plusieurs enregistrements            |
| `PATCH`  | `/api/tables/{tableId}/records/batch`  | Modifier plusieurs enregistrements         |
| `DELETE` | `/api/tables/{tableId}/records/batch`  | Supprimer plusieurs enregistrements (soft) |
| `POST`   | `/api/tables/{tableId}/records/upsert` | Créer ou modifier un enregistrement        |

### Corbeille et historique

| Méthode | Chemin                                             | Description                          |
| ------- | -------------------------------------------------- | ------------------------------------ |
| `GET`   | `/api/tables/{tableId}/trash`                      | Lister les enregistrements supprimés |
| `POST`  | `/api/tables/{tableId}/records/{recordId}/restore` | Restaurer un enregistrement supprimé |
| `POST`  | `/api/tables/{tableId}/records/batch/restore`      | Restaurer plusieurs enregistrements  |
| `GET`   | `/api/tables/{tableId}/records/{recordId}/history` | Obtenir l'historique des révisions   |

### Commentaires

| Méthode  | Chemin                                              | Description                                 |
| -------- | --------------------------------------------------- | ------------------------------------------- |
| `GET`    | `/api/tables/{tableId}/records/{recordId}/comments` | Lister les commentaires d'un enregistrement |
| `POST`   | `/api/tables/{tableId}/records/{recordId}/comments` | Ajouter un commentaire                      |
| `GET`    | `.../{recordId}/comments/{commentId}`               | Obtenir un commentaire par ID               |
| `PATCH`  | `.../{recordId}/comments/{commentId}`               | Modifier un commentaire                     |
| `DELETE` | `.../{recordId}/comments/{commentId}`               | Supprimer un commentaire                    |

## Vues

Vues préconfigurées qui filtrent, trient et regroupent les enregistrements d'une table.

| Méthode | Chemin                                         | Description                             |
| ------- | ---------------------------------------------- | --------------------------------------- |
| `GET`   | `/api/tables/{tableId}/views`                  | Lister les vues d'une table             |
| `GET`   | `/api/tables/{tableId}/views/{viewId}`         | Obtenir une vue par ID                  |
| `GET`   | `/api/tables/{tableId}/views/{viewId}/records` | Obtenir les enregistrements via une vue |

## Activité

Journal d'audit des modifications de données sur toutes les tables.

| Méthode | Chemin                       | Description                      |
| ------- | ---------------------------- | -------------------------------- |
| `GET`   | `/api/activity`              | Lister les entrées d'activité    |
| `GET`   | `/api/activity/{activityId}` | Obtenir le détail d'une activité |

## Analytique

Analytique d'utilisation respectueuse de la vie privée, sans cookies.

| Méthode | Chemin                     | Description                           |
| ------- | -------------------------- | ------------------------------------- |
| `POST`  | `/api/analytics/collect`   | Enregistrer un événement de page vue  |
| `GET`   | `/api/analytics/overview`  | Obtenir l'aperçu analytique           |
| `GET`   | `/api/analytics/pages`     | Obtenir les pages les plus vues       |
| `GET`   | `/api/analytics/referrers` | Obtenir les principaux référents      |
| `GET`   | `/api/analytics/devices`   | Obtenir la répartition par appareil   |
| `GET`   | `/api/analytics/campaigns` | Obtenir les statistiques de campagnes |

## Admin : gestion de schéma

Édition de schéma en direct (brouillon → validation → publication) pour les utilisateurs administrateurs. Enregistrée uniquement lorsque `app.auth` est configuré et que `SCHEMA_EDIT_API_ENABLED=true` ; sinon, chaque chemin `/api/admin/schema/*` retourne 404. Toutes les routes nécessitent le rôle `admin`.

| Méthode | Chemin                                 | Description                               |
| ------- | -------------------------------------- | ----------------------------------------- |
| `GET`   | `/api/admin/schema/status`             | Statut de dérive / brouillon              |
| `GET`   | `/api/admin/schema/diff`               | Aperçu de la dérive en direct vs fichier  |
| `GET`   | `/api/admin/schema/export`             | Sérialiser la version en direct en YAML   |
| `GET`   | `/api/admin/schema/draft`              | Obtenir le brouillon de travail           |
| `PUT`   | `/api/admin/schema/draft`              | Remplacer le brouillon de travail         |
| `POST`  | `/api/admin/schema/draft/discard`      | Abandonner le brouillon                   |
| `POST`  | `/api/admin/schema/draft/validate`     | Valider le brouillon                      |
| `POST`  | `/api/admin/schema/draft/publish`      | Publier le brouillon (nouvelle version)   |
| `POST`  | `/api/admin/schema/draft/rebase`       | Rebaser un brouillon obsolète sur l'actif |
| `GET`   | `/api/admin/schema/versions`           | Lister les versions publiées              |
| `GET`   | `/api/admin/schema/versions/{version}` | Obtenir une version                       |
| `POST`  | `.../versions/{version}/restore`       | Restaurer une version                     |

Les mutations de brouillon par ressource (`/api/admin/schema/draft/tables`, `/pages`, `/auth/strategies`, `/forms`, `/automations`, `/connections`, `/preview`) et l'opération `/api/admin/schema/prune` complètent la surface. Chaque endpoint REST est reflété en tant qu'outil MCP (`{appName}_schema_*`) pour les agents IA.

## Endpoints d'authentification

L'authentification est gérée par Better Auth et montée sur `/api/auth/*`. Elle inclut la connexion et l'inscription par email/mot de passe, les fournisseurs OAuth sociaux, la gestion des sessions, la réinitialisation de mot de passe, la vérification d'email, l'authentification à deux facteurs, les liens magiques, l'OTP par email, les organisations et la gestion des utilisateurs par les administrateurs. Consultez la [documentation de configuration de l'authentification](/fr/auth-overview) pour la mise en place, ou explorez chaque endpoint d'authentification dans la documentation interactive de l'API.

Les administrateurs peuvent parcourir la surface complète lisible par les machines sur `/api/scalar` et récupérer les documents OpenAPI bruts — consultez [OpenAPI](/fr/openapi).

## Fonctionnalités transversales

Capacités qui s'appliquent à tous les endpoints de l'API.

- **Pagination** — les endpoints de liste paginent leurs résultats
- **Suppressions douces** — `DELETE` met à la corbeille (récupérable) ; une purge distincte supprime définitivement
- **RBAC** — les rôles admin / member / viewer protègent chaque route protégée
- **Permissions au niveau des champs** — contrôle granulaire en lecture/écriture par champ et par rôle
- **Limitation de débit** — les endpoints d'authentification et d'administration sont limités en débit
- **Enveloppe d'erreur canonique** — chaque réponse 4xx/5xx partage une forme unique (voir ci-dessus)

# Référence LLM

Sovrium fournit des fichiers de documentation lisibles par les machines, conçus pour les grands modèles de langage (LLM) et les assistants de codage IA. Utilisez ces fichiers pour donner aux outils IA un contexte complet sur le schéma d'application Sovrium, la CLI, l'API et le format de configuration.

:::callout
**Télécharger la documentation LLM.** Fichiers en texte brut optimisés pour les outils IA comme Claude, ChatGPT, GitHub Copilot et Cursor.

- [llms.txt ↗](/llms.txt) — référence rapide compacte
- [llms-full.txt ↗](/llms-full.txt) — référence complète en un seul fichier
  :::

## Qu'est-ce que llms.txt ?

Un standard émergent pour fournir de la documentation aux assistants IA dans un format adapté aux machines.

La convention llms.txt est un standard croissant où les sites web servent des fichiers de documentation en texte brut à des URL bien connues (`/llms.txt` et `/llms-full.txt`). Ces fichiers sont spécifiquement formatés pour être consommés par les grands modèles de langage, fournissant des informations structurées sur le projet, ses API, son format de configuration et ses capacités. Sovrium publie deux fichiers : une référence rapide compacte pour les consultations rapides, et une référence complète exhaustive pour générer des configurations et répondre aux questions détaillées.

## Les fichiers

Deux fichiers de documentation optimisés pour différents cas d'utilisation.

### `llms.txt`

```
https://sovrium.com/llms.txt
```

Vue d'ensemble compacte avec des liens vers toutes les sections de documentation. Idéal pour un contexte rapide et la navigation.

- **Taille** : environ 40 lignes — s'intègre facilement dans n'importe quelle fenêtre de contexte LLM.
- **Cas d'usage** : à utiliser lorsque vous avez besoin d'un résumé rapide ou que vous souhaitez orienter un outil IA vers des sections spécifiques de la documentation.

### `llms-full.txt`

```
https://sovrium.com/llms-full.txt
```

Documentation complète couvrant l'ensemble de la plateforme Sovrium. Idéal pour une assistance IA approfondie.

- **Taille** : environ 3000 lignes — référence complète en un seul fichier.
- **Cas d'usage** : à utiliser lorsque vous souhaitez qu'un assistant IA dispose d'un contexte complet sur Sovrium, génère des configurations ou réponde à des questions détaillées.

La référence complète couvre :

- Les guides de démarrage
- L'aperçu du schéma et les propriétés racine
- Les 49 types de champs
- Tous les types de composants
- La configuration de l'authentification
- Le thème et les tokens de design
- Les pages et les interactions
- Les langues et l'i18n
- La configuration de l'analytique
- La référence de l'API (enregistrements, authentification, admin, santé)
- Des exemples YAML complets
- La référence du schéma JSON

:::callout
**Synchronisé automatiquement avec les versions.** Les deux fichiers sont automatiquement mis à jour à chaque version de Sovrium pour refléter la dernière version du schéma, les types de champs, les types de composants et les endpoints de l'API. La version actuelle est toujours exacte.
:::

## Utilisation avec les outils IA

Comment fournir la documentation Sovrium à votre assistant IA de choix.

Récupérez la documentation directement :

```bash
# Quick reference (~40 lines)
curl https://sovrium.com/llms.txt

# Complete documentation (~2700 lines)
curl https://sovrium.com/llms-full.txt
```

Collez l'URL ou le contenu dans votre assistant IA avec un prompt comme :

```
Read the Sovrium documentation from https://sovrium.com/llms-full.txt
and help me create an app.yaml configuration for a blog with:
- A posts table with title, content, and published_at fields
- Email/password authentication
- A homepage with a list of recent posts
```

:::callout
**Quel fichier utiliser ?** Commencez par `llms.txt` pour des questions rapides sur ce que Sovrium peut faire. Utilisez `llms-full.txt` lorsque vous avez besoin que l'IA génère des configurations complètes, comprenne tous les types de champs ou travaille avec l'API complète.
:::

## Créer des applications Sovrium avec l'IA

Parce qu'une application Sovrium est un unique fichier de configuration déclaratif, elle constitue une cible idéale pour la rédaction assistée par l'IA. Une boucle pratique :

1. **Donnez le contexte à l'IA.** Orientez-la vers `llms-full.txt` pour qu'elle connaisse l'intégralité du schéma — les [49 types de champs](/fr/field-types-overview), les types de composants, les options d'authentification et la [surface de l'API REST](/fr/api-reference).
2. **Rédigez en TypeScript pour la sûreté de typage.** Demandez à l'IA de générer un `app.ts` en utilisant `defineConfig()` de [`@sovrium/types`](/fr/json-schema#typescript-autocompletion-with-sovriumtypes). Votre éditeur valide alors la sortie de l'IA au fil de l'écriture, en détectant en ligne les types de champ invalides et les sections mal formées.
3. **Validez avant d'exécuter.** Exécutez `sovrium validate app.ts` (voir la [Référence CLI](/fr/cli)) pour confirmer que la configuration se décode par rapport à `AppSchema`, en faisant remonter les types de champ inconnus et les erreurs structurelles avec le code de sortie `1`.
4. **Itérez face à l'application en cours d'exécution.** Démarrez avec `sovrium start app.ts --watch` ; l'IA peut affiner la configuration et le serveur se recharge à chaud à l'enregistrement.

:::callout
**Une sortie vérifiée par le typage l'emporte sur les conjectures en texte libre.** Associer `llms-full.txt` (contexte) à `@sovrium/types` (validation à la compilation) et à `sovrium validate` (décodage à l'exécution) donne à l'IA une boucle de rétroaction serrée — les configurations générées sont vérifiées au moment de la rédaction et de la validation, avant même de démarrer.
:::

# OpenAPI

Sovrium décrit son API HTTP sous forme de documents **OpenAPI 3.1** standard, générés à partir des mêmes schémas Zod de requête/réponse (`src/domain/models/api/`) qui valident le trafic en direct. Parce que les documents OpenAPI exposent la forme complète de l'API, ils sont servis **uniquement aux administrateurs** à l'exécution — jamais aux appelants non authentifiés ou non administrateurs.

:::callout
**Réservé aux administrateurs par conception.** Exposer le schéma de l'API au public divulguerait la surface interne. Sovrium protège tous les endpoints OpenAPI derrière le rôle `admin`. Lorsque `app.auth` n'est pas configuré, les endpoints ne sont pas enregistrés du tout (chaque chemin retourne 404).
:::

## Ce qui est généré

Deux documents OpenAPI plus un explorateur interactif, servis par une instance Sovrium en cours d'exécution.

| Endpoint                     | Retourne         | Description                                            |
| ---------------------------- | ---------------- | ------------------------------------------------------ |
| `GET /api/openapi.json`      | OpenAPI 3.1 JSON | L'API de l'application (tables, enregistrements, etc.) |
| `GET /api/auth/openapi.json` | OpenAPI 3.1 JSON | La surface de l'API Better Auth                        |
| `GET /api/scalar`            | HTML (UI Scalar) | Explorateur interactif unifié pour les deux            |

Le document de l'application est produit par un assistant interne `getOpenAPIDocument(app)` ; le document d'authentification est généré par `generateOpenAPISchema()` de Better Auth. L'UI Scalar monte les deux comme sources commutables (« API » et « Auth »).

## Contrôle d'accès

Les trois endpoints partagent une seule garde administrateur.

| Appelant                             | `/api/openapi.json` | Raison                                                                 |
| ------------------------------------ | ------------------- | ---------------------------------------------------------------------- |
| Non authentifié                      | `401 UNAUTHORIZED`  | Pas de session (sémantique HTTP d'authentification standard)           |
| Authentifié, non administrateur      | `404 NOT_FOUND`     | Anti-énumération : le refus d'autorisation ressemble à « introuvable » |
| Administrateur authentifié           | `200` + document    | Accès complet                                                          |
| Tout appelant, `app.auth` non défini | `404 NOT_FOUND`     | Routes jamais enregistrées                                             |

Les enveloppes 401/404 suivent le [contrat d'erreur canonique](/fr/api-reference#error-response-contract).

## Récupérer les documents

Depuis une instance en cours d'exécution, un administrateur peut récupérer les documents bruts (cookie de session ou en-tête `Authorization: Bearer <token>` requis) :

```bash
# Application API schema
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/openapi.json

# Better Auth API schema
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/auth/openapi.json
```

Enregistrez un document sur le disque pour l'alimenter vers des outils externes :

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/openapi.json -o app.openapi.json
```

:::callout
**Pas encore de commande `export` autonome.** Sovrium ne livre pas actuellement de sous-commande CLI `sovrium openapi` destinée aux utilisateurs — les documents OpenAPI sont générés et servis par le serveur en cours d'exécution aux routes réservées aux administrateurs ci-dessus. Pour produire un fichier statique, récupérez la route en tant qu'administrateur et redirigez vers un fichier (illustré ci-dessus). Le schéma JSON, en revanche, _dispose_ d'une commande dédiée — consultez [`sovrium schema`](/fr/json-schema#generating-the-schema).
:::

## Explorateur d'API Scalar

Visitez `/api/scalar` dans un navigateur tout en étant connecté en tant qu'administrateur pour parcourir, rechercher et tester chaque endpoint. L'explorateur affiche à la fois les documents de l'application et de Better Auth depuis une seule page.

```
http://localhost:3000/api/scalar
```

Il expose les schémas de requête/réponse, les codes de statut et l'enveloppe d'erreur canonique, et vous permet d'émettre des requêtes authentifiées directement depuis la page.

## Intégration d'outils externes

Parce que les documents sont au standard OpenAPI 3.1, tout outil compatible peut les consommer une fois que vous avez récupéré le JSON en tant qu'administrateur.

| Outil              | Comment utiliser le document                                                |
| ------------------ | --------------------------------------------------------------------------- |
| Postman            | Import → File → sélectionnez `app.openapi.json` pour générer une collection |
| Insomnia           | Import / Export → Import Data → From File                                   |
| openapi-typescript | Générer des clients typés à partir de `app.openapi.json`                    |
| Redoc / Swagger UI | Pointez le visualiseur vers le fichier JSON récupéré                        |

Pour les types TypeScript côté client de la _configuration_ (pas de l'API), préférez [`@sovrium/types`](/fr/json-schema#typescript-autocompletion-with-sovriumtypes) ; pour la génération de clients d'API, utilisez le document OpenAPI ci-dessus.

## Comment cela reste synchronisé

Le document OpenAPI de l'application est dérivé des mêmes schémas Zod que les routes utilisent pour la validation, et le document d'authentification est généré par Better Auth au moment de la requête. Il n'y a pas de fichier de spécification maintenu séparément qui pourrait dériver — l'ajout ou la modification du schéma de requête/réponse d'un endpoint met à jour automatiquement le document généré. Consultez la [Référence API](/fr/api-reference) pour la carte des endpoints lisible par les humains.

# Licence

Sovrium est publié sous la **Business Source License 1.1 (BSL 1.1)**. Cette page en résume la portée pratique. Les termes faisant foi se trouvent dans le fichier [`LICENSE.md`](https://github.com/sovrium/sovrium/blob/main/LICENSE.md) à la racine du dépôt.

:::callout
La Business Source License n'est **pas** une licence open source à ce jour, mais l'œuvre sous licence se convertit automatiquement en véritable licence open source à la date de bascule. D'ici là, chaque fonctionnalité est libre d'usage en mode auto-hébergé — pas d'édition payante, pas de clés de licence, pas de fonctionnalités bridées.
:::

## Ce que vous pouvez faire

Vous pouvez utiliser Sovrium pour **tout usage**, sous réserve de l'unique restriction décrite ci-dessous. Les usages permis incluent explicitement :

- Les applications métier internes à votre organisation
- Les déploiements clients où le client auto-héberge et contrôle le logiciel
- Les projets personnels non commerciaux
- Les usages éducatifs et de recherche
- La contribution d'améliorations au projet

## L'unique restriction

Vous ne pouvez **pas** utiliser Sovrium pour fournir un service hébergé ou managé à des tiers lorsque Sovrium — ou une part substantielle de ses fonctionnalités — constitue la valeur principale de ce service.

« Tiers » désigne des personnes ou organisations autres que vous, vos employés, vos prestataires travaillant uniquement pour votre compte, ou vos filiales détenues à 100 %.

Les usages restreints (nécessitant une licence commerciale distincte) incluent :

- Proposer un « hébergement Sovrium Cloud » comme service à des clients
- Intégrer Sovrium comme fonctionnalité centrale d'une plateforme SaaS proposée à des tiers
- Fournir des instances Sovrium managées comme offre commerciale
- Marque blanche de Sovrium revendu comme service hébergé

## Date de bascule

Le **2030-06-02** — quatre ans après la publication de cette version — la licence se convertit automatiquement en **Apache License, Version 2.0**. À partir de cette date, la version correspondante de Sovrium est pleinement open source.

## Droit d'auteur

L'œuvre sous licence est Copyright (c) 2025-2026 ESSENTIAL SERVICES. Chaque fichier source porte l'en-tête BSL 1.1.

## Licence commerciale

Si votre usage relève de la restriction ci-dessus, une licence commerciale est disponible. Contactez **license@sovrium.com**.

## Voir aussi

- [Marque déposée](/fr/trademark) — comment utiliser le nom et le logo « Sovrium »
- [Contribuer](/fr/contributing) — comment proposer des changements

# Marque déposée

**Sovrium** est une marque déposée d'**ESSENTIAL SERVICES** (enregistrée en France, et potentiellement dans d'autres juridictions). Cette page résume les conditions d'utilisation de la marque. La notice complète se trouve dans [`TRADEMARK.md`](https://github.com/sovrium/sovrium/blob/main/TRADEMARK.md) à la racine du dépôt.

## Droit d'auteur et marque

Le projet sépare délibérément le droit d'auteur et la marque :

| Aspect juridique | Titulaire          | Ce qu'il protège                                                             |
| ---------------- | ------------------ | ---------------------------------------------------------------------------- |
| Droit d'auteur   | ESSENTIAL SERVICES | Le code source, la documentation et les œuvres (sous [BSL 1.1](/fr/license)) |
| Marque           | ESSENTIAL SERVICES | Le nom de marque « Sovrium » et le logo                                      |
| Domaine          | ESSENTIAL SERVICES | La propriété web sovrium.com                                                 |

Cette séparation permet au code de devenir un jour open source tout en gardant la marque protégée.

## Usage permis

Vous pouvez utiliser le nom « Sovrium » pour :

- Désigner ce logiciel de manière factuelle (« construit avec Sovrium », « compatible avec Sovrium »)
- Décrire votre propre projet qui utilise Sovrium (« MonApp utilise Sovrium pour son backend »)
- Contribuer au projet Sovrium
- Rédiger des tutoriels ou de la documentation sur Sovrium

## Usage interdit

Vous ne pouvez **pas** utiliser « Sovrium » pour :

- Nommer votre propre produit ou service (par ex. « Sovrium Cloud », « Sovrium Plus »)
- Laisser entendre un soutien officiel sans autorisation
- Créer une confusion sur l'origine d'un produit
- Déposer des marques ou noms de domaine similaires

## Usage commercial et de la marque

L'usage commercial du **logiciel** Sovrium nécessite une licence commerciale (voir [Licence](/fr/license)). L'usage de la **marque** Sovrium en contexte commercial nécessite l'autorisation explicite d'ESSENTIAL SERVICES.

Pour toute demande de licence de marque, contactez **license@sovrium.com**.

## Voir aussi

- [Licence](/fr/license) — les termes BSL 1.1 pour le code
- [Contribuer](/fr/contributing) — comment proposer des changements

# Contribuer

Sovrium se construit au grand jour et accueille les contributions. Que vous corrigiez une faute, amélioriez la documentation, signaliez un bug ou proposiez une fonctionnalité, cette page explique comment démarrer.

## Façons de contribuer

- **Signaler un bug ou demander une fonctionnalité** — ouvrez une issue sur [GitHub](https://github.com/sovrium/sovrium/issues) avec une description claire et, si possible, une reproduction minimale.
- **Améliorer la documentation** — ces pages font partie du dépôt ; les corrections et clarifications sont toujours bienvenues.
- **Soumettre une pull request** — implémentez un correctif ou une fonctionnalité et ouvrez une PR pour relecture (nécessite une certification — voir ci-dessous).

## Devenir contributeur certifié

Ouvrir des issues et signaler des bugs est ouvert à tout le monde. **Soumettre du code, en revanche, requiert de devenir un contributeur certifié.** Pour obtenir votre certification, contactez-nous à **contribute@sovrium.com** et nous vous accompagnerons dans la démarche.

Nous avons instauré cette étape de façon délibérée. Le volume de pull requests non sollicitées et générées par IA a rendu la contribution ouverte intenable pour de nombreux projets — les mainteneurs passent plus de temps à trier des correctifs bâclés et écrits par des machines qu'à construire. La certification nous permet de :

- **Préserver notre capacité de relecture pour le vrai travail** — nous ne sommes pas submergés par un flot de PR automatisées et opportunistes.
- **Garantir une communauté de contributeurs de qualité** — les contributeurs certifiés comprennent le code, l'architecture et les standards avant de livrer.

La certification n'est ni un péage ni un concours de popularité — c'est un court échange pour confirmer que vous êtes une personne qui contribuera avec soin. Une fois certifié, vos pull requests sont relues et fusionnées comme toutes les autres.

## Avant de commencer

- Parcourez les [issues](https://github.com/sovrium/sovrium/issues) et pull requests existantes pour éviter de dupliquer le travail.
- Pour tout changement non trivial, ouvrez d'abord une issue afin de discuter de l'approche avant d'écrire du code — cela fait gagner du temps à tout le monde.
- En contribuant, vous acceptez que votre contribution soit placée sous la [Business Source License 1.1](/fr/license) du projet.

## Mise en place de l'environnement

Sovrium fonctionne sur [Bun](https://bun.sh) (1.3+). Clonez le dépôt et installez les dépendances :

```bash
git clone https://github.com/sovrium/sovrium
cd sovrium
bun install
```

Lancez l'application depuis les sources :

```bash
bun run start chemin/vers/votre/app.ts
```

Validez un fichier de configuration par rapport au schéma :

```bash
bun run src/cli/index.ts validate chemin/vers/votre/app.ts
```

## Conventions de code

- **TypeScript** partout, écrit pour le runtime Bun.
- **Commits conventionnels** — préfixez vos messages par `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, etc.
- Gardez des changements ciblés — un changement logique par pull request accélère la relecture.
- Respectez le style du code environnant ; le formateur et le linter du dépôt définissent les conventions.

## Soumettre une pull request

1. Forkez le dépôt et créez une branche de travail.
2. Effectuez votre changement avec un message de commit conventionnel et clair.
3. Ouvrez une pull request décrivant **ce qui** change et **pourquoi**.
4. Répondez aux retours de relecture — les mainteneurs vous aideront à mener le changement jusqu'à la fusion.

## Note sur la marque

Contribuer au code ne confère aucun droit sur le nom ou le logo **Sovrium**. Voir la page [Marque déposée](/fr/trademark) pour l'usage autorisé de la marque.

## Voir aussi

- [Licence](/fr/license) — les termes BSL 1.1
- [Marque déposée](/fr/trademark) — conditions d'utilisation de la marque