docs: add Organizations & Permissions section under AI builder [ENG-10395]

docs/ai_builder/organization/audit_logs.md

@@ -0,0 +1,55 @@
+---
+tags: Organization
+description: Review a record of who did what in your Reflex organization and projects, with search, filtering, and CSV export.
+---
+
+# Audit Logs
+
+```python exec
+import reflex as rx
+```
+
+An **audit log** records the important actions taken in your organization: who did what, and when. It answers questions like *who removed this member?* or *when was this domain verified?* for security reviews, compliance, or day-to-day troubleshooting.
+
+Reflex keeps audit logs at two levels: one for the **organization** and one for each **project**.
+
+## The organization audit log
+
+Open your organization's **Settings → Audit log** to see organization-wide activity, such as member and role changes, domain and single sign-on changes, and other administrative actions.
+
+Each entry shows:
+
+- **Time**: when the action happened.
+- **Event**: what happened, with a short summary.
+- **Actor**: who did it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/audit-logs/org_audit_log.webp",
+    alt="The organization audit log table showing Time, Event, and Actor columns with a search box and event filter",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Who can view the audit log
+The organization audit log is available to organization **admins** and **managers**. Members don't have access.
+```
+
+### Finding an entry
+
+The audit log supports:
+
+- **Search** across events, actors, and details.
+- **Filter** by event type.
+- **Export to CSV** for reporting or to share with your security team.
+- **Refresh** for the latest activity.
+
+## Project audit logs
+
+Each project has its own audit log, under the project's **Settings → Audit log**, covering activity within that project. Viewing it requires the **View audit log** permission, which comes with the project **Admin** role and can be added to a [custom role](/docs/ai/organization/custom-roles/).
+
+## Related
+
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — who can see each audit log.
+- [Deployment approvals](/docs/ai/organization/deployment-approvals/) — a checkpoint before deployments run.

docs/ai_builder/organization/cloud_providers.md

@@ -0,0 +1,84 @@
+---
+tags: Organization
+description: Connect your own cloud provider account to a Reflex organization so its apps deploy to infrastructure you control.
+---
+
+# Bring Your Own Cloud
+
+```python exec
+import reflex as rx
+```
+
+By default, apps run on Reflex's infrastructure. On the **Enterprise** plan, you can connect your organization's own cloud account instead, so apps run on infrastructure you control and are billed directly by your provider. This is often required by security, procurement, or data-residency policies.
+
+You connect a cloud account once, at the organization level, under **Settings → Cloud providers**. The whole organization can then deploy to it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/cloud-providers/providers_overview.webp",
+    alt="The Cloud providers tab showing Google Cloud connected, with AWS and Azure greyed out and unavailable",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Who can connect a cloud provider
+Only organization admins can connect, view, or remove cloud provider accounts. Connecting is an Enterprise feature; [contact sales](https://reflex.dev/pricing/) to enable it.
+```
+
+## Supported providers
+
+**Google Cloud** is available now. **AWS** and **Azure** aren't available yet.
+
+## Connecting Google Cloud
+
+Connecting Google Cloud takes two steps:
+
+1. **Run the setup.** Reflex provides a script that prepares your Google Cloud project and creates the credentials it needs. Select **Copy agent setup** to copy a prompt you can hand to an AI coding agent to run the steps for you.
+2. **Enter the details.** Select **Connect GCP** and paste the values the setup produced:
+   - the **service account key** (the contents of the key file),
+   - the **project number**,
+   - the **Cloud Run region** where apps should run, and
+   - optionally, an **Artifact Registry repository** name.
+
+Reflex validates the details and marks the provider connected.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/cloud-providers/connect_gcp.webp",
+    alt="The Connect your GCP account dialog with fields for the service account key, project number, and region",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# Your credentials are kept safe
+The service account key is stored encrypted and used only to deploy and manage your organization's apps.
+```
+
+Once connected, the tab shows the account's status, project, region, and repository.
+
+## Removing a connection
+
+To disconnect, open the connected provider and select **Remove connection**. Two effects:
+
+- New deployments to that cloud fail until an admin reconnects an account.
+- Apps already running there keep running, but Reflex can't manage them.
+
+## Deploying to your own cloud
+
+Connecting an account here lets your organization's apps target your cloud. You can also deploy to your own cloud from the command line. For the full workflow and provider details, see:
+
+- [Bring Your Own Cloud](/docs/hosting/bring-your-own-cloud/) — deploying to AWS, GCP, or Azure from the command line.
+- [Deploy to GCP Cloud Run](/docs/hosting/deploy-to-gcp/) — a detailed Google Cloud walkthrough.
+
+## Workload isolation and namespaces
+
+Each organization's apps run in their own isolated space on the underlying infrastructure, separate from other organizations. With bring-your-own-cloud, that isolation is inside your account.
+
+This separation is called a *namespace*. Reflex sets it up and manages it; you don't configure it yourself. Enterprise customers with specific isolation requirements can discuss custom arrangements with the Reflex team.
+
+## Related
+
+- [Bring Your Own Cloud (CLI)](/docs/hosting/bring-your-own-cloud/) — deploy from the command line.
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — who can manage organization settings.

docs/ai_builder/organization/custom_roles.md

@@ -0,0 +1,98 @@
+---
+tags: Organization
+description: Create custom project roles in Reflex, built on a base access level with the specific permissions your team needs.
+---
+
+# Custom Roles
+
+```python exec
+import reflex as rx
+```
+
+The built-in project roles (Viewer, Editor, and Admin) cover most cases, but sometimes you need something in between: a contractor who can build and deploy apps but nothing else, or a reviewer who can approve deployments without editing. A **custom role** defines that combination.
+
+Custom roles are created per project, under **Settings → Roles**, by anyone with the project **Admin** role.
+
+```md alert info
+# Custom roles are for teams
+Custom roles matter once you have teammates on a project. Inviting teammates is an Enterprise feature; see [Managing project access](/docs/ai/organization/project-access/).
+```
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/custom-roles/roles_list.webp",
+    alt="The project Roles tab listing built-in roles and a custom role, with a New role button",
+    class_name="rounded-md h-auto",
+)
+```
+
+## How a custom role is built
+
+A custom role has two parts:
+
+1. **Base access level**: Viewer, Editor, or Admin. The role includes everything that level can do.
+2. **Additional permissions**: individual abilities you add on top of the base level.
+
+Pick the closest built-in level, then add the permissions you need.
+
+## Creating a role
+
+Select **New role** and fill in:
+
+- **Role name**: a label your team will recognize, such as *Support lead* or *Release manager*.
+- **Base access**: the starting level (Viewer, Editor, or Admin).
+- **Additional permissions**: the abilities to add on top.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/custom-roles/create_role_dialog.webp",
+    alt="The Create role dialog showing a name field, a base access dropdown, and grouped permission checkboxes",
+    class_name="rounded-md h-auto",
+)
+```
+
+Permissions that come with the base level are shown ticked and greyed out; they're part of the role and can't be removed. You choose everything else.
+
+### The permissions you can add
+
+| Group | Permission | What it allows |
+| --- | --- | --- |
+| **Project** | Create apps | Add new apps to the project |
+| | Create threads | Start new Build chats in the project |
+| | Rename project | Change the project's name |
+| | Delete project | Permanently delete the project |
+| **Secrets & integrations** | Manage integrations | Connect and configure integrations |
+| | View secret names | See which secrets exist (names only) |
+| | Reveal secret values | See the value of a secret |
+| | Edit secrets | Add, change, and remove secrets |
+| **Deployments** | Approve deployments | Approve or reject deployments that need sign-off |
+| **Activity** | View audit log | See the project's activity history |
+
+```md alert info
+# Some permissions come as a set
+Revealing or editing secret values requires seeing the secret names, so turning on **Reveal secret values** or **Edit secrets** also includes **View secret names**.
+```
+
+## Permissions you can't delegate
+
+Two abilities stay with the built-in **Admin** role and can't be added to a custom role:
+
+- **Managing members** (adding people and changing their roles)
+- **Managing roles** (creating and editing roles)
+
+Either one amounts to admin control. If someone needs it, give them the Admin role. Billing isn't part of project roles either; it comes from a person's [organization role](/docs/ai/organization/roles-and-permissions/).
+
+## Assigning a custom role
+
+A custom role appears in the role dropdown wherever you assign project roles: when [adding members](/docs/ai/organization/project-access/) and when changing an existing member's role. Each custom role shows its base level and how many permissions it adds.
+
+## Editing and deleting roles
+
+From the Roles tab, **edit** a custom role to rename it or change its permissions. Built-in roles can't be edited and carry a **Built-in** badge.
+
+To **delete** a custom role, first reassign any members using it to another role. Reflex won't delete a role while members are still assigned to it.
+
+## Related
+
+- [Managing project access](/docs/ai/organization/project-access/) — assign a role to members.
+- [Roles & permissions](/docs/ai/organization/roles-and-permissions/) — how the built-in roles are made up.

docs/ai_builder/organization/deployment_approvals.md

@@ -0,0 +1,57 @@
+---
+tags: Organization
+description: Require deployments in a Reflex project to be approved before they go live, and manage the approval queue.
+---
+
+# Deployment Approvals
+
+```python exec
+import reflex as rx
+```
+
+You can require every deployment in a project to be **approved** before it runs. With approvals on, anyone can request a deployment, but it waits for sign-off from someone with permission. This gives the team a checkpoint before changes reach production.
+
+Deployment approvals are configured per project, under **Settings → Deploy approvals**.
+
+## Turning on approvals
+
+On the **Deploy approvals** tab, switch on **Require approval to deploy**. Deployments in the project are then held until approved.
+
+Only **project admins** can change this setting; others can see it but not change it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/deployment-approvals/approval_policy.webp",
+    alt="The Deploy approvals tab with the Require approval to deploy toggle switched on",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Who can approve
+
+Anyone with the **Approve deployments** permission can approve a deployment:
+
+- **Project admins**, who have it by default.
+- Anyone with a [custom role](/docs/ai/organization/custom-roles/) that grants **Approve deployments**.
+
+This separates who can request a deployment from who can approve one. For example, editors can deploy to staging while a release manager signs off on production.
+
+## The approval flow
+
+1. A team member starts a deployment as usual.
+2. With approvals on, the deployment is held instead of running.
+3. It appears under **Pending deployments** on the **Deploy approvals** tab, showing the app, who requested it, and where it would deploy (provider, region, and machine size).
+4. An approver selects **Approve** to run it, or **Reject** to stop it.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/deployment-approvals/pending_deployments.webp",
+    alt="A pending deployments list showing an app, the requester, deployment details, and Approve and Reject buttons",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Related
+
+- [Custom roles](/docs/ai/organization/custom-roles/) — grant the Approve deployments permission.
+- [Audit logs](/docs/ai/organization/audit-logs/) — review approvals and other activity.

docs/ai_builder/organization/domains.md

@@ -0,0 +1,79 @@
+---
+tags: Organization
+description: Verify a company email domain so teammates automatically join your Reflex organization.
+---
+
+# Verified Domains & Auto-Join
+
+```python exec
+import reflex as rx
+```
+
+Inviting people one at a time works for small teams. For a whole company, verify your email domain (such as `acme.com`) so anyone with a matching address joins the organization automatically, without an individual invitation.
+
+Verified domains are managed under **Settings → Domains** and are part of the **Enterprise** plan.
+
+## How it works
+
+1. Claim a domain your company owns.
+2. Prove ownership by adding a DNS record.
+3. Once verified, people with an email on that domain join automatically, including both new sign-ups and existing Reflex users.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/domains/domains_list.webp",
+    alt="The Domains tab showing a verified domain with an auto-join toggle and a pending domain awaiting verification",
+    class_name="rounded-md h-auto",
+)
+```
+
+## Claiming and verifying a domain
+
+Select **Add domain** and enter the domain to claim, such as `acme.com`. It appears with a **Pending** status and a set of DNS instructions.
+
+To verify ownership, add the **TXT record** shown (its Type, Name, and Value) with your DNS provider, where you manage your domain. Then return and select **Verify**.
+
+```python eval
+rx.image(
+    src="https://web.reflex-assets.dev/docs-preview/organization/domains/dns_verification.webp",
+    alt="A pending domain card showing the TXT record type, name, and value to add, with a Verify button",
+    class_name="rounded-md h-auto",
+)
+```
+
+```md alert info
+# DNS changes take a little time
+After you add the record, it can take a few minutes to propagate. If verification fails at first, wait and try again.
+```
+
+Only one organization can verify a given domain.
+
+## Auto-join
+
+Once a domain is verified, **auto-join** is on by default:
+
+- **New people** who sign up with an email on the domain join the organization automatically.
+- **Existing Reflex users** with a matching email are added too.
+
+Turn auto-join **off** with the toggle to stop adding new people while keeping the domain verified. Use this to pause onboarding without removing the domain.
+
+### Syncing existing members
+
+If a domain shows **Sync incomplete**, some existing users on it haven't been added yet. Select **Sync members** to add them; it's safe to run at any time.
+
+### When you're out of seats
+
+If auto-join would add someone but the organization has no free [seats](/docs/ai/organization/members/), they go into the **Awaiting a seat** queue and hold no seat until an admin activates them. See [Members & seats](/docs/ai/organization/members/) to activate them.
+
+## Removing a domain
+
+Select the delete icon on a domain's card and confirm. New people on that domain stop joining automatically, but existing members keep their access. You can claim the domain again later.
+
+## Domains and single sign-on
+
+A verified domain is also required for [single sign-on](/docs/ai/organization/sso/). To have your team sign in through your identity provider, verify the domain first, then set up SSO. The Single sign-on card sits on this page, below your domains.
+
+## Related
+
+- [Single sign-on (SSO)](/docs/ai/organization/sso/) — sign in through your identity provider.
+- [Members & seats](/docs/ai/organization/members/) — seats and the awaiting-a-seat queue.