diff --git a/apps/docs/src/components/project-tabs.tsx b/apps/docs/src/components/project-tabs.tsx
index ebcd9a2..80fb034 100644
--- a/apps/docs/src/components/project-tabs.tsx
+++ b/apps/docs/src/components/project-tabs.tsx
@@ -30,7 +30,7 @@ export function ProjectTabs({ projects, currentProject, switchUrls }: ProjectTab
               )}
             >
               {project.icon && <Icon icon={`lucide:${project.icon}`} className="size-4 shrink-0" />}
-              {project.name}
+              {project.title ?? project.name}
             </a>
           )
         })}
diff --git a/apps/docs/src/content/docs/cli/_meta.json b/apps/docs/src/content/docs/cli/_meta.json
index 0c598ea..fac61a5 100644
--- a/apps/docs/src/content/docs/cli/_meta.json
+++ b/apps/docs/src/content/docs/cli/_meta.json
@@ -1,4 +1,5 @@
 {
   "icon": "terminal",
-  "title": "CLI"
+  "title": "Cli",
+  "order": 5
 }
diff --git a/apps/docs/src/content/docs/discover/_meta.json b/apps/docs/src/content/docs/discover/_meta.json
index 8f98ca8..5ee043f 100644
--- a/apps/docs/src/content/docs/discover/_meta.json
+++ b/apps/docs/src/content/docs/discover/_meta.json
@@ -1,4 +1,5 @@
 {
   "icon": "book-open",
-  "title": "Discover"
+  "title": "Discover",
+  "order": 1
 }
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx b/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx
index 98df5c5..4c7efb7 100644
--- a/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx
@@ -2,7 +2,7 @@
 title: Architecture
 description: "Hexagonal architecture, domain modules, and the ports & adapters pattern in FerrisKey."
 icon: boxes
-order: 21
+order: 22
 ---
 
 # Architecture
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx b/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx
index 805e22c..c8e29a4 100644
--- a/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx
@@ -2,7 +2,7 @@
 title: Contributing
 description: "How to contribute issues, documentation, code, tests, and pull requests to FerrisKey."
 icon: git-pull-request
-order: 22
+order: 23
 ---
 
 # Contributing
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/email.mdx b/apps/docs/src/content/docs/discover/default/en/guides/email.mdx
new file mode 100644
index 0000000..8a7bf34
--- /dev/null
+++ b/apps/docs/src/content/docs/discover/default/en/guides/email.mdx
@@ -0,0 +1,239 @@
+---
+title: Email & Templates
+description: "Configure SMTP and customize transactional email templates in FerrisKey: password reset, magic link, and email verification."
+icon: mail
+order: 21
+---
+
+# Email & Templates
+
+FerrisKey sends transactional emails for password resets, magic link authentication, and email verification. Delivery is configured per realm through a dedicated SMTP setup, and each email type can be customized with your own HTML template.
+
+## Configure SMTP
+
+SMTP is stored in the database at the realm level — not as a global environment variable. Each realm can use a different mail provider independently.
+
+:::callout{variant="info" title="No global SMTP"}
+SMTP is configured per realm, not globally. See the [Configuration guide](/en/discover/guides/configuration) for the short overview. This page covers the full field reference and API.
+:::
+
+### SMTP Fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `host` | String | SMTP server hostname |
+| `port` | u16 | Port number (1–65535) |
+| `username` | String | SMTP authentication username |
+| `password` | String | SMTP authentication password — write-only, never returned by the API |
+| `from_email` | String | Sender address, must be a valid email |
+| `from_name` | String | Sender display name |
+| `encryption` | Enum | `tls` \| `starttls` \| `none` |
+
+**Encryption modes:**
+
+| Mode | Port | When to use |
+|---|---|---|
+| `tls` | 465 | Implicit TLS from the first byte — preferred for modern providers |
+| `starttls` | 587 | Plain connection upgraded to TLS — common in corporate relays |
+| `none` | 25 / any | No encryption — use only on a trusted local network or for testing |
+
+### SMTP API Endpoints
+
+All endpoints are scoped to a realm and require authentication.
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/smtp-config` | Read the current config (password omitted) |
+| `PUT` | `/realms/{realm_name}/smtp-config` | Create or replace the config |
+| `DELETE` | `/realms/{realm_name}/smtp-config` | Remove the config |
+
+**Required permissions:** reading SMTP config requires view access to the realm. Creating, updating, or deleting requires `ManageRealm`. There are no dedicated SMTP permissions beyond the realm permission gates.
+
+### Configure SMTP in the Console
+
+::::step-group
+:::step{title="Open Realm Settings"}
+In the left sidebar, select the realm you want to configure. Navigate to **Realm Settings**.
+:::
+
+:::step{title="Go to the Email tab"}
+Click the **Email** tab. You will see the SMTP configuration form.
+:::
+
+:::step{title="Fill in the provider details"}
+Enter the host, port, credentials, sender address and name. Select the encryption mode that matches your provider.
+
+Common provider settings:
+
+| Provider | Host | Port | Encryption |
+|---|---|---|---|
+| Gmail (App Password) | `smtp.gmail.com` | 465 | `tls` |
+| Mailgun | `smtp.mailgun.org` | 587 | `starttls` |
+| Resend | `smtp.resend.com` | 465 | `tls` |
+| Local (MailHog / MailPit) | `localhost` | 1025 | `none` |
+:::
+
+:::step{title="Save and verify"}
+Click **Save**. Send a test email from the console to confirm delivery reaches the inbox before enabling email-gated features.
+:::
+::::
+
+:::callout{variant="warning" title="Password is write-only"}
+The API never returns the SMTP password. If you need to rotate credentials, submit a full `PUT` with the new password included.
+:::
+
+---
+
+## Transactional Emails
+
+FerrisKey sends exactly three types of transactional email. Each is tied to a realm feature toggle.
+
+| Email type | Identifier | Sent when | Realm toggle required |
+|---|---|---|---|
+| Password reset | `reset_password` | A user requests a password reset link | `forgot_password_enabled` |
+| Magic link | `magic_link` | A user requests passwordless email login | `magic_link_enabled` |
+| Email verification | `email_verification` | A user must verify their email address | `email_verification_enabled` |
+
+Enabling these toggles in Realm Settings activates the corresponding flow. FerrisKey will use the default built-in template unless you assign a custom one.
+
+---
+
+## Customizing Templates
+
+### Template Engine
+
+FerrisKey uses a lightweight custom interpolation engine — not Handlebars or Tera. Placeholders use double-brace syntax:
+
+```text
+{{variable_name}}
+```
+
+All interpolated values are HTML-escaped before insertion (`&`, `<`, `>`, `"`, `'`), which prevents injection attacks in the rendered email.
+
+:::callout{variant="info" title="HTML escaping"}
+Values inserted via `{{...}}` are always HTML-escaped. If a user's name is `Alice <script>`, it renders as `Alice &lt;script&gt;` in the final email — safe to embed in HTML.
+:::
+
+Templates are stored as a JSON `structure` that FerrisKey renders to MJML and then to HTML before sending.
+
+### Available Variables
+
+These variables are available in every template:
+
+| Variable | Description |
+|---|---|
+| `user.first_name` | User's first name |
+| `user.last_name` | User's last name |
+| `user.email` | User's email address |
+| `expiration` | Expiry time of the token or link |
+
+Each email type also provides one link variable:
+
+| Email type | Link variable | Description |
+|---|---|---|
+| `reset_password` | `reset_link` | The password-reset URL |
+| `magic_link` | `magic_link` | The passwordless login URL |
+| `email_verification` | `verification_link` | The email verification URL |
+
+You can query the available variables for any type without authentication:
+
+```
+GET /email-templates/variables/{email_type}
+```
+
+`email_type` must be one of: `reset_password`, `magic_link`, `email_verification`.
+
+Example response for `reset_password`:
+
+```json title="GET /email-templates/variables/reset_password"
+{
+  "data": [
+    { "name": "user.first_name", "description": "User's first name" },
+    { "name": "user.last_name", "description": "User's last name" },
+    { "name": "user.email", "description": "User's email address" },
+    { "name": "expiration", "description": "Expiration time" },
+    { "name": "reset_link", "description": "Password reset link" }
+  ]
+}
+```
+
+### Template API Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/email-templates` | List all templates for the realm |
+| `POST` | `/realms/{realm_name}/email-templates` | Create a new template |
+| `GET` | `/realms/{realm_name}/email-templates/{template_id}` | Get a template by ID |
+| `PUT` | `/realms/{realm_name}/email-templates/{template_id}` | Update a template |
+| `DELETE` | `/realms/{realm_name}/email-templates/{template_id}` | Delete a template |
+
+**Request body for `POST`:** `name`, `email_type`, `structure`.
+
+**Request body for `PUT`:** `name`, `structure` (`email_type` cannot be changed after creation).
+
+**Required permissions:** `ViewEmailTemplates` to read. `ManageEmailTemplates` to create, update, or delete. `ManageRealm` also grants both.
+
+### Linking a Template to an Email Type
+
+Creating a template does not activate it automatically. You must link it to the realm by updating the realm settings:
+
+| Realm setting field | Applies to |
+|---|---|
+| `reset_password_template_id` | `reset_password` emails |
+| `magic_link_template_id` | `magic_link` emails |
+| `email_verification_template_id` | `email_verification` emails |
+
+Set the field to the template UUID to activate it. Set it to `null` (or leave it unset) to fall back to the built-in default.
+
+---
+
+## Example
+
+### Template snippet
+
+A minimal password-reset template body using placeholder syntax:
+
+```html title="Reset password template (body excerpt)"
+<p>Hi {{user.first_name}},</p>
+
+<p>
+  Someone requested a password reset for your account (<strong>{{user.email}}</strong>).
+  This link expires in {{expiration}}.
+</p>
+
+<p>
+  <a href="{{reset_link}}">Reset your password</a>
+</p>
+
+<p>If you did not request this, you can safely ignore this email.</p>
+```
+
+### Variables response
+
+```json title="GET /email-templates/variables/magic_link"
+{
+  "data": [
+    { "name": "user.first_name", "description": "User's first name" },
+    { "name": "user.last_name", "description": "User's last name" },
+    { "name": "user.email", "description": "User's email address" },
+    { "name": "expiration", "description": "Expiration time" },
+    { "name": "magic_link", "description": "Magic link URL" }
+  ]
+}
+```
+
+---
+
+::::card-group{cols=2}
+:::card{label="Configuration" icon="lucide:settings" href="/en/discover/guides/configuration"}
+Environment variables, deployment options, and the overview of SMTP setup.
+:::
+
+:::card{label="Magic Links" icon="lucide:mail" href="/en/modules/trident/magic-links"}
+How passwordless magic-link authentication works in FerrisKey.
+:::
+
+:::card{label="Realms" icon="lucide:layers" href="/en/discover/core-concepts/realms"}
+Realm concepts, settings, and multi-tenancy model.
+:::
+::::
diff --git a/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx b/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx
index 346c997..44c92c5 100644
--- a/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx
@@ -50,6 +50,9 @@ Scopes and protocol mappers to control what goes into your tokens.
 :::card{label="Webhooks" icon="lucide:webhook" href="/en/modules/webhooks/overview"}
 Event-driven integrations for lifecycle events and external notifications.
 :::
+:::card{label="Organizations" icon="lucide:building-2" href="/en/modules/organization/overview"}
+B2B tenancy that groups users into organizations with shared membership and custom attributes.
+:::
 ::::
 
 ## Next Steps
diff --git a/apps/docs/src/content/docs/kubernetes/_meta.json b/apps/docs/src/content/docs/kubernetes/_meta.json
index c3b2008..d5fddf8 100644
--- a/apps/docs/src/content/docs/kubernetes/_meta.json
+++ b/apps/docs/src/content/docs/kubernetes/_meta.json
@@ -1,4 +1,5 @@
 {
   "icon": "container",
-  "title": "Kubernetes"
+  "title": "Kubernetes",
+  "order": 4
 }
diff --git a/apps/docs/src/content/docs/learn/_meta.json b/apps/docs/src/content/docs/learn/_meta.json
index be5dfb0..7f6c184 100644
--- a/apps/docs/src/content/docs/learn/_meta.json
+++ b/apps/docs/src/content/docs/learn/_meta.json
@@ -1,4 +1,5 @@
 {
   "icon": "graduation-cap",
-  "title": "Learn"
+  "title": "Learn",
+  "order": 2
 }
diff --git a/apps/docs/src/content/docs/modules/_meta.json b/apps/docs/src/content/docs/modules/_meta.json
index 64cde27..a3b55dd 100644
--- a/apps/docs/src/content/docs/modules/_meta.json
+++ b/apps/docs/src/content/docs/modules/_meta.json
@@ -1,4 +1,5 @@
 {
   "icon": "puzzle",
-  "title": "Modules"
+  "title": "Modules",
+  "order": 3
 }
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/_meta.json b/apps/docs/src/content/docs/modules/default/en/organization/_meta.json
new file mode 100644
index 0000000..e999e83
--- /dev/null
+++ b/apps/docs/src/content/docs/modules/default/en/organization/_meta.json
@@ -0,0 +1,6 @@
+{
+  "icon": "building-2",
+  "title": "Organizations",
+  "type": "group",
+  "order": 8
+}
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/attributes.mdx b/apps/docs/src/content/docs/modules/default/en/organization/attributes.mdx
new file mode 100644
index 0000000..3c18cc2
--- /dev/null
+++ b/apps/docs/src/content/docs/modules/default/en/organization/attributes.mdx
@@ -0,0 +1,85 @@
+---
+title: Attributes
+description: "Custom key-value metadata on FerrisKey organizations."
+icon: tags
+order: 82
+---
+
+# Attributes
+
+Attributes are custom key-value pairs attached to an organization. They let you store arbitrary metadata on an organization without extending the core schema — useful for subscription tiers, external system IDs, feature flags, and any other business data that belongs with the organization record.
+
+## Attribute Endpoints
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/organizations/{organization_id}/attributes` | List all attributes for an organization |
+| `PUT` | `/realms/{realm_name}/organizations/{organization_id}/attributes/{key}` | Upsert an attribute by key |
+| `DELETE` | `/realms/{realm_name}/organizations/{organization_id}/attributes/{key}` | Delete an attribute by key |
+
+## Upsert Semantics
+
+The `PUT` endpoint upserts by key: if the key already exists, its value is overwritten; if it does not exist, a new attribute is created. There is no separate create endpoint.
+
+```json title="PUT /realms/acme/organizations/{org_id}/attributes/plan"
+{
+  "value": "enterprise"
+}
+```
+
+Both `key` and `value` are required. An empty or missing value is rejected.
+
+## Attribute Fields
+
+| Field | Type | Constraints | Description |
+|---|---|---|---|
+| `id` | UUID v7 | — | Auto-generated identifier |
+| `organization_id` | UUID | — | The organization this attribute belongs to |
+| `key` | String | 1–255 characters, required | Attribute name |
+| `value` | String | Required | Attribute value |
+| `created_at` | DateTime (UTC) | — | Creation timestamp (set on first upsert, not updated on overwrites) |
+
+## Example: Multiple Attributes
+
+A typical organization might carry several attributes:
+
+```json title="GET /realms/acme/organizations/{org_id}/attributes"
+[
+  {
+    "id": "01936b2e-aaaa-7000-abcd-000000000001",
+    "organization_id": "01936b2e-1234-7000-abcd-000000000001",
+    "key": "plan",
+    "value": "enterprise",
+    "created_at": "2026-01-15T09:00:00Z"
+  },
+  {
+    "id": "01936b2e-bbbb-7000-abcd-000000000002",
+    "organization_id": "01936b2e-1234-7000-abcd-000000000001",
+    "key": "stripe_customer_id",
+    "value": "cus_Qx8mN2kLpR4t",
+    "created_at": "2026-01-15T09:01:00Z"
+  },
+  {
+    "id": "01936b2e-cccc-7000-abcd-000000000003",
+    "organization_id": "01936b2e-1234-7000-abcd-000000000001",
+    "key": "feature_advanced_reporting",
+    "value": "true",
+    "created_at": "2026-03-01T14:30:00Z"
+  }
+]
+```
+
+## Real-World Uses
+
+| Key pattern | Example value | Use case |
+|---|---|---|
+| `plan` | `free`, `pro`, `enterprise` | Gate features by subscription tier |
+| `stripe_customer_id` | `cus_Qx8mN2kLpR4t` | Link to billing provider |
+| `salesforce_account_id` | `001Dn00000KjlHSIAZ` | Link to CRM record |
+| `feature_<name>` | `true` / `false` | Per-org feature flags |
+| `max_seats` | `50` | Enforce seat limits in application logic |
+| `onboarded_at` | `2026-01-15` | Track onboarding completion |
+
+:::callout{variant="warning" title="Values are always strings"}
+Attributes store strings only. Numeric values (`50`), booleans (`true`), and dates (`2026-01-15`) are stored as their string representations. Your application is responsible for parsing them back to the appropriate type.
+:::
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/members.mdx b/apps/docs/src/content/docs/modules/default/en/organization/members.mdx
new file mode 100644
index 0000000..e001f07
--- /dev/null
+++ b/apps/docs/src/content/docs/modules/default/en/organization/members.mdx
@@ -0,0 +1,91 @@
+---
+title: Members
+description: "Manage organization membership in FerrisKey: add, remove, and list members, and look up a user's organizations."
+icon: users
+order: 81
+---
+
+# Members
+
+Membership connects a user to an organization. A user can belong to multiple organizations within the same realm, and an organization can have any number of members. Membership is flat: there are no per-member roles or permissions inside an organization.
+
+## Membership Endpoints
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/organizations/{organization_id}/members` | List all members of an organization |
+| `POST` | `/realms/{realm_name}/organizations/{organization_id}/members` | Add a user to an organization |
+| `DELETE` | `/realms/{realm_name}/organizations/{organization_id}/members/{user_id}` | Remove a user from an organization |
+| `GET` | `/realms/{realm_name}/users/{user_id}/organizations` | List all organizations a user belongs to |
+
+## Adding a Member
+
+Send the target `user_id` in the request body:
+
+```json title="POST /realms/acme/organizations/01936b2e-1234-7000-abcd-000000000001/members"
+{
+  "user_id": "01936b2e-5678-7000-abcd-000000000002"
+}
+```
+
+A successful addition returns the new membership record:
+
+```json
+{
+  "id": "01936b2e-9999-7000-abcd-000000000003",
+  "organization_id": "01936b2e-1234-7000-abcd-000000000001",
+  "user_id": "01936b2e-5678-7000-abcd-000000000002",
+  "created_at": "2026-06-16T10:00:00Z"
+}
+```
+
+## Adding a Member Step by Step
+
+::::step-group
+:::step{title="Confirm the organization is enabled"}
+A disabled organization (`enabled: false`) rejects new member additions. Check the organization's `enabled` field before attempting to add members. Re-enable it with a `PUT` to the organization endpoint if needed.
+:::
+
+:::step{title="Confirm the user is in the same realm"}
+The user must belong to the same realm as the organization. Cross-realm membership is rejected. Verify `realm_id` on the organization matches the realm the user was created in.
+:::
+
+:::step{title="POST to the members endpoint"}
+Send `{ "user_id": "<uuid>" }` to `POST /realms/{realm_name}/organizations/{organization_id}/members`. The user is added immediately.
+:::
+
+:::step{title="Verify with a list call"}
+Confirm the user appears in `GET /realms/{realm_name}/organizations/{organization_id}/members` or in `GET /realms/{realm_name}/users/{user_id}/organizations`.
+:::
+::::
+
+## Behavior Rules
+
+| Situation | Result |
+|---|---|
+| User already a member of this organization | `AlreadyExists` error — duplicate membership is rejected |
+| User is in a different realm than the organization | Request rejected |
+| Organization is disabled (`enabled: false`) | Request rejected |
+| Removing a user who is not a member | `NotFound` error |
+
+## Listing a User's Organizations
+
+To find every organization a specific user belongs to across the realm:
+
+```
+GET /realms/{realm_name}/users/{user_id}/organizations
+```
+
+This returns an array of membership records — each carrying the `organization_id`, `user_id`, and `created_at` (the same `OrganizationMember` shape returned when adding a member), not full organization objects. Resolve each `organization_id` against `GET /realms/{realm_name}/organizations/{organization_id}` for full details. Use this to build a workspace switcher, enforce org-level feature access, or display the user's account context.
+
+## Removing a Member
+
+```
+DELETE /realms/{realm_name}/organizations/{organization_id}/members/{user_id}
+```
+
+Membership removal is immediate. If the user is not a member, the call returns `NotFound`. There is no cascading effect on the user's account — the user record itself is untouched.
+
+:::callout{variant="info" title="Flat membership — org-scoped roles are roadmap"}
+Every member has the same standing inside an organization. There is no `role` field on a membership record, and no way to mark a member as owner, admin, or viewer at the organization level. Organization-scoped RBAC is planned but not yet implemented. For now, use realm-level roles to differentiate access.
+:::
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/overview.mdx b/apps/docs/src/content/docs/modules/default/en/organization/overview.mdx
new file mode 100644
index 0000000..8f8aef7
--- /dev/null
+++ b/apps/docs/src/content/docs/modules/default/en/organization/overview.mdx
@@ -0,0 +1,95 @@
+---
+title: Overview
+description: "Organizations in FerrisKey: B2B tenancy that groups users with shared membership and custom attributes."
+icon: building-2
+order: 80
+---
+
+# Organizations
+
+Organizations are a B2B grouping layer inside a realm. A single realm can contain many organizations; a user can belong to many organizations simultaneously; and each organization can carry custom key-value metadata. Together, these primitives cover the most common multi-tenant SaaS pattern: customers are organizations, users are members.
+
+:::callout{variant="info" title="New to B2B identity?"}
+For conceptual background on how customer-facing (B2B/CIAM) identity differs from workforce IAM, see [What is CIAM?](/en/learn/ciam/overview) and [Branding, Portals & Org Policies](/en/learn/ciam/org-policies) in the Learn section.
+:::
+
+## Why Organizations?
+
+Realms provide isolation at the deployment level — one realm per product, or per environment. Organizations sit one level below that. They let you model the business structure of your customers without spinning up a new realm per customer.
+
+Use organizations when:
+
+- Your users belong to customer accounts that have distinct identities (company name, billing plan, external IDs).
+- You need to list every organization a given user belongs to, or every member of a given organization.
+- You want to attach arbitrary metadata to a customer account (CRM ID, subscription tier, feature flags) without extending the user schema.
+
+Use a separate realm per tenant instead when you need complete credential isolation, different authentication policies, or different token lifetimes per tenant.
+
+## Organization Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | UUID v7 | — | Auto-generated identifier |
+| `realm_id` | UUID | — | The realm this organization belongs to |
+| `name` | String (1–255) | Yes | Human-readable label |
+| `alias` | String (1–255) | Yes | URL-safe identifier — lowercase alphanumeric, `-`, and `_`. Unique per realm |
+| `domain` | String (≤255) | No | Optional email domain. Stored and validated but **not yet used** for automatic onboarding — see Roadmap below |
+| `redirect_url` | String | No | Optional callback URL |
+| `description` | String | No | Optional free-text description |
+| `enabled` | Boolean | No | Defaults to `true`. A disabled organization rejects new member additions |
+| `created_at` | DateTime (UTC) | — | Creation timestamp |
+| `updated_at` | DateTime (UTC) | — | Last-modified timestamp |
+
+## Realm Scoping
+
+Every organization belongs to exactly one realm. All API endpoints are realm-scoped:
+
+```
+/realms/{realm_name}/organizations
+```
+
+A user and the organization they join must be in the same realm. Cross-realm membership is rejected.
+
+The `alias` must be unique within the realm. Attempting to create or update an organization with a duplicate alias returns a `AlreadyExists` error.
+
+## The `enabled` Flag
+
+Setting `enabled: false` on an organization freezes membership additions — the `POST /members` endpoint will reject new requests. Existing members are unaffected. Use this to suspend an organization without deleting it or removing all its members.
+
+## Permissions
+
+| Action | Required permission |
+|---|---|
+| List, view organization | `ManageRealm` or `ManageUsers` or `ViewUsers` |
+| Create, update organization | `ManageRealm` or `ManageUsers` |
+| Manage members and attributes | `ManageRealm` or `ManageUsers` |
+| Delete organization | `ManageRealm` only |
+
+There are no organization-specific permissions. All access control uses the realm-level permissions above.
+
+:::callout{variant="info" title="Roadmap"}
+The following features are planned but not yet implemented:
+
+- **Organization-scoped roles**: membership is currently flat — there is no per-member role or permission within an organization.
+- **Domain-based auto-onboarding**: the `domain` field is stored and validated, but FerrisKey does not yet automatically assign users to an organization based on their email domain.
+- **Organization policies**: forced SSO, domain-matching rules, and org-level authentication policies are aspirational and not shipped.
+- **Soft delete**: deletes are hard (permanent). There is no archive or restore flow.
+:::
+
+## When to Use Organizations vs. Separate Realms
+
+| Scenario | Recommendation |
+|---|---|
+| B2B SaaS, customers share auth policies | Organizations within one realm |
+| Customers need completely different token lifetimes or IdP federation | Separate realms per customer |
+| Internal multi-team product | Organizations within one realm |
+| Regulated multi-tenant isolation (data residency) | Separate realms |
+
+::::card-group{cols=2}
+:::card{label="Members" icon="lucide:users" href="/en/modules/organization/members"}
+Add, remove, and list organization members, and look up which organizations a user belongs to.
+:::
+:::card{label="Attributes" icon="lucide:tags" href="/en/modules/organization/attributes"}
+Attach custom key-value metadata to an organization — plan tier, CRM IDs, feature flags.
+:::
+::::
diff --git a/apps/docs/src/content/docs/modules/default/en/overview.mdx b/apps/docs/src/content/docs/modules/default/en/overview.mdx
index 6758ec3..5a5d103 100644
--- a/apps/docs/src/content/docs/modules/default/en/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/overview.mdx
@@ -28,6 +28,9 @@ FerrisKey is built as a collection of purpose-built modules. Each module owns a
 :::card{label="Webhooks" icon="lucide:webhook" href="/en/modules/webhooks/overview"}
 **Event-Driven Extensibility**: Subscribe to lifecycle events and push notifications to external systems.
 :::
+:::card{label="Organizations" icon="lucide:building-2" href="/en/modules/organization/overview"}
+**B2B Tenancy**: Group users into organizations with membership and custom attributes.
+:::
 ::::
 
 ## Module Architecture
diff --git a/apps/docs/src/lib/docs.ts b/apps/docs/src/lib/docs.ts
index 4d8e893..6e66baa 100644
--- a/apps/docs/src/lib/docs.ts
+++ b/apps/docs/src/lib/docs.ts
@@ -22,6 +22,8 @@ export interface ProjectInfo {
   versions: string[]
   hasVersioning: boolean
   icon?: string
+  title?: string
+  order?: number
 }
 
 export interface DocsContext {
@@ -80,12 +82,19 @@ export function getProjectsInfo(entries: CollectionEntry<'docs'>[], metaFiles?:
     projectMap.get(project)!.add(version)
   }
 
-  return Array.from(projectMap.entries()).map(([name, versions]) => ({
-    name,
-    versions: Array.from(versions).sort(),
-    hasVersioning: versions.size > 1 || !versions.has('default'),
-    icon: metaFiles?.[name]?.icon,
-  }))
+  return Array.from(projectMap.entries())
+    .map(([name, versions]) => ({
+      name,
+      versions: Array.from(versions).sort(),
+      hasVersioning: versions.size > 1 || !versions.has('default'),
+      icon: metaFiles?.[name]?.icon,
+      title: metaFiles?.[name]?.title,
+      order: metaFiles?.[name]?.order ?? Infinity,
+    }))
+    .sort((a, b) => {
+      if (a.order !== b.order) return a.order - b.order
+      return (a.title ?? a.name).localeCompare(b.title ?? b.name)
+    })
 }
 
 /** Extract all unique locales from the collection */